Jenkins 备份恢复、升级与故障排查
验证：未记录
- 适用版本
- 未记录
- 验证范围
- 尚未登记验证记录。
RPO（Recovery Point Objective，可容忍数据丢失窗口）由备份频率决定；RTO（Recovery Time Objective，恢复耗时目标）须通过演练测量。先能恢复，再升级。
1. 一致性备份#
针对 Compose 部署。安装 age 加密工具，准备备份接收方公钥 BACKUP_RECIPIENT 与独立保管的 KEY_RECIPIENT；私钥不放 Controller。
- Manage Jenkins → Prepare for Shutdown，停止接收新构建，等待在途任务完成；审批中的任务也要明确结束或记录恢复方式。
- 暂停 Webhook／定时触发入口，记录镜像 digest、核心／Java／插件版本和配置提交。
- 停止后备份 Home，避免运行中打包产生不一致快照：
set -euo pipefail
: "${JENKINS_HOME_DIR:?}" "${BACKUP_RECIPIENT:?}" "${KEY_RECIPIENT:?}"
export BACKUP_DIR="$(pwd)/backup-$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -m 700 "$BACKUP_DIR"
docker compose stop controller
sudo tar --exclude='./secrets/master.key' -C "$JENKINS_HOME_DIR" -czf - . | age -r "$BACKUP_RECIPIENT" > "$BACKUP_DIR/home.tar.gz.age"
sudo cat "$JENKINS_HOME_DIR/secrets/master.key" | age -r "$KEY_RECIPIENT" > "$BACKUP_DIR/master.key.age"
(cd "$BACKUP_DIR" && sha256sum *.age > SHA256SUMS)
docker compose start controller- Home 密文和校验单送到受控备份仓库；master.key 密文送到独立权限的密钥备份位置。确认都可恢复后清理本地暂存。
- 恢复触发入口、退出维护状态，运行测试任务。
Home 含凭据密文和其他秘密，应整体加密。master.key 与 secrets/hudson.util.Secret 都关系到凭据解密，隔离保管不等于漏备份。官方要求
2. 隔离恢复演练#
新建私有虚拟机，默认阻断生产 Agent、Webhook、外网和云元数据，撤掉生产实例角色。克隆任务可能恢复执行，必须先隔离网络和身份再启动。
set -euo pipefail
: "${RESTORE_HOME:?new empty directory}" "${BACKUP_IDENTITY:?}" "${KEY_IDENTITY:?}"
# 从两个受控备份位置下载密文和可信校验单到当前目录。
sha256sum -c SHA256SUMS
sudo install -d -m 700 -o 1000 -g 1000 "$RESTORE_HOME"
[ -z "$(sudo ls -A "$RESTORE_HOME")" ] || { echo 'Restore directory must be empty'; exit 1; }
age -d -i "$BACKUP_IDENTITY" home.tar.gz.age | sudo tar -xzf - -C "$RESTORE_HOME"
age -d -i "$KEY_IDENTITY" master.key.age | sudo tee "$RESTORE_HOME/secrets/master.key" >/dev/null
sudo chown -R 1000:1000 "$RESTORE_HOME"
sudo chmod 600 "$RESTORE_HOME/secrets/master.key"
export JENKINS_HOME_DIR="$RESTORE_HOME"
# 使用备份对应的镜像、配置、测试 URL 与受控秘密挂载。
docker compose up -d controller确认任务／历史和登录正常，用专用测试凭据验证解密及 Agent 连接，不调用生产凭据。按备份时间与恢复耗时测量 RPO／RTO。校验和随可信仓库元数据保存，其本身不提供防篡改认证。
3. 核心与插件升级#
- 阅读目标及跨越版本的 LTS 升级指南、Java 要求与插件安全公告。
- 在隔离恢复副本验证核心、Java、插件组合；老旧实例按官方迁移说明分阶段升级，不假设任何跨度均可直升。
- 测试 Git、Agent、共享库、审批、锁、报告、凭据及恢复。
- 维护窗口停止接收任务 → 停止 → 完整备份 → 更新固定镜像／配置 → 启动验收。
- 失败恢复升级前 Home + 镜像 + 配置。新版可能迁移磁盘数据，不能仅切回旧镜像。
插件小版本也要验证兼容性；禁止生产直接全部升级。Home 中实际插件版本须与发布记录对照。
4. 故障定位#
| 现象 | 先检查 | 处理要点 |
|---|---|---|
| 持续排队 | 标签、节点在线、执行器、锁、配额 | 不增加 Controller 执行器救急 |
| Agent 掉线 | WebSocket、代理超时、DNS、证书、资源 | 区分基础设施故障与应用失败再重试 |
| 磁盘满 | 历史、workspace、镜像缓存、日志 | 配置留存，不直接删配置和凭据 |
| 内存不足 | JVM 堆、线程、GC、容器 OOM | 留堆外内存，限制并发 |
| 无法启动 | 插件依赖、Java、JCasC、文件权限 | 查日志，恢复已验证组合 |
| 凭据失效 | 角色信任、时间同步、授权、过期 | 不打印 token 或完整环境变量 |
JVM 为 Java Virtual Machine，GC 为 Garbage Collection，OOM 为 Out Of Memory。监控队列等待、离线 Agent、磁盘、堆、失败率、备份年龄和恢复演练，阈值根据实际基线设置。