V4.18.0

升级指南

配置变更

• HNSW_EF_SEARCH / systemEnv.hnswEfSearch 的默认值从 100 调整为 200，适用于 PostgreSQL、Milvus、OceanBase、SeekDB 和 openGauss；显式配置的值继续生效，可按召回率与查询耗时调整。
• HNSW_MAX_SCAN_TUPLES / systemEnv.hnswMaxScanTuples 不再生效，管理台移除对应设置；PostgreSQL 的扫描上限改按本次索引检索涉及的最大知识库向量行数自动设置，上限为 2147483647，已有部署可移除旧配置。
• 新增 SHOW_OUTLINK_BRAND：未配置 PRO_URL 时固定为 true；接入 Pro 后默认 false，可设为 true 启用品牌展示。前端 show_outlink_brand 由服务端环境派生，覆盖 config.json 中的同名配置。
• 插件服务部署：Docker Compose 模板补齐 fastgpt-plugin 的 FASTGPT_BASE_URL=http://fastgpt-app:3000，将 MONGODB_URI 指向独立的 fastgpt-plugin 数据库，并显式设置 DB_MAX_LINK=100，避免与主库集合混用；自定义部署应填写插件容器可访问的主服务地址。已有部署替换模板前应核对原插件库，保留已使用的独立库连接；若需切换数据库，先备份并迁移既有插件数据。
• 默认部署的对象存储改为 RustFS，已有部署可继续使用原存储，如需切换请参考 MinIO 迁移到 RustFS。

镜像更新

升级脚本

升级前提：先在 4.17.x 完成所需历史迁移，再升级到本版本；4.18.x 已移除旧任务的注册与实现，不会继续执行，数据库中的历史状态和错误明细保留。

新增 初始化知识库向量索引（20261022_initialize_dataset_vector_indexes），仅 PostgreSQL 在启动后于后台自动执行，不阻塞业务：先核验并在线删除旧全局 vector_index，再分批统计有效知识库并投递索引维护任务。任务成功表示统计与投递完成，实际建图由全局串行队列继续执行；清理或扫描失败时，可在升级管理页修复问题后重试，沿已保存的断点继续，同名但定义不匹配的自建索引会保留并报错。

PG 局部索引要求支持 halfvec、固定向量维度在 1–4000 范围内，并具备在线创建、删除索引的权限及足够的内存、共享内存和磁盘资源。索引未就绪或失败期间继续精确检索，可能增加查询耗时；建图失败不会自动降低资源预算重试，排除故障后由下一次真实向量计数重新投递，缓存命中不会触发重试。

新增 回填历史对话调用渠道（20261104_backfill_chat_publish_source），启动后独立在后台批量读写，不阻塞业务，也不等待普通后台长任务；分别为对话与统计记录补齐 publishSource，不修改旧字段、身份、消息或统计计数。历史 API、MCP 及已删除渠道可能只能恢复类型，无法补齐渠道 ID；引用冲突或数据异常会记录失败，修复后可在升级管理页重试并沿断点续跑。

新增 回填 API Key 类型（20261104_backfill_openapi_key_type），启动后独立在后台按固定范围分批扫描，仅为缺失类型的旧密钥按 appId 绑定情况补齐个人或应用类型，不改变凭证、绑定、归属和额度。类型或绑定异常会记录失败项；修复后可在升级管理页重试，沿断点续跑并优先处理失败数据。

兼容说明

