---
title: API密钥与作用域
description: 客户如何创建API密钥（vk_前缀）、选择作用域、按IP和过期时间进行限制，以及管理员如何审查和吊销这些密钥。
url: https://nexcmp.com/zh-cn/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# API密钥与作用域 {#api-keys-and-scopes}

> **门户位置：** API keys (`/api-keys`)。**管理后台位置：** Customers › Customers › API keys (`/customers/apikeys`)。

## 功能说明 {#what-it-does}

通过 **API key**，脚本、CI作业、[`cmp` CLI](https://nexcmp.com/zh-cn/docs/developers/cmp-cli/) 或AI助手（[MCP](https://nexcmp.com/zh-cn/docs/developers/mcp/)）可以代表单个客户调用 [REST API](https://nexcmp.com/zh-cn/docs/developers/api/)，且仅拥有被授予的权限（**scopes**）。客户密钥以 `vk_` 开头。它们可以读取和管理服务，但**绝不能**触及资金或账户本身。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| 客户 | 已登录的门户会话（密钥无法创建或编辑其他密钥，模拟客户的管理员也无法这样做）。 |
| 开关 | API密钥默认处于开启状态。如果将其关闭，调用将返回401 `api_keys_disabled`。 |
| 依赖项 | 产品的作用域仅在该产品于站点上启用时才会显示。 |

## 创建密钥（客户） {#create-a-key-customer}

1. 登录门户并打开 **API keys**。
2. 点击 **Create key**。
3. 填写表单：

   | 字段 | 规则 |
   |---|---|
   | **Key name** | 必填，最多60个字符（例如“deploy server”、“backup script”）。 |
   | **此密钥可执行的操作** | 勾选所需的作用域——至少选择一个。只读密钥不应获得任何写权限。涉及扣费或删除数据的作用域请谨慎勾选。 |
   | **Expiry** | 永不过期、30天、90天或1年（API接受1到3650天）。 |
   | **仅允许来自这些 IP 的调用** | 每行一个IP或CIDR范围，最多20个（IPv4或IPv6）。留空表示允许任何IP。请尽可能固定您服务器的IP。 |

4. 确认表单。密钥将在“Key created — shown ONCE”窗口中**仅显示一次**。请复制它并点击 **I saved the key**。系统仅存储SHA-256哈希值，因此连管理员也无法再次查看；如果您丢失了密钥，请将其吊销并创建一个新的。
5. 门户还会显示一个用于测试密钥的现成`curl`命令。


密钥格式为 `vk_` 后跟一长串随机字符串。列表中仅显示前几个字符（例如 `vk_a1b2c3d4`）、作用域、到期时间、最后使用时间、请求次数和状态（*Active*、*Expired*、*Revoked*）。

### 编辑、吊销、审计 {#edit-revoke-audit}

- **Edit** 可用于更改名称、权限范围、允许的 IP 和过期时间。在模拟会话期间不允许此操作。
- **Revoke** 会立即停用密钥且无法撤销。系统会保留该行记录，以便继续查阅使用日志。
- **Key usage log** 展示最近 60 天内的写操作及所有错误：时间、请求、密钥、结果与源 IP。
- 默认情况下，一个账户最多可拥有 **10 个活动密钥**。
- 通过 CLI 或 MCP 登录创建的密钥会显示在 **Connected apps & devices** 下，并可在该处进行撤销。

## 权限范围 {#scopes}

权限范围名称的格式为 `area:action`。具体提供哪些范围取决于您已启用的产品。

| 权限范围 | 允许操作 |
|---|---|
| `catalog:read` | 读取套餐和目录。 |
| `vm:read` | 读取虚拟机、指标与虚拟机账单。 |
| `vm:write` | 电源操作、轻微更改、防火墙、快速快照。 |
| `vm:create` | **创建虚拟机（产生费用）。** |
| `vm:plan` | **更改套餐或调整大小（产生费用）。** |
| `vm:destroy` | **删除虚拟机。** |
| `vm:restore` | **从快照恢复虚拟机（会覆盖磁盘）。** |
| `vm:console` | 开启 VNC 控制台工单。 |
| `sshkey:read`, `sshkey:write` | 读取、添加和移除 SSH Keys。 |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | 数据卷（创建和扩容会产生费用；销毁会导致数据丢失）。 |
| `backup:read`, `backup:write`, `backup:restore` | Backups（恢复会覆盖磁盘）。 |
| `billing:read` | 钱包、账单、支付历史 — **仅限读取**。 |
| `bandwidth:buy` | **购买带宽附加包（产生费用）。** |
| `account:read`, `account:write` | 个人资料、概览、活动、通知；`account:write` 仅用于将通知标记为已读。 |
| `apikey:read` | 列出账户的密钥和使用日志（无法创建、编辑或撤销）。 |
| `apikey:self` | 每个密钥默认包含：检查调用密钥（`GET /v1/apikeys/self`）。 |
| `ticket:read`, `ticket:write` | 支持工单。 |
| `aff:read`, `transfer:read` | 分销联盟计划和服务转移 — 仅限读取。 |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes（创建和扩容会产生费用；kubeconfig 具有 cluster-admin 权限）。 |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | 私有云。 |
| `image:read`, `image:write` | 操作系统与 ISO 镜像（存储按小时计费）。 |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage（S3密钥仅显示一次）。 |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN 与 IPv6 代理（连接详情包含代理密码）。 |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | 独立服务器（通过钱包创建订单；销毁会重新安装操作系统）。 |
| `shield:read`, `shield:write`, `shield:agent` | DDoS 防护盾（仅在该模块启用时可用）。 |

对超出密钥权限范围的调用会返回 **403 `scope_required`**；对任何密钥均无权调用的路径会返回 **403 `endpoint_not_public`**。

### 密钥绝无权限执行的操作 {#what-a-key-can-never-do}

任何权限范围都无法进行以下操作：充值或提现、更改银行卡或自动充值、更改密码、电子邮箱或 2FA、删除账户、创建、编辑或撤销其他密钥。这些操作始终需要通过登录浏览器的会话来完成。即使密钥泄露，也无法触及客户的资金或账户。

## 可信赖的规则 {#rules-you-can-rely-on}

| 规则 | 详情 |
|---|---|
| 绑定站点 | 密钥仅在其创建所在的站点（域）上有效。 |
| 速率限制 | 按密钥和按账户：默认分别为每分钟 120 次和 300 次请求。 |
| 幂等性 | 会产生费用或无法重复执行的操作需要携带 `Idempotency-Key` 请求头。 |
| 配额 | 密钥受到与客户相同的 [quotas](https://nexcmp.com/zh-cn/docs/billing/quotas/) 限制。 |
| 锁定账户 | 已被锁定客户的密钥会失效（403 `account_blocked`）。 |
| 审计 | 管理员执行的吊销操作会被记录到管理员审计日志中。 |

## 管理员视图 {#administrator-view}

1. 打开 **Customers › API keys**（`/customers/apikeys`）。表格会显示密钥名称及前几位字符、所有者、权限范围、状态、最后使用情况（时间、请求次数、IP）以及过期时间。
2. 若设有分销商，可按站点筛选。支持按名称、ID或密钥开头搜索。
3. 点击 **Revoke** 停用活跃密钥，或点击 **Log** 查看其使用日志。
4. 管理员可以**查看并吊销**密钥，但无法为客户读取或创建密钥。

![管理员查看的客户API密钥列表，包含权限范围、状态、最后使用情况和吊销按钮](https://nexcmp.com/zh-cn/docs/images/developers/api-keys-02-admin.webp)

## 验证 {#verify}

1. 仅创建带有 `vm:read` 权限范围的密钥。
2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` 返回虚拟机列表。
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` 返回 403 `scope_required`。
4. 吊销该密钥后，再次调用将返回 401 `key_revoked`。

## 限制与注意事项 {#limits-notes}

- 密钥仅显示这一次。请将其视为密码，保存在密钥管理器或CI密钥中。
- 建议每个脚本使用一个密钥、采用最小权限范围、设置较短的过期时间并配置IP白名单；通过创建新密钥并吊销旧密钥来进行轮换。
- 来自设备登录（CLI、MCP）的密钥默认有效期为90 days。
- 吊销密钥不会影响已删除或已转移的资源。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| Error `too_many_keys` (422) | 已达到活跃密钥上限（默认10个） | 吊销一个旧密钥。 |
| 错误 `invalid_argument`：未选择权限范围 | 未勾选任何权限范围 | 请至少勾选一个权限范围。 |
| 允许的IP出现错误 `invalid_argument` | 条目不是IP或网段、前缀长度错误或条目超过20个 | 每行一个IP或CIDR，例如 `203.0.113.0/24`。 |
| 模拟登录期间拒绝创建 | `impersonate_forbidden` | 请让客户自行创建密钥。 |
| 401 `key_expired` | 已过期的日期 | 创建一个新密钥。 |
| 401 `key_ip_denied` | 调用方IP不在白名单中 | 添加该IP或清空白名单。 |
| 401 `api_keys_disabled` | 功能已关闭 | 请联系您的管理员（`api_keys_enabled` 设置）。 |