• 配置外部 URL
  • 在安装时指定外部 URL
• 配置相对 URL
• 从非 root 用户加载外部配置文件
• 将 Git 数据存储在备用目录中
• 更改 Git 用户/组的名称
• 指定数字化的用户和组标识符
• 禁用用户和组帐户管理
• 移动用户的主目录
• 禁用存储目录管理
  • 禁用 /etc/gitlab 目录管理
  • 禁用 /var/opt/gitlab 目录管理
• 仅在挂载给定文件系统后启动 Omnibus GitLab 服务
• 配置运行时目录
• 配置失败的身份验证禁令
• 在安装过程中禁用自动缓存清理
• 使用 Sentry 进行错误报告和记录
• 设置内容交付网络（CDN） URL
• 设置 Content Security Policy
• 在安装时设置初始 root 密码
• 设置允许的主机以防止 host header 攻击
• 故障排查
  • Mixlib::ShellOut::ShellCommandFailed: linux_user[GitLab user and group]

极狐GitLab Linux 软件包的配置选项

要配置极狐GitLab，请在 /etc/gitlab/gitlab.rb 文件中设置相关选项。

gitlab.rb.template 包含可用选项的完整列表。新安装默认具有 /etc/gitlab/gitlab.rb 中列出的模板的所有选项。

配置外部 URL

要向您的用户显示正确的仓库克隆链接，您必须向极狐GitLab 提供您的用户用来访问仓库的 URL。 您可以使用服务器的 IP，但首选完全限定域名 (FQDN)。有关在自助管理实例中使用 DNS 的更多详细信息，请参阅 DNS 文档。

要更改外部 URL：

1. 可选。在更改外部 URL 之前，请确定您之前是否自定义了 主页 URL 或 注销后路径。 在配置新的外部 URL 后，这两个设置都可能导致意外重定向。如果您定义了任何 URL，请将它们完全删除。

2. 编辑 /etc/gitlab/gitlab.rb 并将 external_url 更改为您的首选 URL：

   external_url "http://gitlab.example.com"
   

   或者，您可以使用服务器的 IP 地址：

   external_url "http://10.0.0.1"
   

   在前面的示例中，我们使用 HTTP。如果您想使用 HTTPS，请参阅如何配置 SSL。

3. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

4. 可选。如果您已经使用极狐GitLab 一段时间，在更改外部 URL 后，您还应该使 Markdown 缓存无效。

在安装时指定外部 URL

如果您使用 GitLab Linux 软件包，您可以使用 EXTERNAL_URL 环境变量以最少的命令数设置极狐GitLab 实例。 如果设置了这个变量，它会被自动检测到，并且它的值被写为 gitlab.rb 文件中的 external_url。

EXTERNAL_URL 环境变量仅影响软件包的安装和升级。对于常规的重新配置运行，使用 /etc/gitlab/gitlab.rb 中的值。

作为包更新的一部分，如果您无意中设置了 EXTERNAL_URL 变量，它将替换 /etc/gitlab/gitlab.rb 中的现有值，而不会发出任何警告。因此，我们建议不要全局设置变量，而是专门将其传递给安装命令：

sudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ee

配置相对 URL

虽然我们建议在自己的（子）域名下安装极狐GitLab，但有时这是不可能的。在这种情况下，极狐GitLab 也可以安装在相对 URL 下，例如，https://example.com/gitlab。

通过更改 URL，所有远端 URL 也会更改，因此您必须在指向极狐GitLab 实例的任何本地仓库中手动编辑它们。

要启用相对 URL：

1. 在 /etc/gitlab/gitlab.rb 中设置 external_url：

   external_url "https://example.com/gitlab"
   

   在这个例子中，提供给极狐GitLab 使用的相对 URL 是 /gitlab。根据您的喜好更改它。

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

从非 root 用户加载外部配置文件

Omnibus GitLab 包从 /etc/gitlab/gitlab.rb 文件加载所有配置。 该文件具有严格的文件权限，归 root 用户所有。严格权限和所有权的原因是，/etc/gitlab/gitlab.rb 在 gitlab-ctl reconfigure 期间由 root 用户作为 Ruby 代码执行。这意味着 /etc/gitlab/gitlab.rb 具有写入权限的用户，可以添加由 root 作为代码执行的配置。

在某些组织中，允许访问配置文件，但不能以 root 用户身份访问。 您可以通过指定文件的路径在 /etc/gitlab/gitlab.rb 中包含外部配置文件：

from_file "/home/admin/external_gitlab.rb"

当您运行 sudo gitlab-ctl reconfigure 时，使用 from_file 包含在 /etc/gitlab/gitlab.rb 中的代码，以 root 权限运行。 在包含 from_file 之后，在 /etc/gitlab/gitlab.rb 中设置的任何配置都优先于包含文件中的配置。

