FastGPT

升级指南

配置变更

• 源码部署的 Node.js 版本须满足 ^22.23.4 || ^24.22.1 || ^26.12.1，升级前请先确认运行环境符合该范围。
• DEFAULT_TEAM_BASIC_PERMISSIONS_ENABLED 仍默认 false；启用时，新团队默认全员组除应用、技能和知识库创建权限外，还会获得 API Key 创建权限，已有团队不自动补授。
• Agent 沙盒活跃实例总上限改为通过 AGENT_SANDBOX_MAX 配置，默认 100，应用会话与技能编辑共用额度；原 AGENT_SANDBOX_MAX_EDIT_DEBUG 不再使用。新增 AGENT_SANDBOX_MAX_PER_TEAM 设置单团队上限，默认不限制。商业版管理台中的配额配置优先于环境变量。
• OpenSandbox 新增 AGENT_SANDBOX_CPU_OVERCOMMIT_FACTOR 与 AGENT_SANDBOX_MEMORY_OVERCOMMIT_FACTOR，默认均为 1，取值须不小于 1。仅在 Kubernetes 运行态且 OpenSandbox Server 不低于 v0.2.1 时生效，降低资源预留但保持资源上限不变，仅影响新建或重建的沙盒。
• 商业版管理台新增「向量检索最大并发数」（systemEnv.vectorRecallConcurrency），允许配置 0–1000，默认 0 表示不限制。正数限制所有服务实例、所有向量库的共享召回并发；开源版不启用此限制，无对应环境变量。
• 新增 AUXILIARY_GENERATION_SHOW_RUN_DETAIL，默认 false，控制技能、Agent 和工作流辅助生成的运行详情入口是否展示。
• 应用市场默认地址（MARKETPLACE_URL）更新为 https://v3.marketplace.fastgpt.cn，显式配置的自定义地址继续使用原值。

镜像更新

• 更新 fastgpt-app（FastGPT 主服务）镜像 tag: v4.17.3
• 更新 fastgpt-pro（FastGPT 商业版）镜像 tag: v4.17.3
• 更新 fastgpt-plugin 镜像 tag: v1.2.0
• 更新 fastgpt-code-sandbox 镜像 tag(后续都独立发布，按需更新): v5.0.0
• 更新 AI Proxy 镜像 tag: v0.7.7

升级脚本

系统先完成启动必需任务及其前置依赖链，各 App 实例重载模型后启动业务。以下 3 个新增任务随后在后台自动执行，共享集群最多 3 个并发名额，失败不会阻断无依赖任务；可在管理页查看结果，修复失败数据后重试。

• 回填沙盒实例团队归属（20261009_backfill_agent_sandbox_team_id）：根据来源应用或技能补齐历史实例的团队归属，用于团队配额统计；来源已删除的孤儿记录跳过并计数。
• 回填目录祖先路径（20261022_backfill_folder_ancestor_ids）：重建应用、工具及知识库目录路径，清理非文件夹资源的残留字段。直接挂在其他类型目录树下的文件夹移到本团队根目录，并清理旧父级继承权限；更高层的跨树祖先路径在边界处截断。缺失父级、跨团队或成环等异常记录保留为失败项，修复后重试。
• 迁移系统模型价格至百万单位（20261025_token_prices_per_million）：将历史系统模型价格换算并写入 pricing，保留旧字段原值，跳过已有合法 pricing 的模型；团队模型不参与迁移。

兼容说明

