API 生产接入清单

开放 API 面向客户账号，不等同于管理员后台 API。你的程序只能读取或修改当前账号拥有的套餐、网站、任务和允许的客户资源。

认证和密钥

• 使用服务端环境变量、云密钥管理或 Docker Secret 保存 API 密钥。
• 推荐 Authorization: Bearer <API_KEY>；也支持 X-API-Key。
• 不要同时发送两个不同的密钥；这会被判定为认证冲突。
• 轮换密钥后，旧密钥立即失效；部署时先更新 Secret，再逐步重启调用方。
• 日志只记录密钥前缀和末四位，不能记录完整请求头。

创建网站的安全流程

1. GET /packages 找到当前账号的 active 套餐。
2. GET /sites?search=域名 检查域名是否已经存在。
3. 校验源站地址、端口和协议，避免把内网地址或管理地址暴露给上游。
4. POST /sites 创建网站，并保存返回的本地网站 ID。
5. 轮询 GET /sites/:id 或监控接口，直到同步状态稳定。
6. 由 DNS 系统添加 CNAME，完成后再做访问验收。

创建请求示例：

curl --fail-with-body -X POST "$KUNTT_BASE/sites" \
  -H "Authorization: Bearer $KUNTT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "cdn.example.com",
    "packageId": "客户套餐ID",
    "origins": [{"address": "origin.example.com", "weight": 1}],
    "originProtocol": "http",
    "httpPort": 80,
    "httpsPort": 443
  }'

幂等和重试

网络超时不代表请求没有成功。对于创建网站、提交缓存任务等写操作，重试前先查询结果：

• 创建网站：按域名搜索，确认不存在后再创建。
• 缓存任务：保存业务批次号和目标 URL，避免重复提交大量刷新。
• 启停网站：重复发送同一状态是安全的，但仍要限制重试次数。
• 429：读取 Retry-After，按 1、2、4 秒指数退避，不要并发轰炸。
• 502/503：先记录 requestId，短暂退避后重试；持续失败应转人工排查。

资源归属

接口会在服务端重新检查套餐、网站和 URL 的归属。缓存任务中的 URL 主机名必须属于当前账号的网站；删除网站还需要在 confirmDomain 中原样填写当前域名。

不要把上游管理员端的 upid、节点 ID 或其他内部标识当作客户 API 的套餐 ID。客户 API 返回的 ID 是面向当前账号的稳定引用。

监控和审计

每次调用至少记录：

时间、HTTP 方法、路径、状态码、code、requestId、耗时、业务批次号

不要记录：API 密钥、Cookie、支付密钥、DNS-API Secret、完整 Authorization 头。

建议给调用方设置：连接超时、读取超时、最大重试次数、并发上限和失败告警。发布前在测试账号验证 401、403、404、429、502 等错误路径，确认程序不会把错误响应当成成功数据。

删除和高风险操作

删除网站会解除域名、证书和策略关联。生产环境建议先停用、切换 DNS、确认访问已迁移，再执行删除。高风险配置变更应保留操作者、审批单号和变更前后的 JSON 摘要。

下一步：阅读 错误码与限流 和 完整示例。