账户
API 密钥和开发者访问
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
Kapsule 为您提供两个开发者接口：用于以编程方式读取您账户的作用域 API 密钥，以及可以加速您自己的机器和 CI 运行器上的 Turborepo 和 Nx 构建的远程构建缓存。
两者默认都不启用。两者都在设置中创建，并且两者都会向您显示一次密钥。
创建 API 密钥
API 密钥位于设置下的安全中的 API Keys 卡片。
- 进入设置，然后安全。
- 滚动到 API Keys 并点击新建密钥。
- 为密钥命名。该字段建议"密钥名称(例如 My automation script)"。该名称仅供您使用，因此请清楚地说明密钥的使用位置。
- 点击作用域芯片以选择密钥可执行的操作。三个读取作用域被预先选中：
read:sites、read:email和read:domains。点击芯片来添加或移除它。 - 点击创建。
完整的密钥仅显示一次，在标题为"立即复制"的绿色面板中。立即将其复制到您的密钥存储中。当您关闭该面板后，密钥将消失：只保留一个短前缀，这是列表以后唯一能显示给您的内容。
密钥不会第二次显示，无法恢复。如果您丢失了它，请撤销该密钥并创建一个新密钥。不要将其粘贴到共享文档、工单、提交或聊天消息中。
只有所有者和管理员角色可以创建密钥。任何其他角色都会收到权限错误。创建密钥时，创建者的邮箱地址会收到安全警报邮件，所以收到意外的邮件值得立即调查。
作用域
提供七个作用域：
| 作用域 | 授予 |
|---|---|
read:sites | 读取您的网站 |
write:sites | 为网站写入操作预留 |
read:email | 读取您的邮箱 |
write:email | 为邮箱写入操作预留 |
read:domains | 读取您的域名 |
write:domains | 为域名写入操作预留 |
read:billing | 为读取计费数据预留 |
客户 API 目前仅支持读取。write: 作用域和 read:billing 可以在密钥上选择，但没有客户端点目前使用它们，因此授予它们不会改变任何内容。仅授予您实际需要的读取作用域，并在写入端点发布时重新访问密钥。
使用密钥
在 Authorization 标头上发送密钥作为 Bearer 令牌。
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
三个端点接受客户 API 密钥：
| 端点 | 所需作用域 | 返回 |
|---|---|---|
GET /api/v1/sites | read:sites | 您的网站，包括域名、应用类型和状态 |
GET /api/v1/domains | read:domains | 您的域名，包括状态和过期时间 |
GET /api/v1/mailboxes | read:email | 您的邮箱 |
没有密钥、密钥未知或密钥已撤销的请求返回 401。有效但没有正确作用域的密钥返回 403 并显示所需作用域的消息。每次成功调用都会更新密钥的最后使用时间戳。
轻轻地轮询。这些端点读取实时账户数据，对其进行紧密循环与滥用无异。对于仪表板需要的任何内容，每分钟一次是宽松的；每小时一次通常足够。
审查和撤销密钥
API Keys 表按名称、前缀(密钥的可见开头)和作用域列出每个活动密钥。点击行尾的撤销来删除它。
撤销立即生效，没有确认对话框。使用该密钥的下一个请求失败，返回 401。已撤销的密钥无法恢复，因此在点击之前请确保您知道什么在使用它。
密钥属于账户，而不是创建它的人。从团队页面移除队友不会撤销他们创建的密钥。在离职流程中构建密钥审查：移除该人，然后来这里撤销他们创建的任何密钥。
密钥创建和撤销都记录在审计日志中的 api_key.* 操作下，包括操作者和来源 IP 地址。
远程构建缓存
开发者页面位于设置栏的高级组中，提供远程构建缓存。该面板将其描述为"通过在机器和 CI 管道之间共享分布式缓存来加速 Turborepo 和 Nx 构建"的方式。
- 进入设置，然后开发者。
- 点击启用远程缓存。
- 从标题为"已生成新令牌。立即复制，它不会再被显示"的面板中复制令牌。
然后在您的 CI 配置或本地 .env.local 中设置两个环境变量：
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
团队 ID 是您的 Kapsule 账户 ID，显示在同一页面的设置说明中。
该页面陈述了其自身的兼容性：Turborepo 1.x 及更高版本、Nx 16 及更高版本，以及任何实现相同远程缓存协议的工具。工件按账户存储，不会跨账户共享。
卡片上还有两个进一步的控件：
- 轮换令牌生成新令牌并使旧令牌失效。任何仍持有旧令牌的 CI 任务停止使用缓存，因此同时轮换并更新您的密钥。
- 禁用完全关闭缓存。
在两者之间选择
它们解决不相关的问题，不可互换。
在 Kapsule 外的某些东西需要了解您账户的状态时使用 API 密钥：一个列出您网站的状态板、一个警告您域名即将过期的脚本、一个库存导出。
在您的构建速度慢是因为每台机器和每次 CI 运行都重新构建相同未更改的包时使用远程构建缓存。它与您的托管网站无关，不读取您的账户数据。
如果您从 Git 部署而不是调用 API，请改用 Kapsule Orbit。它直接从您的存储库构建和发布，构建缓存为您处理。
故障排除
每个请求都返回 401。 确认您发送的标头为 Authorization: Bearer <key> 且仅用一个空格分隔，密钥在复制时没有被截断，并且没有被撤销。将密钥的开头与前缀列进行比较，确保您使用的是您认为的密钥。
请求返回 403 并命名一个作用域。 该密钥不包含该作用域。作用域在创建密钥时是固定的，因此创建一个具有正确作用域的替代密钥并撤销旧密钥。
我看不到 API Keys 卡片。 它在安全页面上，而不是开发者页面。开发者页面仅保存构建缓存。
新建密钥按钮没有反应。 您的角色低于管理员。询问所有者或管理员。
构建没有命中缓存。 检查 TURBO_TOKEN 和 TURBO_TEAM 都存在于构建环境中，令牌自设置后没有被轮换，以及该页面仍显示活动徽章。