极狐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.rbgitlab-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 用户/组的名称

note我们不建议更改现有安装的用户或组,因为它可能会导致不可预知的副作用。

默认情况下,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
    

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

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

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 包要求存在以下用户和组:

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 用户/组

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

  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 包要求这些目录存在于文件系统中。如果配置了此设置,则由您来创建和设置正确的权限。

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

默认位置 权限 所有权 目的
/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 保存授权密钥

要禁用存储目录的管理:

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

    将添加值为 mainstage 标签。

  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 文档

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

添加 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