升级 GitHub Enterprise Server

关于 GitHub Enterprise Server 的升级

GitHub Enterprise Server 在不断改进，通过功能和修补程序版本引入了新功能和缺陷修复。你负责升级到实例。 有关详细信息，请参阅“关于升级到新版本”。

要升级实例，必须计划并沟通升级事宜，选择适当的包，备份数据，然后执行升级。

先决条件

要成功升级 你的 GitHub Enterprise Server 实例，实例的数据磁盘必须至少有 15% 的可用空间。 GitHub 建议确保磁盘上有更多可用存储空间。 在某些极少数情况下，对于具有大量数据的客户，此阈值可能有所不同。

升级时，通过预外部测试检查来评估实例是否满足有关系统硬件资源（例如内存、CPU 核心和用户和根磁盘存储）的最低要求。 如果预外部测试检查确定资源不足，或者因其他原因未通过检查，则系统会通知你并中止升级。

准备升级

要准备升级，请规划升级路径，根据需要升级 GitHub Actions 运行器，并计划维护时段。

1. 确定升级策略并选择要升级到的版本。 有关详细信息，请参阅“升级要求”和 升级助手 以查找当前发行版本的升级路径。

2. 使用GitHub Enterprise Server Backup Utilities 创建实例主节点的全新备份。 有关详细信息，请参阅 GitHub Enterprise Server Backup Utilities 项目文档中的 README。

   注意：GitHub Enterprise Server Backup Utilities 版本需要与 你的 GitHub Enterprise Server 实例 版本相同，或前者最多比后者低两个版本。 有关详细信息，请参阅“在实例上配置备份”。

3. 如果 你的 GitHub Enterprise Server 实例 对 GitHub Actions 使用临时自承载运行器，并且已禁用自动更新，请将运行器升级到升级实例将运行的运行器应用程序版本。 若要查找版本所需的最低版本，请参阅“GitHub Enterprise Server 发行版”。

4. 如果你要使用升级包进行升级，请为 GitHub Enterprise Server 最终用户排定维护窗口。 如果你要使用热补丁，则不需要使用维护模式。

   注意：维护时段取决于所执行升级的类型。 使用热补丁进行升级通常不需要维护窗口。 有时需要重启，不过你可以在之后的某个时间重启。 按照 MAJOR.FEATURE.PATCH 的版本控制方案，使用升级包的补丁版本通常需要不到 5 分钟的停机时间。 包含数据迁移的功能版本需要的时间更长，具体视存储性能以及迁移的数据量而定。 有关详细信息，请参阅“启用和排定维护模式”。

生成快照

快照存储虚拟机 (VM) 在某一时间点的状态。 GitHub 强烈建议在升级 VM 之前生成快照，这样一来，如果升级失败，可以将 VM 还原到快照状态。 GitHub 建议仅在实例的 VM 处于关闭状态或实例处于维护模式且所有后台作业都已完成时创建 VM 快照。

如果你要升级到新的功能版本，则必须生成 VM 快照。 如果你要升级到补丁版本，可以连接现有数据磁盘。

有两种类型的快照：

• VM 快照会保存整个 VM 状态，包括用户数据和配置数据。 此快照方法需要占用大量磁盘空间，且比较耗时。

• 数据磁盘快照仅保存用户数据。

  注意：

  • 某些平台不允许你只生成数据磁盘的快照。 对于此类平台，你需要生成整个 VM 的快照。
  • 如果你的虚拟机监控程序不支持完整的 VM 快照，你应连续、快速地生成根磁盘和数据磁盘的快照。

平台	Snapshot 方法	文档
Amazon AWS	磁盘	AWS 文档中的创建 Amazon EBS 快照
Azure	VM	在 Microsoft Learn 的 Azure VM 上创建虚拟硬盘的快照
Hyper-V	VM	Microsoft Learn 中的在 Hyper-V 中启用或禁用检查点
Google Compute Engine	磁盘	Google Cloud 文档中的 Create and manage disk snapshots（创建和管理磁盘快照）
VMware	VM	VMware Docs 中的 Taking Snapshots of a Virtual Machine（拍摄虚拟机的快照）

