症状：你只想自动上传指定 App，却在团队密钥和个人密钥之间反复试错。 最快解法：低频自动化优先选择受限用户对应的个人 API Key；只有需要 Provisioning 端点或个人密钥不支持的能力时，才改用最小角色的独立团队 API Key。
这条判断适用于构建上传、TestFlight 分发、元数据自动化和常驻发布脚本，但前提是你先核对实际 API 调用、App 访问范围和签名材料需求。App Store Connect API Key 解决的是 App Store Connect API 身份验证，不会自动替代证书、描述文件或代码签名私钥。
如果你准备把发布流程放到远程 Mac 上，建议先确认主机登录权限、凭据注入方式和环境恢复方案，再决定密钥类型。需要长期运行 Xcode、fastlane 或 Transporter 时，也可以先从 MACGPU 的远程 Mac 使用入口 了解主机访问方式，但不要把远程主机权限与 App Store Connect 权限混为一谈。
先按任务能力划分密钥边界
你可以把发布链拆成 4 个互不等价的部分：
- App Store Connect 权限：上传构建、管理版本信息、处理 TestFlight。
- Certificates、Identifiers & Profiles 权限：创建或下载证书、描述文件，以及配置部分签名资源。
- 远程 Mac 登录权限：VNC、SSH、网页控制台或主机管理员账户。
- 代码签名材料：证书私钥、Provisioning Profile、钥匙串和构建环境中的签名配置。
Apple 将 API Key 分为 Team 和 Individual 两类。团队密钥由 Account Holder 或 Admin 管理，并按照创建时选择的角色授权；个人密钥则继承关联用户自身的角色和 App 访问范围。团队密钥不能限制到单个 App，而个人密钥的访问范围会跟随对应用户权限。 Apple：创建 App Store Connect API Key 的官方说明
先记录 4 项判断标准
在创建密钥前，写下下面 4 个答案：
- 任务所需能力：只是上传构建和管理 TestFlight，还是还要调用 Provisioning 端点？
- App 隔离范围：脚本只服务一款 App，还是会跨多个 App 发布？
- 交接方式：凭据归属于一个开发者，还是要由 CI 维护者长期接管？
- 撤销影响：撤销后会影响一条流水线，还是会同时中断多个项目？
用一张表确定 Team API Key 还是 Individual API Key
| 判断项目 | Individual API Key | Team API Key |
|---|---|---|
| 权限来源 | 继承关联用户的角色与 App 访问权限 | 创建时直接选择团队角色 |
| App 范围 | 可以跟随用户限制到指定 App | 不能限制到单个 App，默认跨团队 App 生效 |
| 创建资格 | 由符合条件的团队成员创建，具体取决于组织设置 | 通常由 Account Holder 或 Admin 创建与管理 |
| Provisioning 端点 | Apple 文档明确列为不支持 | 可根据角色和 API 能力评估 |
| 个人密钥数量 | 每名用户同时只能保留 **1 把有效个人密钥** | 团队可创建多把不同角色的团队密钥 |
| 适合场景 | 单人开发、指定 App、低频自动化、外包人员 | 跨 App CI、专用发布账户、需要个人密钥不支持的能力 |
| 主要风险 | 人员离职或个人密钥撤销会影响关联流程 | 一把密钥可能接触所有 App，误授权范围更大 |
如果你还在比较本地设备与远程主机的发布方式，建议把密钥决策和主机决策分开。比如，使用 MACGPU 的 M4 远程 Mac 方案说明 时，你仍然需要自行确认 Xcode 版本、签名材料和流水线脚本是否符合项目要求；租用远程 Mac 不会自动扩大 API Key 权限。
按使用人群落地最小权限方案
独立开发者：先用个人密钥验证主流程
如果你独立维护一款或少数几款 App，主要任务是以下几类：
- 从远程 Mac 或本地 Mac 上传 Archive；
- 将构建分发到 TestFlight；
- 更新版本元数据或查看构建状态；
- 使用 fastlane、Transporter 或自建脚本完成重复操作。
但有一个容易忽略的限制：每名用户只能保留 1 把有效个人 API Key。如果你重新生成个人密钥，原有工具切换、旧流水线引用和备份记录都要同步检查，不能把它当成可以长期并存的多环境密钥池。
个人密钥的创建、下载与撤销规则，应以 Apple 的 API Key 文档 为准。不要把第三方脚本参数中的 key_id、issuer_id 或私钥文件名，误认为是 Apple 额外授予的权限。
小团队：把发布负责人和自动化任务分开
小团队最常见的错误，是让发布负责人直接生成一把 Admin 团队密钥，再把它放进所有项目的 CI。这样做的问题至少有 3 个：
- App 无法单独隔离：即使创建多把团队密钥，也不能把某把限制到某一个 App。
- 角色过宽：Admin 不只是上传构建，还可能拥有用户管理等高风险能力。
- 撤销影响集中：密钥泄露后，撤销动作可能同时打断多款 App 的发布流程。
- 发布负责人：保留人工审核、版本提交和敏感设置权限。
- 日常开发者：使用受限用户权限访问自己负责的 App。
- 自动化任务：使用独立的团队 API Key，角色从 Developer 或 App Manager 等最低必要级别开始。
- 多项目团队：按发布职责拆分密钥，而不是误以为“多建几把团队密钥”就能实现 App 级隔离。
外部协作者：身份、主机和签名材料分开交接
外包开发者只需要上传某一款 App 到 TestFlight 时，不要把团队 API Key、远程 Mac 管理员账户和签名私钥打包交付。正确的拆分方式是：
- 为协作者创建独立的 App Store Connect 用户。
- 选择能够完成上传和测试分发的最低角色。
- 将用户访问范围限制在目标 App。
- 单独配置远程 Mac 登录权限，避免把主机管理员权限等同于 App Store Connect 权限。
- 项目结束时同时清理用户、API Key、SSH 或 VNC 账户、钥匙串和脚本中的凭据引用。
⚠️ 注意：App Store Connect API Key 被撤销后不能恢复。若你只撤销了 API Key，却保留了远程 Mac 登录账户、签名私钥或仓库部署密钥，协作者仍可能从其他入口访问发布环境。
持续集成维护者：不要因为无人值守就选择最高角色
在常驻远程 Mac 上运行 fastlane、Transporter 或自建脚本时，先列出脚本实际动作，再决定密钥类型：
- 只上传构建：确认上传角色和 App 访问范围即可。
- 管理 TestFlight：确认构建处理完成后，脚本是否还要创建测试组、分配构建或管理测试信息。
- 更新元数据：确认脚本是否同时修改版本描述、价格、内购或审核资料。
- 调用 Provisioning 相关端点：如果个人 API Key 不支持该能力，再考虑专用团队 API Key。
- 跨多个 App 发布：团队密钥更方便，但必须接受它无法按单个 App 隔离的事实。
用条件分支做最终选择
按下面的顺序执行，不要先看团队规模再反推密钥：
- 若只访问指定 App，且任务是构建上传、TestFlight 或元数据自动化，选择受限用户对应的 Individual API Key。
- 若个人密钥不支持脚本所需的 Provisioning 端点，回退到独立的 Team API Key，并选择完成任务所需的最低角色。
- 若脚本跨多个 App 运行，可以选择团队密钥，但必须把它视为全团队范围凭据，不能宣称实现了 App 级隔离。
- 若协作者只负责某一款 App，先创建受限用户和个人密钥，不要交付共用团队密钥。
- 若任务包含证书、描述文件或代码签名，单独配置签名材料，不能把 API Key 当作完整签名方案。
- 若只是临时测试，优先使用独立、可撤销的凭据；测试结束后确认脚本、环境变量和远程 Mac 上没有残留引用。
aud 和过期时间；过期时间超过 **20 分钟** 的令牌通常无效，除非属于 Apple 列出的特定资源。字段格式和有效期限制应以 [Apple 的 JWT 生成文档](https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests) 为准。
示例配置只能使用明显占位符，不能把真实密钥写入脚本：
ISSUER_ID=YOUR_ISSUER_ID
KEY_ID=YOUR_KEY_ID
PRIVATE_KEY_PATH=/secure/path/AuthKey_YOUR_KEY_ID.p8
BUNDLE_ID=com.example.placeholder私钥正文、完整 JWT、真实 Team ID 和真实 Bundle ID 不应出现在公开仓库、构建产物或普通日志中。日志中可以保留脱敏后的 Key ID 末尾字符、任务编号和失败阶段，但不要输出完整认证头。
把 FAQ 放进发布前的核对流程
个人密钥能不能管理证书和 Provisioning Profile？
不能直接这样理解。个人 API Key 不能使用 Provisioning 端点；证书私钥、描述文件、钥匙串和 API Key 需要分别管理。你可以使用 API Key 认证 App Store Connect API，但仍要为 Xcode Archive 准备可用的签名环境。
fastlane 自动上传选哪种密钥？
如果 fastlane 只上传构建、管理 TestFlight 或更新元数据，先用受限用户的个人密钥。若脚本调用个人密钥不支持的 API，或者必须跨多个 App 运行，再使用专用团队密钥；不要仅因脚本运行在 CI 就直接授予 Admin。
远程 Mac 上私钥应该放在哪里？
放在不进入仓库和构建产物的受控凭据目录中，由环境变量或安全注入机制提供路径。Key ID、Issuer ID 和私钥文件分开保存，日志中只保留脱敏后的标识；示例路径、Bundle ID 和 JWT 内容都应使用占位符。
外包人员上传 TestFlight 需要什么权限？
外包人员应使用独立用户身份，并限制到目标 App。根据实际动作选择 Developer、App Manager 或其他最低必要角色；如果还需要签名资源，就单独授权和交付签名材料，不要把团队 API Key 和主机管理员权限一起给出去。
撤销旧密钥后为什么流水线仍可能有风险？
撤销 API Key 只会阻止它继续认证 App Store Connect API，不会自动删除远程 Mac 登录账户、代码仓库部署密钥、钥匙串证书或脚本中的其他凭据。项目交接必须执行多入口清理，并在撤销后重新跑一次失败验证。
用发布前验收卡验证整条链
新密钥上线前，建议在受控测试 App 上完成以下检查：
- ✅ 身份验证：使用占位符替换后的真实配置生成 JWT，确认 Key ID、Issuer ID 和私钥匹配。
- ✅ Archive：在本地或远程 Mac 上完成 Archive，检查 Bundle ID、版本号和签名状态。
- ✅ 上传：使用 Transporter、fastlane 或脚本上传构建，不把完整 JWT 或私钥打印到日志。
- ✅ TestFlight：确认构建经过处理后可见，并验证目标用户能否访问相应测试分组。
- ✅ 权限边界：尝试访问不应开放的 App 或接口，确认失败结果符合预期。
- ✅ 撤销验证：撤销旧密钥后重新执行一次任务，确认流水线不再引用旧凭据。
- ✅ 恢复记录：记录新密钥负责人、注入位置、撤销条件和恢复步骤，但不要在文档中复制私钥正文。
TestFlight 的验收也不能只看上传命令返回成功。你还需要确认构建已经完成后台处理、能够在目标 App 下显示，并且测试分发权限与用户范围符合预期；完整流程可以参考 Apple 的 TestFlight 官方说明。
从评分角度看，个人密钥在“指定 App 隔离”和“外包交接”上更容易拿到高分；团队密钥在“跨 App 自动化”和“无人值守调用特殊接口”上更有优势，但它的 App 范围更宽，撤销影响也更集中。你的选择应以任务能力和隔离边界为准，而不是以“CI 就必须用团队密钥”这种经验判断。
如果你目前用个人电脑承担发布，常见缺点是设备不一定持续在线、磁盘和 Xcode 环境容易被日常开发占用，而且外包协作者接入时很难做到主机权限与发布凭据完全分离。若你判断结果是使用团队 API Key 承担长期无人值守发布，可进一步核对远程 Mac 是否支持独立管理员权限、安全注入凭据、持续在线和环境恢复；确认这些条件后，再按实际发版周期选择 MACGPU 的临时或常驻租赁方案，而不是把长期重负载或必须依赖本地物理接口的工作强行迁移到远程环境。