基于Docker搭建Gitlab代码仓库

基于Docker搭建Gitlab代码仓库

gitlab支持Linux安装包（Omnibus），云原生、docker几种方式安装。本文记录使用Docker搭建GitLab。

1. 先决条件

1.1 安装需求

Gitlab依赖的软件，例如PG、Redis等组件已经统一打包为单个容器镜像，会作为一个容器运行。这里仅说明硬件要求：

CPU

以下是针对部分用户数量群体，推荐的最低 CPU 硬件要求。

• 4 核 是推荐的最小核数，支持多达 500 名用户
• 8 核支持多达 1000 名用户

CPU 需求取决于用户数量和预期的工作负载，确切需求更多地取决于您的工作负载。您的工作负载受多重因素影响，不限于您的用户活跃程度、您使用的自动化程度、镜像、制品库大小和变更大小。

内存

以下是针对部分用户数量群体，推荐的最低内存硬件要求。

• 4GB RAM 是必需的最小内存，支持多达 500 名用户
• 8GB RAM 支持多达 1000 名用户

内存需求取决于用户数量和预期的工作负载，确切需求更多地取决于您的工作负载。您的工作负载受多重因素影响，不限于您的用户活跃程度、您使用的自动化程度、镜像、制品库大小和变更大小。

存储

Omnibus GitLab 软件包需要大约 2.5 GB 的存储空间用于安装。必要的硬盘空间在很大程度上取决于您想在极狐GitLab 中存储的仓库的大小，但作为准则，您应该至少拥有与所有仓库组合占用的空间一样多的可用空间。

1.2 docker环境准备

参考Docker官方安装文档安装Docker环境。

本文以ubuntu 20.04系统为例：

apt update
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
\# 这里使用的是阿里云的 Docker 镜像源，您也可以选择其他中国国内的镜像源，比如 DaoCloud、网易云等。
add-apt-repository "deb [arch=amd64] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"
apt install docker-ce docker-ce-cli containerd.io
systemctl start docker
systemctl enable docker

说明

Docker for Windows 不受gitlab官方支持，存在卷权限的已知问题，以及潜在的其他未知问题。

2. 设置卷位置

配置一个新的环境变量 $GITLAB_HOME，指向配置、日志和数据文件所在的目录。 确保该目录存在并且已授予适当的权限。

export GITLAB_HOME=/data/gitlab

GITLAB_HOME 环境变量应该附加到您的 shell 的配置文件中，以便它应用于所有未来的终端会话：~/.bash_profile

GitLab 容器使用主机装载的卷来存储持久数据：

本地位置	容器位置	使用
$GITLAB_HOME/data	/var/opt/gitlab	用于存储应用程序数据。
$GITLAB_HOME/logs	/var/log/gitlab	用于存储日志。
$GITLAB_HOME/config	/etc/gitlab	用于存储GitLab 配置文件。

3. 准备gitlab镜像

可以直接拉取或者离线导入gitlab-ce镜像, 注意选择ce版本的镜像：

docker search gitlab

# 拉取github官方的gitlab镜像
docker pull gitlab/gitlab-ce:latest

# 极狐gitlab镜像
docker pull registry.gitlab.cn/omnibus/gitlab-jh:latest

# 指定版本的镜像
docker pull registry.gitlab.cn/omnibus/gitlab-jh:14.5.0

gitlab镜像较大，在线拉取时间较长。

说明

1. GitLab Docker 镜像是GitLab 的整体镜像，在单个容器中运行所有必要的服务。Docker 镜像中不包括邮件传输代理 (MTA)。推荐的解决方案是添加在单独容器中运行的 MTA（例如 Postfix 或 Sendmail）。作为另一种选择，您可以直接在GitLab 容器中安装 MTA，但这会增加维护开销，因为您可能需要在每次升级或重新启动后重新安装 MTA。
2. 不建议在K8S部署Gitlab容器镜像，存在单点故障。K8S下建议使用 GitLab Helm Chart 或者 GitLab Operator。
3. 如果访问docker hub受限，可以使用gitlab-jh镜像，功能是一样的，并且做了汉化处理。

