极狐 GitLab Logo

Linux 软件包安装故障排查

  • Tier: 基础版，专业版，旗舰版
  • Offering: 私有化部署

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

下载软件包时哈希和校验不匹配#

apt-get install 输出类似于：

plaintext
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

运行以下命令来修复此问题：

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

另一种解决方法是手动下载软件包，从 JH 软件包 仓库中选择正确的软件包：

shell
curl -LJO "https://packages.gitlab.cn/repository/ubuntu-focal/pool/g/gitlab-jh/gitlab-jh_18.0.2-jh.0_arm64.deb"
dpkg -i gitlab-jh_18.0.2-jh.0_arm64.deb

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

Linux 软件包除了软件包仓库提供签名的元数据外，还使用 GPG 密钥签名。这确保分发给用户的软件包的真实性和完整性。然而，openSUSE 和 SLES 操作系统使用的软件包管理器有时可能会对这些签名发出错误警告，类似于：

plaintext
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 或软件包升级触发了重新配置，产生了类似的错误：

plaintext
1 ================================================================================
2 Recipe Compile Error in /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/default.rb
3 ================================================================================
4
5NoMethodError
6-------------
7undefined method '[]=' for nil:NilClass
8
9Cookbook Trace:
10---------------
11  /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/config.rb:21:in 'from_file'
12  /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/default.rb:26:in 'from_file'
13
14Relevant File Content:

此错误是在 /etc/gitlab/gitlab.rb 配置文件包含无效或不支持的配置时抛出的。仔细检查是否存在拼写错误或配置文件是否包含过时配置。

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

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

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

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

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

邮件未被发送#

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

如果需要，您可以通过在 /etc/gitlab/gitlab.rb 中使用以下设置来修改极狐GitLab 发送的邮件的 'From' 字段：

ruby
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 中进行覆盖，如下所示：

ruby
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 永久设置上下文。针对 RHEL 系列操作系统的 RPM 软件包中已添加了运行时依赖 policycoreutils-python，以确保 semanage 命令可用。

诊断和解决 SELinux 问题#

Linux 软件包检测 /etc/gitlab/gitlab.rb 中的默认路径更改，并应应用正确的文件上下文。

从极狐GitLab 16.10 开始，管理员可以尝试使用 `gitlab-ctl apply-sepolicy` 自动修复 SELinux 问题。有关运行时选项，请参阅 `gitlab-ctl apply-sepolicy --help`。

对于使用自定义数据路径配置的安装，管理员可能需要手动解决 SELinux 问题。

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

例如，如果 /data/gitlab 替换 /var/opt/gitlab 作为基础数据目录，下面的方法可以修复安全上下文：

shell
1sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/.ssh/
2sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/.ssh/authorized_keys
3sudo restorecon -Rv /data/gitlab/
4sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/gitlab-shell/config.yml
5sudo restorecon -Rv /data/gitlab/gitlab-shell/
6sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/gitlab-rails/etc/gitlab_shell_secret
7sudo restorecon -Rv /data/gitlab/gitlab-rails/
8sudo semanage fcontext --list | grep /data/gitlab/

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

shell
ssh -T git@gitlab-hostname

所有系统#

默认情况下，Git 用户在 /etc/shadow 中以锁定密码创建，由 '!' 表示。除非启用了 "UsePam yes"，否则 OpenSSH 守护程序会阻止 Git 用户通过 SSH 密钥进行身份验证。一种安全的替代解决方案是通过将 /etc/shadow 中的 '!' 替换为 '*' 来解锁密码。Git 用户仍然无法更改密码，因为它在受限 shell 中运行，并且非超级用户的 passwd 命令需要输入当前密码才能输入新密码。用户无法输入与 '*' 匹配的密码，这意味着帐户仍然没有密码。

请记住，Git 用户必须能够访问系统，因此请查看 /etc/security/access.conf 中的安全设置，并确保未阻止 Git 用户。

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

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

plaintext
  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.

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

ruby
postgresql['shared_buffers'] = "100MB"

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

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

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

