POST/api/v1/admin/users/{userId}/avatars
管理员Cookie,ADMIN_USER_PROFILES_WRITEJSON 响应接入指南 ↗

后台暂存用户头像

请求参数

面向后台网页,要求可信HTTPS、独立HttpOnly Cookie及OWNER的ADMIN_USER_PROFILES_WRITE权限。App Bearer不能调用。这是明确的文件入口,不使用JWE;不能携带X-Budyoo-Encryption标记。写操作要求Origin等于后台源并带会话X-Admin-CSRF。

公共头见请求头,四语见公共响应,身份见后台协议。客户端类型和图片UUID本身不授予权限。

路径userId必填,为目标用户UUID;不存在返回404。无查询参数。 | multipart字段 | 类型 | 必填 | 限制 | | --- | --- | --- | --- | | file | binary | 是 | JPEG/PNG/WebP,单文件≤10MiB(10,485,760字节),整包≤11MiB,单边≤4096且总像素≤1600万 |

内容实际解码并移除元数据,等比重编码为最长边≤1024的PNG,不放大,不接受SVG或客户端文件路径。上传只暂存,不改变头像引用或已保存相册。沿用头像每小时20次、最多20个保留文件的既有额度;旧头像及孤立文件自动清理尚未实现。目标用户须ACTIVE且COMPLETE。

请求示例

示例UUID为合成数据;deviceId必须复用当前安装,不要每次新建。以下示例覆盖八项公共头;禁止日志输出Cookie或Bearer。

const url = new URL('/api/v1/admin/users/11111111-1111-4111-8111-111111111111/avatars', location.origin);
const headers = {
  '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': installationId, // 当前浏览器已持久保存的安装UUID
  'X-Request-Id': crypto.randomUUID(), 'X-Request-Timestamp': String(Date.now()),
  'X-Admin-CSRF': csrfToken, // 从加密会话响应取得,只保留内存
};
const form = new FormData();
form.append('file', file); // 用户选择的文件,不手动设置boundary
const response = await fetch(url, {method: 'POST', headers,
  body: form, credentials: 'same-origin', redirect: 'error'});
// 按HTTP状态和JSON code共同判断,不自动重发写请求

必须从已验证的HTTPS同源页面调用;Origin和Cookie由浏览器维护,不在脚本写入Cookie。实际前端统一封装接入另行完成。

成功响应

HTTP200,Cache-Control:no-store;合法请求ID回传。

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "contentType": "image/png",
    "sizeBytes": 2048
  },
  "errors": []
}
data字段 类型 可空 含义
id string(UUID) 否 保存资料的avatarId
contentType string 否 固定image/png
sizeBytes integer 否 规范化后文件大小,字节

注意:原App头像上传返回字段叫avatarId;本后台媒体接口返回id,不能混用两份契约。

失败响应

HTTP code 条件
400 BAD_REQUEST/VALIDATION_FAILED 路径UUID、请求格式或必填参数不合法
400 INVALID_CLIENT_HEADERS 公共头缺失、重复或格式错误
401 UNAUTHORIZED 未登录、会话失效或安装不匹配
403 FORBIDDEN/ADMIN_CSRF_INVALID 无对应权限、Origin或CSRF不符
404 NOT_FOUND 用户或归属范围内的图片不存在/已删除
426 HTTPS_REQUIRED 当前路径不允许明文HTTP
503 SERVICE_UNAVAILABLE 数据库/Redis依赖暂不可用
400 INVALID_AVATAR 空文件、格式、解码、尺寸或像素不符
413 PAYLOAD_TOO_LARGE 单文件超过10MiB或整包超过11MiB
429 AUTH_RATE_LIMITED 上传频率或保留数量达到上限
409 REGISTRATION_INCOMPLETE 目标用户尚未完成注册
403 ACCOUNT_DISABLED 目标账号被禁用

错误结构示例:

{"code":"UNAUTHORIZED","message":"按Accept-Language返回中文、英文、日文或韩文提示","data":null,"errors":[]}

未知或缺省语言回退英文;code不翻译。字段校验明细在errors[].field/message。网关可能先返回429/413,不能当成认证过的JWE业务响应。

接入说明

上传编号仅表示图片暂存成功;必须调用后台资料保存才能生效。放弃未绑定相册上传时可丢弃,丢弃不更改资料版本;已绑定照片通过资料保存移除。读取不公开、不支持其他用户查看,图片数据不写审计或日志。

后台成功动作与审计同事务,审计失败回滚数据库修改;新上传文件按事务失败补偿。审计只记录动作、目标UUID、请求ID和版本/数量摘要,不保存生日、介绍、图片内容或Cookie。资料保存动作USER_PROFILE_UPDATE,头像上传USER_AVATAR_UPLOAD,相册上传USER_PHOTO_UPLOAD,暂存丢弃USER_PHOTO_DISCARD。

已通过服务器隔离PostgreSQL/Redis完整整合272项回归,包含并行国家目录改动;本批24项覆盖30/31字符、鉴权、字段白名单、相册归属与九张上限、并发版本、两端真实JWE、后台CSRF和审计回滚。真实Servlet验证上传10MiB与超限,隔离Nginx另通过8项媒体路径大小检查。实现位于profile、media及admin/users模块,跨业务只走api契约。已随账号列表整合版本部署,V9已应用且媒体网关已更新;后台账号列表已接入头像读取,Flutter与后台资料编辑/相册页面尚未接入。完整278项服务器整合回归通过;本次公网浏览器核对列表及头像,其他新写接口的验收范围仍为服务器隔离测试。物理文件清理、公开图片分发、审核、好友、钱包和聊天不在本批范围。