如何通过Docker让gitlab-runner连接私有网络内的自托管GitLab

我刚好有过类似的私有网络Docker GitLab+Runner部署经验，给你一步步梳理下怎么实现，确保runner能顺利连接你的自托管GitLab：

1. 准备GitLab Runner的Docker运行环境 #

首先，我们用Docker来部署runner，这样和你的GitLab环境更统一。创建一个简单的docker-compose.yml文件：

version: '3'
services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: always
    volumes:
      - ./gitlab-runner-config:/etc/gitlab-runner  # 持久化runner配置
      - /var/run/docker.sock:/var/run/docker.sock  # 让runner能调用宿主机Docker执行任务
    networks:
      - gitlab-network  # 如果你的GitLab容器是用这个网络启动的，直接复用；没有的话可以删掉这几行，默认桥接网络只要能通就行

networks:
  gitlab-network:
    external: true  # 假设你的GitLab已经创建了这个外部网络，否则去掉这行让它自动创建

保存后，用docker-compose up -d启动runner容器。

2. 获取GitLab的Runner注册令牌 #

登录你的GitLab网页（172.16.X.Y:10080），分两种情况获取令牌：

• 全局runner：点击右上角的管理员图标（扳手样式）→ 进入Admin Area→ 选择左侧菜单的Runners，复制页面上的Registration token
• 项目专属runner：进入目标项目→ 点击Settings→CI/CD→ 展开Runners部分，复制项目对应的Registration token

3. 注册Runner到你的自托管GitLab #

注册是关键步骤，我们可以直接在runner容器里执行注册命令：

# 先进入runner容器
docker exec -it gitlab-runner bash

# 执行注册命令，替换成你的实际参数
gitlab-runner register \
  --non-interactive \
  --url "http://172.16.X.Y:10080/" \
  --registration-token "你刚才复制的令牌" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "私有网络Docker Runner" \
  --tag-list "private,docker,internal" \
  --run-untagged="true" \
  --locked="false"

参数说明： #

• --url：这里用http是因为你的GitLab网页是通过10080端口的HTTP访问的，如果你的GitLab配置了HTTPS，就改成https://172.16.X.Y:对应HTTPS端口
• --executor "docker"：指定用Docker作为任务执行器，这是最常用的方式，能隔离不同CI任务的环境
• --tag-list：给runner打标签，方便后续CI任务指定特定runner执行
• --run-untagged="true"：允许这个runner执行没有指定标签的CI任务
• --locked="false"：如果是全局runner，设为false可以让所有项目使用；如果是项目专属runner，建议设为true锁定给当前项目

你也可以用一次性的docker run命令完成注册，不用进入容器：

docker run --rm -v $(pwd)/gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "http://172.16.X.Y:10080/" \
  --registration-token "你的注册令牌" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "私有网络Docker Runner" \
  --tag-list "private,docker" \
  --run-untagged="true" \
  --locked="false"

4. 验证Runner连接状态 #

回到GitLab的Runner页面，你应该能看到刚才注册的runner显示为Active状态。为了确保没问题，你可以创建一个测试项目，添加一个.gitlab-ci.yml文件：

test-runner-connection:
  script:
    - echo "✅ 私有网络GitLab Runner连接成功！"
    - ping -c 2 172.16.X.Y  # 验证runner能访问GitLab服务器

提交代码后，查看CI流水线的执行状态，如果成功运行，就说明runner已经正常工作了。

几个关键注意事项 #

• 网络互通：确保runner容器能ping通172.16.X.Y，如果是自定义网络，一定要让GitLab和runner在同一个网络里；如果是桥接网络，检查宿主机的防火墙/安全组有没有阻挡10080端口
• HTTPS证书问题：如果你的GitLab配置了自签名HTTPS证书，需要把证书文件挂载到runner容器里，注册时加上--tls-ca-file /etc/gitlab-runner/your-ca.crt参数，避免证书验证失败
• Docker权限：挂载/var/run/docker.sock后，要确保runner容器内的用户有操作Docker的权限，否则CI任务可能无法启动子容器

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