Help us learn about your current experience with the documentation. Take the survey.

维护 Rake 任务

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

GitLab 提供了用于常规维护的 Rake 任务。

收集 GitLab 和系统信息

此命令收集有关您的 GitLab 安装及其运行所在系统的信息。在请求帮助或报告问题时，这些信息可能很有用。在多节点环境中，请在运行 GitLab Rails 的节点上运行此命令，以避免 PostgreSQL 套接字错误。

Linux 软件包安装：
```
sudo gitlab-rake gitlab:env:info
```

自编译安装：

bundle exec rake gitlab:env:info RAILS_ENV=production

示例输出：

System information
System:         Ubuntu 20.04
Proxy:          no
Current User:   git
Using RVM:      no
Ruby Version:   2.7.6p219
Gem Version:    3.1.6
Bundler Version:2.3.15
Rake Version:   13.0.6
Redis Version:  6.2.7
Sidekiq Version:6.4.2
Go Version:     unknown

GitLab information
Version:        15.5.5-ee
Revision:       5f5109f142d
Directory:      /opt/gitlab/embedded/service/gitlab-rails
DB Adapter:     PostgreSQL
DB Version:     13.8
URL:            https://app.gitaly.gcp.gitlabsandbox.net
HTTP Clone URL: https://app.gitaly.gcp.gitlabsandbox.net/some-group/some-project.git
SSH Clone URL:  git@app.gitaly.gcp.gitlabsandbox.net:some-group/some-project.git
Elasticsearch:  no
Geo:            no
Using LDAP:     no
Using Omniauth: yes
Omniauth Providers:

GitLab Shell
Version:        14.12.0
Repository storage paths:
- default:      /var/opt/gitlab/git-data/repositories
- gitaly:       /var/opt/gitlab/git-data/repositories
GitLab Shell path:              /opt/gitlab/embedded/service/gitlab-shell


Gitaly
- default Address:      unix:/var/opt/gitlab/gitaly/gitaly.socket
- default Version:      15.5.5
- default Git Version:  2.37.1.gl1
- gitaly Address:       tcp://10.128.20.6:2305
- gitaly Version:       15.5.5
- gitaly Git Version:   2.37.1.gl1

显示 GitLab 许可证信息

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

此命令显示您的 GitLab 许可证信息以及已使用的席位数量。它仅在 GitLab Enterprise 安装上可用：许可证无法安装到 GitLab Community Edition 中。

在向支持团队提交工单或以编程方式检查许可证参数时，这些信息可能很有用。

Linux 软件包安装：
```
sudo gitlab-rake gitlab:license:info
```

自编译安装：

bundle exec rake gitlab:license:info RAILS_ENV=production

示例输出：

Today's Date: 2020-02-29
Current User Count: 30
Max Historical Count: 30
Max Users in License: 40
License valid from: 2019-11-29 to 2020-11-28
Email associated with license: user@example.com

检查 GitLab 配置

gitlab:check Rake 任务运行以下 Rake 任务：

gitlab:gitlab_shell:check
gitlab:gitaly:check
gitlab:sidekiq:check
gitlab:incoming_email:check
gitlab:ldap:check
gitlab:app:check
gitlab:geo:check（仅当您运行 Geo 时）

它会检查每个组件是否按照安装指南进行了设置，并为发现的问题建议修复方案。此命令必须从您的应用服务器运行，在 Gitaly 等组件服务器上无法正确运行。

您还可以查看我们的故障排除指南：

GitLab。
Linux 软件包安装。

此外，您还应该验证可以使用当前密钥解密数据库值。

要运行 gitlab:check，请运行：

Linux 软件包安装：
```
sudo gitlab-rake gitlab:check
```

自编译安装：

bundle exec rake gitlab:check RAILS_ENV=production

