进阶 onorca.dev 2026-10-18 18:52:09 · 19 阅读
第5章 第 5 章：GitHub 错误排查指南
# 第 5 章：排查 GitHub 错误
诊断 Orca 中 PR 检查、Tasks 和源代码控制里的速率限制、认证失败及其他 GitHub CLI 错误。
Orca 通过你机器（或远程 Orca 主机）上的 GitHub CLI（gh）与 GitHub 通信。当 PR 状态、检查、问题或 Tasks 无法刷新时，原因几乎总是 GitHub 认证、权限或 API 速率限制——而非 PR 面板本身故障。
本页涵盖最常出现的错误及其修复方法。
## 快速分诊
| 你看到的现象 | 可能原因 | 首选尝试步骤 |
| :--- | :--- | :--- |
| “GitHub is rate-limiting requests” / “rate limit exceeded (core)” | 用户的 GitHub REST（core）配额已耗尽 | 等待重置；停止额外的 gh / agent / Orca 使用；检查 Settings → Git → GitHub API Budget |
| “GitHub authentication is unavailable” / gh auth 提示 | gh 未登录、令牌过期或 GITHUB_TOKEN 无效 | 运行 gh auth status，然后执行 gh auth login |
| “GitHub did not allow access” / HTTP 403（非速率限制） | 缺少 scope 或对仓库无访问权限 | 使用具有相应仓库（及所需组织 SSO）的凭据重新认证；确认能在浏览器中打开该 PR |
| “repository is unavailable” / HTTP 404 | 远程地址错误、无权限的私有仓库或仓库已重命名 | 检查 git remote -v 和浏览器访问情况 |
| “GitHub is unreachable” / 超时 | 网络、代理、VPN 或 GitHub 故障 | 检查 githubstatus.com；在关闭 VPN 的情况下重试 |
| “GitHub CLI is unavailable” | Orca 使用的 PATH 中缺少 gh | 安装 gh 并重启 Orca |
## 速率限制（最常见）
GitHub 为每个经过认证的用户提供共享的小时级预算。该账号上的所有工具都共享此配额：包括 Orca、终端中的 gh、调用 gh 的 Claude/Codex/Grok 代理、CI 脚本、浏览器扩展及其他应用。
### Orca 关注的配额桶
| 配额桶 | 覆盖范围 | 典型限制（已认证） |
| :--- | :--- | :--- |
| REST (core) | 大多数 PR/Issue/API 调用（gh pr view、检查元数据、许多 REST 端点） | 5,000 / 小时 |
| GraphQL | 项目/Tasks 及部分更丰富的 PR 查询 | 5,000 points / 小时 |
| Search | 搜索驱动的列表 | 30 / 分钟 |
当主要配额桶耗尽时，GitHub 返回带消息的 HTTP 403，例如 *API rate limit exceeded*。Orca 会将其归类为速率限制，在可能的情况下保留最后已知的 PR 状态，并在短时间窗口内停止生成更多的 gh 调用，防止单次限制演变成故障风暴。
### 为什么 Settings 看起来“正常”但 PR 面板被阻断
Settings → Git → GitHub API Budget 读取 GitHub 特殊的 rate_limit 端点。该探针不受速率限制统计约束，有时仍会报告剩余配额，而实际上同一用户的真实 REST 调用已返回 remaining: 0。
当数据不一致时，请信任以下优先级：
1. PR / Checks 面板上的错误（实时请求失败）
2. 真实的 CLI 检查（见下文）
3. Settings 中的预算数字（有用，但仅为探针结果）
此外，不要将 GitHub API Budget 与 Accounts 下的 Claude / Codex / Grok 用量混淆——后者是 AI 提供商的限制，而非 GitHub 的 REST 配额。
### 从终端确认速率限制
```bash
# 探针（不消耗配额；结果可能比实际更“健康”）
gh api rate_limit --jq '.resources | {core, graphql, search}'
# 真实的 REST 调用——这是 PR 刷新所依赖的
gh api user -i 2>&1 | head -40
```
如果 gh api user 返回 403 且伴随 *API rate limit exceeded* 以及 X-Ratelimit-Remaining: 0，则该账号在 X-Ratelimit-Reset（Unix 纪元秒）之前被禁止进行 REST 调用。
### 通常消耗配额的情况
- 同时打开多个 Orca 窗口或 electron-dev 构建（每个可能都会刷新 PRs / Tasks）
- 代理自动运行 gh（分配 PR/Issue、轮询检查、批量 GraphQL）
- 在刷新 PR 面板的同时执行大量 Tasks / 多仓库扇出
- 其他使用相同 GitHub 用户令牌的应用
### 应对措施
- 等待错误中显示的每小时重置时间或 X-Ratelimit-Reset 指定的时间。
- 减少并发的 GitHub 客户端——退出额外的 Orca 实例并暂停批量 gh 自动化任务。
- 在受限期间避免在 PR 面板上频繁点击刷新；Orca 已在自动退避。
- 优先在脚本中批量处理 GraphQL；避免在个人账号上使用循环逐一处理大型集合的 REST 请求。
- 重置后，如果 PR 刷新仍然失败，请重新检查认证（下一节）。
## 认证问题
Orca 继承该主机上 gh 所使用的任何配置。
### 检查状态
```bash
gh auth status -h github.com
gh api user --jq '{login, id}'
```
正常输出：已登录，令牌有效，gh api user 返回你的登录名。
### 常见陷阱
- Shell profile 中的 GITHUB_TOKEN / GH_TOKEN
如果这些变量被导出（例如在 `~/.bash_profile` 或 `~/.zshrc` 中设置 `export GITHUB_TOKEN=$(gh auth token)`），`gh` 会优先使用环境变量而非钥匙链。过期的或不正确的环境变量 token 会导致令人困惑的认证或速率限制问题。请取消设置这些变量并重新登录： unset GITHUB_TOKEN GH_TOKEN gh auth logout -h github.com gh auth login -h github.com
token 过期或被撤销
`gh auth status` 可能显示 token 无效。运行 `gh auth login`（或 `gh auth refresh`），然后重启 Orca 以使其识别新的凭据。
组织 SAML SSO
私有组织仓库的 token 可能需要 SSO 授权。从 GitHub token 设置中打开该组织的 SSO 授权链接，然后重试。
远程 / SSH worktree
GitHub 的认证是按主机隔离的。在笔记本上登录，并不意味着远程机器上的 gh 也已登录。请 SSH 到对应主机执行 gh auth login，或在该环境中使用 Orca 的远程服务器 GitHub 预算视图。 权限与仓库错误 现象含义HTTP 403 且不含 “rate limit”Token 缺少权限范围，或你无权访问该资源HTTP 404 / “could not resolve to a Repository”仓库不存在、已改名，或对该 token 不可见“resource not accessible by integration”App/token 类型无法执行该操作 解决方法： 确认以 gh api user 所显示的同一用户身份，能在浏览器中打开对应 PR/仓库 重新认证，使用包含 repo 的 classic 权限范围（如用到相应功能，还需 read:org / project） 对于 GitHub Enterprise，确保 gh 已针对该主机名完成认证（gh auth login --hostname …） 网络问题与 GitHub 故障 出现超时、“could not resolve host” 或 “GitHub is unreachable” 等提示，说明是连接问题： 查看 GitHub Status 尝试关闭 VPN / 公司代理 在远程主机上，确认可正常访问 api.github.com 的出站 HTTPS GitHub CLI 缺失 如果 Orca 提示 GitHub CLI 不可用： 安装 gh 在普通终端中确认 which gh 可用 完全退出并重新打开 Orca（使 PATH 保持一致） 在 Windows 上，确保安装到 Orca 启动所用的同一环境（WSL 或原生） GitHub 故障时 Orca 的表现 限流 / 故障：PR 和 Checks 面板会保留最近已知状态并显示简短横幅，而不会清空界面。 严重的认证 / 权限失败：会给出清晰的空状态或横幅提示，指导你修复登录或权限问题。 熔断机制：一旦主限流返回 403，Orca 会暂时拒绝为对应桶（core、search 或 graphql）发起新的 gh 进程，以保持应用响应流畅，避免问题恶化。 在 Orca 中查看 GitHub API 预算 打开 Settings → Git，找到 GitHub API Budget： 来自 GitHub 探测的 REST / Search / GraphQL 剩余额度 等待限流解除后刷新 在远程 Orca 服务器上，请使用远程高级预算视图查看服务器端 gh 身份的额度（本地 Settings 只显示桌面客户端） 仍然无法解决？ 在与 Orca 相同的机器和用户下，用 gh pr view 或 gh api user 在终端中复现一次。 收集日志：Help → Open Logs。 提交 issue 时附上分类后的错误文本（不含密钥）、gh auth status 脱敏后的输出，以及终端中 gh 是否出现同样错误。 GitHub Issues Discord 相关内容 Hosted reviews, issues & Actions — 依赖 GitHub 的 PR 和 Checks 功能 Settings reference — Integrations 与 Git 面板 Usage & rate-limit tracking — AI 供应商（Claude/Codex）的用量与限流，与 GitHub API 无关 Troubleshooting & FAQ — Orca 的常见问题
如果这些变量被导出（例如在 `~/.bash_profile` 或 `~/.zshrc` 中设置 `export GITHUB_TOKEN=$(gh auth token)`），`gh` 会优先使用环境变量而非钥匙链。过期的或不正确的环境变量 token 会导致令人困惑的认证或速率限制问题。请取消设置这些变量并重新登录： unset GITHUB_TOKEN GH_TOKEN gh auth logout -h github.com gh auth login -h github.com
token 过期或被撤销
`gh auth status` 可能显示 token 无效。运行 `gh auth login`（或 `gh auth refresh`），然后重启 Orca 以使其识别新的凭据。
组织 SAML SSO
私有组织仓库的 token 可能需要 SSO 授权。从 GitHub token 设置中打开该组织的 SSO 授权链接，然后重试。
远程 / SSH worktree
GitHub 的认证是按主机隔离的。在笔记本上登录，并不意味着远程机器上的 gh 也已登录。请 SSH 到对应主机执行 gh auth login，或在该环境中使用 Orca 的远程服务器 GitHub 预算视图。 权限与仓库错误 现象含义HTTP 403 且不含 “rate limit”Token 缺少权限范围，或你无权访问该资源HTTP 404 / “could not resolve to a Repository”仓库不存在、已改名，或对该 token 不可见“resource not accessible by integration”App/token 类型无法执行该操作 解决方法： 确认以 gh api user 所显示的同一用户身份，能在浏览器中打开对应 PR/仓库 重新认证，使用包含 repo 的 classic 权限范围（如用到相应功能，还需 read:org / project） 对于 GitHub Enterprise，确保 gh 已针对该主机名完成认证（gh auth login --hostname …） 网络问题与 GitHub 故障 出现超时、“could not resolve host” 或 “GitHub is unreachable” 等提示，说明是连接问题： 查看 GitHub Status 尝试关闭 VPN / 公司代理 在远程主机上，确认可正常访问 api.github.com 的出站 HTTPS GitHub CLI 缺失 如果 Orca 提示 GitHub CLI 不可用： 安装 gh 在普通终端中确认 which gh 可用 完全退出并重新打开 Orca（使 PATH 保持一致） 在 Windows 上，确保安装到 Orca 启动所用的同一环境（WSL 或原生） GitHub 故障时 Orca 的表现 限流 / 故障：PR 和 Checks 面板会保留最近已知状态并显示简短横幅，而不会清空界面。 严重的认证 / 权限失败：会给出清晰的空状态或横幅提示，指导你修复登录或权限问题。 熔断机制：一旦主限流返回 403，Orca 会暂时拒绝为对应桶（core、search 或 graphql）发起新的 gh 进程，以保持应用响应流畅，避免问题恶化。 在 Orca 中查看 GitHub API 预算 打开 Settings → Git，找到 GitHub API Budget： 来自 GitHub 探测的 REST / Search / GraphQL 剩余额度 等待限流解除后刷新 在远程 Orca 服务器上，请使用远程高级预算视图查看服务器端 gh 身份的额度（本地 Settings 只显示桌面客户端） 仍然无法解决？ 在与 Orca 相同的机器和用户下，用 gh pr view 或 gh api user 在终端中复现一次。 收集日志：Help → Open Logs。 提交 issue 时附上分类后的错误文本（不含密钥）、gh auth status 脱敏后的输出，以及终端中 gh 是否出现同样错误。 GitHub Issues Discord 相关内容 Hosted reviews, issues & Actions — 依赖 GitHub 的 PR 和 Checks 功能 Settings reference — Integrations 与 Git 面板 Usage & rate-limit tracking — AI 供应商（Claude/Codex）的用量与限流，与 GitHub API 无关 Troubleshooting & FAQ — Orca 的常见问题
