Docker 部署 GitLab 和 GitLab Runner 指南

GitLab 和 GitLab Runner Docker 部署指南

说明： 本文中所有 IP 地址（如 192.168.1.100）均为示例地址，实际部署时请替换为您自己的服务器 IP 地址或域名。

前言

本文将详细介绍如何使用 Docker 部署 GitLab CE（社区版）和 GitLab Runner，包括配置说明和常见问题处理。适合希望快速搭建 Git 私有仓库和 CI/CD 环境的开发者。

一、拉取 GitLab 镜像

1.1 拉取镜像

sh 复制代码

# 拉取最新版本
docker pull gitlab/gitlab-ce:latest

# 拉取指定版本（推荐使用稳定版本）
docker pull gitlab/gitlab-ce:17.9.8-ce.0

参数说明：

gitlab/gitlab-ce:latest：拉取 GitLab 社区版的最新镜像
gitlab/gitlab-ce:17.9.8-ce.0：拉取指定版本，生产环境建议使用固定版本号以保证稳定性

1.2 启动容器

方式一：启动最新版

sh 复制代码

docker run -d \
    --hostname 192.168.1.100 \
    --name gitlab \
    --restart always \
    -p 8002:443 -p 8003:80 -p 8004:22 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /data/gitlab/config:/etc/gitlab \
    -v /data/gitlab/logs:/var/log/gitlab \
    -v /data/gitlab/data:/var/opt/gitlab \
    gitlab/gitlab-ce

方式二：启动指定版本（推荐）

sh 复制代码

docker run --detach \
  --hostname 192.168.1.100 \
  -p 7001:80 -p 7002:22 -p 7003:443 \
  --name gitlab \
  --restart always \
  --volume /data/gitlab/config:/etc/gitlab \
  --volume /data/gitlab/logs:/var/log/gitlab \
  --volume /data/gitlab/data:/var/opt/gitlab \
  gitlab/gitlab-ce:17.9.8-ce.0

参数详解：

-d 或 --detach：后台运行容器
--hostname：设置容器主机名，建议设置为服务器的 IP 地址或域名
--name gitlab：指定容器名称为 gitlab
--restart always：容器退出时自动重启，确保服务高可用
-p 8002:443：将容器的 443 端口（HTTPS）映射到宿主机的 8002 端口
-p 8003:80：将容器的 80 端口（HTTP）映射到宿主机的 8003 端口
-p 8004:22：将容器的 22 端口（SSH）映射到宿主机的 8004 端口
-v /etc/localtime:/etc/localtime:ro：同步宿主机时区到容器（只读）
-v /data/gitlab/config:/etc/gitlab：挂载配置文件目录
-v /data/gitlab/logs:/var/log/gitlab：挂载日志目录
-v /data/gitlab/data:/var/opt/gitlab：挂载数据目录（仓库数据、数据库等）

1.3 修改 SSH 端口号用于项目可以通过 SSH 带端口号克隆

当 GitLab 的 SSH 端口映射到非标准的 22 端口时（如上面的 7002），需要告诉 GitLab 使用自定义端口。

步骤 1：编辑 GitLab 配置文件

sh 复制代码

# 进入容器并编辑 GitLab 配置文件
docker exec -it gitlab vi /etc/gitlab/gitlab.rb

步骤 2：设置 SSH 端口号

在配置文件中添加或修改以下内容：

ruby 复制代码

# 配置 SSH 端口（告诉 GitLab SSH 克隆地址显示的端口号）
gitlab_rails['gitlab_shell_ssh_port'] = 7002

步骤 3：重载 GitLab 配置

sh 复制代码

# 使配置生效（此过程需要几分钟）
docker exec -it gitlab gitlab-ctl reconfigure

说明：

gitlab-ctl reconfigure：重新配置 GitLab，解析 gitlab.rb 文件并应用更改
配置完成后，项目的 SSH 克隆地址会显示为 git@192.168.1.100:7002:username/project.git

1.4 修改 GitLab 容器内部的端口号为 7001

如果需要修改 GitLab 内部使用的端口（通常在使用非标准端口映射时需要）：

sh 复制代码

# 编辑 GitLab 的 Rails 配置文件
docker exec -it gitlab vi /opt/gitlab/embedded/service/gitlab-rails/config/gitlab.yml

在配置文件中找到 gitlab 部分，修改 port 字段为 7001（与宿主机映射的端口一致）。

配置示例：

yaml 复制代码

production: &base
  gitlab:
    host: 192.168.1.100
    port: 7001  # 修改此处
    https: false

1.5 重启 GitLab

修改配置后需要重启 GitLab 服务使其生效：

sh 复制代码

# 重启 GitLab 所有服务
docker exec -it gitlab gitlab-ctl restart

⚠️ 重要提示：

如果修改了 /etc/gitlab/gitlab.rb 文件，必须执行 reconfigure 才会生效：

sh 复制代码

# 编辑配置文件
docker exec -it gitlab vi /etc/gitlab/gitlab.rb

# 重载配置（必须执行）
docker exec -it gitlab gitlab-ctl reconfigure

常用 GitLab 管理命令：

sh 复制代码

# 查看 GitLab 服务状态
docker exec -it gitlab gitlab-ctl status

# 停止所有服务
docker exec -it gitlab gitlab-ctl stop

# 启动所有服务
docker exec -it gitlab gitlab-ctl start

