ADR 0001：采用多仓服务架构

• 状态：已接受
• 日期：2026-08-28

背景

平台包含 Next.js Web、NestJS API、Conductor Worker、MCP Server、Render Worker，以及共享契约和独立基础设施。各服务部署方式、资源模型、扩容策略和安全边界存在明显差异。团队现有 GitLab 项目也采用群组下多仓管理方式。

决策

采用 8 个独立仓库：

narra-cine-prototypes-doc
narra-cine-web
narra-cine-server
narra-cine-worker
narra-cine-render
narra-cine-mcp
narra-cine-contracts
narra-cine-infra

业务代码统一采用 TypeScript/Node.js。共享协议通过 narra-cine-contracts 发布版本化 npm 包。Conductor、PostgreSQL、Redis、OSS 和 FFmpeg 作为基础设施或外部进程使用。

原因

• Web、API、Worker、MCP 和 Render 可独立部署、扩容和回滚；
• Render Worker 的 FFmpeg 和计算资源与普通服务隔离；
• MCP 的公网暴露、鉴权和审计边界独立；
• Worker 可以按供应商和任务类型拆分部署；
• 设计文档和基础设施拥有独立发布生命周期；
• 与现有 GitLab 群组和团队管理方式一致。

影响

正面：

• 仓库职责和部署边界清晰；
• 权限、CI、镜像和扩容可以分别治理；
• 大型媒体依赖不会污染其他服务。

负面：

• 跨仓变更需要版本协调；
• 本地开发和端到端测试需要聚合脚本；
• 契约版本管理必须严格执行。

约束

• 所有共享 DTO、事件、Workflow Task 和 TimelineSpec 放入 contracts；
• MCP 不复制 Server 业务规则；
• Worker 通过明确 API 或命令回写领域状态；
• Web 不直接调用供应商、Conductor 或数据库；
• contracts 不依赖 NestJS、Prisma 或供应商 SDK；
• 使用兼容性测试验证跨仓协议。

本地聚合

各仓库统一克隆到：

/Users/xhwx/work/coder/narra-cine/

后续在 infra 仓库提供本地聚合启动、依赖安装和端到端测试脚本。