---
title: Admin API keys
description: 为 AI 代理和脚本创建并撤销 ak_ 管理员密钥：八个权限范围、过期时间、IP 范围、速率限制、密钥永不能执行的操作以及每个错误代码。
url: https://nexcmp.com/zh-cn/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Admin API keys {#admin-api-keys}

> **管理后台位置：** System › Settings › API & AI agents (`/agent/keys`)，标签页 **API keys**。同一页面还包含标签页 **Connect an AI**、**Connected apps** 和 **Activity**。

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

管理员 API 密钥（前缀 `ak_`）允许 AI 客户端或脚本以您精确赋予的权限管理您的面板。它适用于 `/v1/admin/` 下的管理员 API 以及管理员 MCP 端点 `/mcp/admin`。它在其他任何地方均无效。

::: info 与客户密钥不同
客户在客户门户中创建以 `vk_` 开头的密钥（[API keys and scopes](https://nexcmp.com/zh-cn/docs/developers/api-keys/)）。这些密钥只能访问客户 API 和 `/mcp`。`ak_` 密钥在客户 API 上会被拒绝，而 `vk_` 密钥在管理 API 上会被拒绝。
:::

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| 角色 | 您必须登录到管理后台。密钥无法创建其他密钥。 |
| 演示 | 在演示面板上，此页面为只读：无法创建或撤销任何密钥。 |
| 可达性 | 客户端必须能够访问您面板上的 `https://cloud.example.com/mcp/admin` 或 `/v1/admin/...`（如果您使用了 IP 限制，请检查您的防火墙）。 |

## 创建密钥 {#create-a-key}

1. 打开 **System › Settings › API & AI agents** 并停留在 **API keys** 标签页上。
2. 点击 **Create new key**。
3. 填写表单：

   | 字段 | 规则 |
   |---|---|
   | 名称 | 最多 60 个字符，例如 "Claude Code on my laptop"。 |
   | 权限范围 | 勾选至少一个。参见 [Scopes](#scopes)。最初请仅选择 `admin:read`。 |
   | 过期时间 | 1、7、30、60 或 90 天。默认 30。最大 90。无法创建没有过期时间的密钥。 |
   | IP 范围（可选） | 每行一个 IPv4 或 IPv6 地址或 CIDR，例如 `203.0.113.0/24` 或 `2001:db8::/48`。最多 32 个。留空则允许任何 IP。 |
   | 每分钟调用次数 | 1 到 6000。默认 120。 |

4. 点击 **Create key**。一个对话框会显示一次该密钥，例如 `ak_XXXX`。**请立即复制**：NexCMP 仅存储哈希值，且绝不会再次显示它。
5. 点击 **I have saved the key**。打开 **Connect an AI** 标签页即可获取现成可粘的命令，其中已经包含了您刚刚创建的密钥（仅在此页面上有效，直到您刷新页面）。

![填入了名称、权限范围复选框、过期时间跟 IP 范围的新密钥对话框](https://nexcmp.com/zh-cn/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![带有一个复制按钮和一个警告、仅显示一次新密钥的对话框](https://nexcmp.com/zh-cn/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## 权限范围 {#scopes}

API Key 仅可使用其权限范围（scopes）允许的工具和端点。写权限不包含读权限：需要读写功能的 Key 同时还需包含 `admin:read`。

| 权限范围 | 允许的操作 |
|---|---|
| `admin:read` | 读取设置、目录、客户、账单与日志。系统绝不会返回密钥（Secrets）。 |
| `catalog:write` | 套餐、操作系统模板、配额、折扣码。 |
| `infra:write` | 基础设施源（CloudStack、Proxmox）、可用区、服务器。 |
| `billing:write` | 支付网关、货币、账单、余额。资金相关操作需要确认。 |
| `customers:write` | 客户和分销商。 |
| `settings:write` | 常规设置、品牌、电子邮件、法律页面、模块、通知。 |
| `ai:write` | AI提供商与AI功能。 |
| `secrets:write` | 写入密码和API密钥。可以设置但永远无法读取。 |

::: tip 设置密钥需要两个作用域
任何携带密码、API密钥或令牌值的调用（例如SMTP密码、支付密钥、Telegram机器人令牌、AI提供商密钥、CloudStack或Proxmox凭据）都需要`secrets:write`**以及**该区域的作用域（例如用于SMTP的`settings:write`）。如果您更愿意自行手动输入密钥，请不要勾选`secrets:write`并在管理后台中输入。
:::

## 吊销密钥 {#revoke-a-key}

1. 在表格中找到该密钥（状态为**Active**、**Expired**或**Revoked**；**Last used**会显示时间和客户端）。
2. 点击**Revoke**并确认。

密钥将立即停止工作。吊销操作是永久性的；如需再次使用，请创建新密钥。

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

无论拥有何种作用域，密钥永远无法访问这些区域。这些操作需要您登录管理后台。

- 创建或修改管理员用户、2FA和登录安全性、管理员会话以及管理员API令牌。
- 创建、列出或吊销管理员密钥、OAuth连接和AI账户，或使用AI Console。
- 备份或恢复面板、更新面板或更改其许可证。
- 以客户或分销商身份登录、打开客户控制台、读取虚拟机凭据或kubeconfig、设置SSH密钥，或者发送或重置密码。
- 更改网络与路由模块（BGP、FRR、RTBH、XDP、接口、静态和策略路由、NAT）或外部代理与门户集成。这些属于只读操作。
- 更改诸如`demo_*`、`admin_*`、主机列表、通行密钥、重新认证和验证码密钥等设置。

规则未覆盖的任何内容默认禁止写入，且读取时需要`admin:read`。

### 需要您确认的操作 {#actions-that-need-your-confirmation}

这些操作仅在您批准预览后才能成功执行（参见[Two-step confirmation](#two-step-confirmation)）：

- 更改客户余额或分销商钱包、打款、账单记录、汇率。
- 更改价格（套餐价格、批量创建套餐、镜像和存储定价）以及创建折扣码或代金券。
- 保存支付网关凭据或CloudStack连接。
- 删除任何内容、封禁或删除客户、更改客户限制、暂停或关闭分销商。
- 对客户服务器进行操作，或为客户创建付费服务器。
- 通过常规设置更改全站开关、登录安全设置或支付设置。

## 两步确认 {#two-step-confirmation}

当调用需要确认时，此时不会产生任何更改。响应为HTTP **428**，其中包含`confirm_required`、`confirm_token`、`preview`（方法、路径、原因、新值以及可用时的当前值）以及`expires_in: 300`。

1. 客户端会向您展示预览。
2. 在您批准后，客户端会使用带有`X-Confirm-Token: <confirm_token>`标头的**相同**请求（相同的方法、路径和正文）重新发送。MCP工具则改用参数`confirm_token`。
3. 该令牌仅可使用一次，并在5分钟后过期。

在管理后台为AI Chat创建的密钥只能在屏幕上确认：响应会显示`confirm_in: "ui"`，并且管理后台中会出现一个确认卡片。AI无法对其进行批准。

## 速率限制与IP规则 {#rate-limit-and-ip-rules}

- 超过每分钟限制时，调用将返回`rate_limited`（HTTP 429）以及`Retry-After: 60`。
- 如果设置了IP范围，来自任何其他地址的调用将返回`ip_not_allowed`（HTTP 403）。

## 活动日志 {#activity-log}

**Activity** 标签页按时间顺序列出使用密钥进行的所有调用，最新的排在最前面：时间、密钥、客户端、来源（`http`、`mcp`、`chat`、`cli`、`confirm`、`preview`）、方法和路径、工具、HTTP 状态、IP 以及（已掩码的）详细信息。你可以按路径、工具或密钥名称搜索，仅显示错误（HTTP 400 及以上）或仅显示等待确认的调用（428 及以上），并将时间范围限制为过去一小时、24 小时或 7 天。NexCMP 会保留最新的 200,000 条记录。通过密钥进行的更改也会以 `ak:<admin>/<key name>` 的名义显示在 Logs › Admin actions 中。

![显示状态、客户端、工具和IP的Activity标签页调用列表](https://nexcmp.com/zh-cn/docs/images/configure-with-ai/admin-api-keys-03-activity.webp)

## 验证 {#verify}

在IP范围内的任意机器上测试只读密钥：

```bash
curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"
```

你将获得一个包含权限范围内工具的JSON列表。运行其中一个：

```bash
curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'
```

密钥的**Last used**时间会更新，且调用会显示在**Activity**中。完整的工具列表和OpenAPI描述（`/v1/admin/openapi.json`）在[Connect an AI client](https://nexcmp.com/zh-cn/docs/configure-with-ai/mcp-admin/)中说明。

## 错误 {#errors}

错误信息为JSON格式：`{"error": {"code": "...", "message": "..."}}`。

| HTTP | `code` | 说明 | 解决办法 |
|---|---|---|---|
| 401 | `invalid_key` | 密钥缺失、格式错误或未知。在非管理路径上使用`ak_`密钥时也会返回此错误。 | 检查密钥；仅在`/v1/admin/`和`/mcp/admin`上使用它。 |
| 401 | `key_expired` | 密钥已过期。 | 创建一个新密钥。 |
| 401 | `key_revoked` | 密钥已被撤销。 | 创建一个新密钥。 |
| 403 | `ip_not_allowed` | 调用者的IP超出了密钥的IP范围。 | 从允许的IP发起调用，或使用正确的范围创建密钥。 |
| 403 | `local_only_key` | 为AI Chat或服务器CLI创建的密钥从另一台机器上被使用。 | 这些密钥仅在面板服务器本身上有效。 |
| 403 | `insufficient_scope` | 密钥缺少权限范围；响应包含`required_scope`。 | 使用该权限范围创建一个密钥。 |
| 403 | `forbidden_for_keys` | 端点或你尝试更改的设置对密钥关闭。 | 请在管理后台中进行操作。 |
| 403 | `demo_read_only` | 面板处于演示模式，且调用执行了写入操作。 | 请使用非演示面板。 |
| 403 | `confirm_in_ui` | 此操作必须在管理后台的屏幕上进行确认。 | 批准确认卡片。 |
| 428 | `confirm_required` | 预览已就绪；未作任何更改。包含`confirm_token`。 | 显示预览，然后使用`X-Confirm-Token`重试。 |
| 409 | `confirm_expired` | 令牌创建时间超过5分钟。 | 重新发送请求以获取新的预览。 |
| 409 | `confirm_mismatch` | 令牌属于不同的请求（方法、路径或请求体不同）。 | 重复相同的请求。 |
| 409 | `confirm_invalid` | 未知或已被使用的令牌。 | 重新发送请求以获取新的预览。 |
| 429 | `rate_limited` | 当前分钟内的调用次数过多。 | 等待`Retry-After`。 |
| 400 | `invalid_path` | 路径包含禁止的序列。 | 请使用普通路径。 |
| 413 | `too_large` | 请求体超过10 MB。 | 请发送较少的数据。 |
| 400 | `invalid_argument` | 工具参数缺失、未知或类型错误；消息中会指明具体参数。 | 修复该参数。 |

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

- 保持密钥短期有效且权限精简。建议每个客户端使用一个密钥，以便单独撤销。
- 密钥的权限取决于其权限范围。`secrets:write`加上`billing:write`是最敏感的组合；资金相关操作仍然会在预览阶段停止。
- 自动创建的密钥（用于AI Chat、服务器CLI）仅存活数分钟，且仅在面板服务器上有效。
- 要立即切断AI客户端，请吊销其密钥。可以在**Connected apps**标签页（[OAuth connectors](https://nexcmp.com/zh-cn/docs/configure-with-ai/oauth-connectors/)）中吊销OAuth连接。