API密钥与作用域

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

功能说明

通过 API key，脚本、CI作业、cmp CLI 或AI助手（MCP）可以代表单个客户调用 REST API，且仅拥有被授予的权限（scopes）。客户密钥以 vk_ 开头。它们可以读取和管理服务，但绝不能触及资金或账户本身。

前提条件

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

创建密钥（客户）

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

权限范围

权限范围名称的格式为 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。

密钥绝无权限执行的操作

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

可信赖的规则

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

管理员视图

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

验证

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。

限制与注意事项

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

故障排查

症状	原因	解决办法
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 设置）。