测试用户

测试用户用于把联调/演示账号与真实运营账号区分开：标记后用户列表显示徽标，并可用 ?testUser=true 过滤。标记本身不影响登录、收发消息或推送，也不产生计费；自托管版没有“测试额度/购买”概念。

概念​

  • 标记保存在应用级测试用户集合；同一用户重复标记幂等。
  • 配额默认 100，可通过接口改为 1–100000；超过上限返回 4xx（1001），不会静默忽略。
  • 列表接口返回 limitConfigured/limitDefault=100/limitMax=100000/usage。
  • 标记只用于运营区分；封禁、禁言、Token 等能力与普通用户完全一致。
不适用：测试套餐/计费

自托管版没有“测试版套餐”“试用额度”或按测试用户计费的流程；配额只是控制台自用的标记上限。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#testusers（tab #testusers：测试用户配额）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 查看当前标记与配额

    打开「测试用户配额」页或调用列表接口，确认 usage 与 limitConfigured。

  2. 标记/取消标记

    对目标 userId 传 {testUser:true|false}；用户不存在返回 1004。

  3. 调整上限

    按团队规模设置 limit；调低不会自动取消已标记用户，但新增标记会被拒绝。

  4. 在用户列表过滤

    用户列表传 ?testUser=true，只返回已标记用户。

参数表​

操作方法与路径请求体 / 参数
测试用户列表GET /api/admin/apps/{appkey}/test-userskeyword、offset、limit
标记/取消POST /api/admin/apps/{appkey}/users/{userId}/test-user{testUser}
设置上限POST /api/admin/apps/{appkey}/test-users/limit{limit}（1–100000）
用户列表过滤GET /api/admin/apps/{appkey}/users?testUser=true—

示例​

标记两个用户并把上限调到 200​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/bob/test-user" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"testUser":true}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/carol/test-user" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"testUser":true}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/test-users/limit" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"limit":200}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/test-users" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/users?testUser=true" \
  -H 'X-Admin-Secret: dev-admin'

常见问题​

标记测试用户会影响消息统计吗？​

不会。标记只是元数据；消息、DAU、在线等统计照常计入。

超过配额会怎样？​

标记接口返回 4xx（1001），已有标记不受影响；调高上限后可继续标记。

取消标记会删除用户吗？​

不会。只移除标记，用户与数据保留。

为什么用户列表过滤没有结果？​

确认 testUser=true 拼写；该过滤只匹配已标记用户，不会按昵称猜测。

相关链接​