开放 API 与 Webhook

获取 Token

客户：账号设置 → 开放 API Token → 生成（Token 只显示一次，服务端只存哈希）。

管理员：财务端管理后台 → 帮助中心旁边可查看接口文档页 /docs/api。

认证与限流

curl -H "Authorization: Bearer nkx_xxxxxxxx" https://cloud.example.com/api/open/v1/me

• 每个 Token 每分钟 120 次请求
• 只返回该账号自己的资源

接口一览

方法	路径	说明
GET	/api/open/v1/me	账号与余额
GET	/api/open/v1/game/instances	游戏实例列表
GET	/api/open/v1/game/instances/{id}/logs?tail=100	实例日志
POST	/api/open/v1/game/instances/{id}/power	开关机 {"action":"start|stop|restart"}
POST	/api/open/v1/game/instances/{id}/command	执行命令 {"command":"say hi"}
GET	/api/open/v1/game/instances/{id}/stats?tf=hour	资源监控
GET	/api/open/v1/game/instances/{id}/files?path=/	文件列表
POST	/api/open/v1/game/instances/{id}/files	文件操作（rename / copy / mkdir / extract …）

Webhook

账号设置 → Webhook：填回调地址，选择事件。

支持事件：

• vm.created 机器开通
• order.paid 订单支付
• vm.expiring 即将到期
• ticket.replied 工单回复

回调请求示例：

POST https://你的服务/webhook
Content-Type: application/json
X-NKX-Event: order.paid
X-NKX-Signature: <hmac-sha256(secret, body)>

{"event":"order.paid","order_id":12,"amount_cents":500,"kind":"buy","time":"2026-09-27T14:00:00+08:00"}

验签（Node.js 示例）：

const crypto = require('crypto')
const sig = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
if (sig !== req.headers['x-nkx-signature']) return res.status(403).end()

失败会重试 3 次（间隔递增）。

主控执行 API（内部）

财务端调用主控的接口使用 X-Service-Token 头，仅限内网 / 服务端调用，不要暴露给客户。