document/content/self-host/upgrading/4-16/4160.mdx
4.16.0 需要依赖 proxy 进行静态资源代理访问，如果网关支持 ws 和 http 在同一个端口，则可以只开放一个端口。如果不支持，可以通过设置 PREVIEW_PORT 来设置 http 访问端口。
# ws和http服务的端口
PORT=1006
# http服务的端口，可以覆盖 PORT
PREVIEW_PORT=1007
访问地址以 http:// 或 https:// 开头。单端口部署时，它可以与 AGENT_SANDBOX_PROXY_URL 指向同一域名和端口，但协议分别使用 HTTP(S) 和 WebSocket(S)。强烈建议配置的域名与 FastGPT 主站使用不同的 origin。同源部署会让这些脚本进入主站的同源安全边界，可能访问主站凭证或接口。系统当前不会强制检查 origin 是否隔离。
可以通过访问: https://{{host}}/health 来确认是否可访问。
在 fastgpt-app 和 fastgpt-pro 同时修改变量。
# 浏览器访问 Sandbox 文件预览的 HTTP(S) 地址，这个地址从第一步取。
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# opensandbox 需配置，存储全前缀名（之前是配置在 volumn 镜像环境变量里）
VM_VOLUME_NAME_PREFIX=fastgpt-session
AGENT_SANDBOX_DISK_MB，E2B 相关变量。
| 变量 | 默认值 | 说明 |
|---|---|---|
AGENT_SANDBOX_CPU_COUNT | 1 | Agent Sandbox 单实例 CPU 核数上限。 |
AGENT_SANDBOX_MEMORY_MIB | 2048 | Agent Sandbox 单实例内存上限，单位 MiB。 |
AGENT_SANDBOX_STORAGE_SIZE_GI | 1 | Agent Sandbox 存储容量，单位 Gi；用于 Sealos Devbox 存储上限，以及 OpenSandbox Kubernetes 模式下创建新 PVC。 |
AGENT_SANDBOX_SUSPEND_MINUTES | 60 | 运行中的 Sandbox 未活跃多久后自动暂停，单位分钟。 |
AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS | 7 | 已暂停 Sandbox 未活跃多久后自动归档，单位天。 |
E2B Sandbox Provider 已移除。此前配置过 E2B 的环境需要切换为 opensandbox 或 sealosdevbox，并删除 AGENT_SANDBOX_E2B_API_KEY。
FastGPT、
fastgpt-agent-sandbox-proxy和fastgpt-agent-sandbox的预览协议已同步变更。启用 Agent Sandbox 时必须使用本版本配套镜像，不支持新旧版本混合部署。
本版本开始在系统模型初始化及保存时使用严格 Schema。此前版本保存的数字字符串、字符串形式的价格梯度或缺失字段可能导致初始化校验失败。升级后请先执行 dry-run，查看需要处理的模型配置；dry-run 不会修改数据或刷新缓存：
curl -X POST 'https://你的域名/api/admin/dataClean/cleanSystemModelConfigs' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
确认 invalidSamples 中没有需要人工处理的数据后，执行正式清洗：
curl -X POST 'https://你的域名/api/admin/dataClean/cleanSystemModelConfigs' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
清洗会将合法数字字符串转换为 number、将字符串形式的 priceTiers 转换为数组，并删除非法的可选数字。非法或缺失的必填数字使用系统默认值：LLM 的 maxContext/maxResponse/quoteMaxToken 分别为 16000/16000/13000，Embedding 的 defaultToken/maxToken 分别为 500/3000，价格为 0。functionCall 保持可选，Embedding 缺失的 weight 补为 0。
正式执行会统一写入数据并立即刷新系统模型缓存；即使没有记录需要更新，也会重新构建运行时缓存。接口可安全重复执行；再次 dry-run 时，wouldUpdate 应为 0。无法通过当前完整模型 Schema 的记录不会写入，详情会全部返回在 invalidSamples 中。
本版本将手动模式 HTTP 工具的数组参数改为标准 JSON Schema。升级前创建过手动 HTTP 工具的环境需要执行此迁移；OpenAPI 模式的 HTTP 工具无需迁移，脚本会自动跳过。
先执行 dry-run，查看当前应用及历史版本中的待处理数据。dry-run 不会修改数据：
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
确认结果后执行正式迁移：
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
脚本会先按 HTTP 工具类型筛选应用，再根据这些应用的 appId 迁移对应的历史版本。仅 apiSchemaStr 不存在的手动模式会被处理，其他应用及 OpenAPI 模式不会修改。迁移按批次执行且可安全重试；返回结果中 total.changedDocumentCount 表示发现的待处理文档数，正式执行后可再次 dry-run，确认该值为 0。
本版本将 App Chat 的 Agent Sandbox 从“每个对话一个实例”调整为“同一 App、同一用户共享一个实例”。不同对话的文件仍分别保存在 sessions/<chatId> 目录中，已发布 Skill 则统一保存在共享的 projects 目录中。
如果此前启用过 Agent Sandbox，必须按以下顺序完成旧 Workspace 迁移。未启用过 Agent Sandbox 的环境可以跳过本节。
先执行 dry-run，查看 beta6 Sandbox 字段归一化和旧 Skill Debug Chat 清理的待处理数。dry-run 不会创建资源、访问对象存储或修改数据：
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
查看 dry-run 结果后执行正式迁移。正式迁移会先执行 beta6 归一化，并且只在剩余待处理数归零时，才在同一请求中继续 Workspace 归档：
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
如果 failures 中仅包含 Sandbox source is missing or deleted，并且已确认对应 App 或 Skill 确实不再存在，可以显式跳过这些残留 Sandbox：
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false,"skipError":true}'
skipError 默认为 false，省略时保持严格迁移。该开关只跳过 source 已缺失或已软删除的整个分组，不会归档、删除或迁移其中的 Sandbox；跳过明细通过 skippedCount 和 skipped 返回。归档、对象存储、Provider 和并发控制等其他错误仍会阻断迁移。
迁移会先执行 V4.15.0-beta6 的完整前置逻辑：补齐旧 Sandbox 的 sourceType/sourceId、清理遗留字段、删除无法归属的孤立资源，并清理缺失 sourceType 的旧 Skill Debug Chat 三表数据及私有、公开 Bucket 旧前缀。与 App 同 ID 的 Skill 会跳过 Chat 清理。两类数据重新统计后合计为 normalization.pendingCount；数量不为 0 时不会进入 Workspace 归档。归零后直接归档全部旧 Workspace 并清理旧计算资源，再迁移 Skill，最后按 App、用户聚合到用户级 Sandbox。只要归档阶段存在失败，安装阶段就不会开始。新的 Sandbox 会在 Workspace 安装完成后暂停，首次使用时再按正常流程启动。脚本可安全重试，已完成的归档和迁移不会重复执行；迁移完成后会保留旧归档和旧 MongoDB 记录作为备份。
请检查返回结果中的 normalization.pendingCount、normalizationBlocked、failedCount、failures、skippedCount 和 skipped。只有 normalization.pendingCount 和 failedCount 均为 0，且 normalizationBlocked 为 false 时，才表示所有未跳过的 Sandbox 迁移完成；skipped 中的 Legacy 记录会保留且不会迁移。
metadata，可通过 API、CSV 或 Excel 模板导入 JSON 元数据；检索结果和备份导出会保留该字段。模板导入和备份导入均支持 .csv 和 .xlsx 文件，使用 q、a、index、metadata 表头；q、a、metadata 各一列，index 可多列且顺序任意。Excel 文件仅支持单个工作表且不能包含合并单元格，无法正确解析的 CSV 或 Excel 文件会提示文件格式异常。%、#、?、斜杠等特殊字符时，可能导致上传、解析、预览或下载异常的问题。