4. 启动gitlab容器

export GITLAB_HOME=/data/gitlab

# docker启动命令
docker run --detach \
  --hostname gitlab.example.com \
  --publish 443:443 --publish 80:80 --publish 10022:22 \
  --name gitlab \
  --privileged=true \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab \
  --volume $GITLAB_HOME/logs:/var/log/gitlab \
  --volume $GITLAB_HOME/data:/var/opt/gitlab \
  --shm-size 256m \
  gitlab/gitlab-ce:latest

这将下载并启动极狐GitLab 容器，并发布访问 SSH、HTTP 和 HTTPS 所需的端口。所有极狐GitLab 数据将存储在 $GITLAB_HOME 的子目录中。系统重启后，容器将自动 restart。

首次部署会进行部署化，过程较长，可以查看容器日志进行跟踪：

docker logs -f gitlab

访问极狐GitLab URL，并使用用户名 root 和来自以下命令的密码登录：

docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

进入gitlab后及时修改root密码，上述密码文件会在24h后删除。

5. 自定义端口部署示例

gitlab容器默认的http端口为80，https端口为443。如果要使用不同的端口，docker run命令映射端口时需要注意。

例如，要在主机的端口 8929 上公开 Web 界面，并在端口 2289 上公开 SSH 服务：

1. 使用以下 docker run 命令：

export GITLAB_HOME=/data/gitlab

docker run --detach \
  --hostname gitlab.example.com \
  --publish 8929:8929 --publish 2289:22 \
  --name gitlab \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab \
  --volume $GITLAB_HOME/logs:/var/log/gitlab \
  --volume $GITLAB_HOME/data:/var/opt/gitlab \
  --shm-size 256m \
  gitlab/gitlab-ce:latest

发布端口的格式是 hostPort:containerPort。在 Docker 的文档中阅读有关公开传入端口的更多信息。

2. 进入正在运行的容器：

docker exec -it gitlab /bin/bash

3. 用编辑器打开 /etc/gitlab/gitlab.rb 并设置 external_url：

# For HTTP
external_url "http://gitlab.example.com:8929"

or

# For HTTPS (notice the https)
external_url "https://gitlab.example.com:8929"

此 external_url 中指定的端口必须与 Docker 发布到主机的端口匹配，上述url中的端口8929即是http(s)端口，docker主机的端口要映射到容器的8929端口，gitlab容器web界面会监听8929端口。【！！！这块容易配置错误，导致最终访问不了gitlab web界面，请务必注意】。

此外，如果 NGINX 监听端口没有在 nginx['listen_port'] 中明确设置，它将从 external_url 中拉取。有关更多信息，请参阅 NGINX 文档。

4. 设置 gitlab_shell_ssh_port：

gitlab_rails['gitlab_shell_ssh_port'] = 2289

5. 重新配置极狐GitLab：

gitlab-ctl reconfigure

如果是容器刚启动进入后修改配置文件并重新配置，上述命令执行时间较长，请耐心等待。

按照上面的示例，您将能够从 Web 浏览器在 http://gitlab.example.com:8929 下访问极狐GitLab，并在端口 2289 下使用 SSH 进行推送。

说明

1. /etc/gitlab/gitlab.rb文件的配置会映射到/opt/gitlab/embedded/service/gitlab-rails/config/gitlab.yml。
2. 如果是用ip地址配置，将上述域名部分换为ip地址即可。

6. 场景问题

如果您在使用 Omnibus GitLab 和 Docker 时遇到问题，以下信息将有所帮助。下面常见问题摘自官方文档，供参考。

诊断潜在问题

读取容器日志：

docker logs gitlab

进入正在运行的容器：

docker exec -it gitlab /bin/bash

从容器内，您可以像 Omnibus 安装示例一样管理极狐GitLab 容器。

HTTP 502: Waiting for GitLab to boot

It can take up to a few minutes for GitLab to boot completely.

Gitlab容器里的组件没有启动完成，等待一会进行访问。

500 Internal Error

更新 Docker 镜像时，您可能会遇到所有路径都显示 500 页面的问题。如果发生这种情况，请重新启动容器以尝试纠正问题：

