视知所CDN

接入文档

本域只提供静态资源,不承载业务接口与用户数据。所有请求以完整路径作为缓存键,路径区分大小写。

版本 2.3 更新 2026-10-28

路径规范

路径分为「类型 / 业务标识 / 文件名」三段。业务标识用于区分调用方,同一文件在不同业务前缀下互不影响。

https://cdn.shizhisuo.com/assets/{type}/{owner}/{file}
段取值约束
typeimg / css / js / font固定四类,不接受其他值
owner业务标识小写字母、数字与连字符,不超过 32 个字符
file文件名区分大小写,建议带内容指纹

带内容指纹的文件名(例如 app.9f3c1a.css)可以长期缓存,更新时更换文件名即可,不需要刷新边缘。

缓存策略

缓存时长按类型设定,边缘与浏览器使用同一份 Cache-Control。需要即时更新的文件请更换文件名。

类型扩展名Cache-Control边缘 TTL
图片webp avif jpg png svgpublic, max-age=2592000, immutable30 天
样式csspublic, max-age=6048007 天
脚本js mjspublic, max-age=6048007 天
字体woff2 woffpublic, max-age=2592000, immutable30 天

边缘未命中的请求按区域回源,同一区域内合并并发回源,避免源站出现重复请求。

响应头

命中缓存时的典型响应:

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回源超时同上,连续出现时联系维护方

变更记录