# 查看日志
docker exec -it gitlab gitlab-ctl tail

1.6 首次重置 GitLab 管理员账户密码

GitLab 首次启动后，默认管理员账号是 root，需要手动设置密码。

步骤 1：进入 GitLab Rails 控制台

sh 复制代码

# 进入 GitLab 的 Rails 控制台（注意：容器名称需要与实际一致）
sudo docker exec -it gitlab gitlab-rails console -e production

说明：

gitlab-rails console：进入 GitLab 的 Ruby on Rails 控制台
-e production：指定生产环境
首次进入需要等待约 50 秒，系统会加载各种依赖

步骤 2：在控制台中执行以下命令

ruby 复制代码

# 查找 root 用户对象
user = User.find_by_username('root')

# 设置新密码（必须满足 GitLab 密码强度要求，通常至少 8 位，包含字母和数字）
user.password = 'NewSecurePassword123!'
user.password_confirmation = 'NewSecurePassword123!'

# 保存更改到数据库
user.save!

# 退出控制台
exit

密码要求：

至少 8 个字符
建议包含大小写字母、数字和特殊字符
避免使用弱密码，确保系统安全

修改完密码后，就可以使用 root 用户名和新密码登录 GitLab 了。访问地址：http://192.168.1.100:7001

二、部署 GitLab Runner

GitLab Runner 是用于执行 CI/CD 任务的组件，与 GitLab 配合使用可以实现自动化构建、测试和部署。

2.1 拉取 GitLab Runner 镜像

sh 复制代码

# 拉取最新版本的 GitLab Runner
docker pull gitlab/gitlab-runner:latest

2.2 创建 GitLab Runner 容器

sh 复制代码

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

参数详解：

-d：后台运行容器
--name gitlab-runner：指定容器名称
--restart always：容器异常退出时自动重启
-v /data/gitlab-runner/config:/etc/gitlab-runner：挂载配置目录，持久化 Runner 配置
-v /var/run/docker.sock:/var/run/docker.sock：挂载 Docker socket，允许 Runner 在宿主机上执行 Docker 命令（用于 Docker executor）

说明：

挂载 Docker socket 后，Runner 可以在 CI/CD 任务中构建 Docker 镜像、运行容器等操作。

三、注册 Runner 到 GitLab

创建 Runner 容器后，需要将其注册到 GitLab 才能使用。

3.1 获取注册 Token

登录 GitLab
进入项目 → Settings → CI/CD → Runners
1. 参考下图步骤
复制 Registration token 然后到gitlab-runner容器内执行

3.2 注册 Runner

sh 复制代码

docker exec -it gitlab-runner gitlab-runner register  --url http://192.168.1.100:7001  --token glrt-t3_xxxxxxxxxxxxxx

按照提示输入以下信息：

GitLab 实例 URL ：http://192.168.1.100:7001/, 可以直接回车
Registration token：从 GitLab 复制的 token, 可以直接回车
Runner 描述 ：自定义名称，如 my-docker-runner
Runner tags ：标签，用于指定哪些任务使用此 Runner，如 docker,build
Executor ：选择 docker
默认 Docker 镜像 ：如 alpine:latest

注册完成后，在 GitLab 的 Runner 页面就能看到新注册的 Runner 了。

3.3 设置 Runner 的 Docker 镜像优先从本地拉取

为了提高 CI/CD 任务的执行效率，可以配置 Runner 优先使用本地已有的 Docker 镜像，避免每次都从远程仓库拉取。

步骤 1：编辑 Runner 配置文件

找到宿主机上挂载的 Runner 配置文件（通常在 /data/gitlab-runner/config/config.toml）：

sh 复制代码

vi /data/gitlab-runner/config/config.toml

步骤 2：添加镜像拉取策略

在 [runners.docker] 配置段中添加以下内容：

toml 复制代码

[[runners]]
  name = "my-runner"
  url = "http://192.168.1.100:7001/"
  token = "your-runner-token"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    pull_policy = "if-not-present"  # 添加此行

pull_policy 可选值：

always：总是从远程拉取最新镜像（默认）
if-not-present：本地不存在时才拉取（推荐）
never：从不拉取，只使用本地镜像

四、总结

至此，GitLab 和 GitLab Runner 已经部署完成。主要步骤回顾：

✅ 拉取并启动 GitLab 容器
✅ 配置 SSH 端口和内部端口
✅ 重置管理员密码
✅ 部署 GitLab Runner
✅ 配置镜像拉取策略
✅ 注册 Runner 到 GitLab

现在可以开始使用 GitLab 进行代码管理和 CI/CD 自动化了！

五、常见问题

5.1 GitLab 启动很慢怎么办？

GitLab 首次启动需要初始化数据库和各种服务，通常需要 3-5 分钟。可以通过以下命令查看启动日志：

sh 复制代码

docker logs -f gitlab

5.2 忘记管理员密码怎么办？

参考第 1.6 节的步骤重新设置密码。

5.3 如何备份 GitLab 数据？

GitLab 的所有数据都在挂载的目录中，定期备份以下目录即可：

/data/gitlab/config：配置文件
/data/gitlab/data：仓库数据和数据库
/data/gitlab/logs：日志文件（可选）

5.4 Runner 无法连接到 GitLab？

检查以下几点：

GitLab 服务是否正常运行
Runner 容器与 GitLab 容器是否在同一网络
URL 和 token 是否正确
防火墙是否开放相应端口