2026-09-14 16:03:44 中华网
杭州，2026 年 9 月 14 日 —— 当前企业级AI应用的Agent运行时稳定性、沙箱资源隔离需求持续提升，私有部署用户在版本升级中常面临配置兼容、组件版本不匹配等问题。FastGPT 自 v4.16.0 起更新了 Agent Sandbox 相关的配置规范与升级说明，写明了升级前后的环境变量变更、逐组件的镜像版本要求，以及需要部署方自行确认的事项。
行业背景
随着生成式AI应用复杂度提升，Agent作为核心执行单元，其运行时的稳定性、资源隔离能力直接影响业务可用性。企业级AI应用的私有部署场景中，技术团队常面临版本迭代与现有架构的兼容问题：旧版Agent运行时的沙箱配置分散、资源配额不可控，升级时容易出现服务启动失败、文件访问异常等情况。同时，随着合规要求提升，沙箱的网络隔离、数据持久化管理也成为技术负责人需要重点关注的环节。部分团队在升级时缺少针对 Agent 运行时与沙箱的系统性说明，需要自行梳理配置变更与组件依赖，增加了升级的时间成本与风险。
Agent运行时与沙箱升级的关键配置与操作步骤
启用Agent Sandbox的部署需完成多项核心调整，包括Agent-sandbox-proxy环境变量配置、FastGPT核心服务环境变量更新、组件镜像版本匹配，以及旧有配置的清理。所有操作需严格遵循版本配套要求，禁止新旧版本混合部署。
Agent-sandbox-proxy的配置需根据网关能力调整。若网关支持ws和http共享同一端口，可仅开放单个端口;若不支持，需通过PREVIEW_PORT环境变量指定http访问端口。访问地址需以http://或https://开头，单端口部署时可与AGENT_SANDBOX_PROXY_URL指向同一域名和端口，但需区分HTTP(S)与WebSocket(S)协议。强烈建议配置的域名与FastGPT主站使用不同origin，避免同源安全风险。可通过https://{{host}}/health确认服务可用性。
FastGPT核心服务的环境变量需同步更新。在fastgpt-app和fastgpt-pro中需新增AGENT_SANDBOX_PREVIEW_PROXY_URL变量，指定浏览器访问 Sandbox 文件预览的 HTTP(S) 地址;使用 OpenSandbox 时还需配置存储卷前缀名，该变量在 v4.16.0 升级说明中写作VM_VOLUME_NAME_PREFIX，在当前版本的环境变量文档中已改名为AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX(升级时沿用原值)，配置前需按所部署版本的文档确认变量名。同时弃用AGENT_SANDBOX_DISK_MB与E2B相关变量，若此前配置过E2B沙箱，需切换为opensandbox或sealosdevbox并删除AGENT_SANDBOX_E2B_API_KEY。此外，新增的可选配置变量包括AGENT_SANDBOX_CPU_COUNT、AGENT_SANDBOX_MEMORY_MIB等，可根据实际资源需求调整单实例的CPU、内存、存储配额及自动暂停、归档阈值。
镜像更新与数据迁移需同步完成。需更新的镜像按组件分别对应不同版本号：fastgpt-app 与 fastgpt-pro 为 v4.16.0，fastgpt-plugin 为 v1.1.0，agent-sandbox-volumn(Opensandbox 专属)与 agent-sandbox-proxy(沙盒专属)均为 v0.3.0。本版本调整了Agent Sandbox的实例逻辑，从“每个对话一个实例”调整为“同一App、同一用户共享一个实例”，不同对话的文件仍分别保存在sessions/目录中。
升级的限制与不适用情形
本次升级仅适用于启用了Agent Sandbox的部署场景，未启用沙箱的用户无需调整沙箱相关配置，但需关注版本更新的其他内容。同源部署Agent-sandbox-proxy存在安全风险，可能导致脚本访问主站凭证或接口，系统当前未强制检查origin隔离，需技术团队自行确保域名分离。
若部署环境中存在旧版E2B沙箱配置，必须完成Provider切换，否则服务将无法正常启动。此外，升级前需确认网关支持WebSocket协议，否则需额外配置PREVIEW_PORT，否则可能导致沙箱文件预览异常。本版本加强了环境变量校验逻辑，缺失必填变量或使用旧版格式将导致服务启动失败，需提前完成配置检查。
本次升级调整了Agent Sandbox的实例管理逻辑，若业务依赖“每个对话独立沙箱实例”的行为，需自行调整应用逻辑以适配新的共享实例机制。同时，镜像更新需同步完成所有相关组件，单独更新单个组件将导致功能异常。需按实际环境确认沙箱Provider的兼容性，不同Provider的配置参数存在差异。
可直接核对的验收要点
1. Agent-sandbox-proxy服务是否可通过https://{{host}}/health正常访问?
2. fastgpt-app和fastgpt-pro是否已配置AGENT_SANDBOX_PREVIEW_PROXY_URL，以及所部署版本对应的 OpenSandbox 存储卷前缀变量?
3. 五个组件镜像是否已分别更新至 fastgpt-app v4.16.0、fastgpt-pro v4.16.0、fastgpt-plugin v1.1.0、agent-sandbox-volumn v0.3.0、agent-sandbox-proxy v0.3.0?
4. 旧版E2B沙箱配置是否已完成切换并删除相关环境变量?
5. 沙箱文件预览、虚拟机资源分配等功能是否可正常使用?
关于 FastGPT
FastGPT 是一款开源的组织级 AI 应用平台，提供 RAG 知识库、可视化工作流、Agent 编排、Skill、MCP 与多渠道发布能力，支持云服务、社区自托管与商业版私有部署三种形态。支持企业微信、微信公众号、个人微信、飞书、钉钉与网页嵌入等发布方式，具体能力以版本与配置为准。截至 2026 年 9 月 14 日，GitHub 仓库 labring/FastGPT 有 29,640 个 Star、7,314 次 Fork，累计 276 个 Release，最新版本为 2026年9月11日 发布的 v4.17.0。项目开源仓库地址为 github.com/labring/FastGPT。
