dify 1.17.1更新：知识库、工作流、Agent、服务 API 全面修复，升级前必须注意 Weaviate 风险

发布日期：2026年9月12日
版本：1.17.1

重要提醒：使用内置 Weaviate 的自托管部署，在启动 dify 1.17.1 前必须执行手动、分阶段升级。内置 Weaviate 服务将从 1.27.0 升级至 1.39.2，跨越 12 个小版本，直接跳过中间版本并不受支持。若直接拉取镜像并重启，可能会静默且永久性地破坏向量检索能力。 全新部署、使用外部 Weaviate 的部署，以及使用其他向量数据库的部署不受此影响。

dify 1.17.1 是一次覆盖范围很广的稳定性更新。此次版本不仅新增了知识库 API 密钥范围控制、工作流键盘移动、插件市场创作者主页、Markdown 表单字段名长度配置等功能，还集中修复了知识库文档解析、模型供应商迁移、工作流人机交互、Agent 会话记忆、服务 API 分页、OpenAPI 合约、并发死锁等大量问题。

尤其值得注意的是，知识库部分修复了多种“内容在没有报错的情况下被错误索引”的问题。对于受影响的 CSV、Notion、Excel、PDF、网页抓取和 Markdown 文档，升级完成后需要重新导入，已经建立的索引文本不会自动修复。

一、升级前最关键的事项：内置 Weaviate 需要分阶段升级

本次升级中，内置 Weaviate 的版本从 1.27.0 提升至 1.39.2。由于跨越了 12 个小版本，不能直接跳过中间版本启动新版本。

对于使用 dify 自带 Weaviate 的自托管环境，必须先按照升级指南完成手动分阶段升级，再启动 dify 1.17.1。

如果忽略这一要求，直接拉取新版本并重启，可能导致向量搜索功能被静默破坏，并且这种损坏可能是永久性的。

以下场景不受影响：

• 新部署的 dify 环境

• 使用外部 Weaviate 的环境

• 使用其他向量数据库的环境

二、新功能：知识库 API 密钥支持按知识库范围授权

过去，知识库服务 API 密钥是以整个工作区为范围授权的。一个密钥可以读取和写入租户中的全部知识库。

这意味着，如果要让某个集成访问一个知识库，实际上就相当于给了它访问工作区所有知识库的权限。

在 dify 1.17.1 中，知识库 API 密钥支持绑定到指定知识库。创建密钥时，可以在知识库的 API 访问面板中选择授权范围：

• 工作区范围

• 当前知识库范围

绑定到某个知识库的密钥，只能访问该知识库的数据。若尝试访问其他知识库，无论是文档操作还是检索操作，都会返回 403。

对于不携带知识库 ID 的接口，例如列出全部知识库的接口，绑定型密钥同样无法访问。

已有的旧密钥不会被自动限制，仍然保持工作区范围的原有行为。因此，升级后不会影响现有集成和既有调用逻辑。

三、新功能：工作流节点和评论支持键盘移动

此前，工作流画布上的节点和评论只能通过鼠标拖拽移动。

现在，工作流中的以下对象都可以使用方向键移动：

• 单个节点

• 多节点选择

• 评论标记

• 草稿评论

• Note 节点

• Iteration 节点

• Loop 节点

按住 Shift 键再使用方向键，可以进行更大步长的移动。

连续按键移动时，系统会在松开按键或失去焦点后统一提交位置变更，因此连续移动只会生成一条撤销记录，而不是每按一次方向键就生成一条撤销记录。

只读模式、容器边界限制以及协作更新规则也仍然会被正确遵守。

四、新功能：插件市场创作者主页与首页改版

插件作者现在拥有公开的创作者主页，访问路径为：

/marketplace/creator/


创作者主页会展示其创建的内容，并提供发布者侧边栏信息。

侧边栏帮助菜单中新增了 Creator Center 入口，方便进入创作者相关页面。

插件市场首页也进行了重新设计，新增和调整了以下内容：

• 顶部主视觉区域

• 横幅轮播

• 吸顶搜索

• 目录标签页

• 标签筛选

• 语言筛选

• 移动端堆叠与滑动布局

此外，Bundles 不再混入插件分类中展示。

五、新功能：Markdown 表单字段名长度可配置

此前，Markdown 表单字段名称的长度限制被硬编码为 128 个字符。

在一些自动生成字段名较长的场景中，固定长度限制可能无法满足需求。

