# API密钥和开发者访问

Source: https://support.kapsulehost.com/zh-cn/developer-api-access

KapsuleHost 为您提供两个开发者界面：限定范围的 API 密钥用于以编程方式读取您的账户，以及远程构建缓存用于加速您自己的机器和 CI 运行器上的 Turborepo 和 Nx 构建。

默认情况下，两者都未启用。两者都从**设置**创建，两者都会向您交付一个密钥，且仅交付一次。

## 创建 API 密钥

API 密钥位于**设置**下，然后是**安全**，在 **API 密钥**卡中。

![KPanel 安全设置中的 API 密钥卡，显示范围芯片](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. 转到**设置**，然后**安全**。
2. 滚动到 **API 密钥**并点击**新密钥**。
3. 为密钥指定一个名称。该字段建议"密钥名称（例如 My automation script）"。该名称仅供您使用，因此请让它说明密钥将在何处使用。
4. 点击范围芯片以选择密钥可以执行的操作。三个读取范围已预先选定：`read:sites`、`read:email` 和 `read:domains`。点击芯片以添加或删除它。
5. 点击**创建**。

完整密钥出现一次，在一个绿色面板中，标题为"立即复制"。将其直接复制到您的密钥存储中。当您关闭该面板时，密钥消失：仅保留一个短前缀，这是列表以后能显示的全部。

> **Warning:** 密钥永远不会显示第二次，并且无法恢复。如果您丢失了它，撤销该密钥并创建一个新的。不要将其粘贴到共享文档、工单、提交或聊天消息中。

只有**所有者**和**管理员**角色可以创建密钥。任何其他角色都会收到权限错误。创建密钥时，安全警报电子邮件会发送到创建该密钥的人的地址，因此意外收到其中之一是值得立即调查的。

## 范围

提供七个范围：

| 范围 | 授予 |
|---|---|
| `read:sites` | 读取您的网站 |
| `write:sites` | 保留用于网站上的写入操作 |
| `read:email` | 读取您的邮箱 |
| `write:email` | 保留用于邮箱上的写入操作 |
| `read:domains` | 读取您的域 |
| `write:domains` | 保留用于域上的写入操作 |
| `read:billing` | 保留用于读取计费数据 |

> **Note:** 客户 API 目前是只读的。`write:` 范围和 `read:billing` 可以在密钥上选择，但目前没有客户端点使用它们，因此授予它们不会改变任何内容。仅授予您实际需要的读取范围，并在写入端点发货时重新访问密钥。

## 使用密钥

在 `Authorization` 标头上将密钥作为承载者令牌发送。

```sh
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`，并带有一条消息，命名所需的范围。每次成功调用都会更新密钥的上次使用时间戳。

> **Tip:** 轻轻轮询。这些端点读取实时账户数据，针对它们的紧密循环与滥用无法区分。对于仪表板需要的任何内容，每分钟一次都很充分；每小时一次通常足够了。

## 审查和撤销密钥

API 密钥表按**名称**、**前缀**（密钥的可见开头）和**范围**列出每个活跃密钥。点击行末尾的**撤销**以将其禁用。

> **Important:** 撤销立即生效，没有确认对话框。使用该密钥的下一个请求失败，返回 `401`。已撤销的密钥无法恢复，因此在点击之前请确保您知道什么在使用它。

密钥属于**账户**，而不是创建它们的人。从[团队页面](https://support.kapsulehost.com/zh-cn/account-team-members)移除团队成员不会撤销他们创建的密钥。将密钥审查纳入您的员工离职流程：移除该人，然后来这里撤销他们创建的任何东西。

密钥创建和撤销都记录在[审计日志](https://support.kapsulehost.com/zh-cn/account-audit-log)中，在 `api_key.*` 操作下，包含执行者和来源 IP 地址。

## 远程构建缓存

设置边栏的高级组中的**开发者**页面提供**远程构建缓存**。该面板将其描述为"通过在机器和 CI 管道之间共享分布式缓存来加速 Turborepo 和 Nx 构建"的方式。

1. 转到**设置**，然后**开发者**。
2. 点击**启用远程缓存**。
3. 从标题为"已生成新令牌。立即复制它，它不会再次显示"的面板中复制令牌。

然后在您的 CI 配置或本地 `.env.local` 中设置两个环境变量：

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

团队 ID 是您的 KapsuleHost 账户 ID，显示在同一页面上的设置说明中。

该页面说明了其自身的兼容性：Turborepo 1.x 及更高版本、Nx 16 及更高版本，以及任何实现相同远程缓存协议的工具。工件按账户存储，永远不会跨账户共享。

卡上还有两个进一步的控件：

- **轮换令牌**发出新令牌并使旧令牌失效。任何仍保留旧令牌的 CI 作业都会停止使用缓存，因此请一起轮换和更新您的密钥。
- **禁用**完全关闭缓存。

## 在两者之间选择

它们解决的是无关问题，不可互换。

当 KapsuleHost 外部的某些东西需要了解您账户的状态时，使用 **API 密钥**：列出您网站的状态板、警告您有关域名即将过期的脚本、库存导出。

当您的构建速度缓慢因为每台机器和每次 CI 运行都重新构建相同的未更改包时，使用**远程构建缓存**。它与您托管的网站无关，不读取您的账户数据。

## 故障排除

**每个请求都返回 401。**确认您在 `Authorization: Bearer <key>` 上以单个空格发送了标头，密钥在复制时未被截断，并且未被撤销。将密钥的开头与**前缀**列进行比较，以确保您使用的是您认为的密钥。

**请求返回 403 并命名范围。**密钥不包含该范围。范围在创建密钥时是固定的，因此创建一个具有正确范围的替代品并撤销旧的。

**我看不到 API 密钥卡。**它在安全页面上，不在开发者页面上。开发者页面仅保存构建缓存。

**新密钥按钮没有反应。**您的角色低于管理员。请联系所有者或管理员。

**构建未命中缓存。**检查 `TURBO_TOKEN` 和 `TURBO_TEAM` 是否都存在于构建环境中，令牌自设置以来是否未被轮换，以及页面是否仍显示**活跃**徽章。

**出现了一个我未创建的密钥。**将其视为泄露。撤销它，然后通过[账户安全](https://support.kapsulehost.com/zh-cn/account-security)进行操作，并检查[审计日志](https://support.kapsulehost.com/zh-cn/account-audit-log)了解还有什么更改。