CDN媒体远程鉴权回调¶
请求参数¶
调用方为CDN,不供App或网页直接调用。不是普通AppJSON接口,不要求八项App公共头,不使用Cookie、本站Bearer或JWE;仅HTTPS。无查询参数和请求体。已提供的请求头必须唯一、非空,不允许换行;媒体token与path在实际GET/HEAD时必需,OPTIONS预检不携带。
| 头 | 最大长度 | 来源与含义 |
|---|---|---|
| X-Budyoo-CDN-Secret | 64 | 云侧回调配置与后台持有的独立随机秘密;不能下发App或写进公开文档/日志 |
| X-Budyoo-CDN-URI | 180 | CDN以$request_uri覆盖为终端请求的原始完整资源URI(含查询串);当前须精确为/media/正式对象键,无查询串、编码或外部URL |
| X-Budyoo-CDN-Method | 7 | CDN覆盖为终端请求方法,只允许GET、HEAD,以及后台浏览器CORS预检OPTIONS |
| X-Budyoo-CDN-IP | 45 | CDN覆盖为终端连接的字面IPv4/IPv6,不能转发用户自报X-Forwarded-For、主机名或列表 |
| X-Budyoo-Media-Token | 47 | App为bdm_媒体凭证;后台为bda_单文件授权,两种身份和索引独立 |
| X-Budyoo-Media-Path | 180 | 从终端保留的原业务媒体path;须重新通过原领域权限,并与CDN-URI的对象完全匹配 |
回调秘密与上述CDN覆盖字段不能直接从终端同名头透传。业务path不能作为可信身份,只用于服务端重新鉴权。正确媒体token也不能访问其他无权对象、目录、原始staging或管理接口。
浏览器预检另外保留唯一的Origin(最多200)、Access-Control-Request-Method(最多4)和Access-Control-Request-Headers(最多200)。仅后台CDN启用、Origin精确匹配后台、请求方法GET/HEAD且请求头仅包含两个媒体头和可选Range时允许。OPTIONS的200只表示可继续浏览器预检,不给GET/HEAD授予任何文件权限。实际后台读取按后台媒体下载检查当前管理员会话、权限与文件归属,不套用App的注册/VIP准入。
请求示例¶
仅供CDN管理者配置,示例材料均为占位符,不代表可用凭证:
GET /api/v1/media/cdn/authorize HTTP/1.1
Host: api.example.com
X-Budyoo-CDN-Secret: <独立64位十六进制回调秘密>
X-Budyoo-CDN-URI: /media/avatars/33333333-3333-4333-8333-333333333333.png
X-Budyoo-CDN-Method: GET
X-Budyoo-CDN-IP: 198.51.100.20
X-Budyoo-Media-Token: <本次bdm_媒体凭证>
X-Budyoo-Media-Path: /api/v1/media/avatars/33333333-3333-4333-8333-333333333333
成功响应¶
HTTP200、空正文、Cache-Control:no-store。表示此时、此会话对该精确对象和方法允许联网读取;不是整个桶或其他文件的授权。CDN此后再执行缓存读取或私有回源。
失败响应¶
- HTTP403、空正文:后台CDN开关关闭,或任何鉴权材料缺失/重复/非法,会话过期/注销/撤销、账号/设备/IP限制、注册/VIP不准入、屏蔽、媒体不存在/不可见、path与对象不符、缓存索引/数据库依赖异常等。Java层不返回可能被误判为成功的200业务错误。
- HTTP405:回调方法不匹配;实际云配置必须使用GET。Nginx在开关关闭时直接拒绝,返回正文可为网关统一错误,不进入Java。
- 其他网络或框架错误:不能视为鉴权成功;CDN必须配置超时拒绝,其他未定义状态码拒绝。
接入说明¶
CDN成功状态只配置200,失败配置403;“其他状态码是否放行”设为否,“鉴权超时之后的动作”设为拒绝。全文件类型执行鉴权,不能只覆盖有扩展名文件,因为视频对象路径可为content。先鉴权后访问缓存,不能把一次200结果按URL共享给其他账号。HEAD、Range、缓存命中、退出、封禁、屏蔽和下架都要实际验收。
远程鉴权会增加后台轻量请求;图片、音视频正文不经过此接口。CDN私有回源时去掉媒体token和业务path头。源站匿名访问要在客户端切换验证后关闭,防止绕过CDN。完整客户端契约见固定媒体地址协议。
2026-11-19深圳正式部署环境(上线前阶段,当前运行配置为dev)已启用真实CDN,回调为https://api.budyoo.cn/api/v1/media/cdn/authorize,全文件类型GET鉴权、3秒超时拒绝、非200拒绝配置已生效。实际边缘HIT后无凭证、伪造凭证、跨账号、路径不符、查询串变体及退出后读取均返回403;合法GET/HEAD/Range和终端伪造可信回调头覆盖检查通过。此前后端25项媒体测试、Nginx关闭/隔离开启15项及1364项全量结果仍为历史验证依据,本次未重跑Java全量。容量、封禁/屏蔽/下架的全部云端组合及Flutter设备验证尚未覆盖,完整边界见共享契约。