• 历史应用密钥：已保存有效 appId 绑定的旧 Key 现按应用 Key 鉴权，请求中的 appId 或 SDK 后缀不再覆盖绑定；原先借此访问其他应用、知识库或模型接口的接入需改用个人密钥，查看、复制与修改应用 Key 需具备绑定应用的管理权限。全部鉴权节点升级后再启用应用 Key，回滚版本也必须识别密钥类型与绑定边界。
• 密钥管理脚本：/api/support/openapi/list 默认仅返回本人的个人密钥，不再按 appId 置顶；查询历史绑定密钥的脚本需显式选择应用类型，更新应用 Key 时按可编辑字段提交，并移除 authProxy 与个人标签字段。
• 团队审计查询：商业版 /proApi/support/user/team/audit/list 新增必填的 dateStart、dateEnd，并要求登录成员具备团队管理权限；已有查询脚本需补齐起止时间并核对调用身份，整日查询应显式提交带偏移的日初至日末。
• 对话运行状态：chatGenerateStatus 改由 Redis 租约计算，仅返回 0（生成中）或 1（空闲），不再持久化到 Mongo 或返回 2（错误）；直接读取数据库状态或依赖错误枚举的接入需改用接口及消息错误信息。升级时先停止旧实例接收新请求并等待生成任务结束，再统一切换生成与状态查询实例，避免新旧互斥机制混用。
• 动态选择选项：用户选择节点及表单单选、多选的变量引用选项，运行时仅保留前 200 个有效项，单项文本最长 100 个 UTF-16 码元，超出部分截断；依赖超长选项值或后续候选项的流程需调整候选数据，并核对下游匹配逻辑。
• 工作流历史记忆：内容提取、问题分类与 Pi Agent 的记忆键改按来源和调用路径隔离，直接读写 ChatItem.memories 的自定义集成需适配新键，不再依赖 agentLoopMemory-${nodeId} 或不含调用路径的子流程键。
• API 身份参数：API 会话不再允许更换使用者，已有会话以保存的身份为准，续聊需保持相同 customUid；已绑定后漏传、清空或更换，以及从默认身份改为自定义身份都会被拒绝，混用使用者的接入需改用独立 chatId。非空 customUid 仅允许 API Key 调用；它与 authProxy 互斥，即使为空字符串也不能同时传入，已有同时传参的接入需保留一种身份。
• 会话 ID 长度：会话管理、文件、引用和沙盒等入口统一将 chatId 限制为最多 1024 个字符；使用超长自定义 ID 的接入需调整生成规则，并核查已有超长会话及相关引用。
• 重复生成响应：非流式 chat/completions 在同会话已有生成时返回 HTTP 409，依赖原错误状态码的自定义客户端需适配冲突响应。
• 日志 CSV：基于「使用者」列解析团队成员的脚本需适配 ID:name 格式（旧版为成员名），成员缺少姓名时仅输出 ID；渠道列拆分为「调用渠道」与「渠道名」，按列名解析的脚本也需适配。
• 应用日志时间参数：应用日志相关接口改为校验 ISO 日期或日期时间，其中图表不再接受数字时间戳；旧脚本需调整非标准格式，整日查询应显式提交带偏移的日初至日末，仅日期或无偏移值按服务器本地时间解释。
• 商业版应用图表口径：统计按请求起点的固定偏移分组，不再读取账号时区，跨夏令时也保持起点偏移；留存仅统计所选窗口内的后续活跃，不再扩展查询，依赖旧口径的报表需显式提供所需偏移并核对留存结果。
• 调用渠道数据：自定义对话查询与日志解析应改用 publishSource；新运行不再写入 Chat.shareId，依赖旧字段查询分享历史的集成需适配，升级期间避免将新建分享会话继续交给旧实例读取。
• Agent 历史上下文：Agent 运行不再读取节点的 history 配置，普通历史窗口统一为最近 50 轮，仍保留系统消息与上下文压缩检查点；依赖零历史或自定义历史数组隔离上下文的应用需重新核对上下文控制与模型用量。
• Agent 文本输出：answerText 和工具响应改为拼接本次 Agent 循环全过程的文本，包含工具调用前的说明；依赖其仅包含最后一段回答的下游节点需调整处理。
• Agent 交互约束：Agent 现按交互节点处理，不能放入并行容器，商业版也不再允许为含 Agent 的应用创建自动评测任务；已有并行 Agent 需移出容器，评测接入需选择不含交互节点的应用版本。
• 嵌套沙盒归属：嵌套 Agent 与工具调用改用根应用会话的沙盒；依赖子应用独立沙盒或按子应用定位文件的流程，需适配根会话归属与父子节点共享工作区的行为。
• 沙盒初始化脚本：工作流 Agent 与工具调用节点按应用、节点分别记录脚本成功状态，不再复用旧全局标记；已有沙盒升级后，配置了脚本的节点首次使用时会重新执行，请确认脚本可安全重复执行。
• 自建 JavaScript 代码沙盒：Linux 启用 seccomp 时新增必需的 fastgpt_js_launcher；自建镜像或源码部署需重新构建并打包原生组件，将启动器与 .node 模块一同部署，缺失启动器时 JavaScript 进程池初始化失败。
• 系统工具管理接口：移除 DELETE /api/core/plugin/admin/tool/delete，仍调用该旧接口的自定义管理端需停止使用。

