wsk/deerflow-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b638b541d0
deerflow-code/docs/openvibecoding-内网沙箱改造-开发方案.md
gozeros b638b541d0 初始化
2026-09-07 18:24:55 +08:00

15 KiB
Raw Blame History

OpenVibeCoding 内网可视化应用生成平台：分步开发方案

文档状态：待实施

目标环境：现有 Ubuntu 22.04 Docker 服务器；对外可用端口限定为 8020-8030。

本文基于 2026-08-31 的只读巡检编写。未在目标服务器上安装、停止或修改任何服务。

1. 目标与范围

将 OpenVibeCoding 改造成一个使用公司内网模型、在公司服务器 Docker 沙箱中生成并运行可视化应用的工作台。用户通过对话生成项目，查看并修改文件，在浏览器中预览运行结果。

第一期只服务以下项目类型：

  • 数据大屏、数据看板、海报和展示型页面；
  • React + Vite + TypeScript 前端；
  • ECharts 图表、流程图；
  • 可选的轻量 Python FastAPI 接口；
  • 项目文件浏览、编辑、运行日志和实时预览。

第一期明确不做：

  • 腾讯云 CloudBase、SCF、TCR、CodeBuddy、云端一键部署；
  • 任意语言、任意 npm/PyPI 包的无限制安装；
  • 用户自定义 Dockerfile、Docker Socket 挂载、宿主机命令执行；
  • 直接将沙箱暴露为独立公网端口；
  • 对不可信代码提供“绝对安全”的隔离承诺。

2. 已确认的服务器基线

目标服务器当前具备：

项目 巡检结果 判断
操作系统 Ubuntu 22.04.5 LTS 支持 Docker 方案
CPU 32 vCPU 足够第一期
内存 125 GiB；巡检时可用约 106 GiB 足够第一期
根磁盘 2 TB；巡检时可用约 1.6 TB 足够 Harbor、镜像与工作区
Docker 29.1.3，Docker Compose 2.40.3 已满足
负载 约 0.5 当前有余量
8020-8030 巡检时无监听、无 Docker 端口映射 可规划使用

该服务器已承载 DeerFlow、Coze、LiteLLM、数据库和其他容器；80、8000、8005、8006、3306、5432 等端口已经被使用。因此，本项目不能占用现有端口、网络、数据库或容器名称。

该服务器有公网 IP，且已有多项服务绑定在 0.0.0.0。本方案将它视作“公网可达的共享主机”处理；云安全组和宿主机防火墙必须额外核验，不能仅凭端口监听结果假设安全。

3. 总体架构

flowchart LR
    U[用户浏览器] -->|:8020| G[App Builder Gateway]
    U -->|:8022 /preview/<sandboxId>/| P[Preview Router]

    G --> O[OpenVibe Web / Agent Server]
    O --> M[现有内网模型网关]
    O --> DB[(独立 PostgreSQL)]
    O --> R[(独立 Redis)]
    O --> SM[Local Sandbox Manager]

    SM --> D[Docker Engine]
    D --> S1[visual-ui Sandbox]
    D --> S2[visual-fullstack Sandbox]
    P --> S1
    P --> S2

    D --> H[Harbor :8023]
    S1 --> N[内网 pnpm/npm 源或预置离线依赖]
    S2 --> N

设计原则：

  1. 保留 OpenVibe 的对话、任务、文件树、工具卡片和 OpenCode ACP 代码代理体验。
  2. 模型请求仅由 OpenVibe 服务端发往既有内网模型网关；API Key 不进入沙箱。
  3. 每个项目运行于独立 Docker 容器和独立工作区；沙箱只运行项目代码，不承担平台控制逻辑。
  4. 浏览器预览只经过统一预览路由，不为每个项目映射新的公网端口。
  5. 先用固定模板和固定依赖清单保证稳定，后续再按白名单增加依赖。

4. 端口规划

端口虽然可用，但应尽量少暴露。除 8020、8022 和按需开放的 8023 外，其余服务只加入 Docker 内部网络。

