GB
Grok Bot for Enterprise OSS Planning Docs · 开源规划文档
Unofficial / Inspired-by · 非官方

← Overview · Design Doc

Grok Bot for Enterprise（开源）— 设计 / 架构文档

定位：受 Grok Bot 类助手形态启发的开源企业方案，与 xAI / Grok 专有产品无隶属关系。

文档版本：v0.1 · 日期：2026-09-30 · 状态：规划草案

1. 概述

系统为企业提供可自托管的智能助手平台：浏览器访问 Web 应用，Node.js API 处理认证、会话、Agent 编排与管理面；PostgreSQL 持久化；对象存储保存附件与产物；Worker 执行异步任务；通过云驱动管理 Bot 计算机（VM） 池。模型调用经可配置路由层访问外部或内网 LLM。

2. 系统上下文图（描述）

  • 用户 / 管理员 → HTTPS → Web App（SPA）
  • Web App → HTTPS/WSS → API Gateway / Node API
  • API → PostgreSQL（元数据、会话、审计、RBAC）
  • API → Object Storage（S3 兼容：附件、Agent 产物）
  • API 入队 → Workers（Agent 步进、Routine、VM 生命周期）
  • Workers / API → Model Router → 各 LLM Provider
  • Workers → Cloud Provider Drivers → AWS / GCP / Azure / 阿里云 / 腾讯云 / 华为云 …
  • Bot VM 在隔离 VPC / 安全组中运行；仅经受控通道回连控制面

3. 架构图（Mermaid）

flowchart TB subgraph Clients U[End Users] A[Admins / IT] end

subgraph ControlPlane["Control Plane"] WEB[Web Frontend SPA] API[Node.js API] WRK[Background Workers] MR[Model Router] AUTH[Auth / RBAC] end

subgraph DataPlane["Data Plane"] PG[(PostgreSQL)] OBJ[(Object Storage S3-compatible)] Q[(Queue / Jobs)] end

subgraph Compute["Bot Computer Pool"] DRV[Cloud Drivers] VM1[VM AWS] VM2[VM GCP/Azure] VM3[VM Aliyun/Tencent/Huawei] end

subgraph Models["LLM Providers"] EXT[OpenAI-compatible / Anthropic / 国产 API] LOC[Private vLLM / On-prem] end

U --> WEB A --> WEB WEB --> API API --> AUTH API --> PG API --> OBJ API --> Q Q --> WRK WRK --> PG WRK --> OBJ API --> MR WRK --> MR MR --> EXT MR --> LOC WRK --> DRV DRV --> VM1 DRV --> VM2 DRV --> VM3

序列：用户启动需 VM 的 Agent（简图）

sequenceDiagram participant U as User participant API as Node API participant W as Worker participant D as Cloud Driver participant VM as Bot VM participant M as Model Router

U->>API: Start agent run API->>W: Enqueue job W->>D: Provision VM D->>VM: Create + bootstrap W->>M: Plan next step M-->>W: Tool call: exec W->>VM: Run command (channel) VM-->>W: stdout / artifact W->>M: Observation M-->>W: Final answer W->>D: Destroy or idle TTL W-->>API: Status complete API-->>U: Stream / notify result

4. 组件说明

组件 职责 备注
Web 聊天 UI、Agent 轨迹、管理控制台、设置 React/Vue 任选；MVP 建议 React + Vite
API REST/JSON + SSE/WebSocket；鉴权；业务编排入口 Node.js（TypeScript）
Workers Agent 循环、定时 Routine、VM 调谐、出站连接器任务 与 API 同仓不同进程；可水平扩展
PostgreSQL 用户、组织、会话、消息、任务、审计、配置 主存储；迁移用 Prisma/Drizzle/Knex
Object Storage 附件、日志包、VM 产物 MinIO（自托管）或云厂商 S3
Queue 任务队列 Redis + BullMQ，或 Postgres 队列起步
VM Pool 按需实例 + 镜像 + 网络策略 驱动插件化
Model Router 凭证、限流、模型映射、失败降级 不落日志完整 Prompt（可配置脱敏）

5. 认证与授权（Auth）

OSS MVP

  • 邮箱 + 密码（argon2）；首个用户引导为 owner
  • Session：HTTP-only Secure Cookie 或 JWT（短 TTL）+ Refresh
  • API Key（可选）：供 CI / 自动化，作用域受限

Enterprise（扩展）

  • OIDC / SAML SSO、SCIM 用户同步
  • 强制 MFA、会话策略、IP allowlist

RBAC

  • 权限检查在 API 中间件；敏感操作双写审计
  • 资源级：多数表带 org_id；VM / Connector 绑定组织

6. 多租户（Multi-tenancy）

模式：共享应用、共享 DB、行级 org_id 隔离（MVP）；Enterprise 可提供「专属 DB / 专属 VPC」拓扑。

原则：

  • 所有查询必须带租户上下文（中间件注入，禁止客户端伪造）
  • 对象存储 Key 前缀：org/{org_id}/...
  • 云账号：组织级凭证或平台级池（托管场景）

