极狐 GitLab Logo

数据库设置

  • Tier: 基础版，专业版，旗舰版
  • Offering: 私有化部署

极狐GitLab 仅支持 PostgreSQL 数据库管理系统。

因此，您有两种选项可以与 Linux 软件包安装一起使用数据库服务器：

  • 使用 Linux 软件包安装中包含的打包 PostgreSQL 服务器（无需配置，推荐）。
  • 使用外部 PostgreSQL 服务器。

使用随 Linux 软件包提供的 PostgreSQL 数据库服务#

重新配置和 PostgreSQL 重启#

Linux 软件包安装通常会在重新配置时重新启动任何服务，如果在 gitlab.rb 文件中更改了该服务的配置设置。PostgreSQL 独特之处在于其某些设置通过重新加载（HUP）生效，而其他设置需要重新启动 PostgreSQL。由于管理员通常希望更好地控制 PostgreSQL 何时确切重启，因此配置了 Linux 软件包安装在重新配置时对 PostgreSQL 进行重新加载，而不是重启。这意味着如果您修改了任何需要重启的 PostgreSQL 设置，您需要在重新配置后手动重启 PostgreSQL。

极狐GitLab 配置模板识别哪些 PostgreSQL 设置需要重启，哪些仅需要重新加载。您还可以针对数据库运行查询，以确定任何单个设置是否需要重启。使用 sudo gitlab-psql 启动数据库控制台，然后将以下查询中的 <setting name> 替换为您正在更改的设置：

sql
SELECT name,setting FROM pg_settings WHERE context = 'postmaster' AND name = '<setting name>';

如果更改设置需要重启，查询将返回设置的名称和当前运行的 PostgreSQL 实例中的设置值。

PostgreSQL 版本更改时自动重启#

默认情况下，当基础版本更改时，Linux 软件包安装会自动重启 PostgreSQL，正如上游文档建议的那样。可以使用 postgresql 和 geo-postgresql 可用的 auto_restart_on_version_change 设置来控制此行为。

要禁用 PostgreSQL 版本更改时的自动重启：

  1. 编辑 /etc/gitlab/gitlab.rb 并添加以下行：

    ruby
    # 对 PostgreSQL/Patroni
postgresql['auto_restart_on_version_change'] = false

# 对 Geo PostgreSQL
geo_postgresql['auto_restart_on_version_change'] = false

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

建议在基础版本更改时重启 PostgreSQL，以避免像加载必要库相关的错误。

配置 SSL#

Linux 软件包安装自动在 PostgreSQL 服务器上启用 SSL，但默认情况下它将接受加密和未加密的连接。强制 SSL 需要在 pg_hba.conf 中使用 hostssl 配置。

SSL 支持取决于以下文件：

  • 数据库的公共 SSL 证书 (server.crt)。
  • SSL 证书的相应私钥 (server.key)。
  • 验证服务器证书的根证书包 (root.crt)。 默认情况下，Linux 软件包安装使用嵌入的证书包 /opt/gitlab/embedded/ssl/certs/cacert.pem。对于自签名证书，这不是必需的。

Linux 软件包安装生成一个 10 年的自签名证书和私钥供使用。如果您更倾向于使用 CA 签名证书或用您自己的自签名证书替换它，请使用以下步骤。

请注意，这些文件的位置可以配置，但私钥必须可由 gitlab-psql 用户读取。Linux 软件包安装为您管理文件的权限，但如果路径被自定义，您必须确保 gitlab-psql 可以访问文件所在的目录。

请注意，server.crt 和 server.key 可能与访问极狐GitLab 使用的默认 SSL 证书不同。例如，假设您的数据库外部主机名是 database.example.com，而您的极狐GitLab 外部主机名是 gitlab.example.com。您将需要一个 *.example.com 的通配符证书或两个不同的 SSL 证书。

ssl_cert_file、ssl_key_file 和 ssl_ca_file 文件指示 PostgreSQL 在文件系统上找到证书、密钥和包的位置。这些更改应用于 postgresql.conf。指令 internal_certificate 和 internal_key 用于填充这些文件的内容。可以直接添加内容或从文件中加载，如以下示例所示。

获取这些文件后，启用 SSL：

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    postgresql['ssl_cert_file'] = '/custom/path/to/server.crt'
postgresql['ssl_key_file'] = '/custom/path/to/server.key'
postgresql['ssl_ca_file'] = '/custom/path/to/bundle.pem'
postgresql['internal_certificate'] = File.read('/custom/path/to/server.crt')
postgresql['internal_key'] = File.read('/custom/path/to/server.key')

    相对路径将在 PostgreSQL 数据目录中根化（默认情况下为 /var/opt/gitlab/postgresql/data）。

  2. 重新配置极狐GitLab以应用配置更改。

  3. 重启 PostgreSQL 使更改生效：

    shell
    gitlab-ctl restart postgresql

    如果 PostgreSQL 启动失败，请检查日志（例如，/var/log/gitlab/postgresql/current）以获取更多详细信息。

要求 SSL#

  1. 将以下内容添加到 /etc/gitlab/gitlab.rb：

    ruby
    gitlab_rails['db_sslmode'] = 'require'

  2. 重新配置极狐GitLab以应用配置更改。

禁用 SSL#

  1. 将以下内容添加到 /etc/gitlab/gitlab.rb：

    ruby
    postgresql['ssl'] = 'off'

  2. 重新配置极狐GitLab以应用配置更改。

  3. 重启 PostgreSQL 使更改生效：

    shell
    gitlab-ctl restart postgresql

    如果 PostgreSQL 启动失败，请检查日志（例如，/var/log/gitlab/postgresql/current）以获取更多详细信息。

