GitLab + GitLab Runner 本地 Docker 部署实战文档

下面给你整理一套 完整的，包含：

✅ 安装部署流程
✅ Runner 注册流程
✅ Docker 网络配置
✅ 常见错误汇总
✅ 每个问题的根本原因 + 解决方案
✅ 最终稳定架构

一、整体架构说明

本地 Docker Desktop 环境结构：

复制代码

Docker Desktop
│
├── gitlab (容器)
│    端口映射：
│    8929 → 80
│    2222 → 22
│
├── gitlab-runner (容器)
│
└── node:22 (CI Job临时容器)

⚠ 重点：

CI 任务执行时，Runner 会动态创建新的 Docker 容器（比如 node:22），

这些容器必须和 GitLab 在同一个 Docker 网络中。

否则会出现：

复制代码

fatal: Could not resolve host: gitlab

二、GitLab Docker 安装

1️⃣ 创建自定义网络

powershell 复制代码

docker network create gitlab-net

2️⃣ 启动 GitLab

powershell 复制代码

docker run -d ^
  --name gitlab ^
  --network gitlab-net ^
  -p 8929:80 ^
  -p 2222:22 ^
  -v gitlab-config:/etc/gitlab ^
  -v gitlab-logs:/var/log/gitlab ^
  -v gitlab-data:/var/opt/gitlab ^
  gitlab/gitlab-ce:latest

3️⃣ 配置 external_url

进入容器：

bash 复制代码

docker exec -it gitlab bash

编辑：

bash 复制代码

vi /etc/gitlab/gitlab.rb

设置：

ruby 复制代码

external_url 'http://localhost:8929'

然后执行：

bash 复制代码

gitlab-ctl reconfigure
gitlab-ctl restart

4️⃣ 访问 GitLab

浏览器访问：

复制代码

http://localhost:8929

三、获取 GitLab 初始密码

bash 复制代码

docker exec -it gitlab bash
cat /etc/gitlab/initial_root_password

用户名：

复制代码

root

四、安装 GitLab Runner

powershell 复制代码

docker run -d ^
  --name gitlab-runner ^
  --network gitlab-net ^
  -v gitlab-runner-config:/etc/gitlab-runner ^
  gitlab/gitlab-runner:latest

五、注册 Runner（正确方式）

进入 runner：

bash 复制代码

docker exec -it gitlab-runner bash

bash 复制代码

gitlab-runner register

输入：

复制代码

GitLab instance URL:
http://gitlab

⚠ 注意：

必须写：

复制代码

http://gitlab

不能写：

复制代码

http://localhost:8929

因为 Runner 在容器内，localhost 不是宿主机。

注册时选择：

复制代码

executor: docker
default image: node:22

六、最关键一步（你踩坑的核心）

编辑：

bash 复制代码

vi /etc/gitlab-runner/config.toml

找到：

toml 复制代码

[runners.docker]
  image = "node:22"

增加：

toml 复制代码

network_mode = "gitlab-net"

最终：

toml 复制代码

[runners.docker]
  image = "node:22"
  privileged = false
  network_mode = "gitlab-net"

重启 runner：

powershell 复制代码

docker restart gitlab-runner

七、为什么必须设置 network_mode

因为：

复制代码

gitlab-runner 在 gitlab-net
gitlab 在 gitlab-net
node:22 默认不在 gitlab-net

导致：

复制代码

fatal: Could not resolve host: gitlab

加上：

复制代码

network_mode = "gitlab-net"

后结构变为：

复制代码

gitlab-net
 ├── gitlab
 ├── gitlab-runner
 ├── node:22

问题解决。

八、CI 指定 Runner Tag

推荐目录结构：

复制代码

/var/www/admin/
 ├── releases/
 │    ├── 20250618123000
 │    ├── 20250618150000
 └── current -> releases/20250618150000

CI 发布脚本：

.gitlab-ci.yml

yaml 复制代码

deploy-job:
  stage: deploy
  tags:
    - node22
  script:
    - VERSION=$(date +%Y%m%d%H%M%S)
    - mkdir -p releases/$VERSION
    - cp -r dist/* releases/$VERSION/
    - ln -sfn releases/$VERSION current

回滚命令

查看版本：

bash 复制代码

ls releases

回滚：

bash 复制代码

ln -sfn releases/20250618123000 current

秒级回滚，无需重新部署。

九、常见错误汇总 + 解决方案

❌ 1. Could not resolve host: 866c1762bbfd

原因：

external_url 没设置正确。

解决：

ruby 复制代码

external_url 'http://localhost:8929'
gitlab-ctl reconfigure

❌ 2. Failed to connect to localhost port 80

原因：

external_url 设成了 http://localhost

GitLab 默认走 80 端口。

解决：

必须带端口：

ruby 复制代码

external_url 'http://localhost:8929'

❌ 3. Could not resolve host: gitlab

原因：

node job 容器不在 gitlab-net 网络。

解决：

在 config.toml 加：

toml 复制代码

network_mode = "gitlab-net"

❌ 4. Cannot connect to Docker daemon

原因：

Docker Desktop 没启动。

解决：

启动 Docker Desktop。

❌ 5. 无可用 Runner

原因：

Runner 未注册或 Tag 不匹配。

解决：

检查 Runner 状态
检查 .gitlab-ci.yml 的 tags

❌ 6. 403 Forbidden unregister

原因：

使用了过期 token。

解决：

直接删除 config.toml 重新注册。

十、最终推荐稳定结构（生产思路）

推荐使用 docker-compose：

yaml 复制代码

version: '3'
services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    networks:
      - gitlab-net
    ports:
      - "8929:80"
      - "2222:22"

  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    networks:
      - gitlab-net
    volumes:
      - ./runner-config:/etc/gitlab-runner

networks:
  gitlab-net:
    driver: bridge

十一、完整流程总结

创建 gitlab-net
启动 GitLab
设置 external_url
启动 Runner
注册 Runner
修改 config.toml 加 network_mode
重启 Runner
推送代码触发 CI

十二、你现在掌握的能力

你已经学会：

Docker 网络原理
GitLab external_url 机制
Runner 注册机制
CI Docker executor 工作原理
Docker 容器 DNS 解析原理
GitLab 内部 clone 机制

这已经是 DevOps 入门到中级水平了 🔥