🚀 新增内容

1. [工具与渠道] 新增绑定单个应用的应用 API Key，在应用发布页与个人密钥分开管理，由应用管理员共同维护，专用于该应用的对话及对话管理，不依赖归属成员的应用权限。商业版按资源交接流程转交密钥归属，删除应用时同步清理绑定密钥。
2. [工具与渠道] 对话及配套管理统一支持外部使用者标识与成员代理，可通过 customUid 进一步限定历史、消息、文件、引用和沙盒等操作的使用者范围；开启代理权限的个人密钥可通过 authProxy 按被代理成员的权限执行。
3. [工具与渠道] 免登录分享页新增适配桌面、移动和嵌入式页面的 FastGPT 标识，启用后新建链接默认展示，桌面访客可在本次访问临时关闭。团队持久隐藏需有效套餐权益，商业版支持按套餐及单条订阅控制；未保存品牌偏好的历史链接继续豁免，已关闭链接在权益失效时恢复展示，保留偏好供权益恢复后生效。
4. [工作流与 Agent] 工作流 Agent 节点可从模板面板添加并作为工具节点供其他 Agent 调用，知识库输入支持变量引用；独立 ChatAgent 应用也可作为工作流子应用或 Agent 工具引用，支持传入文件与交互续跑，便于组合多 Agent 流程。
5. [模型与计费] 模型管理新增拖拽自定义排序，支持保存前取消；root 可调整系统模型，商业版启用团队模型后，具有「安装模型」权限的成员可调整自己的模型顺序。「可用模型」按本人、共享团队、系统模型分组并在组内应用自定义顺序，JSON 配置更新保留排序，客户端的最终系统模型兜底也使用该顺序。
6. [模型与计费] 启用权限配置的模型表格新增创建人展示，系统模型单独标识来源；成员展示页可获取最新创建人资料，外链目录不暴露成员信息。
7. [知识库与文件] 知识库检索结果及引用记录新增重排前的文本召回排名，便于对比召回与重排效果。
8. [团队与权限] 商业版团队审计日志支持按日期、成员和事件组合筛选，默认展示含今天的近 7 个本地自然日，可选择更早日期及停用成员。具备团队管理权限的登录成员可导出全部匹配记录的多语言 CSV，单次最多 50000 条，超量需缩小范围；CSV 中的日志时间按查询起点偏移展示，发起导出会写入审计记录。
9. [团队与权限] 商业版用户管理接口补充所属团队、成员名和部门路径，团队成员列表补充登录用户名，便于管理端区分账号与成员身份。
10. [系统与运维] 对话记录最近一次运行的调用渠道，日志区分展示渠道类型和渠道名称，支持查看渠道 ID；相关筛选、CSV 导出与商业版统计同步采用新渠道分类。
11. [系统与运维] 对话日志新增默认隐藏的「鉴权者」列，与「使用者」分开展示，便于区分接入方用户和实际鉴权成员；API 传入的 customUid 按原值显示为使用者，CSV 按所选列导出。日志表格按内容分配列宽，避免长 UID 挤压成员姓名。

⚙️ 优化

