Apple M1设备部署的GitLab Runner无法启动问题排查求助

问题排查方法 #

你遇到的红色感叹号对应日志里的Runner is not healthy报错，按照以下优先级排查即可：

• 验证连通性：先进入Runner容器测试GitLab地址是否可访问，执行命令docker exec -it gitlab-runner curl http://latitude:8083/，如果返回超时/解析失败，说明Runner容器无法访问你填写的GitLab实例地址，属于网络问题。
• 校验注册信息：登录你的GitLab后台，进入对应项目的「设置」→「CI/CD」→「Runner」页面，确认是否存在ID为Jc2yrs_v的Runner：
  • 不存在说明注册token无效，注册时没有成功在GitLab侧创建Runner记录
  • 存在的话检查是否被手动锁定、是否被分配到对应项目、权限配置是否匹配
• 核对版本兼容性：你使用的Runner版本为14.4.0，需确认和你的GitLab实例大版本匹配，两者版本差超过2个小版本会出现鉴权失败的问题。
• 检查架构适配：你的M1设备是arm64架构，后续排查完鉴权问题后，要确认指定的执行镜像hannesa2/android-ndk:api28_emu是否支持arm64架构，否则会出现镜像拉取/运行失败的问题。

Runner无法正常启动的原因 #

从日志里的ERROR: Checking for jobs... forbidden报错可以判断，当前故障的核心是Runner向GitLab请求任务时被鉴权拒绝，常见诱因包括：

• 注册时填写的GitLab地址无法被Runner容器访问，比如latitude域名无法在容器内解析、8083端口被防火墙拦截
• 注册使用的token无效，或者注册完成后GitLab侧删除/禁用了该Runner
• 你给Runner配置的access-level="not_protected"，但对应项目的CI/CD设置要求必须使用受保护的Runner才能执行任务
• 注册用的地址和GitLab实例配置的外部地址不一致，导致回调校验失败

修复方案 #

1. 优先解决网络问题：如果容器内无法解析latitude域名，重新创建Runner时添加--add-host latitude:你的GitLab主机IP参数绑定hosts，或者注册时直接用GitLab实例的IP地址代替域名
2. 重新注册Runner：先在GitLab后台删除当前异常的Runner记录，重新获取正确的注册token，再执行注册流程
3. 对齐版本：如果GitLab实例版本和Runner版本差过大，更换Runner镜像的标签，保持和GitLab版本一致
4. 架构适配：如果后续执行镜像启动失败，注册时添加--docker-platform linux/amd64参数，强制用Rosetta转译运行amd64架构的镜像

内容的提问来源于stack exchange，提问作者hannes ach