![]()
![]()
![]()
2026年11月12日,Dify 正式发布 1.19.0 版本。本次版本的核心方向非常明确:让复杂工作流的执行过程更可观测,让 Workflow Tool 能够随应用打包迁移,让 Skills 的管理和自动化能力进一步完善,同时提升 Agent 文件处理、预览、编辑体验、部署配置、安全控制与运维稳定性。
对于已经在生产环境中使用 Dify 工作流、Agent、知识库、外部追踪平台以及 Docker 部署方案的团队来说,1.19.0 并不是一次单纯的功能叠加,而是一次围绕“可追踪、可迁移、可自动化、可运维”展开的重要升级。
一、核心看点:工作流终于可以一层层追踪到底
Dify 1.19.0 最重要的能力,是增强了嵌套工作流的可观测性。
在复杂应用中,一个外层工作流可能调用多个 Workflow Tool,而每个 Workflow Tool 内部又可能包含判断、变量处理、知识检索、模型调用,甚至继续调用其他工作流。过去,开发者虽然能看到部分外层执行信息,但当问题出现在某个嵌套工具内部时,往往需要切换多个页面、翻看多个记录,排查成本很高。
1.19.0 让外部追踪平台能够展示 Workflow Tool 内部已经持久化的执行步骤。
现在,当工作流调用一个 Workflow Tool 后,工具内部的执行帧会出现在调用该工具的 Tool span 下方。也就是说,追踪树不再停留在“调用了某个工具”这一层,而是可以继续展开,看到这个工具内部具体执行了什么。
这种层级结构保留了嵌套关系,也能保留重复调用和失败调用的位置。例如,一个 Workflow Tool 被连续调用多次,每一次调用都能在追踪树中找到对应的位置;如果某一次调用失败,也不会丢失其在完整执行链路中的上下文。
新追踪能力主要带来以下价值:
• 可以从外层工作流一路展开,查看嵌套 Workflow Tool 内部的执行步骤。
• 可以准确理解每一次工具调用的执行情况,包括重复调用、异常调用和失败调用。
• 可以在追踪树中保留模型调用上下文,包括格式化后的提示词、模型响应、Token 使用量,以及项目、Trace 和 Observation 链接。
• 可以更直观地定位问题究竟发生在外层工作流、某个工具节点,还是工具内部的模型调用环节。
• 可以减少复杂编排场景下跨页面、跨日志、跨系统排查问题的成本。
本次追踪导出能力通过统一的 Provider 接口进行交付,覆盖多种观测服务。对于可重试的导出任务,系统会使用确定性的标识符重新发送同一个 Trace 单元,避免重试时产生难以关联的重复追踪数据。
需要特别注意的是,已有的 Provider 配置仍然可以继续使用,已经保存的设置不会失效。不过更丰富的追踪层级只会应用于新执行记录,历史 Trace 不会被回填为新的嵌套 Span 结构。
独立运行的嵌套工作流仍会作为独立 Trace 存在,但会通过父级标识符进行关联。因此,在查看复杂链路时,既可以看到调用关系,也可以保留独立工作流运行的边界。
对于滚动升级场景,追踪队列需要按照新的过渡方案进行切换,不能简单地让新旧消费者混用同一套追踪队列。
二、Workflow Tool 可以跟着应用一起迁移
Dify 1.19.0 的第二项关键更新,是应用导出包支持携带 Workflow Tool 依赖。
过去,导出一个应用时,如果应用依赖 Workflow Tool,目标环境往往还需要手动确认并创建对应的工具工作流。这样不仅容易漏配,也让应用从测试环境迁移到预发布、生产环境时变得更加繁琐。
现在,应用导出的 ifpkg 包会包含应用所绑定版本的 Workflow Tool 工作流,并且支持打包传递依赖。
换句话说,如果应用调用了一个 Workflow Tool,而这个 Workflow Tool 又继续依赖其他工具工作流,那么这些依赖关系都可以一并进入导出包。
本次打包与导入机制具备以下特性:
• 应用包会包含所调用 Workflow Tool 对应的工作流版本。
• 支持包含传递依赖,不仅打包直接依赖,也处理更深层的依赖关系。
• 默认最多可打包 20 个工具工作流。
• 当目标工作区已经存在对应工具时,导入过程会复用已有工具。
• 当目标工作区缺少工具时,系统会创建、发布并注册缺失的工具。
• 导入时会重新映射工具引用,保证导入后的应用能够正确关联目标环境中的资源。
• 创建缺失工具需要具备工具管理权限,同时还需要目标工作区拥有足够的应用配额。
• 如果导入过程中遇到需要确认 DSL 版本的情况,该流程会拒绝继续执行。
• 如果应用创建后导入失败,系统会清理本次失败操作已创建的应用,避免遗留不完整资源。
需要注意的是,Dify 1.19.0 中的应用导出包统一使用 format v2。
这项规则适用于所有应用导出场景,即使应用没有调用 Workflow Tool,也会导出为 format v2。嵌套应用包同样采用 format v2。
旧版本的 format v1 导入在 1.19.0 中仍然受支持。显式 YAML 导出也仍然存在,但 YAML 导出不会携带 Workflow Tool 依赖。因此,如果目标是完整迁移一个包含工具工作流依赖的应用,应优先使用新的应用包机制。
升级时必须确认目标导入环境具备兼容的导入器。较旧的导入器,甚至包括一些采用早期严格 v2 规则的构建版本,都可能拒绝新的应用包。因此,在将新导出的应用包导入旧环境之前,必须先升级目标环境。
此外,本次更新还修复了导出过程中的依赖识别问题。Workflow Tool 和 API Tool 的标识符不再被误判为多余的插件依赖,避免导出时出现无意义的 langgenius UUID 类插件依赖。
需要区分的是,新的 format v2 规则不会改变独立 Roster Agent 包的格式。
三、Agent 文件支持批量上传、原地预览与更稳定的编辑体验
在 Agent 配置和文件处理方面,1.19.0 提升了文件上传、绑定、保存和预览流程的可用性。
现在,用户可以一次选择多个 Agent 配置文件,也可以将多个文件直接拖拽到上传区域。多个文件会并行上传,提高大批量配置文件导入时的效率。
上传成功后,文件会通过一次原子绑定请求统一关联。这意味着批量上传不会出现只绑定一部分文件、另一部分文件状态不一致的问题。
本次文件管理更新还包括:
• 支持多选文件上传。
• 支持多个文件直接拖放上传。
• 支持并行上传,提高多文件处理效率。
• 支持一次原子化绑定多个成功上传的文件。
• 支持利用缓存的上传标识符进行重试。
• 防止旧的 Composer 保存操作覆盖后来新绑定的文件。
• 保持原有单文件接口兼容,不会破坏既有集成。
Prompt 上传体验也得到优化。插入多个文件引用时,编辑器会保持光标位置,避免用户在内容编辑过程中因批量插入引用而丢失当前输入位置。
文件预览能力也进一步完善。
现在,系统能够直接预览 PDF,支持按需渲染 PDF 内容;对于文本和源码类文件,可以进行语法高亮展示;当文本内容过长被截断时,界面会明确提示用户内容已经被截断。
这些预览能力覆盖多个场景:
• 已配置的 Agent 文件。
• Skill 内部成员文件。
• 工作目录中的文件。
PDF 预览如果无法加载,界面会提供下载操作,确保用户仍然能够获得原始文件。
本次更新还改善了预览稳定性,避免预览窗口在操作过程中频繁变化或意外关闭。对于重复 PDF 预览导致重复资源的问题,修复只会阻止未来新上传内容产生重复资源,不会自动删除历史上已经存在的重复文件。
四、Skills 迎来 OpenAPI 与命令行自动化能力
Dify 1.19.0 为工作区 Skills 带来了更完整的自动化管理能力。
开发者现在可以通过 OpenAPI 和 difyctl 管理 Skills,包括查找、查看、导出、导入和发布 Skill 版本。
可用操作包括:
• 查询和查看工作区中的 Skills。
• 导出 Skill 草稿版本。
• 导出已发布的 Skill 版本。
• 从本地文件夹导入 Skill。
• 发布新的 Skill 版本。
• 通过命令行完成 Skill 自动化管理。
这些操作需要使用账户身份调用,并且调用者需要具备对应工作区权限,同时目标工作区必须启用 Skills 功能。
导入 Skill 不会自动发布。也就是说,导入后得到的是草稿状态,仍然需要显式执行发布操作。
如果导入时携带 Skill ID,导入行为会替换该 Skill 当前的草稿内容,因此属于破坏性操作。系统的操作目录和命令行帮助会明确区分读取、写入和破坏性操作,帮助使用者在自动化脚本中识别风险。
在导入校验方面,系统增加了多项保护:
• 导入的 SKILL.md 中名称必须与目标 Skill 名称匹配。
• 可以使用可选的 draft_hash 校验草稿是否过期。
• draft_hash 使用秒级时间戳,因此无法识别同一秒内发生的多次编辑。
• 导入时会过滤操作系统产生的无关文件。
• 会拒绝不安全路径。
• 会拒绝重复路径。
• 会校验文件数量和文件大小限制。
• 对完全相同的二进制资源会进行复用。
• 如果导入失败,系统会清理失败过程中写入的资源。
• Skill Frontmatter 中的字面连字符会被保留,不会被错误处理。
此外,Dify 新增了实验性的 OpenAPI 内容映射包,用于根据 OpenAPI 源自动推断类型化 API 调用、查询辅助方法,以及可复用的 Schema、输入和输出类型。
该能力还支持按需启用与契约兼容的类型子路径。不过这项更新目前定位为开发基础设施,并不会将生产环境中的 Console 或 Marketplace 调用迁移到新的客户端。
五、工作流停止操作语义调整
在自动化管理与操作目录中,工作流和 Chatflow 的停止操作进行了调整。
Workflow 和 Chatflow 自动化应使用更新后的 stop.run 操作,而消息类应用应继续使用 stop.task。
两者的语义不同:
• Workflow 和 Chatflow 的停止操作基于已存储的运行归属和运行状态。
• 如果请求停止一个不存在的运行,系统返回 404。
• 如果运行已结束,或处于其他不允许停止的状态,系统返回 409。
• 消息类应用仍然使用任务标识符语义,不随本次调整改变。
对于通过脚本、平台集成或运维工具控制应用运行状态的团队,需要及时检查已有调用,避免继续沿用不匹配的停止操作。
六、升级前必须关注的 Docker Compose、环境变量与追踪队列变化
Dify 1.19.0 对 Docker Compose 版本和环境配置优先级提出了更明确的要求。
Docker Compose 现在要求使用 2.35.0 或更高版本。这是最低支持版本,原因是根目录 .env 覆盖必须能够在 Compose 解析服务默认配置时正确生效。
可以使用以下命令检查版本:
docker compose version升级时,建议保留当前环境文件,不要直接用新版本模板覆盖已有配置。应在原有环境文件基础上合并必要的新增配置。
新的默认配置文件位于 docker/envs 目录下的 defaults 文件中,这些文件会被自动加载。服务自定义配置应写入对应的本地 .env 文件,具体覆盖路径可参考默认文件中的说明。
根目录 docker/.env 用于部署输入和显式覆盖,其优先级高于服务级环境文件。
升级时应特别检查以下问题:
• 不要删除现有 .env 文件。
• 不要直接覆盖本地配置。
• 检查是否存在意外的空赋值。
• 检查是否仍有旧模板复制而来的固定值。
• 确认根目录 docker/.env 中的覆盖值是否符合预期。
• 确认服务级本地 .env 文件是否使用了正确的覆盖路径。
此前已有的 shared.env 文件仍然继续支持。
公共 API、Worker 和 Beat 配置现在推荐迁移到 docker/envs/core-services/api-worker.env。Compose 会先读取旧的 shared.env,再读取 api-worker.env,因此当两者存在冲突配置时,api-worker.env 优先级更高。
根目录 docker/.env 的优先级仍然高于 shared.env 和 api-worker.env。
为了兼容旧配置,系统保留了一份未修改的 api-worker.defaults,使现有 shared.env 自定义项仍可继续工作。
七、滚动升级必须使用新的追踪队列
对于滚动部署,1.19.0 的追踪队列变更是不能忽略的重点。
新的任务默认使用:
OPS_TRACE_QUEUE=ops_trace_v2API、Worker 和 Beat 必须使用一致的新队列配置。
如果部署中使用了自定义的 CELERY_QUEUES、CELERY_WORKER_QUEUES 或 Worker 启动参数中的 queues 列表,那么这些配置必须包含新的 ops_trace_v2 队列。
滚动升级时,旧版本追踪 Worker 仍需要继续消费旧队列 ops_trace,直到以下所有旧任务都完成:
• 已排队任务。
• 正在执行的任务。
• 已预留任务。
• 已计划任务。
• 重试中的任务。
不能直接清空旧队列,也不能让新版本中已经退役的处理器去导出旧格式消息。
正确做法是让旧生产者、旧任务和旧消费者完成其生命周期,再完成追踪队列切换。否则可能导致追踪消息丢失、重复处理,或新旧格式不兼容。
八、Docker Compose 升级流程与配置要求
在 1.19.0 发布标签和镜像可用后,单栈 Docker Compose 部署可以按照以下流程升级:
cd dify/docker
docker compose stop -t -1
git fetch --tags
git checkout 1.19.0
docker compose pull
docker compose up -d在切换版本后、拉取镜像前,应将必要的配置变更合并到现有环境文件中。
升级前需要先完成备份,建议至少备份以下数据:
• 数据库。
• 向量数据库或向量存储数据。
• 上传文件。
• Agent 快照和工作区存储。
• 部署密钥。
• 所有环境文件。
对于单栈升级,建议安排维护窗口,并优雅停止服务。
所有 Dify 组件应同步升级到匹配版本,包括:
• API。
• Worker。
• Web。
• Agent Backend。
• Local sandbox。
• 插件守护进程。
插件守护进程版本更新为 0.6.14-local。
升级时必须保留 Local sandbox 原有认证 Token,不能随意更换。同时,如果当前已配置 PASSWORD_PEPPER,也必须保持不变。
如果是从 1.18.0 之前的版本升级,还必须先遵循 1.18.0 的升级要求。
API 启动时应保持数据库迁移启用,即:
MIGRATION_ENABLED=true如果采用自管迁移流程,则必须在新 Worker 启动前执行完整数据库迁移链路。
插件守护进程相关密钥需要在根目录 docker/.env 中配置,并确保守护进程及其客户端获得一致的值:
PLUGIN_DAEMON_KEY
PLUGIN_DIFY_INNER_API_KEY端口、卷路径、Profile、健康检查调度等配置仍然属于根目录配置输入。
九、源码部署要求同步提升
对于源码部署,Dify 1.19.0 更新了运行时要求。
需要使用:
• Python 3.13。
• Node.js 24.22.1 或更高的 24.x 版本。
• pnpm 12.16.1。
需要注意的是,pnpm 不再为工作区自动提供 Node.js。因此,部署环境必须自行安装符合要求的 Node.js 运行时。
在仓库根目录可执行以下操作:
uv sync --project api --frozen
uv run --directory api flask db upgrade
pnpm install --frozen-lockfile完成依赖安装和迁移后,需要重新构建 Web 应用,并从同一个发布版本重启 API、Worker、Scheduler 和 Agent 服务。
如果单独部署 Agent Backend,也需要刷新其锁定的服务端依赖。
difyctl 用户需要安装匹配的 1.19.0 客户端版本,并通过 difyctl help 查看当前服务器支持的操作目录。
已安装的 Agent Skills 可以使用以下方式刷新:
difyctl install skills 十、数据库迁移与已有数据影响
从 1.18.0 升级到 1.19.0 时,需要执行六个数据库迁移版本,最终迁移版本为:
53c10126d551必须通过常规迁移执行器完成整个迁移链路。
其中有两类数据库变化需要重点规划。
第一类是存储清理索引。
系统会为以下字段创建引用索引:
• message_files.upload_file_id。
• workflow_node_execution_offload.file_id。
• workflow_draft_variable_files.upload_file_id。
在 PostgreSQL 中,这些索引会并发创建,但索引构建仍会扫描数据并消耗 I/O 资源。因此,在大规模生产数据库中,需要提前评估磁盘、CPU、I/O 与维护窗口。
在线升级会复用名称和定义均匹配的健康索引。如果存在冲突索引或无效索引,迁移会拒绝继续执行。
如果索引构建中断并产生无效索引,应先调查原因再进行重试。不要把删除健康索引当作常规恢复手段。
第二类是追踪配置唯一性。
系统会确保每个应用与 Provider 的组合只保留一条追踪配置,并创建唯一索引。
如果数据库中已经存在重复配置,系统会保留最近更新的一条记录;如果更新时间相同,则通过 ID 进行决策。其余被替代的配置会被删除。
需要特别注意的是,后续即使降级并移除唯一索引,被删除的重复记录也不会自动恢复。因此,升级前必须保留数据库备份。
内容提取相关修复只会影响新处理的内容。如果现有文档存储内容曾受到 EPUB、EML、DOCX、CSV、Markdown 或 Notion 解析问题影响,需要重新导入或重新建立索引。
历史追踪数据不会重建。已有 Agent Trace Ledger 数据仍然可以读取,但以前已经导出的外部 Trace 不会自动获得新的嵌套 Span。
十一、编辑体验、无障碍能力与性能优化
除了工作流追踪与部署能力,1.19.0 还针对控制台编辑体验进行了大量优化。
在方向和键盘支持方面,系统改进了多语言界面的方向同步,并扩大了从右到左布局支持范围。
日期和时间选择器现在与表单集成更紧密,并增强焦点约束。可见标签会保留在无障碍名称中,只读控件的行为也更加一致。
在编辑对话框方面,多个高频操作的稳定性得到提升,包括:
• 删除。
• 重命名。
• 元数据编辑。
• 标注编辑。
• 成员角色编辑。
• 插件设置编辑。
这些对话框会更好地保留会话状态和草稿内容,在请求等待期间保持待处理操作窗口打开,并在操作完成后恢复焦点。
对于删除操作,系统会阻止请求等待期间的重复提交,避免重复删除请求。
在反馈提示方面,字段错误与持久提示会更靠近对应控件显示。应用、工作流、知识库、计费和 Skills 中的告警展示方式也更加统一。
云端计费相关提示支持本地化,并能更明确地区分可重试错误和需要用户执行特定操作的错误。
配额显示也更加准确:
• 能够区分无限数量与零容量。
• 能够正确展示 App Run 和触发器配额。
• 重置日期按照 Unix 秒进行解释。
• 定价展示数据不再被错误地当作实时使用限制。
性能方面,分段页面现在会批量加载子分段和附件,减少查询开销。新的引用索引也能支持应用存储清理流程。
网络连接复用方面,Gunicorn 的可配置 Keep Alive 默认值调整为 10 秒,以减少因为复用连接超过服务器较短空闲窗口而导致的失败。
十二、安全增强:权限、Cookie、数据集与追踪密钥全面收紧
Dify 1.19.0 还加入了多项安全改进。
在工作区控制方面,启用或禁用 Provider 模型需要工作区所有者或管理员权限。邮箱可用性检查也需要满足账户准入条件。
在 SSRF 防护相关的请求 Cookie 处理上,连接池客户端收到的响应 Cookie 只会保留在当前出站请求及其重定向链路中,不会泄漏到后续独立请求,避免一个请求继承另一个请求的 Cookie。
在数据集 Token 权限方面,资源访问 Token 只能列出其明确绑定且处于激活状态的数据集。include_all=true 不再能够扩大该 Token 的可见范围。
旧版工作区 Dataset API Key 仍保留租户范围行为,但不会继承被注入所有者的个人可见性过滤条件。
在应用访问设置方面,如果使用 DSL 导入覆盖已有应用,应用原有的 Web App 访问模式会被保留。将应用转换为其他类型时,也会继承源应用的访问模式。
追踪配置中的密钥继续保持只写特性。读取配置时不会返回已保存的凭据。
如果仅提交空密钥或省略密钥字段,系统会保留原有已保存值;但如果修改了追踪目的地的主机、端点或 URL,就必须重新输入密钥。
同时,Provider 流量会使用统一的出站访问策略,进一步加强对外部追踪服务通信的控制。
十三、总结:Dify 1.19.0 是面向复杂生产工作流的重要版本
代码地址:github.com/langgenius/dify
Dify 1.19.0 的价值,不止是新增几个控制台功能,而是围绕生产级 AI 应用的完整生命周期进行了增强。
从开发调试角度看,嵌套 Workflow Tool 追踪让复杂工作流不再是黑盒,开发者可以沿着执行树一路查看到模型调用的提示词、响应和 Token 数据。
从迁移交付角度看,Workflow Tool 可以跟随应用包一起导出和导入,复杂应用在不同环境之间迁移时更完整、更可靠。
从自动化管理角度看,Skills 获得 OpenAPI 与 difyctl 支持,导入、导出、发布与版本管理可以纳入标准化脚本和平台流程。
从使用体验角度看,批量文件上传、稳定预览、编辑状态保留、无障碍改进和更清晰的错误反馈,都让日常使用更加顺畅。
从运维角度看,Docker Compose 最低版本、环境变量优先级、追踪队列切换、插件守护进程版本、源码运行时要求和数据库迁移影响,都给出了明确的升级边界。
从安全角度看,模型权限、邮箱检查、请求 Cookie 隔离、数据集 Token 范围、应用访问模式继承和追踪密钥保护,也让平台在多工作区、多环境和外部服务集成场景中更加稳健。
对于计划升级到 Dify 1.19.0 的团队,建议优先完成备份,核对 Docker Compose 版本,保留并审查现有环境文件,确认追踪队列切换方案,检查应用包导入目标环境的兼容性,并提前评估数据库索引构建带来的 I/O 消耗。
只有在 API、Worker、Web、Agent Backend、Local sandbox 与插件守护进程完成同版本协同升级后,才能完整获得 Dify 1.19.0 带来的工作流追踪、应用迁移、Skill 自动化与稳定性提升能力。
芯谷ai:xinguhub.com/sign-up?aff=txk5
我们相信人工智能为普通人提供了一种“增强工具”,并致力于分享全方位的AI知识。在这里,您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”,发消息可获得面试资料,让AI助力您的未来发展。
特别声明:以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布,本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.