• root 激活与密码：移除 DEFAULT_ROOT_PSW，启动不再覆盖已有 root 密码。新建 root 初始密码为 123456，首次登录需设置新密码；历史 root 未保存 status 时需使用原密码登录并完成激活。日常改密在账号信息页操作，忘记密码时使用 root 密码重置脚本，并显式提供新密码。
• 模型计价单位：LLM 使用 pricing.tiers，其他模型使用 pricing.unitPrice。Token 单价与阶梯 maxInputTokens 上限改为百万 Tokens，TTS 改为每百万字符，STT 仍按每 60 秒，单价最多保留两位小数。升级后确认后台迁移成功并核对系统模型价格；未迁入 pricing 的系统模型暂按免费处理，团队模型免费。
• 工作流编排校验：画布、调试与辅助生成统一遵循编排规则，禁止纯串行回环、跨工具流程连线及多个调用节点共用同一工具入口，允许由有效条件出口控制的回流。工具子流程可读取调用者上游，但不可引用调用者自身尚未产生的输出。旧工作流保留已有连线并可保存草稿，调试和发布前需修正不符合规则的连线。
• 知识库管理权限：修改知识库基本信息、模型配置，以及文件名称、标签、禁用状态等自身属性需要可管理（manage）权限；内容操作继续使用原有编辑权限。移动文件时同时修改属性，也需要该文件的管理权限。
• 知识库导出：/api/core/dataset/exportAll 仅支持单个知识库，目录导出需逐库请求；开启文件级权限时，仅导出当前成员可读文件。
• 对话文件类型：附件分类新增 document 与 unknown；旧 file 入参和历史记录继续兼容，并按文件名、链接及响应信息归类。自定义客户端应兼容新分类，不再仅用 file 判断文档。
• 分页与错误响应：通用分页将超过 500 的 pageSize 按 500 处理，部分接口仍有更小限制；同时传入 offset 和 pageNum 时优先使用 offset，包括 offset=0，非法偏移量不回退为页码。被识别为用户配置错误的 API 请求返回 HTTP 400，接入方需按失败响应处理。

🚀 新增内容

