客户开放 API 接口矩阵

本页是可直接交给开发人员的接口索引。基础地址为：

https://cdn.1888.news/api/open/v1

所有接口都要求客户 API 密钥，并返回统一结构：

{
  "code": 0,
  "msg": "成功",
  "data": {},
  "requestId": "请求追踪 ID"
}

账户、套餐与订单

方法	路径	说明
GET	/account	当前账号、余额、验证状态和累计实付充值
GET	/packages	当前账号已购买套餐列表
GET	/packages/:id	套餐详情
GET	/packages/:id/usage	套餐实时用量
GET	/packages/:id/upgrades	当前套餐可用升级包
GET	/catalog	当前公开在售套餐、分类和升级包
GET	/orders	当前账号订单列表
GET	/orders/:id	当前账号单个订单

路径中的 :id 是控制台返回的客户套餐实例或订单 ID，不是上游管理员目录 ID，也不是 upid。

网站生命周期

方法	路径	说明
GET	/sites	分页查询网站，支持 page、limit、search
GET	/sites/:id	网站详情
POST	/sites	新增网站并绑定客户套餐
PATCH	/sites/:id/origin	更新源站、回源协议和端口
PATCH	/sites/:id/status	{ "enabled": true/false } 启用或停用
DELETE	/sites/:id	必须提交 { "confirmDomain": "当前域名" }

创建网站前先调用 /packages 和 /sites，确认套餐有效且域名没有重复。删除前先切换 DNS 并确认不再需要证书、缓存和安全策略。

网站配置分区

网站配置不开放客户级完整 PUT，避免一次请求覆盖无关配置。按分区调用：

PATCH /sites/:id/config/basic
PATCH /sites/:id/config/origin
PATCH /sites/:id/config/https
PATCH /sites/:id/config/security
PATCH /sites/:id/config/cache
PATCH /sites/:id/config/access
PATCH /sites/:id/config/advanced

服务端会重新校验证书、ACL、CC 规则、源站地址和资源归属；请求中只提交当前分区字段。

监控、排行与日志

方法	路径	说明
GET	/sites/:id/analytics	流量、带宽、请求、命中率、状态码趋势
GET	/sites/:id/realtime	实时监控指标
GET	/sites/:id/rankings	URL、IP、来源、国家和省份排行
GET	/sites/:id/access-logs	访问日志
GET	/sites/:id/blacklist-logs	拉黑日志

如果上游统计暂时不可用，接口会返回明确的 requestId 和错误原因。客户端应把该次指标标记为“暂不可用”，不要把它当成 0 写入报表。

缓存任务

POST /api/open/v1/cache/tasks
Authorization: Bearer 你的API密钥
Content-Type: application/json

{
  "type": "purge",
  "urls": [
    "https://cdn.example.com/assets/app.css",
    "https://cdn.example.com/images/logo.png"
  ]
}

type 支持 purge、purge-directory 和 preheat，每次最多 100 个 URL；URL 主机名必须属于当前账号的网站。

客户资源白名单

需要自动化管理证书、DNS-API、ACL、CC 规则和四层转发时，使用资源白名单：

/resources/site-groups
/resources/certs
/resources/dnsapis
/resources/acls
/resources/cc-matchs
/resources/cc-filters
/resources/cc-rules
/resources/jobs
/resources/streams
/resources/stream-groups

资源查询、创建、更新和删除都会按当前客户归属校验。证书响应不返回私钥，DNS-API 查询不返回 AccessKey、Secret、Token 或原始认证 JSON。系统内置 CC 匹配器、过滤器和规则只读。

不开放的管理员能力

客户开放 API 不暴露用户管理、节点、区域、线路、全局套餐目录写入、上游订单、全局消息、系统设置、支付/短信/邮箱/极验配置，也不接受任意上游路径代理。管理员后台和客户开放 API 是两套权限边界。

下一步：阅读认证与密钥、网站接口和错误码与限流。