选择升级包

可将 GitHub Enterprise Server 实例升级到新补丁版或新功能版。 要升级到补丁版，可使用热补丁或升级包。 要升级到功能版，必须使用升级包。

GitHub Enterprise Server 实例包含一个或多个节点。 必须遵循的升级过程取决于实例有多少节点。 有关详细信息，请参阅“关于 GitHub Enterprise Server”。

• 使用热补丁升级
  • 使用热补丁升级独立实例
  • 使用热补丁升级具有多个节点的实例
• 使用升级包升级
  • 使用升级包升级独立实例
  • 使用升级包升级具有多个节点的实例

使用热补丁升级

可使用热补丁将 GitHub Enterprise Server 升级到最新的补丁版本。

您可以使用热更新来升级到更新的补丁版本，但不能升级到功能版本。 例如，你可从 2.10.1 升级到 2.10.5，因为它们位于同一功能系列中，但不能从 2.10.9 升级到 2.11.0，因为它们位于不同的功能系列中。

热补丁通常不要求重启。 如果热补丁确实要求重启，GitHub Enterprise Server 发行说明将说明此要求。

热补丁需要配置运行，这可能会导致 你的 GitHub Enterprise Server 实例 上的部分或所有服务短暂出现错误或无响应。 无需在热补丁安装期间启用维护模式，但这样做将保证用户看到维护页，而不是错误或超时。 有关详细信息，请参阅“启用和排定维护模式”。

使用 管理控制台，你可以立即安装热补丁，也可以安排以后安装。 你可以使用管理 shell 通过 ghe-upgrade 实用程序安装热补丁。 有关详细信息，请参阅“升级要求”。

• 使用热补丁升级独立实例
• 使用热补丁升级具有多个节点的实例

使用热补丁升级独立实例

如果要使用热补丁升级只有一个节点的实例，并且目标版本是补丁版，则可使用 管理控制台 进行升级。 若要升级到功能版本，必须使用管理 shell。

• 使用 管理控制台 安装热补丁
• 使用管理 shell 安装热补丁

使用 管理控制台 安装热补丁

你可以通过启用自动更新来使用 管理控制台 通过热补丁进行升级。 然后，你将看到可升级到的最新可用 GitHub Enterprise Server 版本。

如果显示的升级目标是功能版本而不是修补程序版本，则无法使用 管理控制台 来安装修补程序。 你必须改为使用管理 shell 安装热补丁。 有关详细信息，请参阅“使用管理 shell 安装热补丁”。

1. 启用自动更新。 有关详细信息，请参阅“启用自动更新检查”。

2. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击 。

3. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

4. 在“ 站点管理”边栏中，单击“管理控制台”。

5. 在顶部导航栏中，单击“更新”。

   

6. 在新的热补丁下载完毕后，请选择“安装包”下拉菜单。

   • 若要立即安装，请单击“立即”。
   • 要稍后安装，请选择以后的日期。

7. 单击“安装” 。

使用管理 shell 安装热补丁

1. 通过 SSH 连接到 你的 GitHub Enterprise Server 实例。 如果实例包含多个节点，例如，如果配置了高可用性或异地复制，则通过 SSH 连接到主节点。 如果使用群集，则可以通过 SSH 连接到任何节点。 将 HOSTNAME 替换为实例的主机名，或节点的主机名或 IP 地址。 有关详细信息，请参阅“访问管理 shell (SSH)”。

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. 浏览到 GitHub Enterprise Server 版本页。 在要升级到的版本旁边，单击“下载”，然后单击“升级”选项卡 。 复制升级热补丁包（.hpkg 文件）的 URL。

3. 使用 curl 将升级包下载到 你的 GitHub Enterprise Server 实例：

   admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL
   

4. 使用包文件名运行 ghe-upgrade 命令：

   admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.hpkg
   *** verifying upgrade package signature...
   

