Opensandbox (#6651)

* volumn manager

* feat: opensandbox volumn

Author: c121914yu

.claude/CLAUDE.md

@@ -30,7 +30,7 @@ FastGPT 是一个 AI Agent 构建平台,通过 Flow 提供开箱即用的数据
 
 ### Projects (应用程序)
 - `projects/app/` - 主 NextJS Web 应用(前端 + API 路由)
-- `projects/sandbox/` - NestJS 代码执行沙箱服务
+- `projects/code-sandbox/` - Bun + Hono 代码执行沙箱服务
 - `projects/mcp_server/` - Model Context Protocol 服务器实现
 
 ### 关键目录
@@ -55,10 +55,10 @@ FastGPT 是一个 AI Agent 构建平台,通过 Flow 提供开箱即用的数据
 - `cd projects/app && pnpm build` - 构建 NextJS 应用
 - `cd projects/app && pnpm start` - 启动生产服务器
 
-**沙箱 (projects/sandbox/)**:
-- `cd projects/sandbox && pnpm dev` - 以监视模式启动 NestJS 开发服务器
-- `cd projects/sandbox && pnpm build` - 构建 NestJS 应用
-- `cd projects/sandbox && pnpm test` - 运行 Jest 测试
+**代码沙箱 (projects/code-sandbox/)**:
+- `cd projects/code-sandbox && pnpm dev` - 以监视模式启动（Bun）
+- `cd projects/code-sandbox && pnpm build` - 构建沙箱服务
+- `cd projects/code-sandbox && pnpm test` - 运行 Vitest 测试
 
 **MCP 服务器 (projects/mcp_server/)**:
 - `cd projects/mcp_server && bun dev` - 使用 Bun 以监视模式启动

.github/workflows/build-agent-sandbox.yml

@@ -1,13 +1,13 @@
-name: Build fastgpt-sandbox images
+name: Build fastgpt-code-sandbox images
 on:
   workflow_dispatch:
   push:
     paths:
-      - 'projects/sandbox/**'
+      - 'projects/code-sandbox/**'
     tags:
       - 'v*'
 jobs:
-  build-fastgpt-sandbox-images:
+  build-fastgpt-code-sandbox-images:
     permissions:
       packages: write
       contents: read
@@ -56,12 +56,12 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: projects/sandbox/Dockerfile
+          file: projects/code-sandbox/Dockerfile
           platforms: linux/${{ matrix.arch }}
           labels: |
             org.opencontainers.image.source=https://github.com/${{ github.repository }}
-            org.opencontainers.image.description=fastgpt-sandbox image
-          outputs: type=image,"name=ghcr.io/${{ github.repository_owner }}/fastgpt-sandbox,${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-sandbox",push-by-digest=true,push=true
+            org.opencontainers.image.description=fastgpt-code-sandbox image
+          outputs: type=image,"name=ghcr.io/${{ github.repository_owner }}/fastgpt-code-sandbox,${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-code-sandbox",push-by-digest=true,push=true
           cache-from: type=local,src=/tmp/.buildx-cache
           cache-to: type=local,dest=/tmp/.buildx-cache
 
@@ -74,18 +74,18 @@ jobs:
       - name: Upload digest
         uses: actions/upload-artifact@v4
         with:
-          name: digests-fastgpt-sandbox-${{ github.sha }}-${{ matrix.arch }}
+          name: digests-fastgpt-code-sandbox-${{ github.sha }}-${{ matrix.arch }}
           path: ${{ runner.temp }}/digests/*
           if-no-files-found: error
           retention-days: 1
 
-  release-fastgpt-sandbox-images:
+  release-fastgpt-code-sandbox-images:
     permissions:
       packages: write
       contents: read
       attestations: write
       id-token: write
-    needs: build-fastgpt-sandbox-images
+    needs: build-fastgpt-code-sandbox-images
     runs-on: ubuntu-24.04
     steps:
       - name: Login to GitHub Container Registry
@@ -110,7 +110,7 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           path: ${{ runner.temp }}/digests
-          pattern: digests-fastgpt-sandbox-${{ github.sha }}-*
+          pattern: digests-fastgpt-code-sandbox-${{ github.sha }}-*
           merge-multiple: true
 
       - name: Set up Docker Buildx
@@ -119,19 +119,19 @@ jobs:
       - name: Set image name and tag
         run: |
           if [[ "${{ github.ref_name }}" == "main" ]]; then
-            echo "Git_Tag=ghcr.io/${{ github.repository_owner }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Git_Latest=ghcr.io/${{ github.repository_owner }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Ali_Tag=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Ali_Latest=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Docker_Hub_Tag=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Docker_Hub_Latest=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
+            echo "Git_Tag=ghcr.io/${{ github.repository_owner }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Git_Latest=ghcr.io/${{ github.repository_owner }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Ali_Tag=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Ali_Latest=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Docker_Hub_Tag=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Docker_Hub_Latest=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
           else
-            echo "Git_Tag=ghcr.io/${{ github.repository_owner }}/fastgpt-sandbox:${{ github.ref_name }}" >> $GITHUB_ENV
-            echo "Git_Latest=ghcr.io/${{ github.repository_owner }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Ali_Tag=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-sandbox:${{ github.ref_name }}" >> $GITHUB_ENV
-            echo "Ali_Latest=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
-            echo "Docker_Hub_Tag=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-sandbox:${{ github.ref_name }}" >> $GITHUB_ENV
-            echo "Docker_Hub_Latest=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-sandbox:latest" >> $GITHUB_ENV
+            echo "Git_Tag=ghcr.io/${{ github.repository_owner }}/fastgpt-code-sandbox:${{ github.ref_name }}" >> $GITHUB_ENV
+            echo "Git_Latest=ghcr.io/${{ github.repository_owner }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Ali_Tag=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-code-sandbox:${{ github.ref_name }}" >> $GITHUB_ENV
+            echo "Ali_Latest=${{ secrets.FASTGPT_ALI_IMAGE_PREFIX }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
+            echo "Docker_Hub_Tag=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-code-sandbox:${{ github.ref_name }}" >> $GITHUB_ENV
+            echo "Docker_Hub_Latest=${{ secrets.DOCKER_IMAGE_NAME }}/fastgpt-code-sandbox:latest" >> $GITHUB_ENV
           fi
 
       - name: Create manifest list and push
@@ -140,6 +140,6 @@ jobs:
           TAGS="$(echo -e "${Git_Tag}\n${Git_Latest}\n${Ali_Tag}\n${Ali_Latest}\n${Docker_Hub_Tag}\n${Docker_Hub_Latest}")"
           for TAG in $TAGS; do
             docker buildx imagetools create -t $TAG \
-              $(printf 'ghcr.io/${{ github.repository_owner }}/fastgpt-sandbox@sha256:%s ' *)
+              $(printf 'ghcr.io/${{ github.repository_owner }}/fastgpt-code-sandbox@sha256:%s ' *)
             sleep 5
           done

.github/workflows/build-sandbox.yml .github/workflows/build-code-sandbox.yml.github/workflows/build-sandbox.yml renamed to .github/workflows/build-code-sandbox.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        image: [fastgpt, sandbox, mcp_server]
+        image: [fastgpt, code-sandbox, mcp_server]
       fail-fast: false
 
     steps:
@@ -35,10 +35,10 @@ jobs:
             echo "DOCKERFILE=projects/app/Dockerfile" >> $GITHUB_OUTPUT
             echo "DESCRIPTION=fastgpt-pr image" >> $GITHUB_OUTPUT
             echo "IMAGE_NAME=fastgpt" >> $GITHUB_OUTPUT
-          elif [[ "${{ matrix.image }}" == "sandbox" ]]; then
-            echo "DOCKERFILE=projects/sandbox/Dockerfile" >> $GITHUB_OUTPUT
-            echo "DESCRIPTION=fastgpt-sandbox-pr image" >> $GITHUB_OUTPUT
-            echo "IMAGE_NAME=fastgpt-sandbox" >> $GITHUB_OUTPUT
+          elif [[ "${{ matrix.image }}" == "code-sandbox" ]]; then
+            echo "DOCKERFILE=projects/code-sandbox/Dockerfile" >> $GITHUB_OUTPUT
+            echo "DESCRIPTION=fastgpt-code-sandbox-pr image" >> $GITHUB_OUTPUT
+            echo "IMAGE_NAME=fastgpt-code-sandbox" >> $GITHUB_OUTPUT
           elif [[ "${{ matrix.image }}" == "mcp_server" ]]; then
             echo "DOCKERFILE=projects/mcp_server/Dockerfile" >> $GITHUB_OUTPUT
             echo "DESCRIPTION=fastgpt-mcp_server-pr image" >> $GITHUB_OUTPUT

.github/workflows/preview-fastgpt-build.yml

@@ -2,7 +2,7 @@ name: 'Sandbox-Test'
 on:
   pull_request:
     paths:
-      - 'projects/sandbox/**'
+      - 'projects/code-sandbox/**'
   workflow_dispatch:
 
 permissions:
@@ -31,4 +31,4 @@ jobs:
         run: pnpm install
 
       - name: Run Unit Tests
-        run: pnpm --filter=sandbox test
+        run: pnpm --filter=code-sandbox test

.github/workflows/test-sandbox.yaml

@@ -6,8 +6,9 @@ description: 'FastGPT V4.14.10 更新说明'
 
 ## 🚀 新增内容
 
-1. 飞书发布渠道，支持流输出。
-2. 目录最大上限，可通过环境变量配置。
+1. 增加 OpenSandbox docker 部署方案及适配，并支持通过挂载 volumn 进行数据持久化。
+2. 飞书发布渠道，支持流输出。
+3. 目录最大上限，可通过环境变量配置。
 
 ## ⚙️ 优化
 

document/content/docs/self-host/upgrading/4-14/41410.mdx

@@ -240,7 +240,7 @@
   "document/content/docs/self-host/upgrading/4-14/41481.en.mdx": "2026-03-09T12:02:02+08:00",
   "document/content/docs/self-host/upgrading/4-14/41481.mdx": "2026-03-09T17:39:53+08:00",
   "document/content/docs/self-host/upgrading/4-14/4149.en.mdx": "2026-03-23T12:17:04+08:00",
-  "document/content/docs/self-host/upgrading/4-14/4149.mdx": "2026-03-25T14:45:38+08:00",
+  "document/content/docs/self-host/upgrading/4-14/4149.mdx": "2026-03-25T20:20:19+08:00",
   "document/content/docs/self-host/upgrading/outdated/40.en.mdx": "2026-03-03T17:39:47+08:00",
   "document/content/docs/self-host/upgrading/outdated/40.mdx": "2026-03-03T17:39:47+08:00",
   "document/content/docs/self-host/upgrading/outdated/41.en.mdx": "2026-03-03T17:39:47+08:00",

document/data/doc-last-modified.json

@@ -0,0 +1,130 @@
+import { env } from '../../../env';
+import type {
+  OpenSandboxConfigType,
+  OpenSandboxConnectionConfig
+} from '@fastgpt-sdk/sandbox-adapter';
+import type { SandboxStorageType } from './type';
+
+// ---- sealosdevbox ----
+export type SealosConnectionConfig = {
+  baseUrl: string;
+  token: string;
+  sandboxId: string;
+};
+
+export const getSealosConnectionConfig = (sandboxId: string): SealosConnectionConfig => {
+  if (!env.AGENT_SANDBOX_SEALOS_BASEURL || !env.AGENT_SANDBOX_SEALOS_TOKEN) {
+    throw new Error('AGENT_SANDBOX_SEALOS_BASEURL / AGENT_SANDBOX_SEALOS_TOKEN required');
+  }
+  return {
+    baseUrl: env.AGENT_SANDBOX_SEALOS_BASEURL,
+    token: env.AGENT_SANDBOX_SEALOS_TOKEN,
+    sandboxId
+  };
+};
+
+// ---- opensandbox ----
+export const getOpenSandboxConnectionConfig = ({
+  sessionId
+}: {
+  sessionId: string;
+}): OpenSandboxConnectionConfig => {
+  if (!env.AGENT_SANDBOX_OPENSANDBOX_BASEURL) {
+    throw new Error('AGENT_SANDBOX_OPENSANDBOX_BASEURL is required');
+  }
+  return {
+    sessionId,
+    useServerProxy: env.AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY,
+    baseUrl: env.AGENT_SANDBOX_OPENSANDBOX_BASEURL,
+    apiKey: env.AGENT_SANDBOX_OPENSANDBOX_API_KEY,
+    runtime: env.AGENT_SANDBOX_OPENSANDBOX_RUNTIME
+  };
+};
+
+export const buildOpenSandboxCreateConfig = (
+  opts: {
+    volumes?: OpenSandboxConfigType['volumes'];
+    resourceLimits?: OpenSandboxConfigType['resourceLimits'];
+  } = {}
+): OpenSandboxConfigType => {
+  if (!env.AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO) {
+    throw new Error('AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO is required for opensandbox provider');
+  }
+  return {
+    image: {
+      repository: env.AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO,
+      tag: env.AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG
+    },
+    ...(opts.resourceLimits ? { resourceLimits: opts.resourceLimits } : {}),
+    ...(opts.volumes ? { volumes: opts.volumes } : {})
+  };
+};
+
+// ---- volume-manager ----
+export type VolumeManagerConfig = {
+  url: string;
+  token?: string;
+  mountPath: string;
+};
+export type VolumeManagerResult = {
+  volumes: OpenSandboxConfigType['volumes'];
+  storage: SandboxStorageType;
+};
+const vmConfig = {
+  enable: env.AGENT_SANDBOX_ENABLE_VOLUME,
+  url: env.AGENT_SANDBOX_VOLUME_MANAGER_URL!,
+  token: env.AGENT_SANDBOX_VOLUME_MANAGER_TOKEN,
+  mountPath: env.AGENT_SANDBOX_VOLUME_MANAGER_MOUNT_PATH
+};
+export const buildVolumeConfig = (claimName: string, mountPath: string): VolumeManagerResult => {
+  return {
+    volumes: [{ name: 'workspace', pvc: { claimName }, mountPath }],
+    storage: {
+      volumes: [{ name: 'workspace', claimName, mountPath }],
+      mountPath
+    }
+  };
+};
+export const ensureSessionVolume = async (sessionId: string): Promise<string> => {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (vmConfig.token) headers['Authorization'] = `Bearer ${vmConfig.token}`;
+
+  const res = await fetch(`${vmConfig.url}/v1/volumes/ensure`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ sessionId })
+  });
+  if (!res.ok) {
+    throw new Error(`volume-manager error: ${res.status} ${await res.text()}`);
+  }
+  const { claimName } = (await res.json()) as { claimName: string };
+  return claimName;
+};
+export const deleteSessionVolume = async (sessionId: string): Promise<void> => {
+  if (!vmConfig.enable) return;
+  const headers: Record<string, string> = {};
+  if (vmConfig.token) headers['Authorization'] = `Bearer ${vmConfig.token}`;
+
+  const res = await fetch(`${vmConfig.url}/v1/volumes/${encodeURIComponent(sessionId)}`, {
+    method: 'DELETE',
+    headers
+  });
+  if (!res.ok && res.status !== 404) {
+    throw new Error(`volume-manager error: ${res.status} ${await res.text()}`);
+  }
+};
+
+export const getVolumeManagerConfig = async (
+  sandboxId: string
+): Promise<VolumeManagerResult | undefined> => {
+  if (!vmConfig.enable) return undefined;
+  if (!vmConfig.url) {
+    throw new Error(
+      'AGENT_SANDBOX_VOLUME_MANAGER_URL is required when AGENT_SANDBOX_ENABLE_VOLUME=true'
+    );
+  }
+  const claimName = await ensureSessionVolume(sandboxId);
+  const volumeResult = buildVolumeConfig(claimName, vmConfig.mountPath);
+
+  return volumeResult;
+};