Haven 自托管聊天应用架构剖析:Express、Socket.IO 与 better-sqlite3 如何撑起 1000+ 测试用例

原创2026-10-29 12:48:341,427 阅读

Haven 自托管聊天应用架构剖析:Express、Socket.IO 与 better-sqlite3 如何撑起 1000+ 测试用例

Haven 是一个跑在你自己机器上的自托管私有聊天应用,一个无需云服务的 Discord 替代品:没有遥测、没有公司账号、没有付费墙。它的服务端由三块基石组成——Express 负责 HTTP 路由与静态资源,Socket.IO 承载聊天、语音等实时事件,better-sqlite3 把所有数据落到单个 haven.db 文件里。三者配合,让这个聊天应用稳定运行在 211 个测试文件、1000+ 测试用例的守护之下。

Haven 聊天界面截图:左侧频道列表,中间消息流,右侧成员列表


一张图看懂整体架构

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(...) 事件绑定,全部注册在这套工厂模式之下。

这种"工厂 + 注册表"结构带来两个好处:

  1. 可独立测试——模块通过参数注入 db 和依赖,测试时无需启动完整服务器也能验证逻辑;
  2. 内存状态集中管理——频道成员、语音用户、音乐播放等运行时状态都是工厂函数内的 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 定期校对,保证索引永不漂移。

Haven 屏幕共享功能截图:多人在同一频道观看共享画面

650+?不,是 1000+ 测试用例如何守护这个架构

标题里的"650+"只是保守说法。test/ 目录下有 211 个测试文件,累计 1000+ 个 test()/it() 用例,全部使用 Node.js 原生测试运行器:

npm test        # 即 node --test --test-concurrency=1

测试分两类,各有分工:

这种"真刀真枪起整个服务器"的集成策略,恰好能覆盖 Express、Socket.IO、SQLite 三层的交互路径——这也是自托管软件最该被测试的地方:用户升级后一切照常。

Haven 主题切换面板截图:内置多种主题与实时预览

小结:小依赖,大工程

回头看 package.json 的依赖清单:核心运行时只有 express、socket.io、better-sqlite3 三个,外加 helmet、jsonwebtoken、bcryptjs、multer 等安全与工具类库。没有 ORM、没有 Redis、没有消息队列——这正是它的架构哲学:

  1. Express 管"进来的请求",Socket.IO 管"留住的连接",两者共享同一套 db 与权限助手,登录态用 JWT 贯通;
  2. better-sqlite3 用 WAL + 语句缓存 + 内存硬上限,在单文件里扛住整个聊天世界,且把 secure_delete 这类隐私开关交给用户自己;
  3. 1000+ 测试用例(211 个文件)用原生 node --test 守护三层交互,其中集成测试直接启动完整服务器,确保"升级不断服"。

对想学习自托管应用架构的开发者来说,Haven 值得逐行读的地方不在某个大文件,而在那些把事故、权衡和调优原因写进注释的代码段——从 server.js 的陈旧文件守卫,到 src/database.js 的语句缓存,再到 test/socketServerHarness.js 的测试台设计,每一步都能看出"为真实用户环境服务"的思路。

登录后查看全文
Haven