• 配置外部 URL
  • 在安装时指定外部 URL
• 配置相对 URL
  • 启用相对 URL
  • 禁用相对 URL
• 从非 root 用户加载外部配置文件
• 将 Git 数据存储在备用目录中
• 更改 Git 用户/组的名称
• 指定数字化的用户和组标识符
• 禁用用户和组账号管理
  • 移动用户的主目录
• 禁用存储目录管理
• 仅在挂载给定文件系统后启动 Omnibus GitLab 服务
• 配置运行时目录
• 配置失败的身份验证禁令
• 在安装过程中禁用自动缓存清理
• 禁用模拟
• 使用 Sentry 报告和记录错误
• 内容安全策略
• 在安装时设置初始 root 密码
• 设置允许的主机以防止 host header 攻击
• 设置 LDAP 登录
• Smartcard 认证
• 启用 HTTPS
  • 重定向 HTTP 请求到 HTTPS
  • 更改默认端口和 ssl 证书位置
• 使用非打包的网络服务器
• 使用非打包的 PostgreSQL 数据库管理服务器
• 将 ENV 变量添加到 GitLab 运行时环境
• 更改 GitLab.yml 设置
• 通过 SMTP 发送应用邮件
• 调整 Puma 设置
• 设置 NGINX 监听地址
• 将自定义 NGINX 设置插入 GitLab 服务器块
• 将自定义设置插入 NGINX 配置
• 启用 nginx_status

配置选项

通过在 /etc/gitlab/gitlab.rb 中设置相关选项来进行配置。 查看 package defaults 获取默认设置列表并访问 gitlab.rb.template以获取可用选项的完整列表。 新安装的实例默认情况下将具有在 /etc/gitlab/gitlab.rb 中列出的模板的所有选项。

配置外部 URL

为了让 GitLab 向您的用户显示正确的仓库克隆链接，它需要知道您的用户访问它的 URL，例如 http://gitlab.example.com。在 /etc/gitlab/gitlab.rb 中添加或编辑以下行：

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

要使更改生效，请运行：

sudo gitlab-ctl reconfigure

有关在自我管理的 GitLab 实例中使用 DNS 的更多详细信息，请参阅我们的 DNS 文档。

在安装时指定外部 URL

为了使用最少的命令更容易地启动和运行 GitLab 实例，omnibus-gitlab 支持在包安装期间使用环境变量 EXTERNAL_URL。 在检测到此环境变量的存在时，它的值将作为包安装（或升级）的一部分写入 gitlab.rb 文件中的 external_url。

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

配置相对 URL

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

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

启用相对 URL

按照以下步骤在 GitLab 中启用相对 URL：

1. （可选）如果资源不足，可以使用以下命令关闭 Puma 和 Sidekiq，从而暂时释放一些内存：

   sudo gitlab-ctl stop puma
   sudo gitlab-ctl stop sidekiq
   

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

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

   在这个例子中，提供的相对 URL 将是 /gitlab。根据自己的喜好更改它。

3. 重新配置 GitLab 以使更改生效：

   sudo gitlab-ctl reconfigure
   

4. 重新启动服务，以便 Sidekiq 接收更改

   sudo gitlab-ctl restart
   

禁用相对 URL

要禁用相对 URL，请按照与上述相同的步骤操作，并将 external_url 设置为不包含相对路径的 URL。

从非 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 时，/etc/gitlab/gitlab.rb 中包含的使用 from_file 的代码将以 root 权限运行。 在 /etc/gitlab/gitlab.rb 中，在 from_file 之后设置的任何配置都将优先于包含文件中的配置。

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

默认情况下，Omnibus GitLab 将 Git 仓库数据存储在 /var/opt/gitlab/git-data 下。 仓库存储在子文件夹 repositories 中。您可以通过将以下行添加到 /etc/gitlab/gitlab.rb 来更改 git-data 父目录的位置。

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

您还可以通过将以下几行添加到 /etc/gitlab/gitlab.rb 来添加多个 Git 数据目录。

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

如果您在自己的服务器上运行 Gitaly，请记住每个 Git 数据目录还应包含 gitaly_address。请参阅有关配置 Gitaly 的文档。

