# 排查从 GitHub Enterprise Server 到 GHE.com 的实时迁移问题

有关迁移可能遇到的问题的建议。

> \[!NOTE]
> Enterprise Live Migrations 位于 公开预览，可能会有变动。

如果迁移遇到问题，请检查迁移状态 `elm migration status --migration-id MIGRATION-ID` 并查看错误信息。

## 状态和建议的措施

| 地位                      | Meaning               | 建议的操作                                           |
| ----------------------- | --------------------- | ----------------------------------------------- |
| **创建**                  | 迁移已创建，但尚未启动           |                                                 |
| `elm migration start`运行 |                       |                                                 |
| 已排队 \*\*\*\*            | 迁移正在等待开始              | Wait                                            |
| **出口**                  | 正在从源导出数据              | 通过 `elm migration status` 进行监控                  |
| **处理**                  | 导出的数据正在导入到目标          | 通过 `elm migration status` 进行监控                  |
| **准备切换**                | 初始迁移已完成，迁移已准备就绪，可进行切换 | 准备就绪后，运行 `elm migration cutover-to-destination` |
| **切换中**                 | 源存储库已存档，其余更改将应用于目标    | 监控;状态将转换为 **“已完成”**                             |
| **Completed**           | 迁移已成功完成               | 验证目标存储库并回收模拟对象                                  |
| **失败**                  | 迁移遇到无法恢复的失败           | 调查错误（请参阅下文）                                     |
| **已暂停**                 | 迁移已暂停                 | 检查暂停原因并解决问题（请参阅下文）                              |
| **已终止**                 | 迁移已取消                 | N/A                                             |
| **已降级**                 | 目标无法访问                | 检查GitHub企业服务器设备与 GHE.com 之间的网络连接（请参阅下文）         |

## 迁移状态为“失败”

当无法恢复的错误阻止迁移继续时，迁移将进入 **“失败** ”状态。 这不同于单个资源导入失败—迁移失败意味着迁移本身无法继续。

若要分析，请运行 `elm migration status --migration-id MIGRATION-ID` 并查看响应中的错误详细信息。 每次失败都会包含格式为`(Correlation ID for Support: UUID)`的关联 ID。 如果联系 GitHub 支持，请提供此 ID，以便支持团队可以进行调查。

解决基础问题后，使用 `elm migration cancel --migration-id MIGRATION-ID` 中止失败的迁移并启动新的迁移。

## 迁移状态为“已暂停”

当问题需要干预后，迁移会进入 **暂停** 状态，然后才能继续。 运行 `elm migration status --migration-id MIGRATION-ID` 并检查暂停原因。

常见的暂停原因：

* **凭据过期**：其中一个 personal access tokens (classic) 凭据已过期。 创建一个具有所需作用域的新令牌，并用 `elm credential update` 更新它。 然后重启迁移。
* **速率限制**：迁移达到 API 速率限制。 等待几分钟，然后重启。

若要在解决基础问题后重启暂停的迁移，请执行以下操作：

```shell
elm migration start --migration-id MIGRATION-ID
```

## 迁移状态为“已降级”

**降级**状态意味着设备上的迁移服务GitHub Enterprise Server无法访问目标企业。 迁移在源端继续，但目标状态未知。

检查GitHub Enterprise Server设备与GHE.com子域之间的网络连接，然后再次运行`elm migration status --migration-id MIGRATION-ID`。 状态响应包括与目标最后一次成功联系的时间戳，这有助于评估连接问题发生的时间。

## 迁移卡在“导出”阶段

如果迁移仍处于 **导出** 状态，且 30 分钟或更多时间没有进度更改，导出程序可能会停滞不前。

1. 运行 `elm migration status --migration-id MIGRATION-ID` 并记下资源计数是否发生更改。

2. 如果计数值没有变化，请检查设备到目标端的网络连通性。

3. 查看设备上的导出程序日志 GitHub Enterprise Server （需要 SSH 管理员访问权限）：

   ```shell copy
   journalctl -t elm-exporter-backfiller --since "1 hour ago" | tail -50
   journalctl -t elm-exporter-sender --since "1 hour ago" | tail -50
   ```

