perf: deploy doc

deploy/templates/docker-compose.dev.yml

@@ -10,6 +10,38 @@
 #   - aiproxy: 3010
 # - 使用 pgvector 作为默认的向量库
 
+# plugin auth token
+x-plugin-auth-token: &x-plugin-auth-token 'token'
+# code sandbox token
+x-code-sandbox-token: &x-code-sandbox-token 'codesandbox'
+# volume manager auth token
+x-volume-manager-auth-token: &x-volume-manager-auth-token 'vmtoken'
+# aiproxy token
+x-aiproxy-token: &x-aiproxy-token 'token'
+# 数据库连接相关配置
+x-share-db-config: &x-share-db-config
+  MONGODB_URI: mongodb://myusername:mypassword@mongo:27017/fastgpt?authSource=admin
+  DB_MAX_LINK: 100
+  REDIS_URL: redis://default:mypassword@redis:6379
+  # @see https://doc.fastgpt.cn/docs/self-host/config/object-storage
+  STORAGE_VENDOR: minio # minio | aws-s3 | cos | oss
+  STORAGE_REGION: us-east-1
+  STORAGE_ACCESS_KEY_ID: minioadmin
+  STORAGE_SECRET_ACCESS_KEY: minioadmin
+  STORAGE_PUBLIC_BUCKET: fastgpt-public
+  STORAGE_PRIVATE_BUCKET: fastgpt-private
+  STORAGE_EXTERNAL_ENDPOINT: http://192.168.0.2:9000 # 一个服务器和客户端均可访问到存储桶的地址，可以是固定的宿主机 IP 或者域名，注意不要填写成 127.0.0.1 或者 localhost 等本地回环地址(因为容器里无法使用)
+  STORAGE_S3_ENDPOINT: http://fastgpt-minio:9000 # 协议://域名(IP):端口
+  STORAGE_S3_FORCE_PATH_STYLE: true
+  STORAGE_S3_MAX_RETRIES: 3
+# Log 配置
+x-log-config: &x-log-config
+  LOG_ENABLE_CONSOLE: true
+  LOG_CONSOLE_LEVEL: debug
+  LOG_ENABLE_OTEL: false
+  LOG_OTEL_LEVEL: info
+  LOG_OTEL_URL: http://localhost:4318/v1/logs
+
 services:
   # Vector DB
   pg:
@@ -134,19 +166,57 @@ services:
       interval: 30s
       timeout: 20s
       retries: 3
-  sandbox:
-    container_name: sandbox
+  code-sandbox:
+    container_name: code-sandbox
     image: ${{fastgpt-sandbox.image}}:${{fastgpt-sandbox.tag}}
     ports:
       - 3002:3000
     networks:
       - fastgpt
     restart: always
+    environment:
+      <<: [*x-log-config]
+      LOG_OTEL_SERVICE_NAME: fastgpt-code-sandbox
+      SANDBOX_TOKEN: *x-code-sandbox-token
+      # ===== Resource Limits =====
+      # Execution timeout per request (ms)
+      SANDBOX_MAX_TIMEOUT: 60000
+      # Maximum allowed memory per user code execution (MB)
+      # Note: System automatically adds 50MB for runtime overhead
+      # Actual process limit = SANDBOX_MAX_MEMORY_MB + 50MB
+      SANDBOX_MAX_MEMORY_MB: 256
+
+      # ===== Process Pool =====
+      # Number of pre-warmed worker processes (JS + Python)
+      SANDBOX_POOL_SIZE: 20
+
+      # ===== Network Request Limits =====
+      # Whether to check if the request is to a private network
+      CHECK_INTERNAL_IP: false
+      # Maximum number of HTTP requests per execution
+      SANDBOX_REQUEST_MAX_COUNT: 30
+      # Timeout for each outbound HTTP request (ms)
+      SANDBOX_REQUEST_TIMEOUT: 60000
+      # Maximum response body size for outbound requests
+      SANDBOX_REQUEST_MAX_RESPONSE_MB: 10
+      # Maximum request body size for outbound requests (MB)
+      SANDBOX_REQUEST_MAX_BODY_MB: 5
+
+      # ===== Module Control =====
+      # JS allowed modules whitelist (comma-separated)
+      SANDBOX_JS_ALLOWED_MODULES: lodash,dayjs,moment,uuid,crypto-js,qs,url,querystring
+      # Python allowed modules whitelist (comma-separated)
+      SANDBOX_PYTHON_ALLOWED_MODULES: math,cmath,decimal,fractions,random,statistics,collections,array,heapq,bisect,queue,copy,itertools,functools,operator,string,re,difflib,textwrap,unicodedata,codecs,datetime,time,calendar,_strptime,json,csv,base64,binascii,struct,hashlib,hmac,secrets,uuid,typing,abc,enum,dataclasses,contextlib,pprint,weakref,numpy,pandas,matplotlib
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
+      interval: 30s
+      timeout: 20s
+      retries: 3
   fastgpt-mcp-server:
     container_name: fastgpt-mcp-server
     image: ${{fastgpt-mcp_server.image}}:${{fastgpt-mcp_server.tag}}
     ports:
