- 配置外部 URL
- 配置相对 URL
- 从非 root 用户加载外部配置文件
- 将 Git 数据存储在备用目录中
- 更改 Git 用户/组的名称
- 指定数字化的用户和组标识符
- 禁用用户和组帐户管理
- 移动用户的主目录
- 禁用存储目录管理
- 仅在挂载给定文件系统后启动 Omnibus GitLab 服务
- 配置运行时目录
- 配置失败的身份验证禁令
- 在安装过程中禁用自动缓存清理
- 使用 Sentry 进行错误报告和记录
- 设置内容交付网络(CDN) URL
- 设置 Content Security Policy
- 在安装时设置初始 root 密码
- 设置允许的主机以防止 host header 攻击
- 故障排查
极狐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 仓库,则可以将它们移动到新位置:-
在您移动用户时,阻止用户写入仓库:
sudo gitlab-ctl stop
-
将仓库同步到新位置。注意
repositories
后面没有斜线,但git-data
后面有斜线:sudo rsync -av --delete /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/
-
重新配置以启动必要的进程并修复任何错误的权限:
sudo gitlab-ctl reconfigure
-
仔细检查
/mnt/nas/git-data/
中的目录布局。预期的输出应该是repositories
:sudo ls /mnt/nas/git-data/
-
启动极狐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
设置内容交付网络(CDN) URL
使用 gitlab_rails['cdn_host']
为内容交付网络 (CDN) 或 asset 主机,提供静态 asset,将会配置一个 Rails asset 主机。
设置 CDN/asset 主机:
-
编辑
/etc/gitlab/gitlab.rb
:gitlab_rails['cdn_host'] = 'https://mycdnsubdomain.fictional-cdn.com'
-
重新配置极狐GitLab:
sudo gitlab-ctl reconfigure
设置 Content Security Policy
设置内容安全策略 (CSP) 可以帮助阻止 JavaScript 跨站点脚本 (XSS) 攻击。有关更多详细信息,请参阅关于 CSP 的 Mozilla 文档。
report_only
更改为 true
来测试配置。添加 CSP:
-
编辑
/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
。 -
重新配置极狐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
。