GitLab Server升级后老版本Runner出现各类错误，本质是版本断层导致通信协议、API接口或TLS验证不兼容；必须按官方兼容矩阵（如GitLab 15.x需Runner≥14.10.0）升级或降级Runner，并同步更新证书、干净注册。
GitLab Server 升级后，老版本 Runner 出现“无法注册”“连接拒绝”“This job does not have a trace”或 x509 certificate signed by unknown authority 等错误，本质是通信协议、API 接口或 TLS 验证机制发生了不兼容变更。这不是配置问题，而是版本断层导致的硬性阻断。紧急对齐的核心逻辑是：**Runner 版本必须满足 GitLab Server 的最低兼容要求，且不能高于其支持上限**。
确认当前 GitLab Server 版本与 Runner 兼容边界
登录 GitLab 服务器终端，执行：
sudo gitlab-rake gitlab:env:info | grep "GitLab version"
例如输出 GitLab version: 15.11.10，则需查阅官方兼容矩阵（截至 2026 年 5 月）：
- GitLab 15.x 要求 Runner ≥ 14.10.0（最低支持）
- GitLab 15.6+ 已弃用旧注册令牌（
registration_token），必须使用 Runner 15.0+ 才能完成新注册流程 - GitLab 16.x 完全不兼容 Runner
若当前 Runner 版本低于该下限（如 Server 是 15.11.10，Runner 却是 13.12.0），必须升级 Runner；若高于上限（极少见），也需降级至推荐版本。
快速安装匹配的 Runner 版本（RPM/DEB 系统通用）
不要依赖系统默认源或 apt upgrade —— 它往往只提供旧稳定版。应直接从 GitLab 官方仓库拉取指定版本：
-
RHEL/CentOS/AlmaLinux（RPM）：
yum list gitlab-runner --showduplicates | sort -r<br>sudo yum install -y gitlab-runner-15.11.0
-
Ubuntu/Debian（DEB）：
apt-cache madison gitlab-runner<br>sudo apt-get install -y gitlab-runner=15.11.0~ubuntu.22.04.1
注意：版本号后缀（如 ~ubuntu.22.04.1）需与你的系统发行版严格匹配，可在 packages.gitlab.com/runner/gitlab-runner 页面手动查找对应包名。
同步更新证书与重启服务
GitLab Server 升级常伴随 Nginx 证书轮换，而 Runner 默认信任系统 CA 证书库。若证书已更新但 Runner 所在机器未同步，会报 x509 错误：
- 将新证书（通常位于
/var/opt/gitlab/nginx/etc/ssl/或/etc/gitlab/ssl/）复制到 Runner 服务器的系统证书目录：sudo cp /path/to/new/gitlab.crt /etc/pki/tls/certs/
- 更新证书哈希索引：
sudo update-ca-trust
- 重启服务确保加载新证书和新版二进制：
sudo gitlab-runner stop<br>sudo gitlab-runner start
重新注册 Runner（关键步骤）
仅升级二进制不够，旧注册信息可能含已失效字段（如过期 token、不兼容 executor 配置）。请执行干净注册：
- 先注销旧 Runner：
sudo gitlab-runner unregister --name "My Runner"
- 获取新注册 Token：在 GitLab Web 界面 → Admin Area → Overview → Runners → “New project runner” 或 “New group runner”，复制 Registration token（非旧的
token字段） - 执行注册命令（以项目级为例）：
sudo gitlab-runner register \<br> --non-interactive \<br> --url "https://gitlab.example.com/" \<br> --registration-token "your-new-token" \<br> --executor "docker" \<br> --docker-image "alpine:latest" \<br> --description "prod-runner-15.11" \<br> --tag-list "linux,docker"
注册成功后，检查状态：sudo gitlab-runner status 和 sudo gitlab-runner list，再触发一个简单流水线验证日志是否正常回传。