将 Git 数据存储在备用目录中

默认情况下，Omnibus GitLab 将 Git 存储库数据存储在 /var/opt/gitlab/git-data 下。仓库存储在名为 repositories 的子文件夹中。

要更改 git-data 父目录的位置：

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

   git_data_dirs({ "default" => { "path" => "/mnt/nas/git-data" } })
   

   您还可以添加多个 Git 数据目录：

   git_data_dirs({
     "default" => { "path" => "/var/opt/gitlab/git-data" },
     "alternative" => { "path" => "/mnt/nas/git-data" }
   })
   

   目标目录及其任何子路径不得是软链接（symlink）。

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

3. 可选。如果您已经在 /var/opt/gitlab/git-data 中有现有的 Git 仓库，则可以将它们移动到新位置：

   1. 在您移动用户时，阻止用户写入仓库：

      sudo gitlab-ctl stop
      

   2. 将仓库同步到新位置。注意 repositories 后面没有斜线，但 git-data 后面有斜线：

      sudo rsync -av --delete /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/
      

   3. 重新配置以启动必要的进程并修复任何错误的权限：

      sudo gitlab-ctl reconfigure
      

   4. 仔细检查 /mnt/nas/git-data/ 中的目录布局。预期的输出应该是 repositories：

      sudo ls /mnt/nas/git-data/
      

   5. 启动极狐GitLab 并验证您是否可以在 Web 界面中浏览仓库：

      sudo gitlab-ctl start
      

如果您在自己的服务器上运行 Gitaly，请记住还包括每个 Git 数据目录的 gitaly_address。

更改 Git 用户/组的名称

默认情况下，Omnibus GitLab 使用用户名 git 进行 GitLab Shell 登录、Git 数据本身的所有权以及 Web 界面上的 SSH URL 生成。 同样，git 组用于 Git 数据的组所有权。

要更改用户和组：

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

   user['username'] = "gitlab"
   user['group'] = "gitlab"
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

如果您要更改现有安装的用户名，则重新配置运行不会更改嵌套目录的所有权，因此您必须手动执行此操作。 确保新用户可以访问 repositories 和 uploads 目录。

指定数字化的用户和组标识符

Omnibus GitLab 为极狐GitLab、PostgreSQL、Redis、NGINX 等创建用户。要为这些用户指定数字标识符：

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

   user['uid'] = 1234
   user['gid'] = 1234
   postgresql['uid'] = 1235
   postgresql['gid'] = 1235
   redis['uid'] = 1236
   redis['gid'] = 1236
   web_server['uid'] = 1237
   web_server['gid'] = 1237
   registry['uid'] = 1238
   registry['gid'] = 1238
   mattermost['uid'] = 1239
   mattermost['gid'] = 1239
   prometheus['uid'] = 1240
   prometheus['gid'] = 1240
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

3. 可选的。 如果您要更改 user['uid'] 和 user['gid']，请确保更新任何非 Omnibus 直接管理的文件的 uid/guid，例如日志：

find /var/log/gitlab -uid <old_uid> | xargs -I:: chown git ::
find /var/log/gitlab -gid <old_uid> | xargs -I:: chgrp git ::
find /var/opt/gitlab -uid <old_uid> | xargs -I:: chown git ::
find /var/opt/gitlab -gid <old_uid> | xargs -I:: chgrp git ::

禁用用户和组帐户管理

默认情况下，Omnibus GitLab 创建系统用户和组帐户，并保持信息更新。 这些系统帐户运行包的各种组件。 大多数用户不需要更改。 但是，如果您的系统帐户由其他软件管理，例如 LDAP，您可能需要禁用由 GitLab 包完成的帐户管理。

默认情况下，Omnibus GitLab 包要求存在以下用户和组：

要禁用用户和组帐户管理：

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

   manage_accounts['enable'] = false
   

2. 可选的。 您也可以使用不同的用户/组名称，但您必须指定用户/组详细信息：

   # GitLab
   user['username'] = "custom-gitlab"
   user['group'] = "custom-gitlab"
   user['shell'] = "/bin/sh"
   user['home'] = "/var/opt/custom-gitlab"
   
   # Web server
   web_server['username'] = 'webserver-gitlab'
   web_server['group'] = 'webserver-gitlab'
   web_server['shell'] = '/bin/false'
   web_server['home'] = '/var/opt/gitlab/webserver'
   
   # Postgresql (not needed when using external Postgresql)
   postgresql['username'] = "postgres-gitlab"
   postgresql['group'] = "postgres-gitlab"
   postgresql['shell'] = "/bin/sh"
   postgresql['home'] = "/var/opt/postgres-gitlab"
   
   # Redis (not needed when using external Redis)
   redis['username'] = "redis-gitlab"
   redis['group'] = "redis-gitlab"
   redis['shell'] = "/bin/false"
   redis['home'] = "/var/opt/redis-gitlab"
   
   # And so on for users/groups for GitLab Mattermost
   

