数据库设置

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

因此，您有两个选项可以让数据库服务器与 Omnibus GitLab 一起使用：

使用 Omnibus GitLab 附带打包的 PostgreSQL 服务器（不需要配置，推荐）。
使用外部 PostgreSQL 服务器。

使用 Omnibus GitLab 附带的 PostgreSQL 数据库服务

重新配置和 PostgreSQL 重新启动

如果在 gitlab.rb 文件中更改了任何服务的配置设置，Omnibus 通常会在重新配置时重新启动这些服务。PostgreSQL 的独特之处在于它的一些设置将通过重新加载 (HUP) 生效，而其他设置则需要重新启动 PostgreSQL。由于管理员经常希望对 PostgreSQL 重新启动的确切时间进行更多控制，因此 Omnibus 已配置为在重新配置时重新加载 PostgreSQL，而不是重新启动。这意味着如果您修改了任何需要重新启动的 PostgreSQL 设置，您将需要在重新配置后手动重新启动 PostgreSQL。

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

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

如果更改设置需要重新启动，则查询将返回设置的名称以及正在运行的 PostgreSQL 实例中该设置的当前值。

PostgreSQL 版本变化时自动重启

默认情况下，当底层版本发生变化时，Omnibus 会自动重启 PostgreSQL，如上游文档所述。可以通过可用于 postgresql 和 geo-postgresql 的 auto_restart_on_version_change 设置来控制此行为。

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

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

# For PostgreSQL/Patroni
postgresql['auto_restart_on_version_change'] = false

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

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

强烈建议在底层版本更改时重新启动 PostgreSQL，以避免出现与加载必要库有关的错误相似的错误。

配置 SSL

Omnibus 自动在 PostgreSQL 服务器上启用 SSL，但默认情况下它会接受加密和未加密的连接。强制 SSL 需要使用 pg_hba.conf 中的 hostssl 配置。有关更多详细信息，请参阅 pg_hba.conf 文档。

SSL 支持取决于以下文件：

数据库的公共 SSL 证书 (server.crt)。
SSL 证书的相应私钥 (server.key)。
验证服务器证书（root.crt）的根证书包。默认情况下，Omnibus GitLab 使用 /opt/gitlab/embedded/ssl/certs/cacert.pem 中的嵌入式证书包。这不是自签名证书所必需的。

Omnibus GitLab 将生成一个 10 年的自签名证书和私钥以供使用。如果您更喜欢使用 CA 签名证书或将其替换为您自己的自签名证书，请使用以下步骤。

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

有关更多详细信息，请参阅 PostgreSQL 文档。

请注意，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：

编辑 /etc/gitlab/gitlab.rb：

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）为根。

重新配置极狐GitLab 使更改生效
重启 PostgreSQL 使更改生效：
```
gitlab-ctl restart postgresql
```
如果 PostgreSQL 无法启动，请检查日志（例如 /var/log/gitlab/postgresql/current）以获取更多详细信息。

Require SSL

添加以下配置到 /etc/gitlab/gitlab.rb：
```
 gitlab_rails['db_sslmode'] = 'require'
```
重新配置极狐GitLab 使更改生效。
重启 PostgreSQL 使更改生效：
```
gitlab-ctl restart postgresql
```
如果 PostgreSQL 无法启动，请检查日志（例如 /var/log/gitlab/postgresql/current）以获取更多详细信息。

禁用 SSL

添加以下配置到 /etc/gitlab/gitlab.rb：
```
postgresql['ssl'] = 'off'
```
重新配置极狐GitLab 使更改生效。
重启 PostgreSQL 使更改生效：
```
gitlab-ctl restart postgresql
```
如果 PostgreSQL 无法启动，请检查日志（例如 /var/log/gitlab/postgresql/current）以获取更多详细信息。

验证是否正在使用 SSL

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

在 14.2 和之后的版本：

sudo gitlab-rails dbconsole --database main

在 14.1 和之前的版本：

sudo gitlab-rails dbconsole

在启动时，您应该看到如下提示：

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

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

SELECT * FROM pg_stat_ssl;

例如：

gitlabhq_production=> select * from pg_stat_ssl;
 pid  | ssl | version |         cipher         | bits | compression |  clientdn
