如何在GitLab Docker容器中使用本地Docker并配置GitLab Runner？

核心结论：无需符号链接，直接挂载Docker资源 #

你不需要给容器和本地Docker可执行文件建立符号链接——这种方案既绕弯路，还容易触发权限或版本兼容问题。正确的做法是通过挂载本地Docker socket和Docker客户端，让Runner容器直接复用本地的Docker环境。

正确配置步骤（挂载本地Docker到Runner容器） #

1. 启动GitLab Runner容器并挂载必要资源 #

执行以下命令启动Runner容器，挂载三个关键路径：

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /usr/bin/docker:/usr/bin/docker \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

• /var/run/docker.sock：本地Docker daemon的通信套接字，挂载后Runner可直接调用本地Docker服务
• /usr/bin/docker：本地Docker客户端二进制文件，让Runner容器内能执行docker命令
• /srv/gitlab-runner/config：持久化Runner的配置文件，避免容器重启后配置丢失

2. 注册Runner到GitLab实例 #

进入容器执行注册命令：

docker exec -it gitlab-runner gitlab-runner register

按照引导依次输入：

• GitLab实例的URL（比如http://your-gitlab-ip:port）
• 项目或实例级别的注册令牌（在GitLab的Runner设置页面获取）
• Runner的描述、标签（可选）
• 执行器选择docker，并指定默认镜像（比如alpine:latest）

3. 验证配置是否生效 #

进入容器测试能否访问本地Docker：

docker exec gitlab-runner docker ps

如果能列出本地的Docker容器，说明配置成功。也可以提交一个简单的CI job（比如.gitlab-ci.yml里写一个docker info的步骤）验证流水线能否正常调用Docker。

挂载方案遇到问题时的替代方案 #

场景1：挂载后出现权限错误 #

如果容器内执行docker命令提示权限不足，可尝试：

• 临时调整本地Docker socket权限（注意安全风险，仅测试环境用）：

  sudo chmod 666 /var/run/docker.sock
  

• 更安全的方式：将容器内的gitlab-runner用户添加到本地的docker组：

  # 获取本地docker组ID
  getent group docker
  # 修改容器内用户的组ID，和本地docker组匹配
  docker exec gitlab-runner usermod -g <本地docker组ID> gitlab-runner
  # 重启容器
  docker restart gitlab-runner
  

场景2：版本兼容或隔离性需求 #

如果本地Docker版本和Runner容器内的依赖不兼容，或者需要完全隔离的构建环境，可以使用**Docker-in-Docker（DinD）**模式：

1. 启动特权模式的Runner容器：

   docker run -d --name gitlab-runner-dind --restart always \
     --privileged \
     -v /srv/gitlab-runner/config:/etc/gitlab-runner \
     gitlab/gitlab-runner:latest
   

2. 注册Runner时，执行器选docker，并在Runner的配置文件（/srv/gitlab-runner/config/config.toml）中添加：

   [[runners]]
     # 其他配置...
     executor = "docker"
     [runners.docker]
       image = "docker:latest"
       privileged = true
       volumes = ["/cache"]
       pull_policy = "if-not-present"
   

这种模式下，Runner会启动一个独立的Docker daemon，完全和本地环境隔离，但资源消耗会更高。

场景3：彻底规避容器化Runner的麻烦 #

直接在本地机器安装GitLab Runner（非容器化版本），这样Runner会直接调用本地的Docker环境，无需任何挂载配置：

• Linux系统：通过包管理器（apt/yum）安装官方包
• Windows/macOS：下载官方二进制文件，配置为系统服务后注册Runner

内容的提问来源于stack exchange，提问作者Parsa Noori