4. 如果导出程序任务崩溃，它应会自动恢复。 如果未完成，请联系 GitHub 支持。

## Git 同步未完成

如果 `elm migration status` 显示初始 Git 推送在较长时间内未完成，请检查 Git 同步器日志：

```shell copy
journalctl -t elm-exporter-git-syncer --since "2 hours ago"
```

查找:

* **`connection refused`**：设备与目标之间的 GitHub Enterprise Server 网络问题。 检查防火墙规则和 DNS 解析。
* \*\*`authentication failed`\*\*personal access token (classic)：可能缺少所需的范围或已过期。
* **`remote: error`**：目标端可能正在拒绝推送。 请联系 GitHub 支持，并提供错误详情。

## 某些资源无法导入

单个资源可能无法导入，而不会导致整体迁移失败。 在 `elm migration status --migration-id MIGRATION-ID` 的输出中可以看到失败资源的计数。

只有在所有自动重试都用尽后，才会显示失败的资源，因此在无需干预的情况下，你看到的任何失败都会被确认为无法解决。 查看状态响应中的错误详细信息：在补全或实时更新中，每个失败的资源都会显示 `"state":  "failed"`。

如果失败资源的数量和类型可以接受，就可以进行切换。 否则，中止迁移，解决基础问题，然后启动新的迁移。

## 切换失败，源存储库不可用

如果在源存储库已归档后切换失败，ELM 服务将尝试取消归档该存储库。 如果此操作失败，存储库管理员可以取消存储库的存档。 请参阅“[存档仓库](/zh/enterprise-server@3.22/repositories/archiving-a-github-repository/archiving-repositories#unarchiving-a-repository)”。

请注意，取消存档存储库将导致实例上的额外负载，因为存储库中的所有问题和拉取请求都将在 Elasticsearch 中重新编制索引。

源存储库取消存档后，您可以使用 `elm migration cutover-to-destination --migration-id MIGRATION-ID` 重试切换，或者使用 `elm migration cancel --migration-id MIGRATION-ID` 中止迁移，并在准备就绪后开始新的迁移。

## 由于强制推送，必须重新启动迁移

如果在迁移正在进行时有人强制推送到源存储库的默认分支，则源和目标之间的 Git 同步会中断。 强制推送会以无法增量合并的方式重写提交历史记录。

如果发生这种情况，请使用 `elm migration cancel --migration-id MIGRATION-ID` 中止迁移，并启动新的迁移。 在重启之前，请与团队沟通，当迁移处于活动状态时，不允许强制推送到默认分支。

## 访问令牌被拒绝

如果迁移失败并出现身份验证错误，请检查：

* 源令牌和目标令牌都是 personal access tokens (classic)。 不支持细粒度令牌。
* 令牌具有 [使用企业实时迁移迁移存储库](/zh/enterprise-server@3.22/migrations/elm/migrate-your-repository#1-create-access-tokens) 中指定的范围。
* 如果目标组织强制实施 SAML 单一登录，则必须对令牌进行 SSO 授权。

如果最近轮换了令牌，迁移过程会自动获取新的凭据。 无需运行 `ghe-config-apply` 或重启迁移服务。

## 源 GHES URL 被拒绝

Enterprise Live Migrations 需要 GitHub Enterprise Server URL 才能使用 HTTPS。 如果 URL 配置为 HTTP，迁移将在预检验证阶段失败。

## 收集日志以获取支持

联系 GitHub 支持 时，最有用的信息包括：

1. **支持包**（首选）：在`ghe-support-bundle -u`设备上运行GitHub Enterprise Server。 这会自动捕获所有 ELM 日志。
2. **迁移状态输出**： `elm migration status --migration-id MIGRATION-ID`
3. **迁移 ID** 和大约失败时间（带时区）
4. **错误消息中的任何关联 ID**

如果不支持捆绑包，可以手动收集日志：

```shell copy
journalctl -t elm-exporter-migration-manager --since "24 hours ago" > migration-manager.log
journalctl -t elm-exporter-backfiller --since "24 hours ago" > backfiller.log
journalctl -t elm-exporter-sender --since "24 hours ago" > sender.log
journalctl -t elm-exporter-git-syncer --since "24 hours ago" > git-syncer.log
```