Kubernetes 安装：
```
kubectl exec -it <toolbox-pod-name> -- sudo gitlab-rake gitlab:check
```
由于基于 Helm 的 GitLab 安装的特殊架构，输出可能包含对 gitlab-shell、Sidekiq 和 systemd 相关文件的连接验证的假阴性结果。这些报告的失败是预期的，并不表示实际问题，在查看诊断结果时请忽略它们。

如果您想从输出中省略项目名称，请对 gitlab:check 使用 SANITIZE=true。

示例输出：

Checking Environment ...

Git configured for git user? ... yes
Has python2? ... yes
python2 is supported version? ... yes

Checking Environment ... Finished

Checking GitLab Shell ...

GitLab Shell version? ... OK (1.2.0)
Repo base directory exists? ... yes
Repo base directory is a symlink? ... no
Repo base owned by git:git? ... yes
Repo base access is drwxrws---? ... yes
post-receive hook up-to-date? ... yes
post-receive hooks in repos are links: ... yes

Checking GitLab Shell ... Finished

Checking Sidekiq ...

Running? ... yes

Checking Sidekiq ... Finished

Checking GitLab App...

Database config exists? ... yes
Database is SQLite ... no
All migrations up? ... yes
GitLab config exists? ... yes
GitLab config up to date? ... no
Cable config exists? ... yes
Resque config exists? ... yes
Log directory writable? ... yes
Tmp directory writable? ... yes
Init script exists? ... yes
Init script up-to-date? ... yes
Redis version >= 2.0.0? ... yes

Checking GitLab ... Finished

重建 `authorized_keys` 文件

在某些情况下，需要重建 authorized_keys 文件，例如，如果在升级后通过 SSH 推送时收到 Permission denied (publickey) 错误，并在 gitlab-shell.log 文件中发现 404 Key Not Found 错误。要重建 authorized_keys，请运行：

Linux 软件包安装：
```
sudo gitlab-rake gitlab:shell:setup
```

自编译安装：

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production

示例输出：

This will rebuild an authorized_keys file.
You will lose any data stored in authorized_keys file.
Do you want to continue (yes/no)? yes

清除 Redis 缓存

如果由于某种原因仪表板显示错误信息，您可能需要清除 Redis 缓存。为此，请运行：

Linux 软件包安装：
```
sudo gitlab-rake cache:clear
```

自编译安装：

cd /home/git/gitlab
sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production

预编译资源

有时在版本升级过程中，您可能会遇到一些错误的 CSS 或缺少某些图标。在这种情况下，请尝试再次预编译资源。

此 Rake 任务仅适用于自编译安装。阅读更多关于在运行 Linux 软件包时解决此问题的信息。 Linux 软件包的指南可能适用于 GitLab 的 Kubernetes 和 Docker 部署，尽管通常基于容器的安装不会出现缺少资源的问题。

自编译安装：

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production

对于 Linux 软件包安装，未优化的资源（JavaScript、CSS）在上游 GitLab 发布时被冻结。 Linux 软件包安装包含这些资源的优化版本。除非您在安装软件包后在生产机器上修改 JavaScript / CSS 代码，否则没有理由在生产机器上重新执行 rake gitlab:assets:compile。如果您怀疑资源已损坏，您应该重新安装 Linux 软件包。

检查到远程站点的 TCP 连接性

有时您需要知道您的 GitLab 安装是否可以连接到另一台机器上的 TCP 服务（例如 PostgreSQL 或 Web 服务器）以排查代理问题。这里包含一个 Rake 任务来帮助您完成此操作。

Linux 软件包安装：

sudo gitlab-rake gitlab:tcp_check[example.com,80]

自编译安装：

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:tcp_check[example.com,80] RAILS_ENV=production

清除独占租约（危险）

GitLab 使用共享锁机制：ExclusiveLease 来防止在共享资源上同时操作。一个例子是在存储库上运行定期垃圾收集。

在非常特定的情况下，被独占租约锁定的操作可能会失败而不释放锁。如果您无法等待它过期，可以运行此任务来手动清除它。

