CircleChat

自托管的轻量多人聊天服务器。单进程部署，支持群组 / 私聊，含好友关系、开放注册审核、在线状态、消息撤回、表情回应、举报处罚与审计日志。服务端零第三方运行时依赖。基于 GPL-3.0 开源。

环境要求

• Node.js ≥ 22.5（使用内建 node:sqlite，低版本会启动崩溃）
• 运行时自动生成 data/、public/uploads/

快速开始

npm install      # 首次安装前端构建依赖（仅构建期需要）
npm run build    # 构建前端与后端
npm start        # 启动服务，默认监听 0.0.0.0:8090

浏览器访问 http://服务器IP:8090，根路径 / 自动跳转登录页。

生产环境建议经 Nginx 反向代理并启用 HTTPS（WebSocket 升级需 Upgrade / Connection 头透传）。

常用命令

命令	作用
npm install	安装依赖（首次，或依赖变更后）
npm run build	构建前端（Vite）与后端（Nitro）
npm start	启动生产服务（默认 0.0.0.0:8090）
npm run dev	开发模式：监听 src/ 增量构建 + 启动后端（Nitro dev），改代码即时生效
npm run typecheck	类型检查（前端 vue-tsc + 后端 tsc，与 CI 一致）
npm run adduser -- <用户名> [新密码]	用户管理：新增用户或重置密码

CI：.github/workflows/lint.yml 在 push / PR 时执行 npm run typecheck。

分支与协作

• main：默认 / 稳定分支，用于发布；生产服务器从 main 拉取部署。
• dev：日常开发分支，功能完成后再合并回 main。

git checkout dev                 # 日常在 dev 上开发、提交
git push                         # 推送 dev

# 发布：把 dev 合入 main 并推送（服务器据此部署）
git checkout main && git merge dev && git push

远端名为 CircleChat（可用 git remote -v 查看）。

更新服务器

推送到 main 后，在部署机上按顺序执行：

git pull            # 同步源码
npm install         # 仅当 package.json / package-lock.json 有变动时需要
npm run build       # 构建前端（Vite）与后端（Nitro）
# 重启服务进程 / 容器

也可以用远端仓库的 post-receive 钩子把上面几步自动化——钩子同步源码后可继续执行 npm install（依赖有变动时）、npm run build 并重启服务。

两个容易踩的坑：

1. 构建请用与服务运行时相同（或更高）的 Node 版本，vite build 需要 Node ≥ 20.19；
2. 旧版 npm（如 9.x）会在 npm install 时改写 package-lock.json（例如删掉 libc 字段）， 使部署机的 git pull 因工作区不干净而中止。建议升级 npm，或让部署目录只做 git fetch + git reset --hard（部署目录不应存在本地改动）。

配置

项	方式
监听端口	PORT=8080 npm start（默认 8090；由 .output/server/index.mjs 监听）
上传保留天数	FILE_TTL_DAYS=30 npm start（默认 15 天）
显示 / 请求地址分离	编辑 public/js/config.js 的 apiBase / displayBase（无需重新构建）

public/js/config.js 支持三种部署：同源（两项留空）、反代子路径（apiBase: '/chat'）、跨域（apiBase: 'https://api.example.com'）。

内置账号

首次启动若用户表为空，自动创建管理员 admin / Admin1234，部署后请尽快改密。老库升级自动补建 admin 且不覆盖任何已有密码。

安全与数据

• 密码 SHA256 加盐存储；HttpOnly 会话 Cookie（7 天）；同 IP 登录限速（5 次失败锁 10 分钟）。
• 上传类型白名单 + 图片魔数校验 + 路径穿越防护，单文件上限 100MB（服务端 MAX_UPLOAD，前端 MAX_UPLOAD_SIZE，两处需一致）。
• 每个房间保留最近 500 条消息，持久化于 data/chatplus.db（SQLite）。
• 所有 HTTP 请求与 WebSocket 连接写入 data/access.log（应用层网络监控）。
• 后端核心模块位于 server/lib/（Nitro 版，由原 server.js + lib/ 整体迁移而来），修改后端前请谨慎。
• 公共频道功能已移除，以「群组为主」；服务端房间模型仍保留群聊 / 私聊两类。

目录结构

CircleChat/
├── nitro.config.ts        # Nitro 配置（node-server 预设；serveStatic:false，静态由内部 serveStatic 服务）
├── tsconfig.json          # 前端类型检查（vue-tsc，覆盖 src/）
├── tsconfig.server.json   # 后端类型检查（tsc，覆盖 server/lib/）
├── server/
│   ├── lib/     # 后端模块（原 server.js + lib/ 的 1:1 迁移）：runtime/auth/store/groups/friends/ws/moderate/audit/log/migrate
│   ├── routes/  # routes/[...].ts 全量兜底路由，把请求转交 runtime.handleHttp
│   └── plugins/ # bootstrap（启动初始化）、ws（WebSocket 升级）
├── tools/       # adduser.ts（用户管理）、hljs-entry.mjs（highlight.js 打包入口）、security-test.js（安全自检）
├── src/         # 前端源码（Vue3 + TS）：main-{login,chat,group,admin}.ts、components/、core/、i18n/
├── public/      # 页面壳、js/config.js、dist/ 构建产物、css/、vendor/（本地自托管 highlight.js）
├── .github/     # workflows/lint.yml（CI：类型检查）
├── .output/     # Nitro 构建产物（node-server）：server/index.mjs
└── data/        # 运行时生成：chatplus.db、access.log

致谢 / 第三方资源

• 音效（收发消息提示音）来自 Pixabay，作者 universfield。
• 代码高亮使用 highlight.js（BSD-3-Clause，本地自托管）。

完整的第三方资源与许可列表见 CREDITS.md。

许可证

本项目以 GNU GPL v3.0 开源。使用、复制、修改与分发请遵守 GPL-3.0 条款；再分发时须附带本许可证并保留许可声明。本项目按「原样」提供，不提供任何担保。