3. 重新配置极狐GitLab:

   sudo gitlab-ctl reconfigure
   

移动用户的主目录

对于 GitLab 用户，建议将 home 目录设置在本地磁盘（非 NFS）中以获得更好的性能。在 NFS 中设置时，Git 请求将需要发出另一个网络请求来读取 Git 配置，并且会增加 Git 操作的延迟。

要移动现有的主目录，需要停止 GitLab 服务并且需要一些停机时间。

1. 停止 GitLab：

   gitlab-ctl stop
   

2. 停止 runit 服务器：

   sudo systemctl stop gitlab-runsvdir
   

3. 更改主目录：

   usermod -d /path/to/home <username>
   

   如果您有现有数据，则需要手动将其复制/同步到这些新位置。

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

   user['home'] = "/var/opt/custom-gitlab"
   

5. 启动 runit 服务器：

   sudo systemctl start gitlab-runsvdir
   

6. 重新配置极狐GitLab:

   sudo gitlab-ctl reconfigure
   

禁用存储目录管理

Omnibus GitLab 包负责创建具有正确所有权和权限的所有必要目录，并保持更新。

一些目录包含大量数据，因此在某些设置中，这些目录很可能安装在 NFS（或其他）共享上。

某些类型的挂载不允许 root 用户（初始设置的默认用户）自动创建目录，例如在共享上启用了 root_squash 的 NFS。为了解决这个问题，Omnibus GitLab 包尝试使用目录的所有者用户创建这些目录。

禁用 /etc/gitlab 目录管理

如果您挂载了/etc/gitlab目录，你可以关闭该目录的管理：

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

   manage_storage_directories['manage_etc'] = false
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

禁用 /var/opt/gitlab 目录管理

如果要挂载所有 GitLab 存储目录，每个目录都在单独的挂载上，则应完全禁用存储目录的管理。

Omnibus GitLab 包要求这些目录存在于文件系统中。如果配置了此设置，则由您来创建和设置正确的权限。

启用此设置可防止创建以下目录：

要禁用存储目录的管理：

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

   manage_storage_directories['enable'] = false
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

仅在挂载给定文件系统后启动 Omnibus GitLab 服务

如果您想在挂载给定文件系统之前阻止 Omnibus GitLab 服务（NGINX、Redis、Puma 等）启动：

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

   # wait for /var/opt/gitlab to be mounted
   high_availability['mountpoint'] = '/var/opt/gitlab'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

配置运行时目录

启用 Prometheus 监控后，GitLab Exporter 会对每个 Puma 进程（Rails 指标）进行测量。每个 Puma 进程都需要为每个控制器请求，将指标文件写入临时位置。 然后 Prometheus 收集所有这些文件并处理它们的值。

为了避免创建磁盘 I/O，Omnibus GitLab 包使用运行时目录。

在 reconfigure 期间，包检查 /run 是否是 tmpfs 挂载。 如果不是，则会显示以下警告并禁用 Rails 指标：

Runtime directory '/run' is not a tmpfs mount.

再次启用 Rails 指标：

1. 编辑 /etc/gitlab/gitlab.rb 以创建 tmpfs 挂载（注意配置中没有 =）：

   runtime_dir '/path/to/tmpfs'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

配置失败的身份验证禁令

您可以为 Git 和容器镜像库配置失败的身份验证禁令：

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

   gitlab_rails['rack_attack_git_basic_auth'] = {
     'enabled' => true,
     'ip_whitelist' => ["127.0.0.1"],
     'maxretry' => 10, # Limit the number of Git HTTP authentication attempts per IP
     'findtime' => 60, # Reset the auth attempt counter per IP after 60 seconds
     'bantime' => 3600 # Ban an IP for one hour (3600s) after too many auth attempts
   }
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

可以配置以下设置：

• enabled：默认设置为 false。将此设置为 true 以启用 Rack Attack。
• ip_whitelist：不阻止的 IP。它们必须格式化为 Ruby 数组中的字符串。支持 CIDR 表示法，例如，["127.0.0.1", "127.0.0.2", "127.0.0.3", "192.168.0.1/24"]。
• maxretry：在指定时间内可以发出请求的最大次数。
• findtime：在将 IP 添加到拒绝名单之前，失败的请求可以计入 IP 的最长时间（以秒为单位）。
• bantime：IP 被阻止的总时间（以秒为单位）。

在安装过程中禁用自动缓存清理

