v4.17.2

## 📦 升级指南

### 镜像更新

- 更新 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
* fix(mq): retain failed jobs by count and extract shared bullmq options by @c121914yu in https://github.com/labring/FastGPT/pull/7907
* fix(workflow): 判断器「正则」条件对非字符串值报错，编辑器里的示例正则本身无效 by @huiq777 in https://github.com/labring/FastGPT/pull/7903
* fix(markdown): separate image destinations from optional titles by @Guo-Yixin in https://github.com/labring/FastGPT/pull/7910
* fix(deploy): define vector network in v4.14 compose template by @576657922 in https://github.com/labring/FastGPT/pull/7914
* docs: add FAQ entries for multimodal download timeout, legacy template import, and reasoning_content by @mafirs in https://github.com/labring/FastGPT/pull/7922
* fix: migrate default STT model to gpt-transcribe by @wamg7193-wq in https://github.com/labring/FastGPT/pull/7920
* perf(dashboard): migrate pages to client-only & enable shallow routing by @DigHuang in https://github.com/labring/FastGPT/pull/7829
* fix(chat): enforce input guide and hidden app permissions by @c121914yu in https://github.com/labring/FastGPT/pull/7926
* fix(workflow): 判断器「包含/不包含」对非字符串值恒返回 false by @D41910 in https://github.com/labring/FastGPT/pull/7924
* fix(dataset): preserve distinct images during search deduplication by @Guo-Yixin in https://github.com/labring/FastGPT/pull/7921
* fix(admin): restore plugin marketplace route by @FinleyGe in https://github.com/labring/FastGPT/pull/7928
* feat(dataset): 知识库数据训练链路优化与提前落库索引重构 by @c121914yu in https://github.com/labring/FastGPT/pull/7861
* fix(admin): hide non-whitelisted menu items without license by @FinleyGe in https://github.com/labring/FastGPT/pull/7929
* feat(dataset): 搜索范围限定在当前路径及其子树 by @SteelHe in https://github.com/labring/FastGPT/pull/7893
* docs: add FastGPT v4.17.2 upgrading release notes by @c121914yu in https://github.com/labring/FastGPT/pull/7930

## New Contributors
* @Guo-Yixin made their first contribution in https://github.com/labring/FastGPT/pull/7909
* @huiq777 made their first contribution in https://github.com/labring/FastGPT/pull/7903
* @576657922 made their first contribution in https://github.com/labring/FastGPT/pull/7914
* @wamg7193-wq made their first contribution in https://github.com/labring/FastGPT/pull/7920
* @D41910 made their first contribution in https://github.com/labring/FastGPT/pull/7924

**Full Changelog**: https://github.com/labring/FastGPT/compare/v4.17.1...v4.17.2