要清除所有独占租约：

不要在 GitLab 或 Sidekiq 运行时运行它

sudo gitlab-rake gitlab:exclusive_lease:clear

要指定租约 type 或租约 type + id，请指定范围：

# 清除存储库垃圾收集的所有租约：
sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:*]

# 清除特定项目中存储库垃圾收集的租约：(id=4)
sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:4]

显示数据库迁移状态

有关在升级 GitLab 时检查迁移是否完成的信息，请参阅后台迁移文档。

要检查特定迁移的状态，您可以使用以下 Rake 任务：

sudo gitlab-rake db:migrate:status

要检查 Geo 辅助站点上的跟踪数据库，您可以使用以下 Rake 任务：

sudo gitlab-rake db:migrate:status:geo

这将输出一个表格，其中每个迁移的 Status 为 up 或 down。示例：

database: gitlabhq_production

 Status   Migration ID    Type     Milestone    Name
--------------------------------------------------
   up     20240701074848  regular  17.2         AddGroupIdToPackagesDebianGroupComponents
   up     20240701153843  regular  17.2         AddWorkItemsDatesSourcesSyncToIssuesTrigger
   up     20240702072515  regular  17.2         AddGroupIdToPackagesDebianGroupArchitectures
   up     20240702133021  regular  17.2         AddWorkspaceTerminationTimeoutsToRemoteDevelopmentAgentConfigs
   up     20240604064938  post     17.2         FinalizeBackfillPartitionIdCiPipelineMessage
   up     20240604111157  post     17.2         AddApprovalPolicyRulesFkOnApprovalGroupRules

从 GitLab 17.1 开始，迁移按照符合 GitLab 发布节奏的顺序执行。

运行未完成的数据库迁移

数据库迁移可能卡在未完成状态，在 sudo gitlab-rake db:migrate:status 命令的输出中状态为 down。

要完成这些迁移，请使用以下 Rake 任务：
```
sudo gitlab-rake db:migrate
```
命令完成后，运行 sudo gitlab-rake db:migrate:status 检查是否所有迁移都已完成（状态为 up）。

热重载 puma 和 sidekiq 服务：

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

从 GitLab 17.1 开始，迁移按照符合 GitLab 发布节奏的顺序执行。

重建数据库索引

在生产环境中运行时请谨慎使用，并在非高峰时段运行。

可以定期重建数据库索引以回收空间并随时间保持健康的索引膨胀水平。重建索引也可以作为常规 cron 作业运行。 “健康"的膨胀水平高度依赖于特定索引，但通常应低于 30%。

先决条件：

此功能需要 PostgreSQL 12 或更高版本。
这些索引类型不支持：表达式索引和用于约束排除的索引。

运行重建索引

以下任务仅重建每个数据库中膨胀程度最高的两个索引。要重建超过两个索引，请再次运行该任务，直到所有所需索引都已重建。

运行重建索引任务：
```
sudo gitlab-rake gitlab:db:reindex
```
检查 application_json.log 以验证执行或进行故障排除。

自定义重建索引设置

对于较小的实例或调整重建索引行为，您可以使用 Rails 控制台修改这些设置：

sudo gitlab-rails console

然后自定义配置：

# 将最小索引大小降低到 100 MB（默认为 1 GB）
Gitlab::Database::Reindexing.minimum_index_size!(100.megabytes)

# 将最小膨胀阈值更改为 30%（默认为 20%，设置更低没有好处）
Gitlab::Database::Reindexing.minimum_relative_bloat_size!(0.3)

自动重建索引

对于具有大量数据库的大型实例，通过安排在低活动期间运行来自动化数据库重建索引。

使用 crontab 调度

对于打包的 GitLab 安装，使用 crontab：

编辑 crontab：
```
sudo crontab -e
```

根据您首选的计划添加条目：

选项 1：在安静时段每天运行

