Doca 架构深度解析:TypeScript 插件化单体的设计取舍与模块边界
Doca 架构深度解析:TypeScript 插件化单体的设计取舍与模块边界
Doca 是一个开源的文档管理与知识库系统,支持多人实时协同编辑、在线文档、Markdown、表格、幻灯片、画布和 AI 助手。它采用 TypeScript 插件化单体(Modular Monolith)架构:一个可部署单元,内部却按插件化思想划清模块边界。本文带你从目录分层、插件生命周期到"把架构规则写进测试",完整拆解这套设计背后的取舍。
一、为什么先做单体,而不是微服务
Doca 的官方架构文档开篇就定性:"Doca 是一个 TypeScript 模块化单体"(docs/architecture.zh-CN.md)。这个定位直接决定了它的第一条取舍:用单进程换取部署简单与跨领域一致性。
- 单实例零额外依赖:默认模式下,SQLite 单文件 + 本地上传目录 + 进程内实时总线即可跑起完整功能,个人和小团队开箱即用。
- 跨领域事务容易:账号、文档、文件、搜索、AI 在同一个进程里,权限复查、历史版本、知识索引可以共享数据库事务,不必为"分布式一致性"买单。
- 升级路径保留:需要水平扩展时,才引入共享 PostgreSQL + Redis + S3 对象存储,两种模式共用同一套业务协议(docs/horizontal-scaling.zh-CN.md)。
代价也很直白:单进程隔离能力弱。比如插件目前运行在可信的服务端进程内,"这是扩展接口边界,不是 Node.js 安全沙箱";更强进程隔离仍列为待交付项(docs/plugin-sdk-contract.zh-CN.md)。对内部团队工具,这是典型的"先简单、后扩展"取舍。
二、单体之内:pnpm Workspace 如何分层
Doca 是一个 pnpm Workspace monorepo(pnpm-workspace.yaml),apps/* 放可运行应用,packages/* 放可复用包:
| 层 | 代表包 | 职责 |
|---|---|---|
| 前端应用 | apps/web |
React 19 + Vite 工作台,按 features/ 组织功能 |
| 后端应用 | apps/server |
Fastify 路由、会话与安全边界、服务 |
| 核心领域 | packages/core | 领域规则、授权、事务 |
| 数据库 | packages/db | 建库与启动对账共用的目标 DDL |
| 插件契约 | packages/plugin-contracts | manifest 与生命周期校验 |
| 插件宿主 | packages/plugin-host | 依赖图校验、启动与逆序销毁 |
| 公开 SDK | packages/plugin-sdk | 服务注入、事件、存储 Token(当前 0.2.0) |
| 能力/宿主包 | plugin-documents、plugin-files、search-host、ai-host、job-host |
内置能力全部按"插件"形态实现 |
这里有个值得注意的设计:内置的文档、文件、搜索、AI 本身就以内置插件的身份注册,和外部的业务插件走同一套生命周期。组装入口在 apps/server/src/plugins/composition.ts:
const plugins: DocaPlugin[] = [
runtimePlugin(runtime), // 运行时基座
searchPlugin(), // 搜索
documentsPlugin(...), // 文档(含知识册)
aiPlugin(files), // AI
filesPlugin(...), // 文件
];
而"哪些属于核心、哪些属于插件"的界限也很明确:认证、授权、文件、文档协同、安全审计、AI 原始用量账本归核心;邮件、日程、会员、计费、配额、内容审核归业务插件,默认不安装。
三、插件化:生命周期与故障隔离
插件宿主 packages/plugin-host/src/index.ts 实现了一条严格的生命周期:
扫描静态元信息 → 校验依赖 → 导入代码
→ discover → 必需服务检查 → initialize → mount → ready
→ 停止接收请求/排空任务 → 逆依赖顺序 dispose
关键机制有三点:
- 依赖图静态校验:启动前校验 SDK 版本范围、依赖存在性、版本匹配,并用拓扑排序检测循环依赖,不合法的插件直接拒绝启动。
- 服务注入而非全局桥:插件通过稳定字符串 ID 声明
injections,宿主注入服务;禁止globalThis、Symbol.for保存业务实例,一个进程内可以创建多套互不影响的测试应用。 - 故障隔离:SDK 不兼容或依赖缺失时,只隔离受影响的业务插件,宿主与其他插件继续启动,管理页显示不可用原因——这是"插件化单体"区别于"单体加 if 判断"的核心价值。
存储同样托管:安装包必须声明 doca.storage: "host",插件拿到的是 pluginDatabaseToken(托管 SQL)、pluginObjectStorageToken(私有对象)与 pluginCredentialToken(加密凭证),插件定义业务模型和授权,但不选择后端、不直连数据库(docs/plugin-horizontal-scaling.zh-CN.md)。
四、模块边界:把架构规则写成测试
很多单体腐化的根源是"边界只存在于口头约定"。Doca 的做法是把边界规则写成持续运行的测试(tests/module-boundaries.test.ts):
- 核心不得依赖 HTTP 层:
packages/core/src/modules/**中任何文件,导入路径都不允许出现workflows/、apps/server或fastify——领域规则只能依赖领域契约。 - 前端目录白名单:
apps/web/src顶层只允许app、features、plugins、shared、styles五组;apps/server/src顶层只允许routes、services、plugins等八组。 - 禁止跨层穿透:Web 源码中禁止
../../packages/形式的相对路径导入包,必须走包名(HTTP DTO),前端永远不直接摸数据库或密码内部模块。
这几条规则保证了:领域核心可独立测试(内存 SQLite 即可跑)、前端不耦合数据库细节、新业务只能从 SDK 的插槽进入,而不是改宿主路由分支。
五、数据与协同平面:五个编辑器、一条 WebSocket
Doca 默认宿主内置五种编辑器格式:富文本、Markdown、表格、幻灯片、画布。它们在 apps/web/src/features/documents/document-editor.tsx 中分派到各自独立安装的编辑器包(@smartdoca/slate、@smartdoca/markdown、@smartdoca/sheet、@smartdoca/slides、@smartdoca/canvas),前端按需 lazy 加载:
服务端侧的取舍是元数据与正文分离:
- 元数据走 HTTP + 版本检查(乐观锁),冲突返回 409;
- 五种正文格式共用一条宿主 WebSocket 生命周期,各自带 Yjs codec;服务端验证内容、复查授权、提交后才确认保存;
- 后台任务用数据库租约/outbox 而不是进程内存,多副本时任一实例可领取、失败可重试(docs/horizontal-scaling.zh-CN.md)。
Redis 一旦被配置就是必需依赖,故障时不静默回退到进程内广播——避免集群分裂成多个"看似正常"的单实例。
六、取舍总结:这套架构适合谁
| 维度 | 收益 | 成本 |
|---|---|---|
| 部署 | 单实例零依赖,SQLite 开箱即用 | 多副本需 PostgreSQL + Redis + S3 |
| 扩展性 | 新业务以插件安装,故障按插件隔离 | 进程级隔离未交付,升级需人工重启全部实例 |
| 一致性 | 跨领域共享事务,权限复查简单 | 单体发布节奏统一,无法按模块独立扩缩 |
| 质量保障 | 边界规则测试化,防止架构腐化 | 契约严格(精确版本校验),不做兼容适配 |
一句话概括 Doca 的设计哲学:对外是一个简单单体,对内是插件化内核——用公开 SDK 而非网络边界来定义模块关系,用测试而非文档来守护边界。如果你正在为小团队设计文档、知识库类产品,这套"模块化单体 + 边界测试 + 插件生命周期"的组合,值得直接参考 docs/sdd-module-index.zh-CN.md 中的模块-契约-测试索引方式。


