Dify 1.18.0 是个偏向「架构整理」的大版本：Agent 能自己决定工作流走哪条分支了，应用能打包成单个 .ifpkg 文件带着走，嵌套的工作流调用也能看清内部每一步。23 号刚发的，升级注意事项不少，打算更的自托管用户先看完再动手。
🔥 更新内容
1. Agent 自主选择工作流分支
给 Agent 节点开启 Output Routes，给每条路由定义选择条件，Agent 完成任务时自己判断走哪条：是直接答复请求，还是转给专家节点处理。节点上有个只读的 switch 输出，能查看它实际选了哪条路。另外普通 Agent v2 节点的文本输出改成流式了，边生成边吐字，不过结构化输出和带默认值兜底的节点还是等跑完再返回。（#42599、#43986）
2. 应用打包成 .ifpkg 单文件
应用导出现在默认是 .ifpkg 格式，工作流和 Chatflow 打包时会把内嵌的 Agent、Skills 和相关文件一起装进去，导入时在目标工作区重建这些资源并重新映射引用。YAML 导入导出保留，两种格式都支持文件和 URL 导入。搬家、交付、备份场景比以前传一堆 YAML 省事。（#42066、#42579、#42626、#42863）
3. 嵌套工作流可追踪
工作流里调用的 Workflow Tool 现在作为子图运行，从运行历史里点开一次工具调用，能看到子工作流内部的每一步执行轨迹，暂停、恢复、停止和文件输出也是协同管理的。要注意嵌套调用的用量统计在暂停或停止后仍可能是近似值。（#40277、#42819-#42822）
4. Agent 知识库（Beta）
新加了一套可选的 KnowledgeFS 知识空间：给 Agent 建知识区、传文件或接外部源，文档处理、元数据、检索轨迹、质量评估放在一个地方看，配套新的 Knowledge Retrieval 节点。老的 Classic Knowledge 不受影响。这是独立服务和独立数据库，默认关闭，想用要专门部署。
5. 命令行工具 difyctl
新的 difyctl 客户端从服务端的 OpenAPI 操作目录发现命令，帮助可搜索，覆盖工作流和 Chatflow 的创建、DSL 导入导出、环境变量、发布和版本回滚，草稿哈希能防止并发编辑互相覆盖。还带了给 Agent 用的 skill，difyctl install skills <dir> 装上就能让 AI 帮你建 Dify 应用。旧版登录态不通用，装完要重新登录。（#42487、#43819）
⚠️ 升级注意（这次特别多）
1. Agent 相关镜像必须一起升。/runs 接口只接受 v2 协议了，旧快照读的时候会转成 v2 存储，但旧运行时读不了新快照。API、worker、Agent Backend、Agent runtime 要在同一个维护窗口升完。
2. 本地沙箱必须配认证 token。DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN 必填且不能为空，1.17.1 的运行时镜像不支持新参数，别混搭。
3. 源码部署要 Python 3.13，Node.js 24.22.1+，pnpm 12.10.1。
4. PASSWORD_PEPPER 保持原样。原来没配的就留空，升级中途新设 pepper 会让现有密码哈希全部失效，得配套做密码重置。
5. 从 1.17.1 升上来有 22 个数据库迁移，MIGRATION_ENABLED 保持开着，先跑完迁移再起 worker。旧版 worker 要先退场再放新流量进来，不然没有新的取消保护。
6. 反代边界要复查。内置 Nginx 现在会用解析后的客户端地址替换 X-Forwarded-For，前面挂了负载均衡或 Cloudflare 的要配好 trusted real-IP，否则访客会共用代理的限流桶。
✅ 适合哪些人
✅ 工作流里跑复杂 Agent 的：Output Routes 加流式输出，编排灵活度上一个台阶
✅ 经常迁移或交付 Dify 应用的：.ifpkg 单文件打包是刚需
✅ 排查过「工作流套工作流看不出卡在哪」的：子图追踪就是给你做的
⚠️ 生产环境用户：这次升级动的东西多，先备份，挑维护窗口，四类镜像一起升
⚠️ 用老脚本直接调 /openapi/v1 的：旧的 mode-agnostic 运行路由没了，改用操作目录
🛠️ 快速升级
cd dify/docker
docker compose stop -t -1
git fetch --tags
git checkout 1.18.0
# 合并 .env 配置变更（沙箱 token、PASSWORD_PEPPER 等）
docker compose pull
docker compose up -d❓ 常见问题
Q：能从 1.17.1 直接升吗？
A：可以，但按升级指南来：备份、镜像统一升、迁移跑完、difyctl 重装重登。从更老版本升还要先完成 1.17.1 的 Weaviate 分阶段升级。
Q：Agent 知识库要马上开吗？
A：不用。默认关闭，Beta 阶段，等稳定了再评估，Classic Knowledge 照常能用。
写在最后
这版没有惊艳的新皮肤，但 .ifpkg 打包和子图追踪都是实打实解决日常痛点的。升级清单变长了也说明 Agent 架构在动大手术，生产环境别当天就冲，先在测试环境过一遍升级流程。你最想用哪个新功能？评论区聊聊。
🔗 发布页：https://github.com/langgenius/dify/releases/tag/1.18.0
#Dify #AI应用开发 #版本更新