封禁用户

封禁用户页把“账号处置”从用户资料里独立出来：支持封禁、解封、注销、恢复四种动作，记录原因、时长与操作者，并由维护周期到期自动解封。封禁/注销会立即踢下线，后续建连与 Open API 调用返回 1016。

概念​

动作写入状态效果
banUser.banned踢下线（kick 1016）；建连/发消息被拒；durationSec 到期自动解封
unbanUser.banned=false立即恢复；旧 Token 仍有效（除非同时 reset）
deactivateUser.deactivated注销视图；与封禁同级的拒绝语义
restoreUser.deactivated=false恢复注销账号
  • 封禁历史为内存环缓冲，上限 2000 条；到期自动解封会写一条 action=expire 记录。
  • 列表支持三种视图：status=active（生效中）、history（历史）、all。
  • 所有动作都写操作日志（admin.bans.apply），可在「操作日志」按 action 过滤。
  • 用户级禁言（mutedUntil）不是封禁，见「用户管理」。
历史不落独立库

封禁历史保存在内存环缓冲，进程重启后只保留随服务端快照持久化的部分；需要长期留存请在动作发生后同步到自有审计库。

前置条件​

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

步骤​

  1. 确认对象与原因

    按 keyword 搜索用户，确认 userId；填写可追溯的 reason 与 operator。

  2. 选择动作与时长

    临时封禁传 durationSec；永久封禁省略。注销用于账号级终止，恢复用于误操作回滚。

  3. 验证生效

    查看「生效中」列表；被处置用户建连应失败，在线连接应被踢下线。

  4. 到期/申诉处理

    到期由维护周期自动解封；提前解封调用 action=unban。

  5. 对账审计

    在「操作日志」过滤 action=admin.bans.apply，核对操作者、对象与结果。

参数表​

操作方法与路径请求体 / 参数
封禁视图GET /api/admin/apps/{appkey}/bansstatus（active/history/all）、keyword、offset、limit
执行动作POST /api/admin/apps/{appkey}/bans{userId,action,reason?,durationSec?,operator?}
用户侧封禁POST /api/admin/apps/{appkey}/users/{userId}/ban{banned,reason?}（等价布尔开关）

示例​

封禁 1 小时 → 查看生效 → 提前解封​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/bans" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"userId":"dave","action":"ban","reason":"骚扰","durationSec":3600,"operator":"ops-zhang"}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/bans?status=active&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/bans" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"userId":"dave","action":"unban","reason":"申诉通过","operator":"ops-zhang"}'

注销与恢复​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/bans" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"userId":"erin","action":"deactivate","reason":"用户申请注销"}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/bans?status=history&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/bans" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"userId":"erin","action":"restore","reason":"误操作回滚"}'

常见问题​

封禁和注销有什么区别？​

两者都拒绝建连与调用，但状态字段不同（banned vs deactivated），语义上前者是可到期解除的处罚，后者是账号终止。

封禁到期会自动解封吗？​

会。维护周期（IM_MAINTENANCE_MS，默认 5s）检查到期并写 expire 历史。

为什么历史记录少了？​

历史是 2000 条环形缓冲，超出淘汰最旧记录；长期留存请自行落库。

封禁后还能收发历史消息吗？​

不能。封禁作用于连接与接口鉴权层，客户端无法建连；解封后历史仍在。

相关链接​