feat(sandbox): support runtime upgrade and advanced file/command operations (labring#7189)

* feat(sandbox): support edit-debug runtime image upgrade with workspace archive and restore

* feat(sandbox): support multi-select, absolute path copy, zip extraction and command execution

* feat(sandbox): support batch move with rollback, auto-naming zip extract, and debug sandbox rebuild fallback

* refactor(app): generalize ProModal and apply to sandbox upgrade modal

* fix(sandbox): prevent data loss by removing unsafe silent restore fallbacks on edit-debug sandbox upgrade or start

Author: DigHuang

document/content/self-host/upgrading/4-15/41505.en.mdx

@@ -1,21 +1,108 @@
 ---
-title: 'V4.15.0-beta5 (In Progress)'
+title: 'V4.15.0-beta5'
 description: 'FastGPT V4.15.0-beta5 Release Notes'
 ---
 
+## 📦 Upgrade Guide
+
+### 1. Update Environment Variables
+
+Add the `CHAT_TITLE_MODEL` environment variable to `fastgpt` and `fastgpt-pro`. It is used to automatically generate chat titles. For example:
+
+```shell
+CHAT_TITLE_MODEL=deepseek-v4-flash
+```
+
+If Agent Sandbox is enabled, also add the following environment variables to `fastgpt`:
+
+```shell
+# Shared with fastgpt-agent-sandbox-proxy. In production, replace it with a random secret longer than 32 characters.
+AGENT_SANDBOX_PROXY_SECRET=replace_with_32_chars_random_secret
+# Browser-accessible WebSocket URL for agent-sandbox-proxy. Use wss:// if it is proxied through an HTTPS domain.
+AGENT_SANDBOX_PROXY_URL=ws://{{host}}:1006
+```
+
+### 2. Image Changes
+
+- Update the fastgpt-app (FastGPT main service) image tag to v4.15.0-beta5.
+- Update the fastgpt-pro (FastGPT commercial edition) image tag to v4.15.0-beta5.
+- Update the fastgpt-plugin image tag to v1.0.0-beta5.
+- Update the aiproxy image tag to v0.6.2.
+
+If Agent Sandbox is enabled, also update the following images:
+
+- Add the fastgpt-agent-sandbox-proxy image with tag v0.2.0-beta3.
+- Update the fastgpt-agent-sandbox image tag to v0.2.0-beta3.
+
+Also add the `fastgpt-agent-sandbox-proxy` service to `docker-compose.yml`. The example below uses the China Mainland image registry. For global deployments, change the image to `ghcr.io/labring/fastgpt-agent-sandbox-proxy:v0.2.0-beta3`:
+
+```yml
+fastgpt-agent-sandbox-proxy:
+  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox-proxy:v0.2.0-beta3
+  container_name: fastgpt-agent-sandbox-proxy
+  restart: always
+  ports:
+    - 1006:1006
+  networks:
+    - fastgpt
+  environment:
+    PORT: 1006
+    # Must exactly match AGENT_SANDBOX_PROXY_SECRET in fastgpt.
+    AGENT_SANDBOX_PROXY_SECRET: replace_with_32_chars_random_secret
+    # Internal URL of the main app container. If your service name is not fastgpt, update it accordingly.
+    FASTGPT_APP_URL: http://fastgpt:3000
+    FASTGPT_APP_REQUEST_TIMEOUT_SECS: 10
+    RUST_LOG: info,fastgpt_agent_sandbox_proxy=debug
+    # Configure this only when the upstream sandbox endpoint returns localhost/127.0.0.1 and the proxy container cannot reach it.
+    # AGENT_SANDBOX_PROXY_REWRITE_HOST: host.docker.internal
+```
+
+### 3. Upgrade Script
+
+Archive all old sandbox workspaces to S3 to more thoroughly release inactive sandboxes. Some old sandboxes may fail to install zip packages because of timeouts. Because most old sandboxes are tied to old chats, you may also remove all old sandboxes directly instead of running this script. This script only affects old sandboxes and does not affect newly created sandboxes.
+
+```shell
+curl --location --request POST 'https://{{host}}/api/admin/initSandboxArchive' \
+--header 'rootkey: {{rootkey}}' \
+--header 'Content-Type: application/json' \
+-d '{"runArchive":true,"inactiveDays":0}'
+```
+
 ## Breaking Changes
 
 1. API Key behavior has changed. FastGPT no longer distinguishes between app keys and system keys; only system keys are kept. For OpenAI SDK compatibility, pass the token as `apikey-appId`. Existing API keys remain compatible and continue to work. For details, see the [FastGPT API documentation](../../../openapi/intro).
 
 ## 🚀 New Features
 
 1. The HTTP node now supports ignoring TLS certificate verification, which is useful when calling HTTPS services that use self-signed or internal certificates.
+2. Added an environment variable for maximum folder depth to prevent unlimited nested folders.
+3. Chat windows now support a quick scroll-to-bottom button.
+4. Optimized streaming output animations based on Lobe UI.
+5. Added model-generated chat titles. Configure the `CHAT_TITLE_MODEL` variable to enable this feature.
+6. Adjusted the Skill Edit editing experience.
+7. The HTTP node now supports returning the complete error object.
+8. Knowledge Base search in agent mode now supports permission filtering.
+9. Optimized API key logic by unifying APIKey management and requiring requests to explicitly pass the app context.
+10. Optimized agent context compression.
+11. Added output syntax for quick replies.
 
 ## ⚙️ Improvements
 
 1. HTML output now automatically switches to preview mode after generation, reducing the need to open the preview manually.
-2. Improved long-name display for apps, datasets, files, and folders: names are truncated when they exceed the available width, and the full name is shown when hovering over the name.
+2. Improved long-name display for apps, Knowledge Bases, files, and folders: names are truncated when they exceed the available width, and the full name is shown on hover.
+3. Removed `temperature` and `max_tokens` from all built-in LLM requests to avoid incompatibility with some models.
+4. Improved error prompts for Knowledge Base training failures, including one-click retry for all failed items.
+5. Filtered out invalid Knowledge Base citation markers.
+6. When a tool returns an empty response, FastGPT now automatically fills in `"none"` to avoid errors from some models.
+7. Added a second permission check before system tools run.
+8. Optimized SSRF checks after redirects.
 
 ## 🐛 Bug Fixes
 
 1. Fixed a potential cross-resource file access risk when private S3 object keys were not bound to the already-authorized resource.
+2. Fixed abnormal tool call parameter schemas for `array` and `object` types in Workflow tools.
+3. Fixed a UI offset issue in the portal publish channel.
+
+## Code Improvements
+
+1. Added a length guard for system string processing. When the string is too long, synchronous replacement stops to avoid high CPU load. You can adjust the limit with the `SYSTEM_MAX_STRING_LENGTH_M` environment variable.

document/content/self-host/upgrading/4-15/41505.mdx

@@ -13,13 +13,50 @@ description: 'FastGPT V4.15.0-beta5 更新说明'
 CHAT_TITLE_MODEL=deepseek-v4-flash
 ```
 
+如果启用 Agent Sandbox，`fastgpt` 还需要增加下面环境变量：
+
+```shell
+# 与 fastgpt-agent-sandbox-proxy 共用，生产环境请改为 32 位以上随机密钥
+AGENT_SANDBOX_PROXY_SECRET=replace_with_32_chars_random_secret
+# 浏览器可访问的 agent-sandbox-proxy WebSocket 地址；如已通过 HTTPS 域名代理，请使用 wss://
+AGENT_SANDBOX_PROXY_URL=ws://{{host}}:1006
+```
+
 ### 2. 镜像变更
 
 - 更新 fastgpt-app(fastgpt 主服务) 镜像 tag: v4.15.0-beta5
 - 更新 fastgpt-pro(fastgpt 商业版) 镜像 tag: v4.15.0-beta5
 - 更新 fastgpt-plugin 镜像 tag: v1.0.0-beta5
 - 更新 aiproxy 镜像 tag: v0.6.2
 
+如果启用 Agent Sandbox，需同步更新下面镜像：
+
+- 新增 fastgpt-agent-sandbox-proxy 镜像 tag: v0.2.0-beta3
+- 更新 fastgpt-agent-sandbox 镜像 tag: v0.2.0-beta3
+
+同时在 `docker-compose.yml` 中新增 `fastgpt-agent-sandbox-proxy` 服务。下面示例使用国内镜像源，海外部署可将镜像改为 `ghcr.io/labring/fastgpt-agent-sandbox-proxy:v0.2.0-beta3`：
+
+```yml
+fastgpt-agent-sandbox-proxy:
+  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox-proxy:v0.2.0-beta3
+  container_name: fastgpt-agent-sandbox-proxy
+  restart: always
+  ports:
+    - 1006:1006
+  networks:
+    - fastgpt
+  environment:
+    PORT: 1006
+    # 必须与 fastgpt 中的 AGENT_SANDBOX_PROXY_SECRET 完全一致
+    AGENT_SANDBOX_PROXY_SECRET: replace_with_32_chars_random_secret
+    # 主站容器内网地址；如果服务名不是 fastgpt，请按实际 docker-compose 服务名调整
+    FASTGPT_APP_URL: http://fastgpt:3000
+    FASTGPT_APP_REQUEST_TIMEOUT_SECS: 10
+    RUST_LOG: info,fastgpt_agent_sandbox_proxy=debug
+    # 当上游 sandbox endpoint 返回 localhost/127.0.0.1 且 proxy 容器无法访问时再配置
+    # AGENT_SANDBOX_PROXY_REWRITE_HOST: host.docker.internal
+```
+
 ### 3. 升级脚本
 
 将所有旧的沙盒 workspace 归档到 s3 里，从而更彻底的释放不活跃的沙盒，旧的沙盒可能因为超时安装 zip 失败。因为旧的沙盒大部分关联的是旧的对话，不执行该脚本，直接把旧的沙盒全部移除也可以。该脚本仅影响旧的沙盒，不影响新生成沙盒。

packages/global/common/error/code/sandbox.ts

@@ -6,7 +6,8 @@ const startCode = 510000;
 
 export enum SandboxErrEnum {
   agentSandboxPermissionDenied = 'agentSandboxPermissionDenied',
-  agentSandboxInitializing = 'agentSandboxInitializing'
+  agentSandboxInitializing = 'agentSandboxInitializing',
+  runtimeUpgradeFailed = 'runtimeUpgradeFailed'
 }
 
 const sandboxErr = [
@@ -18,6 +19,10 @@ const sandboxErr = [
     statusText: SandboxErrEnum.agentSandboxInitializing,
     message: i18nT('common:code_error.sandbox_error.agent_sandbox_initializing'),
     httpStatus: 409
+  },
+  {
+    statusText: SandboxErrEnum.runtimeUpgradeFailed,
+    message: i18nT('common:code_error.sandbox_error.runtime_upgrade_failed')
   }
 ];
 

packages/global/common/string/utils.ts

@@ -5,3 +5,6 @@ export const getTextValidLength = (chunk: string) => {
 export const isObjectId = (str: string) => {
   return /^[0-9a-fA-F]{24}$/.test(str);
 };
+
+/** Shell 单参数安全转义，用于拼接传给 sandbox 的命令。 */
+export const shellQuote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;

packages/global/core/chat/type.ts

@@ -57,6 +57,10 @@ export type SandboxStatusPhase =
   | 'downloadingPackage' // downloading skill package from MinIO
   | 'uploadingPackage' // uploading package into sandbox container
   | 'extractingPackage' // extracting package in sandbox
+  // Runtime image upgrade phases
+  | 'runtimeUpgradeRequired' // existing edit-debug sandbox uses an outdated runtime image
+  | 'runtimeUpgradeArchiving' // archiving workspace before recreating with current image
+  | 'runtimeUpgradeArchived' // outdated runtime is archived or removed; caller should refresh/restart
   // Lazy-init phases
   | 'lazyInit' // LLM first calls sandbox tool, triggers container creation
   // Terminal phases

packages/global/openapi/core/ai/skill/api.ts

@@ -152,7 +152,8 @@ export type ImportSkillResponse = z.infer<typeof ImportSkillResponseSchema>;
 
 export const CreateEditDebugSandboxBodySchema = z.object({
   skillId: IdSchema,
-  image: SandboxImageConfigSchema.optional()
+  image: SandboxImageConfigSchema.optional(),
+  archiveForUpgrade: z.boolean().optional()
 });
 export type CreateEditDebugSandboxBody = z.infer<typeof CreateEditDebugSandboxBodySchema>;
 

packages/service/core/ai/sandbox/instance/repository.ts

@@ -325,7 +325,32 @@ export async function markSandboxArchiving(resource: SandboxResourceDoc, inactiv
     },
     {
       $set: {
-        'metadata.archive.state': 'archiving'
+        'metadata.archive.state': 'archiving',
+        'metadata.archive.startedAt': new Date()
+      }
+    },
+    { new: true }
+  ).lean<SandboxResourceDoc | null>();
+}
+
+/**
+ * 用户主动升级 edit-debug runtime 时抢占实例进行归档。
+ *
+ * 该入口不依赖 inactive/stopped 判断，因为升级由 Skill detail 显式触发；
+ * 但仍使用 archive state CAS，避免与恢复、定时归档或重复点击并发抢同一条记录。
+ */
+export async function markSandboxArchivingForRuntimeUpgrade(resource: SandboxResourceDoc) {
+  return MongoSandboxInstance.findOneAndUpdate(
+    {
+      ...buildSandboxResourceRecordFilter(resource),
+      lastActiveAt: resource.lastActiveAt,
+      'metadata.archive.state': { $exists: false }
+    },
+    {
+      $set: {
+        status: SandboxStatusEnum.stopped,
+        'metadata.archive.state': 'archiving',
+        'metadata.archive.startedAt': new Date()
       }
     },
     { new: true }
@@ -394,6 +419,42 @@ export async function clearSandboxArchiveState(resource: SandboxResourceRef) {
   );
 }
 
+/**
+ * 清理用户升级归档的中间状态，并恢复抢占归档前的本地 status。
+ *
+ * 升级归档会临时把 running 实例标为 stopped 来复用 archived CAS；失败时必须恢复原状态，
+ * 否则用户重试前 Mongo 记录会短暂呈现为 stopped。
+ */
+export async function clearSandboxRuntimeUpgradeArchiveState(resource: SandboxResourceDoc) {
+  return MongoSandboxInstance.updateOne(
+    {
+      ...buildSandboxResourceRecordFilter(resource),
+      'metadata.archive.state': 'archiving'
+    },
+    {
+      $set: {
+        status: resource.status
+      },
+      $unset: {
+        'metadata.archive': ''
+      }
+    }
+  );
+}
+
+/**
+ * 清理卡在 runtime 升级归档中的 edit-debug 记录。
+ *
+ * 只允许处理仍处于 archiving 的同一条资源；调用方随后会删除远端资源并从当前发布包重建。
+ * 这里直接删除 Mongo 记录，避免刷新后继续命中 archiving 状态。
+ */
+export async function deleteStaleRuntimeUpgradeArchivingRecord(resource: SandboxResourceDoc) {
+  return MongoSandboxInstance.deleteOne({
+    ...buildSandboxResourceRecordFilter(resource),
+    'metadata.archive.state': 'archiving'
+  });
+}
+
 /**
  * 原子抢占一个已归档实例进行恢复。
  */

packages/service/core/ai/sandbox/runtime/entrypoint.ts

@@ -1,10 +1,11 @@
 import type { ISandbox } from '@fastgpt-sdk/sandbox-adapter';
+import { shellQuote } from '@fastgpt/global/common/string/utils';
 import { getLogger, LogCategories } from '../../../../common/logger';
 import { serviceEnv } from '../../../../env';
 import { isRedisLeaseError, withRedisLease } from '../../../../common/redis/lock';
 import { createAgentSandboxInitializingError } from '../error';
 import type { SandboxPrepareContext, SandboxPrepareStep } from './prepare';
-import { buildRuntimeHash, shellQuote } from './utils';
+import { buildRuntimeHash } from './utils';
 import {
   getRuntimeStateValue,
   readSandboxRuntimeState,

packages/service/core/ai/sandbox/runtime/mirrors.ts

@@ -1,7 +1,8 @@
 import type { ISandbox } from '@fastgpt-sdk/sandbox-adapter';
+import { shellQuote } from '@fastgpt/global/common/string/utils';
 import { getLogger, LogCategories } from '../../../../common/logger';
 import { serviceEnv } from '../../../../env';
-import { buildRuntimeHash, joinSandboxPath, shellQuote } from './utils';
+import { buildRuntimeHash, joinSandboxPath } from './utils';
 import {
   getRuntimeStateValue,
   readSandboxRuntimeState,

packages/service/core/ai/sandbox/runtime/prepare.ts

@@ -1,12 +1,12 @@
 import type { ISandbox } from '@fastgpt-sdk/sandbox-adapter';
+import { shellQuote } from '@fastgpt/global/common/string/utils';
 import {
   injectInputFilesToSandbox,
   readSandboxPwd,
   type SandboxCommandClient,
   type SandboxInputFile
 } from './files';
 import { prepareSandboxRuntimeMirrors } from './mirrors';
-import { shellQuote } from './utils';
 
 export type SandboxPrepareContext = {
   sandbox: ISandbox;