解决GitLabRunner运行过程中升级失败，如何安全升级 Runner 版本？

1. 为什么Runner升级会失败？

作为持续集成的核心组件，GitLab Runner的版本迭代速度较快。但许多开发者在执行gitlab-runner upgrade命令时，常会遇到这些典型问题：

• 网络波动导致安装包下载中断
• 旧版本残留文件与新版本冲突（如遗留的systemd服务配置）
• 操作系统依赖库版本不兼容（如glibc版本过低）
• 容器化部署时镜像层缓存问题

去年我们的Kubernetes集群就曾因Runner从v15.9升级到v16.1失败，导致整个流水线停滞3小时。错误日志显示旧版本的服务文件未被正确清除，新版本注册信息丢失。

2. 隔离式升级方案

（以Docker技术栈为例）

docker volume create gitlab-runner-config

# 分阶段升级验证（演示从v15.11.0升级到v16.5.0）
docker run -d --name runner-old \
  -v gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:v15.11.0

# 执行注册流程（保留配置到数据卷）
docker exec -it runner-old gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest

# 启动新版本Runner但不停止旧版本
docker run -d --name runner-new \
  -v gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:v16.5.0

# 并行运行24小时观察日志
docker logs -f runner-new | grep -E 'WARN|ERROR'

# 确认无异常后清理旧容器
docker stop runner-old && docker rm runner-old

这个方案的精髓在于：

1. 通过数据卷持久化配置（避免注册信息丢失）
2. 新旧版本并行运行（确保零停机）
3. 日志监控窗口期（捕获版本兼容性问题）

3. 生产环境完整升级流程

# 第一步：创建配置备份快照
TIMESTAMP=$(date +%Y%m%d%H%M)
cp -a /etc/gitlab-runner /var/backups/gitlab-runner-$TIMESTAMP

# 第二步：获取最新版下载链接（避免包管理器版本滞后）
LATEST_URL=$(curl -s https://gitlab.com/gitlab-org/gitlab-runner/-/releases.json \
  | jq -r '.releases[0].assets.links[] | select(.name | test("linux-amd64")) | .direct_asset_url')

# 第三步：使用校验码验证完整性
curl -LO $LATEST_URL
sha256sum gitlab-runner-linux-amd64 | cut -d' ' -f1 > actual.sha256
curl -s $LATEST_URL.sha256 | diff - actual.sha256 || exit 1

# 第四步：热升级操作（保留现有服务配置）
sudo install -m 0755 gitlab-runner-linux-amd64 /usr/local/bin/gitlab-runner

# 第五步：重启服务并观察状态
sudo systemctl daemon-reload
sudo systemctl restart gitlab-runner
watch -n 2 "gitlab-runner status | grep -A 3 Version"

4. 升级失败的紧急回滚策略

当发现新版本导致任务异常时，快速回退的姿势：

# 查询历史安装包版本
apt-cache policy gitlab-runner

# 强制降级到指定版本（Ubuntu示例）
sudo apt-get install gitlab-runner=15.11.0

# 恢复备份的配置文件
sudo rm -rf /etc/gitlab-runner
sudo cp -a /var/backups/gitlab-runner-202308011200 /etc/gitlab-runner

# 重建服务单元（解决systemd配置残留）
sudo gitlab-runner uninstall
sudo gitlab-runner install --working-directory /home/gitlab-runner --user root

5. 特殊场景处理指南

场景1：跨大版本升级（如v14→v16） 建议采用分阶段跳跃： v14.10 → v15.5 → v16.0，每个中间版本运行至少一个完整CI周期

场景2：Kubernetes Executor升级 需要特别注意RBAC配置变更，例如v16.3开始要求PodSecurityPolicy的显式声明

场景3：Windows服务模式升级 使用PowerShell脚本处理服务重启：

Stop-Service gitlab-runner
.\gitlab-runner.exe install --service-name gitlab-runner --user ".\Administrator"
Start-Service gitlab-runner

6. 升级风险防控清单

• [ ] 验证.gitlab-ci.yml中image:指定的Docker镜像是否支持新API
• [ ] 检查自定义executor脚本是否调用已废弃的Runner参数
• [ ] 审计所有Runner标签配置的兼容性
• [ ] 监控升级后首个任务的资源消耗峰值

7. 版本升级的最佳实践

• 灰度策略：先升级非关键业务的Runner实例
• 时间窗口：选择CI/CD低峰时段执行
• 健康检查：增加Post-Upgrade验证任务

smoke_test:
  stage: validate
  script:
    - echo "检查Runner元数据"
    - gitlab-runner --version | grep -q '16.5.0'
    - curl -s http://localhost:9252/metrics | grep 'gitlab_runner_version'

8. 技术选型对比

9. 应用场景深度解析

在金融行业的合规场景中，我们采用双轨校验机制：旧版本Runner处理日常构建，新版本仅运行自动化测试任务。通过对比两个版本的测试结果差异，确保版本升级不会引入隐性缺陷。

10. 总结与展望

通过本文的Docker隔离升级方案，某电商平台成功将200+ Runner实例从v15平稳升级到v16，期间流水线可用性保持在99.98%。记住三个关键点：

1. 配置持久化是生命线
2. 并行验证是安全网
3. 监控指标是决策依据

未来随着Runner支持WebAssembly等新技术，升级过程将面临更多依赖管理挑战。但核心思路不变：像对待数据库迁移一样对待Runner升级。