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

避免强制停止点

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

虽然开发团队维护着一个 维护策略，该策略会产生一个三版本（3个月）的回溯窗口 - 但 GitLab 提供了更长的 版本支持 窗口，包括当前主版本以及前两个主版本。根据以往主版本的发布计划，GitLab 用户可以落后当前版本最多三年，并且仍然期望获得升级支持。

例如，一个从 GitLab 14.0.12 升级到 GitLab 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 值更改 MergeRequests 中的 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. 向数据库团队提交一个问题，以在下一个版本中压缩到该版本的迁移。使用以下模板创建问题：

    Title: `压缩到 <强制停止点版本> 的迁移`
由于为 <强制停止点版本> 添加了强制停止点，我们应该压缩到该版本的迁移，并更新最低模式版本。

交付成果：
- [ ] 迁移已压缩到 <强制停止点版本>
- [ ] `Gitlab::Database::MIN_SCHEMA_VERSION` 与 init_schema 版本匹配

/label ~"group::database" ~"section::enablement" ~"devops::data_stores" ~"Category:Database" ~"type::maintenance"
/cc @gitlab-org/database-team/triage

在强制停止点之后的发布中

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

依赖 upgrade_path.yml 的 GitLab 维护项目

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

延伸阅读