ContextQMD
Back to Fastgpt

V4.15.0-beta7

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

4.15.08.7 KB
Original Source

📦 升级指南

该版本为 4.15.0 正式版最后一个版本，如果有部署过 4.15.0-beta 版本的，需要先升级到该版本，执行完所有 beta 期间的升级操作后，再将所有镜像更新至正式版，正式版镜像可看 4.15.0

1. 开源版 config.json 配置移除

config.json 配置文件移除，全部改成环境变量，环境变量为：

dotenv
# MCP Server 代理地址，用于 MCP 使用方式页拼接 SSE 地址（末尾不要带 /）
SSE_MCP_SERVER_PROXY_ENDPOINT=http://localhost:3003
# ==================== PDF 增强解析（可选） ====================
# 自定义 PDF 解析服务地址
# CUSTOM_PDF_PARSE_URL=
# 自定义 PDF 解析服务密钥
# CUSTOM_PDF_PARSE_KEY=
# Doc2x PDF 解析服务密钥
# DOC2X_KEY=
# 合合信息 Textin 服务 App ID
# TEXTIN_APP_ID=
# 合合信息 Textin 服务 Secret Code
# TEXTIN_SECRET_CODE=

# 向量检索 hnsw ef_search 参数，仅对 PG / OB / OpenGauss 生效
HNSW_EF_SEARCH=100
# 向量检索最大扫描数据量，仅对 PG 生效
HNSW_MAX_SCAN_TUPLES=100000

#  ==================== 知识库处理并发控制  ====================
# 知识库文件解析队列最大并发数
DATASET_PARSE_MAX_PROCESS=10
# 向量训练队列最大并发数
VECTOR_MAX_PROCESS=10
# 问答拆分队列最大并发数
QA_MAX_PROCESS=10
# 图片理解模型处理队列最大并发数
VLM_MAX_PROCESS=10

2. 商业版补充 SSE Mcp Endpoint

该配置从 admin 里移除，需要在 fastgpt 服务里增加环境变量:

dotenv
SSE_MCP_SERVER_PROXY_ENDPOINT=http://localhost:3003

3. OpenSandbox 变量更新

OpenSandbox Volume Manager 配置变为必填，并且环境变量改名为：

dotenv
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL=http://localhost:3005
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN=vmtoken

4. 更新镜像

  • 更新 fastgpt-app(fastgpt 主服务) 镜像 tag: v4.15.0-beta7
  • 更新 fastgpt-pro(fastgpt 商业版) 镜像 tag: v4.15.0-beta7

5. 执行工作流 V1 升级 V2 迁移（可选）

该步骤仅需部署过 <4.8 版本 FastGPT 的用户执行。

V4.15.0-beta7 后工作流保存结构统一使用 V2。历史 apps.modules 与 app_versions.nodes 中可能仍存在 V1 结构，升级后建议先执行 V1 -> V2 迁移，再执行后续 V2 脏数据清洗。

迁移脚本位置：projects/app/src/pages/api/admin/dataClean/v1WorkflowToV2.ts。该接口仅用于本次升级迁移，不作为 OpenAPI 对外接口。

接口默认 dry-run，只扫描、转换和执行 PublishAppBodySchema 校验，不写库：

bash
curl -X POST 'https://你的域名/api/admin/dataClean/v1WorkflowToV2' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: 你的ROOT_KEY' \
  -d '{"dryRun":true}'

确认返回统计无误后，将 dryRun 改为 false 执行写入：

bash
curl -X POST 'https://你的域名/api/admin/dataClean/v1WorkflowToV2' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: 你的ROOT_KEY' \
  -d '{"dryRun":false}'

接口参数：

参数类型默认值说明
dryRunbooleantrue是否只扫描验证不写库。

迁移逻辑：

  1. 按 apps.version != 'v2' 且 type 非 folder、httpPlugin、toolFolder 扫描应用。
  2. 对每批 apps，先转换并写入对应 app_versions，再转换并写入 apps，避免中断后遗漏历史版本。
  3. 将 V1 节点字段升级为 V2 节点字段，例如 moduleId -> nodeId、flowType -> flowNodeType。
  4. 未知节点类型会兜底为 emptyNode，非法 valueType 会转为 any。
  5. 缺失 node.name 时用 flowType 兜底，缺失 input.label 时用 input.key 兜底。
  6. 写库前使用 PublishAppBodySchema 校验 nodes、edges、chatConfig，校验失败的文档不会写入，并会记录到接口返回结果。

6. 执行工作流 V2 枚举与结构脏数据清洗