# 每天在 21:12 运行数据库重建索引
# 日志将由打包的 logrotate 守护进程轮换
12 21 * * * /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1

选项 2：仅在周末运行

# 在周末凌晨 01:00 运行数据库重建索引
0 1 * * 0,6 /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1

选项 3：在低流量时段频繁运行

# 在夜间时段（22:00-07:00）每 3 小时运行一次数据库重建索引
0 22,1,4,7 * * * /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1

对于 Kubernetes 部署，您可以使用 CronJob 资源创建类似的计划来运行重建索引任务。

注意事项

重建数据库索引是一个磁盘密集型任务，因此您应该在非高峰时段执行该任务。在高峰时段运行任务可能导致膨胀增加，也可能导致某些查询执行缓慢。
该任务需要为正在重建的索引提供可用磁盘空间。创建的索引会附加 _ccnew 后缀。如果重建索引任务失败，重新运行该任务会清理临时索引。
数据库索引重建完成所需的时间取决于目标数据库的大小。可能需要几个小时到几天不等。
该任务使用 Redis 锁，可以安全地安排它频繁运行。如果另一个重建索引任务已经在运行，它将不会执行任何操作。

转储数据库架构

在极少数情况下，即使所有数据库迁移都已完成，数据库架构也可能与应用程序代码期望的不同。如果确实发生这种情况，可能会导致 GitLab 中出现奇怪的错误。

要转储数据库架构：

SCHEMA=/tmp/structure.sql gitlab-rake db:schema:dump

Rake 任务创建一个包含数据库架构转储的 /tmp/structure.sql 文件。

要确定是否存在任何差异：

转到 gitlab 项目中的 db/structure.sql 文件。选择与您的 GitLab 版本匹配的分支。例如，GitLab 16.2 的文件：https://gitlab.com/gitlab-org/gitlab/-/blob/16-2-stable-ee/db/structure.sql。
将 /tmp/structure.sql 与您版本的 db/structure.sql 文件进行比较。

检查数据库架构不一致性

此 Rake 任务检查数据库架构的任何不一致性，并在终端中打印它们。此任务是一个诊断工具，应在 GitLab 支持团队的指导下使用。您不应将此任务用于常规检查，因为数据库不一致性可能是预期的。

gitlab-rake gitlab:db:schema_checker:run

收集数据库的信息和统计信息

gitlab:db:sos 命令收集有关您的 GitLab 数据库的配置、性能和诊断数据，以帮助您排查问题。在哪里运行此命令取决于您的配置。确保在 GitLab 安装位置 (/gitlab) 相对的位置运行此命令。

扩展 GitLab：在您的 Puma 或 Sidekiq 服务器上。
云原生安装：在 toolbox pod 上。
所有其他配置：在您的 GitLab 服务器上。

根据需要修改命令：

默认路径 - 要使用默认文件路径 (/var/opt/gitlab/gitlab-rails/tmp/sos.zip) 运行命令，请运行 gitlab-rake gitlab:db:sos。
自定义路径 - 要更改文件路径，请运行 gitlab-rake gitlab:db:sos["/absolute/custom/path/to/file.zip"]。
Zsh 用户 - 如果您没有修改 Zsh 配置，您必须在整个命令周围添加引号，如下所示：gitlab-rake "gitlab:db:sos[/absolute/custom/path/to/file.zip]"

Rake 任务运行五分钟。它在您指定的路径中创建一个压缩文件夹。压缩文件夹包含大量文件。

启用可选查询统计数据

gitlab:db:sos Rake 任务还可以收集用于排查慢查询的数据，使用 pg_stat_statements 扩展。

启用此扩展是可选的，需要重启 PostgreSQL 和 GitLab。此数据可能是排查由慢数据库查询引起的 GitLab 性能问题所必需的。

先决条件：

您必须是具有超级用户权限的 PostgreSQL 用户才能启用或禁用扩展。

修改 /etc/gitlab/gitlab.rb 添加以下行：

postgresql['shared_preload_libraries'] = 'pg_stat_statements'

运行重新配置：
```
sudo gitlab-ctl reconfigure
```

PostgreSQL 需要重启以加载此扩展，这也需要重启 GitLab：

sudo gitlab-ctl restart postgresql
sudo gitlab-ctl restart sidekiq
sudo gitlab-ctl restart puma

修改 /etc/gitlab/gitlab.rb 添加以下行：

postgresql['shared_preload_libraries'] = 'pg_stat_statements'

运行重新配置：

docker exec -it <container-id> gitlab-ctl reconfigure

PostgreSQL 需要重启以加载此扩展，这也需要重启 GitLab：

docker exec -it <container-id> gitlab-ctl restart postgresql
docker exec -it <container-id> gitlab-ctl restart sidekiq
docker exec -it <container-id> gitlab-ctl restart puma

在您的 postgresql.conf 文件中添加或取消注释以下参数

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all

重启 PostgreSQL 以使更改生效。
重启 GitLab：Web (Puma) 和 Sidekiq 服务应该被重启。

在数据库控制台上运行：
```
CREATE EXTENSION pg_stat_statements;
```

检查扩展是否正常工作：

SELECT extname FROM pg_extension WHERE extname = 'pg_stat_statements';
SELECT * FROM pg_stat_statements LIMIT 10;

检查数据库中重复的 CI/CD 标签

此 Rake 任务检查 ci 数据库中 tags 表中的重复标签。此问题可能影响在长时间内经历了多次主要升级的实例。运行以下命令搜索重复标签，然后重写任何引用重复标签的标签分配以使用原始标签。

sudo gitlab-rake gitlab:db:deduplicate_tags

要以试运行模式运行此命令，请设置环境变量 DRY_RUN=true。

检测 PostgreSQL 排序规则版本不匹配

PostgreSQL 排序规则检查器检测数据库和操作系统之间的排序规则版本不匹配，这可能导致索引损坏。PostgreSQL 使用操作系统的 glibc 库进行字符串排序（排序和比较规则）。在更改底层 glibc 库的操作系统升级后运行此任务。

先决条件：

PostgreSQL 13 或更高版本。

要检查所有数据库中的 PostgreSQL 排序规则不匹配：

sudo gitlab-rake gitlab:db:collation_checker

要检查特定数据库：

# 检查主数据库
sudo gitlab-rake gitlab:db:collation_checker:main

# 检查 CI 数据库
sudo gitlab-rake gitlab:db:collation_checker:ci

示例输出

当未发现问题时：

Checking for PostgreSQL collation mismatches on main database...
No collation mismatches detected on main.

如果检测到不匹配，任务会提供修复受影响索引的补救步骤。

存在不匹配的示例输出：

Checking for PostgreSQL collation mismatches on main database...
⚠️ COLLATION MISMATCHES DETECTED on main database!
2 collation(s) have version mismatches:
  - en_US.utf8: stored=428.1, actual=513.1
  - es_ES.utf8: stored=428.1, actual=513.1

Affected indexes that need to be rebuilt:
  - index_projects_on_name (btree) on table projects
    • Affected columns: name
    • Type: UNIQUE

REMEDIATION STEPS:
1. Put GitLab into maintenance mode
2. Run the following SQL commands:

# Step 1: Check for duplicate entries in unique indexes
SELECT name, COUNT(*), ARRAY_AGG(id) FROM projects GROUP BY name HAVING COUNT(*) > 1 LIMIT 1;

# If duplicates exist, you may need to use gitlab:db:deduplicate_tags or similar tasks
# to fix duplicate entries before rebuilding unique indexes.

# Step 2: Rebuild affected indexes
# Option A: Rebuild individual indexes with minimal downtime:
REINDEX INDEX CONCURRENTLY index_projects_on_name;

# Option B: Alternatively, rebuild all indexes at once (requires downtime):
REINDEX DATABASE main;

# Step 3: Refresh collation versions
ALTER COLLATION "en_US.utf8" REFRESH VERSION;
ALTER COLLATION "es_ES.utf8" REFRESH VERSION;

3. Take GitLab out of maintenance mode

有关 PostgreSQL 排序规则问题及其如何影响数据库索引的更多信息，请参阅 PostgreSQL 升级操作系统文档。

修复损坏的数据库索引

索引修复工具修复可能导致数据完整性问题的损坏或缺失的数据库索引。该工具解决受排序规则不匹配或其他损坏问题影响的特定问题索引。该工具：

在唯一索引损坏时对数据进行去重。
更新引用以保持数据完整性。
使用正确配置重建或创建索引。

在修复索引之前，以试运行模式运行该工具以分析潜在更改：

sudo DRY_RUN=true gitlab-rake gitlab:db:repair_index

以下示例输出显示了更改：

INFO -- : DRY RUN: Analysis only, no changes will be made.
INFO -- : Running Index repair on database main...
INFO -- : Processing index 'index_merge_request_diff_commit_users_on_name_and_email'...
INFO -- : Index is unique. Checking for duplicate data...
INFO -- : No duplicates found in 'merge_request_diff_commit_users' for columns: name,email.
INFO -- : Index exists. Reindexing...
INFO -- : Index reindexed successfully.

要修复所有数据库中所有已知的问题索引：

sudo gitlab-rake gitlab:db:repair_index

该命令处理每个数据库并修复索引。例如：

INFO -- : Running Index repair on database main...
INFO -- : Processing index 'index_merge_request_diff_commit_users_on_name_and_email'...
INFO -- : Index is unique. Checking for duplicate data...
INFO -- : No duplicates found in 'merge_request_diff_commit_users' for columns: name,email.
INFO -- : Index does not exist. Creating new index...
INFO -- : Index created successfully.
INFO -- : Index repair completed for database main.

要修复特定数据库中的索引：

# 修复主数据库中的索引
sudo gitlab-rake gitlab:db:repair_index:main

# 修复 CI 数据库中的索引
sudo gitlab-rake gitlab:db:repair_index:ci

故障排除

咨询锁连接信息

运行 db:migrate Rake 任务后，您可能会看到类似以下的输出：

main: == [advisory_lock_connection] object_id: 173580, pg_backend_pid: 5532
main: == [advisory_lock_connection] object_id: 173580, pg_backend_pid: 5532

返回的消息是信息性的，可以忽略。

执行 `gitlab:env:info` Rake 任务时的 PostgreSQL 套接字错误

在 Gitaly 或其他非 Rails 节点上运行 sudo gitlab-rake gitlab:env:info 后，您可能会看到以下错误：

PG::ConnectionBad: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/var/opt/gitlab/postgresql/.s.PGSQL.5432"?

这是因为在多节点环境中，gitlab:env:info Rake 任务应该只在运行 GitLab Rails 的节点上执行。

维护 Rake 任务

收集 GitLab 和系统信息

显示 GitLab 许可证信息

检查 GitLab 配置

重建 authorized_keys 文件

清除 Redis 缓存

预编译资源

检查到远程站点的 TCP 连接性

清除独占租约（危险）

显示数据库迁移状态

运行未完成的数据库迁移

重建数据库索引

运行重建索引

自定义重建索引设置

自动重建索引

使用 crontab 调度

注意事项

转储数据库架构

检查数据库架构不一致性

收集数据库的信息和统计信息

启用可选查询统计数据

检查数据库中重复的 CI/CD 标签

检测 PostgreSQL 排序规则版本不匹配

示例输出

修复损坏的数据库索引

故障排除

咨询锁连接信息

执行 gitlab:env:info Rake 任务时的 PostgreSQL 套接字错误

重建 `authorized_keys` 文件

执行 `gitlab:env:info` Rake 任务时的 PostgreSQL 套接字错误