现在可以通过环境变量调整这一上限：

Docker 部署使用：

MARKDOWN_FORM_FIELD_NAME_MAX_LENGTH

直接部署 Web 前端时使用：

NEXT_PUBLIC_MARKDOWN_FORM_FIELD_NAME_MAX_LENGTH

默认值仍然是原先的 128。

字段字符校验规则以及原型污染防护机制保持不变。

六、知识库修复：CSV 内容不再被错误推断和篡改

此前，CSV 单元格会先经过 pandas 类型推断再被索引，这会带来多个内容错误问题：

• 带前导零的编码会被转换成浮点数，例如00123变为123.0

• 空单元格可能被转为字符串nan

• 内容为NA或NULL的单元格可能被当成缺失值

现在，CSV 提取器会将所有内容作为文本读取，并关闭缺失值推断。

如果调用方希望保留类型化解析行为，仍然可以显式传入csv_args覆盖默认设置。

对于此前受影响的 CSV 文档，需要在升级后重新导入。

七、知识库修复：Notion 表格、属性字段解析恢复正确

此前，Notion 表格中一个单元格内的每段富文本会被错误地输出为独立 Markdown 列。

当单元格包含加粗、链接、提及等混合格式时，就会额外生成列，造成表格内容损坏。

同时，空单元格会被跳过，导致后续列整体左移。

现在，每个 Notion 单元格都会对应一个 Markdown 列，单元格中的多个富文本片段会被正确拼接。

Notion 数据库属性也修复了格式变化后被截断的问题。

此前，rich_text和title类型属性只读取第一个文本片段。例如，一个标题中后半部分采用加粗格式，索引结果可能只保留前半部分。

现在，所有文本片段都会被完整拼接。

受影响的 Notion 文档需要重新导入。

八、知识库修复：旧版 xls 文件中的双引号不再破坏行内容

此前，.xls文件中的单元格如果包含双引号，可能导致整行内容格式损坏。

提取器会生成类似"column":"value"的键值格式。.xlsx路径会转义嵌入的双引号，但旧版.xls路径直接插入原始内容。

例如，单元格内容为：

he said "hi"

此前可能被输出为：

"note":"he said "hi""

现在，.xls与.xlsx对同样内容将采用一致的转义处理。

九、知识库修复：从 URL 加载 PDF 不再触发 AssertionError

此前，从 URL 加载任意 PDF 都可能出现裸AssertionError。

在 PDF 提取器加入租户上下文后，load_from_url路径会对一个 URL 加载本来不存在的上传记录进行断言。

这也影响内置网页抓取器：当目标地址返回Content-Type: application/pdf时，网页抓取流程同样会走到这一问题路径。

现在，租户上下文改为可选：

• 没有上传记录时不会再断言失败

• 没有租户上下文时跳过图片提取

• PDF 文本提取可以正常完成

十、知识库修复：内置网页抓取器返回可读文本

此前，内置网页抓取器返回的不是页面文本，而是 Python 数据结构。

readabilipy返回的plain_text是字典列表，系统直接将其插入输出模板，因此抓取结果可能表现为带有字典语法、引号和 HTML 标签的内容。

现在，这些项目会被正确展平为可读文本。

十一、知识库修复：部分分段更新不再清空附件

此前，对分段进行局部更新时，如果请求中没有提供attachment_ids，系统会将其理解为“替换为空”，从而删除该分段的附件绑定和多模态向量。

现在，只有在请求中显式提供attachment_ids时，附件才会被修改。

具体行为如下：

• 未提供attachment_ids：保留原有附件

• 提供空数组[]：清空附件

十二、知识库修复：无效 Markdown 图片链接不再阻塞索引队列

此前，文档中的无效 Markdown 图片链接可能导致索引队列阻塞。

相对路径、协议相对路径、data:、ftp:以及格式错误的图片地址，都会被交给远程图片抓取器处理，并进入 SSRF 重试循环。

一个包含大量无效图片链接的文档，可能长时间占用索引工作线程，进而导致后续任务积压。

现在，不能抓取的目标会在前置校验中被识别并跳过。

十三、知识库修复：删除内容后同步清理对象存储附件

此前，删除内容时可能只删除数据库记录，而没有删除对象存储中的实际附件文件。

受影响的场景包括：

• 删除分段

• 多模态重新索引

• 批量删除文档

现在，这些路径会在数据库提交后删除底层对象。

