极狐 GitLab

升级说明

升级说明

升级说明页面包含了极狐GitLab 管理员在升级其私有化部署的极狐GitLab 实例时应遵循的信息。

它包含以下信息：

  • 从一个版本到另一个版本的重要缺陷、缺陷修复和变通方案。
  • 管理员应注意的长时间运行的数据库迁移。
  • 配置文件中的重大更改。
  • 改变行为的安全修复。

页面格式#

每个主要版本都存在一个页面：doc/update/versions/gitlab_X_changes.md。

每个页面有两个主要部分：

  • 顶部的版本索引：轻量级的链接列表，每个次要版本一个，管理员通过扫描来查找影响其升级的内容。
  • 底部的升级说明：每个条目的实际内容，每个条目都有自己的标题和稳定的锚点。

完整的页面布局，从上到下：

markdown
1---
2stage: GitLab Delivery
3group: Operate
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
5description: Review the GitLab X upgrade notes.
6title: 极狐GitLab X 升级说明
7---
8
9{{</* details */>}}
10
11- Tier: 基础版，专业版，旗舰版
12- Offering: 私有化部署
13
14{{</* /details */>}}
15
16This page contains upgrade information for minor and patch versions of GitLab X.
17Ensure you review these instructions for:
18
19- Your installation type.
20- All versions between your current version and your target version.
21
22For additional information for Helm chart installations, see
23[the Helm chart X.0 upgrade notes](https://gitlab.cn/docs/charts/releases/X_0/).
24
25## Required upgrade stops
26
27To provide a predictable upgrade schedule for instance administrators,
28required upgrade stops occur at versions:
29
30- `X.2`
31- `X.5`
32- `X.8`
33- `X.11`
34
35## Upgrade notes reference
36
37The following is a reference list of upgrade notes for each minor GitLab version.
38Each list item points to a specific section that holds more information.
39
40Items marked with an installation method, like `(Geo)` or `(Linux package)`,
41apply only to that method. All other items apply to all installation methods.
42
43### Upgrade to X.Y
44
45Before upgrading to GitLab X.Y, review the following:
46
47- [X.Y.0] - [Item title](#item-title)
48
49## Upgrade notes
50
51Specific upgrade notes for GitLab X.
52
53### Item title
54
55- Affects: All installation methods
56- Affected versions: X.Y.0
57
58Description of the item.
59
60### Geo item title
61
62{{</* details */>}}
63
64- Tier: 专业版，旗舰版
65
66{{</* /details */>}}
67
68- Affects: Geo
69- Affected versions: X.0.0
70
71Description of the item.

当需要创建一个新的主要版本时（将 X 替换为主要版本号）：

  1. 使用上一个模板并在 doc/update/versions/gitlab_X_changes.md 下创建一个新页面。

  2. 在 doc/update/upgrade_paths.md 中创建一个匹配的部分：

    markdown
    1### Required GitLab X upgrade stops
2
3Required upgrade stops occur at versions `X.2`, `X.5`, `X.8`, and `X.11`.
4
5You must upgrade to those versions of GitLab X before upgrading to later
6versions. For each version you upgrade to, see the
7[upgrade notes for GitLab X](versions/gitlab_X_changes.md). If a version
8is not in the upgrade notes, then there's nothing specific about that
9version to be aware of.
10
11Find the patch releases in the GitLab package repository at
12<https://packages.gitlab.cn/#browse/browse>.

  3. 在 doc/update/versions/_index.md 下添加一个指向新页面的链接。

  4. 添加一个导航条目。

版本索引#

版本索引是管理员的入口点。 它们包含一个版本列表，这些版本链接到相关的升级说明。

  • 为每个次要版本创建一个标题 ### 升级到 X.Y。不要为补丁版本创建单独的标题。按降序列出次要版本（最新的在顶部）。

    例如：

    markdown
    ### 升级到 X.Y

在升级到极狐GitLab X.Y 之前，请查看以下内容：

- [X.Y.0] - [条目标题](#item-title)

  • 每个列表项都以括号中的补丁版本开头，并链接到升级说明。按降序补丁版本列出项目，以便最新的补丁排在第一位。例如，正在从 18.2.1 升级到 18.2.3 的管理员会扫描 [18.2.3] 和 [18.2.2] 条目。 方括号中的版本取决于更改的类型：

    • 对于有意的更改或新行为，请使用引入它的版本。例如，[18.4.1]。
    • 对于影响多个连续补丁的缺陷或回归，请使用受影响版本的范围。例如，[18.4.0 - 18.4.1]。修复版本记录在升级说明正文中，而不是列表项中。 每个升级说明对于每个次要版本都有一个列表项。

  • 在修复可用之前记录缺陷是可选的。仅当缺陷对升级或操作产生重大影响时才添加已知问题。如果添加，请使用引入该缺陷的版本。当修复发布时，将列表项更新为受影响的范围，并在 升级说明 部分中，将修复的补丁级别添加到 受影响的版本 字段或表格中。 不要为缺陷和修复使用单独的升级说明。使用一个同时记录受影响版本和已修复版本的升级说明。

  • 如果一个项目仅适用于特定的安装方法，请在括号中添加安装类型。使用以下一项或多项的组合：

    • Linux package
    • Helm chart
    • Docker
    • Self-compiled
    • Operator
    • Geo

  • 当一个项目影响多个次要版本时，它会出现在每个相关的版本索引中，并链接到同一个锚点。每个列表项使用与该特定次要版本相关的补丁版本或受影响的范围。

  • 如果特定的补丁版本是必需的升级停止点，请在版本索引中添加一条说明。某些必需的停止点是有条件的。包含条件以及管理员检查他们是否受影响的方法。

  • 当一个问题跨越两个主要版本时（例如，17.11 和 18.0）：

    1. 在较新的主要版本页面上记录完整详细信息（例如，gitlab_18_changes.md）。当较旧的页面最终归档时，内容仍可访问。
    2. 从较旧的页面链接到较新的页面。

    如果该问题影响两个页面上的许多版本并且跨页面链接变得混乱，请在两个页面上复制该项目。

示例模板#

此模板展示了如何列出版本索引的示例。

markdown
1### 升级到 18.8
2
3在升级到极狐GitLab 18.8 之前，请查看以下内容：
4
5- [18.8.2] - [已阻止用户的部署密钥被作废](#deploy-keys-for-blocked-users-invalidated)
6
7### 升级到 18.7
8
9在升级到极狐GitLab 18.7 之前，请查看以下内容：
10
11- [18.7.2] - [已阻止用户的部署密钥被作废](#deploy-keys-for-blocked-users-invalidated)
12
13### 升级到 18.2
14
15在升级到极狐GitLab 18.2 之前，请查看以下内容：
16
17- [18.2.3] - [部署令牌轮换问题](#deploy-token-rotation-issue)
18- [18.2.3] - [后台迁移更正](#background-migration-correction)
19- [18.2.1] - [新的安全修复](#new-security-fix)
20- [18.2.0 - 18.2.1] - [某些已知缺陷](#some-known-bug)
21- [18.2.0 - 18.2.4] - [Geo 复制同步失败](#geo-replication-sync-failure) (Geo)
22- [18.2.0] - [某些迁移更改](#some-migration-change)
23- [18.2.0] - [Geo 校验修复](#geo-verification-fix) (Geo)
24- [18.2.0] - [Gitaly 配置更改](#gitaly-configuration-change) (Linux package)
25
26### 升级到 18.1
27
28<div class="alert alert-info">
29
30对于拥有大型 `ci_pipeline_messages` 表（超过 150 万行）的实例，版本 18.1.3 是一个必需的升级停止点。
31请参阅[长时间运行的流水线消息数据更改](#long-running-pipeline-messages-data-change)
32了解如何检查你是否受影响。
33
34</div>
35
36- [18.1.3] - [长时间运行的流水线消息数据更改](#long-running-pipeline-messages-data-change)
37- [18.1.0 - 18.1.5] - [Geo 复制同步失败](#geo-replication-sync-failure) (Geo)
38
39### 升级到 17.11
40
41- [17.11.0] - [简要描述](gitlab_18_changes.md#descriptive-anchor)

升级说明#

升级说明是描述更改、缺陷或迁移的各个项目。将每个项目添加为 H3 标题，并带有稳定的描述性锚点。所有项目都必须添加到 ## 升级说明 部分，无论它们影响一个版本还是多个版本，也无论它们的长度如何。

对于每个项目：

  • 使用描述性标题（标题在整个页面上必须是唯一的）。不要在标题中包含版本号。
  • 在标题之后直接添加一个列表，该列表首先列出受影响的安装类型，然后列出受影响的补丁版本。 对于安装类型行，使用以下之一：
    • 所有安装方法
    • 受影响安装方法的逗号分隔列表，例如：Linux package, Helm chart, Geo
  • 当一个项目影响两个或更多次要版本时，在 受影响的版本 项目下包含一个受影响版本表。此模式也适用于向后移植到多个分支的安全修复程序。每个受影响的版本索引都链接到这个单一项目。
  • 对于 Geo 项目，在受影响版本列表之前包含一个用于层级信息的详情块。仅对层级使用详情块。
  • 需要大量参考资料（SQL 查询、数据描述、配置选项）的项目可以使用 H4 子标题作为内部结构。其他升级说明通过锚点链接到它们。
markdown
1### 包含 Geo 层级详情的项目
2
3{{</* details */>}}
4
5- Tier: 专业版，旗舰版
6
7{{</* /details */>}}
8
9- Affects: Geo
10- Affected versions: 18.7.0
11
12该项目的描述。
13
14### 包含 H4 标题的项目
15
16- Affects: 所有安装方法
17- Affected versions: 18.2.3
18
19该项目的描述。
20
21#### SQL 查询
22
23使用以下 SQL 查询来加快速度。
24
25...
26
27### 包含多个版本且无固定补丁级别的项目
28
29- Affects: 所有安装方法
30- Affected versions:
31
32  | 版本 | 受影响的补丁级别 | 已修复的补丁级别 |
33  |---------|-----------------------|--------------------------|
34  | 18.8    | 18.8.2 及更高版本      | 不适用（有意的更改） |
35  | 18.7    | 18.7.2 及更高版本      | 不适用（有意的更改） |
36  | 18.6    | 18.6.4 及更高版本      | 不适用（有意的更改） |
37
38该项目的描述。
39
40## 包含多个版本且已固定补丁级别的项目
41
42- Affects: 所有安装方法
43- Affected versions:
44
45  | 版本 | 受影响的补丁版本 | 已修复的补丁级别 |
46  | ------- | ----------------------- | ----------------- |
47  | 17.8    |  17.8.0 - 17.8.6        | 17.8.7            |
48  | 17.10   |  17.10.0 - 17.10.4      | 17.10.5           |
49  | 17.9    |  17.9.0 - 17.9.4        | 17.9.5            |
50
51该项目的描述。