CubeSandbox Dashboard 深度指南从 Vite 开发调试到 nginx 容器化部署【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox本指南围绕 CubeSandbox 仓库中的 Web 控制台web/ 目录展开完整讲解其技术栈、本地快速启动、路由页面设计、与后端 CubeAPI/CubeOps 的通信机制以及一键部署场景下基于 nginx 的同源反向代理与 Docker host-gateway 配置。读完本文你将掌握这套「现代、极简、酷炫」的 AI 沙箱管理面板从前端开发到生产落地的完整链路。项目定位与技术栈概览CubeSandbox Dashboard 是 CubeSandbox 项目的管理控制台面向 AI Agent 沙箱集群提供集群总览、沙箱生命周期管理、模板目录、节点健康等可视化能力。它本身是一个纯前端 SPA不直接操作沙箱运行时而是通过 HTTP 与后端服务交互。按 web/README.md 的定义它的技术选型是构建工具ViteUI 框架React TypeScript样式方案Tailwind CSS v3 shadcn-style 原语组件Radix UI 基础件数据请求TanStack QueryReact Query命令面板cmdk支持 ⌘K 快捷命令这些依赖都可以在 web/package.json 中逐一验证。除了上述核心库还引入了 zustand 做状态管理、react-router-dom v6 做路由、i18next 做国际化内置en/zh两套语言资源、dicebear 生成 Agent 头像、lucide-react 提供图标、fontsource-variable 引入 Inter 与 JetBrains Mono 可变字体。快速启动三条 Make 命令跑通开发闭环web/README.md 给出了三条最常用的命令整个开发调试流程可以在分钟级内启动make web-install # 安装前端依赖npm install make web-dev # 启动 Vite 开发服务器 → http://localhost:5173 make web-build # 生产构建 → web/dist/三个要点值得注意开发端口固定为 5173。在 web/vite.config.ts 的server.port中写死同时 Vite 会把/cubeapi等路径代理到本机 CubeAPI:3000实现前后端分离开发。构建产物目录为web/dist/。生产环境一键部署会直接把这个静态目录挂载进 nginx 容器。版本号自动注入。Vite 配置通过__APP_VERSION__常量注入界面显示的版本优先取CUBE_VERSION环境变量release 构建时由github.ref_name注入否则回退到git describe --tags最近一次 tag最后才使用package.json的 version。这样 UI 上展示的版本号始终与发布 tag 对齐。除了这三条web/package.json 还提供了npm run linttsc 类型检查、npm run fmtprettier 格式化等工程化脚本以及一套类型自动生成链路npm run api:export # 运行 CubeAPI 导出 openapi.yml npm run api:generate # openapi-typescript 从 openapi.yml 生成 src/api/generated/schema.ts npm run api:sync # 两步合并执行这意味着前端的所有 DTO 类型沙箱、模板、节点等都与 CubeAPI 的 OpenAPI 定义保持同步前后端契约由代码生成保证一致性。生成的类型文件位于 web/src/api/generated/schema.ts。路由体系从总览到运维的全景导航web/README.md 列出的核心路由与 web/src/main.tsx 中的实际注册完全吻合按其功能可分为四类核心资源管理路由页面说明/Overview集群 KPI、最近沙箱、模板流水线/sandboxesSandboxes沙箱列表 生命周期操作pause/resume/kill/sandboxes/:idSandboxDetail沙箱详情 日志/templatesTemplates模板目录/nodesNodes节点集群健康运维与进阶/keys在浏览器 localStorage 中保存X-API-KeyREADME 描述的功能入口/versions版本矩阵展示各组件guest image、agent、kernel 等在节点上的兼容性/warehouse及/warehouse/jobs、/warehouse/:component组件仓库管理从 GitHub/CNB/上传导入组件、按节点预安装/store模板市场Agent 能力扩展/agenthubAgent 实例管理支持 OpenClaw 引擎实例的创建、启停、快照、回滚、克隆、发布模板等操作/login登录页占位与预留/network、/observability、/settings在 README 中明确标注为roadmap placeholders路线图占位对应 web/src/pages/Placeholder.tsx。不过在 web/src/main.tsx 中它们已分别映射到 Network、Observability、Settings 页面组件其中 Settings 已承载登录口令修改等功能。路由结构采用AuthGuardAppShell嵌套布局未认证用户跳转/login认证后统一进入带侧边栏Rail和顶栏TopBar的 AppShell 框架。所有未知路径通过*兜底重定向到/。后端集成Dashboard 如何与集群对话两级后端架构README 明确指出Dashboard 只直接对话 CubeAPI仓库中的 CubeAPI/ 目录由 CubeAPI 作为聚合层代理模板、集群、节点等请求到 CubeMaster。这样前端只面对一个 E2B 兼容的 API 面屏蔽了后端的内部拓扑。双通道 API 封装从源码看前端请求封装在 web/src/lib/api.ts 中提供两个基础方法api()SDK 类端点沙箱 CRUD、模板、快照SDK_BASE 即请求同源根路径ops()CubeOps 运维端点OPS_BASE /opsapi/v1经 nginx 重写后到达 CubeOps。两者共用一套逻辑自动拼接 query 参数跳过undefined/null/、JSON 序列化 body、统一ApiError错误封装并且都实现了401 自动刷新 token——访问 token 失效时并发请求只触发一次/auth/refresh刷新后重放原请求web/src/lib/api.ts 的注释特别说明后端每次刷新会轮换 refresh token因此前端必须持久化新返回的 refreshToken否则 1530 分钟后会因旧 token 被吊销而被踢出登录态。从 X-API-Key 到 JWT 的演进README 描述的历史机制是X-API-Key头若 localStorage 的cube.apiKey存在会在每个请求上注入。而从当前 web/src/lib/api.ts 与 web/src/lib/session.ts 的源码看鉴权已经升级为JWT Bearer 体系登录成功后cube.accessToken/cube.refreshToken/cube.sessionUser写入 localStorage每次请求携带Authorization: Bearer accessToken登出时清理 token并向后端/auth/logout上报会话状态allowed/guest记录在 sessionStorage供 AuthGuard 判断首次进入是否需要跳转登录页。这属于文档描述行为 源码已实现增强的典型场景阅读时建议以当前 web/src/lib/api.ts 的实现为准。领域 API 客户端web/src/api/client.ts 在双通道封装之上定义了完整的领域 API 对象并以 OpenAPI 生成的类型做静态约束。例如sandboxApi覆盖了沙箱的完整生命周期方法HTTP说明listGET/v2/sandboxes分页/按 state、metadata 过滤列表getGET/sandboxes/:id详情killDELETE/sandboxes/:id销毁pausePOST/sandboxes/:id/pause暂停resumePOST/sandboxes/:id/resume恢复默认 body{timeout:15, autoPause:false}setTimeoutPOST/sandboxes/:id/timeout调整存活超时logsGET/v2/sandboxes/:id/logs游标式日志拉取createPOST/sandboxes基于模板创建模板侧同样完备templateApi.create支持 image、instanceType、writableLayerSize、exposedPorts、probePort/probePath、CPU/内存、env、网络策略allowInternetAccess、networkType、allowOut/denyOut、registry 凭证、command/args、DNS 等完整创建参数还有构建状态/日志查询/templates/:id/builds/:buildID/status|logs与模板兼容性矩阵/templates/compat。节点侧clusterApi提供 overview、node 列表、节点隔离/解除隔离PUT/DELETE/nodes/:id/isolation、节点操作流水等运维能力。本地开发代理一份 vite.config.ts 看清端口规划web/vite.config.ts 完整呈现了本地开发的代理布局值得逐条理解server: { port: 5173, proxy: { /opsapi: { target: http://127.0.0.1:3010, rewrite: (path) path.replace(/^\/opsapi/, /api), }, /sandboxes: http://127.0.0.1:3000, /v2/sandboxes: http://127.0.0.1:3000, /templates: http://127.0.0.1:3000, /snapshots: http://127.0.0.1:3000, /health: http://127.0.0.1:3000, /cubeapi: http://127.0.0.1:3000, }, },关键信息:3000是 CubeAPISDK/E2B 端点Vite 将 SDK 路径直连代理过去:3010是 CubeOps运维/管理端点/opsapi前缀在代理时被重写为/api注释明确解释只代理具体 API 路径而非proxy all是为了避免与 Vite 自身的静态文件服务冲突。生产部署nginx 同源架构与 Docker host-gatewayREADME 描述的线上拓扑是一键部署中由标准 nginx 容器发布 12088 端口挂载打包好的webui/dist并通过 Dockerhost-gateway把/cubeapi代理到宿主机的 CubeAPI。对应配置可在 deploy/one-click/webui/ 目录验证。容器编排docker-compose.yaml.template 展示了 webui 容器的挂载与健康检查services: webui: image: __WEB_UI_IMAGE__ restart: unless-stopped ports: - __WEB_UI_HOST_PORT__:80 extra_hosts: - host.docker.internal:host-gateway volumes: - __WEB_UI_DIST_DIR__:/usr/share/nginx/html:ro - __WEB_UI_NGINX_CONF__:/usr/local/openresty/nginx/conf/nginx.conf:ro healthcheck: test: [CMD-SHELL, wget -q -O /dev/null http://127.0.0.1/] interval: 10s timeout: 3s retries: 6extra_hosts中的host.docker.internal:host-gateway即 README 所说通过 host-gateway 访问宿主机服务的落点nginx 配置中的__*__占位符由部署脚本在渲染阶段替换为实际地址。同源反向代理的精妙之处deploy/one-click/webui/nginx.conf 是线上流量入口几个关键 location 值得细读/opsapi/→ CubeOpsrewrite到/api/并开启client_max_body_size 8gproxy_request_buffering off适配仓库组件大文件上传场景/cubeapi/v1/→ CubeOps重写为/api/v1/sdk/让前端SDK_BASE/cubeapi/v1/*的请求直达走 JWT 鉴权的 SDK 通道~ ^/(sandboxes|v2/sandboxes|templates|snapshots)这是最值得借鉴的 SPA 技巧——nginx 用$http_authorization区分浏览器导航与API 调用无 Authorization 头返回 418再由error_page 418 spa_fallback落到 SPA 的index.html实现 SDK 路径下的前端路由刷新不 404同时以Vary: Authorization避免缓存串扰/sandbox/长连接代理转发 OpenClaw 网关的 WebSocket/UI 流量到 cube-proxy超时放宽到 7206 秒并利用map $http_upgrade $connection_upgrade只在真实握手时才发 Upgrade 头静态资源缓存/assets/一年强缓存 immutable/走try_filesSPA 回退。前端实现的几个值得关注的细节数据轮询与缓存策略web/src/main.tsx 中 QueryClient 默认retry: 1、refetchOnWindowFocus: false、staleTime: 2000ms。各页面按数据实时性要求设置不同的refetchInterval以 web/src/pages/Overview.tsx 为例集群概览每 10s 刷新、沙箱列表每 5s 刷新、模板列表每 30s 刷新KPI 卡片据此实时渲染沙箱运行数、CPU/内存利用率。Mock 模式web/src/lib/mockFlag.ts 提供了三种开启 mock 的方式构建时VITE_USE_MOCK1、URL 加?mock1持久化到 localStorage、或手动localStorage.setItem(cube.useMock,1)。启用后 web/src/main.tsx 的 bootstrap 会动态加载 MSWMock Service Worker见 web/src/mocks/让前端可以在后端未就绪时独立开发调试。国际化i18n 与 web/src/locales/ 提供了 en/zh 双语文案overview、sandboxes、templates、nodes 等 22 个命名空间并带语言切换器组件适合多语言团队直接扩展。结语CubeSandbox Dashboard 是一个结构清晰、工程化完备的 AI 沙箱管理控制台前端用 Vite React TS Tailwind 快速构建通过 TanStack Query 管理数据流对后端只暴露 CubeAPI/CubeOps 两个通信面开发态由 Vite 代理打通前后端生产态由 nginx 容器完成同源反向代理、JWT 鉴权分流与 SPA 回退。无论是想快速本地体验三条 Make 命令还是想学习一套SDK 端点 运维端点双通道的前端架构或借鉴Authorization 头区分导航与 API的 nginx 技巧这个仓库都提供了完整可运行的参考实现。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考