同时系统会执行孤儿检查：如果附件仍被其他分段共享，则不会删除该附件对象。

十四、知识库修复：文本文件预览不再因 UTF-8 截断被误判为二进制文件

此前，文本预览的字节限制如果刚好截断在一个多字节 UTF-8 字符中间，严格解码会失败，整个文件就会被误判为二进制文件。

这一问题可以在默认预览大小下复现：当一个非 ASCII 字符正好跨越 256 KiB 边界时，预览会出错。

现在，预览会保留最长的完整 UTF-8 前缀。

真正使用无效编码的文件，仍然会被正确识别为二进制文件。

十五、模型供应商修复：旧版本升级不再需要手动迁移模型类型

从 1.15 之前版本升级时，旧安装环境可能仍保留以下旧模型类型值：

•text-generation

•embeddings

•reranking

这些旧值会导致模型相关 API 请求失败，并阻止受影响模型加载。

此前，1.16.1 和 1.17.0 需要额外手动执行flask data-migrate legacy-model-types。

现在，这一过程已被并入flask db upgrade。

升级时会自动完成以下处理：

• 将旧类型值规范化为llm、text-embedding、rerank

• 处理旧值与新值记录并存时的冲突

• 保留凭据引用关系

• 轮换供应商缓存命名空间，避免旧缓存凭据遮蔽迁移后的记录

十六、模型供应商修复：本地文件上传不再错误要求授权

此前，在创建 RAG Pipeline 知识库时，本地文件上传数据源可能显示“Please authorize first”，创建检查列表也会将其标记为未授权。

原因是：不声明凭据模式的供应商不会有已保存的凭据记录，因此系统始终将其判断为未授权。

现在，无需凭据的供应商会直接被标记为已授权。

此外，供应商范围的凭据校验规则现在会被正确应用，缺失工具凭据时也会被明确提示，不再以不透明方式失败。

十七、工作流修复：Human Input 提交后不再显示卡住

自 1.17.0 的 HITL 回调迁移后，提交 Human Input 表单可能让工作流实际完成，但页面仍然看起来处于卡住状态。

具体表现包括：

• 审批按钮仍保留在页面上

• 已发布 Web App 的输入被阻塞

• 工作流引擎只发送通用节点成功事件

• 响应处理管道期待的表单已填写或超时事件没有出现

现在，这些事件会被重新构造，并保留以下信息：

• 已提交的文件值

• 原始超时时间

• 执行元数据

十八、工作流修复：Human Input 可放入 Iteration 和 Loop 容器

1.17.0 已经具备在 Iteration 和 Loop 中运行 Human Input 的运行时能力，但编辑器仍保留了过期限制。

这些限制会阻止用户在容器中：

• 选择 Human Input 节点

• 连接 Human Input 节点

• 粘贴 Human Input 节点

现在，这些编辑器限制已被移除。

十九、工作流修复：Human Input 超时边不再走错分支

编辑器写入的超时边标识为：

__timeout

但后端此前比较的是：

__timeout__

由于两者不一致，运行时超时可能走到用户操作分支，而不是作者在画布中配置的超时分支。

现在，超时边匹配逻辑已修复。

二十、工作流修复：同一次运行中的第二次 Human Input 暂停可继续恢复

此前，如果对象存储拒绝删除上一次暂停快照，异常会中断事务。

此时工作流运行本身已经持久化为PAUSED，但唯一的暂停记录仍然是之前已经恢复过的记录。下一次提交就可能失败，并提示无法恢复一个已经恢复的暂停。

现在，快照清理改为尽力而为：

• 清理失败不会破坏运行的持久化状态

• 遗留对象键会被记录，便于后续清理

• 新的暂停状态可以保持正确

二十一、工作流修复：Workflow-as-Tool 支持收集全部 End 节点输出

此前，将工作流作为工具时，只会暴露第一个 End 节点的输出。

现在，系统会收集每一个 End 节点的输出声明。

对于每个输出，也会标明来源节点。

如果出现重复名称或保留名称，将针对受影响输出生成一条警告。

当实时草稿元数据不可用时，系统会回退到已发布的 Schema。

二十二、工作流修复：Loop 布尔中断条件恢复正确匹配

此前，新建的 Loop 条件将true和false保存为字符串，而不是布尔值。

这会导致布尔中断条件无法正确匹配。

现在：

• 新值会以真实布尔值保存