验证 SSL 是否正在使用#

要确定客户端是否正在使用 SSL，您可以运行：

shell
sudo gitlab-rails dbconsole --database main

在启动时，您应该看到如下横幅：

plaintext
psql (13.14)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: on)
Type "help" for help.

要确定客户端是否在使用 SSL，请发出以下 SQL 查询：

sql
SELECT * FROM pg_stat_ssl;

例如：

plaintext
1gitlabhq_production=> select * from pg_stat_ssl;
2 pid  | ssl | version |         cipher         | bits | compression |  clientdn
3------+-----+---------+------------------------+------+-------------+------------
4  384 | f   |         |                        |      |             |
5  386 | f   |         |                        |      |             |
6  998 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
7  933 | f   |         |                        |      |             |
8 1003 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
9 1016 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
10 1022 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
11 1211 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
12 1214 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
13 1213 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
14 1215 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
15 1252 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           |
16 1280 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
17  382 | f   |         |                        |      |             |
18  381 | f   |         |                        |      |             |
19  383 | f   |         |                        |      |             |
20(16 rows)
  1. 在 ssl 列中列有 t 的行已启用。
  2. 在 clientdn 中有值的行使用 cert 认证方法。

配置 SSL 客户端认证#

客户端 SSL 证书可用于认证到数据库服务器。创建证书超出了 omnibus-gitlab 的范围。但有现有 SSL 证书管理解决方案的用户可以使用此功能。

配置数据库服务器#

  1. 为服务器创建证书和密钥，通用名称应等于服务器的 DNS 名称。

  2. 将服务器证书、密钥和 CA 文件复制到 PostgreSQL 服务器，并确保权限正确。

    1. 证书应由数据库用户拥有（默认：gitlab-psql）。
    2. 密钥文件应由数据库用户拥有，其权限应为 0400。
    3. CA 文件应由数据库用户拥有，其权限应为 0400。

不要使用文件名 server.crt 或 server.key 作为这些文件。这些文件名保留用于 omnibus-gitlab 的内部使用。

  1. 确保在 gitlab.rb 中设置以下内容：

    ruby
    1postgresql['ssl_cert_file'] = 'PATH_TO_CERTIFICATE'