5. 如果至少一个服务或系统组件需要重新启动，热补丁升级脚本会发出通知。 例如，对内核、MySQL 或 Elasticsearch 的更新可能需要重启。

使用热补丁升级具有多个节点的实例

如果要安装热补丁，则无需进入维护模式或停止复制。

• 使用热补丁升级主节点
• 使用热补丁升级其他节点

使用热补丁升级主节点

有关升级主节点的说明，请参阅“使用管理 shell 安装热补丁”。

使用热补丁升级其他节点

要升级包含多个节点的实例（例如高可用性或异地复制配置），必须在每个副本节点上逐个重复以下过程。

1. 要升级节点，请按照“使用管理 shell 安装热补丁”中的说明操作。

2. 以 admin 用户身份在端口 122 上通过 SSH 连接到副本节点：

   ssh -p 122 admin@REPLICA_HOST
   

3. 运行以下命令来验证升级：

   ghe-version
   

4. 对其他每个节点重复上述步骤。

使用升级包升级

虽然你可以使用热补丁升级到功能系列中的最新补丁版本，但必须使用升级包升级到更新的功能版本。 例如，要从 2.11.10 升级到 2.12.4，你必须使用升级包，因为两者属于不同的功能系列。 有关详细信息，请参阅“升级要求”。

• 使用升级包升级独立实例
• 使用升级包升级具有多个节点的实例

使用升级包升级独立实例

1. 通过 SSH 连接到 你的 GitHub Enterprise Server 实例。 如果实例包含多个节点，例如，如果配置了高可用性或异地复制，则通过 SSH 连接到主节点。 如果使用群集，则可以通过 SSH 连接到任何节点。 将 HOSTNAME 替换为实例的主机名，或节点的主机名或 IP 地址。 有关详细信息，请参阅“访问管理 shell (SSH)”。

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. 浏览到 GitHub Enterprise Server 版本页。 在要升级到的版本旁边，单击“下载”，然后单击“升级”选项卡 。 选择适当的平台并复制升级包（.pkg 文件）的 URL。

3. 使用 curl 将升级包下载到 你的 GitHub Enterprise Server 实例：

   admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL
   

4. 启用维护模式并等待 GitHub Enterprise Server 实例上的所有活动进程完成。 有关详细信息，请参阅“启用和排定维护模式”。

   注意：升级采用高可用性配置的主节点时，如果你按照通过升级包升级主节点中的说明操作，实例应当已处于维护模式。

5. 使用包文件名运行 ghe-upgrade 命令：

   admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.pkg
   *** verifying upgrade package signature...
   

6. 确认你要继续升级，并在包签名得到验证后重新启动。 新的根文件系统会写入辅助分区，实例会在维护模式下自动重启：

   *** applying update...
   This package will upgrade your installation to version VERSION-NUMBER
   Current root partition: /dev/xvda1 [VERSION-NUMBER]
   Target root partition:  /dev/xvda2
   Proceed with installation? [y/N]
   

7. （可选）在升级到功能版的过程中，可以使用 ghe-migrations 实用工具监视数据库迁移的状态。 有关详细信息，请参阅“命令行实用程序”。

8. 实例重启后，升级将在后台继续。 在过程完成后，才能取消设置维护模式。

要检查后台作业的状态，请使用 ghe-check-background-upgrade-jobs 实用工具。 如果正在运行连续升级，则必须确保后台作业完成，然后再继续下列升级到功能版。 要将此实用工具与 GitHub Enterprise Server 3.9 一起使用，实例必须运行版本 3.9.7 版或更高版本。 有关实用工具的详细信息，请参阅“命令行实用程序”。

要监视配置运行的进度，请读取 /data/user/common/ghe-config.log 中的输出。 例如，可以通过运行以下命令来跟踪日志：

tail -f /data/user/common/ghe-config.log

1. （可选）升级之后，通过配置 IP 例外列表以允许访问指定 IP 地址列表来验证升级。 有关详细信息，请参阅“启用和排定维护模式”。