-      - 3005:3000
+      - 3003:3000
     networks:
       - fastgpt
     restart: always
@@ -157,27 +227,84 @@ services:
     container_name: fastgpt-plugin
     restart: always
     ports:
-      - 3003:3000
+      - 3004:3000
     networks:
       - fastgpt
     environment:
-      - AUTH_TOKEN=token
-      # @see https://fastgpt.cn/docs/self-host/config/object-storage
-      - STORAGE_VENDOR=minio # minio | aws-s3 | cos | oss
-      - STORAGE_REGION=us-east-1
-      - STORAGE_ACCESS_KEY_ID=minioadmin
-      - STORAGE_SECRET_ACCESS_KEY=minioadmin
-      - STORAGE_PUBLIC_BUCKET=fastgpt-public
-      - STORAGE_PRIVATE_BUCKET=fastgpt-private
-      - STORAGE_EXTERNAL_ENDPOINT=https://minio.com # 一个公开的、前端和用户可以直接访问的对象存储连接
-      - STORAGE_S3_ENDPOINT=http://fastgpt-minio:9000 # 协议://域名(IP):端口
-      - STORAGE_S3_FORCE_PATH_STYLE=true
-      - STORAGE_S3_MAX_RETRIES=3
-      - MONGODB_URI=mongodb://myusername:mypassword@mongo:27017/fastgpt?authSource=admin&directConnection=true
-      - REDIS_URL=redis://default:mypassword@redis:6379
+      <<: [*x-share-db-config, *x-log-config]
+      AUTH_TOKEN: *x-plugin-auth-token
+      # 工具网络请求，最大请求和响应体
+      SERVICE_REQUEST_MAX_CONTENT_LENGTH: 10
+      # 最大 API 请求体大小
+      MAX_API_SIZE: 10
+      # 传递给 OTLP 收集器的服务名称
+      LOG_OTEL_SERVICE_NAME: fastgpt-plugin
     depends_on:
       fastgpt-minio:
         condition: service_healthy
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+  # 沙盒控制器：管理 Docker 容器的创建/执行/停止/删除
+  # runtime=docker 模式需要挂载 Docker socket
+  # 配置 docker.host_ip 为宿主机 LAN IP（容器内访问宿主机服务用）
+  opensandbox-server:
+    image: registry.cn-hangzhou.aliyuncs.com/fastgpt/opensandbox-server:v0.1.9
+    container_name: opensandbox-server
+    restart: always
+    ports:
+      - 8090:8090
+    networks:
+      - fastgpt
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock # Docker 模式必须挂载
+    configs:
+      - source: opensandbox-config
+        target: /etc/opensandbox/config.toml
+    environment:
+      SANDBOX_CONFIG_PATH: /etc/opensandbox/config.toml
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:8090/health']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+  # 卷管理微服务：负责幂等创建/删除 Docker named volume 或 k8s PVC
+  volume-manager:
+    image: ${{volume-manager.image}}:${{volume-manager.tag}}
+    container_name: volume-manager
+    restart: always
+    ports:
+      - 3005:3000
+    networks:
+      - fastgpt
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro # Docker 模式必须挂载（只读即可）
+    environment:
+      PORT: 3000
+      VM_RUNTIME: docker
+      VM_AUTH_TOKEN: *x-volume-manager-auth-token # 对应 AGENT_SANDBOX_VOLUME_MANAGER_TOKEN
+      VM_VOLUME_NAME_PREFIX: fastgpt-session # volume 名称前缀
+      VM_LOG_LEVEL: info
+    healthcheck:
+      test:
+        [
+          'CMD',
+          'bun',
+          '-e',
+          "fetch('http://localhost:3000/health').then((res) => { if (!res.ok) throw new Error(String(res.status)); })"
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+  # Pre-pull only: not started by `docker compose up` (uses profile `prepull`).
+  agent-sandbox-image:
+    image: ${{agent-sandbox-image.image}}:${{agent-sandbox-image.tag}}
+    profiles:
+      - prepull
+
   # AI Proxy
   aiproxy:
     image: ${{aiproxy.image}}:${{aiproxy.tag}}
@@ -193,17 +320,17 @@ services:
       - aiproxy
     environment:
       # 对应 fastgpt 里的AIPROXY_API_TOKEN
-      - ADMIN_KEY=aiproxy
+      ADMIN_KEY: *x-aiproxy-token
       # 错误日志详情保存时间（小时）
-      - LOG_DETAIL_STORAGE_HOURS=1
+      LOG_DETAIL_STORAGE_HOURS: 1
       # 数据库连接地址
-      - SQL_DSN=postgres://postgres:aiproxy@aiproxy_pg:5432/aiproxy
+      SQL_DSN: postgres://postgres:aiproxy@aiproxy_pg:5432/aiproxy
       # 最大重试次数
-      - RETRY_TIMES=3
+      RETRY_TIMES: 3
       # 不需要计费
-      - BILLING_ENABLED=false
+      BILLING_ENABLED: false
       # 不需要严格检测模型
-      - DISABLE_MODEL_CONFIG=true
+      DISABLE_MODEL_CONFIG: true
     healthcheck:
       test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/status']
       interval: 5s
@@ -230,3 +357,24 @@ services:
 networks:
   fastgpt:
   aiproxy:
+
+configs:
+  opensandbox-config:
+    content: |
+      [server]
+      host = "0.0.0.0"
+      port = 8090
+      log_level = "INFO"
+
+      [runtime]
+      type = "docker"
+       execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.6"
+
+      [egress]
+      image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.0.1"
+
+      [docker]
+      network_mode = "bridge"
+      # 容器内访问宿主机服务时需要设置为宿主机 IP 或 hostname
+      # macOS/Windows: host.docker.internal；Linux: 宿主机 LAN IP（如 192.168.1.100）
+      host_ip = "host.docker.internal"

deploy/templates/docker-compose.prod.copy.yml

@@ -1,325 +0,0 @@
-# 用于部署的 docker-compose 文件:
-# - FastGPT 端口映射为 3000:3000
-# - FastGPT-mcp-server 端口映射 3005:3000
-# - 建议修改账密后再运行
-
-# plugin auth token
-x-plugin-auth-token: &x-plugin-auth-token 'token'
-# aiproxy token
-x-aiproxy-token: &x-aiproxy-token 'token'
-# 数据库连接相关配置
-x-share-db-config: &x-share-db-config
-  MONGODB_URI: mongodb://myusername:mypassword@mongo:27017/fastgpt?authSource=admin
-  DB_MAX_LINK: 100
-  REDIS_URL: redis://default:mypassword@redis:6379
-  # @see https://doc.fastgpt.cn/docs/self-host/config/object-storage
-  STORAGE_VENDOR: minio # minio | aws-s3 | cos | oss
-  STORAGE_REGION: us-east-1
-  STORAGE_ACCESS_KEY_ID: minioadmin
-  STORAGE_SECRET_ACCESS_KEY: minioadmin
-  STORAGE_PUBLIC_BUCKET: fastgpt-public
-  STORAGE_PRIVATE_BUCKET: fastgpt-private
-  STORAGE_EXTERNAL_ENDPOINT: http://192.168.0.2:9000 # 一个服务器和客户端均可访问到存储桶的地址，可以是固定的宿主机 IP 或者域名，注意不要填写成 127.0.0.1 或者 localhost 等本地回环地址(因为容器里无法使用)
-  STORAGE_S3_ENDPOINT: http://fastgpt-minio:9000 # 协议://域名(IP):端口
-  STORAGE_S3_FORCE_PATH_STYLE: true
-  STORAGE_S3_MAX_RETRIES: 3
-# Log 配置
-x-log-config: &x-log-config
-  LOG_ENABLE_CONSOLE: true
-  LOG_CONSOLE_LEVEL: debug
-  LOG_ENABLE_OTEL: false
-  LOG_OTEL_LEVEL: info
-  LOG_OTEL_URL: http://localhost:4318/v1/logs
-
-# 向量库相关配置
-x-vec-config: &x-vec-config
-${{vec.config}}
-
-version: '3.3'
-services:
-  # Vector DB
-${{vec.db}}
-  mongo:
-    image: ${{mongo.image}}:${{mongo.tag}} # cpu 不支持 AVX 时候使用 4.4.29
-    container_name: mongo
-    restart: always
-    networks:
-      - fastgpt
-    command: mongod --keyFile /data/mongodb.key --replSet rs0
-    environment:
-      - MONGO_INITDB_ROOT_USERNAME=myusername
-      - MONGO_INITDB_ROOT_PASSWORD=mypassword
-    volumes:
-      - ./mongo/data:/data/db
-    healthcheck:
-      test: ['CMD', 'mongo', '-u', 'myusername', '-p', 'mypassword', '--authenticationDatabase', 'admin', '--eval', "db.adminCommand('ping')"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    entrypoint:
-      - bash
-      - -c
-      - |
-        openssl rand -base64 128 > /data/mongodb.key
-        chmod 400 /data/mongodb.key
-        chown 999:999 /data/mongodb.key
-        echo 'const isInited = rs.status().ok === 1
-        if(!isInited){
-          rs.initiate({
-              _id: "rs0",
-              members: [
-                  { _id: 0, host: "mongo:27017" }
-              ]
-          })
-        }' > /data/initReplicaSet.js
-        # 启动MongoDB服务
-        exec docker-entrypoint.sh "$$@" &
-
-        # 等待MongoDB服务启动
-        until mongo -u myusername -p mypassword --authenticationDatabase admin --eval "print('waited for connection')"; do
-          echo "Waiting for MongoDB to start..."
-          sleep 2
-        done
-
-        # 执行初始化副本集的脚本
-        mongo -u myusername -p mypassword --authenticationDatabase admin /data/initReplicaSet.js
-
-        # 等待docker-entrypoint.sh脚本执行的MongoDB服务进程
-        wait $$!
-  redis:
-    image: ${{redis.image}}:${{redis.tag}}
-    container_name: redis
-    networks:
-      - fastgpt
-    restart: always
-    command: |
-      redis-server --requirepass mypassword --loglevel warning --maxclients 10000 --appendonly yes --save 60 10 --maxmemory 4gb --maxmemory-policy noeviction
-    healthcheck:
-      test: ['CMD', 'redis-cli', '-a', 'mypassword', 'ping']
-      interval: 10s
-      timeout: 3s
-      retries: 3
-      start_period: 30s
-    volumes:
-      - ./redis/data:/data
-  fastgpt-minio:
-    image: ${{minio.image}}:${{minio.tag}}
-    container_name: fastgpt-minio
-    restart: always
-    ports:
-      - 9000:9000
-      - 9001:9001
-    networks:
-      - fastgpt
-    environment:
-      - MINIO_ROOT_USER=minioadmin
-      - MINIO_ROOT_PASSWORD=minioadmin
-    volumes:
-      - ./fastgpt-minio:/data
-    command: server /data --console-address ":9001"
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:9000/minio/health/live']
-      interval: 30s
-      timeout: 20s
-      retries: 3
-
-  opensandbox-server:
-    image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/server:v0.1.7
-    container_name: opensandbox-server
-    restart: always
-    networks:
-      - fastgpt
-    extra_hosts:
-      - 'host.docker.internal:host-gateway' # Enable access to host machine
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-    configs:
-      - source: opensandbox-config
-        target: /etc/opensandbox/config.toml
-    environment:
-      - SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:8090/health']
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-  fastgpt:
-    container_name: fastgpt
-    image: ${{fastgpt.image}}:${{fastgpt.tag}} # git
-    ports:
-      - 3000:3000
-    networks:
-      - fastgpt
-    extra_hosts:
-      - 'host.docker.internal:host-gateway' # Enable access to host machine
-    depends_on:
-      - mongo
-      - sandbox
-      - vectorDB
-      - opensandbox-server
-    restart: always
-    environment:
-      <<: [*x-share-db-config, *x-vec-config, *x-log-config]
-      # 前端外部可访问的地址，用于自动补全文件资源路径。例如 https:fastgpt.cn，不能填 localhost。这个值可以不填，不填则发给模型的图片会是一个相对路径，而不是全路径，模型可能伪造Host。
-      FE_DOMAIN:
-      # root 密码，用户名为: root。如果需要修改 root 密码，直接修改这个环境变量，并重启即可。
-      DEFAULT_ROOT_PSW: 1234
-      # 登录凭证密钥
-      TOKEN_KEY: any
-      # root的密钥，常用于升级时候的初始化请求
-      ROOT_KEY: root_key
-      # 文件阅读加密
-      FILE_TOKEN_KEY: filetoken
-      # 密钥加密key
-      AES256_SECRET_KEY: fastgptkey
-
-      # plugin 地址
-      PLUGIN_BASE_URL: http://fastgpt-plugin:3000
-      PLUGIN_TOKEN: *x-plugin-auth-token
-      # sandbox 地址
-      CODE_SANDBOX_URL: http://sandbox:3000
-      # opensandbox server 地址
-      OPENSANDBOX_SERVER_URL: http://opensandbox-server:8090
-      # AI Proxy 的地址，如果配了该地址，优先使用
-      AIPROXY_API_ENDPOINT: http://aiproxy:3000
-      # AI Proxy 的 Admin Token，与 AI Proxy 中的环境变量 ADMIN_KEY
-      AIPROXY_API_TOKEN: *x-aiproxy-token
-
-      # 传递给 OTLP 收集器的服务名称
-      LOG_OTEL_SERVICE_NAME: fastgpt-client
-
-      # 工作流最大运行次数
-      WORKFLOW_MAX_RUN_TIMES: 1000
-      # 批量执行节点，最大输入长度
-      WORKFLOW_MAX_LOOP_TIMES: 100
-      # 对话文件过期天数
-      CHAT_FILE_EXPIRE_TIME: 7
-      # 服务器接收请求，最大大小，单位 MB
-      SERVICE_REQUEST_MAX_CONTENT_LENGTH: 10
-      # HTML 转换最大字符数
-      MAX_HTML_TRANSFORM_CHARS: 1000000
-    volumes:
-      - ./config.json:/app/data/config.json
-  sandbox:
-    container_name: sandbox
-    image: ${{fastgpt-sandbox.image}}:${{fastgpt-sandbox.tag}}
-    networks:
-      - fastgpt
-    restart: always
-    environment:
-      <<: [*x-log-config]
-      LOG_OTEL_SERVICE_NAME: fastgpt-code-sandbox
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
-      interval: 30s
-      timeout: 20s
-      retries: 3
-  fastgpt-mcp-server:
-    container_name: fastgpt-mcp-server
-    image: ${{fastgpt-mcp_server.image}}:${{fastgpt-mcp_server.tag}}
-    networks:
-      - fastgpt
-    ports:
-      - 3005:3000
-    restart: always
-    environment:
-      <<: [*x-log-config]
-      FASTGPT_ENDPOINT: http://fastgpt:3000
-  fastgpt-plugin:
-    image: ${{fastgpt-plugin.image}}:${{fastgpt-plugin.tag}}
-    container_name: fastgpt-plugin
-    restart: always
-    networks:
-      - fastgpt
-    environment:
-      <<: [*x-share-db-config, *x-log-config]
-      AUTH_TOKEN: *x-plugin-auth-token
-      # 工具网络请求，最大请求和响应体
-      SERVICE_REQUEST_MAX_CONTENT_LENGTH: 10
-      # 最大 API 请求体大小
-      MAX_API_SIZE: 10
-      # 传递给 OTLP 收集器的服务名称
-      LOG_OTEL_SERVICE_NAME: fastgpt-plugin
-    depends_on:
-      fastgpt-minio:
-        condition: service_healthy
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
-      interval: 30s
-      timeout: 20s
-      retries: 3
-  # AI Proxy
-  aiproxy:
-    image: ${{aiproxy.image}}:${{aiproxy.tag}}
-    container_name: aiproxy
-    restart: unless-stopped
-    depends_on:
-      aiproxy_pg:
-        condition: service_healthy
-    networks:
-      - fastgpt
-      - aiproxy
-    environment:
-      # 对应 fastgpt 里的AIPROXY_API_TOKEN
-      ADMIN_KEY: *x-aiproxy-token
-      # 错误日志详情保存时间（小时）
-      LOG_DETAIL_STORAGE_HOURS: 1
-      # 数据库连接地址
-      SQL_DSN: postgres://postgres:aiproxy@aiproxy_pg:5432/aiproxy
-      # 最大重试次数
-      RETRY_TIMES: 3
-      # 不需要计费
-      BILLING_ENABLED: false
-      # 不需要严格检测模型
-      DISABLE_MODEL_CONFIG: true
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/status']
-      interval: 5s
-      timeout: 5s
-      retries: 10
-  aiproxy_pg:
-    image: ${{aiproxy-pg.image}}:${{aiproxy-pg.tag}} # docker hub
-    restart: unless-stopped
-    container_name: aiproxy_pg
-    volumes:
-      - ./aiproxy_pg:/var/lib/postgresql/data
-    networks:
-      - aiproxy
-    environment:
-      TZ: Asia/Shanghai
-      POSTGRES_USER: postgres
-      POSTGRES_DB: aiproxy
-      POSTGRES_PASSWORD: aiproxy
-    healthcheck:
-      test: ['CMD', 'pg_isready', '-U', 'postgres', '-d', 'aiproxy']
-      interval: 5s
-      timeout: 5s
-      retries: 10
-networks:
-  fastgpt:
-  aiproxy:
-  vector:
-${{vec.extra}}
-
-configs:
-  opensandbox-config:
-    content: |
-      [server]
-      host = "0.0.0.0"
-      port = 8090
-      log_level = "INFO"
-
-      [runtime]
-      type = "docker"
-       execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.6"
-
-      [egress]
-      image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.0.1"
-
-      [docker]
-      network_mode = "bridge"
-      # 容器内访问宿主机服务时需要设置为宿主机 IP 或 hostname
-      # macOS/Windows: host.docker.internal；Linux: 宿主机 LAN IP（如 192.168.1.100）
-      host_ip = "host.docker.internal"

deploy/templates/docker-compose.prod.yml

@@ -183,11 +183,11 @@ ${{vec.db}}
       AGENT_SANDBOX_OPENSANDBOX_BASEURL: http://opensandbox-server:8090
       AGENT_SANDBOX_OPENSANDBOX_API_KEY:
       AGENT_SANDBOX_OPENSANDBOX_RUNTIME: docker
-      AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox
-      AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG: latest
+      AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO: ${{agent-sandbox-image.image}}
+      AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG: ${{agent-sandbox-image.tag}}
       # Volume 持久化配置（opensandbox provider 下可选）
       AGENT_SANDBOX_ENABLE_VOLUME: true
-      AGENT_SANDBOX_VOLUME_MANAGER_URL: http://volume-manager:3001
+      AGENT_SANDBOX_VOLUME_MANAGER_URL: http://volume-manager:3000
       AGENT_SANDBOX_VOLUME_MANAGER_TOKEN: *x-volume-manager-auth-token
 
       # ==================== 日志与监控 ====================
@@ -306,8 +306,6 @@ ${{vec.db}}
     image: registry.cn-hangzhou.aliyuncs.com/fastgpt/opensandbox-server:v0.1.9
     container_name: opensandbox-server
     restart: always
-    ports: # 生产环境建议不要暴露
-      - 8090:8090
     networks:
       - fastgpt
     volumes:
@@ -332,6 +330,7 @@ ${{vec.db}}
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro # Docker 模式必须挂载（只读即可）
     environment:
+      PORT: 3000
       VM_RUNTIME: docker
       VM_AUTH_TOKEN: *x-volume-manager-auth-token # 对应 AGENT_SANDBOX_VOLUME_MANAGER_TOKEN
       VM_VOLUME_NAME_PREFIX: fastgpt-session # volume 名称前缀
@@ -342,11 +341,16 @@ ${{vec.db}}
           'CMD',
           'bun',
           '-e',
-          "fetch('http://localhost:3001/health').then((res) => { if (!res.ok) throw new Error(String(res.status)); })"
+          "fetch('http://localhost:3000/health').then((res) => { if (!res.ok) throw new Error(String(res.status)); })"
         ]
       interval: 10s
       timeout: 5s
       retries: 5
+  # Pre-pull only: not started by `docker compose up` (uses profile `prepull`).
+  agent-sandbox-image:
+    image: ${{agent-sandbox-image.image}}:${{agent-sandbox-image.tag}}
+    profiles:
+      - prepull
 
   # AI Proxy
   aiproxy: