GitLab 维护模式

维护模式允许管理员在执行维护任务时将写入操作降至最低。其主要目标是阻止所有会更改内部状态的外部操作。内部状态包括 PostgreSQL 数据库，尤其是文件、Git 仓库和容器仓库。

启用维护模式后，正在进行的操作会相对较快地完成，因为没有新的操作进入，且内部状态的变化也降至最低。在此状态下，各种维护任务会更容易。服务可以被完全停止，或在比通常所需更短的时间内进一步降级。例如，停止 cron 作业和清空队列应该会相当快。

维护模式允许大多数不改变内部状态的外部操作。从高层次来看，HTTP 的 POST、PUT、PATCH 和 DELETE 请求会被阻止，并且提供了如何处理特殊情况的详细概述。

启用维护模式

以管理员身份通过以下任一方式启用维护模式：

• Web 界面：

  1. 在左侧边栏的底部，选择 管理员。
  2. 在左侧边栏中，选择 设置 > 通用。
  3. 展开 维护模式，然后切换 启用维护模式 开关。 您也可以选择性地为横幅添加一条消息。
  4. 选择 保存更改。

• API：

  curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true"

禁用维护模式

通过以下三种方式之一禁用维护模式：

• Web 界面：

  1. 在左侧边栏的底部，选择 管理员。
  2. 在左侧边栏中，选择 设置 > 通用。
  3. 展开 维护模式，然后切换 启用维护模式 开关。 您也可以选择性地为横幅添加一条消息。
  4. 选择 保存更改。

• API：

  curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false"

维护模式下的 GitLab 功能行为

启用维护模式后，页面顶部会显示一个横幅。该横幅可以通过特定消息进行自定义。

当用户尝试执行不被允许的写入操作时，会显示一个错误。

管理员功能

系统管理员可以编辑应用程序设置。这允许他们在启用维护模式后将其禁用。

身份验证

所有用户都可以登录和退出 GitLab 实例，但不能创建新用户。

如果当时安排了 LDAP 同步，它们会失败，因为用户创建已被禁用。同样，基于 SAML 的用户创建也会失败。

Git 操作

所有只读 Git 操作（例如 git clone 和 git pull）都继续有效。所有写入操作都会失败，无论是通过 CLI 还是 Web IDE，并显示错误消息：Git push is not allowed because this GitLab instance is currently in (read-only) maintenance mode.

如果启用了 Geo，向主节点和辅助节点的 Git 推送都会失败。

合并请求、议题、史诗

除前面提到的操作外，所有写入操作都会失败。例如，用户无法更新合并请求或议题。

收件邮件

通过邮件创建新的议题回复、议题（包括新的服务台议题）、合并请求会失败。

发件邮件

通知邮件会继续送达，但需要写入数据库的邮件（例如重置密码）则不会送达。

REST API

对于大多数 JSON 请求，POST、PUT、PATCH 和 DELETE 会被阻止，API 会返回 503 响应以及错误消息：GitLab Maintenance: system is in maintenance mode。仅允许以下请求：

HTTP request	Allowed routes	Notes
POST	/admin/application_settings/general	允许在管理员界面中更新应用程序设置
PUT	/api/v4/application/settings	允许通过 API 更新应用程序设置
POST	/users/sign_in	允许用户登录。
POST	/users/sign_out	允许用户退出。
POST	/oauth/token	允许用户首次登录到 Geo 辅助节点。
POST	/admin/session, /admin/session/destroy	允许GitLab 管理员使用管理员模式
POST	Paths ending with /compare	Git 版本路由。
POST	.git/git-upload-pack	允许 Git pull/clone。
POST	/api/v4/internal	内部 API 路由
POST	/admin/sidekiq	允许在 管理员 区域管理后台作业
POST	/admin/geo	允许在管理员界面中更新 Geo 节点
POST	/api/v4/geo_replication	允许在辅助站点上执行某些特定于 Geo 的管理员界面操作

GraphQL API

POST /api/graphql 请求是允许的，但变更操作会被阻止，并显示错误消息 You cannot perform write operations on a read-only instance。

唯一允许的变更是 GeoRegistriesUpdate，它用于重新同步和重新验证注册表。

持续集成

• 不会启动新的作业或流水线，无论是计划性的还是其他类型的。
• 已在运行的作业在 GitLab 界面中会继续显示 running 状态，即使它们在 GitLab Runner 上已完成运行。
• 处于 running 状态且时间超过项目时间限制的作业不会超时。
• 无法启动、重试或取消流水线。也无法创建新的作业。
• /admin/runners 中 Runner 的状态不会更新。
• gitlab-runner verify 会返回错误 ERROR: Verifying runner... is removed。

禁用维护模式后，新的作业会再次被拾取。在启用维护模式前处于 running 状态的作业会恢复，其日志也会开始再次更新。

部署

部署无法进行，因为流水线未完成。

您应该在维护模式期间禁用自动部署，并在禁用维护模式后重新启用它们。

Terraform 集成

Terraform 集成依赖于运行中的 CI 流水线，因此它会被阻止。

容器仓库

docker push 会失败并显示此错误：denied: requested access to the resource is denied，但 docker pull 可以正常工作。

包仓库

包仓库允许您安装包，但不能发布包。

后台作业

后台作业（cron 作业、Sidekiq）会继续按原样运行，因为后台作业不会被自动禁用。 由于后台作业执行的操作可能会更改您实例的内部状态，您可能希望在启用维护模式时禁用其中一部分或全部。

在计划中的 Geo 故障转移期间，您应该禁用所有 cron 作业，但与 Geo 相关的除外。

要监控队列和禁用作业：

1. 在左侧边栏的底部，选择 管理员。
2. 选择 监控 > 后台作业。
3. 在 Sidekiq 仪表板中，选择 Cron，然后通过选择 禁用全部 来单独或一次性禁用作业。

事件管理

事件管理功能受到限制。警报和事件的创建被完全暂停。因此，警报和事件的通知和寻呼也被禁用。

功能开关

• 开发类功能开关无法通过 API 开启或关闭，但可以通过 Rails 控制台切换。
• 功能开关服务会响应功能开关的检查，但无法切换功能开关。

Geo 辅助节点

当主节点进入维护模式时，辅助节点也会自动进入维护模式。

重要的是，在启用维护模式之前，您不要禁用复制。

通过管理员界面进行的复制、验证以及手动重新同步和重新验证注册表的操作会继续工作，但代理到主节点的 Git 推送则不会。

安全功能

依赖于创建议题或创建/批准合并请求的功能将无法工作。

从漏洞报告页面导出漏洞列表的功能无法工作。

更改查找结果或漏洞对象状态的功能无法工作，即使界面中未显示任何错误。

无法启动 SAST 和密钥检测，因为它们依赖于通过的 CI 作业来创建产物。

一个用例示例：计划中的故障转移

在计划中的故障转移用例中，主数据库中的少量写入操作是可以接受的，因为它们会被快速复制，并且数量不多。

出于同样的原因，我们在启用维护模式时不会自动阻止后台作业。

由此产生的数据库写入是可以接受的。这里的权衡在于更多的服务降级与复制任务的完成之间。

然而，在计划中的故障转移期间，我们要求用户手动关闭与 Geo 无关的 cron 作业。在没有新的数据库写入和非 Geo cron 作业的情况下，新的后台作业要么根本不会被创建，要么数量极少。