Docker 容器中运行 GitLab 的故障排除

在 Docker 容器中安装 GitLab 时，您可能会遇到以下问题。

诊断潜在问题

当排查 Docker 容器中的 GitLab 实例问题时，以下命令很有用：

读取容器日志：

sudo docker logs gitlab

进入运行中的容器：

sudo docker exec -it gitlab /bin/bash

您可以在容器内部管理 GitLab 容器，就像管理 Linux 包安装 一样。

500 内部错误

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

sudo docker restart gitlab

权限问题

从较旧的 GitLab Docker 镜像更新时，您可能会遇到权限问题。这是当之前镜像中的用户权限没有被正确保留时发生的。有一个脚本可以修复所有文件的权限。

要修复您的容器，请执行 update-permissions，然后重启容器：

sudo docker exec gitlab update-permissions
sudo docker restart gitlab

在资源 ruby_block 上执行操作时出错

当在 Windows 或 Mac 上使用 Docker Toolbox 和 Oracle VirtualBox，并使用 Docker 卷时，会出现此错误：

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

/c/Users 卷被挂载为 VirtualBox 共享文件夹，不支持所有 POSIX 文件系统功能。目录所有权和权限无法在不重新挂载的情况下更改，导致 GitLab 失败。

请改用您平台的原生 Docker 安装，而不是使用 Docker Toolbox。

如果您无法使用原生 Docker 安装（Windows 10 家庭版或 Windows 7/8），另一种解决方案是为 Docker Toolbox 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。如果您更改了组名，需要调整命令。

Docker 容器中 /dev/shm 挂载空间不足

GitLab 在 /-/metrics 提供了一个 Prometheus 指标端点，用于暴露 GitLab 的健康和性能统计信息。所需的文件会写入临时文件系统（如 /run 或 /dev/shm）。

默认情况下，Docker 为共享内存目录（挂载在 /dev/shm）分配 64 MB。这不足以容纳生成的所有 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 指标，但解决此问题的推荐方法是 安装 时将共享内存设置为至少 256 MB。如果您使用 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 版本构建的容器时，会发生此错误。在 GitLab 16.0 及更高版本中，容器镜像包含使用较新 glibc 版本构建的 Ubuntu 22.04 Linux 包。

在 Docker 20.10.10 等较新的容器运行时工具中不会出现此问题。

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