1. [工作流与 Agent] 统一 Agent 表单与工作流节点的工具、技能和知识库卡片及状态校验，运行、发布和单节点调试使用相同规则；失效、下线或未配置资源会明确提示，异步选择与保存保留已有配置。
2. [工作流与 Agent] 商业版工作流 Builder 预览新增标题、简短概述和待确认状态，恢复待确认方案时定位到卡片顶部，后续渲染保留阅读位置；确认、修改与取消仍使用统一交互入口。
3. [工作流与 Agent] 单选、多选配置的选项上限由 50 提高至 200，用户选择节点的手动选项也限制为最多 200 项；单项文本输入最长 100 个 UTF-16 码元。
4. [知识库与文件] PostgreSQL 按知识库维护 FP16 局部 HNSW 索引，向量行数超过 10000 时按需建图，低于 5000 时移除，中间区间保留已有状态；未就绪或无索引的知识库走精确检索，各组候选统一以 FP32 距离排序，原向量存储精度不变。
5. [知识库与文件] 商业版简易应用、ChatAgent 与工作流 Agent 的标签过滤移入搜索参数的「搜索过滤」页签，并补充独立开关；手动输入模式关闭时保留条件，重新开启可继续编辑，参数提示按开关状态显示是否启用；知识库或过滤条件使用变量引用时保留配置，避免误删无法在编辑期确认的标签。
6. [知识库与文件] 将文件上传按身份累计的每分钟限流额度提高至原来的 3 倍，减少连续或批量上传时触发「请求过于频繁」的情况。
7. [模型与计费] 统一移动端模型选择、语音播放、渠道绑定、模型日志与仪表盘筛选中的测试模式模型排序，将测试模式模型置后，同组内保留目录顺序。
8. [模型与计费] 模型管理表格统一表头与表体列宽，按行维护编辑弹窗状态，减少大列表打开弹窗时的整表重渲染。
9. [对话体验] 优化对话历史侧栏状态刷新，长列表分批查询，生成中或请求失败时持续重试；隐藏标签页暂停定时刷新，资源切换后忽略迟到响应，失败时保留上次状态和已读信息。
10. [工具与渠道] API 文档按资源、身份及分页方式分组展示参数，突出当前分支的配套字段，并修正必填标记与请求示例，便于直接核对不同接入方式。
11. [系统与运维] 补充 OpenSandbox 启动排障说明，帮助排查卷权限正常但 /workspace 仍不可写时的宿主机 seccomp 限制。
12. [系统与运维] 升级管理页补充知识库与对话迁移的总量进度，只有已处理数量的阶段也会显示计数，便于判断后台任务进展。

🐛 修复

