配置外部 URL
- 在安装时指定外部 URL
配置相对 URL
从非 root 用户加载外部配置文件
将 Git 数据存储在备用目录中
更改 Git 用户/组的名称
指定数字化的用户和组标识符
禁用用户和组帐户管理
移动用户的主目录
禁用存储目录管理
- 禁用 /etc/gitlab 目录管理
- 禁用 /var/opt/gitlab 目录管理
仅在挂载给定文件系统后启动 Omnibus GitLab 服务
配置运行时目录
配置失败的身份验证禁令
在安装过程中禁用自动缓存清理
使用 Sentry 进行错误报告和记录
设置 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：

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

编辑 /etc/gitlab/gitlab.rb：

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

重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```
更改外部 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：

在 /etc/gitlab/gitlab.rb 中设置 external_url：
```
external_url "https://example.com/gitlab"
```
在这个例子中，提供给极狐GitLab 使用的相对 URL 是 /gitlab。根据您的喜好更改它。
重新配置极狐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 父目录的位置：

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

重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```
可选。如果您已经在 /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 数据的组所有权。

要更改用户和组：

编辑 /etc/gitlab/gitlab.rb：

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

重新配置极狐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

重新配置极狐GitLab：
```
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，您可能需要禁用由 GitLab 包完成的帐户管理。

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

Linux 用户和组	必需？	描述
`git`	Yes	GitLab 用户/组
`gitlab-www`	Yes	Web 服务器用户/组
`gitlab-redis`	Only when using the packaged Redis	Redis 中用于 GitLab 的用户/组
`gitlab-psql`	Only when using the packaged PostgreSQL	PostgreSQL 用户/组
`gitlab-prometheus`	Yes	用于 Prometheus 监控和各种导出器的 Prometheus 用户/组
`mattermost`	Only when using GitLab Mattermost	GitLab Mattermost 用户/组
`registry`	Only when using GitLab Registry	GitLab Registry 用户/组
`gitlab-consul`	Only when using GitLab Consul	GitLab Consul 用户/组

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

编辑 /etc/gitlab/gitlab.rb：
```
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:
```
sudo gitlab-ctl reconfigure
```

移动用户的主目录

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

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

停止 GitLab：
```
gitlab-ctl stop
```
停止 runit 服务器：
```
sudo systemctl stop gitlab-runsvdir
```
更改主目录：
```
usermod -d /path/to/home <username>
```
如果您有现有数据，则需要手动将其复制/同步到这些新位置。

编辑 /etc/gitlab/gitlab.rb：

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

启动 runit 服务器：
```
sudo systemctl start gitlab-runsvdir
```
重新配置极狐GitLab:
```
sudo gitlab-ctl reconfigure
```

禁用存储目录管理

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

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

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

禁用 `/etc/gitlab` 目录管理

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

编辑 /etc/gitlab/gitlab.rb：

manage_storage_directories['manage_etc'] = false

重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

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

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

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/ci_secure_files`	`0700`	`git:git`	保存上传的安全文件
`/var/opt/gitlab/gitlab-rails/shared/pages`	`0750`	`git:gitlab-www`	保存用户 pages
`/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`	保存授权密钥

要禁用存储目录的管理：

编辑 /etc/gitlab/gitlab.rb：

manage_storage_directories['enable'] = false

重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

仅在挂载给定文件系统后启动 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'

重新配置极狐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 指标：

编辑 /etc/gitlab/gitlab.rb 以创建 tmpfs 挂载（注意配置中没有 =）：
```
runtime_dir '/path/to/tmpfs'
```
重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

配置失败的身份验证禁令

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

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

重新配置极狐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 任务，因为它可能需要很长时间才能完成。默认情况下，缓存清除任务在重新配置期间自动运行。

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

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

重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

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

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

配置 Sentry：

编辑 /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、生产）跟踪错误和问题。

可选的。要在从特定服务器发送的每个事件上设置自定义 Sentry 标签，可以设置 GITLAB_SENTRY_EXTRA_TAGS 环境变量。这个变量是一个 JSON 编码的散列，表示应该为来自该服务器的所有异常传递给 Sentry 的任何标签。
对于实例，设置：
```
gitlab_rails['env'] = {
  'GITLAB_SENTRY_EXTRA_TAGS' => '{"stage": "main"}'
}
```
将添加值为 main 的 stage 标签。
重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

设置 Content Security Policy

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

不正确地配置 CSP 规则可能会阻止极狐GitLab 正常工作。在实施策略之前，您可能还需要将 report_only 更改为 true 来测试配置。

添加 CSP：

编辑 /etc/gitlab/gitlab.rb：

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'"
    }
}

前面的示例是适用于大多数极狐GitLab 安装的配置。

重新配置极狐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 接受与预期不同的主机头：

编辑 /etc/gitlab/gitlab.rb：

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

重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

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

故障排查

`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。

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

配置外部 URL

在安装时指定外部 URL

配置相对 URL

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

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

更改 Git 用户/组的名称

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

禁用用户和组帐户管理

移动用户的主目录

禁用存储目录管理

禁用 /etc/gitlab 目录管理

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

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

配置运行时目录

配置失败的身份验证禁令

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

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

设置 Content Security Policy

在安装时设置初始 root 密码

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

故障排查

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

禁用 `/etc/gitlab` 目录管理

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

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