查询用户账号列表¶
请求参数¶
仅后台web客户端。必须使用HTTPS和JWE;八项公共元数据必填,clientType=admin、platform=web、channel=admin_web。客户端类型不是管理员认证,App Bearer不能调用后台。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
| q | string | 否 | 默认空,最大64字符;昵称不区分大小写的字面包含或完整UUID |
| status | string | 否 | 空、ACTIVE、DISABLED、DELETED(已注销UUID墓碑,个人资料已清理) |
| registrationStatus | string | 否 | 空、INCOMPLETE、COMPLETE |
| statistic | string | 否 | 默认ALL;仅ALL、TODAY、MALE、FEMALE、GENDER_UNSET,区分大小写;省略或空按ALL处理 |
| page | integer | 否 | 默认1,1–100000 |
| pageSize | integer | 否 | 默认20,1–100 |
statistic为顶部统计卡片对应的互斥分类:ALL全部账号;TODAY按Asia/Shanghai自然日当天00:00至次日00:00的创建时间筛选(左闭右开);MALE/FEMALE按已保存gender=male/female筛选;GENDER_UNSET包括gender为空及尚无资料记录的账号。分类与q、status、registrationStatus取交集,先在数据库过滤再分页,total是全部匹配数;省略保持旧行为。全量口径与基础统计一致,包含禁用、未完成及注销墓碑,不包含管理员;并发新注册或跨日时两个独立请求的快照可能不同。
请求示例¶
通过管理员统一请求约定加密后发送,下面表示解密后的业务内容。外层使用Accept: application/jose;GET无正文,密文置X-Budyoo-JWE。写请求Origin必须与后台源一致,会话操作另带X-Admin-CSRF;HttpOnly Cookie由浏览器自动携带。
无业务JSON正文;查询参数按上表发送。
最小加密请求示例(仅合成数据,Cookie由浏览器维护):
const url = new URL('/api/v1/admin/users?statistic=MALE&page=1&pageSize=20', 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,
'X-Request-Id': crypto.randomUUID(), 'X-Request-Timestamp': String(Date.now()),
};
const encrypted = await codec.prepare({url, method: 'GET', headers, body: null});
const response = await fetch(url, {headers: encrypted.headers,
credentials: 'same-origin', redirect: 'error'});
const payload = await encrypted.decode(response);
// codec为统一createJweEncryption实例;先检查HTTP状态和业务code再展示data。
成功响应¶
HTTP200,Cache-Control:no-store。实际外层为JWE,解密后示例:
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"items": [
{
"userId": "11111111-1111-4111-8111-111111111111",
"nickname": "合成示例",
"displayName": "合成示例",
"registrationChannel": "google_play",
"registrationAccount": "+8613800000000",
"registrationAccountType": "phone",
"avatarId": null,
"gender": "female",
"vipActive": false,
"country": "cn",
"ipLocation": {
"countryCode": "JP",
"region": "overseas",
"observedAt": "2026-11-06T01:00:00Z"
},
"status": "ACTIVE",
"banned": false,
"registrationStatus": "COMPLETE",
"registrationStep": 4,
"createdAt": "2026-11-03T00:00:00Z"
}
],
"total": 1,
"page": 1,
"pageSize": 20
},
"errors": []
}
| 字段 | 类型/可空 | 含义 |
|---|---|---|
| items | array,不为null | 当前页账号,空结果为[] |
| total/page/pageSize | integer,不为null | 筛选后的总数、当前页与请求页大小 |
| items[].userId | UUID string,不为null | 用户账号标识 |
| items[].nickname | string/null | 用户原始昵称,新写入为1–8个UTF-16代码单元,历史昵称按原值返回;null或空白时网页按当前语言显示“未设置” |
| items[].displayName | string,不为null | 旧版兼容字段,新网页不使用;原昵称优先、否则注册账号/UUID的语义保留 |
| items[].registrationChannel | string/null | 账号创建时验证请求的X-Channel;历史缺失时由后续成功登录/刷新或Bearer认证请求首次补录,已有值不覆盖。尚未补获和注销清理后为null;补录不代表历史注册来源,仅统计展示,不是可信身份或设备证明 |
| items[].registrationAccount | string/null | 实际注册手机号(E.164)或邮箱;即使已有昵称也返回。没有手机号/邮箱身份时为null,网页显示“未设置” |
| items[].registrationAccountType | string/null | phone或email,与注册账号配对返回;隔离开发身份归一为相同类型,无注册联系方式时为null |
| items[].avatarId | UUID string/null | 当前资料已选头像编号;null表示未设置,不能当作公开图片URL |
| items[].gender | string/null | male、female或尚未填写的null,不由头像或注册账号推断 |
| items[].vipActive | boolean,不为null | 服务端确认、已生效、未到期且未撤销的VIP;与准入开关是否开启无关 |
| items[].country | string/null | 用户主动选择的资料国家代码,尚未填写为null;头像右下角国旗继续使用此字段,不被IP识别覆盖 |
| items[].ipLocation | object,不为null | 最近记录的已认证访问IP归属地;与country独立,不返回原始IP |
| items[].ipLocation.countryCode | string/null | 离线IP库识别的ISO两位大写国家/地区代码,如CN、JP;无近期记录、非公网地址或无法识别时为null |
| items[].ipLocation.region | string/null | 仅识别成功时返回:CN为domestic,其他已识别国家/地区为overseas;未知为null,不复用闪屏的默认国内回退 |
| items[].ipLocation.observedAt | ISO 8601 string/null | 所选访问记录的服务器采样时间;无近90天内记录时为null;有记录但IP无法识别时仍保留时间 |
| items[].status | string,不为null | ACTIVE、DISABLED或DELETED;注销不会物理删除用户UUID历史行 |
| items[].banned | boolean,不为null | 当前有效的账号运营处罚,独立于status;不是IP定位结果 |
| items[].registrationStatus | string,不为null | INCOMPLETE或COMPLETE |
| items[].registrationStep | integer,不为null | 资料恢复步骤1–4,完成后仍为4;VIP不计入步骤 |
| items[].createdAt | ISO 8601 string,不为null | 账号首次创建的注册时间,带时区;不是资料完成时间 |
排序固定createdAt降序再userId降序。新字段按兼容增加,原字段保持;总数、资料、注册账号及权益在同一只读快照内读取,身份和权益按页批量查询。
“IP 国家/地区”列只读取ipLocation,单行显示对应旗帜和大写代码(如CN),不显示国内/海外副标题;region仍按上述契约返回。无记录、识别失败或旧响应缺少该字段均显示四语“未识别”,不借用资料country或管理员浏览器的IP。头像国旗继续展示用户选择的country,两处不同是正常情况。鼠标提示展示访问记录时间;IP仅表示网络出口,VPN、代理及旅行会改变结果,不能证明国籍或物理位置。
数据来自已有account_access_observation中的成功认证记录,按当前页批量选择近90天内每个账号最新last_seen_at,同时间以记录ID降序稳定选择。记录沿用同目标约五分钟更新的采样策略,因此不是实时在线位置;最新记录无法识别时不退回更早的已识别国家。匿名闪屏不能单独关联到账号,管理员读取不会刷新访问时间;过期记录和注销清理后的记录不使用。本次无新增表、无IP回填,也不改变App资料或闪屏布局策略。离线识别复用闪屏IP协议同一DB-IP国家库,用户IP不发送给外部服务;使用结果的网页保留“IP Geolocation by DB-IP”署名。
网页在注册账号前新增“渠道”列,使用与服务端打包共用的渠道目录按当前界面语言显示名称,未知代码按原文显示,null显示四语“未记录”。新账号在验证码/三方身份成功验证、实际创建账号的同一事务记录渠道。历史账号字段为空时,后续合法登录、刷新或普通Bearer认证请求会补录本次渠道,后台下次读取即可展示;并发只保留首次成功写入,已有值不被后续换渠道覆盖。申请挑战、匿名或认证失败请求不补录,不按国家、手机号/邮箱或旧会话批量推测,注销清除渠道。补录值表示首次补获的自报渠道,不等于还原历史注册来源,完整规则见公共请求头。分页、排序、搜索和权限保持,暂不增加渠道筛选。
新版将昵称和注册账号分列:昵称未填显示“未设置”;注册账号独立展示完整手机号或邮箱,不受昵称是否填写影响。国内手机号注册显示手机号,海外邮箱注册显示邮箱,类型由实际已验证身份决定,不从可编辑国家资料或后台界面语言猜测。三方登录未提供手机号/邮箱时两个注册账号字段为null,不以三方openid/subject代替。
该投影仅供OWNER/VIEWER已授权后台查看,不能复用为App公开资料或写入日志;生日、会话、密码及支付引用不返回。多个手机号/邮箱身份按绑定时间、provider、subject稳定选择最早的一项。搜索仍只支持昵称或完整UUID,不扩展联系方式搜索。旧displayName仅用于兼容已打开页面,新页面必须使用nickname及两个独立注册账号字段。
网页有头像时通过受保护头像接口携带Cookie和八项元数据读取PNG;无头像或加载失败按male/female使用App正式默认头像,gender=null使用圆形Budyoo Logo。注册进度列仅显示简洁文字:INCOMPLETE显示registrationStep/4(如1/4),COMPLETE显示本地化“已完成”;不显示进度条,完成与否仍依据registrationStatus,不能把4/4当作完成。是否VIP按vipActive显示。列表只读,没有禁用/删除/导出操作。
页面顶部的今日注册、总数、男生、女生及未设置性别人数来自独立统计接口,分别显示五项,不复用本响应受筛选的total,口径与更新时间见该契约。点击任一卡片清空昵称/状态/注册状态并回到第一页,通过statistic读取对应账号;用户总数和重置恢复ALL。选中卡片亮黄描边并具有键盘与aria-pressed状态;随后查询可继续叠加其他条件,翻页、刷新保留已应用分类,未提交的搜索输入不影响分页。读取失败显示错误及未知总数,不在新分类下沿用旧列表。
网页右侧固定操作列提供“查看详情”,拥有ADMIN_USER_PROFILES_READ权限的管理员可打开只读弹窗。资料实时通过详细资料接口读取,沿用注册/编辑资料字段;查看不会提交修改,关闭后保留当前列表筛选和分页。
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | BAD_REQUEST/VALIDATION_FAILED | JSON、查询参数或字段校验失败 |
| 400 | INVALID_CLIENT_HEADERS | 元数据缺失/重复/不合法 |
| 400 | ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST | 缺少真实JWE或认证失败 |
| 401 | UNAUTHORIZED | 会话无效、失效、安装不匹配或误用App凭证 |
| 403 | FORBIDDEN/ADMIN_CSRF_INVALID | 权限不足、来源或CSRF不符 |
| 426 | HTTPS_REQUIRED | 通过HTTP发送后台请求 |
| 429 | TOO_MANY_REQUESTS | 来源IP或网关限流 |
| 503 | SERVICE_UNAVAILABLE | 持久存储或Redis依赖不可用 |
错误按四语公共协议返回,不泄露密码、Cookie或内部异常;无法解密前的错误没有加密响应上下文,不作为已认证业务结果。
接入说明¶
ipLocation的服务器隔离验证覆盖真实离线IPv4/IPv6及映射IPv6、资料国家独立、不同安装与同时间记录选择、90天窗口、最新未知不回退、无记录与注销清理、四语/VIEWER/匿名鉴权、分页校验、原始IP不泄露、管理员来源不影响结果及读取失败503。实际执行与发布结果见配套验收;运行库不注入合成访问记录。
registrationChannel隔离回归覆盖九个发行渠道、已有值不覆盖、旧账号在合法验证码/三方登录、Bearer访问和刷新时补录、旧NULL会话绑定、后台JWE读到补录值、资料/创建时间不变及并发首次写入。匿名、错误验证码/三方nonce、无效凭证、错误安装、非法渠道/平台、过期、撤销、禁用、注销及刷新重放均不得补录。V27迁移仍保留历史null;V30只更新字段COMMENT,不批量修改运行账号。服务器隔离回归汇总661项通过,包含18项补录专项,以及验证码/三方、会话、迁移和原业务用例;运行库不创建测试账号。
新增banned布尔字段表示当前有效账号运营处罚,独立于原status(ACTIVE/DISABLED/DELETED)生命周期。列表批量读取,不按设备型号推断封禁;IP及设备限制明细通过封禁详情查询。本字段随V20封禁功能配套,原资料/VIP/注册状态保持。
所有安全和会话约定见后台登录协议,权限由后端每次请求核验。正式凭证不通过未信任TLS链路发送。原有列表集成覆盖昵称与联系方式独立返回、已有昵称仍返回注册账号、手机号/邮箱及开发类型归一、三方联系方式为空且主体不泄露、最早身份选择、会员时效、100项分页、四语真实JWE、权限及未完成/禁用账号头像。新增渠道列的服务器TypeScript和网页构建通过;5项隔离JWE页面检查和12组四语×1440/390/320布局检查覆盖列顺序、九渠道名称、历史null/缺省、未知渠道、搜索空结果/重置及原分页参数。原头像、资料与媒体验收保持;后端渠道与迁移测试随V27/V28整合发布核验。会员有效状态以隔离库合成权益验收,未在运行库发放测试VIP。新增资料保存另有独立契约,接口已部署但网页资料编辑仍未接入;本列表只读。公共CA、管理员创建/角色编辑及用户禁用/删除仍待实现。