站点管理

站点是加速的基本单位:一个域名一条记录,带回源、TLS、缓存、防护等全部配置。

站点列表

GET/api/me/sites

curl -H "Authorization: Bearer $HSCDN_KEY" \
     https://cdn.treeidc.cn/api/me/sites

响应含 sites 数组与 total。单个站点的主要字段:

字段	类型	说明
`id`	number	站点 ID,后续修改 / 删除都用它
`domain`	string	加速域名
`cname`	string	要在 DNS 上配置的 CNAME 目标(只读,由系统分配)
`enabled`	boolean	是否启用
`site_status`	string	运行状态
`disabled_reason`	string	被停用时的原因(如流量超限)
`origins`	array	源站列表,元素形如 `{"addr":"1.2.3.4","weight":1,"status":true}`
`origin_protocol`	string	回源协议:`http` / `https` / `follow`
`origin_http_port` `origin_https_port`	number	回源端口
`http_enabled` `https_enabled`	boolean	是否监听 HTTP / HTTPS
`force_https`	boolean	是否强制跳转 HTTPS
`http2` `http3`	boolean	协议开关
`cert_id`	number	绑定的证书 ID,见证书
`ssl_mode` `ssl_ciphers` `hsts` `ocsp_stapling`	—	TLS 相关配置
`cache_rules`	array	缓存规则
`security`	object	WAF / CC 防护配置
`access_control`	object	访问控制(黑白名单等)
`package_id`	number	所用套餐
`config_synced`	boolean	配置是否已同步到边缘节点
`created_at` `updated_at`	string	创建 / 更新时间(ISO 8601)

站点详情

GET/api/sites/{id}

按 ID 取单个站点,字段与列表元素一致。站点不存在或不属于你时返回 404。

创建站点

POST/api/sites

curl -X POST https://cdn.treeidc.cn/api/sites \
  -H "Authorization: Bearer $HSCDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "domain": "www.example.com",
        "origins": [{"addr": "203.0.113.10", "weight": 1, "status": true}],
        "origin_protocol": "http",
        "https_enabled": true,
        "force_https": true
      }'

创建时有三条由服务端强制的规则:

归属自动绑定 —— 站点始终归调用密钥所属的账号,请求里的 user_id 无效。
CNAME 不可自定义 —— 请求里的 cname 会被丢弃,由系统分配后在响应与列表里返回。
套餐自动选取 —— 不传 package_id 时,系统从你已购且未过期的套餐里挑一个;传了则校验是否属于你。没有可用套餐会返回错误。

响应:

{
  "ok": true,
  "site": { "id": 128, "domain": "www.example.com", "cname": "eq03gi57.hscsdn.cn", ... },
  "ignored_fields": []
}

不在可写字段清单里的字段会被丢弃而不报错(这是有意的:宁可少改一个字段,也不把整个请求拦住)。被丢掉的字段名会列在 ignored_fields 里 —— 请检查它,那是你发现字段名写错的唯一途径。

创建成功后,把返回的 cname 配到你的 DNS 上,加速才会生效。

修改站点

POST/api/sites/{id}/update

增量更新:只传要改的字段,未出现的字段保持不变。

curl -X POST https://cdn.treeidc.cn/api/sites/123/update \
  -H "Authorization: Bearer $HSCDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "origins": [
          {"addr": "203.0.113.10", "weight": 2, "status": true},
          {"addr": "203.0.113.11", "weight": 1, "status": true}
        ],
        "load_balance": "weight",
        "force_https": true
      }'

返回	含义
`200` + `ok:true`	已保存,配置会在数秒内下发到边缘节点
`404`	站点不存在,或不属于你
`403`	引用了不属于你的资源(例如别人的 `cert_id`)

下发是否完成可以看站点的 config_synced 字段。

ignored_fields —— 一定要检查

响应里恒有 ignored_fields 数组,列出被丢弃的字段名。字段名写错时,请求依然返回 200 ok:true,只有这个数组会告诉你:

// 请求: {"origin": [...], "remark": "ok"}   ← origin 少了个 s
{
  "ok": true,
  "site": { ... },              // remark 改了, origins 一个字节没变
  "ignored_fields": ["origin"]  // ← 只有这里能看出来
}

d = call("POST", f"/api/sites/{sid}/update", json=payload)
if d.get("ignored_fields"):
    raise RuntimeError(f"这些字段名写错了, 没有生效: {d['ignored_fields']}")

启用 / 停用

POST/api/sites/{id}/enable

POST/api/sites/{id}/disable

停用后该域名立即停止加速。

这与「套餐流量超限被系统自动停用」不是一回事。后者会在 disabled_reason 里写明原因,直接调 enable 也起不来 —— 需要先处理套餐(充值 / 续费 / 加量)。

删除站点

DELETE/api/sites/{id}

不可撤销。删除会一并清理该站点的解析记录与边缘配置。批量脚本里请务必先按 domain 二次确认 ID,不要直接用循环变量。