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

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

在本文中

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

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

迁移状态为“失败”

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

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

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

迁移状态为“已暂停”

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

常见的暂停原因：

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

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

gh elm migration start --migration-id MIGRATION-ID

迁移状态为“已降级”

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

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

迁移卡在“导出”阶段

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

  1. 运行 gh 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 同步未完成

如果 gh 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 支持，并提供错误详情。

某些资源无法导入

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

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

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

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

如果在源存储库已归档后切换失败，ELM 服务将尝试取消归档该存储库。 如果此操作失败，存储库管理员可以取消存储库的存档。 请参阅“存档仓库”。

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

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

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

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

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

迁移访问令牌遭到拒绝

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

  • 源令牌和目标令牌都是 personal access tokens (classic)。 Fine-grained personal access tokens 不受支持。
  • 如果目标组织强制实施 SAML 单一登录，则必须对令牌进行 SSO 授权。
  • 这两个令牌都具有 使用企业实时迁移迁移存储库 中指定的范围。

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

GitHub CLI 访问令牌被拒绝

Enterprise Live Migrations 使用两组凭据。 本部分适用于在步骤 2 中创建并由本地存储的gh elm configure操作员令牌。

操作员必须为每个端点使用一个 personal access token (classic)：

  • 源操作器令牌必须在GitHub Enterprise Server上创建。
  • 必须在**** 上创建GHE.com。
  • 这两个令牌都具有 使用企业实时迁移迁移存储库 中指定的范围。
  • 令牌所有者必须是相应企业的管理员。 选择范围不会授予用户管理访问权限。
  • Fine-grained personal access tokens 不受支持。

常见响应

响应Meaning纠正方法
401 Bad credentials终结点无法对令牌进行身份验证。 尚未评估授权范围。检查令牌是否已过期或已吊销，是否已完全复制令牌，以及源令牌和目标令牌是否已交换。 确认每个令牌都是在其使用所在的主机上创建的。
403 Forbidden令牌已经过身份验证，但其用户或范围未授权该操作。将 personal access token (classic) 与 admin:enterprise 一起使用。 确认令牌所有者是企业管理员。 如果 SAML SSO 适用，请为 SSO 授权令牌。
Resource not accessible by personal access token不支持令牌类型或权限。 这通常发生在使用 fine-grained personal access token 时。将其替换为具有 admin:enterprise 的 personal access token (classic)。
404 Not Found请求可能使用了错误的 API URL，或者 Enterprise Live Migrations 可能未为目标企业启用。对于 GHE.com，请使用租户 API 的 URL，例如 https://api.SUBDOMAIN.ghe.com，末尾不要带斜杠。 也请验证源 API 的 URL。 如果这两个 URL 都正确，请联系 GitHub 支持 以确认 Enterprise Live Migrations 已启用。

独立验证令牌

在将每个令牌与 /user 一起使用之前，先针对 Enterprise Live Migrations 终结点进行测试。 这些命令打印响应标头，但放弃响应正文。

对于源（GitHub Enterprise Server）令牌：

curl --silent --show-error --output /dev/null --dump-header - \
  --header "Authorization: Bearer $SOURCE_OPERATOR_TOKEN" \
  "$SOURCE_API_URL/user"

对于目标词元：

curl --silent --show-error --output /dev/null --dump-header - \
  --header "Authorization: Bearer $TARGET_OPERATOR_TOKEN" \
  "$TARGET_API_URL/user"

每个请求都应返回 200 OK。 X-OAuth-Scopes 响应标头应包含 admin:enterprise。

如果 /user 返回的是 200 OK，而 Enterprise Live Migrations 命令返回的是 401 Bad credentials，则 CLI 可能存储了不同的令牌或 URL。 再次运行 gh elm configure ，并仔细地将每个令牌与其相应的终结点相关联。

操作员令牌由 Enterprise Live Migrations CLI 本地存储。 轮换操作员令牌后，再次运行 gh elm configure 或使用相应的命令行选项提供替换凭据。

这不同于步骤 4 中配置的迁移服务令牌。 更新后的迁移服务凭据会自动生效，不需要 ghe-config-apply，也不需要重启迁移服务。

不要在日志、屏幕截图、支持捆绑包或支持请求中包含访问令牌。 如果问题仍然存在，请向 GitHub 支持 提供 HTTP 状态、端点主机名、迁移 ID、带时区的时间戳以及任何关联 ID（如有），但不要提供令牌。

源 GHES URL 被拒绝

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

收集日志以获取支持

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

  1. 支持包（首选）：在ghe-support-bundle -u设备上运行GitHub Enterprise Server。 这会自动捕获所有 Enterprise Live Migrations 日志。
  2. 迁移状态输出： gh 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