Apple Silicon M1部署Docker版GitLab Runner无法启动问题求助

红色感叹号报错排查步骤 #

• 验证镜像架构匹配度：执行 docker inspect gitlab/gitlab-runner:latest | grep Architecture 确认镜像为arm64架构，M1设备运行x86架构镜像会触发QEMU模拟层异常，导致文件访问不稳定
• 检查配置文件权限：执行 ls -l /Users/Shared/gitlab-runner/config/config.toml 确认文件权限允许容器内用户读取，官方GitLab Runner镜像默认运行用户UID为998，可执行 sudo chown -R 998:998 /Users/Shared/gitlab-runner/config 修复权限
• 验证网络连通性：进入容器执行 curl http://latitude:8083/ 确认可以正常访问GitLab实例，若域名解析失败可在容器启动命令中添加--add-host latitude:<GitLab服务IP>参数
• 检查Docker套接字访问权限：执行 docker exec gitlab-runner docker ps 确认容器可以正常调用宿主机Docker，若报错可执行 sudo chmod 666 /var/run/docker.sock 临时放开权限测试
• 验证配置文件格式：执行 cat /Users/Shared/gitlab-runner/config/config.toml 检查配置是否存在语法错误，可通过官方配置校验工具验证格式合法性

Runner无法启动的核心原因 #

1. 架构不兼容：你使用的gitlab/gitlab-runner:latest默认拉取x86架构镜像，在M1设备上通过QEMU模拟运行时会出现偶发的文件访问失败，对应日志中时而加载配置成功、时而找不到配置文件的异常表现
2. 权限不足：宿主机挂载的config目录权限不允许容器内的gitlab-runner用户读取，或者docker.sock权限不足导致executor无法正常调用Docker
3. 网络不通：容器内无法解析latitude域名，无法和GitLab服务端完成心跳通信
4. 注册参数异常：注册时填写的URL、token等参数错误，导致Runner无法被服务端识别

修复方案 #

首先替换为arm64版本的Runner镜像，修改启动命令：

docker stop gitlab-runner && docker rm gitlab-runner

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /Users/Shared/gitlab-runner/config:/etc/gitlab-runner \
  --add-host latitude:<替换为你的GitLab服务实际IP> \
  gitlab/gitlab-runner:latest-arm64v8

然后用同版本镜像重新注册Runner：

docker run --rm -v /Users/Shared/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner:latest-arm64v8 register \
  --non-interactive \
  --executor "docker" \
  --docker-image hannesa2/android-ndk:api28_emu \
  --url "http://latitude:8083/" \
  --registration-token "<替换为你的实际注册token>" \
  --description "M1 pro Android NDK + Emu" \
  --tag-list "android,android-ndk,android-emu" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

修复完成后重启容器，再查看日志确认无配置加载错误即可。

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