NPanel 智能授权文档

工作模型

智能授权分为长期身份和短期执行能力。长期身份由 Access Key 与 Secret Key 组成，用于证明 AI 客户端是谁；服务端短期授权只包含一次任务获准的业务指令与资源范围，并在指定时间后自动失效。

敏感数据不经过 AIAI 只提交能力名称、资源 ID 和非敏感业务参数。面板保存的登录密码、数据库密码、DNS 凭据、私钥、通知密钥和环境变量不会进入 AI 请求或响应；需要凭据时由面板在内部按资源 ID 解密并调用既有功能。

建立身份

面板用户创建独立 AI 凭证。

申请能力

AI 提交原因、指令、资源和时长。

人工确认

面板核对时间、IP、能力、资源与时长。

短期执行

批准后激活自动到期的服务端授权。

创建和管理 AI 凭证

进入面板侧边栏的“智能授权”。
在“AI 凭证”模块点击“新建密钥”。
填写名称和有效期。通信密钥只证明客户端身份，本身不携带操作权限。
创建后立即保存 AK 与 SK。SK 只显示一次，面板仅保存其哈希。

能力上限审批人和通信密钥所属账号必须同时拥有能力所需的人类权限；账号权限被收回后，已批准授权也无法继续执行该能力。

密钥列表会标记“有效”“已过期”或“已撤销”。过期密钥不能建立新的授权请求；不再使用的密钥应主动撤销。

审核授权请求

AI 客户端通过 AK/SK 建立身份后，提交需要的能力、资源、原因和申请时长。面板只展示仍在有效期内的待处理请求。

点击“直接授权”后，二次确认窗口会显示：

请求发起时间和来源 IP。
AI 申请的原始时长。
AI 申请的能力列表与资源范围。

操作者可以缩短或调整授权时长，也可以取消部分申请能力，但不能添加 AI 原本没有申请的能力。破坏性和配置能力最长授权 300 秒。确认后，面板激活短期授权。

使用短期授权

短期授权保存在面板服务端。AI 客户端始终使用同一组 AK/SK，面板会按客户端、来源 IP、能力和资源范围自动匹配有效授权；授权到期后需要重新申请。

POST /api/v1/ai/execute
X-NPanel-Access-Key: <AK>
X-NPanel-Secret-Key: <SK>
Idempotency-Key: task-20260824-001
Content-Type: application/json

{
  "capability": "php.project.create",
  "arguments": {
    "name": "example",
    "rootDir": "/var/www/example",
    "phpVersion": "8.3",
    "domains": ["example.com"]
  }
}

AI 只能调用能力目录中的结构化指令。终端、Shell、root 文件、系统用户、SSH、任意服务、特权 Docker 和原始服务配置均为人工专用，无法申请。PHP 配置只允许写入 NPanel 固定 drop-in，并限制在安全字段白名单内。

所有执行参数都会经过敏感字段拒绝检查，功能响应也会在返回 AI 前删除密码、Token、密钥、环境变量、邮箱、命令行和任务输出等字段。外部数据库或 DNS 操作只接受已授权的 connectionId 或 dnsProviderId，不会返回对应凭据。

到期与撤销

短期授权到期后自动失效。
撤销通信密钥会同时终止该客户端相关的待处理和已批准授权。
异常情况下，管理员可以通过紧急撤销关闭全部 AI 授权。
创建、审批和撤销操作均写入面板审计链。

接口调用顺序

阶段	接口	说明
创建身份	`POST /api/v1/auth/communication-keys`	由面板用户创建 AK/SK。
申请授权	`POST /api/v1/ai/authorization-requests`	AI 使用 AK/SK 提交能力、资源范围和 TTL。
人工审批	`POST /api/v1/ai/authorizations/{id}/approve`	面板缩小能力和时长后激活服务端授权。
读取结果	`GET /api/v1/ai/authorization-requests/{id}`	AI 使用 AK/SK 查询授权状态和有效期。
读取目录	`GET /api/v1/ai/capabilities`	列出可授权能力和明确禁止的人工专用边界。
执行能力	`POST /api/v1/ai/execute`	使用 AK/SK 调用获批的结构化指令，面板自动匹配有效授权。
撤销密钥	`DELETE /api/v1/auth/communication-keys/{id}`	终止客户端长期身份。

让 AI 只执行有限、短期、可审计的业务能力