配置外部 URL
- 在安装时指定外部 URL
配置相对 URL
- 启用相对 URL
- 禁用相对 URL
从非 root 用户加载外部配置文件
将 Git 数据存储在备用目录中
更改 Git 用户/组的名称
指定数字化的用户和组标识符
禁用用户和组账号管理
- 移动用户的主目录
禁用存储目录管理
仅在挂载给定文件系统后启动 Omnibus GitLab 服务
配置运行时目录
配置 Rack Attack
在安装过程中禁用自动缓存清理
- 启用/禁用 Rack Attack 并设置基本身份验证限制
禁用模拟
使用 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

在更改外部 URL 之前，确定您之前是否通过选择顶部栏中的 菜单 > 管理，定义了自定义的 首页 URL 或 After sign out a path，然后在左侧边栏中选择 设置 > 通用 > 登录限制。如果定义了 URL，要么更新它们，要么完全删除它们。在配置新的外部 URL 后，这两个设置都可能导致意外重定向。

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

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

要使更改生效，请运行：

sudo gitlab-ctl reconfigure

更改外部 URL 后，建议您同时使 Markdown 缓存失效。

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

在安装时指定外部 URL

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

EXTERNAL_URL 环境变量只影响包的安装/升级。对于常规的 sudo gitlab-ctl reconfigure 运行，将使用 /etc/gitlab/gitlab.rb 中的值。

作为软件包更新的一部分，如果您无意中设置了 EXTERNAL_URL 变量，它将在没有任何警告的情况下替换 /etc/gitlab/gitlab.rb 中的现有值。所以，建议不要全局设置变量，而是专门传递给安装命令：

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

配置相对 URL

Omnibus GitLab 中的相对 URL 支持是实验性功能。

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

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

启用相对 URL

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

（可选）如果资源不足，可以使用以下命令关闭 Puma 和 Sidekiq，从而暂时释放一些内存：
```
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
```
在/etc/gitlab/gitlab.rb 中设置 external_url：
```
external_url "https://example.com/gitlab"
```
在这个例子中，提供的相对 URL 将是 /gitlab。根据自己的喜好更改它。
重新配置 GitLab 以使更改生效：
```
sudo gitlab-ctl reconfigure
```
重新启动服务，以便 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 用户，建议将 home 目录设置在本地磁盘（非 NFS）中以获得更好的性能。在 NFS 中设置时，Git 请求将需要发出另一个网络请求来读取 Git 配置，并且会增加 Git 操作的延迟。

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

停止 GitLab
```
gitlab-ctl stop
```

停止 runit 服务器

# Using systemctl (Debian => 9 - Stretch):
sudo systemctl stop gitlab-runsvdir

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

更改主目录。如果您有现有数据，则需要手动将其复制/同步到这些新位置。
```
usermod -d /path/to/home USER
```

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

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

开启 runit 服务器

# Using systemctl (Debian => 9 - Stretch):
sudo systemctl start gitlab-runsvdir

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

运行重新配置命令
```
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 包仍然希望这些目录存在于文件系统中。如果设置了此设置，则由管理员创建和设置正确的权限。

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

默认位置	权限	所有权	目的
`/var/opt/gitlab/git-data`	`0700`	`git:git`	保存仓库目录
`/var/opt/gitlab/git-data/repositories`	`2770`	`git:git`	保存 Git 仓库
`/var/opt/gitlab/gitlab-rails/shared`	`0751`	`git:gitlab-www`	保存大型对象目录
`/var/opt/gitlab/gitlab-rails/shared/artifacts`	`0700`	`git:git`	保存 CI 产物
`/var/opt/gitlab/gitlab-rails/shared/external-diffs`	`0700`	`git:git`	保存外部合并请求差异
`/var/opt/gitlab/gitlab-rails/shared/lfs-objects`	`0700`	`git:git`	保存 LFS 对象
`/var/opt/gitlab/gitlab-rails/shared/packages`	`0700`	`git:git`	保存软件包仓库
`/var/opt/gitlab/gitlab-rails/shared/dependency_proxy`	`0700`	`git:git`	保存依赖代理
`/var/opt/gitlab/gitlab-rails/shared/terraform_state`	`0700`	`git:git`	保存 terraform state
`/var/opt/gitlab/gitlab-rails/shared/pages`	`0750`	`git:gitlab-www`	保存用户页面
`/var/opt/gitlab/gitlab-rails/uploads`	`0700`	`git:git`	保存用户附件
`/var/opt/gitlab/gitlab-ci/builds`	`0700`	`git:git`	保存 CI 构建日志
`/var/opt/gitlab/.ssh`	`0700`	`git:git`	保存授权密钥

仅在挂载给定文件系统后启动 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 使设置生效。

配置 Rack Attack

为了防止滥用客户端造成损害，GitLab 使用 Rack Attack gem。了解如何配置 Rack Attack。

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

如果您安装了大型实例，您可能不想运行 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

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

启用/禁用 Rack Attack 并设置基本身份验证限制

下一个配置设置控制 Rack Attack：

gitlab_rails['rack_attack_git_basic_auth'] = {
  'enabled' => true, # Enable/Disable Rack Attack
  'ip_whitelist' => ["127.0.0.1"], # Whitelisted urls
  '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
}

禁用模拟

查看 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：

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

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

重新配置 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 文档。

配置选项

配置外部 URL

在安装时指定外部 URL

配置相对 URL

启用相对 URL

禁用相对 URL

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

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

更改 Git 用户/组的名称

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

禁用用户和组账号管理

移动用户的主目录

禁用存储目录管理

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

配置运行时目录

配置 Rack Attack

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

启用/禁用 Rack Attack 并设置基本身份验证限制

禁用模拟

使用 Sentry 报告和记录错误

内容安全策略

在安装时设置初始 root 密码

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

设置 LDAP 登录

Smartcard 认证

启用 HTTPS

重定向 HTTP 请求到 HTTPS

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

使用非打包的网络服务器

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

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

更改 GitLab.yml 设置

通过 SMTP 发送应用邮件

调整 Puma 设置

设置 NGINX 监听地址

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

将自定义设置插入 NGINX 配置

启用 nginx_status

重定向 `HTTP` 请求到 `HTTPS`