1. [工作流与 Agent] 修复多个子应用或工作流工具调用同一目标时，内部节点记忆互相覆盖的问题。按完整调用路径隔离内容提取、问题分类与 Pi Agent 状态，覆盖克隆应用共享后代工具、递归进入根应用等场景。
2. [工作流与 Agent] 修复 Agent、工具调用及嵌套子流程的记忆未完整回传、未执行分支的历史记忆丢失，以及并发子流程用旧状态覆盖其他节点新状态的问题；仅合并子流程本次更新，保留其他有效记忆。
3. [工作流与 Agent] 修复循环、并行运行中的记忆传递与失败隔离问题。循环在成功迭代间传递记忆，交互暂停保留检查点，失败迭代不提交；并行任务仅合并成功结果，失败尝试不影响重试，并按输入顺序合并，同一记忆键以靠后的成功任务为准。
4. [工作流与 Agent] 修复 Agent 作为子工具或子应用追问后续跑丢失上下文、计划或回答，以及交互残留影响下游节点或下一轮循环的问题；按节点保存暂停状态，恢复后输出完整回答。
5. [工作流与 Agent] 修复嵌套 Agent 已成功准备沙盒，但根会话仍无法浏览或下载文件的问题；就绪后记录会话实际启用状态，后续轮次未使用沙盒或就绪后出错不会清除此状态，系统与团队权限仍然生效。
6. [工作流与 Agent] 修复同一轮父子或兄弟 Agent、工具调用节点向共享沙盒注入不同来源的同名文件时互相覆盖的问题，自动分配唯一名称并同步模型可见路径；跨节点注入同名同来源文件时复用本轮已分配名称。
7. [工作流与 Agent] 修复不同节点选择技能时互相清除已部署版本及初始化状态的问题；已发布技能版本及成功状态随沙盒缓存保留，缺失目录重新部署后会清除对应旧标记，确保重新初始化。
8. [工作流与 Agent] 修复并发子应用共用沙盒时因初始化锁竞争直接失败的问题，锁繁忙时有界等待重试，超时或租约异常仍返回初始化错误。
9. [工作流与 Agent] 修复工作流及商业版辅助生成在准备阶段收到的停止请求被初始化清除的问题；MCP、定时触发等非 SSE 工作流执行也能响应显式停止。
10. [工作流与 Agent] 修复旧 Agent 的知识库引用回退为手动选择后，残留引用值导致保存失败的问题；Agent 与知识库搜索节点的手动选择会过滤格式异常项，并保留其余知识库选择。
11. [工作流与 Agent] 修复技能编辑沙盒未运行时导出失败的问题，服务端在可初始化状态下先启动或恢复沙盒，等待就绪后再打包；可编辑成员需等待沙盒就绪，只读协作者的导出入口不再受本地编辑沙盒状态限制。
12. [工作流与 Agent] 修复 Agent 传递交互表单时，时间点、时间范围字段丢失已配置的时间粒度及起止限制的问题，保留原配置。
13. [工作流与 Agent] 修复多行文本框在输入法组合输入及确认候选词时重置光标、干扰输入的问题。
14. [工作流与 Agent] 修复工具及表单参数配置弹窗内容较多时无法正常滚动的问题。
15. [工作流与 Agent] 修复 Agent 最大输出令牌和正文输出开关未完整生效的问题，关闭正文时保留必要交互及节点结果；开启异常捕获后，错误进入异常分支，不再直接拼入可见回答。
16. [工作流与 Agent] 修复 Pi Agent 将旧版必填标记及内部扩展字段直接传给模型，导致工具参数 Schema 被供应商拒绝的问题；工具、沙盒及内置能力统一在模型调用前归一化。
17. [知识库与文件] 修复商业版网站同步漏抓空正文目录页的子链接，以及正文无效、入库失败或页面上限截断时误删旧集合的问题；改进重复链接去重与重定向后的相对资源解析，同步不完整时保留旧数据。提前停止或超时后按序清理并限制等待时间，取消后不再发起后续写入或重试，已开始的数据库操作按自身机制完成。
18. [知识库与文件] 修复阿里云 OSS 流上传已知长度时仍添加分块编码、与 Content-Length 冲突而被拒绝的问题。
19. [对话体验] 修复长时间无输出或客户端断开后生成状态失准、恢复连接持续等待的问题。持久化对话由独立续期的 Redis 租约判断忙闲，进程退出后在最后续期后最多 60 秒过期；租约获取或读取异常时会降级，故障期间无法保证同会话互斥与状态准确。
20. [对话体验] 修复同会话重复发送被拦截后，错误等待新回复而无法恢复原轮次的问题；回填被拒绝的文字和附件，刷新并恢复已有回复，兼容交互续跑及原回复已结束的情况。
21. [对话体验] 修复同一轮用户消息与 AI 回复共用 dataId 时，管理员反馈及关闭自定义反馈误更新用户消息的问题，现在仅更新对应 AI 回复。
22. [对话体验] 修复 Markdown 图片描述包含成对方括号（如 ![Image [1]](...)）时漏识别图片的问题，图片提取与替换现可正常处理这类描述。
23. [对话体验] 补齐沙盒连接及文件错误提示、技能生成状态和工具版本标签的简体中文、繁体中文、英文及韩文文案，修复部分界面显示内部键名或缺少翻译的问题。
24. [对话体验] 修复发送后刷新页面时，浏览器断流被误判为发送失败，导致已发送文字和附件重新出现在草稿中的问题。
25. [团队与权限] 修复 API Key 过期或额度超限的错误信息包含明文 Key 的问题，错误提示不再暴露凭证。
26. [团队与权限] 修复新建、导入 JSON、复制应用及转为工作流副本时，因引用不可读或已不存在的资源而整体失败的问题。初始版本只记录可读资源的授权快照，节点中仍不可用的引用在详情页标记异常，供后续调整。
27. [团队与权限] 修复审计详情把部分含冒号的名称、URL 或变更值误作翻译键的问题，系统标签照常翻译，用户内容按原值展示。
28. [团队与权限] 修复账号注销确认弹窗的「取消」按钮未正确使用当前界面语言的问题。
29. [团队与权限] 修复分享页可使用其他发布渠道标识加载公开应用信息的问题，现在仅接受分享渠道。
30. [系统与运维] 修复 CSV 字段以空白、BOM 或制表、换行符开头时可能绕过公式转义的问题，统一加固日志、用量和审计导出。
31. [系统与运维] 修复 Linux 下启用 seccomp 的 JavaScript 代码运行进程在大量输出或背压时因 io_uring 崩溃的问题，启动前回退到 epoll，并保留原有原生隔离。
32. [系统与运维] 修复 MongoDB 4.x 下清除团队 AI 账号或外部工作流变量、移动知识库集合，以及部分对话反馈更新或清除操作因空更新字段而失败的问题。
33. [系统与运维] 修复 OpenSandbox 将 Pending、Allocated 过渡状态误判为错误的问题，启动或复用沙盒时会继续等待运行就绪后再连接。
34. [系统与运维] 修复商业版管理台在数据库缺少系统配置或旧记录缺少 systemEnv 时，配置页与实际运行值不一致的问题；从有效的 config.json 初始化运行配置，页面仅补齐缺失内容，保留已有站点与套餐配置，避免保存时被默认值覆盖。
35. [系统与运维] 修复日期选择器修改原日期、请求丢失毫秒及图表多查一天导致筛选边界不一致的问题，页面的单日选择、列表、统计与导出保留所选日期的完整范围，模型仪表盘默认展示昨天和今天。商业版应用图表不再因夏令时丢失统计桶，日志与用量 CSV 按请求起点偏移显示时间，避免服务器夏令时干扰。
36. [系统与运维] 修复对话日志同时按使用者、反馈和会话搜索筛选时，条件相互覆盖的问题，列表与 CSV 导出现在组合应用全部筛选条件。
37. [系统与运维] 修复 Langfuse 节点属性污染父级追踪、Agent 缺少模型生成记录和用量的问题；并发执行时各节点分别归集用量，避免混入其他节点的数据。
38. [工具与渠道] 修复语音转文字入参校验失败时被包装为普通服务错误的问题，现在返回统一的 HTTP 400 参数错误。
39. [工具与渠道] 修复繁体中文界面中部分工具名称、简介和标签的繁体翻译为空时显示空白的问题，优先回退简体中文，仍无有效文案时回退英文。

