ContextQMD
Back to Fastgpt

V4.16.2

document/content/self-host/upgrading/4-16/4162.mdx

4.16.29.1 KB
Original Source

📦 升级指南

1. 删除 Worker 并发配置

V4.16.2 移除了 PARSE_FILE_WORKERS、PARSE_FILE_WORKER_MEMORY_LIMIT_MB、HTML_TO_MARKDOWN_WORKERS 和 TEXT_TO_CHUNKS_WORKERS。升级时请从 .env 或 Docker Compose 的 environment 中删除这些变量，无需配置替代变量。

文件解析 Worker 的硬上限会根据 Node.js 检测到的可用 CPU 并行度自动设置，并考虑容器 CPU 配额和进程亲和性，最少保留 1 个 Worker；实际同时运行的任务数还会受到文件解析内存调度限制。

HTML 转 Markdown 和文本切块 Worker 的硬上限为可用 CPU 并行度与 5 中的较小值。任务启动前会检查系统安全预留之外是否还有可调度内存；没有余量时继续排队，任务完成后会立即重试一次，仍不足时每 30 秒检查一次，最长等待 30 分钟。空闲 Worker 超过 60 秒后会自动回收，最多长时间保留 1 个。

2. 镜像更新

3. 清理并迁移资源权限数据(商业版执行)

本版本会先清理无效资源权限，再将 App、Dataset 和 Agent Skill 的资源权限补齐为完整有效 ACL。升级后请先执行 dry-run；dry-run 不会删除或写入权限数据。默认处理所有团队，也可以通过 teamId 指定单个团队。

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

确认 migration.errors 为空或已完成异常资源处理后，执行正式清理和迁移：

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

teamConcurrency 控制 ACL 迁移同时处理的团队数，范围为 1 到 1000，默认值为 100。同一团队内的 App、Dataset 和 Agent Skill 依次处理。单个团队的某类资源处理失败时，会将异常写入 migration.errors 并继续处理其他资源类型和团队。sampleLimit 控制 cleanup.samples 返回的无效权限样本数。返回结果分为 cleanup 和 migration 两部分：cleanup 包含扫描、命中和删除统计；migration.resourceCount 是扫描资源数，migration.updatedResourceCount 是需要写入的资源数，migration.skippedResourceCount 是因父级缺失或树结构异常而跳过的目标资源数，migration.errors 包含异常详情。迁移保留资源自身的 owner 和子级权限，父级资源链会按需读取，继承开关缺失的历史资源按启用继承处理。

dry-run 中的迁移预览基于清理前的当前权限数据；如果 cleanup 命中了无效权限，正式执行清理后的迁移统计可能与预览不同。

正式清理和迁移可安全重复执行；完成后再次执行 dry-run，确认 cleanup.danglingPermissionCount、migration.updatedResourceCount 和 migration.errors 均为 0。存在 migration.errors 时应先根据资源类型、资源 ID 和父级 ID 修复数据，再重试。

4. 使用 Milvus 向量库时升级全文检索

如果当前向量库是 Milvus，升级 FastGPT 前必须先将 Milvus 升级到 2.5.16 或更高版本。V4.16.2 会把全文检索自动切换到 Milvus BM25，并使用新的 modeldata_v2 集合存储向量和全文；Milvus 版本过低、版本无法识别或 BM25 能力校验失败时，FastGPT 会终止启动，不会回退到 MongoDB 全文检索。

已有 Milvus 部署升级时，必须确认旧向量数据仍然存在：

  • 旧 Milvus modeldata 集合存在且有数据：调用 GET /api/admin/4162/milvus，将旧向量和 MongoDB 中的索引文本合并迁移到 modeldata_v2，无需重新生成嵌入。
  • 使用 PG、OceanBase、SeekDB 或 openGauss 时无需执行此步骤，全文检索仍使用 MongoDB $text。

备份、Milvus 镜像升级、dry-run、断点续跑、结果校验、旧表清理和回滚步骤请严格按照 Milvus BM25 全文检索配置与迁移 执行。

🚀 新增内容

  1. 支持韩语。
  2. 技能切换版本时增加覆盖提示。
  3. 支持账号注销。
  4. 使用 Milvus 作为向量库时，支持基于 modeldata_v2 单表的 BM25 全文检索。
  5. 文档解析新增支持 DOC、WPS、DOCM、PPT、PPS、POT、PPTM、PPSX、PPSM、XLS、XLSM、XLSB、ODT、ODS、ODP、RTF 和 EPUB 格式。解析器识别到的内嵌图片会提取并上传到对象存储，在解析结果中保留图片引用；未识别的图片形态仍会回退为可解析的文本内容。
  6. 所有节点支持工具调用，并且优化部分节点输入输出交互。

