对 Omnibus GitLab 安装问题进行故障排查

使用此页面了解用户在安装 Omnibus GitLab 软件包时可能遇到的常见问题。

下载包时哈希和不匹配

apt-get install 输出如下：

E: Failed to fetch https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/pool/trusty/main/g/gitlab-ce/gitlab-ce_8.1.0-ce.0_amd64.deb  Hash Sum mismatch

请运行以下命令来解决这个问题：

sudo rm -rf /var/lib/apt/lists/partial/*
sudo apt-get update
sudo apt-get clean

在 openSUSE 和 SLES 平台上安装会警告未知密钥签名

除了提供签名元数据的包仓库之外，Omnibus GitLab 包使用 GPG 密钥签名。这确保了分发给用户的包的真实性和完整性。 但是，openSUSE 和 SLES 操作系统中使用的包管理器有时可能会使用这些签名引发错误警告，类似于：

File 'repomd.xml' from repository 'gitlab_gitlab-ce' is signed with an unknown key '14219A96E15E78F4'. Continue? [yes/no] (no):
File 'repomd.xml' from repository 'gitlab_gitlab-ce' is signed with an unknown key '14219A96E15E78F4'. Continue? [yes/no] (no): yes

这是 zypper 的一个已知错误，其中 zypper 忽略仓库配置文件中的 gpgkey 关键字。在 Packagecloud 的更高版本中，可能会对此有所改进，但目前用户必须手动同意软件包安装。

所以，在 openSUSE 或 SLES 系统中，如果出现这样的警告，继续安装是安全的。

重新配置时显示错误：NoMethodError - undefined method '[]=' for nil:NilClass

您运行了 sudo gitlab-ctl reconfigure 或包升级触发了重新配置，它产生了类似于以下内容的错误：

 ================================================================================
 Recipe Compile Error in /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/default.rb
 ================================================================================

NoMethodError
-------------
undefined method '[]=' for nil:NilClass

Cookbook Trace:
---------------
  /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/config.rb:21:in 'from_file'
  /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/default.rb:26:in 'from_file'

Relevant File Content:

当 /etc/gitlab/gitlab.rb 配置文件包含无效或不受支持的配置时，会显示此错误。仔细检查没有错别字或配置文件不包含过时的配置。

您可以使用 sudo gitlab-ctl diff-config 或检查最新的 gitlab.rb.template。

极狐GitLab 在我的浏览器中无法访问

尝试在 /etc/gitlab/gitlab.rb 中指定一个 external_url。还要检查您的防火墙设置；您的 GitLab 服务器上的端口 80 (HTTP) 或 443 (HTTPS) 可能已关闭。

请注意，为 GitLab 或任何其他捆绑服务（Registry 和 Mattermost）指定 external_url 不遵循 gitlab.rb 的其它部分遵循的 key=value 格式。确保按以下格式设置它们：

external_url "https://gitlab.example.com"
registry_external_url "https://registry.example.com"
mattermost_external_url "https://mattermost.example.com"
note 不要在 external_url 和值之间添加等号 (=)。

电子邮件未送达

要测试电子邮件传递，您可以为尚未在您的 GitLab 实例中使用的电子邮件创建一个新的极狐GitLab 账户。

如有必要，您可以使用 /etc/gitlab/gitlab.rb 中的以下设置修改 GitLab 发送的电子邮件的 From 字段：

gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'

运行 sudo gitlab-ctl reconfigure 以使更改生效。

GitLab 服务的 TCP 端口已经被占用

默认情况下，Puma 侦听 TCP 地址 127.0.0.1:8080。NGINX 在所有接口上侦听端口 80 (HTTP) 和/或 443 (HTTPS)。

Redis、PostgreSQL 和 Puma 的端口可以在 /etc/gitlab/gitlab.rb 中被覆盖，如下：

redis['port'] = 1234
postgresql['port'] = 2345
puma['port'] = 3456

对于 NGINX 端口更改，请参阅设置 NGINX 监听端口文档。

Git 用户没有 SSH 访问权限

支持 SELinux 的系统

在支持 SELinux 的系统上，Git 用户的 .ssh 目录或其内容可能会弄乱他们的安全上下文。您可以通过运行 sudo gitlab-ctl reconfigure 来解决这个问题，将在 /var/opt/gitlab/.ssh 上设置 gitlab_shell_t 安全上下文。

通过使用 semanage 永久设置上下文来改进此行为。运行时依赖项 policycoreutils-python 已添加到基于 RHEL 的操作系统的 RPM 包中，以确保 semanage 命令可用。

诊断并解决 SELinux 问题

Omnibus GitLab 检测到 /etc/gitlab/gitlab.rb 中的默认路径更改，并应用正确的文件上下文。对于使用自定义数据路径配置的安装，管理员可能需要手动解决 SELinux 问题。

数据路径可以通过 gitlab.rb 更改，但是，一个常见的场景会强制使用 symlink 路径。管理员应谨慎，因为并非所有场景都支持 symlink 路径，例如 Gitaly 数据路径。

例如，如果 /data/gitlab 替换 /var/opt/gitlab 作为基本数据目录，则参考以下命令修复安全上下文：

sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/.ssh/
sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/.ssh/authorized_keys
sudo restorecon -Rv /data/gitlab/
sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/gitlab-shell/config.yml
sudo restorecon -Rv /data/gitlab/gitlab-shell/
sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/gitlab-rails/etc/gitlab_shell_secret
sudo restorecon -Rv /data/gitlab/gitlab-rails/
sudo semanage fcontext --list | grep /data/gitlab/

应用策略后，您可以通过收到欢迎消息来验证 SSH 访问是否正常：

ssh -T git@gitlab-hostname

所有系统

默认情况下，Git 用户使用锁定的密码创建，在 /etc/shadow 中显示为 '!'。 除非启用 “UsePam yes”，否则 OpenSSH 守护程序将阻止 Git 用户使用 SSH 密钥进行身份验证。另一种安全解决方案是通过在 /etc/shadow 中用 '*' 替换 '!' 来解锁密码。Git 用户仍然无法更改密码，因为它在受限的 shell 中运行，并且非超级用户的 passwd 命令需要在输入新密码之前输入当前密码。用户无法输入与 '*' 匹配的密码，因此账号保持无密码。

请记住，Git 用户必须有权访问系统，因此请检查您在 /etc/security/access.conf 中的安全设置，并确保 Git 用户未被阻止。

PostgreSQL 错误 FATAL: could not create shared memory segment: Cannot allocate memory

打包后的 PostgreSQL 实例会尝试分配总内存的 25% 作为共享内存。在某些 Linux（虚拟）服务器上，可用的共享内存较少，这将阻止 PostgreSQL 启动。 在/var/log/gitlab/postgresql/current 中：

  1885  2014-08-08_16:28:43.71000 FATAL:  could not create shared memory segment: Cannot allocate memory
  1886  2014-08-08_16:28:43.71002 DETAIL:  Failed system call was shmget(key=5432001, size=1126563840, 03600).
  1887  2014-08-08_16:28:43.71003 HINT:  This error usually means that PostgreSQL's request for a shared memory segment exceeded available memory or swap space, or exceeded your kernel's SHMALL parameter.  You can either reduce the request size or reconfigure the kernel with larger SHMALL.  To reduce the request size (currently 1126563840 bytes), reduce PostgreSQL's shared memory usage, perhaps by reducing shared_buffers or max_connections.
  1888  2014-08-08_16:28:43.71004       The PostgreSQL documentation contains more information about shared memory configuration.

您可以手动降低 PostgreSQL 尝试在 /etc/gitlab/gitlab.rb 中分配的共享内存量：

postgresql['shared_buffers'] = "100MB"

运行 sudo gitlab-ctl reconfigure 以使更改生效。

PostgreSQL 错误 FATAL: could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied

默认情况下，PostgreSQL 将尝试检测要使用的共享内存类型。如果没有启用共享内存，您可能会在 /var/log/gitlab/postgresql/current 中看到这个错误。 要解决此问题，您可以禁用 PostgreSQL 的共享内存检测。在/etc/gitlab/gitlab.rb 中设置以下值：

postgresql['dynamic_shared_memory_type'] = 'none'

运行 sudo gitlab-ctl reconfigure 以使更改生效。

PostgreSQL 错误 FATAL: remaining connection slots are reserved for non-replication superuser connections

PostgreSQL 对数据库服务器的最大并发连接数进行了设置。如果您看到此错误，则表示您的极狐GitLab 实例正试图超过此并发连接数限制。

要解决此问题，您有两种选择：

  • 增加最大连接值：

    1. 编辑 /etc/gitlab/gitlab.rb：

      postgresql['max_connections'] = 600

    2. 重新配置极狐GitLab：

      sudo gitlab-ctl reconfigure

  • 或者，您可以考虑使用 PgBouncer，它是 PostgreSQL 的连接池。

重新配置时的 GLIBC 版本问题 

$ gitlab-ctl reconfigure

/opt/gitlab/embedded/bin/ruby: /lib64/libc.so.6: version `GLIBC_2.14' not found (required by /opt/gitlab/embedded/lib/libruby.so.2.1)
/opt/gitlab/embedded/bin/ruby: /lib64/libc.so.6: version `GLIBC_2.17' not found (required by /opt/gitlab/embedded/lib/libruby.so.2.1)

如果您安装的 omnibus 软件包是为与服务器上的操作系统版本不同的操作系统版本构建的，则可能会发生这种情况。 仔细检查您是否为您的操作系统下载并安装了正确的 Omnibus GitLab 软件包。

重新配置无法创建 Git 用户

如果您以 Git 用户身份运行 sudo gitlab-ctl reconfigure，就会发生这种情况。切换到另一个用户。

更重要的是：不要向 Git 用户或 Omnibus GitLab 使用的任何其它用户授予 sudo 权限。授予系统用户不必要的权限会削弱系统的安全性。

使用 sysctl 修改内核参数失败

如果 sysctl 无法修改内核参数，您可能会收到以下堆栈跟踪错误：

 * execute[sysctl] action run
================================================================================
Error executing action `run` on resource 'execute[sysctl]'
================================================================================


Mixlib::ShellOut::ShellCommandFailed
------------------------------------
Expected process to exit with [0], but received '255'
---- Begin output of /sbin/sysctl -p /etc/sysctl.conf ----

这在非虚拟机上不太可能发生，但在像 openVZ 这样具有虚拟化功能的 VPS 上，容器可能没有启用所需的模块或容器无法访问内核参数。

尝试启用 sysctl 出错的模块。

此错误的另一个变体中，报告文件系统是只读的，并显示以下堆栈跟踪：

 * execute[load sysctl conf] action run
    [execute] sysctl: setting key "kernel.shmall": Read-only file system
              sysctl: setting key "kernel.shmmax": Read-only file system

    ================================================================================
    Error executing action `run` on resource 'execute[load sysctl conf]'
    ================================================================================

    Mixlib::ShellOut::ShellCommandFailed
    ------------------------------------
    Expected process to exit with [0], but received '255'
    ---- Begin output of cat /etc/sysctl.conf /etc/sysctl.d/*.conf  | sysctl -e -p - ----
    STDOUT:
    STDERR: sysctl: setting key "kernel.shmall": Read-only file system
    sysctl: setting key "kernel.shmmax": Read-only file system
    ---- End output of cat /etc/sysctl.conf /etc/sysctl.d/*.conf  | sysctl -e -p - ----
    Ran cat /etc/sysctl.conf /etc/sysctl.d/*.conf  | sysctl -e -p - returned 255

此错误仅在虚拟机中报告发生，建议的解决方法是在主机中设置值。GitLab 所需的值可以在虚拟机的 /opt/gitlab/embedded/etc/90-omnibus-gitlab.conf 文件中找到。在主机操作系统的 /etc/sysctl.conf 文件中设置这些值后，在主机上运行 cat /etc/sysctl.conf /etc/sysctl.d/*.conf | sysctl -e -p -。然后尝试在虚拟机中运行 gitlab-ctl reconfigure。这样应该检测到内核已经在使用必要的设置运行，并且不会引发任何错误。

另请注意，您可能需要对其它几行重复此过程，例如重新配置将失败 3 次，您最终将在/etc/sysctl.conf 中添加如下内容：

kernel.shmall = 4194304
kernel.sem = 250 32000 32 262
net.core.somaxconn = 1024
kernel.shmmax = 17179869184

您可能会发现查看 Chef 输出中的行比查找文件更容易（因为每个错误的文件都不同）。请参阅此代码段的最后一行。

* file[create /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf kernel.shmall] action create
  - create new file /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf
  - update content in file /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf from none to 6d765d
  --- /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf 2017-11-28 19:09:46.864364952 +0000
  +++ /opt/gitlab/embedded/etc/.chef-90-omnibus-gitlab-kernel.shmall.conf kernel.shmall20171128-13622-sduqoj 2017-11-28 19:09:46.864364952 +0000
  @@ -1 +1,2 @@
  +kernel.shmall = 4194304

我无法在没有 root 访问权限的情况下安装 Omnibus GitLab

有时人们会问他们是否可以在没有 root 访问权限的情况下安装 GitLab。这样做有一些问题。

安装 .deb 或 .rpm

据我们所知，没有一种干净的方法可以以非特权用户身份安装 Debian 或 RPM 软件包。您不能安装 Omnibus GitLab RPM，因为 Omnibus 构建过程不会创建源 RPM。

在端口 80 和 443 上轻松托管

部署 GitLab 最常见的方法是让 Web 服务器（NGINX/Apache）与 GitLab 运行在同一台服务器上，Web 服务器侦听特权 TCP 端口（低于 1024）。在 Omnibus GitLab 中，我们通过捆绑一个自动配置的 NGINX 服务来提供这种便利，该服务需要以 root 身份运行其主进程以打开端口 80 和 443。

如果这是有问题的，安装 GitLab 的管理员可以禁用捆绑的 NGINX 服务，但这给他们带来了在应用程序更新期间保持 NGINX 配置与 GitLab 一致的负担。

Omnibus 服务之间的隔离

Omnibus GitLab 中的捆绑服务（GitLab 本身、NGINX、PostgreSQL、Redis、Mattermost）使用 Unix 用户账号相互隔离。创建和管理这些用户账号需要 root 访问权限。默认情况下，Omnibus GitLab 将在 gitlab-ctl reconfigure 期间创建所需的 Unix 账户，但该行为可以禁用。

原则上，如果我们为每个应用程序提供自己的 runit (runsvdir)、PostgreSQL 和 Redis 进程，Omnibus GitLab 只能使用 2 个用户账号（一个用于 GitLab，一个用于 Mattermost）。 但这将是 gitlab-ctl reconfigure Chef 代码的一个重大变化，它可能会给所有现有的 Omnibus GitLab 安装带来重大的升级痛苦。（我们可能需要重新排列 /var/opt/gitlab 下的目录结构。）

调整操作系统以获得更好的性能

在 gitlab-ctl reconfigure 期间，我们设置并安装了几个 sysctl 调整以提高 PostgreSQL 性能并增加连接限制。这只能通过 root 访问来完成。

gitlab-rake assets:precompile 失败并显示 ‘Permission denied’

一些用户报告说，运行 gitlab-rake assets:precompile 不适用于 Omnibus 包。对此的简短回答是：不要运行该命令。

GitLab Web 界面使用 CSS 和 JavaScript 文件，在 Ruby on Rails-speak 中称为 “assets”。在上游 GitLab 仓库中，这些文件以开发人员友好的方式存储：易于阅读和编辑。当您是 GitLab 的普通用户时，您不希望这些文件采用开发人员友好的格式，因为这会使 GitLab 变慢。这就是为什么 GitLab 设置过程的一部分是将 asset是 从开发人员友好的格式转换为最终用户友好的（紧凑、快速）格式； 这就是 rake assets:precompile 脚本的用途。

当我们构建 Omnibus 安装包时，我们为您编译 assets。当您使用 Omnibus 安装包安装 GitLab 时，转换后的 assets 已经存在！这就是为什么从包安装 GitLab 时不需要运行 rake assets:precompile 的原因。

当 gitlab-rake assets:precompile 因权限错误而失败时，从安全角度来看，它失败是有充分理由的：assets 无法轻易重写的事实使攻击者更难使用您的 GitLab 服务器，来提供恶意的 JavaScript 代码给您的 GitLab 服务器的访问者。

如果您想使用自定义 JavaScript 或 CSS 代码运行 GitLab，您最好从源代码运行 GitLab，或者构建自己的包。

如果您真的知道您在做什么，您可以像这样执行 gitlab-rake gitlab:assets:compile：

sudo NO_PRIVILEGE_DROP=true USE_DB=false gitlab-rake gitlab:assets:clean gitlab:assets:compile
# user and path might be different if you changed the defaults of
# user['username'], user['group'] and gitlab_rails['dir'] in gitlab.rb
sudo chown -R git:git /var/opt/gitlab/gitlab-rails/tmp/cache

Apt 错误 ‘The requested URL returned error: 403’

尝试使用 apt 仓库安装极狐GitLab 时，如果您收到类似于以下内容的错误：

W: Failed to fetch https://packages.gitlab.com/gitlab/gitlab-ce/DISTRO/dists/CODENAME/main/source/Sources  The requested URL returned error: 403

检查您的服务器前面是否有仓库缓存器，例如 apt-cacher-ng。

将以下行添加到 apt-cacher-ng 配置（例如在/etc/apt-cacher-ng/acng.conf中）：

PassThroughPattern: (packages\.gitlab\.com|packages-gitlab-com\.s3\.amazonaws\.com|*\.cloudfront\.net)

在 packagecloud 博客上，阅读更多关于 apt-cacher-ng 以及需要进行此更改的原因。

使用自签名证书或自定义证书颁发机构

如果您在具有自定义证书颁发机构或使用自签名证书的隔离网络中安装 GitLab，请确保 GitLab 可以访问该证书。 不这样做会导致如下错误：

Faraday::SSLError (SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed)

当 GitLab 尝试连接 GitLab Shell 等内部服务时。

要修复这些错误，请参阅安装自定义公共证书部分。

error: proxyRoundTripper: XXX failed with: “net/http: timeout awaiting response headers”

如果 GitLab Workhorse 在 1 分钟（默认）内没有收到来自 GitLab 的答复，它将提供一个 502 页面。

请求可能超时的原因有很多，也许用户正在加载一个非常大的差异或类似情形。

您可以通过在 /etc/gitlab/gitlab.rb 中设置值来增加默认超时值：

gitlab_workhorse['proxy_headers_timeout'] = "2m0s"

保存文件并重新配置极狐GitLab 以使更改生效。

您想要的更改被拒绝

很可能您在 GitLab 前面有代理的环境中设置了 GitLab，并且默认情况下在包中设置的代理 headers 不适合您的环境。

有关如何覆盖默认 headers 的详细信息，请参阅更改 NGINX 文档的默认代理 headers 部分。

无法验证 CSRF 令牌已完成认证 422 Unprocessable

很可能您在 GitLab 前面有代理的环境中设置了 GitLab，并且默认情况下在包中设置的代理 headers 不适合您的环境。

有关如何覆盖默认 headers 的详细信息，请参阅更改 NGINX 文档的默认代理 headers 部分。

扩展缺少 pg_trgm

GitLab 需要 PostgreSQL 扩展 pg_trgm。如果您将 Omnibus GitLab 包与捆绑数据库一起使用，则升级时应自动启用扩展。

但是，如果您使用的是外部（非打包）数据库，则需要手动启用扩展。这样做的原因是带有外部数据库的 Omnibus GitLab 包无法确认扩展是否存在，并且它也没有启用扩展的方法。

要解决此问题，您需要先安装 pg_trgm 扩展。 该扩展位于 postgresql-contrib 包中。对于 Debian：

sudo apt-get install postgresql-contrib

安装扩展后，以超级用户身份访问 psql 并启用扩展。

  1. 以超级用户身份访问 psql：

    sudo gitlab-psql -d gitlabhq_production

  2. 启用扩展：

    CREATE EXTENSION pg_trgm;
\q

  3. 现在再次运行迁移：

    sudo gitlab-rake db:migrate

如果使用 Docker，首先需要访问你的容器，然后运行上面的命令，最后重启容器。

  1. 访问容器：

    docker exec -it gitlab bash

  2. 运行上面的命令。

  3. 重启容器：

    docker restart gitlab

Errno::ENOMEM: Cannot allocate memory during backup or upgrade

极狐GitLab 需要 2GB 的可用内存才能正常运行。根据服务器上其它进程的资源使用情况，安装 2GB 内存可能不够。 如果 GitLab 在不升级或运行备份时运行良好，那么添加更多 swap 应该可以解决您的问题。如果您在正常使用期间看到服务器使用 swap，则可以添加更多 RAM 以提高性能。

NGINX error: ‘could not build server_names_hash, you should increase server_names_hash_bucket_size’

如果 GitLab 的外部 URL 长于默认存储桶大小（64 字节），NGINX 可能会停止工作并在日志中显示此错误。为了允许更大的服务器名称，将 /etc/gitlab/gitlab.rb 中的存储桶大小加倍：

nginx['server_names_hash_bucket_size'] = 128

运行 sudo gitlab-ctl reconfigure 使更改生效。

由于 NFS root_squash “’root’ cannot chown” 导致重新配置失败 

$ gitlab-ctl reconfigure

================================================================================
Error executing action `run` on resource 'ruby_block[directory resource: /gitlab-data/git-data]'
================================================================================

Errno::EPERM
------------
'root' cannot chown /gitlab-data/git-data. If using NFS mounts you will need to re-export them in 'no_root_squash' mode and try again.
Operation not permitted @ chown_internal - /gitlab-data/git-data

如果您使用 NFS 挂载了目录并在 root_squash 模式下配置，就会发生这种情况。重新配置无法正确设置目录的所有权。您需要在 NFS 服务器上的 NFS 导出中切换到使用 no_root_squash，或禁用存储目录管理并自己管理权限。

gitlab-runsvdir 未启动

适用于使用 systemd 的操作系统（例如 Ubuntu 18.04+、CentOS 等）。

gitlab-runsvdir 在 multi-user.target 而不是 basic.target 期间启动。如果您在升级 GitLab 后无法启动此服务，您可能需要通过以下命令检查您的系统是否已正确启动了 multi-user.target 所需的所有服务：

systemctl -t target

如果一切正常，输出应如下所示：

UNIT                   LOAD   ACTIVE SUB    DESCRIPTION
basic.target           loaded active active Basic System
cloud-config.target    loaded active active Cloud-config availability
cloud-init.target      loaded active active Cloud-init target
cryptsetup.target      loaded active active Encrypted Volumes
getty.target           loaded active active Login Prompts
graphical.target       loaded active active Graphical Interface
local-fs-pre.target    loaded active active Local File Systems (Pre)
local-fs.target        loaded active active Local File Systems
multi-user.target      loaded active active Multi-User System
network-online.target  loaded active active Network is Online
network-pre.target     loaded active active Network (Pre)
network.target         loaded active active Network
nss-user-lookup.target loaded active active User and Group Name Lookups
paths.target           loaded active active Paths
remote-fs-pre.target   loaded active active Remote File Systems (Pre)
remote-fs.target       loaded active active Remote File Systems
slices.target          loaded active active Slices
sockets.target         loaded active active Sockets
swap.target            loaded active active Swap
sysinit.target         loaded active active System Initialization
time-sync.target       loaded active active System Time Synchronized
timers.target          loaded active active Timers

LOAD   = Reflects whether the unit definition was properly loaded.
ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
SUB    = The low-level unit activation state, values depend on unit type.

22 loaded units listed. Pass --all to see loaded but inactive units, too.
To show all installed unit files use 'systemctl list-unit-files'.

每一行都应该显示 loaded active active。如下行所示，如果您看到 inactive dead，这意味着可能有问题：

multi-user.target      loaded inactive dead   start Multi-User System

要检查 systemd 可能排队的作业，请运行：

systemctl list-jobs

如果您看到 running 作业，则服务可能会卡住，从而阻止 GitLab 启动。例如，一些用户遇到 Plymouth 无法启动的问题：

  1 graphical.target                     start waiting
107 plymouth-quit-wait.service           start running
  2 multi-user.target                    start waiting
169 ureadahead-stop.timer                start waiting
121 gitlab-runsvdir.service              start waiting
151 system-getty.slice                   start waiting
 31 setvtrgb.service                     start waiting
122 systemd-update-utmp-runlevel.service start waiting

在这种情况下，请考虑卸载 Plymouth。

非 Docker 容器中的初始化守护进程检测

在 Docker 容器中，GitLab 包检测 /.dockerenv 文件的存在并跳过初始化系统的自动检测。但是，在非 Docker 容器（如 containerd、cri-o 等）中，该文件不存在并且包回退到 sysvinit，这可能会导致安装问题。为了防止这种情况，用户可以通过在 gitlab.rb 文件中添加以下设置来显式禁用 init 守护进程检测：

package['detect_init'] = false

如果使用此配置，则必须在运行 gitlab-ctl reconfigure 之前启动 runit 服务，使用 runsvdir-start 命令：

/opt/gitlab/embedded/bin/runsvdir-start &

gitlab-ctl reconfigure 在使用 AWS Cloudformation 时挂起

GitLab systemd 单元文件默认对 After 和 WantedBy 字段使用 multi-user.target。这样做是为了确保服务在 remote-fs 和 network 目标之后运行，因此 GitLab 将正常运行。

但是，这与 AWS Cloudformation 使用的 cloud-init 自己的单元排序交互不佳。

为了解决这个问题，用户可以使用 gitlab.rb 中的 package['systemd_wanted_by'] 和 package['systemd_after'] 设置来指定正确排序所需的值并运行 sudo gitlab-ctl reconfigure。重新配置完成后，重启 gitlab-runsvdir 服务以使更改生效。

sudo systemctl restart gitlab-runsvdir

Errno::EAFNOSUPPORT: Address family not supported by protocol - socket(2)

启动 GitLab 时，如果观察到类似如下错误： ruby FATAL: Errno::EAFNOSUPPORT: Address family not supported by protocol - socket(2)

检查正在使用的主机名是否可解析并返回 IPv4 地址：

getent hosts gitlab.example.com
# Example IPv4 output: 192.168.1.1 gitlab.example.com
# Example IPv6 output: 2002:c0a8:0101::c0a8:0101 gitlab.example.com

getent hosts localhost
# Example IPv4 output: 127.0.0.1 localhost
# Example IPv6 output: ::1 localhost

如果返回 IPv6 地址格式，请进一步检查网络接口上是否启用了 IPv6 协议支持（关键字 ipv6）：

ip addr # or 'ifconfig' on older operating systems

当 IPv6 网络协议支持不存在或被禁用，但 DNS 配置将主机名解析为 IPv6 地址时，GitLab 服务将无法建立网络连接。

这可以通过修复 DNS 配置（或/etc/hosts）将主机解析为 IPv4 地址而不是 IPv6 来解决。

当 external_url 包含下划线时显示 URI::InvalidComponentError (bad component(expected host component: my_url.tld)

如果你使用下划线设置了 external_url（例如 https://my_company.example.com），您可能会面临以下 CI/CD 问题：

  • 将无法打开项目的 设置 > CI/CD 页面。
  • Runners 将不会选择作业，并且会失败并显示错误 500。

如果是这种情况，production.log 将包含以下错误：

Completed 500 Internal Server Error in 50ms (ActiveRecord: 4.9ms | Elasticsearch: 0.0ms | Allocations: 17672)

URI::InvalidComponentError (bad component(expected host component): my_url.tld):

lib/api/helpers/related_resources_helpers.rb:29:in `expose_url'
ee/app/controllers/ee/projects/settings/ci_cd_controller.rb:19:in `show'
ee/lib/gitlab/ip_address_state.rb:10:in `with'
ee/app/controllers/ee/application_controller.rb:44:in `set_current_ip_address'
app/controllers/application_controller.rb:486:in `set_current_admin'
lib/gitlab/session.rb:11:in `with_session'
app/controllers/application_controller.rb:477:in `set_session_storage'
lib/gitlab/i18n.rb:73:in `with_locale'
lib/gitlab/i18n.rb:79:in `with_user_locale'

作为解决方法，请避免在 external_url 中使用下划线。

升级失败，错误 timeout: run: /opt/gitlab/service/gitaly

如果在运行重新配置时时软件包升级失败并出现以下错误，请检查所有 Gitaly 进程是否已停止，然后重新运行 sudo gitlab-ctl reconfigure。

---- Begin output of /opt/gitlab/embedded/bin/sv restart /opt/gitlab/service/gitaly ----
STDOUT: timeout: run: /opt/gitlab/service/gitaly: (pid 4886) 15030s, got TERM
STDERR:
---- End output of /opt/gitlab/embedded/bin/sv restart /opt/gitlab/service/gitaly ----
Ran /opt/gitlab/embedded/bin/sv restart /opt/gitlab/service/gitaly returned 1

重新安装极狐GitLab 时重新配置卡住

在卸载极狐GitLab 并尝试再次安装后，重新配置过程卡在 ruby_block[wait for logrotate service socket] action run。当卸载极狐GitLab 时未执行其中一个 systemctl 命令时，就会出现此问题。

解决此问题：

  • 确保您遵循卸载极狐GitLab 时的所有步骤，并在必要时执行这些步骤。
  • 可以参考此议题。

Pulp 或 Red Hat Satellite 失败时镜像极狐GitLab yum 仓库

Pulp 或 Red Hat Satellite 在同步时失败，直接镜像位于 https://packages.gitlab.com/gitlab/ 的 Omnibus GitLab yum 仓库。不同软件会引起不同错误：

  • Pulp 2 或 Satellite < 6.10 失败，并出现 "Malformed repository: metadata is specified for different set of packages in filelists.xml and in other.xml" 错误。
  • Satellite 6.10 失败并出现 "pkgid" 错误。
  • Pulp 3 或 Satellite > 6.10 似乎成功，但仅同步仓库元数据。

这些同步失败是由极狐GitLab yum 镜像仓库中的元数据问题引起的。此元数据包括一个 filelists.xml.gz 文件，该文件通常包含仓库中每个 RPM 的文件列表。极狐GitLab yum 仓库将此文件大部分保留为空，以解决文件完全填充时可能导致的大小问题。

每个极狐GitLab RPM 都包含大量文件，当乘以仓库中的大量 RPM 时，如果完全填充，将产生一个巨大的 filelists.xml.gz 文件。由于存储和构建限制，我们创建该文件但不填充。空文件会导致该文件的 Pulp 和 RedHat Satellite（使用 Pulp）仓库镜像失败。

解决该问题

要解决该问题：

  1. 使用替代 RPM 仓库镜像工具（如 reposync 或 createrepo）制作官方极狐GitLab yum 仓库的本地副本。这些工具在本地数据中重新创建仓库元数据，其中包括创建完全填充的 filelists.xml.gz 文件。
  2. 将 Pulp 或 Satellite 指向本地镜像。

本地镜像示例

以下是进行本地镜像的示例。该示例使用：

  • Apache 作为仓库的 Web 服务器。
  • reposync 和 createrepo 将极狐GitLab 仓库同步到本地镜像。该本地镜像可以用作 Pulp 或 RedHat Satellite 的源。您也可以使用其他工具，例如 Cobbler。

在这个例子中：

  • 本地镜像在 RHEL 8、Rocky 8 或 AlmaLinux 8 系统上运行。
  • 用于网络服务器的主机名是 mirror.example.com。
  • Pulp 3 从本地镜像同步。

创建并配置 Apache 服务器

以下示例显示如何安装和配置基本 Apache 2 服务器来托管一个或多个 Yum 仓库镜像。有关配置和保护 Web 服务器的详细信息，请参阅 Apache 文档。

  1. 安装 httpd：

    sudo dnf install httpd

  2. 将 Directory 添加到 /etc/httpd/conf/httpd.conf：

    <Directory “/var/www/html/repos“>
Options All Indexes FollowSymLinks
Require all granted
</Directory>

  3. 完成 httpd 配置：

    sudo rm -f /etc/httpd/conf.d/welcome.conf
sudo mkdir /var/www/html/repos
sudo systemctl enable httpd --now

获取镜像的 Yum 仓库 URL

  1. 安装极狐GitLab 仓库 yum 配置文件：

    curl "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash
sudo dnf config-manager --disable gitlab_gitlab-ee gitlab_gitlab-ee-source

  2. 获取仓库 URL：

    sudo dnf config-manager --dump gitlab_gitlab-ee | grep baseurl
baseurl = https://packages.gitlab.com/gitlab/gitlab-ee/el/8/x86_64

    您使用 baseurl 的内容作为本地镜像的来源。例如 https://packages.gitlab.com/gitlab/gitlab-ee/el/8/x86_64。

创建本地镜像

  1. 安装 createrepo 软件包：

    sudo dnf install createrepo

  2. 运行 reposync 以将 RPM 拷贝到本地镜像：

    sudo dnf reposync --arch x86_64 --repoid=gitlab_gitlab-ee --download-path=/var/www/html/repos --newest-only

--newest-only 选项仅下载最新的 RPM。如果您省略这个选项，将下载仓库中的所有 RPM（每个大约 1 GB）。

  1. 运行 createrepo 重新创建仓库元数据：

    sudo createrepo -o /var/www/html/repos/gitlab_gitlab-ee /var/www/html/repos/gitlab_gitlab-ee

现在应该可以在 http://mirror.example.com/repos/gitlab_gitlab-ee/ 获取本地镜像仓库。

上传本地镜像

您的本地镜像应定期更新，以便在新的极狐GitLab 版本发布时获取新的 RPM。一种方法是使用 cron。

使用以下内容创建 /etc/cron.daily/sync-gitlab-mirror：

#!/bin/sh

dnf reposync --arch x86_64 --repoid=gitlab_gitlab-ee --download-path=/var/www/html/repos --newest-only --delete
createrepo -o /var/www/html/repos/gitlab_gitlab-ee /var/www/html/repos/gitlab_gitlab-ee

dnf reposync 命令中使用的 --delete 选项会删除相应极狐GitLab 仓库中不存在的本地镜像中的 RPM。

使用本地镜像

  1. 创建 Pulp repository 和 remote：

    pulp rpm repository create --retain-package-versions=1 --name "gitlab-ee"
pulp rpm remote create --name gitlab-ee --url "http://mirror.example.com/repos/gitlab_gitlab-ee/" --policy immediate
pulp rpm repository update --name gitlab-ee --remote gitlab-ee

  2. 同步仓库：

    pulp rpm repository sync --name gitlab-ee

必须定期运行此命令，以通过对极狐GitLab 仓库进行更改来更新本地镜像。

仓库同步后，您可以创建发布和分发以使其可用。有关详细信息，请参阅 https://docs.pulpproject.org/pulp_rpm/。