------+-----+---------+------------------------+------+-------------+------------
| f   |         |                        |      |             |
| f   |         |                        |      |             |
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| f   |         |                        |      |             |
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           |
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| f   |         |                        |      |             |
| f   |         |                        |      |             |
| f   |         |                        |      |             |
(16 rows)

在 ssl 列下列出了 t 的行被启用。
在 clientdn 中具有值的行正在使用 cert 身份验证方法

配置 SSL 客户端身份验证

客户端 SSL 证书可用于对数据库服务器进行身份验证。创建证书超出了 omnibus-gitlab 的范围。但是拥有现有 SSL 证书管理解决方案的用户可以使用它。

配置数据库服务器

为服务器创建证书和密钥，公用名称应等于服务器的 DNS 名称
将服务器证书、密钥和 CA 文件复制到 PostgreSQL 服务器，并确保权限正确
1. 证书应归数据库用户所有（默认：gitlab-psql）
2. 密钥文件应归数据库用户所有，其权限应为 0400
3. CA文件应归数据库用户所有，其权限应为 0400
不要为这些文件使用文件名 server.crt 或 server.key。这些文件名保留供 omnibus-gitlab 内部使用。

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

postgresql['ssl_cert_file'] = 'PATH_TO_CERTIFICATE'
postgresql['ssl_key_file'] = 'PATH_TO_KEY_FILE'
postgresql['ssl_ca_file'] = 'PATH_TO_CA_FILE'
postgresql['listen_address'] = 'IP_ADDRESS'
postgresql['cert_auth_addresses'] = {
'IP_ADDRESS' => {
  'database' => 'gitlabhq_production',
  'user' => 'gitlab'
}

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

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

配置 Rails 客户端

为了让 rails 客户端连接到服务器，您需要一个证书和密钥，其中 commonName 设置为 gitlab，由在数据库服务器上的 ssl_ca_file 中指定的 CA 文件中信任的证书颁发机构签名。

配置 gitlab.rb

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'

运行 gitlab-ctl reconfigure 使 rails 客户端使用新设置。
按照验证是否正在使用 SSL 中的步骤确保身份验证正常工作。

配置打包的 PostgreSQL 服务器以侦听 TCP/IP

打包的 PostgreSQL 服务器可以配置为侦听 TCP/IP 连接，但需要注意的是，某些非关键脚本需要 UNIX 套接字并且可能会出现错误行为。

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

配置 PostgreSQL 块

postgresql 块中的以下设置会受到影响：

listen_address：控制 PostgreSQL 将侦听的地址。
port：控制 PostgreSQL 将侦听的端口，如果设置了 listen_address，则 必须设置。
md5_auth_cidr_addresses：在使用密码进行身份验证后，允许连接到服务器的 CIDR 地址块列表。
trust_auth_cidr_addresses：允许连接到服务器的 CIDR 地址块列表，无需任何类型的身份验证。要非常小心的设置。建议限制在 127.0.0.1/24 甚至 127.0.0.1/32 的环回地址。
sql_user：控制用于 MD5 身份验证的预期用户名。这默认为gitlab，不是必需的设置。
sql_user_password：设置 PostgreSQL 将接受的用于 MD5 身份验证的密码。将以下示例中的 securesqlpassword 替换为可接受的密码。

编辑 /etc/gitlab/gitlab.rb：

postgresql['listen_address'] = '0.0.0.0'
postgresql['port'] = 5432
postgresql['md5_auth_cidr_addresses'] = %w()
postgresql['trust_auth_cidr_addresses'] = %w(127.0.0.1/24)
postgresql['sql_user'] = "gitlab"

##! SQL_USER_PASSWORD_HASH can be generated using the command `gitlab-ctl pg-password-md5 gitlab`,
##! where `gitlab` is the name of the SQL user that connects to GitLab.
postgresql['sql_user_password'] = "SQL_USER_PASSWORD_HASH"

# force ssl on all connections defined in trust_auth_cidr_addresses and md5_auth_cidr_addresses
postgresql['hostssl'] = true

重新配置极狐GitLab 并重启 PostrgreSQL：

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'] 块中的一个实例连接到 PostgreSQL，则必须提供。如果您连接到 127.0.0.1 并且已经配置了 postgresql['trust_auth_cidr_addresses'] 以包含它，则这不是必需的。

编辑 /etc/gitlab/gitlab.rb：

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

重新配置极狐GitLab 并重启 PostrgreSQL：

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

应用并重启服务

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

Omnibus 包的一些包含脚本（例如gitlab-psql）期望通过 UNIX 套接字处理与 PostgreSQL 的连接，并且可能无法正常运行。您可以在不禁用 UNIX 套接字的情况下启用 TCP/IP。

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

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

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

要启用 WAL 归档：

编辑 /etc/gitlab/gitlab.rb：

# Replication settings
postgresql['sql_replication_user'] = "gitlab_replicator"
postgresql['wal_level'] = "replica"
    ...
    ...
# Backup/Archive settings
postgresql['archive_mode'] = "on"
postgresql['archive_command'] = "/your/wal/archiver/here"
postgresql['archive_timeout'] = "60"

重新配置极狐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 数据的位置

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

这是侵入性操作。在现有安装上不停机就无法完成。

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

升级打包的 PostgreSQL 服务器

Omnibus GitLab 提供了 gitlab-ctl pg-upgrade 命令来将打包的 PostgreSQL 服务器更新到更高版本（如果包中包含）。在软件包升级期间将 PostgreSQL 更新为默认打包版本，除非特别选择退出。

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

要升级 PostgreSQL 版本，请确保：

您正在运行支持您当前版本的 PostgreSQL 的最新版本的极狐GitLab。
如果您最近升级过，则在继续之前运行 sudo gitlab-ctl reconfigure。
您有足够的磁盘空间用于数据库的两个副本。除非您有足够的可用空间，否则请勿尝试升级。
- 使用 sudo du -sh /var/opt/gitlab/postgresql/data 检查你的数据库大小（或更新到你的数据库路径）。
- 使用 sudo df -h 检查可用空间。如果数据库所在的分区没有足够的空间，则将参数--tmp-dir $DIR 传递给命令。13.3 及更高版本包括可用磁盘空间检查，如果不满足要求，将中止升级。

在您确认满足以上清单后，您可以继续升级：

sudo gitlab-ctl pg-upgrade

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

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

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

升级完成后，验证一切是否按预期工作。

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

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：

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

在验证您的 GitLab 实例运行正常后，您可以清理旧的数据库文件：

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

您可以在 Omnibus GitLab 附带的 PostgreSQL 版本文档中找到多种 GitLab 版本附带的 PostgreSQL 版本的详细信息。

选择退出自动 PostgreSQL 升级

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

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

16.2 及更高版本

从 16.2 版本开始，PostgreSQL 13.11 和 14.8 都随 Omnibus 一起提供。在软件包升级期间，数据库不会升级到 PostgreSQL 14。如果您想升级到 PostgreSQL 14，则必须手动执行此操作：

sudo gitlab-ctl pg-upgrade -V 14

Geo 部署不支持 PostgreSQL 14，但计划在未来版本中支持。

16.0 及更高版本

PostgreSQL 版本 12 不再受支持，二进制文件已被删除。管理员必须：

确保安装使用 PostgreSQL 13。

15.11 及更高版本

在极狐GitLab 15.11 中，PostgreSQL 会自动升级到 13.x，以下情况除外：

在以下任何情况下都会跳过升级：

您正在使用 Patroni，运行数据库时保持高可用性。
您的数据库节点是极狐GitLab Geo 配置的一部分。
您已明确选择退出升级。
您的 gitlab.rb 中有 postgresql['version'] = 12。

容错和 Geo 安装实例支持手动升级到 PostgreSQL 13，请参阅部署在 HA/Geo 集群中的打包 PostgreSQL。

15.0 及更高版本

从 15.0 版本开始，新安装实例将默认使用 PostgreSQL 13。

现有的单个数据库节点实例可以通过以下方式手动更新：

sudo gitlab-ctl pg-upgrade -V 13

在删除 PostgreSQL 12 之前，如果出于兼容性或测试环境原因的需要，管理员可以固定 PostgreSQL 版本。

容错和 Geo 安装实例需要额外的步骤和规划。

14.0 及更高版本

不再支持 PostgreSQL 版本 11，二进制文件已被删除。要继续，管理员必须：

确保安装使用 PostgreSQL 12。
如果使用 repmgr，转换为使用 patroni。

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

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

在附带多个 PostgreSQL 版本的 GitLab 版本上，用户可以使用 gitlab-ctl revert-pg-upgrade 命令将已经升级的 PostgreSQL 版本降级到早期版本。此命令还支持 -V 标志为包中提供两个以上 PostgreSQL 版本的场景指定目标版本（例如：GitLab 12.8，其中提供了 PostgreSQL 9.6.x、10.x 和 11.x）。

要指定目标 PostgreSQL 版本 12：

gitlab-ctl revert-pg-upgrade -V 12

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

在仅提供一个 PostgreSQL 版本的其他 GitLab 版本上，您无法降级 PostgreSQL 版本。为此，您必须将 GitLab 降级到旧版本。

配置多数据库连接

gitlab:db:decomposition:connection_status Rake 任务引入于 15.11 版本。

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

要选择加入此功能，您首先需要确保 PostgreSQL 的 max_connections 足够高（使用超过可用最大连接数的 50%）。您可以通过运行以下 Rake 任务来验证：

sudo gitlab-rake gitlab:db:decomposition:connection_status

如果任务中 max_connections 足够高，您可以通过在 /etc/gitlab/gitlab.rb 中更新此设置来启用此功能：

gitlab_rails['databases']['ci']['enable'] = true

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

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

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

编辑 /etc/gitlab/gitlab.rb：

# Disable the built-in Postgres
postgresql['enable'] = false

# Fill in the connection details for database.yml
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'utf8'
gitlab_rails['db_host'] = '127.0.0.1'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_username'] = 'USERNAME'
gitlab_rails['db_password'] = 'PASSWORD'

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

请注意：

/etc/gitlab/gitlab.rb 应该具有文件权限 0600，因为它包含纯文本密码。
PostgreSQL 允许监听多个地址
如果在 gitlab_rails['db_host'] 中使用多个地址，以逗号分隔，则列表中的第一个地址将用于连接。

重新配置极狐GitLab 使更改生效。
播种数据库。

非打包 PostgreSQL 的 UNIX 套接字配置

如果您想使用系统的 PostgreSQL 服务器（安装在与 GitLab 相同的系统上）而不是与 GitLab 捆绑在一起的服务器，您可以使用 UNIX 套接字来实现：

编辑 /etc/gitlab/gitlab.rb：

# Disable the built-in Postgres
postgresql['enable'] = false

# Fill in the connection details for database.yml
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'utf8'
# The path where the socket lives
gitlab_rails['db_host'] = '/var/run/postgresql/'

重新配置 GitLab 以使更改生效：
```
sudo gitlab-ctl-reconfigure
```

配置 SSL

Require SSL

添加以下配置到 /etc/gitlab/gitlab.rb：
```
gitlab_rails['db_sslmode'] = 'require'
```
重新配置极狐GitLab 使更改生效。
重新启动 PostgreSQL 以使更改生效：
```
gitlab-ctl restart postgresql
```
如果 PostgreSQL 无法启动，请检查日志（例如 /var/log/gitlab/postgresql/current）以获取更多详细信息。

Require SSL 并根据 CA 包验证服务器证书

PostgreSQL 可以配置为 require SSL 并根据 CA 包验证服务器证书以防止欺骗。 gitlab_rails['db_sslrootcert'] 中指定的 CA 包必须包含根证书和中间证书。

添加以下配置到 /etc/gitlab/gitlab.rb：
```
gitlab_rails['db_sslmode'] = "verify-full"
gitlab_rails['db_sslrootcert'] = "your-full-ca-bundle.pem"
```
如果您将 Amazon RDS 用于 PostgreSQL 服务器，请确保为 gitlab_rails['db_sslrootcert'] 下载并使用 combined CA bundle。可以在 AWS 的使用 SSL/TLS 加密与数据库实例的连接文章中找到关于此的更多信息。
重新配置极狐GitLab 使更改生效。
重新启动 PostgreSQL 以使更改生效：
```
gitlab-ctl restart postgresql
```
如果 PostgreSQL 无法启动，请检查日志（例如 /var/log/gitlab/postgresql/current）以获取更多详细信息。

播种数据库 (仅全新安装)

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

Omnibus GitLab 不会播种您的外部数据库。运行以下命令以导入 schema 并创建第一个管理用户： shell # Remove 'sudo' if you are the 'git' user sudo gitlab-rake gitlab:setup

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

gitlab_rails['initial_root_password'] = 'nonstandardpassword'

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

gitlab_rails['initial_shared_runners_registration_token'] = 'token'

固定打包的 PostgreSQL 版本（仅限全新安装）

14.1 及更高版本同时提供 Postgres 12 和 Postgres 13。14.0 版本仅提供 PostgreSQL 12。13.3 及更高版本同时提供 Postgres 11 和 Postgres 12。13.0 到 13.2 版本仅提供 PostgreSQL 11。

Omnibus GitLab 将使用默认版本初始化 PostgreSQL。

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

在初始重新配置后，使用 Omnibus 打包的 PostgreSQL 时，设置 postgresql['version'] 将输出有关在不同版本的 PostgreSQL 上初始化数据目录的错误。如果遇到这种情况，请参阅将打包的 PostgreSQL 服务器恢复到以前的版本。

故障排查

将 `default_transaction_isolation` 设置为 `read committed`

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

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 文件中设置。更改配置后，您将需要重新启动/重新加载数据库。默认情况下，Omnibus GitLab 附带的打包 PostgreSQL 服务器中包含此配置。

无法加载库 `plpgsql.so`

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

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 造成的。修复此错误：

运行以下命令之一：

# For PostgreSQL
sudo gitlab-ctl restart postgresql

# For Patroni
sudo gitlab-ctl restart patroni

# For Geo PostgreSQL
sudo gitlab-ctl restart geo-postgresql

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

数据库的应用程序设置

禁用自动数据库迁移

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

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

# Enable or disable automatic database migrations
# on all hosts except the designated deploy node
gitlab_rails['auto_migrate'] = false

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

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

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

设置客户端 statement_timeout

现在可以使用 gitlab_rails['db_statement_timeout'] 设置来调整 Rails 在超时之前等待数据库事务完成的时间量。默认情况下，不使用此设置。

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['db_statement_timeout'] = 45000

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

设置连接超时

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

编辑 /etc/gitlab/gitlab.rb：
```
gitlab_rails['db_connect_timeout'] = 5
```
重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

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

设置 tcp 控制

Rails PostgreSQL 适配器提供了一系列 TCP 连接控件，可以对其进行调整以提高性能。有关每个参数的更多信息，请参阅 PostgreSQL 上游文档。

Omnibus 没有为这些值设置默认值，而是使用 PostgreSQL 适配器提供的默认值。使用下表中注明的参数在 gitlab.rb 中覆盖它们，然后运行 gitlab-ctl reconfigure。

PostgreSQL 参数	`gitlab.rb` 参数
`keepalives`	`gitlab_rails['db_keepalives']`
`keepalives_idle`	`gitlab_rails['db_keepalives_idle']`
`keepalives_interval`	`gitlab_rails['db_keepalives_interval']`
`keepalives_count`	`gitlab_rails['db_keepalives_count']`
`tcp_user_timeout`	`gitlab_rails['db_tcp_user_timeout']`

数据库自动重新索引

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

在后台重新创建数据库索引（称为“重新索引”）。这可用于删除索引中积累的膨胀空间，并有助于维护健康和高效的索引。

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

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

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

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

编辑 /etc/gitlab/gitlab.rb：

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'

重新配置极狐GitLab：
```
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 被配置为高可用，pg-upgrade 应该在所有运行 PostgreSQL 的节点上运行。可以跳过其它节点，但必须与数据库节点运行相同的 GitLab 版本。

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

次要节点必须在主节点之前升级。
1. 在次要节点上，编辑 /etc/gitlab/gitlab.rb 以包含以下内容：
```
# Replace X with the number of DB nodes + 1
postgresql['max_replication_slots'] = X
```
1. 运行 gitlab-ctl reconfigure 来更新配置。
2. 运行 sudo gitlab-ctl restart postgresql 来让 PostgreSQL 使用新配置重新启动。
3. 在 PostgreSQL 次要节点上运行 pg-upgrade 时，该节点将从集群中删除。
4. 一旦所有次要节点都使用 pg-upgrade 升级，用户将得到一个只有主节点的单节点集群。
5. pg-upgrade，在次要节点上不会更新现有数据以匹配新版本，因为该数据将被来自主节点的数据替换。但是，它会将现有数据移动到备份位置。
升级所有次要节点后，在主节点上运行 pg-upgrade。
1. 在主节点上，编辑 /etc/gitlab/gitlab.rb 以包含以下内容：
```
# Replace X with the number of DB nodes + 1
postgresql['max_replication_slots'] = X
```
1. 运行 gitlab-ctl reconfigure 来更新配置。
2. 运行 sudo gitlab-ctl restart postgresql 来让 PostgreSQL 使用新配置重新启动。
3. 在主节点上，pg-upgrade 将更新现有数据以匹配新的 PostgreSQL 版本。
通过在每个节点上运行以下命令来重新创建次要节点
```
gitlab-ctl repmgr standby setup MASTER_NODE_NAME
```
检查 repmgr 集群是否恢复到原始状态
```
gitlab-ctl repmgr cluster show
```

对 HA 集群中的升级进行故障排查

如果在某个时刻，捆绑的 PostgreSQL 在升级到 HA 设置之前已经在节点上运行，则旧数据目录可能会保留。这将导致 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 重新创建次要节点时遇到以下错误，请确保postgresql['max_replication_slots'] = X，在 /etc/gitlab/gitlab.rb 中将 X 替换为数据库节点数量 + 1：

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 需要在所有次要节点上停机，因为需要将 PostgreSQL 复制重新初始化到 Geo 次要节点。这是由于 PostgreSQL 流式复制的工作方式造成的。重新初始化复制再次从主节点复制所有数据，因此可能需要很长时间，主要取决于数据库的大小和可用带宽。例如，在 30 Mbps 的传输速度和 100 GB 的数据库大小下，重新同步可能需要大约 8 小时。有关更多信息，请参阅 PostgreSQL 文档。

使用 Geo 时如何升级 PostgreSQL

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

在 Geo 主数据库节点上找到现有 replication slot 的名称，运行：
```
sudo gitlab-psql -qt -c 'select slot_name from pg_replication_slots'
```
如果您在此处找不到您的 slot_name，或者没有返回任何输出，则您的 Geo secondaries 可能不健康。在这种情况下，请确保次要节点是健康的并且复制正在工作。
收集复制用户的密码。
在 Geo 主服务器上手动升级 PostgreSQL。在 Geo 主数据库节点上运行：
```
sudo gitlab-ctl pg-upgrade
```
等待主数据库完成升级，然后再开始下一步，以便次要数据库可以作为备份保持准备就绪。之后，您可以与次要数据库并行升级跟踪数据库。
在 Geo 次要节点上手动升级 PostgreSQL。在 Geo 次要数据库和跟踪数据库上运行：
```
sudo gitlab-ctl pg-upgrade
```
使用以下命令重新启动 Geo 次要数据库上的数据库复制：
```
sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME
```
系统将提示您输入主复制用户的密码。将 SECONDARY_SLOT_NAME 替换为从上述第一步中检索到的 slot 名称。
在 Geo 次要数据库上重新配置 GitLab 更新 pg_hba.conf 文件。这是必需的，因为 replicate-geo-database 将主节点的文件复制到次要节点。

重启 puma、sidekiq 和 geo-logcursor。

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

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

数据库设置

使用 Omnibus GitLab 附带的 PostgreSQL 数据库服务

重新配置和 PostgreSQL 重新启动

PostgreSQL 版本变化时自动重启

配置 SSL

Require SSL

禁用 SSL

验证是否正在使用 SSL

配置 SSL 客户端身份验证

配置数据库服务器

配置 Rails 客户端

配置打包的 PostgreSQL 服务器以侦听 TCP/IP

配置 PostgreSQL 块

配置 GitLab Rails 块

应用并重启服务

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

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

升级打包的 PostgreSQL 服务器

选择退出自动 PostgreSQL 升级

16.2 及更高版本

16.0 及更高版本

15.11 及更高版本

15.0 及更高版本

14.0 及更高版本

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

配置多数据库连接

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

非打包 PostgreSQL 的 UNIX 套接字配置

配置 SSL

Require SSL

Require SSL 并根据 CA 包验证服务器证书

播种数据库 (仅全新安装)

固定打包的 PostgreSQL 版本（仅限全新安装）

故障排查

将 default_transaction_isolation 设置为 read committed

无法加载库 plpgsql.so

数据库的应用程序设置

禁用自动数据库迁移

设置客户端 statement_timeout

设置连接超时

设置 tcp 控制

数据库自动重新索引

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

升级 GitLab HA 集群

升级 GitLab HA Repmgr 集群

对 HA 集群中的升级进行故障排查

升级 Geo 实例

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

使用 Geo 时如何升级 PostgreSQL

将 `default_transaction_isolation` 设置为 `read committed`

无法加载库 `plpgsql.so`