ruby
postgresql['dynamic_shared_memory_type'] = 'none'

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

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

PostgreSQL 有一个设置，用于限制到数据库服务器的最大并发连接数。如果您看到此错误，意味着您的极狐GitLab 实例尝试超出此并发连接数的限制。

要检查最大连接数和可用连接数：

  1. 打开一个 PostgreSQL 数据库控制台：

    shell
    sudo gitlab-psql

  2. 在数据库控制台中执行以下查询：

    sql
    1SELECT
2  (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections,
3  COUNT(*) AS current_connections,
4  COUNT(*) FILTER (WHERE state = 'active') AS active_connections,
5  ((SELECT setting::int FROM pg_settings WHERE name = 'max_connections') - COUNT(*)) AS remaining_connections
6FROM pg_stat_activity;

要解决此问题，您有两个选项：

  • 可以增加最大连接数值：

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

      ruby
      postgresql['max_connections'] = 600

    2. 重新配置极狐GitLab：

      shell
      sudo gitlab-ctl reconfigure

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

重新配置时抱怨 GLIBC 版本#

shell
$ 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)

这可能发生在您安装的 Linux 软件包是为与您的服务器不同的操作系统版本构建时。仔细检查您下载并安装了正确的 Linux 软件包。

重新配置无法创建 Git 用户#

这可能发生在您以 Git 用户身份运行 sudo gitlab-ctl reconfigure。切换到其他用户。

更重要的是：不要给予 Git 用户或 Linux 软件包使用的其他用户 sudo 权限。给予系统用户不必要的权限会削弱您的系统安全性。

使用 sysctl 修改内核参数失败#

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

plaintext
1 * execute[sysctl] action run
2================================================================================
3Error executing action `run` on resource 'execute[sysctl]'
4================================================================================
5
6
7Mixlib::ShellOut::ShellCommandFailed
8------------------------------------
9Expected process to exit with [0], but received '255'
10---- Begin output of /sbin/sysctl -p /etc/sysctl.conf ----

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

忽略错误可能会对极狐GitLab 服务器的性能产生意想不到的副作用，因此不建议这样做。

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

