# 从备份还原

使用先前创建的备份快照还原GitHub Enterprise Server实例。

可以使用命令行从备份还原 GitHub Enterprise Server 实例。 备份服务支持完整实例还原，包括配置和用户数据。

> \[!WARNING] 从备份中还原将会覆盖实例上的所有现有数据\*\*\*\*。 无法撤消此操作。

## 快照版本要求

仅当某个快照最多落后目标实例版本的两个功能版本时，才能还原该快照。

例如：

* 例如，版本 3.17 的快照可以还原到运行 3.17.x、3.18.x 或 3.19.x 的目标。
* 不能将 3.17 的快照还原到 3.20，因为这已经超出了两个版本的范围。

不能从较新版本还原到较旧版本。 例如，尝试将 3.18 快照还原到 3.17 实例将失败，出现以下错误信息：`Error: Snapshot can not be restored to an older release of GitHub Enterprise Server.`

## Prerequisites

还原备份前：

1. 在目标实例上启用维护模式\*\*\*\*。 请参阅“[启用和排定维护模式](/zh/enterprise-server@3.21/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode)”。
2. 验证对包含快照的备份存储的访问权限\*\*\*\*。
3. 暂停干扰服务 - 如果使用高可用性 (HA)，请确保已停止复制\*\*\*\*。
4. **为 GitHub Actions 做好准备** — 如果启用了该功能，请确保目标实例已配置正确的外部存储。 有关详细信息，请参阅“[在启用GitHub Actions的情况下进行还原](/zh/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/restoring-with-github-actions-enabled)”。

## 启动还原操作

要从快照还原，请执行以下步骤：

1. 以 `admin` 用户身份通过 SSH 登录目标实例。

2. 运行下列命令之一：

   * 最新快照恢复

     ```shell
     ghe-restore
     ```

   * 还原特定快照。 将 `<SNAPSHOT_TIMESTAMP>` 替换为要还原的快照的时间戳（例如 `YYYYMMDDTHHMMSS`）。

     ```shell
     ghe-restore -s <SNAPSHOT_TIMESTAMP>
     ```

   * （可选）强制重写配置、许可证和证书数据：

     ```shell
     ghe-restore -c          # Latest snapshot
     ghe-restore -s <SNAPSHOT_TIMESTAMP> -c  # Specific snapshot
     ```

3. **在管理控制台内完成：**

   * 查看所有配置设置（网络、身份验证、TLS 等）。
   * 单击“Save settings”，应用这些设置并启动服务\*\*\*\*。
   * 只有完成此步骤后，实例才会完全正常运行。

4. 验证还原的实例\*\*\*\*，确保一切按预期工作。

5. 如果使用 HA\*\*\*\*，请先在独立实例上完成还原。 然后重新配置 HA。

   * 如果遇到同步问题（例如 `ghe-repl-status` 中的过时 UUID），请运行 `ghe-repl-teardown`。
   * 如需帮助，请联系 GitHub 支持。

6. **重新注册自托管 GitHub Actions 运行器**，因为恢复操作会使之前的令牌失效。

## 快照轮换和保留

根据您的保留设置，快照会被自动修剪：

* 仅保留最新的 n 个快照（根据配置）。
* 每次成功备份后，都会删除较旧的快照。
* 快照使用时间戳 (`YYYYMMDDTHHMMSS`) 进行命名，以便于参考。
* 硬链接用于有效存储未更改的文件，同时保留完整还原功能。

## 排查恢复失败问题

如果还原操作失败，请检查以下项：

* 备份完整性\*\*\*\* - 确保快照未中断或未损坏。
* 存储访问\*\*\*\* - 验证实例是否可以装载和读取备份卷。
* 版本不匹配\*\*\*\* - 确认快照版本与目标实例兼容。
* 日志\*\*\*\* - 查看 `/var/log/github-backup/restore-verbose-[timestamp].log` 是否存在问题。

管理控制台如果显示常规故障，请通过 SSH 连接到实例以访问详细日志。