极狐 GitLab Logo

极狐GitLab 维护模式

  • Tier: 专业版, 旗舰版
  • Offering: 私有化部署

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

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

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

启用维护模式#

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

  • Web UI:

    1. 在左侧边栏底部，选择 管理员。
    2. 在左侧边栏中，选择 设置 > 常规。
    3. 展开 维护模式，并切换 启用维护模式。您还可以选择为横幅添加消息。
    4. 选择 保存更改。

  • API:

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

禁用维护模式#

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

  • Web UI:

    1. 在左侧边栏底部，选择 管理员。
    2. 在左侧边栏中，选择 设置 > 常规。
    3. 展开 维护模式，并切换 启用维护模式。您还可以选择为横幅添加消息。
    4. 选择 保存更改。

  • API:

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

维护模式下极狐GitLab功能的行为#

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

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

Maintenance Mode banner and error message

在某些情况下，操作的视觉反馈可能会产生误导。例如，当标星项目时，**标星**按钮会更改为显示 **取消标星** 操作。然而，这只是前端更新，并未考虑到 POST 请求的失败状态。

管理员功能#

系统管理员可以编辑应用设置。这使他们可以在启用后禁用维护模式。

身份验证#

所有用户都可以登录和退出极狐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 返回 403 响应，错误信息为：You cannot perform write operations on a read-only instance。仅允许以下请求：

HTTP 请求允许的路径备注
POST/admin/application_settings/general允许在管理员 UI 中更新应用设置
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以 /compare 结尾的路径Git 修订路线。
POST.git/git-upload-pack允许 Git 拉取/克隆。
POST/api/v4/internal内部 API 路线
POST/admin/sidekiq允许在 管理员 区域管理后台作业
POST/admin/geo允许在管理员 UI 中更新 Geo 节点
POST/api/v4/geo_replication允许在次要站点上进行某些特定于 Geo 的管理员 UI 操作

GraphQL API#

History
    • GeoRegistriesUpdate 突变在 GitLab 16.2 中引入。

POST /api/graphql 请求被允许，但突变被阻止，错误信息为 You cannot perform write operations on a read-only instance。

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

持续集成#

  • 没有新的作业或流水线启动，无论是否已安排。
  • 已经运行的作业在极狐GitLab UI 中继续显示 运行中 状态，即使它们在极狐GitLab Runner 上完成运行。
  • 处于 运行中 状态超过项目时间限制的作业不会超时。
  • 无法启动、重试或取消流水线。也无法创建新作业。
  • /admin/runners 中 runners 的状态不更新。
  • gitlab-runner verify 返回错误 ERROR: Verifying runner... is removed。

禁用维护模式后，新作业将再次被拾取。在启用维护模式之前处于 运行中 状态的作业将恢复，并且它们的日志将开始更新。

在关闭维护模式后，您应该重新启动之前 `运行中` 的流水线。

部署#

由于流水线未完成，部署无法进行。

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

Terraform 集成#

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

容器注册表#

docker push 会失败并出现错误：denied: requested access to the resource is denied，但 docker pull 可以工作。

软件包注册表#

软件包注册表允许您安装但不发布软件包。

后台作业#

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

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

要监控队列并禁用作业：

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

事件管理#

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

功能标志#

Geo 从站#

当主站处于维护模式时，从站也会自动进入维护模式。

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

通过管理员 UI 继续工作，但代理的 Git 推送到主站不工作。

安全功能#

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

从漏洞报告页面导出漏洞列表不起作用。

即使在 UI 中没有显示错误，也无法更改发现或漏洞对象的状态。

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

示例用例：计划的故障转移#

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

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

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

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