1. [工作流与 Agent] 商业版新增工作流辅助生成，通过自然语言确认方案后，由同一 Agent 连续搭建、校验和修复并交付候选版本，中断后可根据已保存的对话、计划和任务状态继续。候选版本卡片支持赞踩反馈，需手动应用并检查、调试后再保存发布；使用时需有应用编辑权限，并启用辅助生成与沙盒能力。
2. [工作流与 Agent] 用户选择节点及表单的单选、多选字段支持变量引用动态选项，动态选项为空时返回明确错误。
3. [工作流与 Agent] 密码输入、工具密钥与 HTTP/MCP 鉴权请求头支持变量引用，可在运行时使用上游节点或应用变量提供凭据。
4. [模型与计费] 支持团队成员配置专属 AI 模型与渠道，完善资源隔离、鉴权及 AI Proxy 集成；团队所有者可批量替换失效的语言、语音播放和重排模型引用，覆盖知识库、应用及历史版本，并展示处理统计。空值、动态引用与索引模型不参与替换。
5. [团队与权限] 新增账号待激活与首次设置密码流程，root 可在账号信息页改密；激活或改密后保留当前登录会话并清理其他会话。商业版管理台可按全部、活跃、待激活、禁用和注销状态筛选用户。
6. [团队与权限] 创建应用、工具与知识库文件夹时可选择是否继承权限；资源目录导航支持沿父级路径访问被授权的子资源，父目录仅作为导航入口，不额外授予管理权限。
7. [团队与权限] 团队审计补充知识库训练任务重试、删除、切换索引模型，以及资源恢复权限继承等操作记录，保留资源路径和模型标识，支持按事件类型筛选。
8. [对话体验] 支持恢复输入草稿与已成功上传的附件引用，按成员、应用、会话隔离；当前浏览器标签页最多保留 10 份草稿，自最后编辑起保留 1 小时，发送被正式受理后清除。
9. [对话体验] Markdown 支持有限 HTML 渲染，完善富文本组件交互。
10. [工具与渠道] 系统插件的名称、简介、子工具、参数、密钥 Schema 与 README 支持多语言展示，已有工作流节点与 Agent 固定工具保留添加时的语言快照。
11. [工具与渠道] MCP 与外部渠道统一接入团队对话 QPM 限制，超限返回额度和等待时间，外部渠道去重后计数。依赖服务异常时记录日志并跳过检查，避免故障阻断对话。
12. [系统与运维] Agent 沙盒支持系统总配额与团队配额，OpenSandbox Kubernetes 运行态可独立配置 CPU、内存超卖倍率，控制活跃实例数量与资源预留。
13. [系统与运维] 新增按请求头 x-fastgpt-profile: 1 启用的性能采集，汇总阶段耗时、Mongo 操作及进程指标并支持 OTel 上报。
14. [知识库与文件] 新增 [OXR 自部署接入指南](https://doc

📦 升级指南

镜像更新

• 更新 fastgpt-app（FastGPT 主服务）镜像 tag: v4.17.2
• 更新 fastgpt-pro（FastGPT 商业版）镜像 tag: v4.17.2

升级脚本

本次升级包含以下手动触发升级脚本（可在「管理员 > 版本升级」中查看与执行）：

1. 历史分块训练任务迁移（20261008_migrate_chunk_training）：将存量旧版 chunk 训练任务平滑转换为关联正式数据行的新模式。属于手动触发任务（不阻塞服务启动），请在确认集群中所有旧版本 FastGPT App 与 Pro 实例已完全停止、旧任务租约过期后再点击执行。
2. 知识库重建状态迁移（20261009_migrate_dataset_rebuild_status）：依赖上述训练任务迁移完成，属于手动触发任务（不阻塞服务启动），将历史知识库数据行中的旧版 rebuilding 标记和过渡状态统一迁移至全新的 indexStatus 重建状态体系。

🚀 新增内容

1. 知识库数据提前落库与训练链路重构：
   • 解析分块、图片导入及备份/模板导入在内容解析完成后立即落库为可见数据行，全流程绑定唯一 dataId；训练完成后直接把向量与索引写回同一条数据，彻底避免长训练周期中无数据、训练中断残留孤儿数据的问题。
   • 新增数据索引三态流转（parsed -> indexing -> indexed）：待索引数据在检索层天然隔离不被召回，前端提供只读查看，后端对编辑、删除数据及修改索引提供安全拦截；训练失败数据支持直接编辑或删除。
   • QA 拆分一对多优化：源数据直接复用为首条拆分项，其余叶子节点新建预落库数据，入队、数据写入与源任务清理收敛在单数据库事务中。
   • 知识库模型切换与同义词重建优化：仅对已完成索引（indexed）的数据触发重建，待索引数据不参与重建链；同义词重建时自动复用未变更的向量数据，大幅降低重算开销。
   • 训练进度精细化看板：训练弹窗支持按处理模式（Vector、QA 等）分类展示当前阶段的训练进度，优化训练错误查看与重试体验。
2. 知识库与文件列表搜索支持限定在当前目录及子树：在知识库列表或文件集合列表指定目录下搜索时，范围自动限制为当前路径自身及其全部子文件夹下的内容，命中结果平铺展示；在根目录下搜索则保持检索全量内容。底层采用高效内存分桶与层序遍历，并包含成环与最大深度/节点数截断保护。

⚙️ 优化

1. 核心控制台与管理页面迁移至客户端渲染（CSR）并启用浅路由（shallow routing）：将智能体、技能、MCP、系统工具、模板市场、评测等工作台页面，账号中心各模块，管理员后台以及定价页全面迁移为客户端渲染，避免页面切换时的完整 SSR 往返请求与白屏重渲染，显著提升交互响应速度。
2. 国际化（i18n）资源加载性能优化：将客户端语言包打包为单一 chunk 预加载，统一采用安全翻译 hook（useSafeTranslation），移除冗余的 namespace 异步网络请求，减少初始化开销并消除水合闪烁。
3. 异步任务队列（BullMQ）失败保留策略优化：提取共享的 BullMQ 队列与 Worker 默认配置，将所有后台任务（应用删除、知识库删除、知识库同步、评测、S3 文件清理、技能创建/删除、团队删除及商业版账号注销）的失败任务保留策略统一由按时间过期改为按数量保留最新 10,000 条（removeOnFail: { count: 10000 }），并统一采用 5000ms 指数退避重试，防止突发异常时历史失败记录过早丢失，便于任务排查与重放恢复。
4. 系统模型状态探测告警优化：当模型健康状态探测达到最大重试次数全部失败时，错误信息开头自动附带模型名称，便于在告警通知与监控平台中直观识别故障模型。
5. 数字本土化单位格式化进位优化：修复 formatNumberWithUnit 在四舍五入到两位小数后正好达到下一单位时（如 99,999,999 进位到 10000 万、999,999 进位到 1000K），正确使用更高一级的单位（如 1 亿、1M）。
6. 知识库多路召回检索去重时误删不同图片的问题：在融合去重时结合归一化文本与原始图片 imageId，确保描述相同或为空的不同图片均被完整保留。
7. 文件下载 Header 解析（parseContentDispositionFilename）在 filename* 包含损坏编码时解析失败的问题，安全回退到常规 filename 参数，避免下载文件名丢失。

🐛 修复

1. 修复工作流条件判断器（If/Else）「包含/不包含」条件对非字符串值判断异常的问题：针对 any 类型变量在运行时输入数字、布尔等非字符串值的情况，先转为字符串再进行匹配，避免非字符串值直接返回 false 导致「不包含」条件恒为真、流程分支误走向。
2. 修复工作流条件判断器（If/Else）「正则」条件对非字符串值报错的问题：输入非字符串值时自动转换为文本后再匹配；修复引用变量作为正则模式时非字符串值导致 TypeError 的问题，对空模式严格判定为不匹配；并修复条件输入框中示例手机号正则丢失反斜杠导致非法正则报错的问题。
3. 修复开源版与未激活 License 状态下管理员菜单展示问题（#7929）：使用路由白名单严格过滤管理员导航菜单项，防止非白名单子项（如未授权的应用模板）在无 License 时暴露在侧边栏中。
4. 修复系统工具点击「从插件市场安装」跳转路径错误的问题：恢复正确的管理员插件市场路由 /config/tool/marketplace，并完善对应页面布局。
5. 修复知识库列表滚动翻页时触发初始加载骨架屏导致重复加载的问题；并在成员信息同步函数（addSourceMember）中，当关联成员不存在或已离职时回填离职兜底信息，保证列表长度与分页逻辑一致，避免跳页或遗漏数据。
6. 修复聊天输入引导词计数接口权限校验缺失的问题：为 countTotal 接口补全应用读权限校验，未授权成员禁止探测或读取引导词。
7. 修复隐藏应用（Hidden App）同团队成员权限划分不严格的问题：同团队普通成员仅具备应用只读与对话权限，不再默认附带应用聊天日志权限，日志仅对团队管理员开放。
8. 修复 Markdown 图片语法解析时目的地址与可选标题混淆的问题：严格遵循 CommonMark 规范分离图片 destination 与 title，支持尖括号包裹的 URL 与多行标题；知识库图片转存与 alt 描述回填时保留原有的目的地址格式与标题，避免图片链接损坏或解析截断。
9. 修复通用分页参数解析器（parsePaginationRequest）在请求省略 pageSize 时丢失 offset 或 pageNum 的问题，并支持正确识别 offset=0。

🛠️ 代码优化

1. 新增 ClientRouteReadyGate 路由守卫组件与 useRequiredQueryParam hook，集中处理客户端渲染页面路由参数未就绪时的状态拦截与弹窗初始化时序，消除竞态问题。
2. 团队成员管理逻辑重构：在打开编辑成员弹窗前先拉取完整成员信息，避免部分信息未加载时保存导致数据覆盖。

What's Changed

• chore(deploy): bump images to v4.17.1 and sync deployment docs by @c121914yu in https://github.com/labring/FastGPT/pull/7900
• fix(dataset): prevent duplicate loading on dataset list scroll by @DigHuang in https://github.com/labring/FastGPT/pull/7899
• fix: include model name in model probe errors by @c121914yu in https://github.com/labring/FastGPT/pull/7915
• fix(global): formatNumberWithUnit 进位到下一单位时显示成 10000万 / 1000K by @kevin9327 in https://github.com/labring/FastGPT/pull/7911
• fix(file): fall back to filename when filename* is invalid by @Guo-Yixin in https://github.com/labring/FastGPT/pull/7909
• fix(api): honor offset and pageNum when pageSize is omitted by @Guo-Yixin in https://github.com/labring/FastGPT/pull/7906

📦 升级指南

镜像更新

• 更新 fastgpt-app（FastGPT 主服务）镜像 tag: v4.17.1
• 更新 fastgpt-pro（FastGPT 商业版）镜像 tag: v4.17.1
• 更新 fastgpt-plugin 镜像 tag: v1.1.4
• 更新 AI Proxy 镜像 tag: v0.7.3

升级脚本

本次升级包含以下自动化脚本

1. 回填应用资源权限快照，清理遗留 V1 应用及版本数据，并校验应用正式版本；迁移任务不阻塞服务启动，可在系统升级任务中查看进度和失败记录。
2. 为兼容渠道启用 reasoning 映射：为现有 AIProxy OpenAI 协议渠道开启 map_reasoning_to_reasoning_content: true 的响应字段转换，解决深度思考模型（如 DeepSeek-R1）的思考内容字段兼容问题，并保留渠道的原有配置；已配置该项的渠道不会重复更新，迁移任务不阻塞服务启动。
3. 升级知识库标签数据：将存量 Collection 标签迁移为类型化标签，并清理重复标签定义；迁移任务不阻塞服务启动。
4. 回填团队成员名设置标记：为历史团队成员回填 isSetMemberName 标记；owner 始终标记为已设置，非 owner 中与登录用户名相同的成员名标记为需要补充；迁移任务不阻塞服务启动。

管理员入口调整

商业版管理界面已并入 FastGPT 主应用，root 用户登录后可从「管理员」入口访问系统配置、运营管理和 License 激活、续期页面。系统配置位于 /admin/settings/*，系统工具和系统模型分别位于 /admin/resources/tool 和 /admin/resources/model。旧路径不再保留。

FastGPT Pro 服务仍需保留；若为 Pro 配置了自定义健康检查，请将探测路径调整为 /api/health。

🚀 新增内容

1. 应用发布版本新增资源权限快照和运行时授权，静态资源按发布时快照校验，动态资源按实际运行用户校验。解决协作开发的应用，运行时权限分散导致无法正确计算问题。
2. 新增知识库标签管理与筛选，支持类型化标签值、集合标签维护，以及在工作流和 Agent V2 知识库搜索中使用标签条件。
3. 修改密码支持第三方认证，并统一改密授权、验证和密码更新流程。
4. Agent V2 的知识库搜索支持知识库引用，聊天中可展示本次检索实际返回的引用内容。
5. 应用增加 Token 统计看板，用量记录同步展示 Token 消耗。
6. App、Agent、Skill、工具和 Dataset 列表支持批量选择、移动和删除，并根据管理权限限制可操作资源。
7. 管理员功能统一集成到主应用，支持按 License 授权展示管理菜单和功能状态。
8. 文件读取节点调试支持本地上传文件和添加文件链接，并在上传未完成或文件异常时阻止运行。
9. 新增知识库文件级权限（集合级权限）：可按文件/文件夹单独配置协作者，并支持继承与独立态、恢复继承、所有权转移。开关默认关闭，存量知识库行为不变；开启后列表、详情与检索召回均按文件权限逐条鉴权，关闭则清空全部文件权限配置。详见 知识库文件级权限。
10. 系统模型健康状态探测与监控：管理员支持开启系统模型健康状态定时探测，提供 48 小时状态图可视化监控，并支持配置告警 Webhook 和 Token，在模型状态发生变动时触发 Webhook 通知。详见 系统模型配置与监控。
11. 首次登录待办与引导流程：首次登录支持强制要求补齐团队成员显示姓名，自动提示并处理待确认的团队邀请，并统一编排系统公告与企业认证提示等后续弹窗。
12. 系统模型标识符修改：管理员支持通过稳定的 modelId 直接修改系统模型的模型标识符（model），并自动同步更新关联渠道的模型映射与列表。
13. 支持 OFD 文件解析。
14. 新增词元跳动 (TokenDance) 统一 AI API 网关接入文档与示例。
15. 新增 SSO 密码策略：管理员可禁止 SSO 命名空间账号使用平台密码登录和修改密码，登录页会按可用的身份验证方式展示入口。
16. 个人工作流工具支持配置跟随最新发布版本，应用更新后无需重新手动调整工具版本。
17. 工作流新增 off 节点输入类型：专门面向第三方接口传参，界面不渲染该输入，但完整保留参数定义、默认值与校验，且禁止作为 Agent 自动生成参数。
18. 工作流知识库搜索支持字符串（string）类型标签筛选：支持结构化文本和引用变量过滤，并在检索层执行对应匹配逻辑。
19. OpenAPI 开放文档新增「基础功能 - 模型管理」分类与接口，开放公开模型列表、成员可用模型清单和批量模型详情接口，支持通过 API Key 查询当前可用模型。
20. 新增环境变量 DISABLE_MARKETPLACE（默认为 false）：支持隐藏系统工具中的插件市场安装入口，仅保留本地文件导入。
21. 管理员创建用户接口支持显式传入并保存成员显示名称（memberName）。
22. 知识库、技能、应用都增加被使用引用，便于看到该资源被哪些应用引用。

⚙️ 优化

1. 调整知识库集合批量操作栏、标签间距和标签管理空状态。
2. App 日志使用者筛选改为打开筛选框后再加载，支持服务端搜索和分页，移除固定的 100 个使用者限制。
3. 知识库搜索节点支持记录重排前的召回候选集，便于对比检索与重排结果；通过 RETRIEVAL_RESULTS_LIMIT 配置记录上限，默认不记录。
4. 模型选择器将 Beta 模型排在列表末尾。
5. 知识库默认图片模型清空后被自动回填的问题，允许不配置图片模型。
6. 重构管理员系统配置表单交互与布局设计，提供更清晰的分类导航与配置保存体验。
7. 商业版 License 激活支持永久/无到期时间（unlimited expired time），完善无到期时间许可证的显示与校验。
8. 优化中文语言环境下的大数字格式化，正确展示万、亿等本土化单位。
9. 表格默认开启横向滚动并移除多余左右内边距，长表格在窄屏下更易浏览。
10. 工作流数组类型变量收到单个对象的 JSON 字符串时被解析为普通对象、导致循环与并行节点报错「不是数组」的问题，自动将其包装为单元素数组。
11. 从模板添加模型列表支持按模型提供商（Provider）预设顺序排序返回，保持界面模型分组展示整齐一致。
12. 优化会话标题生成规则：首轮仅上传文件或触发自动执行时支持生成本地化固定标题（如「上传文件」/「自动执行」），后续轮次输入提问文本后自动以新问题标题覆盖；用户自定义标题（customTitle）拥有最高优先级且不会被自动覆盖；统一会话历史、日志与导出等处的标题展示与兜底逻辑，并禁止将空值或占位符持久化为标题。
13. 优化多模态消息 Token 估算：多模态内容（图片、音频、视频、文件）在进入 Token 计算 Worker 前使用固定占位符替代 base64、媒体 URL 或二进制数据，避免长 URL 或大二进制数据导致 Token 计算超时或估算严重偏离。
14. 优化找回密码验证流程：在发送验证码前校验输入的账号是否符合邮箱或手机号格式，避免非法账号在打开图形验证码或请求接口时提示参数校验错误。

🐛 修复

1. 工具调用隔离工作流工具运行时状态，并恢复交互节点记忆，避免并发调用相互污染或丢失交互结果。
2. 修复发票抬头表单回填时覆盖现有输入、必填字段校验不完整的问题。
3. 临时对话尚未保存到历史记录时不再显示自定义标题操作，避免修改结果无法保存。
4. 修复 FastGPT Pro 登录后的许可证校验流程，并补充账单相关接口的鉴权校验。
5. 修复同一聊天轮次内并发写入人类消息和 AI 消息导致 MongoDB 事务报错的问题。
6. 修复解析文档中的 HTML 图片无法预览的问题，支持将 HTML 标签内的 S3 对象键转换为预览地址。
7. 修复文本清理误删正文中的 ]]，并修复中文字符之间连续空白未全部清理的问题。
8. 修复提示词编辑器中的变量和 Skill 标签选择、复制及粘贴异常。
9. 修复模型生成 JSON 后追加包含括号的说明文字时，JSON 提取范围错误的问题。
10. 修复 PowerPoint 段落中的软换行被丢弃、导致相邻文本粘连的问题。
11. 修复表格单元格中的反斜杠和 HTML 无表头表格转换为 Markdown 时破坏表格结构的问题。
12. 工具执行失败不再被当作普通聊天错误展示在底部错误卡片中，也不再计入节点响应摘要的错误数。
13. 修复应用聊天测试未提前校验模型可用性的问题，在发送请求前提示具体的模型配置错误。
14. 修复 FastGPT Pro 飞书发布渠道配置 Encrypt Key 时，事件订阅 URL 校验无法正确返回 challenge 的问题。
15. 修复

升级说明

升级到 V4.17.0 前，请先升级到 V4.16.2，并执行完成 V4.16.x 版本要求的所有旧升级脚本。 V4.17.0 的自动升级机制只管理从本版本开始登记的新任务，不会补执行此前版本的历史脚本。

从 4.17.0 版本开始，登记到系统升级机制的任务会自动执行，并通过 lease 抢占避免多节点并发问题，同时支持心跳检测，检查脚本是否活跃。可在 管理员 > 版本升级 中查看升级脚本状态。

分批迁移任务默认每批处理 100 条记录。数据量较大时，可通过 SYSTEM_MIGRATION_BATCH_SIZE 调整为 50～1000。

AI Proxy（必需）

从 V4.17.0 起，必须部署或接入 AI Proxy，并在 FastGPT App 及复用 App/Service 配置的商业版 Admin 服务中设置：

• AIPROXY_API_ENDPOINT：可访问的 AI Proxy 服务根地址，例如 http://aiproxy:3000，不要附加 /v1。
• AIPROXY_API_TOKEN：与 AI Proxy 服务端配置一致的非空管理员 Token。

从 V4.17.0 起，OPENAI_BASE_URL 和 CHAT_API_KEY 已弃用并移除，配置后不再生效。 请从部署环境中删除这两个变量，改用上述 AI Proxy 配置，并在管理员的模型渠道中维护模型服务商地址和密钥。旧的 systemEnv.oneapiUrl/chatApiKey 覆盖配置也不再生效。

缺少任一 AI Proxy 配置会导致启动校验失败，单模型的 requestUrl/requestAuth 不能替代这两个必填项。升级前请确认 AI Proxy 可访问，且管理员 Token 可以访问渠道管理接口；不要把模型服务商的 API Key 当作 AI Proxy 管理员 Token。

CSRF 防御

本版本新增了环境变量用于防御 HTML 标签的 CSRF 工具。

CSRF_ENABLED=true

Code Sandbox seccomp 兼容配置（可选）

Code Sandbox 默认继续启用 seccomp。若宿主机内核不支持应用内 seccomp，进程池初始化会失败；确认可以接受系统调用隔离能力降低后，可为 Code Sandbox 显式设置：

SANDBOX_DISABLE_SECCOMP=true

该配置只关闭 seccomp，chroot、no_new_privs 和 UID/GID 降权仍保持启用。关闭后不再从内核层阻断网络、创建进程、线程和执行二进制等系统调用，不建议在支持 seccomp 的环境中使用。

新建团队默认创建权限（可选）

设置 DEFAULT_TEAM_BASIC_PERMISSIONS_ENABLED=true 后，新建团队时会为默认全员组授予应用、Skill 和知识库创建权限。默认值为 false，仅影响新建团队，不会修改已有团队权限。FastGPT Pro 请在 FastGPT 和 Admin 服务中保持该配置一致，以覆盖各自的团队创建入口，包括企业微信授权建队。

镜像更新

• 更新 fastgpt-app（FastGPT 主服务）镜像 tag: v4.17.0
• 更新 fastgpt-pro（FastGPT 商业版）镜像 tag: v4.17.0
• 更新 fastgpt-plugin 镜像 tag: v1.1.3
• 更新 fastgpt-code-sandbox 镜像 tag: v4.17.0

弃用说明

模型自定义请求地址

模型自定义请求地址将于未来版本弃用，当前版本仍兼容，请都改成渠道进行模型管理。

🚀 新增内容

1. FastGPT SSO Service 新增 LDAP 成员与组织架构同步，并补充不同 SSO Provider 的独立环境变量模板和配置文档。
2. FastGPT SSO Service 新增钉钉用户与部门同步。
3. Workflow Tool 的文件上传字段支持设置为由 Agent 生成；历史文件字段仍默认保持手动上传，避免升级后行为变化。
4. 新增自动系统升级任务管理，可查看升级状态、阶段进度、失败数据和执行结果，并重试失败的非阻塞任务。
5. Agent V2 新增语音播报（TTS）配置，支持关闭播报、浏览器播报或模型播报，并可选择音色、调整语速和试听；配置样式与 Chat Agent 保持一致。
6. AI 对话节点的响应详情新增首 Token 响应时间，统计从发起模型请求到收到首个正文或思考内容的耗时。
7. 团队所有者转让扩展到多团队模式，支持选择团队成员作为新所有者，并通过输入确认降低误操作风险。
8. CSRF 防御，避免外部系统（尤其是 HTML 标签）携带 Cookie 直接请求接口。

⚙️ 优化

1. 优化对话暂停体验：暂停请求写入工作流停止标记后立即返回；客户端收到确认后主动中断当前流式请求，不再等待最多 5 秒。
2. 优化暂停后的内容保留：模型仅输出思考内容、尚未生成正文时暂停，也会持久化已有思考内容，刷新后仍可查看。
3. 优化图片引用展示：图片后仅包含引用标记时，引用标记在图片下方居中显示；正文中的行内引用保持原有布局。
4. 优化生成冲突恢复：当前对话仍在服务端生成时，客户端会识别冲突并恢复原有生成流，避免新增空白消息或错误状态。
5. 优化处理中内容的交互：思考或工具调用的折叠预览支持点击展开，并直接定位到对应详情。
6. 统一工作台 App、Skill、Dataset、模板市场、工具、账号用量、模型看板、API Key、审计日志和 App 日志等列表的筛选交互；按页面提供类型、来源、创建者、成员、分类、时间和排序等筛选，并支持在长选项列表中搜索。
7. App、Skill 和 Dataset 列表新增按创建者与创建时间排序等筛选能力；历史 App 和 Dataset 创建时间由系统升级任务自动补齐。
8. 统一表格多选、日期范围、数字输入、长列表滚动和弹窗等基础交互，改善批量操作和长内容展示体验。
9. App、Dataset 和 Skill 列表及相关资源选择器改为分页加载，并优化虚拟滚动、加载骨架屏和文件夹导航，改善大量资源时的加载与浏览体验。
10. 模型摘要、详情和候选列表按使用场景加载，选择器展开时再加载候选模型，并区分加载中、加载失败和模型不可用状态。
11. 统一工具描述逻辑：工具节点和工具集子工具使用节点简介作为工具调用描述；工具集子工具支持直接编辑描述，并保留历史自定义或主动清空的内容，避免同步工具定义时被覆盖。
12. 表格组件，支持表头和内容分离滚动，同时支持虚拟滚动。

🐛 修复

1. 修复账号注销确认弹窗底部间距、长文本无法正确换行的问题，并优化账号注销邮件模板。
2. 将 DB_MAX_LINK 限制在 10～1000，避免连接数过低影响并发或配置过大造成资源压力；官方部署模板默认使用 20。
3. 修复关闭团队插件安装后，部分上传、URL 安装和安装确认接口仍可绕过功能开关的问题。
4. 修复禁用 XLSX XML 扫描后仍可能继续扫描文件的问题。
5. 修复 HTTP/OpenAPI Tool 输入项的「手动输入 / Agent 生成」模式保存后丢失，以及作为 Agent Tool 或子工作流运行时被错误重置的问题。
6. 修复模型选择未严格区分模型类型、模型最高温度留空时校验失败，以及管理员模型目录与成员可用模型列表排序不一致的问题；同时避免服务启动阶段误清理仍然有效的成员模型缓存。
7. FastGPT Pro 将飞书、企业微信、钉钉和微信公众号等发布渠道收到的非法消息调整为返回明确的客户端错误，避免将请求格式问题误报为服务端故障。
8. FastGPT Pro 修复历史团队成员 role 字段可能覆盖当前权限计算的问题：除团队所有者外，废弃的角色值不再参与权限判断。
9. 修复简易应用和对话 Agent 的隐藏多模态配置导致图片、音频或视频未进入模型请求的问题；工作流中有显式多模态开关的模型切换入口统一清除新模型不支持的选项，切回后不会自动恢复。
10. 修复模型请求字段映射在同名、交换或链式映射时覆盖错误的问题；映射使用已归一化并按模型能力过滤的请求数据，重复目标字段会明确报错。
11. 修复 MCP / HTTP Tool 定义随工作流快照过期或存储不兼容的问题，运行时读取工具定义，并兼容历史工具配置和鉴权信息。
12. 修复 OpenAPI 导入工具未按接口定义发送参数的问题：根据原文将参数分配到 Path、Query、Header 和 JSON Body，支持路径级共享参数，并按 style / explode 序列化数组和浅对象，保留重复 Query 参数名及 JSON Body 中的原始数据类型。
13. 修复 OpenAPI 定义中未传入的可选 Cookie 参数阻断请求的问题；必填参数缺失、实际传入但不支持