端口 服务 绑定范围 用途
8020 appbuilder-gateway 公网访问面或 VPN 白名单 控制台页面、/api、SSE/WebSocket
8021 预留 仅 127.0.0.1 平台调试；第一期不对外开放
8022 preview-router 公网访问面或 VPN 白名单 统一预览入口：/preview/<sandboxId>/
8023 Harbor 仅沙箱节点、构建节点和管理员网段 私有镜像仓库 HTTPS Registry
8024 预留 不对外开放 后续 npm 私服或运维服务
8025-8030 预留 不对外开放 扩展、迁移或故障切换

4.1 预览路由规则

暂时没有可用泛域名时，使用路径型预览：

http(s)://<服务器地址>:8022/preview/<sandboxId>/

项目模板的 Vite base 和 HMR 路径必须由启动脚本注入为该前缀，确保图片、JS/CSS 资源及热更新不会错误请求到根路径。后续若获得 *.preview.company.local 内网泛域名，可切换为子域名预览，用户体验更好。

5. 镜像、模板与离线依赖策略

5.1 标准镜像

第一期维护两种版本化镜像，不允许用户自行构建 Dockerfile：

镜像 用途 预置内容
appbuilder/visual-ui:<version> 大屏、海报、纯前端 Node.js 20、pnpm、React、Vite、TypeScript、ECharts、流程图库、统一 UI 库、Tailwind、图标与中文字体
appbuilder/visual-fullstack:<version> 前端加接口 上述前端依赖 + Python 3.12、FastAPI、Uvicorn、Pydantic

流程图库第一期统一选择一种（建议 React Flow），避免同时生成多种流程图语法和样式。地图、背景图、字体等资源也应作为受版本控制的本地资产打包，不能依赖 Google Fonts 或公网 CDN。

5.2 项目模板

每次创建项目时从镜像中的模板初始化到 /workspace：

templates/
  visual-screen/          # React + ECharts + React Flow + Mock 数据
  visual-screen-api/      # visual-screen + FastAPI + /api 反向代理
  poster-page/            # 海报、营销展示、静态动效

