深度剖析Warpdrive技术架构:Next.js + tRPC + Postgres如何撑起一套实时CRM
深度剖析Warpdrive技术架构:Next.js + tRPC + Postgres如何撑起一套实时CRM
Warpdrive 是一款开源、可自托管的实时 CRM(Pipedrive 开源替代方案),面向商务拓展团队提供 Pipeline 看板、客户管理与双向 Gmail 同步。本文带你深度剖析 Warpdrive 的技术架构,看懂它如何用 Next.js + tRPC + Postgres 这套组合,撑起看板拖拽秒级同步、收件箱实时更新等实时协作能力——全程无需重型中间件,一台服务器即可跑起来。
🧩 一张表看懂 Warpdrive 的完整技术栈
Warpdrive 的选型思路很清晰:能用 Postgres 原生能力解决的,就不引入额外组件。
| 层次 | 技术选型 | 承担的角色 |
|---|---|---|
| 框架 | Next.js (App Router) + React + TypeScript | 页面渲染、API 路由 |
| 读取(读) | tRPC + TanStack Query | 类型安全的查询接口 |
| 写入(写) | Next server actions | 带 CSRF 防护的变更操作 |
| 数据库 | Postgres + Drizzle ORM | 全部关系型数据 + 实时事件总线 |
| 实时推送 | 自建 WebSocket 服务 + Postgres LISTEN/NOTIFY |
看板/收件箱/通知实时刷新 |
| 后台任务 | pg-boss | 邮箱同步、CSV 导入、定时发送 |
| 对象存储 | Garage(S3 兼容) | 文件附件 |
| UI 层 | shadcn/ui + Tailwind、dnd-kit | 看板拖拽与交互 |
完整说明见官方架构文档:docs-site/docs/architecture.md。
📡 读路径:tRPC 如何做到"类型从服务端流到浏览器"
Warpdrive 把所有只读请求收口到 tRPC。在 src/server/trpc/root.ts 中,appRouter 聚合了 21 个领域路由器:pipeline、deal、contacts、email、activities、search、stats……每个功能模块在自己的目录里定义 router,最后统一挂载。
几个值得新手学习的设计点:
- 鉴权内建:
protectedProcedure(src/server/trpc/trpc.ts)在每个请求入口校验会话,未登录直接返回稳定错误码E_AUTH_003; - 上下文只算一次:src/server/trpc/context.ts 用
React.cache包裹会话解析,同一请求里布局、子布局、页面共享一次用户信息加载,避免重复查库; - SSR 预取复用同一套类型:
createCaller让服务端组件在渲染时就调用 tRPC 过程预取数据,客户端拿到的类型与服务端完全一致(见 src/lib/trpc-client.ts)。
✍️ 写路径:server actions + "结果优先"的错误处理
写操作没有走 tRPC,而是交给 Next server actions。以编辑 Pipeline 为例(src/features/pipelines/pipelineEditActions.ts),每个 action 的执行顺序固定:
- 先过 CSRF 防护,再解析当前用户与权限;
- 输入用 zod schema 校验——外部数据在"边界处"只校验一次,进入程序内部后信任推断类型;
- 失败不抛异常,而是返回可辨识联合类型(
{ ok: true, value }或{ ok: false, error: { id } }),批处理中单个失败不会拖垮整批。
这个"结果优先(Results over throws)"的约定,加上贯穿始终的 AbortSignal 取消信号,是 Warpdrive 处理长任务(如同步多个邮箱)不堆积、可中止的关键。
⚡ 实时核心:Postgres LISTEN/NOTIFY + WebSocket 三件套
这是全文最值得细看的部分。整个实时系统没有 Redis、没有消息队列,事件总线就是 Postgres 本身,分三步走:
第 1 步:写库和发事件在同一个事务里。 任何业务写入(比如移动一笔交易)都会调用唯一的发布入口 src/server/notify.ts:先原子地给该通道版本号 +1(channel_versions 表),再执行 pg_notify(通道名, 事件JSON)。事务回滚则事件不发,前端绝不会出现"收到通知但数据没变"的幽灵状态。
第 2 步:独立的 WebSocket 服务监听数据库。 部署中的 ws 进程持有一条专用 Postgres 连接(src/server/ws/relay.ts),某个通道有订阅者就 LISTEN,最后一个订阅者离开就 UNLISTEN。数据库事件是唯一的转发来源,客户端发来的消息永远不当事件转发,从根上杜绝伪造推送。
第 3 步:浏览器端单连接多路复用。 每个浏览器标签页只开一条 WebSocket 连接(而非每个组件一条),由 src/server/ws/server.ts 按通道分帧下发,服务端在每帧上加盖序号(seq)保证顺序与去重。连接本身也有安全边界:tRPC 的 realtime.ticket 接口先签发一次性票据(src/server/trpc/routers/realtime.ts),并对连接数、消息大小设置了硬性上限。
效果就是:同事拖动看板卡片,你的看板、收件箱、通知铃铛、在线状态几乎同时就地更新,无需刷新页面。
🎯 拖拽不串数据:乐观并发的"比较并交换"
实时系统最怕并发写冲突。Warpdrive 的看板拖拽(src/features/deals/dealMove.ts)用了一个数据库层面的经典技巧——CAS(Compare-And-Swap):
- 客户端拖动卡片时会带上"我读到的
updated_at时间戳"; - 服务端执行
UPDATE ... WHERE updated_at = 期望值的单条原子语句; - 影响行数为 0 就说明别人抢先改过了,直接返回
DEAL_PRECONDITION错误,让前端重试,而不是覆盖他人修改。
改动、变更审计日志、实时事件发布,三者全部在同一个数据库事务中提交——要么全成,要么全不成。
🗄️ 数据层:Drizzle ORM + JSONB 自定义字段
- 全部表结构由 Drizzle ORM 定义(src/db/schema/),迁移 SQL 以 78 个版本文件形式固化在 drizzle/ 目录,
migrate一次性容器在应用启动前自动应用; - 自定义字段存 JSONB 而非新加列:管理员在界面上加一个字段,数据库零 schema 变更——这是 CRM 类产品"字段随便加"体验的底层支撑;
- 应用、WS、worker 三个进程共享同一个连接池(src/db/client.ts),行为一致;
- 集成测试永远跑在真实 Postgres 上(Testcontainers 起临时库,从不 mock),因为"迁移写坏了 mock 测不出来"正是 CRM 最不能接受的事故。
🏗️ 部署拓扑:一台机器上的 5+2 个进程
看 docker-compose.yml 就能理解整个运行时。docker compose up -d --build 之后,单机上跑着:
| 服务 | 职责 |
|---|---|
app |
Next.js 主应用 |
ws |
WebSocket 实时服务器 |
worker |
pg-boss 后台任务:邮箱同步、CSV 导入、定时发送、文件清理 |
postgres |
全部数据 + 事件总线 |
garage |
S3 兼容文件存储 |
migrate / storagecors |
一次性任务:迁移数据库、配置存储桶 CORS |
生产环境由 Caddy 统一反代并自动签发 HTTPS。这里有个运维要点:后台任务的执行器只在 worker 进程里注册(src/server/worker.ts)——如果导入任务"卡住"了,多半是 worker 没在跑,而不是业务逻辑挂了。
配置方面,src/config/env.ts 是全项目唯一读取 process.env 的模块,启动时用 zod 校验、配置错误直接拒绝启动,lint 规则禁止其他文件裸读环境变量——配置问题在启动时就暴露,而不是运行到一半才炸。
📁 代码组织:按功能而非按层分目录
src/
features/<feature>/ 实现 + 类型 + 校验 + 测试,全部同目录
components/ui/ shadcn 设计系统封装
constants/ 命名常量(含错误码注册表)
config/env.ts 唯一环境变量入口
app/ Next.js 路由
每个功能(如 features/deals/、features/email/)把业务实现、zod 校验、tRPC router、server actions 和测试装进同一个目录,理解一个功能不需要跨五个目录翻文件。配套约定(边界校验、稳定错误码 E_<DOMAIN>_<NNN>、取消信号透传)由 lint 规则强制执行,而不靠口头约定。
📚 延伸阅读
- 官方架构文档:docs-site/docs/architecture.md
- 自托管部署指南(含 Google OAuth 配置):docs/deploy.md
- MCP 服务器能力说明:docs/mcp-server.md
- 邮箱同步功能文档:docs-site/docs/administration/email-sync.md
总结
Warpdrive 的架构给自托管项目提供了一个很好的参考范本:读走 tRPC、写走 server actions、实时靠 Postgres LISTEN/NOTIFY、并发靠事务内 CAS——用四个"够用且原生"的机制,就换来了拖拽秒同步、多进程可横向分工的实时 CRM 体验,而且全部代码和类型对开发者开放可查。如果你想给自己的产品加一套轻量实时能力,这条"Postgres 即事件总线"的路径非常值得抄作业。



