尧图网站建设 
1. 升级前先搞清楚1.16.0 到底动了哪些底层dify 1.16.0 这次升级最容易被忽略的不是 UI 上多了个 Agent 构建器而是它把 Agent 从「工作流里的一个节点」变成了「跑在 Linux 沙箱里的独立后端服务」。这意味着你的部署拓扑变了以前一套 api worker web 就能跑现在多了agent_backend和local_sandbox两个容器Agent 的代码执行、文件读写、包安装全在沙箱里完成跟主服务做了隔离。适合谁看这篇已经用 Docker Compose 或源码部署过 dify、现在想升到 1.16.0 的开发者。如果你还没部署过这篇的配置片段也能当参考但升级步骤那部分可以先跳过。我这次升级踩的坑主要集中在三块环境变量改名没跟上导致 Agent 起不来、GPT-5.6 的 API 类型还是旧的 Chat Completions 报错、MCP 服务端版本协商没配对。下面按「前置准备 → 可复制配置 → 验证 → 排障」的顺序拆开讲配置片段都能直接抄。先明确一个概念方便后面理解Agent 沙箱就是一个受限的 Linux 运行环境Agent 在里面装包、跑脚本、读写文件即使跑飞了也炸不到你的主服务。MCP 协议是模型和外部工具之间的通信标准1.16.0 支持到 2025-06-18 版多了版本协商和结构化输出。GPT-5.6 兼容的核心是 OpenAI 把新模型的接口从 Chat Completions 换成了 Responsesdify 新配置默认走 Responses但老的自定义密钥还留着旧设置。2. 前置准备TaoToken 接入与密钥规划升级前建议先把模型接入这条链路理顺不然升完发现 Agent 调不通模型排查起来会同时怀疑沙箱和密钥两头。我自己的做法是模型请求统一走一个兼容 OpenAI 协议的网关这样 dify 里配一次 base_url 和 key后面换模型不用改代码。TaoToken 在这里的角色就是提供 OpenAI 兼容的调用入口dify 的 OpenAI 插件把 API Base 指过去就能用。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意这个不带 UTM 参数配置里填的就是它。具体到 dify 的模型供应商配置你需要准备两样东西一个 API Key和上面那个 API Base。Key 在控制台生成地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 生成后复制出来dify 里粘贴时注意别带前后空格这个坑我见过好几次报 401 但其实是空格问题。如果你后面要跑长期编码类 Agent或者想让 Agent 持续调用工具链可以了解下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。模型对话调试的入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 升级过程中想快速验证某个模型通不通直接在这里试比在 dify 里试快得多。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了不同协议的调用方式配 MCP 或者自定义模型时对着看。如果你用 Claude Code 这类工具做 Agent 开发Anthropic 兼容的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。提示升级前先把当前能用的模型配置截图存一份尤其是自定义供应商的 API 类型和 base_url回滚时能省很多事。3. 可复制配置config.toml、settings.json 与沙箱环境变量这一节是重点配置抄错一个字段 Agent 就起不来。先给一个config.toml的骨架这是源码部署时 Agent 后端读的配置Docker 部署对应的是环境变量逻辑一样。# config.toml - Agent 后端服务配置骨架 [server] host 0.0.0.0 port 5050 secret_key 替换成你生成的密钥 [redis] url redis://redis:6379/2 keepalive true keepalive_idle 300 [sandbox] backend local home_dir /home/agent landlock_enabled true landlock_version 1 [timeout] stream_read_seconds 30 run_seconds 1200secret_key一定要换生成命令是python -c import secrets; print(secrets.token_urlsafe(32))landlock_version 1这个别改成 2官方为了兼容更广的内核版本降到了 v1你改高在部分内核上会直接失败。然后是settings.json这是 MCP 服务端的配置骨架1.16.0 支持 2025-06-18 协议版本关键是protocolVersion字段{ mcpServers: { my-tool-server: { protocolVersion: 2025-06-18, transport: http, url: http://your-mcp-server:8080/mcp, headers: { X-Custom-Auth: {{request.headers.X-Custom-Auth}} }, capabilities: { tools: { listChanged: true }, structuredOutput: true } } } }注意headers里那个占位符写法这是 1.16.0 新增的运行时动态注入能力{{request.headers.X-Custom-Auth}}会在每次请求时替换成调用方传进来的头做逐请求认证透传就靠它。以前只能写死 token现在能透传了。沙箱相关的环境变量Docker 部署时写进.env# Agent 后端 AGENT_BACKEND_BASE_URLhttp://agent_backend:5050 AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS30 AGENT_BACKEND_RUN_TIMEOUT_SECONDS1200 DIFY_AGENT_SERVER_SECRET_KEY替换成生成的密钥 DIFY_AGENT_REDIS_URLredis://redis:6379/2 # 沙箱 NEXT_PUBLIC_ENABLE_AGENT_V2true # 工作流生成 WORKFLOW_GENERATION_TIMEOUT_MS180000 WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS6 # Redis 保活 REDIS_KEEPALIVE1 REDIS_KEEPALIVE_IDLE300这里有个必须注意的点ENABLE_AGENT_V2这个旧变量已经被移除了1.16.0 用的是NEXT_PUBLIC_ENABLE_AGENT_V2而且默认就是开的。如果你.env里还留着旧的删掉不然可能干扰。Docker Compose 里新增的两个服务长这样services: agent_backend: image: langgenius/dify-agent-backend:1.16.0 env_file: .env depends_on: - redis - db local_sandbox: image: langgenius/dify-agent-local-sandbox:1.16.0 env_file: .envapi和worker现在要依赖agent_backend如果你维护了自定义 compose 文件记得把depends_on补上不然启动顺序乱了 Agent 会连不上后端。4. 验证请求Agent 调用与模型兼容性实测配置写完别急着高兴先验证。分两步先验模型通不通再验 Agent 能不能在沙箱里跑起来。第一步验证 GPT-5.6 兼容性。进 dify 的模型供应商设置找到 OpenAI 那栏检查 API 类型。1.16.0 新配置默认是 Responses但如果你之前存过自定义密钥它可能还留着 Chat Completions。手动切到 Responses保存。然后用 curl 直接打一下确认网关侧没问题curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: gpt-5.6, messages: [{role: user, content: ping}] }返回里有正常的choices就说明模型链路通了。如果这里就报错别去 dify 里找问题先解决网关侧。第二步验证 Agent 沙箱。升级完执行数据库迁移docker compose exec api flask db upgrade然后进 dify 控制台新建一个 Dify Agent基础提示词随便写个「列出当前目录文件」保存后运行。正常的话你会看到它在沙箱里执行ls并返回结果。如果卡住不动多半是agent_backend没起来用这个命令看日志docker compose logs -f agent_backend看到Uvicorn running on http://0.0.0.0:5050才算正常。沙箱容器也要确认docker compose ps | grep sandbox第三步验证 MCP 服务端。把工作流发布为 MCP Server用支持 2025-06-18 的客户端连一下看版本协商是否成功。如果客户端是旧版dify 会向后兼容但结构化输出能力用不了。5. 本篇常见错排查升级过程中我遇到和收集到的报错按出现频率排一下。Agent 启动后一直 pending日志报连接拒绝。九成是AGENT_BACKEND_BASE_URL写错了。Docker 内部通信用服务名应该是http://agent_backend:5050不是localhost。源码部署才用localhost。模型调用报 400提示参数不支持。这是 GPT-5.6 走了旧 Chat Completions 接口的典型症状。去模型供应商设置把 API 类型切成 Responses。注意这个设置对已保存的自定义密钥不会自动迁移必须手动改。沙箱里装包失败报权限错误。检查landlock_enabled和landlock_version。版本必须是 1home_dir要指向沙箱内有写权限的目录。另外确认local_sandbox容器真的在跑docker compose ps里状态是 Up 才行。MCP 连接报协议版本不匹配。检查settings.json里的protocolVersion是不是2025-06-18。如果你连的服务端只支持旧版本把 dify 这边的版本降下来或者升级服务端。版本协商失败时 dify 不会自动降级到任意版本只会兼容它支持的旧客户端。升级后登录跳转异常。1.16.0 修了开放重定向漏洞同时改了重定向 URL 的保留逻辑。如果你前面挂了反向代理检查X-Forwarded-*头有没有正确传递代理配置里proxy_set_header那几行别漏。数据库迁移报错。先确认备份做了。9 个迁移文件涉及工作流版本、Agent 角色、文件系统重构等如果之前手动改过表结构可能冲突。这种情况建议在测试环境先跑一遍flask db upgrade看具体哪个迁移失败再针对性处理。注意升级前务必备份 volumes 数据尤其是 PostgreSQL 和 Redis 的卷。迁移一旦执行回滚成本很高。6. 升级后的收尾与后续接入升级完成后有几个收尾动作建议做掉。一是把.env里所有新增的 28 个变量过一遍重点确认DIFY_AGENT_SERVER_SECRET_KEY是生产级随机值不是默认值。二是检查NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW的默认值从 false 变成了 true如果你不想要预览功能手动关掉。三是把ENABLE_AGENT_V2旧变量从所有配置文件里清干净。后续如果要继续做 Agent 开发模型接入这块建议固定用一套配置。API Key 管理在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节对着文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配。想先试试模型对话效果用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速验证。长期跑编码类 Agent 的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后说个实测下来的经验dify 1.16.0 的 Agent 沙箱在首次运行时会有一次环境初始化比后续调用慢不少别以为是卡死了。等第一次跑完后面就快了。如果超过AGENT_BACKEND_RUN_TIMEOUT_SECONDS默认 1200 秒还没结果那才是真出问题了去翻agent_backend的日志找线索。 dify 1.16.0 升级实战：原生 Agent 沙箱、MCP 协议与 GPT-5.6 兼容配置一文看懂
1. 升级前先搞清楚1.16.0 到底动了哪些底层dify 1.16.0 这次升级最容易被忽略的不是 UI 上多了个 Agent 构建器而是它把 Agent 从「工作流里的一个节点」变成了「跑在 Linux 沙箱里的独立后端服务」。这意味着你的部署拓扑变了以前一套 api worker web 就能跑现在多了agent_backend和local_sandbox两个容器Agent 的代码执行、文件读写、包安装全在沙箱里完成跟主服务做了隔离。适合谁看这篇已经用 Docker Compose 或源码部署过 dify、现在想升到 1.16.0 的开发者。如果你还没部署过这篇的配置片段也能当参考但升级步骤那部分可以先跳过。我这次升级踩的坑主要集中在三块环境变量改名没跟上导致 Agent 起不来、GPT-5.6 的 API 类型还是旧的 Chat Completions 报错、MCP 服务端版本协商没配对。下面按「前置准备 → 可复制配置 → 验证 → 排障」的顺序拆开讲配置片段都能直接抄。先明确一个概念方便后面理解Agent 沙箱就是一个受限的 Linux 运行环境Agent 在里面装包、跑脚本、读写文件即使跑飞了也炸不到你的主服务。MCP 协议是模型和外部工具之间的通信标准1.16.0 支持到 2025-06-18 版多了版本协商和结构化输出。GPT-5.6 兼容的核心是 OpenAI 把新模型的接口从 Chat Completions 换成了 Responsesdify 新配置默认走 Responses但老的自定义密钥还留着旧设置。2. 前置准备TaoToken 接入与密钥规划升级前建议先把模型接入这条链路理顺不然升完发现 Agent 调不通模型排查起来会同时怀疑沙箱和密钥两头。我自己的做法是模型请求统一走一个兼容 OpenAI 协议的网关这样 dify 里配一次 base_url 和 key后面换模型不用改代码。TaoToken 在这里的角色就是提供 OpenAI 兼容的调用入口dify 的 OpenAI 插件把 API Base 指过去就能用。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意这个不带 UTM 参数配置里填的就是它。具体到 dify 的模型供应商配置你需要准备两样东西一个 API Key和上面那个 API Base。Key 在控制台生成地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 生成后复制出来dify 里粘贴时注意别带前后空格这个坑我见过好几次报 401 但其实是空格问题。如果你后面要跑长期编码类 Agent或者想让 Agent 持续调用工具链可以了解下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。模型对话调试的入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 升级过程中想快速验证某个模型通不通直接在这里试比在 dify 里试快得多。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了不同协议的调用方式配 MCP 或者自定义模型时对着看。如果你用 Claude Code 这类工具做 Agent 开发Anthropic 兼容的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。提示升级前先把当前能用的模型配置截图存一份尤其是自定义供应商的 API 类型和 base_url回滚时能省很多事。3. 可复制配置config.toml、settings.json 与沙箱环境变量这一节是重点配置抄错一个字段 Agent 就起不来。先给一个config.toml的骨架这是源码部署时 Agent 后端读的配置Docker 部署对应的是环境变量逻辑一样。# config.toml - Agent 后端服务配置骨架 [server] host 0.0.0.0 port 5050 secret_key 替换成你生成的密钥 [redis] url redis://redis:6379/2 keepalive true keepalive_idle 300 [sandbox] backend local home_dir /home/agent landlock_enabled true landlock_version 1 [timeout] stream_read_seconds 30 run_seconds 1200secret_key一定要换生成命令是python -c import secrets; print(secrets.token_urlsafe(32))landlock_version 1这个别改成 2官方为了兼容更广的内核版本降到了 v1你改高在部分内核上会直接失败。然后是settings.json这是 MCP 服务端的配置骨架1.16.0 支持 2025-06-18 协议版本关键是protocolVersion字段{ mcpServers: { my-tool-server: { protocolVersion: 2025-06-18, transport: http, url: http://your-mcp-server:8080/mcp, headers: { X-Custom-Auth: {{request.headers.X-Custom-Auth}} }, capabilities: { tools: { listChanged: true }, structuredOutput: true } } } }注意headers里那个占位符写法这是 1.16.0 新增的运行时动态注入能力{{request.headers.X-Custom-Auth}}会在每次请求时替换成调用方传进来的头做逐请求认证透传就靠它。以前只能写死 token现在能透传了。沙箱相关的环境变量Docker 部署时写进.env# Agent 后端 AGENT_BACKEND_BASE_URLhttp://agent_backend:5050 AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS30 AGENT_BACKEND_RUN_TIMEOUT_SECONDS1200 DIFY_AGENT_SERVER_SECRET_KEY替换成生成的密钥 DIFY_AGENT_REDIS_URLredis://redis:6379/2 # 沙箱 NEXT_PUBLIC_ENABLE_AGENT_V2true # 工作流生成 WORKFLOW_GENERATION_TIMEOUT_MS180000 WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS6 # Redis 保活 REDIS_KEEPALIVE1 REDIS_KEEPALIVE_IDLE300这里有个必须注意的点ENABLE_AGENT_V2这个旧变量已经被移除了1.16.0 用的是NEXT_PUBLIC_ENABLE_AGENT_V2而且默认就是开的。如果你.env里还留着旧的删掉不然可能干扰。Docker Compose 里新增的两个服务长这样services: agent_backend: image: langgenius/dify-agent-backend:1.16.0 env_file: .env depends_on: - redis - db local_sandbox: image: langgenius/dify-agent-local-sandbox:1.16.0 env_file: .envapi和worker现在要依赖agent_backend如果你维护了自定义 compose 文件记得把depends_on补上不然启动顺序乱了 Agent 会连不上后端。4. 验证请求Agent 调用与模型兼容性实测配置写完别急着高兴先验证。分两步先验模型通不通再验 Agent 能不能在沙箱里跑起来。第一步验证 GPT-5.6 兼容性。进 dify 的模型供应商设置找到 OpenAI 那栏检查 API 类型。1.16.0 新配置默认是 Responses但如果你之前存过自定义密钥它可能还留着 Chat Completions。手动切到 Responses保存。然后用 curl 直接打一下确认网关侧没问题curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: gpt-5.6, messages: [{role: user, content: ping}] }返回里有正常的choices就说明模型链路通了。如果这里就报错别去 dify 里找问题先解决网关侧。第二步验证 Agent 沙箱。升级完执行数据库迁移docker compose exec api flask db upgrade然后进 dify 控制台新建一个 Dify Agent基础提示词随便写个「列出当前目录文件」保存后运行。正常的话你会看到它在沙箱里执行ls并返回结果。如果卡住不动多半是agent_backend没起来用这个命令看日志docker compose logs -f agent_backend看到Uvicorn running on http://0.0.0.0:5050才算正常。沙箱容器也要确认docker compose ps | grep sandbox第三步验证 MCP 服务端。把工作流发布为 MCP Server用支持 2025-06-18 的客户端连一下看版本协商是否成功。如果客户端是旧版dify 会向后兼容但结构化输出能力用不了。5. 本篇常见错排查升级过程中我遇到和收集到的报错按出现频率排一下。Agent 启动后一直 pending日志报连接拒绝。九成是AGENT_BACKEND_BASE_URL写错了。Docker 内部通信用服务名应该是http://agent_backend:5050不是localhost。源码部署才用localhost。模型调用报 400提示参数不支持。这是 GPT-5.6 走了旧 Chat Completions 接口的典型症状。去模型供应商设置把 API 类型切成 Responses。注意这个设置对已保存的自定义密钥不会自动迁移必须手动改。沙箱里装包失败报权限错误。检查landlock_enabled和landlock_version。版本必须是 1home_dir要指向沙箱内有写权限的目录。另外确认local_sandbox容器真的在跑docker compose ps里状态是 Up 才行。MCP 连接报协议版本不匹配。检查settings.json里的protocolVersion是不是2025-06-18。如果你连的服务端只支持旧版本把 dify 这边的版本降下来或者升级服务端。版本协商失败时 dify 不会自动降级到任意版本只会兼容它支持的旧客户端。升级后登录跳转异常。1.16.0 修了开放重定向漏洞同时改了重定向 URL 的保留逻辑。如果你前面挂了反向代理检查X-Forwarded-*头有没有正确传递代理配置里proxy_set_header那几行别漏。数据库迁移报错。先确认备份做了。9 个迁移文件涉及工作流版本、Agent 角色、文件系统重构等如果之前手动改过表结构可能冲突。这种情况建议在测试环境先跑一遍flask db upgrade看具体哪个迁移失败再针对性处理。注意升级前务必备份 volumes 数据尤其是 PostgreSQL 和 Redis 的卷。迁移一旦执行回滚成本很高。6. 升级后的收尾与后续接入升级完成后有几个收尾动作建议做掉。一是把.env里所有新增的 28 个变量过一遍重点确认DIFY_AGENT_SERVER_SECRET_KEY是生产级随机值不是默认值。二是检查NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW的默认值从 false 变成了 true如果你不想要预览功能手动关掉。三是把ENABLE_AGENT_V2旧变量从所有配置文件里清干净。后续如果要继续做 Agent 开发模型接入这块建议固定用一套配置。API Key 管理在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节对着文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配。想先试试模型对话效果用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速验证。长期跑编码类 Agent 的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后说个实测下来的经验dify 1.16.0 的 Agent 沙箱在首次运行时会有一次环境初始化比后续调用慢不少别以为是卡死了。等第一次跑完后面就快了。如果超过AGENT_BACKEND_RUN_TIMEOUT_SECONDS默认 1200 秒还没结果那才是真出问题了去翻agent_backend的日志找线索。