API 密钥

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

API 密钥采用基于角色的访问控制 (RBAC)。密钥可以拥有组织级角色、应用范围绑定，或两者兼有。每个应用绑定都始终与其所属组织关联。为了遵循最小权限原则，请将密钥限制在选定的应用中，而不是分配组织级角色。

API 密钥在哪里管理？

前往 设置 > 组织 > API Keys 占 console.capgo.app/settings/organization/api-keys.

本页面分为两个部分：

RBAC 密钥 — 已分配角色的 Keys（推荐）。这些 Key 使用全新的基于角色的权限系统。
旧版密钥 — 使用旧版基于模式（mode-based）系统的 Keys (read, upload, write, all)，且未分配角色。

如何创建新的 API 密钥？

点击 ”+” RBAC 密钥表格顶部的按钮。
填写 密钥信息:
- 名称 (必填) — 密钥的描述性标签 (例如，“CI/CD Deploy” 或 “Monitoring Read-Only”)。
- 创建安全密钥 (可选) — 勾选后，密钥将在服务端进行哈希处理。明文密钥 仅显示一次 创建后即可查看，之后无法再次获取。
- 设置过期日期 (可选) — 选择一个日期，密钥在该日期后失效。某些组织会通过策略强制要求设置过期时间。

选择密钥作用域：
- 全组织访问权限 — 选择一个 组织角色 以定义整个组织的基准权限。可用角色取决于你自身的角色级别：
  - 无 — 无全组织访问权限。
  - 成员 — 对组织的基本读取权限。
  - 管理员 — 拥有该组织及其所有 App 的完整管理权限。
- 仅限 App 访问 — 启用 仅限选定的 App 使用此密钥. 每个 App 绑定仍与其所属组织关联；此模式仅省略了组织级别的 RBAC 角色。
如果该 Key 需要通过公共 API 创建组织，请启用 “允许创建组织”.

这将添加全局 org.create 权限。该 Key 还需一个组织范围的 org_admin 或 org_super_admin 绑定。在 dashboard 中，选择 管理员 创建 org_admin 绑定。当此密钥创建新组织时，Capgo 会自动将该密钥设为该新组织的 Super Admin。
要授予 App 访问权限：
- 当 仅限选定的 App 使用此密钥 已启用，请在下方选择一个组织 用于筛选应用的组织 以显示其 App。选定的 App 绑定仍与其所属组织关联；此筛选器不会授予组织级访问权限。
- 点击 ”+ 添加 App”，选择一个或多个 App，然后为每个 App 分配角色：
  - App 阅读器 — 对应用的只读权限。
  - App 上传器 — 可上传新 bundle。
  - 应用开发者 — 可上传 bundle、管理设备、触发 Native Build 并更新 channel 设置。
  - 应用管理员 — 对应用的完全访问权限。
  - 应用预览 — 预览 CI/CD 生命周期：上传 bundle 并创建 preview channel。该 channel 仅针对此 key 自动获得 channel 范围内的生命周期权限。
点击 “创建”.
如果你勾选了 创建安全密钥，弹窗将显示明文密钥。 立即复制 — 关闭弹窗后将无法再次获取。

在预览工作流中使用 App Preview 密钥

使用 应用预览 适用于会创建临时、非公开预览 channel、上传并发布 bundle，然后删除该 channel 和 bundle 的 CI。它没有对现有默认或主 channel 的生命周期访问权限。

创建 RBAC 密钥并启用 仅限选定的 App 使用此密钥.
在 用于筛选应用的组织，选择组织以显示其应用；每个选中的应用仍与其所属组织保持关联。
仅添加用于预览部署的应用。
选择 应用预览 为每个选中的应用。
创建一个安全密钥，按需设置过期时间，并存入你的 CI secret manager。

这种仅限选中应用的模式不包含组织级角色；它确实会不会移除组织关联。每个 app_preview 绑定仍限定在所选应用及该应用所属组织范围内。

授予	权限与范围
`app_preview` 针对所选应用	`app.read`, `app.read_bundles`, `app.upload_bundle`，以及 `app.create_channel`.
自动 `channel_preview` 绑定	当此密钥创建 channel 时，Capgo 会自动为该密钥授予 `channel.read`, `channel.promote_bundle`，以及 `channel.delete` 仅限该 channel 使用。

app_preview 保留 app.read，因此该密钥可以枚举所选应用中的 channel 元数据。自动子绑定是一种管理 boundary：该 key 无法对非其创建的 channel 进行生命周期变更。

Capgo 还会记录哪个 App Preview key 上传了 bundle。该 key 只能在其创建的每个 preview channel 上设置自己的 bundle，并能一并清理这对组合。它不会获得现有默认或 main channel、由其他 preview key 创建的 channel，或其他 key 的 bundle 的 channel 绑定。

对于典型的 CI 任务，请为每个 pull request 使用唯一的 channel 名称：

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

对于新 channel， bundle upload --channel 在一个流程中创建 channel、上传 bundle 并将其 promote。最后一个命令使用范围很窄的原子清理路径：仅当该 key 拥有该 preview channel 及其关联且未共享的 bundle 时才会成功。 应用预览 仍然不具备通用 bundle.delete权限，因此无法删除任意 bundle。

请参阅访问控制参考以了解完整的边界。

如何管理（编辑）API 密钥？

点击 扳手图标 点击列表中任何 RBAC 密钥旁的 (Manage)。这将打开密钥详情页，您可以：

修改密钥名称.
更新 组织角色.
启用或禁用 “允许创建组织” 当密钥具有 Admin 组织角色时。
添加、移除或更改 单个 App 的角色.

点击 保存更改 完成后。

如何重新生成 API 密钥？

要重新生成 API 密钥的 secret 值，请点击 刷新图标 （Regenerate），该图标位于列表中任意密钥旁。

将弹出确认对话框。确认后：

对于 安全（已哈希）密钥：将生成一个新的明文密钥，并在模态框中仅显示一次。请立即复制。
对于 明文密钥：密钥值将在服务端重新生成。

任何使用旧密钥值的集成都将立即失效。

如何删除 API 密钥？

点击 垃圾桶图标 点击列表中任意密钥上的 (Delete)，然后在对话框中确认删除。

密钥会立即被撤销——任何使用该密钥的请求都会失败。

旧版密钥

如果您在 旧版密钥 部分（未分配角色的密钥）看到密钥，说明它们使用的是旧版基于模式的权限系统（read, upload, write, all）。它们仍然可用，但无法获得 RBAC 细粒度权限带来的好处。

旧版密钥可以重新生成，也可以从列表中删除，但无法编辑以添加 RBAC 角色。建议尽可能创建新的 RBAC 密钥，并删除旧版密钥。

如果您需要直接管理旧版密钥，仍可访问： console.capgo.app/dashboard/apikeys。该页面已弃用，并将在后续更新中移除。

继续阅读 API 密钥

如果你正在使用 API 密钥 要规划 dashboard 和 API 操作，请将其连接到 API 概览关于 API Overview 中的实现细节，简介关于 Introduction 中的实现细节， API 密钥有关 API Keys 的实现细节，设备有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。