常见问题与排错

部署与使用 CircleChat 时最常碰到的问题，按主题归类。相关依据见 配置说明 与 生产部署。

部署与构建

构建报错 / 启动崩溃，提示 node:sqlite 不可用

后端依赖 Node.js 内建的 node:sqlite，需要 Node ≥ 22.5。版本过低，进程一启动就会崩。用 node -v 确认版本。前端打包（vite build）则只需 Node ≥ 20.19。

构建机版本和生产机版本不一致

如果构建用的 Node 比运行时低（尤其 < 20.19），前端产物可能在低版本 Node 上跑不起来。构建请用与服务运行时相同或更高等的 Node 版本。

git pull 中止，提示工作区不干净

旧版 npm（如 9.x）在 npm install 时会改写 package-lock.json（常见是删掉 libc 字段），导致部署目录出现未提交改动，git pull 因此中止。两个办法：

• 升级 npm 到较新版本；
• 或让部署目录只做 git fetch + git reset --hard（部署目录本就不该有本地改动，所有改动走 main 推送）。

实时消息收不到 / 一直重连

WebSocket 必须能升级。如果走了反向代理，务必透传 Upgrade 和 Connection 两个头（见 生产部署 · 反向代理）。漏掉它们，连接会建立后立刻断，或者收不到推送。另外进程重启后内存会话清空，前端检测到会话失效会直接跳登录页而不是无限重连——这是预期行为。

登录与账号

注册后无法登录

开放注册提交后是 pending（待审核）状态，管理员在 管理后台 · 注册审核 通过前不能登录。登录接口对未激活 / 已拒绝账号返回 403 类提示。

登录一直返回限速

同 IP 连续失败 5 次会被锁 10 分钟，期间再试直接 429。等 10 分钟，或换 IP / 清掉限速计数（重启服务会清空内存中的失败记录）。

开了两步验证却登不进

开了 TOTP 后，第一次登录只回挑战码（need2fa: true），还要拿 6 位动态码去 /api/twofa/verify 校验才建会话。挑战码有效期 5 分钟。

忘了管理员密码

用命令行重置：npm run adduser -- admin <新密码>。首次启动、用户表为空时会自动建 admin / Admin1234，生产环境务必尽快改掉。

数据与容量

为什么每个房间只保留 500 条消息

这是运行期常量 MAX_MESSAGES = 500，每个群 / 每对私聊独立裁剪，超出部分从库里删除，避免单表无限膨胀。历史更久的消息需要通过 聊天记录搜索 按关键字检索（只搜文本）。

上传的文件会一直保存吗

不会。上传文件按 FILE_TTL_DAYS（默认 15 天）过期清理硬盘文件，消息记录保留并标 file_expired，不会变成乱码。相同内容按 sha256 去重，只落盘一次。

数据存在哪

data/chatplus.db（SQLite，单文件）和 data/access.log（访问日志），上传在 public/uploads/。备份时把这两个目录拷走即可，拷贝前最好停服或确保没有写入。

上传与文件

上传失败 / 报 413

单文件上限 100MB，分片每片 5MB。小于 5MB 走单次上传；大于 5MB 走分片续传。超限（单文件 > 100MB、分片 > 上限、文本 > 4096 字符）会返回 413。

某些文件被拒

上传做类型白名单 + 图片魔数嗅探 + 路径穿越防护。伪装成图片的非图片内容会被降级存成 .bin。非白名单或伪造路径会被拒。

网络与地址

反向代理挂在子路径下怎么配

把 Nginx 的 location /chat 转发到后端，并把前端 public/js/config.js 的 apiBase 设为 /chat（详见 配置说明 · 显示 / 请求地址分离）。

前后端不同域（跨域）部署

apiBase 填完整 API 域名（如 https://api.example.com），WebSocket 也按 apiBase 连。确保反代 / CORS 放行。

性能与监控

怎么监控访问

所有 HTTP 请求与 WebSocket 连接都会以 JSON 行写入 data/access.log，可接 ELK / Loki 等做监控。审计类操作（登录、发消息、处罚等）还会进 管理后台 · 操作日志，按动作 / 操作人过滤。

内存占用高吗

单进程设计，目标页面加载 1 秒内，内存占用低。会话、限速计数、在线状态都在内存里，重启会清空（所以重启后已登录用户需要重新登录）。