# 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. 总体架构

```mermaid
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 预览路由规则

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

```text
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`：

```text
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 后再作为受控的内部多人平台发布。