缓存刷新

POST/api/cache/refresh

让指定 URL 的缓存立即失效,下一次访问回源取新内容。

参数

参数	类型	必填	说明
`urls`	string	是	要刷新的 URL,多条用换行分隔

urls 必须是字符串,不是数组。

传入	返回
缺失 / 空串	`400` `{"ok":false,"message":"URL不能为空"}`
数组 / 数字 / 对象	`400` `{"ok":false,"message":"urls 必须是字符串(多条 URL 用换行分隔), 不能传数组/数字/对象"}`
超过 2000 条	`400`

这几种都是 400 而不是 5xx —— 传错类型是调用方的问题,重试没有意义。你的重试逻辑可以据此直接放弃,不必退避。

例子

curl -X POST https://cdn.treeidc.cn/api/cache/refresh \
  -H "Authorization: Bearer $HSCDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": "https://www.example.com/a.js\nhttps://www.example.com/b.css"}'

Python 里从列表拼:

urls = [
    "https://www.example.com/app.js",
    "https://www.example.com/app.css",
]
requests.post(
    "https://cdn.treeidc.cn/api/cache/refresh",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"urls": "\n".join(urls)},        # 注意: 拼成字符串, 不要直接传 list
    timeout=20,
)

用在发版流程里

典型做法是在 CI 部署完成后调一次,把本次变更的静态资源刷掉:

# CI 里, 部署成功之后
CHANGED=$(git diff --name-only HEAD~1 HEAD -- 'static/*' \
          | sed 's|^static|https://www.example.com|')

[ -n "$CHANGED" ] && curl -s -X POST https://cdn.treeidc.cn/api/cache/refresh \
  -H "Authorization: Bearer $HSCDN_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg u "$CHANGED" '{urls:$u}')"

如果你的静态资源文件名带内容哈希(如 app.a1b2c3.js),其实不需要刷新缓存 —— 换文件名本身就是最干净的失效方式。刷新更适合用在文件名不变的资源上,比如 /index.html。