Haven 自托管聊天应用架构剖析:Express、Socket.IO 与 better-sqlite3 如何撑起 1000+ 测试用例
Haven 自托管聊天应用架构剖析:Express、Socket.IO 与 better-sqlite3 如何撑起 1000+ 测试用例
Haven 是一个跑在你自己机器上的自托管私有聊天应用,一个无需云服务的 Discord 替代品:没有遥测、没有公司账号、没有付费墙。它的服务端由三块基石组成——Express 负责 HTTP 路由与静态资源,Socket.IO 承载聊天、语音等实时事件,better-sqlite3 把所有数据落到单个 haven.db 文件里。三者配合,让这个聊天应用稳定运行在 211 个测试文件、1000+ 测试用例的守护之下。
一张图看懂整体架构
Haven 的架构可以概括为"一个进程、两条通道、一层存储":
| 层 | 技术 | 职责 |
|---|---|---|
| HTTP 层 | express + helmet | REST API(/api/...)、静态页面、上传、鉴权 |
| 实时层 | socket.io | 收发消息、语音信令、在线状态、打字指示 |
| 存储层 | better-sqlite3 + 本地/S3 文件 | haven.db 数据库 + uploads/ 媒体目录 |
所有代码都围绕根目录的 server.js 展开:入口文件完成 Node 版本检查、.env 引导、密钥自动生成,然后组装这三层。
Express:一条轻量而"加固"过的 HTTP 管道
Express 实例在 server.js 创建,随后依次挂上安全中间件。几个值得新手注意的细节:
- 安全头由 helmet 统一兜底:CSP、Referrer-Policy 等头在 server.js 处集中配置,管理员还能在面板里调整策略。
- 自动生成长期密钥:首次启动时若
.env里没有JWT_SECRET,server.js 会自动生成一个 48 字节随机密钥并写回文件(权限收紧到0600),同时用 web-push 生成 VAPID 推送密钥——零配置就能安全地跑起来。 - 磁盘守卫:上传前会检查剩余空间(src/diskGuard.js),防止磁盘写满后管理员连删除文件都做不到。
- HTTP→HTTPS 重定向服务器:启用 TLS 后,还会额外起一个限流的重定向服务器(server.js),并做了防开放重定向的 URL 消毒。
Socket.IO:把"聊天"做成 287 个事件的注册表
实时交互是整个应用的核心。Socket.IO 服务器在 server.js 创建,配置刻意收紧:
cors: { origin: false } // 仅同源连接
maxHttpBufferSize: 64 KB // 单条消息上限
pingInterval: 25000 // 心跳
真正的事件逻辑不在 server.js 里,而是拆分到了 src/socketHandlers/ 目录的 30 多个模块中:channels、messages、voice、roles、moderation、admin……每个模块导出一个 register* 函数,由 src/socketHandlers/index.js 中的 setupSocketHandlers(io, db, opts) 统一装配(调用点在 server.js)。全目录累计约 287 处 socket.on(...) 事件绑定,全部注册在这套工厂模式之下。
这种"工厂 + 注册表"结构带来两个好处:
- 可独立测试——模块通过参数注入
db和依赖,测试时无需启动完整服务器也能验证逻辑; - 内存状态集中管理——频道成员、语音用户、音乐播放等运行时状态都是工厂函数内的
Map(见 src/socketHandlers/index.js),避免散落在各模块里难以回收。
better-sqlite3:单文件数据库的性能与隐私调校
数据库初始化在 src/database.js,打开 haven.db 后先做了一组非常"聊天应用化"的调参:
journal_mode = WAL // 写日志模式,并发读不阻塞写
synchronous = NORMAL // WAL 下安全且快 2-3 倍
cache_size = -8000 // 8 MB 页缓存(从 64 MB 降下来)
secure_delete = ON // 删除的行用零覆盖,杜绝事后从 db 里"恢复"消息
soft_heap_limit = 32 MB // 硬性限制 SQLite 堆内存
注释里写得很直白:早期 64 MB 缓存 + 256 MB mmap 的组合会在桌面端吃掉约 320 MB 原生内存,直接触发了 Oilpan OOM 崩溃。这正是自托管项目常见的权衡——为家用机器而不是数据中心调性能。
另一个亮点是预编译语句缓存(src/database.js):拦截 db.prepare(),相同 SQL 字符串复用同一个 Statement 对象。原因同样写在注释里——socket 事件里高频 prepare 会让 V8 GC 来不及回收原生对象。这种把真实线上事故写进注释的风格,本身就是很好的架构教材。
数据模型也值得一提:src/database.js 中用 CREATE TABLE IF NOT EXISTS 定义了 users、channels、messages、roles、webhooks 等几十张表,并配套了一整套幂等迁移函数(hasColumn/addColumn,src/database.js),保证旧库升级不会失败。
媒体文件去哪了?一个可插拔的存储层
消息在 SQLite 里,但图片、语音文件在磁盘上。src/storage/index.js 用驱动模式做了隔离:默认是 LocalStorage(本地 uploads/ 目录),设置 HAVEN_EXTERNAL_STORAGE=true 即切换到 S3Storage。所有文件的读写、移动、删除都走同一个入口,并同步维护 media_objects 索引,由 src/storage/reconcile.js 定期校对,保证索引永不漂移。
650+?不,是 1000+ 测试用例如何守护这个架构
标题里的"650+"只是保守说法。test/ 目录下有 211 个测试文件,累计 1000+ 个 test()/it() 用例,全部使用 Node.js 原生测试运行器:
npm test # 即 node --test --test-concurrency=1
测试分两类,各有分工:
- 纯逻辑单测(如 test/discordText.test.js):不启动服务器,直接 require 模块验证渲染、权限计算等纯函数;
- 集成测试(文件名带
integration,如 test/kickLeavesVoice.integration.test.js):由共享测试台 test/socketServerHarness.js 在临时端口上 spawn 一个真实的server.js进程,注册账号、连接socket.io-client、等待事件,测完自动清理临时数据目录。
这种"真刀真枪起整个服务器"的集成策略,恰好能覆盖 Express、Socket.IO、SQLite 三层的交互路径——这也是自托管软件最该被测试的地方:用户升级后一切照常。
小结:小依赖,大工程
回头看 package.json 的依赖清单:核心运行时只有 express、socket.io、better-sqlite3 三个,外加 helmet、jsonwebtoken、bcryptjs、multer 等安全与工具类库。没有 ORM、没有 Redis、没有消息队列——这正是它的架构哲学:
- Express 管"进来的请求",Socket.IO 管"留住的连接",两者共享同一套
db与权限助手,登录态用 JWT 贯通; - better-sqlite3 用 WAL + 语句缓存 + 内存硬上限,在单文件里扛住整个聊天世界,且把
secure_delete这类隐私开关交给用户自己; - 1000+ 测试用例(211 个文件)用原生
node --test守护三层交互,其中集成测试直接启动完整服务器,确保"升级不断服"。
对想学习自托管应用架构的开发者来说,Haven 值得逐行读的地方不在某个大文件,而在那些把事故、权衡和调优原因写进注释的代码段——从 server.js 的陈旧文件守卫,到 src/database.js 的语句缓存,再到 test/socketServerHarness.js 的测试台设计,每一步都能看出"为真实用户环境服务"的思路。


