Dify v1.16.0 是 7 月 17 日发布的大版本更新。上一篇文章聊了新特性，这篇专门聊升级时会踩的坑。如果你正在用 Dify 跑生产环境，建议逐条看完再动手。
这次升级，为什么格外要小心？
说实话，Dify 每个大版本都会有环境变量变动，但 1.16.0 的力度是空前的：28 个新增环境变量、1 个删除、1 个修改，Docker Compose 新增两个服务，还有 9 个数据库迁移。
任何一个环节漏掉，轻则启动报错，重则数据异常。下面按坑的严重程度排序，逐个讲清楚。
坑 1：GPT-5.6 用户必看——API 类型悄悄改了
这个坑最隐蔽。
Dify 的 OpenAI 插件之前默认用的是 Chat Completions API，但从 1.16.0 开始，新配置的默认值改成了 Responses API。
为什么要改？因为 OpenAI 自己已经在今年早些时候废弃了 Chat Completions API，而 GPT-5.6 系列模型在 Chat Completions 下有大量奇怪的参数限制——OpenAI 只给它提供最低限度的兼容支持。换句话说，不是 Dify 的问题，是 OpenAI 那边不保证 Chat Completions 对 GPT-5.6 的行为正确。
踩坑场景： 如果你之前配置过自定义 OpenAI API Key，那个配置里的 API 类型还是旧的 Chat Completions。升级后 Dify 不会自动帮你改，你的 GPT-5.6 请求可能开始出现奇怪的报错，而这些报错看起来像是 Dify 的锅。
怎么修：
-
打开 Dify 后台 → 设置 → 模型供应商 → OpenAI -
检查你之前保存的 API Key 配置 -
把 API 类型从 Chat Completions 切到 Responses -
如果你还在用 GPT-4o 或更老的模型，理论上两种 API 都能跑，但建议也切过来，迟早的事
坑 2：Docker Compose 大变——两个新服务必须加
1.16.0 的 Docker Compose 配置变动非常大，新增了两个关键服务：
-
agent_backend（langgenius/dify-agent-backend:1.16.0）：Dify Agent 的后端服务，处理 Agent 的运行调度 -
local_sandbox（langgenius/dify-agent-local-sandbox:1.16.0）：Agent 的本地沙箱环境，跑 shell 命令和代码执行
而且，原有的 api 和 worker 服务现在 依赖 agent_backend。如果你用的是自定义的 docker-compose.yaml，升级后直接 docker compose up -d 会起不来。
操作步骤：
-
备份你的自定义 docker-compose.yaml -
对照官方的最新配置，把 agent_backend和local_sandbox两个服务加进去 -
确认 api和worker的depends_on里包含agent_backend -
检查网络和卷的配置是否一致
如果你没有魔改过 compose 文件，直接拉官方最新版覆盖就行。
坑 3：环境变量——28 个新增，3 个必须重点关注
28 个新增环境变量大部分是 Dify Agent 相关的，有默认值一般不会出问题。但有 3 个你必须手动处理：
① DIFY_AGENT_SERVER_SECRET_KEY——必须替换！
这个变量用于 Agent Stub 的 JWE 加密密钥，默认给的是开发环境的值。生产环境必须替换，否则你的 Agent 认证信息等于裸奔。
生成方法：
把生成的随机字符串填到 .env 文件的 DIFY_AGENT_SERVER_SECRET_KEY 里。
② ENABLE_AGENT_V2 → NEXT_PUBLIC_ENABLE_AGENT_V2——改名了
旧变量 ENABLE_AGENT_V2 被删除了，替代它的是 NEXT_PUBLIC_ENABLE_AGENT_V2，默认值从 false 变成了 true。如果你之前在 .env 里写了 ENABLE_AGENT_V2=false 来禁用 Agent，现在要改成 NEXT_PUBLIC_ENABLE_AGENT_V2=false，不然升级后 Agent 功能会默认打开。
③ NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW——默认值从 false 变成 true
这个变量控制是否启用实验性功能。如果你之前显式设置过 false，升级后如果不更新配置文件，可能会被覆盖成 true。建议检查一下你的 .env。
坑 4：数据库迁移——9 个新迁移，顺序执行
这次有 9 个数据库迁移文件，涵盖 Agent 配置、工作流归档、Web App 占位文字等功能。
升级后必须执行：
注意事项：
-
先备份数据库再执行迁移 -
如果你是源码部署，确保在 api目录下执行 -
迁移过程中不要中断，9 个迁移之间有依赖关系 -
如果之前跳过某个小版本的迁移，这次要确保所有历史迁移都执行过
坑 5：MCP 协议升级——兼容但有前提
好消息是 MCP 协议的升级做了向后兼容处理，老版本的 MCP Client 仍然能正常工作。
但有两个新特性你需要知道，因为它们可能影响你的工具链集成：
① 版本协商：MCP Server 现在支持协议版本自动协商。如果你的 MCP Client 也在更新，升级后会自动匹配到 2025-06-18 版本，享受结构化工具输出等新能力。
② 动态 Header 注入：MCP Client 连接现在支持在运行时注入 HTTP 请求头，语法是 {{request.headers.X-Custom-Auth}}。这意味着你可以实现每次请求的认证透传，不用把鉴权信息写死在 MCP 配置里。
潜在坑点： 如果你的 MCP 工具链依赖特定的请求头格式做鉴权，升级后动态注入可能会跟你的逻辑冲突。建议升级后先测试一下 MCP 连接是否正常。
坑 6：安全加固——生产环境必须尽快升级的理由
这次修复了几个比较严重的安全问题：
-
SQL 注入：关闭了一个 SQL 注入漏洞，加强了元数据 key 的校验。如果你之前用的是 1.15.x 或更早的版本，这个漏洞是存在的 -
SSRF 绕过：API 工具 schema 获取中的 SSRF 绕过被修复。攻击者可以通过构造恶意 API 工具 schema 来绕过 SSRF 防护 -
开放重定向：登录后和认证流程中的开放重定向漏洞被修复 -
Landlock 保护：Agent HOME 目录用 Landlock 做了文件系统保护，降级到 v1 以兼容更多内核版本
如果你的 Dify 实例是公网暴露的，这些安全修复是必须尽快打上的。
升级清单（建议截图保存）
-
✅ 备份 docker-compose.yaml和.env文件 -
✅ 备份数据库（ pg_dump） -
✅ 拉取最新代码或 compose 配置 -
✅ 对照官方 .env.example更新环境变量，重点处理上面 3 个关键变量 -
✅ 生成并替换 DIFY_AGENT_SERVER_SECRET_KEY -
✅ 把 ENABLE_AGENT_V2替换为NEXT_PUBLIC_ENABLE_AGENT_V2 -
✅ 确认 Docker Compose 新增了 agent_backend和local_sandbox服务 -
✅ docker compose down→docker compose up -d -
✅ 执行 flask db upgrade（源码部署）或确认容器启动时自动迁移 -
✅ 检查 OpenAI 插件的 API 类型是否已切到 Responses -
✅ 测试 MCP 连接是否正常 -
✅ 测试 Agent 功能是否按预期工作
写在最后
Dify 1.16.0 的升级复杂度在 Dify 的历史版本里算高的。Agent 系统的引入让整体架构多了一层，环境变量和 compose 配置的变动是必然的。
但只要按清单走，一步步来，其实也没有那么可怕。最怕的是看到发版公告就直接 git pull && docker compose up -d，然后对着满屏报错发呆。
生产环境建议先在测试环境跑一遍，确认没问题再上生产。
GitHub Release：https://github.com/langgenius/dify/releases/tag/1.16.0
升级遇到问题欢迎评论区交流，我会逐条回复。觉得有用点个「在看」，让更多人少踩坑。
推荐标签
#Dify# #Dify升级# #DifyAgent# #GPT5_6# #MCP# #AI工作流# #Agent开发# #开源AI# #大模型应用# #自托管运维#
Dify社区群：嗨聊吧
友情提示：纯技术社区嗨聊社群已满，请添加微信:winteroak,邀请加入海聊吧！