后台读取用户头像¶
请求参数¶
面向后台网页,要求可信HTTPS、独立HttpOnly Cookie及OWNER或VIEWER的ADMIN_USER_PROFILES_READ权限。App Bearer不能调用。这是明确的文件入口,不使用JWE;不能携带X-Budyoo-Encryption标记。若发送Origin也必须与后台源一致,跨站请求拒绝。
公共头见请求头,四语见公共响应,身份见后台协议。客户端类型和图片UUID本身不授予权限。
路径userId必填,为目标用户UUID;不存在返回404。路径id必填,为图片UUID,必须归属目标用户且仍有效。无查询参数。 无业务请求体。
请求示例¶
示例UUID为合成数据;deviceId必须复用当前安装,不要每次新建。以下示例覆盖八项公共头;禁止日志输出Cookie或Bearer。
const url = new URL('/api/v1/admin/users/11111111-1111-4111-8111-111111111111/avatars/44444444-4444-4444-8444-444444444444', 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()),
};
const response = await fetch(url, {method: 'GET', headers,
credentials: 'same-origin', redirect: 'error'});
// 200读取PNG Blob;失败响应解析统一JSON
必须从已验证的HTTPS同源页面调用;Origin和Cookie由浏览器维护,不在脚本写入Cookie。后台账号列表已通过统一媒体请求封装读取Blob,携带完整公共头;换页或关闭时释放当前显示引用,最后一个未完成引用离开才取消下载;退出时清空所有私有图片。
成功响应¶
HTTP200,Cache-Control:no-store;合法请求ID回传。
Content-Type:image/png,X-Content-Type-Options:nosniff;响应为去除元数据的PNG字节,不套JSON。不允许以图片URL作为公开或永久访问地址。
失败响应¶
| 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依赖暂不可用 |
错误结构示例:
{"code":"UNAUTHORIZED","message":"按Accept-Language返回中文、英文、日文或韩文提示","data":null,"errors":[]}
未知或缺省语言回退英文;code不翻译。字段校验明细在errors[].field/message。网关可能先返回429/413,不能当成认证过的JWE业务响应。
接入说明¶
账号列表和用户详情共用受保护头像组件,详情展示最新profile.avatarId;无头像时按性别使用默认头像,性别未设置则使用圆形Logo。后台头像与资料审核图片共用当前管理员会话的内存及IndexedDB缓存:账号头像按userId+avatarId、审核图片按审核项+来源+avatarId标识;同图并发合并,已验证图片切换菜单或强制刷新后可复用。两层缓存各最多64项/32MiB,下载成功后固定保留5分钟且不超过会话有效期,命中不延长有效期,超限按最近使用顺序淘汰;图片标识变化使用新文件,失败或损坏图片不缓存。刷新先经服务器恢复身份,再按管理员、会话及权限摘要选择缓存,摘要不含明文凭据;退出、换号或权限范围变化清理旧副本。列表/详情JSON仍每次读取,命中也校验当前权限与精确媒体路径,并实际解码后才允许通过头像审核。头像尚在加载时使用中性占位,不先显示默认头像;只有未设置头像或读取失败才回退默认素材。HTTP媒体继续no-store及同源Cookie/公共头,不把Cookie、CSRF或Blob地址写入持久存储;IndexedDB不可用时退回正常下载和内存缓存,最后一个未完成引用离开才取消下载。
上传编号仅表示图片暂存成功;必须调用后台资料保存才能生效。放弃未绑定相册上传时可丢弃,丢弃不更改资料版本;已绑定照片通过资料保存移除。读取不公开、不支持其他用户查看,图片数据不写审计或日志。
已通过服务器隔离PostgreSQL/Redis完整整合272项回归,包含并行国家目录改动;本批24项覆盖30/31字符、鉴权、字段白名单、相册归属与九张上限、并发版本、两端真实JWE、后台CSRF和审计回滚。真实Servlet验证上传10MiB与超限,隔离Nginx另通过8项媒体路径大小检查。实现位于profile、media及admin/users模块,跨业务只走api契约。已随账号列表整合版本部署,V9已应用且媒体网关已更新;后台账号列表已接入头像读取,Flutter与后台资料编辑/相册页面尚未接入。完整278项服务器整合回归通过;本次公网浏览器核对列表及头像,其他新写接口的验收范围仍为服务器隔离测试。物理文件清理、公开图片分发、审核、好友、钱包和聊天不在本批范围。
后台网页优先将本接口路径交给申请后台媒体下载,取得单文件CDN授权后读取。本文原文件协议继续兼容;CDN鉴权失败不会自动回退。