• 启用维护模式
• 禁用维护模式
• 维护模式下的功能表现
  • 管理员功能
  • 身份验证
  • Git 操作
  • 合并请求，议题，史诗
  • 接收电子邮件
  • 外发电子邮件
  • REST API
  • GraphQL API
  • 持续集成
  • 部署
    • Terraform 集成
  • Container Registry
  • Package Registry
  • 后台作业
  • 事件管理
  • 功能标志
  • Geo secondaries
  • 安全功能
• 示例用例：计划的故障转移

极狐GitLab 维护模式

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

启用维护模式后，进行中的操作会相对较快地完成，因为没有新操作进入，并且内部状态更改很小。 在这种状态下，各种维护任务更容易，服务可以完全停止或进一步降级，时间比原本需要的时间短得多。例如，停止 cron 作业和排空队列应该很快。

维护模式允许大多数不改变内部状态的外部操作。概括地说，HTTP POST、PUT、PATCH 和 DELETE 请求被阻止。

启用维护模式

以管理员身份启用维护模式的方法有以下三种：

• Web UI：
  1. 在左侧边栏中，选择 搜索或转到。
  2. 选择 管理中心。
  3. 在左侧边栏中，选择 设置 > 通用。
  4. 展开 维护模式，然后切换 启用维护模式。 您也可以选择为 banner 添加消息。
  5. 选择 保存修改。

• API：

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

• Rails console：

  ::Gitlab::CurrentSettings.update!(maintenance_mode: true)
  ::Gitlab::CurrentSettings.update!(maintenance_mode_message: "New message")
  

禁用维护模式

有三种方法可以禁用维护模式：

• Web UI：
  1. 在左侧边栏中，选择 搜索或转到。
  2. 选择 管理中心。
  3. 在左侧边栏中，选择 设置 > 通用。
  4. 展开 维护模式，然后切换 启用维护模式。 您也可以选择为 banner 添加消息。
  5. 选择 保存修改。

• API：

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

• Rails console：

  ::Gitlab::CurrentSettings.update!(maintenance_mode: false)
  

维护模式下的功能表现

启用维护模式后，页面顶部会显示 banner。 可以使用特定消息自定义 banner。

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

管理员功能

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

身份验证

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

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

Git 操作

所有只读 Git 操作继续工作，例如 git clone 和 git pull。通过 CLI 和 Web IDE 的所有写入操作都失败，并显示错误消息：Git push is not allowed because this GitLab instance is current 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	Paths ending with /compare	Git 修订路径。
POST	.git/git-upload-pack	允许 Git 拉取/克隆。
POST	/api/v4/internal	内部 API 路径。
POST	/admin/sidekiq	允许在管理 UI 中管理后台作业。
POST	/admin/geo	允许在管理员 UI 中更新 Geo 节点。
POST	/api/v4/geo_replication	允许在次要站点上，执行某些特定于 Geo 的管理员 UI 操作。

GraphQL API

许可名单中的 GeoRegistriesUpdate 变更添加引入于极狐GitLab 16.2。

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

唯一允许的变更是 GeoRegistriesUpdate，用于重新同步和重新验证镜像库。

持续集成

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

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

部署

部署没有通过，因为流水线未完成。

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

Terraform 集成

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

Container Registry

docker push 失败并出现以下错误：denied: requested access to the resource is denied，但 docker pull 有效。

Package Registry

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

后台作业

后台作业（cron 作业、Sidekiq）继续按原计划运行，因为后台作业不会自动禁用。 在计划的 Geo 故障转移期间，建议您禁用除与 Geo 相关的所有 cron 作业。

要监控队列并禁用作业：

1. 在左侧边栏中，选择 搜索或转到。
2. 选择 管理中心。
3. 在左侧边栏中，选择 监控 > 后台作业。

事件管理

事件管理功能是有限的。警报和事件的创建完全暂停。因此禁用警报和事件的通知和呼叫。

功能标志

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

Geo secondaries

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

在启用维护模式之前不要禁用复制，这一点很重要。

通过管理 UI 重新同步和重新验证镜像库的复制、验证和手动操作仍然有效，但代理 Git 推送到主服务器的操作不起作用。

安全功能

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

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

更改结果或漏洞对象的状态不工作，即使 UI 中未显示错误。

SAST 和 Secret Detection 无法启动，因为它们依赖于传递 CI 作业来创建产物。

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

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

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

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

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