Doca 架构深度解析:TypeScript 插件化单体的设计取舍与模块边界

原创2026-11-16 14:38:13233 阅读

Doca 架构深度解析:TypeScript 插件化单体的设计取舍与模块边界

Doca 是一个开源的文档管理与知识库系统,支持多人实时协同编辑、在线文档、Markdown、表格、幻灯片、画布和 AI 助手。它采用 TypeScript 插件化单体(Modular Monolith)架构:一个可部署单元,内部却按插件化思想划清模块边界。本文带你从目录分层、插件生命周期到"把架构规则写进测试",完整拆解这套设计背后的取舍。

Doca 开源文档管理工作台首页,模块化单体单实例提供文档、知识库与 AI 助手完整能力

一、为什么先做单体,而不是微服务

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 原始用量账本归核心;邮件、日程、会员、计费、配额、内容审核归业务插件,默认不安装。

Doca AI 画布工具生成的数据库关系图,展示内置 AI 插件在画布编辑器中的输出结果

三、插件化:生命周期与故障隔离

插件宿主 packages/plugin-host/src/index.ts 实现了一条严格的生命周期:

扫描静态元信息 → 校验依赖 → 导入代码
→ discover → 必需服务检查 → initialize → mount → ready
→ 停止接收请求/排空任务 → 逆依赖顺序 dispose

关键机制有三点:

  1. 依赖图静态校验:启动前校验 SDK 版本范围、依赖存在性、版本匹配,并用拓扑排序检测循环依赖,不合法的插件直接拒绝启动。
  2. 服务注入而非全局桥:插件通过稳定字符串 ID 声明 injections,宿主注入服务;禁止 globalThis、Symbol.for 保存业务实例,一个进程内可以创建多套互不影响的测试应用。
  3. 故障隔离: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 加载:

Doca 画布编辑器界面,五种文档编辑器共用同一条宿主 WebSocket 协同通道

服务端侧的取舍是元数据与正文分离:

  • 元数据走 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 中的模块-契约-测试索引方式。

登录后查看全文
doca