• 旧字符串值会在渲染时进行规范化

二十三、工作流修复：触发器入口工作流不再允许手动调用

触发器入口工作流此前仍可从多个入口被手动调用：

• Web App

• Service API

• OpenAPI

• MCP 的 tools/call

这会创建无法正常运行的工作流任务。

现在，这类调用会在创建运行记录或日志之前被拒绝。

HTTP 和 MCP JSON-RPC 会使用统一的业务代码。

以下行为不受影响：

• 真实触发器执行

• 只读接口

• 按历史 Start 版本 ID 运行

二十四、工作流修复：异常 LLM 节点不再让整个编辑器崩溃

如果某个工作流中的 LLM 节点将model_selector持久化为null，而不是省略该字段，Workflow Studio 在加载时可能崩溃。

此前，单个节点异常会导致节点检查清单失败，并触发页面级错误边界，整个画布无法使用。

现在，这类问题不会再导致整个编辑器不可用，而是针对对应节点进行处理。

二十五、工作流修复：启用 Agent V2 后旧版 Agent 节点可重新发布

此前，启用 Agent V2 后，包含旧版 Agent 节点的工作流可能无法发布。

原因是发布校验无法解析旧版校验器。

现在，包含旧版 Agent 节点的工作流可以重新发布。

旧版 Agent 节点仍然不会出现在节点选择器中。

二十六、工作流修复：从工作流创建工具时优先发布当前版本

此前，从工作流创建工具时，可能会使用此前已经发布的版本，而不是当前工作流版本。

现在，系统会先发布当前工作流，这与更新工具时的逻辑保持一致。

如果发布失败，供应商创建流程会停止，不再静默绑定到旧版本。

此外，撤销删除 Webhook 触发器节点后，其 URL 被改变的问题也已修复。

二十七、工作流修复：MySQL 下文档创建和更新不再误报文件不存在

在 MySQL 默认的REPEATABLE READ隔离级别下，文档创建或更新可能提示：

One or more files not found.

即使上传已经提交，当前请求会话的读取快照可能在上传发生之前就已经固定，因此看不到另一个会话刚写入的上传记录。

受影响接口包括：

• 通过文本创建文档

• 通过文件创建文档

• 通过文本更新文档

• 通过文件更新文档

现在，这四个接口会在查找上传记录前刷新快照。

PostgreSQL 不受这一问题影响。

二十八、工作流修复：大型工作流图不再导致协作 Socket 反复重连

大型工作流图的sync_request载荷可能超过 Engine.IO 默认的 1 MiB 限制。

当帧被拒绝后，编辑器会不断重连。

现在，最大缓冲区大小可通过以下环境变量配置：

WEBSOCKET_MAX_HTTP_BUFFER_SIZE

默认值调整为 10 MiB。

同时，Access Point 页面在已发布工作流请求失败时，不再错误显示“没有已发布版本”的引导；对于返回 403 的请求，也不再重复重试。

二十九、Agent 与聊天修复：Chatflow Agent V2 恢复跨轮记忆

此前，Chatflow Agent V2 在多轮对话中无法记住前文。

现在，会话以conversation_id为键，因此记忆能够在同一个对话中持续保留。

同时，还修复了在对话中途发布新 Agent 配置版本的问题。

此前，如果在对话过程中发布了新的 Agent roster 版本，可能会将新的配置与旧参与者组合，导致生成校验失败。

现在：

• 已存在的对话会固定使用其开始时的版本

• 新对话才会使用当前最新版本

三十、Agent 与聊天修复：推理模型回复不再全部显示为 thinking

部分推理模型会使用
标签包裹思维链。

当工具调用在输出前中断生成时，真正的回答可能仍嵌套在未关闭的标签中，最终整个回复都被渲染为“thinking”。

现在，在以下场景中会自动修复悬挂的
标签：

• 工具日志中断流式输出时

• 实际内容之后又出现新的
时

• 流式输出结束时

• Markdown 预处理阶段

因此，已经存储的历史输出也可以获得正确渲染。

三十一、Agent 与聊天修复：图片上传会作为原生多模态内容发送

此前，上传到 Agent App 的图片会被转换为 shell 下载指令，而不是直接展示给模型。

现在，支持视觉能力的模型会收到原生多模态内容。

系统会根据所选的、已绑定凭据的模型 Schema 判断模型是否具备视觉能力。

以下情况仍保留下载回退方案：

