排查 Jenkins 反向代理问题-未完纪

Table of Contents

症状
背景
上下文路径
进一步诊断

症状

“管理 Jenkins”页面中显示以下错误消息：

你的反向代理配置似乎存在问题（It appears that your reverse proxy setup is broken）。

即使没有通过反向代理访问 Jenkins，也可能出现这条消息。请确认系统配置中设置的 Jenkins URL 与实际访问 Jenkins 时使用的 URL 一致。

背景

反向代理要正常工作，需要正确处理请求重写和响应重写。请求重写是接收传入的 HTTP 调用，再向 Jenkins 转发请求，过程中可能修改部分 HTTP 请求头，也可能不修改。如果请求重写配置错误，很容易发现，因为根本无法看到任何页面。

但要正确进行反向代理，还必须满足下面两种方式之一：

重写响应中的 Location 请求重定向地址。Jenkins 可能返回 Location: http://actual.server:8080/jenkins/foobar，而反向代理必须将其改写为 Location: http://nice.name/jenkins/foobar。遗憾的是，这部分配置错误更难发现。另一种方式是：
在转发的请求中设置 X-Forwarded-Host，并在需要时设置 X-Forwarded-Port。Jenkins 会解析这些请求头，并据此生成重定向及其他链接。根据反向代理的实现，可以分别从原始 Host 请求头中提取主机名和端口；也可以将原始 Host 原样放入 X-Forwarded-Host，并从请求中移除 X-Forwarded-Port。如果反向代理还在 HTTPS 与 HTTP 之间转换协议，则必须设置 X-Forwarded-Proto。

Jenkins 会主动检查这些配置是否正确。它通过 XmlHttpRequest 请求 Jenkins 中的特定相对 URL；只要请求重写正确，请求就能够到达。该地址随后重定向到 Jenkins 的另一个页面，最终返回 200。这一步只有在响应重写配置正确时才会成功。

出现该错误消息，说明这项检查失败。最可能的原因是响应重写配置不正确。更多配置提示见反向代理配置示例。

如果用户通过 HTTPS 访问反向代理，而代理通过 HTTP 访问 Jenkins，也就是 HTTPS 转 HTTP，务必设置 X-Forwarded-Proto。

上下文路径

上下文路径是 URL 路径的前缀。Jenkins 控制器与反向代理必须使用相同的上下文路径。例如，若控制器 URL 为 https://www.example.com/jenkins/，则启动控制器的命令行参数中必须包含 –prefix=/jenkins。

使用 Linux 软件包时，可以运行 systemctl edit jenkins，并添加以下内容设置上下文路径：

[Service]
Environment="JENKINS_PREFIX=/jenkins"

在 Windows 控制器上，应在安装目录的 jenkins.xml 文件中添加 –prefix 命令行参数。

确保 Jenkins 实际运行的上下文路径与反向代理对外提供服务的路径一致，遵循这一原则可以减少问题。

如果上下文路径为空，则不需要 –prefix。例如，https://jenkins.example.com/ 的上下文路径为空。

通过反向代理改变 Jenkins 的上下文路径存在较大风险，因为需要重写许多 URL。即使已重写 HTML 文件中的全部 URL，也可能遗漏 JavaScript、CSS 或 XML 资源中的地址。

从技术上说，可以通过重写规则改变上下文路径，但找齐并修正所有规则需要大量工作，反向代理也会花费大量时间重写 Jenkins 响应。更简单的办法，是让 Jenkins 直接运行在反向代理预期的上下文路径。例如，反向代理将 https://manchu.example.org/foobar/ 的请求转发给 Jenkins 时，可以使用 java -jar jenkins.war –prefix=/foobar 启动 Jenkins。

进一步诊断

若要进一步诊断，可以尝试使用 cURL：

BASE=administrativeMonitor/hudson.diagnosis.ReverseProxySetupMonitor
curl -iL -e http://your.reverse.proxy/jenkins/manage \
            http://your.reverse.proxy/jenkins/${BASE}/test

以下示例假定 Jenkins 位于 http://your.reverse.proxy/jenkins/，并且允许匿名读取。

原文：Reverse proxy – Issues。作者／来源：Jenkins 文档贡献者。本文依据所列原文整理为中文，代码、命令与配置示例保留原文。

文章版权归作者所有，未经允许请勿转载。

THE END