⚙️ 优化

  1. 优化账号页整体 UI 和移动端适配。
  2. 管理员页和模型提供商路由。
  3. S3 分块上传网络抖动优化。
  4. 文件上传错误提示统一文案。
  5. 优化技能保存时，结构化提取 name 和 description，允许空 description。
  6. 连续工具调用异常检查，提高判断精确性，不再只判断调用次数和工具数量，改成判断相同工具且相同参数，连续调用超过 5 次，认为是模型幻觉异常。
  7. Agent 调用工具报错时保留完整工具响应，并在 nodeResponse、toolResponse 及流式事件中同步展示失败信息。
  8. 统一 Workflow Tool 与 ToolCall/Agent 的子工作流输出和计费归集：商业版工具执行失败不收取调用费或 Token 费用，个人 Workflow Tool 的 pluginOutput.error 保留为业务字段。
  9. 将增强 PDF 解析费用归集到 read_files 工具节点并保留页数明细；知识库外部文件和 API 文件解析传递 usageId，避免费用归属丢失。
  10. 优化工具配置、版本选择和解析文档展示，支持响应式布局、版本说明、两列网格及长文件名省略提示。
  11. 加固代码沙盒执行 js 代码时安全问题。

🐛 修复

  1. 修复 admin 模板市场头像显示问题。
  2. 系统工具卸载后重装失败。
  3. 修复空知识库或仅含一条分块时，导出的备份 CSV 无法重新导入的问题。
  4. 修复历史聊天设置缺少收藏标签或历史成员名称为空时的兼容问题。
  5. 修复自定义 Workflow Tool 的头像配置未按预期展示的问题，并补充系统工具头像兜底。
  6. 修复管理员套餐列表遇到团队已删除的孤立套餐时整个请求失败的问题。
  7. 修复待开票列表丢失订单 ID、历史账单月份格式不一致，以及历史发票缺少联系人电话时列表校验失败的问题。
  8. 修复历史知识库分块参数以数字字符串保存时无法通过校验，以及知识库详情尚未加载完成就发起同步请求的问题。
  9. 修复旧版 App 模板中的历史工作流字段无法按当前结构读取的问题。
  10. 修复文件图标使用模糊后缀匹配，导致 Markdown 文件名包含 DOCX 等文本时错误显示为 DOC 图标的问题；补齐新增文档格式的图标映射，并为 EPUB 增加独立图标。
  11. 修复历史 App 变量的 valueType 为空或 null 时，聊天配置无法通过校验的问题。读取和保存聊天配置时会根据变量输入类型补齐 valueType，无法映射或值非法时回退为 any，并在保存前通过 Zod 校验；已有数据无需执行额外清洗脚本。
  12. 工具调用，对于空参数，错误增加了空的 type: object params。

🛠️ 代码优化

  1. 统一工作流旧版工具参数兼容方案。
  2. 将 App、Dataset 和 Agent Skill 的资源权限改为物化有效 ACL，统一协作者权限变更和继承同步逻辑。
  3. 知识库数据创建接口强制要求 MongoDB session，并为手动插入数据补齐事务，确保主数据、全文检索数据和图片 TTL 状态原子提交。
  4. XLSX 文件解析增加工作表范围、合并单元格和 Worker 内存限制，防止异常文件造成内存占用过高。
  5. 切换支付方式时即时刷新支付弹窗内容。
  6. 优化管理员团队、套餐、支付和用户列表查询，提升用户名搜索和分页性能。
  7. 优化文件解析的内存与并发控制。排队任务只保存轻量文件来源，不再持有完整 Buffer；可信 S3 文件按已知大小预留资源，外部链接在流式下载时按实际字节更新资源占用并执行文件大小和单任务内存硬限制，降低并发解析时的 OOM 风险。
  8. 统一文件解析输入为 FileSource，仅在 Worker 获得执行槽位和初始资源额度后物化文件内容：
    • 可信 S3 来源通过对象元数据获取文件大小，一次性预留物化和解析所需资源；上传阶段已经完成业务大小校验，解析时不重复检查。
    • 不可信外部链接入队时只声明解析器基础资源，下载时检查业务文件上限和单任务永久内存上限，并随实际下载字节单调增加软预留。软预留耗尽当前空闲容量时只阻止后续任务启动，不中断已经运行的下载。
    • 等待队列不设置任务数量或估算资源总量上限，仅保留 30 分钟排队超时；失败、超时或 Worker 退出时会中止未完成下载并释放全部资源预留。
  9. 重构模型选择数据结构。