统一媒体交付与缓存¶
当前契约与发布边界¶
2026-11-20统一媒体协议已部署:所有已认证App成功聚合响应中的受支持用户媒体,以及批量下载授权,使用同一份RoutedMediaDelivery字段契约。不再要求X-Media-Delivery;不传、cdn-v1、oss-v1均使用同一结构,服务端不再用该头选择格式,也不回传能力头。产品尚未正式开放,本次不保留旧App媒体响应格式。
统一媒体协议已在唯一正式部署环境生效,实际运行配置仍为dev。 本次完成服务器构建、发布前备份和应用切换,没有新增数据库迁移、执行上线前清库或修改OSS桶权限。客户端应使用已同步的统一协议代码,服务器与公网验证范围见统一协议验证,设备验收单独记录。
本次服务器完整clean verify为1390项、0失败、0错误、1项条件跳过;部署后真实公网39项检查通过,覆盖PNG、H.264视频及首帧、缓存HIT、视频三段Range、跨账号拒绝、后台身份边界、退出及删除后的撤权。合成账号已注销,正式媒体对象已删除,原始暂存按既有签名宽限回收;这些结果不代替客户端播放器和真机验收。
原接口直接返回地址¶
职责边界:CDN启停、域名、回源和URL生成由后台负责。Flutter业务页面只接收后台URL并交给现有公共媒体加载组件;必要的私密凭证、请求头和缓存由该组件集中处理,页面不配置CDN,不新增鉴权协议。
原资料、首页、关系、动态、评论、明信片和上传确认的成功JSON自动提供媒体地址;公共头、Bearer、JWE、业务ID、审核、保存与并发字段保持原规则。首屏使用原聚合接口,不为每张图额外请求下载授权。
原有avatarUrl、url、contentPath、photoUrl、posterUrl、thumbnailUrl和thumbnailUrls中的受支持用户媒体路径替换为真实交付地址。原本人资料只有非空avatarId时补充可空avatarUrl;albumPhotoIds保持并补充顺序一致的albumPhotos:[{id,url}]。他人头像仍只取有权读取的已审引用。国家旗帜、兴趣图标等目录资产不在转换范围;用户默认头像仍可显式返回API交付。
含受支持用户媒体的响应顶层增加mediaDelivery数组,与data同在JWE密文内;没有这类媒体时不添加。一个业务path在单次响应只登记一次。独立下载授权直接在data[]返回同结构,不再套顶层mediaDelivery。
| 服务端结果 | transport | 加载方式与缓存 |
|---|---|---|
| 已启用CDN的有权对象 | CDN | 固定HTTPS地址+返回的路径头+独立媒体凭证;PUBLIC最多缓存86400秒,PRIVATE仅内存 |
| CDN关闭、允许公开交付的已审对象 | OSS_PUBLIC | 公开OSS HTTPS;无媒体凭证,最多缓存86400秒 |
| CDN关闭、私密或未启用公开交付的对象 | OSS_SIGNED | 完整OSS签名地址;最长5分钟,只在当前账号内存使用 |
| 默认头像等明确API资源 | API | 原相对路径,按原文件接口身份和缓存规则加载 |
| 当前无权或媒体依赖故障 | NONE | url=null,access为DENIED/UNAVAILABLE;不使用历史地址或缓存绕过权限 |
CDN开关和公开交付开关只影响服务端通道选择,字段结构不变化。客户端不要拼接CDN域名、解析对象键或因403自行切回OSS/API。OSS直传、暂存确认、私有回源及管理员协议继续独立保留。
统一字段与失败隔离¶
字段固定为path、url、access、expiresAt、cacheKey、cacheMaxAgeSeconds、code、transport、requestHeaders、authorization。完整类型、可空性、枚举与合成示例见统一字段表。不再返回旧下载项delivery或单项message;顶层message与字段错误继续按原四语规则本地化,单项用固定code处理。
对象媒体的cacheKey为服务端生成的不透明稳定键,与域名、URL签名、媒体凭证无关;API和不可用条目使用业务path。客户端原样使用,不以URL或签名参数作为对象身份;PRIVATE不能因键稳定而开启磁盘缓存。
媒体复制、签名或查询依赖失败,只将成功聚合响应中的对应URL置null,并返回access=UNAVAILABLE、transport=NONE及错误code,不推翻已经提交的资料/动态保存,不因此重做业务写入。业务本身的失败仍按原HTTP错误返回;独立下载授权的供应商失败仍整批503。匿名响应、管理员响应、错误响应和二进制正文不经过本App投影。
Flutter接入与设备验收¶
- 去掉控制协议格式的本地CDN开关、能力请求头和旧下载项解析,统一消费上述字段;开发构建与正式构建使用同一协议,地址仍使用服务端返回值。
- CDN仅在目标origin与授权origin及凭证origin精确一致时附加路径头和媒体Token;凭证按账号合并刷新、仅保存在内存。OSS连接不带本站Bearer、Cookie、JWE、公共头或媒体Token;API资源继续原身份处理。
- PUBLIC依当前业务可见性、cacheKey和有效期复用本机缓存;PRIVATE仅当前账号/页面内存。换号、退出、注销清理凭证、私密字节与晚到回执;业务下架/删除/屏蔽立即撤下显示。
- CDN 403最多刷新凭证并重试一次;OSS_SIGNED到期需网络读取时按path重新下载授权,最多重试一次。再次拒绝即停止,不轮询、不绕回旧地址。媒体故障不重复资料保存、发动态或上传确认后的业务操作。
- 真机覆盖头像/相册、本人主页/他人资料、动态图片/视频封面、明信片照片、音视频持续Range及拖动;检查首次加载、缓存命中、过期刷新、退出换号、跨账号拒绝、弱网恢复和后台切换。核对媒体正文走media域名,静态API例外有明确来源;控制面继续HTTPS/JWE。
- Java协议已部署,真实域名的服务器探针与设备验收分别记录。服务器自动测试和公网字节/Range检查不证明Android/iOS播放器附加头、磁盘缓存、移动网络或海外链路已通过。
2026-11-20客户端对话已报告上述协议清理与公共组件同步完成,页面仍只传后台URL;Java未修改Flutter仓库。前端425项回归与43项补测属于客户端报告,本次没有构建客户端或执行真机验收。Java最终字段没有再次变更,后端部署已完成,后续由客户端任务执行设备联调。
OSS公开对象边界¶
CDN关闭且服务端允许公开交付时,仍可使用独立media/public/*副本。已有公开OSS地址可匿名读取,不能靠App退出立即使已获取的公开链接失效;撤回经原持久任务回收,云故障会延后。PRIVATE签名是短期持有能力,新的授权检查当前权限,已经签发的地址在到期或对象删除前可能仍有效。
本轮不删除公开对象、不调整桶ACL、不关闭公开前缀。当前私有源对象、上传与回源身份保持原权限;统一协议不等于所有历史媒体只能经CDN访问。公开副本收敛或权限变更须另行实施并验收。
既有验证¶
此前2026-11-17的1364项服务器回归、真实OSS四类公开/七类私密对象、40项公网/回收检查及2026-11-19媒体CDN公网15项检查属于当时已部署版本。它们仍说明原存储与云链路的已验范围,不替代本次统一协议上线或Flutter设备验收;详情见CDN验证记录。