如果您有大型极狐GitLab 安装实例，您可能不想运行 rake cache:clear 任务，因为它可能需要很长时间才能完成。默认情况下，缓存清除任务在重新配置期间自动运行。

要在安装期间禁用自动缓存清理：

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

   # This is an advanced feature used by large gitlab deployments where loading
   # whole RAILS env takes a lot of time.
   gitlab_rails['rake_cache_clear'] = false
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

使用 Sentry 进行错误报告和记录

Sentry 是一个错误报告和日志记录工具，可用作 SaaS 或内部部署。它是开源的，您可以浏览它的源代码 存储库。

配置 Sentry：

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

   gitlab_rails['sentry_enabled'] = true
   gitlab_rails['sentry_dsn'] = 'https://<key>@sentry.io/<project>'
   gitlab_rails['sentry_clientside_dsn'] = 'https://<key>@sentry.io/<project>'
   gitlab_rails['sentry_environment'] = 'production'
   

   Sentry 环境 可用于跨多个已部署的极狐GitLab 环境（例如实验室、开发、staging、生产）跟踪错误和问题。

2. 可选的。要在从特定服务器发送的每个事件上设置自定义 Sentry 标签，可以设置 GITLAB_SENTRY_EXTRA_TAGS 环境变量。这个变量是一个 JSON 编码的散列，表示应该为来自该服务器的所有异常传递给 Sentry 的任何标签。

   对于实例，设置：

   gitlab_rails['env'] = {
     'GITLAB_SENTRY_EXTRA_TAGS' => '{"stage": "main"}'
   }
   

   将添加值为 main 的 stage 标签。

3. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

设置内容交付网络（CDN） URL

使用 gitlab_rails['cdn_host'] 为内容交付网络 (CDN) 或 asset 主机，提供静态 asset，将会配置一个 Rails asset 主机。

设置 CDN/asset 主机：

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

   gitlab_rails['cdn_host'] = 'https://mycdnsubdomain.fictional-cdn.com'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

设置 Content Security Policy

设置内容安全策略 (CSP) 可以帮助阻止 JavaScript 跨站点脚本 (XSS) 攻击。有关更多详细信息，请参阅关于 CSP 的 Mozilla 文档。

添加 CSP：

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

   gitlab_rails['content_security_policy'] = {
       enabled: true,
       report_only: false
   }
   

   极狐GitLab 自动为 CSP 提供安全的默认值。 为指令明确设置 <default_value> 值，等同于不设置值并将使用默认值。

   添加自定义 CSP：

   gitlab_rails['content_security_policy'] = {
       enabled: true,
       report_only: false,
       directives: {
         default_src: "'none'",
         script_src: "https://example.com"
       }
   }
   

   在 14.9 及更高版本中，安全默认值用于未明确配置的指令。

   要取消设置 CSP 指令，请将值设置为 false。

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

在安装时设置初始 root 密码

管理员用户 root 的初始密码可以在安装时使用 GITLAB_ROOT_PASSWORD 环境变量设置：

sudo GITLAB_ROOT_PASSWORD="<strongpassword>" EXTERNAL_URL="http://gitlab.example.com" apt install gitlab-ee

设置允许的主机以防止 host header 攻击

为了防止极狐GitLab 接受与预期不同的主机头：

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

   gitlab_rails['allowed_hosts'] = ['gitlab.example.com']
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

极狐GitLab 中没有因未配置 allowed_hosts 导致的已知安全问题，但建议深入防御潜在的 HTTP host header 攻击。

如果使用自定义外部代理（例如 apache），则可能需要添加 localhost。管理员应向外部代理添加过滤器，以减轻通过代理传递给 workhorse 的潜在 HTTP Host header 攻击。

gitlab_rails['allowed_hosts'] = ['gitlab.example.com', '127.0.0.1']

故障排查

Mixlib::ShellOut::ShellCommandFailed: linux_user[GitLab user and group]

为用户移动主目录时，如果没有停止 runit 服务，也没有手动为用户移动主目录，极狐GitLab 在重新配置时会遇到错误：

account[GitLab user and group] (gitlab::users line 28) had an error: Mixlib::ShellOut::ShellCommandFailed: linux_user[GitLab user and group] (/opt/gitlab/embedded/cookbooks/cache/cookbooks/package/resources/account.rb line 51) had an error: Mixlib::ShellOut::ShellCommandFailed: Expected process to exit with [0], but received '8'
---- Begin output of ["usermod", "-d", "/var/opt/gitlab", "git"] ----
STDOUT:
STDERR: usermod: user git is currently used by process 1234
---- End output of ["usermod", "-d", "/var/opt/gitlab", "git"] ----
Ran ["usermod", "-d", "/var/opt/gitlab", "git"] returned 8

确保在移动主目录之前停止 runit。