极狐 GitLab

避免强制停机

强制停机是指对极狐GitLab 组件 或依赖项的任何更改，这些更改导致在升级极狐GitLab 时需要升级到并停留在特定的 major.minor 版本。

虽然开发团队维护着维护策略，该策略会提供三个版本（3 个月）的回溯窗口，但极狐GitLab 拥有更长的版本支持 窗口，涵盖当前主要版本以及前两个主要版本。根据以往主要版本的发布计划，极狐GitLab 客户可以落后当前版本长达三年，仍能获得升级支持。

例如，一名极狐GitLab 用户从极狐GitLab 14.0.12 升级到 16.1（这是一个完全支持的升级路径）时，在升级到最新的 16.1.z 版本之前，可能会遇到以下强制停机版本：14.3.6、14.9.5、14.10.5、15.0.5、15.1.6、15.4.6 和 15.11.11。

以往的强制停机往往在引入数月后才被发现，这通常是因为用户跨越超过 1-3 个次要版本升级时需要支持工程师、客户成功经理和开发工程师进行大量故障排查和提供协助。

应尽可能避免强制停机。如果无法避免，强制停机应对齐到计划的强制停机。

计划的强制停机通常会在 major 版本发布前，针对上一个 major.minor 版本实施，以便适应多个计划弃用 和已知的重大变更。

此外，从极狐GitLab 16 开始，我们引入了计划的 major.minor 强制停机：

在极狐GitLab 16.x 期间，我们计划安排两到三个强制升级停机。 当我们安排强制升级停机时，我们会至少提前两个里程碑通知。第一个计划的强制升级停机计划在极狐GitLab 16.3。如果未引入需要升级停机的内容，极狐GitLab 16.3 将被视为常规升级。

追溯添加强制停机#

如果我们考虑追溯声明一个计划外的强制停机，请联系分发团队产品经理 以就后续步骤提供建议。如果对于是否应声明强制停机存在不确定性，分发产品经理可上报至极狐GitLab 产品领导层（VP 或首席产品官）以做出最终决定。例如，当某个变更可能仅对极小部分超大型极狐GitLab 私有化部署实例需要强制停机，并且存在明确定义的变通方案供客户遇到问题时使用时，就可能发生此类情况。

强制停机的原因#

对已完成迁移的错误假设#

大多数强制停机是由于对特定版本中数据模型状态的假设，通常表现为相互依赖的数据库迁移，或者代码更改假设先前迁移中引入的模式更改在代码加载时已经完成。

针对版本间向后兼容性 设计更改和迁移可以减轻持续或零停机升级时的停机担忧。但是，当引入需要后台迁移在运行或加载前完成的迁移/代码更改时，契约 阶段可能会引入强制停机。

如果你正在考虑添加或删除迁移，或引入假设迁移在特定版本中已完成的代码，请先查看有关强制停机 的数据库相关文档。

示例#

  • 极狐GitLab 12.1：引入了后台迁移，根据 state 值更改合并请求中的 merge_status。state 属性在 12.10 中移除。直到 13.6 才记录此强制停机。
  • 极狐GitLab 13.8：包含一个后台迁移来处理重复的服务记录。在 13.9 中，另一个迁移应用了唯一索引，该索引依赖于后台迁移的完成。直到极狐GitLab 14.3 才被发现/记录。
  • 极狐GitLab 14.3：包含针对 merge_request_diff_commits 的可能长时间运行的后台迁移，该迁移在 14.5 中转为前台执行。此更改导致大型极狐GitLab 实例的用户遭受大量停机。直到极狐GitLab 15.1 才记录。
  • 极狐GitLab 14.9：包含针对 namespaces 和 projects 的批量后台迁移，该迁移需要在 14.10 中添加的另一个批量后台迁移执行前完成，从而强制要求停机。在大型极狐GitLab 实例中，该迁移可能需要数小时或数天才能完成。

更多详细信息以及相关议题和合并请求的链接可在以下位置找到：议题：采取措施避免极狐GitLab 升级路径停机的增加/扩散

代码变通方案和缓解措施的移除#

与对数据模型/模式/迁移状态的假设类似，由于有意移除了用于解决之前发现问题的代码，强制 major.minor 停机已被引入。

示例#

  • 极狐GitLab 13.1：Rails 6.0.3.1 中的一个安全修复引入了 CSRF 令牌更改（导致金丝雀环境事件）。我们引入了代码来保持对先前生成的令牌的接受，并在 13.2 中移除了该代码，从而在 13.1 中创建已知的强制停机。
  • 极狐GitLab 15.4：引入了一个迁移，用于修复自极狐GitLab 14.9 以来在代码中缓解的作业产物不准确的 expires_at 时间戳。该变通方案在极狐GitLab 15.6 中被移除，导致 15.4 成为强制停机。

弃用#

弃用，尤其是重大变更，如果引入长时间的迁移延迟或需要极狐GitLab 管理员进行手动操作，也可能导致强制停机。

这些通常被接受为大型版本发布前后的强制停机，停机位置要么在紧随新的 major 版本发布前的最新 major.minor 版本，要么可能在最新的 major.0 补丁版本。迄今为止，与弃用相关的已发现强制停机仅限于这些版本。

并非所有弃用都会导致强制停机，因为在大多数情况下，用户能够在开始升级之前调整其配置，而不会导致停机或其他重大问题。

示例#

弃用的示例太多，无法在此一一列举，但可以在以下位置找到：

添加强制停机#

规划强制停机里程碑#

我们不能在每个里程碑中都添加强制停机，因为这会损害用户在升级极狐GitLab 时的体验。分发团队负责协助规划和确定引入强制停机的时间。

从极狐GitLab 17.5 开始，我们将在 X.2、X.5、X.8 和 X.11 次要里程碑中引入强制停机。如果你引入了需要升级停机的代码更改或功能，你必须牢记这些里程碑来对齐你的更改。

强制停机发布前#

在发布已知的强制停机之前，请完成以下步骤。如果强制停机在发布后才被识别，仍必须完成以下步骤：

  1. 在同一 MR 中，更新升级路径 文档以包括新的强制停机，以及 upgrade_path.yml 文件。upgrade_path.yml 是我们所有强制停机的单一事实来源（SSoT）。

  2. 与客户支持和发布管理团队沟通更改。

  3. 向数据库组提交一个议题，以便在下一个版本中将迁移压缩到该版本。使用此模板创建议题：

    markdown
    1Title: `将迁移压缩到 <Required stop version>`
2由于在 <required stop version> 中添加了强制停机，我们应该将迁移压缩到该版本，并更新最低模式版本。
3
4Deliverables:
5- [ ] 迁移已压缩到 <required stop version>
6- [ ] `Gitlab::Database::MIN_SCHEMA_VERSION` 与 init_schema 版本匹配
7
8/label ~"group::database" ~"section::enablement" ~"devops::data_stores" ~"Category:Database" ~"type::maintenance"
9/cc @gitlab-org/database-team/triage

强制停机后的发布中#

  1. 在 charts 项目中，将升级检查钩子 更新为强制停机版本。

极狐GitLab 维护的依赖 upgrade_path.yml 的项目#

我们有多个项目依赖于 upgrade_path.yml 单一事实来源。因此，对该文件结构的任何更改都需要考虑到可能影响以下项目之一：

进一步阅读#