• 非图片文件

• 不支持视觉能力的模型

同时，图片 URL 和 Base64 载荷会从 Agent 后端日志中脱敏。

三十二、Agent 与聊天修复：建议问题生成不再长时间等待或卡住

此前，如果没有专用的建议问题模型，接口会回退使用工作区默认模型。

这可能继承高成本配置，例如：

•reasoning_effort=high

• 2560 Token 输出额度

• 全局 600 秒插件超时

浏览器可能在 100 秒后放弃请求，但后端仍持续运行。

现在，建议问题生成进行了限制和优化：

• 输出上限为 256 Token

• 关闭思考，或使用最低支持的思考强度

• 使用请求级别的 30 秒超时

某个案例中，请求耗时从 113 秒至 344 秒下降到 3 秒以内。

如果默认模型不可用，现在会立即返回空列表，而不是报错失败。

三十三、Agent 与聊天修复：E2B Agent 运行失败处理改进

此前，基于 E2B 的 Agent 运行可能出现502 binding_create_failed。

原因是固定版本 E2B SDK 中的陈旧 HTTP/2 连接可能在内联聊天过程中导致失败。

现在：

• SDK 已升级，避开受影响的传输路径

•connect、pause、kill、delete-snapshot在有限传输失败时会重试一次

• 供应商容量耗尽会返回 429，而不是被报告为创建失败

绑定和快照创建仍然只执行一次，避免将不明确结果静默认定为成功。

此外，Agent Preview 也修复了复用不匹配配置会话的问题。

由于 Preview 会原地编辑草稿，一个对话可能继续使用旧的会话快照，而配置组合层已经增加、删除或调整顺序。

此前这会导致 Agent 后端返回内部不匹配错误。

现在，这种情况会返回：

409 agent_session_configuration_changed

并提示用户开启新对话。

仅修改配置值、但不改变组合层拓扑结构时，原会话仍可复用。

三十四、Service API 与 OpenAPI 修复：分页不再静默丢失数据

此前，分页接口中的has_more按客户端请求的limit计算，但实际查询页大小被限制为 100。

例如，请求limit=200，实际有 150 条数据时：

• 接口只返回 100 条

•has_more=false

• 剩余 50 条数据无法继续获取

现在，分段、知识库和文档列表接口会基于实际生效的页大小计算has_more，并在响应中返回该实际页大小。

删除 MCP provider 返回 422 的问题也已修复。

此前，DELETE 请求解析只读取查询参数，而 Web 客户端会将provider_id放入 JSON 请求体。

现在，当查询字符串为空时，会回退读取 JSON 请求体；使用查询参数的删除方式仍然可用。

三十五、Service API 与 OpenAPI 修复：标准 Schema 与生成合约恢复一致

此前，只要请求带有X-Request-Env，一个标准 OpenAPI Schema 就可能被判定为：

invalid schema: 'env'

原因是服务匹配逻辑无条件索引了非标准的env键。

现在，不含该扩展字段的 Schema 会正确回退到第一个服务器 URL。

生成的 Service API 合约也已与运行时行为对齐，包括：

• 非空字段不再携带null默认值

• 移除仅用于 Console 的权限元数据

• 移除接口实际不会返回的错误响应

• 恢复历史上的 404 和 503 声明

• 拆分任务停止请求 Schema，准确描述聊天、补全和工作流行为

• 修正 Service API 限流说明

这些变更会影响导出的合约和生成的客户端，但不会改变请求处理行为。

三十六、并发与死锁修复：知识检索命中计数更新采用稳定锁顺序

此前，并发知识检索可能发生死锁。

命中计数更新会通过一次UPDATE … WHERE id IN (…)更新所有匹配分段。

PostgreSQL 不保证按传入 ID 的顺序获取行锁。多个并发检索请求的加锁顺序不同，就可能触发deadlock_detected。

现在，系统会先按稳定的ORDER BY id顺序获取锁，再进行计数递增。

对于死锁错误，会进行最多三次重试，并且重试范围严格限定于死锁错误。

三十七、自动摘要生成问题说明

代码地址：github.com/langgenius/dify

自动摘要生成此前可能无限期占用工作线程。

Tencent VectorDB 不接受 JSON 元数据中的布尔值，因此摘要写入时，is_summary: true标记可能在 upsert 阶段失败。

原始更新内容在此处结束于after summary，未提供后续完整修复说明。

我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。