请注意，目标目录及其任何子路径不能是软链接。

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

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

# Prevent users from writing to the repositories while you move them.
sudo gitlab-ctl stop

# Note there is _no_ slash behind 'repositories', but there _is_ a
# slash behind 'git-data'.
sudo rsync -av --delete /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/

# Start the necessary processes and run reconfigure to fix permissions
# if necessary
sudo gitlab-ctl reconfigure

# Double-check directory layout in /mnt/nas/git-data. Expected output:
# repositories
sudo ls /mnt/nas/git-data/

# Done! Start GitLab and verify that you can browse through the repositories in
# the web interface.
sudo gitlab-ctl start

如果您不想移动所有仓库，而是希望在现有仓库存储之间移动特定项目，请使用编辑项目 API端点并指定 repository_storage 属性。

更改 Git 用户/组的名称

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

我们不建议更改现有安装的用户/组，因为这会导致不可预测的副作用。 如果您仍然想更改用户和组，可以通过将以下几行添加到 /etc/gitlab/gitlab.rb 来实现。

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

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

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

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

Omnibus GitLab 为 GitLab、PostgreSQL、Redis 和 NGINX 创建用户。 您可以在/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

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

如果您正在更改 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，您可能需要禁用由程序包完成的账号管理。

要禁用用户和组账号管理，在 /etc/gitlab/gitlab.rb 中设置：

manage_accounts['enable'] = false

警告 Omnibus GitLab 仍然希望用户和组存在于安装了 Omnibus GitLab 包的系统上。

默认情况下，Omnibus GitLab 包期望存在以下用户：

# GitLab user (required)
git

# Web server user (required)
gitlab-www

# Redis user for GitLab (only when using packaged Redis)
gitlab-redis

# Postgresql user (only when using packaged Postgresql)
gitlab-psql

# Prometheus user for prometheus monitoring and various exporters
gitlab-prometheus

# GitLab Mattermost user (only when using GitLab Mattermost)
mattermost

# GitLab Registry user (only when using GitLab Registry)
registry

# GitLab Consul user (only when using GitLab Consul)
gitlab-consul

默认情况下，Omnibus GitLab 包期望存在以下组：

# GitLab group (required)
git

# Web server group (required)
gitlab-www

# Redis group for GitLab (only when using packaged Redis)
gitlab-redis

# Postgresql group (only when using packaged Postgresql)
gitlab-psql

# Prometheus user for prometheus monitoring and various exporters
gitlab-prometheus

# GitLab Mattermost group (only when using GitLab Mattermost)
mattermost

# GitLab Registry group (only when using GitLab Registry)
registry

# GitLab Consul group (only when using GitLab Consul)
gitlab-consul

您也可以使用不同的用户/组名称，但是您必须在 /etc/gitlab/gitlab.rb 中指定用户/组详细信息，例如：

# Do not manage user/group accounts
manage_accounts['enable'] = false

# 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

移动用户的主目录

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

1. 停止 GitLab

   gitlab-ctl stop
   

2. 停止 runit 服务器

   # Using systemctl (Debian => 9 - Stretch):
   sudo systemctl stop gitlab-runsvdir
   
   # Using systemd (CentOS, Ubuntu >= 18.04):
   systemctl stop gitlab-runsvdir.service
   

3. 更改主目录。如果您有现有数据，则需要手动将其复制/同步到这些新位置。

   usermod -d /path/to/home USER
   

4. 更改您的 gitlab.rb 中的配置设置

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

5. 开启 runit 服务器

   # Using systemctl (Debian => 9 - Stretch):
   sudo systemctl start gitlab-runsvdir
   
   # Using systemd (CentOS, Ubuntu >= 18.04):
   systemctl start gitlab-runsvdir.service
   

6. 运行重新配置命令

   gitlab-ctl reconfigure
   

如果 runnit 服务没有停止，也没有为用户手动移动 home 目录，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

请务必遵循上述说明以避免此问题。

禁用存储目录管理

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

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

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

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

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

manage_storage_directories['manage_etc'] = false

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

要禁用这些目录的管理，请在 /etc/gitlab/gitlab.rb 中设置：

manage_storage_directories['enable'] = false

