CircleChat

主题

本文共 0 字
预计阅读 1 分钟

管理后台 ​

管理能力集中在管理面板 admin.html（由 AppAdmin 驱动），仅对 role=admin 开放，所有管理操作都受管理员角色限制，并写入审计日志（audit.add）。入口有服务端与前端两层限制：

  • 服务端鉴权：对 /admin.html 与 /js/admin.js 做鉴权，非管理员被 302 重定向到聊天页。
  • 前端拦截：main-admin.ts 再拦一道，role !== 'admin' 跳回聊天页。

管理面板分五个业务页签：审核 / 用户 / 治理 / 文件 / OAuth / 日志（对应源码卡片 Approvals / Users / Files / Logs / Moderation / OAuth）。

用户管理 ​

能力方法路径
用户列表GET/api/admin/users
新增用户POST/api/admin/user/add
删除用户POST/api/admin/user/del
重命名POST/api/admin/user/rename
改头像POST/api/admin/user/image
重置密码POST/api/admin/user/pass
  • 用户列表（GET /api/admin/users）：查看全部用户及状态——激活（active）/ 待审（pending）/ 封禁（banned）等。
  • 新增用户（POST /api/admin/user/add）：在面板直接建账号设密码；也可走命令行 npm run adduser -- <用户名> [新密码]，省略密码则交互式隐藏输入。
  • 删除用户（POST /api/admin/user/del）：移除用户，并清掉其消息、私聊、回应、群组、好友里的引用（在 auth.renameUser 同类的清理逻辑里做事务处理）。
  • 重命名（POST /api/admin/user/rename）：改用户名，在一个事务里同步 users / messages / dm / reactions / groups / friends 的全部引用。
  • 改头像（POST /api/admin/user/image）：设置用户头像（/uploads/...）。
  • 重置密码（POST /api/admin/user/pass）：为用户设置新密码，无需旧密码。

注册审核 ​

开放注册产生的账号先进入 pending，审核通过前无法登录。未过审（待审或被拒）的账号登录时返回 403 对应提示。

能力方法路径
待审列表GET/api/admin/approvals
通过POST/api/admin/review/approve
拒绝POST/api/admin/review/reject
  • 待审列表在「审核」页签。
  • 通过（POST /api/admin/review/approve）：账号激活，用户可登录。
  • 拒绝（POST /api/admin/review/reject）：账号被拒，无法登录。

举报与处罚 ​

能力方法路径
举报处理GET/api/admin/reports
驳回POST/api/admin/reports/dismiss
从举报执行处罚POST/api/admin/reports/punish
处罚记录GET/api/admin/penalties
撤销处罚POST/api/admin/penalties/revoke
新增处罚POST/api/admin/penalties/add
  • 举报处理（GET /api/admin/reports）：查看用户上报的举报，每条记录举报者 IP 与消息快照。可驳回（POST /api/admin/reports/dismiss）或从举报执行处罚（POST /api/admin/reports/punish，带 user / action / duration）。
  • 处罚类型：warning（警告）/ mute（禁言）/ ban（封禁）/ ipban（IP 封禁）。时长上限 MAX_DAYS = 3650 天；永久处罚 expires = null。
  • 处罚记录（GET /api/admin/penalties）：查看全部处罚，可撤销（POST /api/admin/penalties/revoke）；新增处罚走 POST /api/admin/penalties/add（user / action / duration）。
  • 自动通知：执行账号类处罚后，系统自动向被处罚用户写一条站内「通知」，并实时推 penalty WebSocket 消息，前端据此禁用输入框。
  • 服务端拦截：moderate.blockFor 计算 muted / banned / ipBanned 状态，发消息或建连时都会被拦。处罚状态由服务端计算，不是前端自判，无法绕过限制。

公告 ​

能力方法路径
发布公告POST/api/admin/announcements
删除公告DELETE/api/admin/announcements
  • 发布（POST /api/admin/announcements）：系统级公告，标题 + 内容，全员可见，出现在每用户信箱「公告」标签，返回新建 id。
  • 删除（DELETE /api/admin/announcements）：删已有公告，需带 id。

文件管理 ​

能力方法路径
查看文件GET/api/admin/files
删除单个POST/api/admin/file/del
批量删除POST/api/admin/files/del-batch
  • 查看（GET /api/admin/files）：已上传文件列表，可与 FILE_TTL_DAYS 保留策略配合查看哪些快过期。used 是被引用次数（0 就是没人引用），avatar 标记头像文件。
  • 删除单个 / 批量删除（POST /api/admin/file/del、/api/admin/files/del-batch）：请求体用落盘文件名（name / names），用 path.basename 比对防穿越。删除后同步去重记录，并把仍引用它的消息标记为「已过期」——聊天记录保留，只是打不开了。
  • 头像受保护：用户头像与群头像会被标记为「已引用」，不计入未引用文件、不参与过期清理，也不能在文件管理里删除（返回 api.admin.fileIsAvatar）。换头像请到该用户的资料或群设置里操作。这样能避免头像被当成垃圾文件清理掉、整站冒出空白头像。

操作日志 ​

  • 审计日志（GET /api/admin/logs）：分页查看审计 / 操作日志——登录、登出、发消息、上传、处罚、举报等活动，以及来源 IP。audit.list 支持按 actor / action / target / actionPrefix / excludeActions 过滤。detail 以结构化 {k: i18n键, v: 占位变量} 存储，前端按语言翻译；单条详情上限 300 字符，总容量 5000 条。
  • 访问日志：所有 HTTP 请求与 WebSocket 连接以 JSON 行写入 data/access.log，可配合外部日志系统（ELK / Loki 等）做更细的监控，不在管理面板内。

小程序 ​

「小程序」页签管理索引源：官方源 + 任意第三方源，平台启动时会合并加载一次（之后缓存 30 分钟，可手动「保存并刷新」）。

  • 每条源可配名称、索引地址、优先级、启用开关；官方源优先级最高且不可删除（可停用）。
  • 「各源状态」会显示这次加载是否成功、拿到几个小程序、耗时，失败时直接给出原因（超时 / 404 / JSON 解析失败等）。
  • 用户在聊天页侧栏「+ → 小程序商店」自行安装，装到个人（侧栏入口）或某个群（#指令 调用）；安装时勾选的权限由后端逐次校验。
  • 管理侧只管「有哪些小程序可用」，不参与授权；相关日志在「日志」里按「小程序」类别筛选。

详见小程序 · 部署者指南。

OAuth 配置 ​

能力方法路径
管理 OAuthGET/POST/api/admin/oauth
用户侧 providersGET/api/oauth/providers
用户侧 meGET/api/oauth/me
用户侧 unbindPOST/api/oauth/github/unbind
  • 管理侧：管理面板「OAuth」页签管理 GitHub 登录账号，GET/POST /api/admin/oauth 读写 GitHub 的 client_id / client_secret，secret 存 app_config，永不下发前端。
  • 用户侧流程：GET /api/oauth/providers 查看可用 Provider、<start> 跳转授权、<callback> 回跳绑定、GET /api/oauth/me 查看绑定状态、POST /api/oauth/github/unbind 解绑（<start> / <callback> 为占位表示）。

依赖命令行 ​

命令作用
npm run adduser -- <用户名> [新密码]新增 / 重置用户密码（服务端命令行，适合无界面时批量建号）

相关文档 ​

基于 GPL-3.0 开源

Copyright © 2026 CircleChat Team