Debian 上实现 Jenkins 高可用的推荐架构
- 采用多 Master + 共享存储 + 外部负载均衡的“主动-主动”模式，前端用 HAProxy/Nginx 做 VIP/域名接入与健康检查，后端多台 Jenkins Master 挂载同一份 JENKINS_HOME（如 NFS、CephFS、Longhorn/RWX 卷），实现控制面与任务编排的高可用。构建负载通过 Agent/从节点水平扩展，避免单 Master 成为瓶颈。为降低风险，建议将 Jenkins 升级为 Controller/Agent 架构（现代 Jenkins 的长期方向），但下述方案对现有 Master/Slave 同样适用。
实施步骤
-
准备共享存储与目录
- 部署 NFS/CephFS/Longhorn 等共享卷，导出目录如 /srv/jenkins。
- 在每台 Master 上挂载到 /var/lib/jenkins（或自定义 $JENKINS_HOME），权限与属主保持一致（如 jenkins:jenkins）。
- 首次初始化建议只在一台 Master 上完成（解锁、插件安装、系统配置），完成后确保其他 Master 以只读方式挂载或等待首次启动完成后再切换为读写，避免 credentials.xml、jobs/ 等元数据并发写冲突。
-
安装与初始化 Jenkins（每台 Master）
- 安装 OpenJDK 11 与 Jenkins（Debian 稳定源）：
sudo apt update && sudo apt install -y openjdk-11-jdk jenkins
- 首次管理员密码路径：/var/lib/jenkins/secrets/initialAdminPassword。
- 建议将 JENKINS_HOME 明确配置到共享目录（如 /etc/default/jenkins 或 systemd 环境变量），并确保目录权限正确。
-
配置外部负载均衡与健康检查
- 安装 HAProxy（或 Nginx）：sudo apt install -y haproxy
- HAProxy 示例（/etc/haproxy/haproxy.cfg）：
frontend jenkins_http
bind *:8080
mode http
default_backend jenkins_back
backend jenkins_back
balance roundrobin
option httpchk GET /login
server master1 10.0.0.11:8080 check inter 5s fall 3 rise 2
server master2 10.0.0.12:8080 check inter 5s fall 3 rise 2
- 如使用 JNLP 固定端口（便于 Agent 连接），在“全局安全配置”开启 TCP 端口 for JNLP agents（默认 50000），并在 HAProxy 增加对应端口转发与健康检查。
-
扩展构建能力（Agent/从节点）
- 在 Manage Jenkins → Manage Nodes and Clouds → New Node 添加 Agent。
- 推荐通过 SSH 启动 Agent（在从节点安装 Java，Master 配置 SSH 凭据），或使用 Launch agent via Java Web Start/JNLP 方式。
- 为不同平台/用途打标签（如 linux、docker、gpu），在 Job 中通过 Label 约束运行节点，实现弹性伸缩与资源隔离。
-
验证与演练
- 访问 VIP:8080 登录，确认系统配置、插件、凭据在各 Master 上一致。
- 触发构建，确认任务在 Agent 上执行且日志、工作空间一致。
- 进行 滚动升级/故障切换演练：逐台重启 Master、断开某台网络、停止 HAProxy 后端，验证服务不中断与自动恢复。
关键配置与最佳实践
-
避免脑裂与元数据损坏
- 严格控制 $JENKINS_HOME 的并发写：首台初始化后，其他 Master 启动时可短暂以只读方式挂载，待初始化完成后再切换读写；或采用外部一致性机制（如 etcd/operator）管理领导选举与配置下发。
- 将 Jenkins 升级为 Controller/Agent 架构后，官方提供更为成熟的 HA/多租能力，可逐步迁移。
-
存储与权限
- 共享存储需保证 低时延与高可用（SSD/NVMe、多副本/纠删码），并定期备份 $JENKINS_HOME（含 jobs/、credentials.xml、plugins/、config.xml）。
- 统一 UID/GID（如 1000:1000） 与目录权限，避免因权限不一致导致插件/构建失败。
-
网络与安全
- 仅暴露 8080/443 与 JNLP 50000 到内网，启用 TLS/HTTPS 与强认证；限制 executors 数量与 Agent 标签范围，避免资源争用。
- 为 HAProxy 配置合适的 健康检查路径（如 /login），并开启 会话保持（如有表单登录依赖），减少用户会话中断。
-
监控与容量
- 监控 JVM 堆/GC、HTTP 5xx、构建队列长度、磁盘 IO、Agent 在线率；为 Jenkins Master 配置合适的 JVM 堆大小（如 -Xms/-Xmx），并限制并发构建数。
- 构建密集型场景优先扩容 Agent 与共享存储 IOPS，而非盲目增加 Master 数量。
常见陷阱与排查要点
- 元数据并发写导致 XML 冲突/损坏：确保共享 $JENKINS_HOME 的写入序列化，首台初始化完成后再让其他 Master 加入。
- JNLP 端口未开放导致 Agent 离线：在“全局安全配置”开启 JNLP TCP 端口，并在 HAProxy/Nginx 放行对应端口与健康检查。
- 权限/用户不一致导致插件安装或构建失败：统一 jenkins:jenkins 的 UID/GID 与目录权限。
- 时间漂移引发任务调度异常：所有节点启用 NTP 同步。
- 负载均衡会话粘滞问题：如依赖表单登录，启用 源地址/会话保持 或改用 API Token 执行器。