警告 Omnibus GitLab 包仍然希望这些目录存在于文件系统中。如果设置了此设置，则由管理员创建和设置正确的权限。

启用此设置将阻止创建以下目录：

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

如果你想阻止 Omnibus GitLab 服务（NGINX、Redis、Puma 等）在给定的文件系统被挂载之前启动，请将以下内容添加到 /etc/gitlab/gitlab.rb：

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

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

配置运行时目录

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

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

在 reconfigure 期间，包会检查 /run 是否是 tmpfs 挂载。 如果不是，将打印警告：

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

并且 Rails 指标将被禁用。

要再次启用 Rails 指标，请创建一个 tmpfs 挂载并在 /etc/gitlab/gitlab.rb 中指定它：

runtime_dir '/path/to/tmpfs'

运行 sudo gitlab-ctl reconfigure 使设置生效。

配置失败的身份验证禁令

您可以为 Git 和容器注册表配置失败身份验证禁令。

1. 用您的编辑器打开 /etc/gitlab/gitlab.rb。

2. 添加以下内容：

   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
   }
   

3. 重新配置极狐GitLab。

   sudo gitlab-ctl reconfigure
   

可以配置以下设置：

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

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

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

编辑 /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

不要忘记删除此行开头的 # 注释字符。

禁用模拟

查看 API 文档，获取禁用模拟的详细信息。

使用 Sentry 报告和记录错误

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

以下设置可用于配置 Sentry：

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 Environment 可用于跟踪多个已部署的 GitLab 环境中的错误和问题，例如 lab、development、staging、production。

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

例如，设置：

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

将添加值为 ‘main’ 的 ‘stage’ 标签。

内容安全策略

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

默认情况下未配置 CSP 和带有内联的随机数的支持 JavaScript。适用于大多数安装实例的示例配置如下：

gitlab_rails['content_security_policy'] = {
    enabled: true,
    report_only: false,
    directives: {
      default_src: "'self'",
      script_src: "'self' 'unsafe-inline' 'unsafe-eval' https://www.recaptcha.net https://apis.google.com",
      frame_ancestors: "'self'",
      frame_src: "'self' https://www.recaptcha.net/ https://content.googleapis.com https://content-compute.googleapis.com https://content-cloudbilling.googleapis.com https://content-cloudresourcemanager.googleapis.com",
      img_src: "* data: blob:",
      style_src: "'self' 'unsafe-inline'"
    }
}

不正确地配置 CSP 规则可能会阻止 GitLab 正常工作。 在推出策略之前，您可能还想将 report_only 更改为 true 以测试配置。

在安装时设置初始 root 密码

用户 root 的初始密码可以在安装时通过环境变量 GITLAB_ROOT_PASSWORD 设置。

例如：

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

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

为了防止 GitLab 接受非预期的 host header：

1. 编辑 /etc/gitlab/gitlab.rb 并配置 allowed_hosts：

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

2. 重新配置 GitLab 使更改生效：

   sudo gitlab-ctl reconfigure
   

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

设置 LDAP 登录

查看 LDAP 设置文档。

Smartcard 认证

查看 Smartcard 文档。

启用 HTTPS

查看 NGINX 文档.

重定向 HTTP 请求到 HTTPS

查看 NGINX 文档。

更改默认端口和 ssl 证书位置

查看 NGINX 文档。

使用非打包的网络服务器

使用已有的 NGINX、Passenger、或 Apache webserver，查看 NGINX 文档。

使用非打包的 PostgreSQL 数据库管理服务器

要连接到一个外部的 PostgreSQL DBMS，查看数据库设置文档。

将 ENV 变量添加到 GitLab 运行时环境

查看环境变量文档。

更改 GitLab.yml 设置

查看 gitlab.yml 文档。

通过 SMTP 发送应用邮件

查看 SMTP 配置文档。

调整 Puma 设置

查看 Puma 文档。

设置 NGINX 监听地址

查看 NGINX 文档。

将自定义 NGINX 设置插入 GitLab 服务器块

查看 NGINX 文档。

将自定义设置插入 NGINX 配置

查看 NGINX 文档。

启用 nginx_status

查看 NGINX 文档。