接入文档
本域只提供静态资源,不承载业务接口与用户数据。所有请求以完整路径作为缓存键,路径区分大小写。
路径规范
路径分为「类型 / 业务标识 / 文件名」三段。业务标识用于区分调用方,同一文件在不同业务前缀下互不影响。
https://cdn.shizhisuo.com/assets/{type}/{owner}/{file}
| 段 | 取值 | 约束 |
|---|---|---|
type | img / css / js / font | 固定四类,不接受其他值 |
owner | 业务标识 | 小写字母、数字与连字符,不超过 32 个字符 |
file | 文件名 | 区分大小写,建议带内容指纹 |
带内容指纹的文件名(例如 app.9f3c1a.css)可以长期缓存,更新时更换文件名即可,不需要刷新边缘。
缓存策略
缓存时长按类型设定,边缘与浏览器使用同一份 Cache-Control。需要即时更新的文件请更换文件名。
| 类型 | 扩展名 | Cache-Control | 边缘 TTL |
|---|---|---|---|
| 图片 | webp avif jpg png svg | public, max-age=2592000, immutable | 30 天 |
| 样式 | css | public, max-age=604800 | 7 天 |
| 脚本 | js mjs | public, max-age=604800 | 7 天 |
| 字体 | woff2 woff | public, max-age=2592000, immutable | 30 天 |
边缘未命中的请求按区域回源,同一区域内合并并发回源,避免源站出现重复请求。
响应头
命中缓存时的典型响应:
HTTP/2 200 content-type: image/webp content-length: 42118 cache-control: public, max-age=2592000, immutable etag: "a41f9c2e-9f1a" last-modified: Fri, 20 Nov 2026 03:45:30 GMT x-content-type-options: nosniff referrer-policy: no-referrer age: 18422
age 表示该对象在边缘已缓存的时间(秒)。etag 与 last-modified 用于条件请求,命中 304 时不计入回源。
错误码
| 状态 | 含义 | 处理方式 |
|---|---|---|
404 | 路径不存在 | 检查业务标识与文件名大小写,确认 type 为四类之一 |
403 | 目录列表被禁用 | 使用完整文件路径,不要请求以 / 结尾的目录 |
429 | 单 IP 请求频率超限 | 退避后重试,批量任务请分散时间窗口 |
502 | 回源失败 | 先在状态页确认源站可用性,再重试 |
504 | 回源超时 | 同上,连续出现时联系维护方 |
变更记录
- 2.3 · 2026-10-28 字体 TTL 由 7 天延长至 30 天。
- 2.2 · 2026-09-16 图片根据
Accept头协商avif与webp。 - 2.1 · 2026-08-03 上线
ap-northeast-2(首尔),韩国请求不再回退东京。 - 2.0 · 2026-06-11 路径规范改为三段式,旧的两段式路径保留兼容至 2026 年底。