GET/api/v1/admin/users
管理员Cookie,ADMIN_USERS_READJSON 响应接入指南 ↗

查询用户账号列表

请求参数

仅后台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、管理员创建/角色编辑及用户禁用/删除仍待实现。