2postgresql['ssl_key_file'] = 'PATH_TO_KEY_FILE'
3postgresql['ssl_ca_file'] = 'PATH_TO_CA_FILE'
4postgresql['listen_address'] = 'IP_ADDRESS'
5postgresql['cert_auth_addresses'] = {
6'IP_ADDRESS' => {
7  'database' => 'gitlabhq_production',
8  'user' => 'gitlab'
9}

    将 listen_address 设置为客户端将用于连接数据库的服务器的 IP 地址。 确保 cert_auth_addresses 包含允许连接数据库的 IP 地址以及数据库和用户的列表。您可以在指定 cert_auth_addresses 的键时使用 CIDR 表示法，以包含一个 IP 地址范围。

  2. 运行 gitlab-ctl reconfigure，然后运行 gitlab-ctl restart postgresql 使新设置生效。

配置 Rails 客户端#

要使 Rails 客户端连接到服务器，您需要一个 commonName 设置为 gitlab 的证书和密钥，并由数据库服务器 ssl_ca_file 中指定的证书机构信任。

  1. 配置 gitlab.rb

    ruby
    gitlab_rails['db_host'] = 'IP_ADDRESS_OR_HOSTNAME_OF_DATABASE_SERVER'
gitlab_rails['db_sslcert'] = 'PATH_TO_CERTIFICATE_FILE'
gitlab_rails['db_sslkey'] = 'PATH_TO_KEY_FILE'
gitlab_rails['db_rootcert'] = 'PATH_TO_CA_FILE'

  2. 运行 gitlab-ctl reconfigure 以使 Rails 客户端使用新设置。

  3. 按照验证 SSL 是否正在使用中的步骤确保认证正在工作。

配置打包的 PostgreSQL 服务器监听 TCP/IP#

打包的 PostgreSQL 服务器可以配置为监听 TCP/IP 连接，但有些非关键脚本预期 UNIX 套接字，可能会出现不正常的行为。

要为数据库服务配置使用 TCP/IP，请对 gitlab.rb 的 postgresql 和 gitlab_rails 部分进行更改。

配置 PostgreSQL 块#

postgresql 块中受影响的设置如下：

  • listen_address: 控制 PostgreSQL 将监听的地址。
  • port: 控制 PostgreSQL 监听的端口。默认是 5432。
  • md5_auth_cidr_addresses: 允许连接到服务器并在使用密码进行认证后可连接的 CIDR 地址块列表。
  • trust_auth_cidr_addresses: 允许连接到服务器且不进行任何形式认证的 CIDR 地址块列表。您应该仅设置此设置，以允许需要连接的节点，例如极狐GitLab Rails 或 Sidekiq。这包括在同一节点上部署时的本地连接或来自 Postgres Exporter (127.0.0.1/32) 的连接。
  • sql_user: 控制 MD5 认证的预期用户名。默认为 gitlab，不是必需设置。
  • sql_user_password: 设置 PostgreSQL 将接受的 MD5 认证密码。

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    1postgresql['listen_address'] = '0.0.0.0'
2postgresql['port'] = 5432
3postgresql['md5_auth_cidr_addresses'] = %w()
4postgresql['trust_auth_cidr_addresses'] = %w(127.0.0.1/24)
5postgresql['sql_user'] = "gitlab"
6
7##! SQL_USER_PASSWORD_HASH 可以通过命令 `gitlab-ctl pg-password-md5 'gitlab'` 生成，
8##! 其中 'gitlab'（单引号以避免 shell 插值）是连接到极狐GitLab 的 SQL 用户名。
9##! 您将被提示输入其他客户端将用于认证数据库的密码，例如下面部分中的 `securesqlpassword`。
10postgresql['sql_user_password'] = "SQL_USER_PASSWORD_HASH"
11
12# 强制所有连接在 trust_auth_cidr_addresses 和 md5_auth_cidr_addresses 中定义的连接上使用 SSL
13postgresql['hostssl'] = true

  2. 重新配置极狐GitLab并重启 PostgreSQL：

    shell
    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

任何将通过网络连接的客户端或极狐GitLab 服务都需要提供 sql_user 的值作为用户名，并在连接到 PostgreSQL 服务器时提供配置中的密码。它们还必须在提供给 md5_auth_cidr_addresses 的网络块中。

配置极狐GitLab Rails 块#

要配置 gitlab-rails 应用程序通过网络连接到 PostgreSQL 数据库，必须配置多个设置：

  • db_host: 需要设置为数据库服务器的 IP 地址。如果这与 PostgreSQL 服务在同一实例上，这可以是 127.0.0.1，并且不需要密码认证。
  • db_port: 设置连接到 PostgreSQL 服务器的端口，必须设置如果 db_host 已设置。
  • db_username: 配置连接到 PostgreSQL 的用户名。默认是 gitlab。
  • db_password: 必须提供如果通过 TCP/IP 连接到 PostgreSQL，并且来自 postgresql['md5_auth_cidr_addresses'] 块中的实例设置。这不是必需的，如果您连接到 127.0.0.1 并已配置 postgresql['trust_auth_cidr_addresses'] 包括它。

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    gitlab_rails['db_host'] = '127.0.0.1'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_username'] = "gitlab"
gitlab_rails['db_password'] = "securesqlpassword"

  2. 重新配置极狐GitLab并重启 PostgreSQL：

    shell
    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

应用并重启服务#

在进行前面的更改后，管理员应运行 gitlab-ctl reconfigure。如果您遇到有关服务未监听 TCP 的任何问题，请尝试直接使用 gitlab-ctl restart postgresql 重启服务。

Linux 软件包的某些包含脚本（例如 gitlab-psql）预期与 PostgreSQL 的连接通过 UNIX 套接字处理，并可能无法正常工作。您可以启用 TCP/IP 而不禁用 UNIX 套接字。

要从其他客户端测试访问，您可以运行：

shell
sudo gitlab-rails dbconsole --database main

启用 PostgreSQL WAL（预写日志）归档#

默认情况下，打包的 PostgreSQL 的 WAL 归档未启用。在寻求启用 WAL 归档时考虑以下事项：

  • WAL 级别需要是“replica”或更高（9.6+ 选项为 minimal、replica 或 logical）。
  • 增加 WAL 级别将增加常规操作中消耗的存储量。

要启用 WAL 归档：

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    1# 复制设置
2postgresql['sql_replication_user'] = "gitlab_replicator"
3postgresql['wal_level'] = "replica"
4    ...
5    ...
6# 备份/归档设置
7postgresql['archive_mode'] = "on"
8postgresql['archive_command'] = "/your/wal/archiver/here"
9postgresql['archive_timeout'] = "60"

  2. 重新配置极狐GitLab以使更改生效。这将导致数据库重启。

将 PostgreSQL 数据存储在不同的目录中#

默认情况下，一切都存储在 /var/opt/gitlab/postgresql 下，由 postgresql['dir'] 属性控制。

这包括：

  • 数据库套接字将是 /var/opt/gitlab/postgresql/.s.PGSQL.5432。这由 postgresql['unix_socket_directory'] 控制。
  • gitlab-psql 系统用户将其 HOME 目录设置为此。这由 postgresql['home'] 控制。
  • 实际数据将存储在 /var/opt/gitlab/postgresql/data 中。

要更改 PostgreSQL 数据的位置：

如果您有现有数据库，则需要先将数据移动到新位置。

这是一个侵入性操作。无法在现有安装上进行而不需要停机。

  1. 如果这是现有安装，请停止极狐GitLab：gitlab-ctl stop。
  2. 更新 postgresql['dir'] 到所需位置。
  3. 运行 gitlab-ctl reconfigure。
  4. 启动极狐GitLab：gitlab-ctl start。

升级打包的 PostgreSQL 服务器#

Linux 软件包提供 gitlab-ctl pg-upgrade 命令，以更新打包的 PostgreSQL 服务器到更高版本（如果软件包中包含）。这会在软件包升级时更新 PostgreSQL 到默认提供版本，除非特别选择退出。

在将极狐GitLab 升级到新版本之前，请参阅 Linux 软件包的特定版本更改，查看：

  • 数据库版本何时更改。
  • 何时需要升级。

在升级之前，务必在运行任何命令之前完全阅读本节。对于单节点安装，此升级需要停机，因为在执行升级时数据库必须关闭。时间长度取决于数据库的大小。

如果在升级过程中遇到任何问题，付费用户请联系您的客户成功经理。免费用户，请在官方论坛上寻求帮助，也可以查看GitLab 专业升级服务。

要升级 PostgreSQL 版本，请确保：

  • 您正在运行支持当前 PostgreSQL 版本的极狐GitLab 最新版本。

  • 如果您最近升级，您在继续之前成功运行了 sudo gitlab-ctl reconfigure。

  • 您有足够的磁盘空间用于数据库的两个副本。不要尝试升级，除非您有足够的可用空间。

    • 使用 sudo du -sh /var/opt/gitlab/postgresql/data（或更新您的数据库路径）检查您的数据库大小。
    • 使用 sudo df -h 检查可用空间。如果数据库所在的分区没有足够的空间，请将参数 --tmp-dir $DIR 传递给命令。升级任务包括可用磁盘空间检查，如果未满足要求，则会中止升级。

在确认上述检查列表已满足后，您可以继续进行升级：

shell
sudo gitlab-ctl pg-upgrade

要升级到特定的 PostgreSQL 版本，请使用 -V 标志附加版本。例如，要升级到 PostgreSQL 16：

shell
sudo gitlab-ctl pg-upgrade -V 16

pg-upgrade 可以接受参数；例如，您可以设置执行底层命令的超时时间（--timeout=1d2h3m4s5ms）。运行 gitlab-ctl pg-upgrade -h 查看完整列表。

gitlab-ctl pg-upgrade 执行以下步骤：

  1. 确保数据库处于已知良好状态。
  2. 检查是否有足够的可用磁盘空间，否则中止。您可以通过附加 --skip-disk-check 标志跳过此步骤。
  3. 关闭现有数据库和任何不必要的服务，并启用极狐GitLab 部署页面。
  4. 更改 /opt/gitlab/embedded/bin/ 中 PostgreSQL 的符号链接，指向数据库的新版本。
  5. 创建一个新的目录，其中包含一个新的、空的数据库，其区域设置与现有数据库匹配。
  6. 使用 pg_upgrade 工具将数据从旧数据库复制到新数据库。
  7. 将旧数据库移出。
  8. 将新数据库移动到预期位置。
  9. 调用 sudo gitlab-ctl reconfigure 以进行所需的配置更改并启动新的数据库服务器。
  10. 运行 ANALYZE 生成数据库统计数据。
  11. 启动剩余服务并移除部署页面。
  12. 如果在此过程中检测到任何错误，则恢复到旧版本的数据库。

升级完成后，验证一切是否正常工作。

如果在运行 ANALYZE 步骤时输出中出现错误，您的升级仍将正常运行，但在生成数据库统计数据之前数据库性能会很差。使用 gitlab-psql 确定是否需要手动运行 ANALYZE：

shell
sudo gitlab-psql -c "SELECT relname, last_analyze, last_autoanalyze FROM pg_stat_user_tables WHERE last_analyze IS NULL AND last_autoanalyze IS NULL;"

如果上述查询返回了任何行，您可以手动运行 ANALYZE：

shell
sudo gitlab-psql -c 'SET statement_timeout = 0; ANALYZE VERBOSE;'

ANALYZE 命令的执行时间可能会根据您的数据库大小显著变化。要监控此操作的进度，您可以在另一个控制台会话中周期性运行以下查询。tables_remaining 列应该逐渐达到 0：

shell
1sudo gitlab-psql -c "
2SELECT
3    COUNT(*) AS total_tables,
4    SUM(CASE WHEN last_analyze IS NULL OR last_analyze < (NOW() - INTERVAL '2 hours') THEN 1 ELSE 0 END) AS tables_remaining
5FROM pg_stat_user_tables;
6"

在您确认极狐GitLab 实例运行正常后，您可以清理旧数据库文件：

shell
sudo rm -rf /var/opt/gitlab/postgresql/data.<old_version>
sudo rm -f /var/opt/gitlab/postgresql-version.old

您可以在Linux 软件包中 PostgreSQL 版本中找到极狐GitLab 版本所附带的 PostgreSQL 版本详细信息。

选择退出自动 PostgreSQL 升级#

要在极狐GitLab 软件包升级期间选择退出自动 PostgreSQL 升级，请运行：

shell
sudo touch /etc/gitlab/disable-postgresql-upgrade

如果您使用 Docker 镜像，可以通过设置 GITLAB_SKIP_PG_UPGRADE 环境变量为 true 来禁用自动升级。

恢复打包的 PostgreSQL 服务器到以前的版本#

此操作将恢复您的当前数据库，包括其数据，到您上次升级前的状态。在尝试降级打包的 PostgreSQL 数据库之前，请务必创建备份。

在极狐GitLab 版本中提供多个 PostgreSQL 版本的情况下，用户可以使用 gitlab-ctl revert-pg-upgrade 命令将已升级的 PostgreSQL 版本降级到之前的版本。此命令还支持 -V 标志来指定目标版本，用于在软件包中提供多个 PostgreSQL 版本的场景（例如：极狐GitLab 12.8，其中 PostgreSQL 9.6.x、10.x 和 11.x 已提供）。

要指定 PostgreSQL 14 的目标版本：

shell
gitlab-ctl revert-pg-upgrade -V 14

如果未指定目标版本，它将使用 /var/opt/gitlab/postgresql-version.old 中的版本（如果可用）。否则，它会回退到极狐GitLab 默认版本。

在其他极狐GitLab 版本中仅提供一个 PostgreSQL 版本，您不能降级 PostgreSQL 版本。您必须将极狐GitLab 降级到旧版本才能实现此目的。

配置多个数据库连接#

History
    • gitlab:db:decomposition:connection_status Rake 任务在极狐GitLab 15.11 中引入。
    • 单数据库支持将在未来版本中移除。

在极狐GitLab 16.0 中，极狐GitLab 默认使用两个指向同一 PostgreSQL 数据库的数据库连接。

在升级到极狐GitLab 16.0 之前，检查 PostgreSQL max_connections 设置是否足够高，以便超过 50% 的可用连接显示为未使用。例如，如果 max_connections 设置为 100，您看到 75 个连接正在使用，则在升级之前必须将 max_connections 增加到至少 150，因为升级后，正在使用的连接将翻倍到 150。

您可以通过运行以下 Rake 任务验证这一点：

shell
sudo gitlab-rake gitlab:db:decomposition:connection_status

如果任务指示 max_connections 足够高，则您可以继续进行升级。

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

默认情况下，极狐GitLab 配置为使用 Linux 软件包中包含的 PostgreSQL 服务器。您还可以重新配置以使用外部的 PostgreSQL 实例。

如果您使用的是非打包 PostgreSQL 服务器，您需要确保根据数据库要求文档设置 PostgreSQL。

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    1# 禁用内置的 Postgres
2postgresql['enable'] = false
3
4# 填写 database.yml 的连接详细信息
5gitlab_rails['db_adapter'] = 'postgresql'
6gitlab_rails['db_encoding'] = 'utf8'
7gitlab_rails['db_host'] = '127.0.0.1'
8gitlab_rails['db_port'] = 5432
9gitlab_rails['db_username'] = 'USERNAME'
10gitlab_rails['db_password'] = 'PASSWORD'

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

    请注意：

    • /etc/gitlab/gitlab.rb 应具有文件权限 0600，因为它包含明文密码。

    • PostgreSQL 允许监听多个地址。

      如果您在 gitlab_rails['db_host'] 中使用多个地址，逗号分隔，列表中的第一个地址将用于连接。

  2. 重新配置极狐GitLab以使更改生效。

  3. seed 数据库。

非打包 PostgreSQL 的 UNIX 套接字配置#

如果您想使用系统的 PostgreSQL 服务器（安装在与极狐GitLab 相同的系统上），而不是极狐GitLab 附带的那个，您可以通过使用 UNIX 套接字来实现：

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    1# 禁用内置的 Postgres
2postgresql['enable'] = false
3
4# 填写 database.yml 的连接详细信息
5gitlab_rails['db_adapter'] = 'postgresql'
6gitlab_rails['db_encoding'] = 'utf8'
7# 套接字所在的路径
8gitlab_rails['db_host'] = '/var/run/postgresql/'

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

    ruby
    sudo gitlab-ctl-reconfigure

配置 SSL#

要求 SSL#

  1. 将以下内容添加到 /etc/gitlab/gitlab.rb：

    ruby
    gitlab_rails['db_sslmode'] = 'require'

  2. 重新配置极狐GitLab以应用配置更改。

要求 SSL 并验证服务器证书是否对 CA 包有效#

PostgreSQL 可以配置为要求 SSL，并验证服务器证书是否对 CA 包有效，以防止欺骗。 gitlab_rails['db_sslrootcert'] 中指定的 CA 包必须包含根证书和中间证书。

  1. 将以下内容添加到 /etc/gitlab/gitlab.rb：

    ruby
    gitlab_rails['db_sslmode'] = "verify-full"
gitlab_rails['db_sslrootcert'] = "<full_path_to_your_ca-bundle.pem>"

    如果您使用 Amazon RDS 作为您的 PostgreSQL 服务器，请确保下载并使用组合 CA 包作为 gitlab_rails['db_sslrootcert']。有关此的更多信息可以在 AWS 的使用 SSL/TLS 加密连接到 DB 实例文章中找到。

  2. 重新配置极狐GitLab以应用配置更改。

备份和恢复非打包 PostgreSQL 数据库#

使用备份和恢复命令时，极狐GitLab 将尝试使用打包的 pg_dump 命令创建数据库备份文件，并使用打包的 psql 命令恢复备份。这仅在它们是正确版本时有效。检查打包 pg_dump 和 psql 的版本：

shell
/opt/gitlab/embedded/bin/pg_dump --version
/opt/gitlab/embedded/bin/psql --version

如果这些版本与您的非打包外部 PostgreSQL 不同，您可能会在尝试运行备份命令时遇到以下错误输出。

plaintext
Dumping PostgreSQL database gitlabhq_production ... pg_dump: error: server version: 13.3; pg_dump version: 12.6
pg_dump: error: aborting because of server version mismatch

在这个例子中，错误发生在极狐GitLab 14.1 使用 PostgreSQL 版本 13.3 时，而不是默认提供的 PostgreSQL 版本 12.6。

在这种情况下，您需要安装与数据库版本匹配的工具，然后遵循以下步骤。有多种方式安装 PostgreSQL 客户端工具。

一旦正确的 psql 和 pg_dump 工具在您的系统上可用，按照这些步骤，使用您安装新工具的位置的正确路径：

  1. 将符号链接添加到非打包版本：

    shell
    ln -s /path/to/new/pg_dump /path/to/new/psql /opt/gitlab/bin/

  2. 检查版本：

    shell
    /opt/gitlab/bin/pg_dump --version
/opt/gitlab/bin/psql --version

    它们现在应该与您的非打包外部 PostgreSQL 相同。

完成此操作后，确保备份和恢复任务使用正确的可执行文件，通过运行备份和恢复命令。

升级非打包 PostgreSQL 数据库#

您可以在停止连接到数据库的所有进程（Puma、Sidekiq）后升级外部数据库：

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

在继续升级之前，请注意以下几点：

  • 检查极狐GitLab 版本和 PostgreSQL 版本之间的兼容性：
  • 使用极狐GitLab 备份或恢复时，必须保持极狐GitLab 的同一版本。 如果您计划升级到较新的极狐GitLab 版本，首先升级 PostgreSQL。
  • 可以使用备份和恢复命令将数据库备份和恢复到较新的 PostgreSQL 版本。
  • 如果指定了 postgresql['version'] 的 PostgreSQL 版本与该 Linux 软件包版本不提供的版本不匹配， 兼容性表中的默认版本决定活跃的客户端二进制文件（如 PostgreSQL 备份/恢复二进制文件）。

以下示例演示了从运行 PostgreSQL 14 的数据库主机升级到运行 PostgreSQL 16 的另一个数据库主机并导致停机：

  1. 启动一个新的 PostgreSQL 16 数据库服务器，按照数据库要求设置。

  2. 确保极狐GitLab Rails 实例上使用兼容版本的 pg_dump 和 pg_restore。要修改极狐GitLab 配置，编辑 /etc/gitlab/gitlab.rb 并指定 postgresql['version'] 的值：

    ruby
    postgresql['version'] = 16

  3. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

  4. 停止极狐GitLab（注意此步骤会导致停机）：

    shell
    sudo gitlab-ctl stop

备份命令需要附加参数，当您的安装使用 PgBouncer 时。

  1. 使用 SKIP 选项运行备份 Rake 任务，仅备份数据库。 记下备份文件名；稍后您将使用它进行恢复。

    shell
    sudo gitlab-backup create SKIP=repositories,uploads,builds,artifacts,lfs,pages,registry

  2. 关闭 PostgreSQL 14 数据库主机。

  3. 编辑 /etc/gitlab/gitlab.rb 并更新 gitlab_rails['db_host'] 设置，指向 PostgreSQL 数据库 16 主机。

  4. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

备份命令需要附加参数，当您的安装使用 PgBouncer 时。

  1. 使用之前创建的数据库备份文件恢复数据库，并确保在询问“此任务现在将重建 authorized_keys 文件”时回答 否：

    shell
    # 使用备份时间戳 https://gitlab.cn/docs/administration/backup_restore/backup_gitlab/#backup-timestamp
sudo gitlab-backup restore BACKUP=<backup-timestamp>

  2. 启动极狐GitLab：

    shell
    sudo gitlab-ctl start

  3. 在将 PostgreSQL 升级到新的主版本后，重新创建表统计数据，以确保选择有效的查询计划并减少数据库服务器 CPU 负载。

    如果升级是使用 pg_upgrade 的“原地”升级，请在 PostgreSQL 数据库控制台上运行以下查询：

    SQL
    SET statement_timeout = 0; ANALYZE VERBOSE;

    ANALYZE 命令的执行时间可能会根据您的数据库大小显著变化。要监控此操作的进度，您可以在另一个 PostgreSQL 数据库控制台中周期性运行以下查询。tables_remaining 列应该逐渐达到 0：

    SQL
    SELECT
  COUNT(*) AS total_tables,
  SUM(CASE WHEN last_analyze IS NULL OR last_analyze < (NOW() - INTERVAL '2 hours') THEN 1 ELSE 0 END) AS tables_remaining
FROM pg_stat_user_tables;

    如果升级使用 pg_dump 和 pg_restore，请在 PostgreSQL 数据库控制台上运行以下查询：

    SQL
    SET statement_timeout = 0; VACUUM VERBOSE ANALYZE;

种子数据库（仅适用于新安装）#

这是一个破坏性命令；不要在现有数据库上运行。

Linux 软件包安装不会种植您的外部数据库。运行以下命令导入架构并创建第一个管理用户：

shell
# 如果您是“git”用户，请删除“sudo”
sudo gitlab-rake gitlab:setup

如果您想为默认 root 用户指定密码，请在运行上面的 gitlab:setup 命令之前在 /etc/gitlab/gitlab.rb 中指定 initial_root_password 设置：

ruby
gitlab_rails['initial_root_password'] = 'nonstandardpassword'

如果您想为共享的极狐GitLab Runner 指定初始注册令牌，请在运行 gitlab:setup 命令之前在 /etc/gitlab/gitlab.rb 中指定 initial_shared_runners_registration_token 设置：

ruby
gitlab_rails['initial_shared_runners_registration_token'] = 'token'

固定打包的 PostgreSQL 版本（仅适用于新安装）#

Linux 软件包附带不同的 PostgreSQL 版本，并在未另行指定的情况下初始化默认版本。

要使用非默认版本初始化 PostgreSQL，您可以在初始重新配置之前将 postgresql['version'] 设置为一个主要版本之一的打包 PostgreSQL 版本。例如，在极狐GitLab 17.10 中，您可以使用 postgresql['version'] = 14 来使用 PostgreSQL 14 而不是默认的 PostgreSQL 16。

在初始重新配置后，如果使用的是与 Linux 软件包捆绑的 PostgreSQL，则设置 postgresql['version'] 会抛出关于数据目录在不同版本的 PostgreSQL 上初始化的错误。如果遇到这种情况，请参阅恢复打包的 PostgreSQL 服务器到以前的版本。

如果您在以前安装过极狐GitLab 的环境上进行全新安装并且使用的是固定的 PostgreSQL 版本，请首先确保删除与 PostgreSQL 相关的任何文件夹，并且实例上没有运行 PostgreSQL 进程。

提供敏感数据配置给极狐GitLab Rails 而不存储纯文本#

有关更多信息，请参阅配置文档中的示例。

数据库的应用程序设置#

禁用自动数据库迁移#

如果您有多个极狐GitLab 服务器共享一个数据库，您可能希望限制在重新配置期间执行迁移步骤的节点数量。

编辑 /etc/gitlab/gitlab.rb 以追加：

ruby
# 启用或禁用自动数据库迁移
# 在所有主机上，除了指定的部署节点
gitlab_rails['auto_migrate'] = false

/etc/gitlab/gitlab.rb 应该具有文件权限 0600，因为它包含纯文本密码。

下次重新配置携带上述配置的主机时，不会执行迁移步骤。

为避免与架构相关的升级后错误，必须在升级期间将标记为部署节点的主机设置为 gitlab_rails['auto_migrate'] = true。

设置客户端 statement_timeout#

Rails 等待数据库事务完成的时间可以通过 gitlab_rails['db_statement_timeout'] 设置进行调整。默认情况下，不使用此设置。

编辑 /etc/gitlab/gitlab.rb：

ruby
gitlab_rails['db_statement_timeout'] = 45000

在此情况下，客户端 statement_timeout 设置为 45 秒。该值以毫秒为单位。

设置连接超时#

Rails 等待 PostgreSQL 连接尝试成功的时间可以通过 gitlab_rails['db_connect_timeout'] 设置进行调整。默认情况下，不使用此设置：

  1. 编辑 /etc/gitlab/gitlab.rb：

    ruby
    gitlab_rails['db_connect_timeout'] = 5

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

在此情况下，客户端 connect_timeout 设置为 5 秒。该值以秒为单位。适用的最小值为 2 秒。将此设置为 <= 0 或不指定设置将禁用超时。

设置 TCP 控制#

Rails PostgreSQL 适配器提供了一系列 TCP 连接控制，可以进行调整以提高性能。

Linux 软件包未设置这些值的默认值，而是使用 PostgreSQL 适配器提供的默认值。在 gitlab.rb 中使用下表中的参数覆盖它们，然后运行 gitlab-ctl reconfigure。

PostgreSQL 参数gitlab.rb 参数
keepalivesgitlab_rails['db_keepalives']
keepalives_idlegitlab_rails['db_keepalives_idle']
keepalives_intervalgitlab_rails['db_keepalives_interval']
keepalives_countgitlab_rails['db_keepalives_count']
tcp_user_timeoutgitlab_rails['db_tcp_user_timeout']

自动数据库重建索引#

这是一个实验性功能，默认情况下未启用。

在后台重建数据库索引（称为"重建索引"）。这可以用于去除索引中累积的膨胀空间，并有助于保持健康和高效的索引。

可以通过定时任务定期启动重建索引任务。要配置定时任务，应将 gitlab_rails['database_reindexing']['enable'] 设置为 true。

在多节点环境中，此功能应仅在应用程序主机上启用。重建索引过程不能通过 PgBouncer 进行，必须直接连接数据库。

默认情况下，这将在周末（可能是低流量时间）每小时启动一次定时任务。

您可以通过细化以下设置来更改计划：

  1. 编辑 /etc/gitlab/gitlab.rb：

    shell
    gitlab_rails['database_reindexing']['hour'] = '*'
gitlab_rails['database_reindexing']['minute'] = 0
gitlab_rails['database_reindexing']['month'] = '*'
gitlab_rails['database_reindexing']['day_of_month'] = '*'
gitlab_rails['database_reindexing']['day_of_week'] = '0,6'

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

在 HA/Geo 集群中部署的打包 PostgreSQL#

升级极狐GitLab HA 集群#

要在 Patroni 集群中升级 PostgreSQL 版本，请参阅在 Patroni 集群中升级 PostgreSQL 主要版本。

升级极狐GitLab HA Repmgr 集群#

如果您要升级到 PostgreSQL 12，您需要先从 Repmgr 切换到 Patroni，详见从 Repmgr 切换到 Patroni。

这些说明适用于使用 Repmgr 将旧的极狐GitLab 集群升级到 PostgreSQL 11。

如果PostgreSQL 已配置为高可用性，则应在运行 PostgreSQL 的所有节点上运行 pg-upgrade。可以跳过其他节点，但必须与数据库节点运行相同的极狐GitLab 版本。

按照以下步骤升级数据库节点：

  1. 必须在主节点之前升级辅助节点。

    1. 在辅助节点上，编辑 /etc/gitlab/gitlab.rb 以包含以下内容：

      shell
      # 将 X 替换为 DB 节点数 + 1
postgresql['max_replication_slots'] = X

    2. 运行 gitlab-ctl reconfigure 以更新配置。

    3. 运行 sudo gitlab-ctl restart postgresql 以使用新配置重新启动 PostgreSQL。

    4. 在 PostgreSQL 辅助节点上运行 pg-upgrade 时，该节点将被移出集群。

    5. 一旦使用 pg-upgrade 升级了所有辅助节点，用户将只剩下一个只有主节点的单节点集群。

    6. 在辅助节点上，pg-upgrade 不会更新现有数据以匹配新版本，因为这些数据将由主节点的数据替换。然而，它会将现有数据移动到备份位置。

  2. 一旦所有辅助节点都升级完毕，在主节点上运行 pg-upgrade。

    1. 在主节点上，编辑 /etc/gitlab/gitlab.rb 以包含以下内容：

      shell
      # 将 X 替换为 DB 节点数 + 1
postgresql['max_replication_slots'] = X

    2. 运行 gitlab-ctl reconfigure 以更新配置。

    3. 运行 sudo gitlab-ctl restart postgresql 以使用新配置重新启动 PostgreSQL。

    4. 在主节点上，pg-upgrade 将更新现有数据以匹配新的 PostgreSQL 版本。

  3. 通过在每个辅助节点上运行以下命令重新创建辅助节点

    shell
    gitlab-ctl repmgr standby setup MASTER_NODE_NAME

  4. 检查 repmgr 集群是否恢复到原始状态

    shell
    gitlab-ctl repmgr cluster show

在 HA 集群中排除升级故障#

如果在升级到 HA 设置之前，捆绑的 PostgreSQL 曾在某个节点上运行，则可能会保留旧的数据目录。这将导致 gitlab-ctl reconfigure 降级该节点上使用的 PostgreSQL 工具版本。移动（或删除）该目录以防止此问题：

  • mv /var/opt/gitlab/postgresql/data/ /var/opt/gitlab/postgresql/data.$(date +%s)

如果在使用 gitlab-ctl repmgr standby setup MASTER_NODE_NAME 重新创建辅助节点时遇到以下错误，请确保在 /etc/gitlab/gitlab.rb 中包含 postgresql['max_replication_slots'] = X（其中 X 是 DB 节点数 + 1）：

shell
pg_basebackup: could not create temporary replication slot "pg_basebackup_12345": ERROR:  all replication slots are in use
HINT:  Free one or increase max_replication_slots.

升级 Geo 实例#

由于 Geo 默认依赖于 PostgreSQL 流复制，因此在升级极狐GitLab 和/或升级 PostgreSQL 时有以下额外考虑。

使用 Geo 升级 PostgreSQL 时的注意事项#

使用 Geo 时，升级 PostgreSQL 需要在所有二级节点上进行停机。

使用 Geo 时，升级 PostgreSQL 需要在所有二级节点上进行停机，因为这需要重新初始化到 Geo 二级节点的 PostgreSQL 复制。这是由于 PostgreSQL 流复制的工作方式。重新初始化复制会再次复制主节点的所有数据，因此这可能需要很长时间，主要取决于数据库的大小和可用带宽。例如，在传输速度为 30 Mbps，数据库大小为 100 GB 的情况下，重新同步可能需要大约 8 小时。

使用 Geo 时如何升级 PostgreSQL#

要升级 PostgreSQL，您将需要复制槽的名称和复制用户的密码。

  1. 在 Geo 主数据库节点上查找现有复制槽的名称，运行：

    shell
    sudo gitlab-psql -qt -c 'select slot_name from pg_replication_slots'

    如果您在此处找不到 slot_name，或者没有返回输出，您的 Geo 二级节点可能不健康。在这种情况下，请确保二级节点健康且复制正常工作。

    即使查询为空，您也可以尝试使用在Geo 网站管理区域中找到的 slot_name 重新初始化辅助数据库。

  2. 收集复制用户的密码。在设置 Geo 时，在步骤 1. 配置主站点中设置。

  3. 可选。暂停每个辅助站点上的复制以保护其灾难恢复 (DR) 能力。

  4. 手动升级 Geo 主节点上的 PostgreSQL。在 Geo 主数据库节点上运行：

    shell
    sudo gitlab-ctl pg-upgrade

    等待主数据库完成升级，然后开始以下步骤，以便辅助节点可以保留为备份。之后，您可以与辅助数据库并行升级跟踪数据库。

  5. 手动升级 Geo 辅助节点上的 PostgreSQL。在 Geo 辅助数据库和跟踪数据库上运行：

    shell
    sudo gitlab-ctl pg-upgrade

  6. 使用以下命令重新启动 Geo 辅助数据库上的数据库复制：

    shell
    sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME --sslmode=verify-ca

    系统会提示您输入主节点的复制用户密码。将 SECONDARY_SLOT_NAME 替换为从上一步中检索到的槽名称。

  7. 重新配置极狐GitLab 在 Geo 辅助数据库上以更新 pg_hba.conf 文件。这是必需的，因为 replicate-geo-database 将主节点的文件复制到辅助节点。

  8. 如果您在步骤 3 中暂停了复制，恢复每个辅助节点上的复制。然后，重启 puma、sidekiq 和 geo-logcursor。

    shell
    sudo gitlab-ctl hup puma
sudo gitlab-ctl restart sidekiq
sudo gitlab-ctl restart geo-logcursor

  9. 导航到 https://your_primary_server/admin/geo/nodes 并确保所有节点都健康。

连接到 PostgreSQL 数据库#

如果您需要连接到 PostgreSQL 数据库，可以以应用程序用户身份连接：

shell
sudo gitlab-rails dbconsole --database main

故障排除#

将 default_transaction_isolation 设置为 read committed#

如果您在 production/sidekiq 日志中看到类似以下的错误：

plaintext
ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR:  could not serialize access due to concurrent update

很可能是您的数据库的 default_transaction_isolation 配置不符合极狐GitLab 应用程序的要求。您可以通过连接到 PostgreSQL 数据库并运行 SHOW default_transaction_isolation; 来检查此配置。极狐GitLab 应用程序期望配置为 read committed。

此 default_transaction_isolation 配置是在您的 postgresql.conf 文件中设置的。一旦更改配置，您将需要重新启动/重新加载数据库。在包含的 Linux 软件包中的打包 PostgreSQL 服务器中默认提供此配置。

无法加载库 plpgsql.so#

在运行数据库迁移或 PostgreSQL/Patroni 日志中，您可能会看到类似以下的错误：

plaintext
ERROR:  could not load library "/opt/gitlab/embedded/postgresql/12/lib/plpgsql.so": /opt/gitlab/embedded/postgresql/12/lib/plpgsql.so: undefined symbol: EnsurePortalSnapshotExists

此错误是由于在底层版本更改后未重新启动 PostgreSQL 导致的。要修复此错误：

  1. 运行以下命令之一：

    shell
    1# 对于 PostgreSQL
2sudo gitlab-ctl restart postgresql
3
4# 对于 Patroni
5sudo gitlab-ctl restart patroni
6
7# 对于 Geo PostgreSQL
8sudo gitlab-ctl restart geo-postgresql

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

数据库 CPU 负载非常高#

如果数据库 CPU 负载非常高，可能是由于自动取消冗余流水线设置引起的。

要解决此问题：

  • 您可以为数据库服务器分配更多的 CPU 资源。
  • 如果 Sidekiq 负载过重，您可能需要为 ci_cancel_redundant_pipelines 队列添加更多 Sidekiq 进程，如果您的项目有非常大量的流水线。
  • 您可以启用 disable_cancel_redundant_pipelines_service 特性标志以在实例范围内禁用此设置，并查看 CPU 负载是否下降。这会为所有项目禁用该特性，可能导致不再被自动取消的流水线增加资源使用量。