7. 模型路由（Model Routing）

Request(modelHint, org, user, taskType)
  → Policy(允许模型、预算、数据分级)
  → Resolve(provider, modelId, params)
  → Execute(stream)
  → Meter(tokens, cost_estimate)
  → Audit(metadata only)
  • 支持 OpenAI 兼容 API 为第一优先级（覆盖大量国产与自建网关）
  • 组织可配置「默认聊天模型 / 默认 Agent 模型」
  • 密钥存 KMS 或应用层加密（信封加密），永不下发前端

8. VM 生命周期（VM Lifecycle）

  1. Request：Agent 或用户请求 vm.acquire
  2. Provision：驱动创建实例、注入 bootstrap（agent worker、只读根、临时凭证）
  3. Ready：健康检查通过后绑定 run_id
  4. Use：命令执行、文件同步至对象存储
  5. Idle policy：空闲 N 分钟暂停或销毁
  6. Terminate：强制 TTL、用户销毁、或任务结束钩子
  7. Reconcile：Worker 周期性对齐云上实例子与 DB 状态

安全默认：

  • 独立安全组 / NSG；默认拒绝入站；出站可白名单
  • 无长期 IAM Key 进镜像；使用短时角色 / 一次性 token
  • 不可变基础设施：只从签名镜像启动

9. 安全与合规笔记

  • 威胁：提示注入导致工具滥用、VM 逃逸、密钥泄露、跨租户数据串扰
  • 缓解：工具权限矩阵、人类审批闸门（高风险）、租户强制过滤、密钥轮换、镜像扫描、依赖 SBOM
  • 合规方向：SOC2 / ISO27001 控制映射（Enterprise）；审计只追加；数据驻留区域开关
  • 隐私：默认不训练客户数据；遥测 opt-in
  • 免责：文档与 UI 声明非 xAI 官方产品

10. 部署拓扑

10.1 自托管 OSS

[ Docker Compose / K8s ]
  web + api + worker + postgres + redis + minio
  → 客户云账号（可选）用于 Bot VM
  → 客户自备 LLM API 或内网模型

适合：POC、强数据主权、二次开发。

10.2 托管 Enterprise

[ 厂商控制面多租户 ]
  区域部署 API/Worker
  共享或专属 PG
  平台云账号 VM 池 或 客户跨账户 AssumeRole
  SSO、SLA、备份、升级由厂商负责

适合：要省运维、要合规套件与支持的客户。

10.3 专属 VPC（大型企业）

  • 控制面部署进客户 VPC；出站经客户代理
  • 可选「空气间隙」变体：仅内网模型 + 无外网 VM

11. 技术选型与理由

选型 理由
Node.js + TypeScript 与实时流式、SSE、生态工具链契合；前后端类型可共享；招聘面广
PostgreSQL 可靠事务、JSON 灵活字段、生态成熟；审计与 RBAC 友好
React + Vite（建议） 管理台与聊天 UI 组件生态强；SSR 非必须
Redis + BullMQ Agent/VM 异步任务成熟方案；Compose 友好
S3 API 对象存储 多云可移植；MinIO 本地一致
云驱动插件 避免核心绑定单云；社区可贡献阿里云/腾讯云等
Zod / OpenAPI 契约优先，减少前后端漂移

刻意不选（MVP）：沉重的微服务网格、强绑 Kubernetes Operator（可作为 Later）、多语言混布（增加运维成本）。

12. 数据模型草图（核心表）

  • organizations, users, memberships, roles, permissions
  • sessions, messages, attachments
  • providers, models, model_policies
  • agent_runs, agent_steps, routines, routine_runs
  • connectors, connector_accounts
  • vms, vm_events
  • audit_events

（详细 DDL 在实现阶段给出；所有业务表含 org_id + 时间戳。）

13. API 风格（示例）

  • POST /v1/chat/completions（会话封装，非裸透传密钥）
  • POST /v1/agents/runs · GET /v1/agents/runs/:id/events（SSE）
  • POST /v1/vms · DELETE /v1/vms/:id · POST /v1/vms/:id/exec
  • CRUD /v1/admin/providers · GET /v1/admin/audit

版本化 /v1；错误统一 { code, message, request_id }。

14. 可观测性

  • 结构化日志（JSON）+ request_id / org_id / run_id
  • Metrics：延迟、Token、VM 供给时间、队列深度
  • Tracing：API → Worker → Provider（注意脱敏）

15. 开放架构问题

  1. Agent 状态机存在 PG vs 工作流引擎（Temporal）的引入时机？
  2. Web 终端进 VM：Guardian 代理 vs 云厂商控制台跳板？
  3. 是否提供「轻量容器执行」与「完整 VM」双模式？
  4. 控制面与 VM 的回连：WireGuard / SSM / 自研 tunnel？

16. 修订记录

版本 日期 说明
v0.1 2026-09-30 初稿

本文档指导实现与 RFC；与 PRD 里程碑对齐后冻结 MVP 范围。