POST/api/v1/admin/media/downloads
独立管理员Cookie、CSRF、HTTPS、JWE及目标文件对应读权限JSON 响应接入指南 ↗

申请后台媒体下载

请求参数

本接口遵循公共协议、公共请求头、后台安全及JWE协议。Origin必须为后台来源,Cookie绑定当前安装,POST必须带X-Admin-CSRF。不接受App Bearer替代管理员身份。

字段 类型 限制
path string 必填,最长180字符,完整且大小写精确的既有后台媒体路径;不得包含域名、查询串、片段、百分号编码或相对路径
允许路径 权限
/api/v1/admin/users/{userId}/avatars/{id}、/api/v1/admin/users/{userId}/album-photos/{id} ADMIN_USER_PROFILES_READ
/api/v1/admin/profile-reviews/{id}/avatars/{source}、/api/v1/admin/profile-reviews/{id}/photos/{source}/{photoId} ADMIN_PROFILE_REVIEWS_READ
/api/v1/admin/posts/{postId}/photos/{id}、/api/v1/admin/posts/{postId}/files/{id}及其/poster ADMIN_POSTS_READ
/api/v1/admin/content-reports/{reportId}/evidence/{id}、/api/v1/admin/postcards/{cardId}/photos/{id} ADMIN_POSTS_READ
/api/v1/admin/interests/icons/{id} ADMIN_INTERESTS_READ

编号必须是小写标准UUID;source仅submitted或previous。服务端复用原领域归属、删除状态和审核快照检查;不得使用任意文件编号越权。

请求示例

下例为JWE解密后的业务正文,不能作为普通JSON直接提交:

{"path":"/api/v1/admin/users/11111111-1111-4111-8111-111111111111/album-photos/22222222-2222-4222-8222-222222222222"}

使用项目统一JWE网络层,提供以下请求头;Cookie由浏览器HttpOnly机制管理:

POST /api/v1/admin/media/downloads
Origin: https://admin.example.test
Accept-Language: zh-CN
X-Client-Type: admin
X-Platform: web
X-App-Version: 1.0.0
X-App-Build: 1
X-Channel: admin_web
X-Device-Id: 33333333-3333-4333-8333-333333333333
X-Request-Id: 44444444-4444-4444-8444-444444444444
X-Request-Timestamp: <当前Unix毫秒>
X-Admin-CSRF: <当前会话返回值>
X-Budyoo-Encryption: jwe-v1
Accept: application/jose
Content-Type: application/jose

实际信封结构及附加加密头以统一JWE网络层为准,不自行拼接密文。

成功响应

HTTP 200,以下为响应认证解密后的示意;地址和凭证均为占位数据:

{
  "code":"SUCCESS",
  "message":"操作成功",
  "data":{
    "path":"/api/v1/admin/users/11111111-1111-4111-8111-111111111111/album-photos/22222222-2222-4222-8222-222222222222",
    "transport":"CDN",
    "url":"https://media.example.test/media/album-photos/22222222-2222-4222-8222-222222222222.png",
    "expiresAt":"2026-11-19T12:05:00Z",
    "requestHeaders":{
      "X-Budyoo-Media-Token":"<bda_前缀的单文件随机凭证>",
      "X-Budyoo-Media-Path":"/api/v1/admin/users/11111111-1111-4111-8111-111111111111/album-photos/22222222-2222-4222-8222-222222222222"
    }
  }
}

CDN凭证最长5分钟,且不超过管理员会话绝对期限。只授权当前会话、路径和文件;每次CDN GET/HEAD及Range均重新核对会话、账号状态、权限和实际对象。URL本身不含凭证,不能单独读取文件。

当后台CDN开关关闭,或图片仍在数据库(兴趣图标及未迁移的历史明信片图片)时,显式返回transport=API、url=path、expiresAt=null、requestHeaders={};仍按原Cookie、公共头和HTTPS协议下载。权限错误不会返回兼容地址。

失败响应

沿用公共四语错误提示,code不翻译:400 BAD_REQUEST/VALIDATION_FAILED/INVALID_CLIENT_HEADERS/ENCRYPTION_REQUIRED;401 UNAUTHORIZED;403 FORBIDDEN/ADMIN_CSRF_INVALID;404 NOT_FOUND;503 SERVICE_UNAVAILABLE。用户状态错误沿用原资料媒体接口。网关限流返回429。JSON错误按既有JWE处理,未通过解密的请求按加密公共协议返回。

CDN实际下载拒绝时为HTTP403,不保证业务JSON或本地化正文,前端不能尝试匿名OSS回退。

接入说明

  1. 继续使用接口返回的后台文件路径作为稳定引用;显示前调用本接口。
  2. CDN仅发送返回的两个媒体头,credentials: omit、redirect: error,不发送后台Cookie、CSRF、App Bearer或JWE;不将凭证放进URL、日志、localStorage或IndexedDB。
  3. CDN只对精确后台来源允许CORS,预检允许两个媒体头及Range,实际GET/HEAD仍强制授权。后台CSP只增加配置中的媒体域名。
  4. CDN403可重新申请一次授权,仍失败则停止。网络错误、无权限或对象不存在不绕回OSS/API。服务器明确返回API时才使用兼容下载。
  5. 本次后台保留已有Blob预览和会话图片缓存,视频由CDN完整下载后播放、拖动;不宣称已实现浏览器分段流式播放器。底层CDN允许单Range读取。退出或切换会话清理原缓存并丢弃进行中的旧会话结果;已下载内容无法远程回收。
  6. 上传、审核、资料保存及审计契约保持原样。此接口是读取授权,不产生审核或配置写审计。

2026-11-19已部署到admin.budyoo.cn,运行值为ADMIN_MEDIA_CDN_ENABLED=true。候选版本定向回归6项通过,随后在隔离数据库完成Java全量1381项测试,失败0、错误0、跳过1;Java打包、后台静态站点构建、Nginx语法及应用健康检查通过。公网预检OPTIONS https://media.budyoo.cn/media/...从https://admin.budyoo.cn返回200,未带媒体凭证的GET返回403且带后台来源响应头。已登录后台的账号详情页实际加载头像和4张相册图片;当前生产库没有视频型community_file记录,视频与海报路径由相同授权链覆盖并由AdminMediaPermissionTest验证,待出现合规视频素材后再做播放器实物验收。后台Cookie、CSRF、管理员会话和领域权限均保留,退出或权限变化不会继续交付。

2026-11-20随Java统一App媒体协议重新部署,本接口字段和独立管理员协议保持不变,后台CDN开关仍为true。服务器完整1390项回归通过(0失败、0错误、1项条件跳过),其中后台媒体正向授权、角色/对象归属、CSRF、安装绑定、会话撤销与删除检查均通过。公网再次验证无管理员Cookie和仅持App凭证均无法申请后台媒体授权,后台来源预检返回200、实际无媒体凭证读取返回403。真实H.264视频及首帧、三段Range经App授权链验收,不等于本次已登录后台或验证浏览器播放器;范围见统一协议验证。