plaintext
1 * execute[load sysctl conf] action run
2    [execute] sysctl: setting key "kernel.shmall": Read-only file system
3              sysctl: setting key "kernel.shmmax": Read-only file system
4
5    ================================================================================
6    Error executing action `run` on resource 'execute[load sysctl conf]'
7    ================================================================================
8
9    Mixlib::ShellOut::ShellCommandFailed
10    ------------------------------------
11    Expected process to exit with [0], but received '255'
12    ---- Begin output of cat /etc/sysctl.conf /etc/sysctl.d/*.conf  | sysctl -e -p - ----
13    STDOUT:
14    STDERR: sysctl: setting key "kernel.shmall": Read-only file system
15    sysctl: setting key "kernel.shmmax": Read-only file system
16    ---- End output of cat /etc/sysctl.conf /etc/sysctl.d/*.conf  | sysctl -e -p - ----
17    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。它应该检测到内核已经在必要的设置下运行，并且不会引发任何错误。

您可能需要为其他行重复此过程。例如，重新配置失败三次之后，您在 /etc/sysctl.conf 中添加了类似的内容：

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

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

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

我无法在没有 root 权限的情况下安装极狐GitLab#

有时人们会问是否可以在没有 root 权限的情况下安装极狐GitLab。由于多个原因，这在某种程度上是有问题的。

安装 .deb 或 .rpm#

据我们所知，没有清晰的方法可以在非特权用户下安装 Debian 或 RPM 软件包。您无法安装 Linux 软件包 RPM，因为构建过程不创建源 RPM。

端口 80 和 443 上的无忧托管#

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

如果这有问题，安装极狐GitLab 的管理员可以禁用捆绑的 NGINX 服务，但这会使他们在应用更新期间保持与极狐GitLab 的 NGINX 配置同步的负担。

服务之间的隔离#

Linux 软件包中的捆绑服务（极狐GitLab 本身、NGINX、PostgreSQL、Redis、Mattermost）通过 Unix 用户帐户相互隔离。创建和管理这些用户帐户需要 root 权限。默认情况下，Linux 软件包在 gitlab-ctl reconfigure 期间创建所需的 Unix 帐户，但该行为可以禁用。

原则上，Linux 软件包只需要 2 个用户帐户（一个用于极狐GitLab，一个用于 Mattermost），如果我们给每个应用程序其自己的 runit（runsvdir）、PostgreSQL 和 Redis 进程。但这将是 gitlab-ctl reconfigure Chef 代码中的一个重大变化，并且可能会为所有现有的 Linux 软件包安装创建重大升级问题。（我们可能需要重新安排 /var/opt/gitlab 下的目录结构。）

调整操作系统以提高性能#

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

gitlab-rake assets:precompile 失败，提示 'Permission denied'#

一些用户报告运行 gitlab-rake assets:precompile 在 Linux 软件包中不起作用。对此的简短回答是：不要运行该命令，它仅适用于从源安装的极狐GitLab。

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

当您从源安装极狐GitLab 时（这是我们拥有 Linux 软件包之前唯一的方法），您必须在每次更新极狐GitLab 时在极狐GitLab 服务器上转换资产。人们过去常常忽略这一步，并且互联网上仍有帖子、评论和邮件，用户建议彼此运行 rake assets:precompile（现已重命名为 gitlab:assets:compile）。使用 Linux 软件包情况有所不同。当我们构建软件包时，我们为您编译资产。当您使用 Linux 软件包安装极狐GitLab 时，转换后的资产已经存在！这就是为什么您在从软件包安装极狐GitLab 时不需要运行 rake assets:precompile。

当 gitlab-rake assets:precompile 因权限错误而失败时，从安全角度来看，它失败的原因是合理的：资产不能轻易地被重写，这使得攻击者更难以使用您的极狐GitLab 服务器向您的极狐GitLab 服务器的访问者提供恶意 JavaScript 代码。

如果您想运行极狐GitLab 并使用自定义 JavaScript 或 CSS 代码，您可能更适合从源运行极狐GitLab，或者构建自己的软件包。

如果您确实知道自己在做什么，可以这样执行 gitlab-rake gitlab:assets:compile：

shell
sudo NO_PRIVILEGE_DROP=true USE_DB=false gitlab-rake gitlab:assets:clean gitlab:assets:compile
# user 和 path 可能会有所不同，如果您更改了 gitlab.rb 中 user['username']、user['group'] 和 gitlab_rails['dir'] 的默认值
sudo chown -R git:git /var/opt/gitlab/gitlab-rails/tmp/cache

'Short read or OOM loading DB' 错误#

尝试清理旧的 Redis 会话。

Apt 错误 '请求的 URL 返回错误：403'#

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

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

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

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

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

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

当极狐GitLab 尝试与内部服务（如极狐GitLab Shell）连接时。

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

错误：proxyRoundTripper: XXX failed with: "net/http: timeout awaiting response headers"#

如果极狐GitLab 工作马在默认情况下未在 1 分钟内收到来自极狐GitLab 的回复，则会显示一个 502 页面。

请求可能超时的原因有很多，比如用户在加载非常大的 diff 或类似内容。

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

ruby
gitlab_workhorse['proxy_headers_timeout'] = "2m0s"

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

您想要的更改被拒绝#

很可能您在一个代理在极狐GitLab 前面的环境中设置了极狐GitLab，并且包中默认设置的代理头在您的环境中不正确。

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

无法验证 CSRF 令牌的真实性，已完成 422 无法处理#

很可能您在一个代理在极狐GitLab 前面的环境中设置了极狐GitLab，并且包中默认设置的代理头在您的环境中不正确。

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

缺少扩展 pg_trgm#

极狐GitLab 需要 PostgreSQL 扩展 pg_trgm。如果您使用的是带捆绑数据库的 Linux 软件包，则在升级时应该会自动启用该扩展。

然而，如果您使用的是外部（非打包）数据库，则需要手动启用该扩展。其原因是 Linux 软件包实例无法确认扩展是否存在，并且也没有办法启用该扩展。

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

shell
sudo apt-get install postgresql-contrib

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

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

    shell
    sudo gitlab-psql -d gitlabhq_production

  2. 启用扩展：

    plaintext
    CREATE EXTENSION pg_trgm;
\q

  3. 现在再次运行迁移：

    shell
    sudo gitlab-rake db:migrate

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

  1. 访问容器：

    shell
    docker exec -it gitlab bash

  2. 运行上述命令

  3. 重启容器：

    shell
    docker restart gitlab

Errno::ENOMEM: 备份或升级期间无法分配内存#

极狐GitLab 需要 2GB 可用内存才能正常运行。如果极狐GitLab 在不升级或运行备份时运行良好，则增加交换空间应该可以解决您的问题。如果您看到服务器在正常使用期间使用交换空间，可以添加更多 RAM 来提高性能。

NGINX 错误：'无法构建 server_names_hash，您应该增加 server_names_hash_bucket_size'#

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

ruby
nginx['server_names_hash_bucket_size'] = 128

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

由于 NFS root_squash，重新配置失败，提示“'root' cannot chown”#

shell
1$ gitlab-ctl reconfigure
2
3================================================================================
4Error executing action `run` on resource 'ruby_block[directory resource: /gitlab-data/git-data]'
5================================================================================
6
7Errno::EPERM
8------------
9'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.
10Operation not permitted @ chown_internal - /gitlab-data/git-data

这可能发生在您有使用 NFS 挂载的目录并在 'root_squash' 模式下配置时。重新配置无法正确设置目录的所有权。您需要在 NFS 服务器上切换到使用 no_root_squash 在您的 NFS 导出中，或者禁用存储目录管理并自行管理权限。

gitlab-runsvdir 未启动#

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

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

shell
systemctl -t target

如果一切正常，输出应显示如下内容：

plaintext
1UNIT                   LOAD   ACTIVE SUB    DESCRIPTION
2basic.target           loaded active active Basic System
3cloud-config.target    loaded active active Cloud-config availability
4cloud-init.target      loaded active active Cloud-init target
5cryptsetup.target      loaded active active Encrypted Volumes
6getty.target           loaded active active Login Prompts
7graphical.target       loaded active active Graphical Interface
8local-fs-pre.target    loaded active active Local File Systems (Pre)
9local-fs.target        loaded active active Local File Systems
10multi-user.target      loaded active active Multi-User System
11network-online.target  loaded active active Network is Online
12network-pre.target     loaded active active Network (Pre)
13network.target         loaded active active Network
14nss-user-lookup.target loaded active active User and Group Name Lookups
15paths.target           loaded active active Paths
16remote-fs-pre.target   loaded active active Remote File Systems (Pre)
17remote-fs.target       loaded active active Remote File Systems
18slices.target          loaded active active Slices
19sockets.target         loaded active active Sockets
20swap.target            loaded active active Swap
21sysinit.target         loaded active active System Initialization
22time-sync.target       loaded active active System Time Synchronized
23timers.target          loaded active active Timers
24
25LOAD   = 反映单元定义是否正确加载。
26ACTIVE = 高级单元激活状态，即 SUB 的泛化。
27SUB    = 低级单元激活状态，值取决于单元类型。
28
29列出了 22 个加载的单元。传递 --all 以查看加载但不活跃的单元。
30要查看所有安装的单元文件，请使用 'systemctl list-unit-files'。

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

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

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

shell
systemctl list-jobs

如果您看到一个 running 作业，则可能有一个服务卡住，从而阻止极狐GitLab 启动。例如，一些用户在 Plymouth 启动时遇到了问题：

plaintext
1  1 graphical.target                     start waiting
2107 plymouth-quit-wait.service           start running
3  2 multi-user.target                    start waiting
4169 ureadahead-stop.timer                start waiting
5121 gitlab-runsvdir.service              start waiting
6151 system-getty.slice                   start waiting
7 31 setvtrgb.service                     start waiting
8122 systemd-update-utmp-runlevel.service start waiting

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

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

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

ruby
package['detect_init'] = false

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

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

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

极狐GitLab systemd 单元文件默认使用 multi-user.target 作为 After 和 WantedBy 字段。这是为了确保服务在 remote-fs 和 network 目标之后运行，从而极狐GitLab 可以正常工作。

然而，这与 cloud-init 的单元排序不良交互，该排序由 AWS Cloudformation 使用。

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

shell
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 地址：

shell
1getent hosts gitlab.example.com
2# 示例 IPv4 输出：192.168.1.1 gitlab.example.com
3# 示例 IPv6 输出：2002:c0a8:0101::c0a8:0101 gitlab.example.com
4
5getent hosts localhost
6# 示例 IPv4 输出：127.0.0.1 localhost
7# 示例 IPv6 输出：::1 localhost

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

shell
ip addr # 或在较旧的操作系统上使用 'ifconfig'

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

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

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

如果您在 external_url 中设置了下划线（例如 https://my_company.example.com），可能会在 CI/CD 中遇到以下问题：

  • 无法打开项目的 设置 > CI/CD 页面。
  • Runner 将无法接受作业并将失败，出现错误 500。

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

plaintext
1Completed 500 Internal Server Error in 50ms (ActiveRecord: 4.9ms | Elasticsearch: 0.0ms | Allocations: 17672)
2
3URI::InvalidComponentError (bad component(expected host component): my_url.tld):
4
5lib/api/helpers/related_resources_helpers.rb:29:in `expose_url'
6ee/app/controllers/ee/projects/settings/ci_cd_controller.rb:19:in `show'
7ee/lib/gitlab/ip_address_state.rb:10:in `with'
8ee/app/controllers/ee/application_controller.rb:44:in `set_current_ip_address'
9app/controllers/application_controller.rb:486:in `set_current_admin'
10lib/gitlab/session.rb:11:in `with_session'
11app/controllers/application_controller.rb:477:in `set_session_storage'
12lib/gitlab/i18n.rb:73:in `with_locale'
13lib/gitlab/i18n.rb:79:in `with_user_locale'

作为一种解决方法，避免在 external_url 中使用下划线。对此有一个开放问题：设置 external_url 带有下划线导致极狐GitLab CI/CD 功能损坏。

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

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

plaintext
---- 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.cn 的 Linux 软件包 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 和使用 Pulp 的 RedHat Satellite 的存储库镜像失败。

解决问题的变通方法#

要解决这个问题：

  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 系统上。
  • 用于 Web 服务器的主机名是 mirror.example.com。
  • Pulp 3 从本地镜像同步。
  • 镜像的是 极狐GitLab 企业版存储库。

创建和配置 Apache 服务器#

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

  1. 安装 httpd：

    shell
    sudo dnf install httpd

  2. 在 /etc/httpd/conf/httpd.conf 中添加一个 Directory 段：

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

  3. 完成 httpd 配置：

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

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

  2. 获取存储库 URL：

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

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

创建本地镜像#

  1. 安装 createrepo 软件包：

    shell
    sudo dnf install createrepo

  2. 运行 reposync 将 RPM 复制到本地镜像：

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

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

  3. 运行 createrepo 重新创建存储库元数据：

    shell
    sudo createrepo -o /var/www/html/repos/gitlab_gitlab-jh /var/www/html/repos/gitlab_gitlab-jh

本地镜像存储库现在应可用，地址为 http://mirror.example.com/repos/gitlab_gitlab-jh/。

更新本地镜像#

您的本地镜像应定期更新以获取新的 RPM，因为新的极狐GitLab 版本会发布。可以使用 cron 来实现这一点。

创建 /etc/cron.daily/sync-gitlab-mirror 文件，内容如下：

shell
#!/bin/sh

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

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

使用本地镜像#

  1. 创建 Pulp repository 和 remote：

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

  2. 同步存储库：

    shell
    pulp rpm repository sync --name gitlab-jh

    必须定期运行此命令，以便用极狐GitLab 存储库的更改来更新本地镜像。

错误：E: connection refused to d20rj4el6vkp4c.cloudfront.net 443#

当您安装托管在 packages.gitlab.com 上的软件包时，您的客户端将接收并跟随重定向到 CloudFront 地址 d20rj4el6vkp4c.cloudfront.net。在隔离网络环境中的服务器可能会收到以下错误：

shell
E: connection refused to d20rj4el6vkp4c.cloudfront.net 443
shell
Failed to connect to d20rj4el6vkp4c.cloudfront.net port 443: Connection refused

要解决此问题，您有三个选项：

  1. 如果可以按域名进行白名单设置，将端点 d20rj4el6vkp4c.cloudfront.net 添加到您的防火墙设置中。
  2. 如果不能按域名进行白名单设置，将 CloudFront IP 地址范围添加到您的防火墙设置中。您必须保持此列表与您的防火墙设置同步，因为它们可能会更改。
  3. 手动下载软件包文件并上传到您的服务器。

我是否需要增加 net.core.somaxconn ？#

以下内容可能有助于识别 net.core.somaxconn 的值是否设置得太低：

shell
$ netstat -ant | grep -c SYN_RECV
4

netstat -ant | grep -c SYN_RECV 的返回值是等待建立的连接数。如果该值大于 net.core.somaxconn：

shell
$ sysctl net.core.somaxconn
net.core.somaxconn = 1024

您可能会遇到超时或 HTTP 502 错误，建议通过更新 gitlab.rb 中的 puma['somaxconn'] 变量来增加此值。

exec request failed on channel 0 或 shell request failed on channel 0 错误#

当使用 Git 通过 SSH 拉取或推送时，您可能会看到以下错误：

  • exec request failed on channel 0
  • shell request failed on channel 0

如果 git 用户的进程数量超过限制，则可能会发生这些错误。

要尝试解决此问题：

  1. 在运行 gitlab-shell 的节点上的 /etc/security/limits.conf 文件中增加 git 用户的 nproc 设置。通常，gitlab-shell 运行在极狐GitLab Rails 节点上。
  2. 重试 Git 拉取或推送命令。

SSH 连接丢失后安装挂起#

如果您在远程虚拟机上安装极狐GitLab 且 SSH 连接丢失，安装可能会挂起并出现僵尸 dpkg 进程。要恢复安装：

  1. 运行 top 找到关联的 apt 进程的进程 ID，这是 dpkg 进程的父进程。
  2. 运行 sudo kill <PROCESS_ID> 终止 apt 进程。
  3. 仅在全新安装时，运行 sudo gitlab-ctl cleanse。此步骤会擦除现有数据，因此在升级时不得使用。
  4. 运行 sudo dpkg configure -a。
  5. 编辑 gitlab.rb 文件以包含所需的外部 URL 和可能缺失的任何其他配置。
  6. 运行 sudo gitlab-ctl reconfigure。

重新配置极狐GitLab 时的 Redis 相关错误#

您可能会在重新配置极狐GitLab 时遇到以下错误：

plaintext
RuntimeError: redis_service[redis] (redis::enable line 19) had an error: RuntimeError: ruby_block[warn pending redis restart] (redis::enable line 77) had an error: RuntimeError: Execution of the command /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket INFO failed with a non-zero exit code (1)

错误消息表明 Redis 可能在尝试与 redis-cli 建立连接时重新启动或关闭。由于该脚本运行 gitlab-ctl restart redis 并尝试立即检查版本，可能会导致竞争条件而引发错误。

要解决此问题，运行以下命令：

shell
sudo gitlab-ctl reconfigure

如果失败，请检查 gitlab-ctl tail redis 的输出并尝试运行 redis-cli。