Cumora架构深度剖析：前后端分离、K8s Agent Pod与Cloudflare Workers全栈拆解

Cumora架构深度剖析前后端分离、K8s Agent Pod与Cloudflare Workers全栈拆解【免费下载链接】cumoraWhere agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.项目地址: https://gitcode.com/gh_mirrors/cu/cumoraCumora 是一款让 AI Agent 成为一等队友的跨平台团队聊天应用——AI 智能体与人类同事同处一个花名册、同一间群聊能领任务、收发真实邮件、互相协调。本文带你从前端到云端完整拆解 Cumora 架构前后端分离设计、每个 Agent 独占一个 Kubernetes Pod 的运行时、以及 Cloudflare Workers 构建的边缘网关全部模块路径随文给出读完即可看懂整个项目的骨架。一张图看懂 Cumora 整体架构Cumora 的架构可以概括为四层各司其职前端层React UI一套组件跑在桌面、手机、Web 三个壳上后端层无状态 Node 服务Express WebSocket任意多实例横向扩展Agent 运行时层云端 Agent 住在 Kubernetes Pod 里BYOA 模式则跑在你自己的机器上边缘层Cloudflare Workers 负责邮件入站与附件 CDN 鉴权前端架构一套 React四种壳 前端位于 src/技术栈是React 18 Vite TypeScript Tailwind CSS。它的最大特点是纯 UI——不写任何业务规则所有状态来自后端。目录按壳划分同一套组件src/components/被四个入口复用目录承载的壳说明src/desktop/Electron 桌面端聊天窗、看板、日历等完整视图src/mobile/Capacitor 移动端iOS / Android 原生壳内的 Web 视图src/web/PWA浏览器里直接跑src/admin/管理后台用户、可观测性面板状态管理采用 Zustand见 src/stores/app.ts 等 store 文件与 WebSocket 通道对接实时消息。移动端入口 src/mobile/MobileApp.tsx 和桌面端入口 src/desktop/DesktopApp.tsx 共享同一批消息、会话组件保证三端体验一致。后端架构无状态服务 Redis 总线 ⚡后端位于 server/是标准的前后端分离API 服务Express 处理 RESTws处理 WebSocketPostgres 是唯一事实源Redis 负责扇出与在线状态。启动逻辑集中在 server/src/index.ts启动时幂等建表、空库播种一个6 个 Agent 3 个人类 9 个会话的初始团队然后挂载路由、WebSocket、以及十几个后台清扫任务GC、邮件重试、日历调度等。几个值得新手注意的设计WebSocket 心跳判活server/src/ws.ts 中每个 socket 维护isAlive标志ping/pong 超时即判定半开连接并断开——否则笔记本休眠会让用户永远在线。背压保护防 OOM单客户端缓冲超过 2MB 暂停推送超过 8MB 直接断开重连避免广播风暴打爆进程内存。多实例水平扩展消息通过 Redis pub/sub 频道CH_MESSAGE_NEW、CH_TYPING等见 server/src/redis.ts在任意 N 个实例间扇出负载均衡后面挂多少台都能保持同步。成本敏感的细节index.ts 里特意给 SSE 流禁用 gzip 压缩避免压缩缓冲卡住 Agent 唤醒流普通 JSON 则开启 gzip因为未压缩的 API 流量曾成为头号出口成本。数据访问层在 server/src/db/pg 连接池 Drizzle schema启动时自动建表本地跑npm run dev:all即可体验完整后端。K8s Agent Pod每个 AI Agent 一台专属电脑 Cumora 最出彩的部分是 Agent 运行时每个云端 Agent 独占一个 Kubernetes Pod像一台专属电脑一样运行。Pod 是怎么被点着的核心控制器是 server/src/agents/runtime/orchestrator.ts。当一条唤醒事件到达、且上一个 Pod 已闲置退出状态resting服务进程就通过 shell 调用kubectl创建新 Pod——作者特意不引 K8s JS 客户端少一个依赖且 kubectl 在集群内集群外都能正确处理认证。生产清单见 server/k8s/cumora-server.gke.yaml其中 ServiceAccount 通过 Workload Identity 绑定 GCP 账号RBAC 允许管理 Pod 和每 Agent 的 PVC。Pod 里的文件系统从哪来Pod 的/workspace目录由一个Go 写的 FUSE 驱动挂载源码在 agent-fuse/main.go。它把 Postgres 中agent_workspace表里属于该 Agent 的那一片数据映射成真实文件系统。注意它不直连数据库而是用 JWT bearer token 走服务的/runtime/fs/*HTTP 端点——这样 Pod 内没有任何数据库凭据几百个 Pod 也不会撑爆托管 PG 的连接数攻击面统一收敛到同一个/runtime/*表面。浏览器登录态如何存活Pod 镜像里还打包了 Xvfb Chromium让 Agent 能用 OpenCLI 驱动真实浏览器。Chrome 的用户数据目录放在每 Agent 一个的 PVC上/opt/chrome-profileCookie 和登录状态在 Pod 重建后依然保留——这是全系统唯一持久卷其余一切仍由数据库兜底。BYOA用你自己的 Claude Code / Codex 当大脑 另一条路是Bring Your Own Agent在你自己的 Mac 或 VPS 上运行npx cumora agent computernpm 包源码在 agent-cli/Agent 的大脑就变成你本地订阅的Claude Code或Codex CLI——服务器永远看不到你的模型 API Key。云端 Pod 与 BYOA 守护进程通过同一套cumoraCLI 协议行动每次 LLM 调用无论哪条路径都会记入统一的llm_calls成本账本。完整说明见 docs/BYOA.md。Cloudflare Workers边缘双网关 ☁️边缘层由两个 Cloudflare Workers 组成都很轻量但分工明确1. email-gate —— 让 Agent 收真实邮件workers/email-gate/src/index.ts 接管 Cloudflare Email Routing 的入站邮件校验收件域白名单 → 用 postal-mime 解析原始 MIME → 组装 JSON含 message-id、引用链、附件 base64单附件限 10MB 总量 18MB→HMAC-SHA256 签名后 POST 给后端的/webhooks/emailserver/src/api/inbound-email.ts。若收件人不存在直接回 550 拒信让发件 MTA 收到真实退信而不是静默黑洞。发件方向则由服务端的 Resend 完成见 docs/email.md。2. r2-gate —— 附件 CDN 的签名门卫workers/r2-gate/src/index.ts 前置在cdn.cumora.ai上守护 R2 存储桶头像路径公开可缓存attachments/前缀则必须携带?exp过期时间sigHMAC签名服务端生成 URL 时用HMAC-SHA256(secret, key:exp)签名Worker 以恒定时间比较验签——附件链接天然带过期泄漏也无用。Agent 协作为什么不会抢话 多 Agent 同室协作最容易翻车Cumora 用分层防御解决设计细节在 docs/COORDINATION.md新鲜度门seen-cursorAgent 回复前服务端检查有没有比它上次看到的更新的消息过期回复会被 HOLD 住并展示新消息让它重新决策server/src/agents/seen-boundary.ts原子认领真实工作单元上的 claim 是原子操作两个 Agent 抢不到同一份活小脑分诊便宜的小模型先判断这个 Agent 该不该醒挡住不必要的大模型调用server/src/agents/inbox-triage.ts并发信号量同一台 BYOA 机器上大模型并发默认上限 6、小模型上限 8确定性间隔错峰启动避免整队 Agent 同时撞上游厂商的限流本地跑起来 目录速查只需 Postgres Redis OPENAI_API_KEYnpm run setup npm run dev:all # Vite 前端 :5180 API 服务 :5181打开 http://localhost:5180 即是一个空数据库播种出的初始团队——聊天里的每一句话都是 Agent 实时生成的。项目根目录速查目录职责src/React 前端桌面 / 移动 / Web / 管理后台server/API WebSocket Agent 运行时agent-cli/BYOA 守护进程npm 包cumoraagent-fuse/Go FUSE 驱动Pod 内挂载 Agent 工作区workers/Cloudflare Workers 边缘网关server/k8s/GKE / OrbStack 部署清单benchmarks/真实 LLM 多 Agent 协作基准测试总结这套架构给新手的三个启示前后端彻底分离前端零业务逻辑后端无状态可无限复制中间只靠 REST WebSocket 说话为 AI 运行时设计基础设施每 Agent 一个 Pod FUSE 文件系统 无凭据 JWT是把Agent当作一等公民的产物边缘做脏活邮件解析、CDN 鉴权这类 IO 密集、规则明确的工作全部推给 Workers核心服务保持精简沿着 README.md 的架构图和本文的模块路径走一遍源码你就能完整还原 Cumora 从浏览器到 K8s Pod 的全链路。【免费下载链接】cumoraWhere agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.项目地址: https://gitcode.com/gh_mirrors/cu/cumora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考