系统架构总览-ChengOS 可视化工作流编排 · MCP 原生支持

适用版本：ChengOS v0.1.0+ ｜最后核对：2026-08-12 ｜来源：根 CLAUDE.md、deploy/README.md、deploy/distributed/README.md、crates/cheng-api/src/rest/routes.rs

本文是一张地图：有哪些进程、后端由哪些 crate 组成，以及这些进程可以被编排成哪些部署形态。

运行时组件

一套完整的安装会运行四个应用进程和最多三个数据存储。

进程	默认端口	角色
`cheng-api`	`3000`	后端。其余一切都是它的客户端。
`cheng-ui`	`8080`	工作流编辑器与管理控制台（静态资源 + 一个轻量服务）
`cheng-app`	`5055`	对话网关：网页组件、H5/PWA、即时通讯渠道
`cheng` CLI	—	终端客户端；本地或通过 URL 连接 `cheng-api`
PostgreSQL	`5432`	唯一的业务真相来源
Valkey（Redis 兼容）	`6379`	缓存、速率限制、智能体记忆。可选。
Qdrant	`6333`/`6334`	面向 RAG 的向量检索。可选。

在原生安装中 Valkey 和 Qdrant 默认关闭（ENABLE_REDIS、ENABLE_QDRANT）。当你开始使用智能体记忆或 RAG 时再打开。

后端架构

后端是一个基于六边形架构的 Rust Cargo workspace（构建意义上的工作空间，与 ChengOS 的「工作区」是两回事）——领域逻辑居中，基础设施在边缘，两者之间用 trait（「端口」）隔开。实际效果是：领域层完全不知道 PostgreSQL 或 HTTP 的存在。

层次	Crate	内容
领域层	`cheng-core`	`Workflow`、`Node`、`Execution`；端口 trait（`WorkflowRepository`、`Executor`、`NodeRegistry`、`EventPublisher`）；领域服务。不依赖任何基础设施。
应用层	`cheng-engine`	`WorkflowEngine` 实现 `Executor` 端口：DAG 分析、规划、调度、流式推送
基础设施层	`cheng-storage`	用 Diesel 在 PostgreSQL 上实现仓储端口；数据库迁移
表现层	`cheng-api`	Axum REST 处理器、WebSocket 管理器、依赖注入

配套 crate：cheng-nodes（内置节点库与注册表）、cheng-llm（供应商抽象）、cheng-vector（Qdrant）、cheng-adapters（WhatsApp、Telegram、Slack、钉钉、企业微信）、cheng-mcp（MCP 客户端与服务端）、cheng-runtime（代码节点用的 QuickJS/Python 沙箱与 Docker 运行时）、cheng-code-index（tree-sitter 代码智能）以及 chengctl（离线 i18n 命令行工具）。

依赖在启动时注入，而不是通过全局变量获取，因此不存在需要推敲的可变全局状态。

一次请求如何变成一次运行

客户端调用 POST /api/v1/executions。
WorkflowEngine 通过 WorkflowRepository 端口加载工作流。
图被校验并规划成有序的阶段。
创建 Execution 记录。
后台任务并发调度就绪节点，每完成一个就持久化结果并发布事件。
事件通过 WebSocket 实时抵达已连接的客户端。
执行进入某个终态。

详细过程见执行模型。

部署形态

支持三种编排方式，全部由同一份 deploy/.env 驱动：

形态	什么跑在哪	何时选用
原生（hybrid）	全部在一台主机；数据库作为普通用户进程或 systemd 服务	试用、单机安装、没有 root 的主机
Docker	每个服务都是 Compose 容器	生产环境、可复现安装
分布式	数据存储在一台主机，`cheng-api` 在另一台，均为原生	对性能敏感、不希望有容器开销的安装

如何选择见部署模式，容器化路径见 Docker 部署。

前端如何访问后端

在生产环境中，UI 和 app 以静态包形式提供，并通过 UI_API_BASE_URL、UI_WS_URL、APP_API_BASE_URL、APP_WS_URL 中的地址访问 API——通常是同一个反向代理后的 /api/v1 与 /ws。

在开发环境中，:5173 上的 Vite 开发服务器把 /api、/ws 及相关路径代理到 :3000 的后端。

节点界面是跨边界由 Schema 驱动的：后端节点定义输出带 x-* 扩展的 JSON Schema，前端的字段控件注册表把它们转换成表单控件。后端修改节点输入，编辑器随之变化，前端无需改动。

国际化同样横跨两侧。chengctl 离线提取并翻译节点定义中的字符串，前端从 /api/v1/i18n 加载生成的语言包。

安全边界

在对外暴露一套安装之前，有四条边界值得了解：

凭证用 CREDENTIAL_MASTER_KEY_1 加密，在使用点由服务端解析，永远不会进入模型的提示词。
工作区按 user_id 和工作区成员关系隔离数据；X-Workspace-Id 会被授权校验，而不是被信任。
沙箱把文件和 shell 工具限制在工作区的目录树内。
网络暴露面应当只有一个经反向代理的 443。Docker 已把数据存储和 API 的宿主机端口绑定到回环地址；原生部署需要主机防火墙。

下一步

核心概念——领域术语。
执行模型——深入调度与状态。
环境变量参考——所有可配置项。

文章版权归作者所有，未经允许请勿转载。

THE END

配置与部署

系统架构总览