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 拉取镜像

# 拉取最新版本
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 启动容器

方式一：启动最新版

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

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

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 配置文件

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

步骤 2：设置 SSH 端口号

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

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

步骤 3：重载 GitLab 配置

# 使配置生效（此过程需要几分钟）
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 内部使用的端口（通常在使用非标准端口映射时需要）：

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

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

配置示例：

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

1.5 重启 GitLab

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

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

⚠️ 重要提示：

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

# 编辑配置文件
docker exec -it gitlab vi /etc/gitlab/gitlab.rb# 重载配置（必须执行）
docker exec -it gitlab gitlab-ctl reconfigure

常用 GitLab 管理命令：

# 查看 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 控制台

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

说明：

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

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

# 查找 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 镜像

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

2.2 创建 GitLab Runner 容器

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

1. 登录 GitLab

2. 进入项目 → Settings → CI/CD → Runners

   1. 参考下图步骤
      

3. 复制 Registration token 然后到gitlab-runner容器内执行

3.2 注册 Runner

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）：

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

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

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

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

pull_policy 可选值：

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

四、总结

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

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

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

五、常见问题

5.1 GitLab 启动很慢怎么办？

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

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 是否正确
• 防火墙是否开放相应端口