🛠️ 代码优化

1. [工作流与 Agent] 统一画布子应用、Agent 子应用工具与旧应用调用节点的执行流程，集中维护文件与变量过滤、记忆隔离、交互恢复、流式控制和用量归集，减少重复实现。
2. [系统与运维] 新增通用服务端翻译加载器，按请求语言与命名空间加载并缓存资源，缺失文案回退英文或原键名，加载失败可重试；固定每个请求的翻译语言，供服务端输出边界复用。
3. [系统与运维] 新增按业务归档的集成测试用例生成与执行技能，将工作流编排回归用例整理为场景矩阵，支持单页浏览与筛选及手动触发的 Node、无头 Playwright 脚本；未覆盖项和脚本失败由 AI 执行或复核，临时 HTML 报告逐项保留执行方、结果、证据及复测历史。
4. [系统与运维] 新增手动触发的 GitHub Actions 已合并 PR 回移流程，默认目标分支为 v4.17.x，可按需修改，完成后生成草稿 PR。仓库维护技能 fastgpt-backport-pr 支持向显式指定的维护分支批量回补，机械冲突自动处理、逻辑冲突需人工确认；局部验证后直接推送代码，回补 v4.17.x 时对齐 Pro 同名维护分支，对应进行中版本的中英文文档则基于 upstream/main 单独提交 PR。
5. [系统与运维] 完善仓库 pr-review 技能的审查规范，加入实现方案与业务约束检查，整合安全、性能和工程清单，纳入 PR 评论、Review 正文和行内讨论；复查时结合历史报告与当前完整差异，逐项核对旧问题的修复状态及新增风险，并保留判断依据。
6. [系统与运维] 文档站支持按语言独立管理草稿，统一过滤路由、导航、搜索和导出；llms.txt 改按请求语言输出已发布内容，并保留缺少译文时的已发布内容回退。
7. [系统与运维] 清理独立测评工作区配置及 Pro 中相关脚本、命令和历史资产，精简开发工具配置。