visual-screen-api 约定：前端只请求相对路径 /api/*；预览网关将其转发到同一沙箱的 FastAPI 8000 端口。没有后端时保留 Mock 数据模块，生成的页面仍可运行。

5.3 依赖预置方式

不能仅把安装命令写进 Dockerfile 后在用户创建项目时再联网执行。正确做法是：

  1. 在受控构建环境中锁定 package.json、pnpm-lock.yaml、requirements.lock。
  2. 构建镜像时执行 pnpm fetch，在镜像保存只读 pnpm store；Python 包保存到 /opt/wheelhouse。
  3. 沙箱初始化使用 pnpm install --offline --frozen-lockfile 和 pip install --no-index --find-links=/opt/wheelhouse。
  4. 第一期开启“固定依赖白名单”：AI 只能使用镜像已安装的依赖；新依赖先由管理员审核、加入锁文件和下一版基础镜像。
  5. 第二期部署 Verdaccio/Nexus 等内部制品源，作为受控补充而非允许访问公网 npm/PyPI。

6. OpenVibe 改造边界

6.1 保留

  • 前端交互：对话、任务状态、文件浏览与修改、预览、日志；
  • OpenCode ACP 代码代理；
  • 项目与会话领域模型；
  • 代码代理的流式事件协议。

6.2 替换或关闭

OpenVibe 当前能力 第一期开源/内网实现
CodeBuddy 只启用 OpenCode，配置内网 OpenAI 兼容模型网关
CloudBase、SCF 沙箱 新增 LocalDockerSandboxManager
TCR Harbor
CloudBase 环境、用户环境池 Docker 容器、工作区卷、沙箱记录
CloudBase 消息与事件持久化 独立 PostgreSQL；Redis 用于临时队列与状态
CloudBase 存储、函数、MCP、资源管理后台 第一期开关关闭或移除入口
CloudBase 项目模板和系统提示词 替换为大屏/海报/FastAPI 模板与受控依赖提示词

重点改造点是将 OpenVibe 的 scf-sandbox-manager 和 CloudBase 生命周期调用替换为本地 Docker 生命周期。为降低前端和 OpenCode 工具改动范围，新管理器应适配现有的文件、命令、日志、健康检查与工作区信息契约，而不是改写所有 Agent 工具。

7. 沙箱安全基线

每个沙箱容器必须满足：

  • 非 root 用户运行；禁止 privileged，禁止 Docker Socket，禁止宿主机目录挂载；
  • --cap-drop=ALL、no-new-privileges、pids-limit；
  • 首期默认限制：1 vCPU、3 GB 内存、10 GB 工作区、60 分钟空闲回收；
  • 使用独立 Docker network；默认无公网出口，只允许访问预置依赖、必要的内网 DNS 和平台回调；
  • 数据库、Redis、Harbor 管理接口、宿主机管理端口不在沙箱网络可访问范围；
  • 运行命令、容器生命周期、文件变更和预览访问写入审计日志；
  • 平台服务由受限服务账号调用 Docker API；用户代码永远不直接获得 Docker 权限。

第一期为“内部可信用户的容器隔离”。若后续允许大量非可信代码或文件上传，应迁移为 Kubernetes 节点，并评估 gVisor/Kata 等更强运行时隔离。

8. 分步实施计划

阶段 0：部署前隔离与基线确认

工作项

  1. 为本项目建立独立目录、Docker Compose Project、卷和网络，命名统一为 appbuilder-*。
  2. 确认云安全组、iptables/nftables 规则：仅允许管理员 SSH；8020、8022、8023 仅向 VPN 或指定办公出口开放。
  3. 不复用当前服务器上已有的 MySQL、PostgreSQL、Redis、Nginx 配置；建立独立实例或独立命名空间。
  4. 创建内部 CA 证书或确定可信 HTTPS 证书方案；Docker 构建/运行节点信任 Harbor 证书。
  5. 轮换目标服务器 root 密码，改用 SSH 密钥和受限运维账号；关闭 root 密码远程登录。

验收

  • 8020-8030 无端口冲突；
  • 新容器、网络和数据卷均不影响既有 DeerFlow 等服务；
  • 业务数据库和沙箱端口无法从非授权公网地址访问。

阶段 1：内网基础设施与镜像供应链

工作项

  1. 在独立 Compose 项目中部署 Harbor，主入口为 8023，镜像数据使用独立持久化目录。
  2. 构建并推送 visual-ui、visual-fullstack 两种基础镜像；记录镜像版本、SBOM 和依赖锁文件。
  3. 完成三个模板及离线依赖初始化脚本。
  4. 先不启动漏洞扫描；严格断网环境下后续通过离线包维护漏洞库。
  5. 预留内部 npm/PyPI 源接入方式；第一期仅使用预置依赖。

验收

  • Docker daemon 能从 Harbor 拉取指定版本镜像；
  • 在禁止公网访问的测试网络中，三个模板均能启动并构建；
  • 一个 ECharts 页面、一个流程图页面和一个 FastAPI /api/health 均可运行。

阶段 2：OpenVibe 去 CloudBase 化与内网模型接入

工作项

  1. Fork 固定版本的 OpenVibeCoding，建立 local-platform 改造分支，记录上游 commit 与许可证。
  2. 只保留 OpenCode Agent；将 provider 指向现有内网模型网关，模型凭证只保存在服务端环境变量或密钥服务。
  3. 将基础实体、任务、消息、流式事件的持久化迁移为独立 PostgreSQL；不再调用 CloudBase 集合。
  4. 关闭 CloudBase 环境、函数、存储、数据库、资源仪表盘和相关 MCP 入口。
  5. 将系统提示词和项目创建默认项改为“可视化页面 + 受控模板/依赖”。

验收

  • 不设置任何腾讯云、CloudBase、CodeBuddy、TCR 环境变量时，平台可启动；
  • 用户发起“生成 ECharts 大屏”后，OpenCode 能调用内网模型并生成项目文件；
  • 服务端日志和沙箱环境中均没有模型 API Key。

阶段 3：本地沙箱管理器与预览路由

工作项

  1. 实现 LocalDockerSandboxManager：创建、启动、停止、超时回收、查询状态和删除容器。
  2. 每个沙箱分配工作区卷、随机内部容器地址、模板类型和资源限制；在数据库记录 sandbox_id、项目、用户、镜像版本、过期时间和状态。
  3. 实现或适配沙箱内 runner：文件读写、受限命令执行、日志流、健康检查、前端端口和 FastAPI 端口发现。
  4. 实现 preview-router：由平台根据 sandboxId 维护路由，将 /preview/<sandboxId>/ 代理到对应内部容器；支持 WebSocket/HMR。
  5. 增加容器异常退出、端口未就绪、构建失败、超时与手动重启的可见状态。

验收

  • 两个用户创建的项目存在于不同容器和不同工作区；
  • 修改 ECharts 配置文件后，预览地址显示修改结果；
  • FastAPI 模板的 /api/health 可通过前端相对路径访问；
  • 沙箱不能访问 Docker Socket、宿主机数据库和非白名单网络；
  • 空闲超时后容器被回收，项目文件仍可恢复。

阶段 4：产品能力收口

工作项

  1. 在文件面板支持安全的文件查看、编辑、保存、目录树刷新与下载；限制文件大小和可编辑扩展名。
  2. 在对话中增加模板选择和能力提示：大屏、流程图、海报、可选 FastAPI。
  3. 为 Agent 增加依赖白名单、图表主题、中文字体、Mock 数据、接口契约等明确提示词。
  4. 增加“运行/停止/重启/删除沙箱”和日志面板；仅项目所有者或管理员有相应权限。
  5. 增加项目快照、模板版本记录和基础审计日志。

验收

  • 从一句自然语言需求到可预览项目的完整链路可完成；
  • 用户可查看并手动修改文件，刷新后改动保留；
  • 页面覆盖 ECharts、流程图、响应式大屏和可选 FastAPI 接口；
  • 非拥有者不能读取、修改或预览另一用户的项目。

阶段 5：上线前安全与运行验收

工作项

  1. 压测 6 个并发沙箱，并记录 CPU、内存、磁盘、容器启动时间、首屏预览时间和模型等待时间。
  2. 验证镜像保留策略、工作区配额、容器回收、数据库备份和 Harbor 备份恢复。
  3. 执行越权、路径穿越、命令注入、网络探测、资源耗尽和模型密钥泄露测试。
  4. 建立日常运维操作：新增基础依赖、构建镜像、发布模板、回滚镜像、清理工作区和审计查询。

验收

  • 并发运行时既有 DeerFlow 等服务不受明显影响；
  • 任一沙箱异常退出不会影响其他项目或平台控制服务；
  • 备份可恢复项目元数据、工作区和 Harbor 镜像；
  • 仅开放计划中的入口端口，内部组件无不必要公网监听。

9. 首期资源与并发建议

由于该主机已有多项业务，首期不应按理论最大值分配：

组件 首期限制
Harbor 8 vCPU、16 GB 内存、500 GB 数据盘配额
OpenVibe 控制服务 4 vCPU、8-16 GB 内存
单个 UI 沙箱 1 vCPU、3 GB 内存、10 GB 工作区
单个 Fullstack 沙箱 1.5 vCPU、4 GB 内存、12 GB 工作区
沙箱并发 先限制为 6；稳定后再逐步上调

当并发超过 10 个，或要面向更广泛用户开放时，应优先增加独立沙箱节点，而不是继续在本共享主机上加容器。

10. 实施顺序与交付物

建议按以下提交/交付顺序推进，每一步都可独立验收和回退：

  1. docs: confirm appbuilder network, ports and security baseline
  2. infra: add Harbor and versioned visual sandbox images
  3. infra: add offline templates and dependency locks
  4. feat: replace OpenVibe CloudBase persistence and model provider
  5. feat: add local Docker sandbox manager
  6. feat: add sandbox runner and path-based preview router
  7. feat: add visual-screen and FastAPI project workflows
  8. test: add sandbox isolation, preview and recovery coverage
  9. ops: add backup, cleanup, monitoring and rollout runbook

达到阶段 3 即可交付“内网模型驱动、生成并预览大屏/海报页面”的 PoC；达到阶段 5 后再作为受控的内部多人平台发布。