此版本的 GitHub Enterprise Server 将于以下日期停止服务 2026-08-25. 已停止发布的版本不受支持。 即使针对重大安全问题，也不会发布补丁。 若要获得更好的性能、改进的安全性和 GitHub Enterprise Server 中的新功能，请参阅升级过程的 Overview。 如需升级帮助，请联系 GitHub Enterprise 支持。

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

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

在本文中

注意

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 速率限制。 等待几分钟，然后重启。

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

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
    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
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"。

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

直接转换失败，源存储库已锁定

如果直接转换失败，源存储库可能会保持锁定或存档状态。 这可以防止开发人员在目标可能仍然不完整的情况下推送到源。

若要解锁源存储库，站点管理员必须从中 GitHub Enterprise Server管理控制台解锁它。

在源解锁后，可以使用 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)。 不支持细粒度令牌。
  • 令牌具有 使用企业实时迁移迁移存储库 中指定的范围。
  • 如果目标组织强制实施 SAML 单一登录，则必须对令牌进行 SSO 授权。

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

源 GHES URL 被拒绝

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

收集日志以获取支持

联系GitHub 支持时，最有用的材料是：

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

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

Shell
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