18.1.5 反向代理与HTTPS接入
在生产环境中通常通过反向代理统一入口、实现TLS终止、访问控制与审计。Jenkins原生监听建议仅绑定内网地址，通过Nginx/HAProxy接入HTTPS对外服务，并配置合适的Host头与X-Forwarded-*头，保证Jenkins生成的URL、回调与Webhook可用。
Jenkins侧基础配置要点与命令示例
1) 绑定内网地址与端口
- systemd 环境变量方式（推荐）
sudo mkdir -p /etc/systemd/system/jenkins.service.d
cat <<'EOF' | sudo tee /etc/systemd/system/jenkins.service.d/override.conf
[Service]
Environment="JENKINS_ARGS=--httpListenAddress=127.0.0.1 --httpPort=8080"
EOF
sudo systemctl daemon-reload
sudo systemctl restart jenkins
sudo ss -lntp | grep 8080
# 预期：仅 127.0.0.1:8080 监听
2) 设置外部访问URL（防止回调/重定向错误）
- Web界面：系统管理 → 系统设置 → Jenkins URL = https://jenkins.example.com
- CLI校验（如已启用Jenkins CLI）：
java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -auth admin:token who-am-i
3) 配置ContextPath（使用子路径时）
- 启动参数示例：
# /etc/default/jenkins（Debian/Ubuntu）
JENKINS_ARGS="--prefix=/jenkins --httpListenAddress=127.0.0.1 --httpPort=8080"
- 重启生效后访问路径为
https://jenkins.example.com/jenkins
Nginx反向代理与HTTPS示例
- 安装与证书部署
# 安装
sudo yum -y install nginx # RHEL/CentOS
# 或
sudo apt -y install nginx # Debian/Ubuntu
# 证书路径示例
sudo mkdir -p /etc/nginx/ssl
# 这里假设证书已签发并放置：
# /etc/nginx/ssl/jenkins.crt
# /etc/nginx/ssl/jenkins.key
- 完整可执行配置（含WebSocket支持与HTTPS跳转）
# /etc/nginx/conf.d/jenkins.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name jenkins.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name jenkins.example.com;
ssl_certificate /etc/nginx/ssl/jenkins.crt;
ssl_certificate_key /etc/nginx/ssl/jenkins.key;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Port $server_port;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 300s;
}
}
- 语法检查与上线
sudo nginx -t
sudo systemctl enable --now nginx
HAProxy接入HTTPS示例
- 安装与配置
sudo yum -y install haproxy
# 或
sudo apt -y install haproxy
# /etc/haproxy/haproxy.cfg
global
log /dev/log local0
maxconn 2048
defaults
mode http
timeout connect 5s
timeout client 120s
timeout server 120s
frontend https_in
bind *:443 ssl crt /etc/haproxy/certs/jenkins.pem
http-request set-header X-Forwarded-Proto https
http-request set-header X-Forwarded-Port 443
default_backend jenkins_backend
backend jenkins_backend
server jenkins1 127.0.0.1:8080 check
- 合并证书为PEM
cat /etc/ssl/jenkins.crt /etc/ssl/jenkins.key | sudo tee /etc/haproxy/certs/jenkins.pem
sudo systemctl restart haproxy
常见问题排查（带命令）
1) 页面重定向到HTTP
- 检查 Jenkins URL 与X-Forwarded-Proto：
curl -I https://jenkins.example.com | grep -i location
# 若Location为http，检查Nginx/Haproxy头设置与Jenkins URL
2) 403 / No valid crumb
- 查看是否丢失请求头或改写方法：
# Nginx访问日志中检查是否为POST且带crumb
sudo tail -f /var/log/nginx/access.log
3) 控制台输出断连（WebSocket问题）
- 验证Upgrade头是否透传：
curl -i -N \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
https://jenkins.example.com/
- 调整超时：
proxy_read_timeout 300s;
4) 大文件上传失败
- 调整Nginx：client_max_body_size 100m;
- 可能还需调整Jenkins全局上传限制或反向代理超时。
安全增强建议
- 仅开放代理入口端口，Jenkins端口仅内网可见。
- 启用HSTS、禁用弱加密套件。
- 配合WAF或IP白名单限制管理访问。
- 使用服务账号与最小权限原则进行Webhook调用。
练习
1) 将Jenkins绑定至127.0.0.1:8080并通过Nginx反代访问，验证HTTPS强制跳转。
2) 启用/jenkins子路径访问，验证构建页面中“蓝球”与控制台日志正常。
3) 故意移除X-Forwarded-Proto头，观察回调URL变化并记录现象。
4) 调整client_max_body_size为1m后上传大文件，复现失败并恢复。