2. 对于单个节点升级，请禁用维护模式，以便用户能够使用 你的 GitHub Enterprise Server 实例。

   注意：升级采用高可用性配置的实例后，你应当一直处于维护模式，直至已升级所有副本节点，且复制是最新版本。 有关详细信息，请参阅“使用升级包升级其他节点”。

使用升级包升级具有多个节点的实例

要使用升级包升级包含多个节点的实例，必须先升级主节点，然后再升级任何其他节点。

• 使用升级包升级主节点
• 使用升级包升级其他节点

使用升级包升级主节点

1. 在主节点上，启用维护模式并等待所有活动进程完成。 有关详细信息，请参阅“启用和排定维护模式”。

2. 以 admin 用户身份在端口 122 上通过 SSH 连接到副本节点：

   ssh -p 122 admin@REPLICA_HOST
   

3. 要停止所有节点上的复制，请在每个节点上运行 ghe-repl-stop。

4. 要升级主节点，请按照“使用升级包升级独立实例”中的说明进行操作。

使用升级包升级其他节点

要升级包含多个节点的实例（例如高可用性或异地复制配置），必须在每个副本节点上逐个重复以下过程。

1. 按照“使用升级包升级独立实例”中的说明升级节点。

2. 以 admin 用户身份在端口 122 上通过 SSH 连接到副本节点：

   ssh -p 122 admin@REPLICA_HOST
   

3. 运行以下命令来验证升级：

   ghe-version
   

4. 在副本节点上，要启动复制，请运行 ghe-repl-start。

5. 在副本节点上，为确保复制服务正常运行，请运行 ghe-repl-status。 成功开始复制且副本已升级时，此命令将对所有服务返回 OK。 如果命令返回 Replication is not running，则复制可能仍处于启动状态。 等待 1 分钟左右，然后再次运行 ghe-repl-status。

   注意：

   • 当正在进行重新同步时，ghe-repl-status 可能指示复制进程落后。 例如，你可能会看到以下消息。

     CRITICAL: git replication is behind the primary by more than 1007 repositories and/or gists
     

   • 如果在 你的 GitHub Enterprise Server 实例 上启用了 GitHub Actions，你可能会看到如下所示的消息。 当复制由于在主设备上设置维护模式而暂停时，预计会出现此消息。 一旦取消设置维护模式，此消息应会得到解决。

     CRITICAL: mssql replication is down, didn't find Token_Configuration!
     

   如果未 ghe-repl-status 返回 OK，并且上述笔记中未列出说明，请联系 GitHub Enterprise 支持。 有关详细信息，请参阅“联系 GitHub 支持”。

6. 对其他每个节点重复上述步骤。

7. 最后一个副本节点升级完成且重新同步完成后，请禁用维护模式，以便用户能够使用 你的 GitHub Enterprise Server 实例。

从失败的升级中恢复

如果升级失败或中断，你应将实例还原为其之前的状态。 完成此操作的过程取决于升级类型。

回滚补丁版本

要回滚修补程序版本，请将 ghe-upgrade 命令与 --allow-patch-rollback 开关结合使用。 在回滚之前，必须通过在所有副本节点上运行 ghe-repl-stop 来暂时停止复制。 回滚升级时，必须使用一个带 .pkg 扩展的升级包文件。 不支持带 .hpkg 扩展的热补丁包文件。

ghe-upgrade --allow-patch-rollback EARLIER-RELEASE-UPGRADE-PACKAGE.pkg

运行命令后需要重启。 回滚不会影响数据分区，因为迁移不是在补丁版本上运行的。

回滚完成后，通过在所有节点上运行 ghe-repl-start 来重新启动复制。

有关详细信息，请参阅“命令行实用程序”。

回滚功能版本

要从功能版本回滚，请从 VM 快照恢复，以确保根分区和数据分区处于一致的状态。 有关详细信息，请参阅“拍摄快照”。

延伸阅读

• 关于升级到新版本