第一版用 OAuth App 登录，用户授权后拿 access token 直接读写仓库，前期完全够用。等做到”代表机器人身份自动提交 PR、按组织批量翻译”时，OAuth App 就撑不住了：权限跟着用户个人走、速率限制和别的应用共享、提交记录显示的是用户本人。我在这件事上折腾了快两周，最终在”代表用户身份访问仓库”和”代表应用身份读写仓库”之间做出明确分工——核心集成换成 GitHub App，OAuth 只留在登录环节。GitHub App 提供了比 OAuth App 更精细的权限边界、更稳定的访问凭据、更好的速率限制与 Webhook 能力，下面把整个选型过程、踩过的坑和迁移代价完整讲一遍。
一、核心差异速览
先看结论再讲道理。两种 App 的差别集中在身份代表、权限粒度、Token 类型和速率限制几个维度：
| 维度 | OAuth App | GitHub App |
|---|---|---|
| 身份代表 | 用户 | 应用/安装 |
| 权限粒度 | 较粗（读/写/管理员） | 细粒度（按仓库、按资源） |
| Token 类型 | 用户 OAuth Token | User Access Token + Installation Token |
| 速率限制 | 5000/h | 安装级 5000/h + 扩展 |
| Webhook | 需手动配置 | 安装即自动注册 |
| 适用场景 | 单一用户代理操作 | 多仓库自动化 |
一句话总结：OAuth App 适合”替某个用户办事”，GitHub App 适合”替应用在多个仓库里自动化作业”。翻译工具属于后者，所以选 GitHub App 是顺理成章的。
速率限制这一行值得单独拎出来说。GitHub 对 OAuth App 的 5000 次/小时是按用户计，应用一多就互相挤占；GitHub App 的安装级配额在默认基础上还能申请扩展，给企业用户留了明确余量。批量翻译一次任务就要消耗几十上百次请求，这个区别对任务吞吐影响很直接。
二、为什么不能只用 OAuth App
OAuth App 用”用户身份”访问仓库，第一版我就被这套机制卡了很久。它会带来三类问题，都直接影响翻译任务的稳定性：
- 权限继承用户：如果用户失去仓库访问权，OAuth 凭据也立即失效，翻译任务中断；
- 速率限制共享：用户的所有 OAuth 应用共享 5000/h 限额；
- 无法代表应用：组织希望用”机器人”身份翻译，但 OAuth App 仍表现为操作者本人。
这三条我实际踩中过两条。团队成员被移出组织，他的翻译任务立刻 403 失败；另一个项目把 GitHub API 配额打满，我这边也跟着限流，两个应用互相抢额度。这类问题不是改配置能解决的，是授权模型本身决定的。
三、GitHub App 的关键优势
换成 GitHub App 之后，前面三类问题都有了对应解法。核心变化是权限和凭据都从”用户”下沉到”安装”：
- 权限按安装范围授予：用户把 App 装到具体仓库，App 只能动这些仓库；
- 安装级速率限制：每个安装有独立 5000/h，可申请扩展；
- 短生命周期 Token：Installation Token 默认 1 小时，泄露风险小；
- Webhook 自动注册：App 装载后无需再单独配置；
- 标识清晰：所有 commit、PR、Issue 评论都会带
app-login[bot]，审计可追溯。
最有用的是 Installation Token 的生成方式。它不落地长期凭据，服务端用 App 私钥先生成 JWT，再用 JWT 换取 1 小时有效的 Installation Token：
import { sign } from "jsonwebtoken";
import { createAppAuth } from "@octokit/auth-app";
// 用 App 私钥签发 JWT，有效期 10 分钟
const jwt = sign(
{
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 600,
iss: APP_ID,
},
PRIVATE_KEY,
{ algorithm: "RS256" }
);
// 用 JWT 换取针对具体 installationId 的 Installation Token
const auth = createAppAuth({ appId: APP_ID, privateKey: PRIVATE_KEY });
const installationAuth = await auth({ type: "installation", installationId });这套流程跑通后，仓库里不会出现任何一个长期有效的 token，私钥只存在服务端环境变量里。token 泄露也只需要等它自动过期，不需要紧急撤销。
四、本项目使用 GitHub App 的关键场景
选型不是拿来主义，得落到具体场景里才有意义。这个工具里 GitHub App 承担了四个关键职责：
- 翻译完成后写回 PR：用 Installation Token 提交分支和 PR，commit 显示为机器人；
- Webhook 触发自动翻译：仓库 push 后 App 自动接收事件；
- 仓库授权：用户安装 App 后，前端列出可访问的仓库，用户勾选即可；
- API 配额管理：每个安装独立计数，便于按企业维度限流。
第四点最省心。企业用户常常几十个仓库一起翻译，如果按 OAuth 的共享额度，几个仓库就撑爆了。安装级计数让每个企业独立跑，互不干扰，也不用我去申请提高限额。
另外有个细节：翻译任务写回 PR 时，commit 署名默认是 bot。刚开始用户不习惯，觉得机器提交不像人工审核；后来发现审计恰恰需要这个区分，谁开的 PR、谁改的代码一查便知，反而成了团队协作里的一层保障。
五、OAuth App 在本项目中的位置
OAuth App 没有完全消失。NextAuth.js v5 用 GitHub OAuth 走”用户登录”流程：用户点登录，拿到 User Access Token，用于读取用户基本信息、邮箱、安装列表。但这只用来登录，不直接读仓库内容。
这是我最满意的一次分工。用户身份和应用权限各归各管：OAuth 回答”你是谁”，GitHub App 回答”系统能碰哪些仓库”。两者都依赖同一套 GitHub 账号体系，但职责完全不重叠。
六、迁移到 GitHub App 的代价
选 GitHub App 不是零成本。迁移过程要处理四件事，每一项都有对应的坑：
| 成本 | 说明 |
|---|---|
| 注册流程 | 需在 GitHub 开发者设置注册新 App，填写回调与权限 |
| 私钥管理 | 需要保存私钥到服务端环境变量或密钥管理服务 |
| 安装引导 | 用户首次需要跳转到 GitHub 完成安装 |
| Webhook 安全 | 需要校验 webhook secret |
相对收益，这些代价是值得的。注册和安装都是一次性工作，私钥用环境变量或密钥管理服务托管后基本无感；webhook secret 校验是个容易漏的点，我加上之后才发现自己之前是裸接请求，好在生产环境还没出过事。
七、给同类项目的建议
如果你也在做类似”读仓库、调外部服务、写回”的工具，按下面的标准选基本不会错：
- 用户数据来自 GitHub、读写仓库频繁：选 GitHub App；
- 只需要用户身份做一次性操作：选 OAuth App；
- 同时需要：GitHub App 做核心集成 + OAuth 做登录。
另外补一句我自己的教训：不要在立项初期就固定选型，先把”权限边界、速率限制、审计追溯”三个问题想清楚，再看该选谁。我就是先跑了 OAuth 路线，发现瓶颈后才迁移的，虽然不算白费，但时间成本确实花在了本可以避免的地方。
常见问题（FAQ）
Q1：可以只用 OAuth App 完成翻译工具吗？
可以，但权限和速率会成为瓶颈。
Q2：GitHub App 需要服务器吗？
需要，因为 Installation Token 需用私钥在服务端生成。
Q3：GitHub App 的私钥要保存多久？
永久保存，私钥换发需要重新注册 App。