部分历史工作流节点可能把 TypeScript 枚举表达式字符串直接写入 MongoDB，例如：

json
{
  "renderTypeList": ["FlowNodeInputTypeEnum.hidden"],
  "valueType": "WorkflowIOValueTypeEnum.any"
}

正确落库值应为：

json
{
  "renderTypeList": ["hidden"],
  "valueType": "any"
}

该脏数据会影响工作流节点输入渲染和 IO 类型判断。执行 V1 -> V2 迁移后，继续执行 V2 清洗脚本，扫描并修复 apps.modules 与 app_versions.nodes。

接口默认 dry-run，只格式化内存数据并执行 PublishAppBodySchema 校验，不写库：

bash
curl -X POST 'https://你的域名/api/admin/dataClean/initWorkflowData' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: 你的ROOT_KEY' \
  -d '{"dryRun":true,"batchSize":1000,"writeBatchSize":10}'

确认返回统计无误后，将 dryRun 改为 false 执行写入：

bash
curl -X POST 'https://你的域名/api/admin/dataClean/initWorkflowData' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: 你的ROOT_KEY' \
  -d '{"dryRun":false,"batchSize":1000,"writeBatchSize":10}'

接口参数：

参数类型默认值说明
dryRunbooleantrue是否只扫描验证不写库。
batchSizenumber1000每批读取文档数量。
writeBatchSizenumber10每次 bulkWrite 的文档数量。线上写入压力大时可调小。

清洗逻辑：

  1. 按批扫描 apps 和 app_versions 中的工作流数据，降低单次读取和写入压力。
  2. 对每条工作流数据执行一次格式化，统一修复历史脏字段、空值、枚举表达式和旧结构兼容问题。
  3. 格式化后使用 PublishAppBodySchema 校验保存接口实际关心的 nodes、edges、chatConfig。
  4. Zod 校验失败的文档只记录在返回结果中，不会写入数据库。
  5. 非 dry-run 时，只写入“发生过格式化变更，且 Zod 校验通过”的文档；未变化文档不会重复写库。

返回结果会分别展示 apps、appVersions 和 total 的统计，包括扫描文档数、可修复文档数、Zod 错误数量、写入成功数量、写入失败数量、枚举表达式统计、变更样本和错误样本。

7. 清理重复 Chat 会话头

部分历史数据可能存在相同 appId + chatId 的重复 chats 会话头，导致新版本创建唯一索引失败。升级后可执行重复会话头清理脚本，保留 updateTime 最新的一条记录；如果 updateTime 相同，则保留 _id 最大的一条。

迁移脚本位置：projects/app/src/pages/api/admin/dataClean/cleanupDuplicateChats.ts。该接口仅用于本次升级迁移，不作为 OpenAPI 对外接口。

接口默认 dry-run，只扫描重复组并返回样本，不删除数据：

bash
curl -X POST 'https://你的域名/api/admin/dataClean/cleanupDuplicateChats' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: 你的ROOT_KEY' \
  -d '{"dryRun":true,"sampleLimit":20}'

确认返回统计无误后，将 dryRun 改为 false 执行删除：

bash
curl -X POST 'https://你的域名/api/admin/dataClean/cleanupDuplicateChats' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: 你的ROOT_KEY' \
  -d '{"dryRun":false,"sampleLimit":20}'

接口参数：

参数类型默认值说明
dryRunbooleantrue是否只扫描统计不删除。
sampleLimitnumber20返回重复组样本数量，取值范围为 0~100。

清理逻辑：

  1. 按 appId + chatId 扫描 chats 集合中的重复会话头。
  2. 每组保留 updateTime 最新的一条；若时间相同，用 _id 倒序作为稳定兜底。
  3. 非 dry-run 时只删除重复的 chats 会话头，不删除 chatitems 和 chat_item_responses 中的消息内容。
  4. 返回结果包含重复组数量、预计删除数量、实际删除数量和重复组样本。

⚙️ 优化

  1. 虚拟机文件地址使用新 API。

🐛 修复

  1. 修复历史 V1 工作流数据在新版保存结构下无法通过校验的问题。
  2. 修复工作流节点配置中 FlowNodeInputTypeEnum.*、FlowNodeOutputTypeEnum.* 和 WorkflowIOValueTypeEnum.* 枚举表达式字符串脏数据导致输入渲染和 IO 类型判断异常的问题。
  3. AgentV2 mcp 拿不到 schema。
  4. 批量执行节点最后未回写变量更新。
  5. 工作流文本框，ctrl+c 复制文本内容时，会被节点复制抢占，导致无法复制文本。