docker restart gitlab

权限问题

从旧的极狐GitLab Docker 镜像更新时，您可能会遇到权限问题。当之前镜像中的用户未正确保留时，就会发生这种情况。存在修复所有文件权限的脚本。

要修复您的容器，请执行 update-permissions 并在之后重新启动容器：

docker exec gitlab update-permissions
docker restart gitlab

Windows/Mac: Error executing action run on resource ruby_block[directory resource: /data/GitLab]

在 Windows 或 Mac 上将 Docker Toolbox 与 VirtualBox 一起使用并使用 Docker 卷时，会发生此错误。/c/Users 卷挂载为 VirtualBox 共享文件夹，不支持所有 POSIX 文件系统功能。 不重新挂载就无法更改目录所有权和权限，并且极狐GitLab 失败。

我们的建议是切换到为您的平台使用本机 Docker 安装，而不是使用 Docker Toolbox。

如果您不能使用本机 Docker 安装（Windows 10 家庭版或 Windows 7/8），那么另一种解决方案是为 Docker 工具箱的 boot2docker 设置 NFS 挂载而不是 VirtualBox 共享。

Linux ACL 问题

如果您在 Docker 主机上使用文件 ACL，docker 组需要对卷的完全访问权限才能让极狐GitLab 工作：

getfacl $GITLAB_HOME

# file: $GITLAB_HOME
# owner: XXXX
# group: XXXX
user::rwx
group::rwx
group:docker:rwx
mask::rwx
default:user::rwx
default:group::rwx
default:group:docker:rwx
default:mask::rwx
default:other::r-x

如果这些不正确，请将它们设置为：

sudo setfacl -mR default:group:docker:rwx $GITLAB_HOME

默认组是docker。如果您更改了组，请务必更新您的命令。

/dev/shm mount 在 Docker 容器中没有足够的空间

极狐GitLab 在 /-/metrics 带有 Prometheus 指标端点，用于公开有关极狐GitLab 运行状况和性能的各种统计信息。为此所需的文件被写入临时文件系统（如 /run 或 /dev/shm）。

默认情况下，Docker 分配 64MB 给共享内存目录（挂载在/dev/shm）。这不足以保存所有生成的 Prometheus 指标相关文件，并将生成如下错误日志：

writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file

除了从管理页面禁用 Prometheus Metrics 之外，解决此问题的推荐解决方案是将共享内存的大小增加到至少 256MB。 如果使用 docker run，可以通过传递标志 --shm-size 256m 来完成。 如果使用 docker-compose.yml 文件，shm_size 键可以用于此目的。

由于 json-file，Docker 容器耗尽了空间

Docker的默认日志驱动是json-file，默认不执行日志轮换。由于缺乏轮换，json-file 驱动程序存储的日志文件可能会为生成大量输出的容器消耗大量磁盘空间。这会导致磁盘空间耗尽。要解决此问题，请在可用时使用 journald 作为日志记录驱动程序，或其他支持的驱动程序与本地轮换支持。

启动 Docker 时出现缓冲区溢出错误

如果您收到此缓冲区溢出错误，您应该清除 /var/log/gitlab 中的旧日志文件：

buffer overflow detected : terminated
xargs: tail: terminated by signal 6

删除旧的日志文件有助于修复错误，并确保实例的干净启动。

ThreadError 不允许操作，无法创建线程

can't create Thread: Operation not permitted

在不支持新的 clone3 函数的主机上，运行使用较新的 glibc 版本构建的容器时，会发生此错误。在 16.0 及更高版本中，容器镜像包含使用较新的 glibc 构建的 Ubuntu 22.04 Linux 软件包。

此问题已在 Docker 20.10.10 等较新的容器运行时工具得到解决。

要解决此问题，请将 Docker 更新到版本 20.10.10 或更高版本。

7.相关资料

1. 中文安装指导：https://gitlab.cn/docs/jh/install/docker.html
2. 英文安装指导：Install GitLab in a Docker container | GitLab
3. 故障排查：极狐GitLab Docker 镜像 | 极狐GitLab