1. dify 1.17.0 升级前先搞清楚这次到底改了什么dify 1.17.0 是 Dify 开源 LLM 应用开发平台的一次大版本迭代核心变化集中在三块Agent 运行时从本地沙箱扩展到云端 E2B 沙箱、工作区级别的技能管理Skill Management、以及 Provider-Neutral 的统一追踪Unified Tracing。如果你正在用 Dify 跑 Agent、工作流或者 RAG 管道这个版本值得认真评估因为它不只是加功能还动了 Agent 运行时的底层架构和一批环境变量。先说适合谁看。第一类是自己用 Docker Compose 部署 Dify 的开发者这次新增了docker-compose.e2b.yaml自定义过 compose 文件的人需要重新合并本地改动。第二类是重度使用 Agent 节点的团队E2B 云沙箱和 Home Snapshots 直接改变 Agent 的执行隔离性和可重现性。第三类是运维和平台同学环境变量有大量新增、重命名和默认值调整EDITION被DEPLOYMENT_EDITION替代APP_MAX_EXECUTION_TIME从 1200 秒提到 3600 秒这些都会影响现有部署。我试过在测试环境先跑一遍迁移最直观的感受是这次升级的“坑”不在代码而在配置。数据库迁移本身用flask db upgrade就能过但如果你没同步更新.env服务起来后会因为找不到旧变量而报错或者新特性默认关闭导致你以为功能没生效。所以这篇不打算把发布说明复述一遍而是按“能不能迁移、怎么迁移、迁移后怎么验证”的顺序把可复制的步骤和排障点讲清楚。需要提前说明的是Dify 1.17.0 的迁移包含新数据库迁移升级时必须执行不能跳过。另外add_conversation_cleanup_index这个迁移会在现有对话表上建索引如果对话数据量很大执行时间可能比较长建议放在低峰期做。下面从环境准备开始一步步来。2. TaoToken 前置给 Dify 的模型调用准备一个稳定入口Dify 本身是应用编排平台它自己不产出模型能力Agent 节点、LLM 节点最终都要调用外部模型 API。很多人在升级 Dify 之后发现工作流跑不通排查半天以为是版本问题结果卡在模型接入这一层。所以在动 Dify 之前先把模型调用入口理顺能省掉大量误判。TaoToken 在这里的角色是提供一个兼容 OpenAI 接口规范的模型调用入口Dify 的模型供应商配置里可以直接按 OpenAI 兼容方式接入。它的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时直接填 Base URL 即可。控制台和密钥管理在https://taotoken.net/console模型对话调试页面在https://taotoken.net/model-chat接入文档在https://taotoken.net/doc。为什么要在 Dify 升级前做这件事因为 Dify 1.17.0 引入了“可复用 LLM 环境变量”多个 LLM 节点可以引用同一个共享配置。如果你在升级前就把模型入口和 Key 固定下来升级后只需要在共享变量里改一处所有节点自动同步不用逐个节点去改 Base URL 和 Key。这个特性在复杂工作流里特别实用后面第 3 节会给具体配置。具体操作上先在控制台创建一个 API Key然后拿这个 Key 去模型对话页面做一次最小验证确认能正常返回。验证通过后再进 Dify 配置避免把“Key 无效”和“Dify 配置错误”混在一起排查。如果你后续要做长期编码类 Agent 或者需要跑大量自动化任务可以关注 Coding Plan 相关的额度方案入口在https://taotoken.net/coding-plan。这一步不涉及 Dify 内部改动属于前置准备做完再进升级流程。3. 可复制配置Dify 1.17.0 的 .env 与 compose 改动这一节是全文最需要动手的部分。Dify 1.17.0 的环境变量变化很大我把它拆成“必须改”“建议开”“注意默认值”三类配合可直接复制的片段。先备份。进到 Dify 的 docker 目录把现有配置存一份带时间戳的副本cd docker cp docker-compose.yaml docker-compose.yaml.$(date %s).bak cp .env .env.$(date %s).bak 2/dev/null || true然后拉取新代码并切到目标版本git fetch --tags git checkout main停服务、备份数据卷这一步别省docker compose down tar -cvf volumes-$(date %s).tgz volumes接下来是.env的关键改动。第一处必须改EDITION已被移除重命名为DEPLOYMENT_EDITION。如果你原来的.env里有EDITIONCOMMUNITY要改成DEPLOYMENT_EDITIONCOMMUNITY第二处ENTERPRISE_ENABLED被移除如果存在请删掉。第三处旧的AGENT_BACKEND_RUN_TIMEOUT_SECONDS被DIFY_AGENT_RUN_TIMEOUT_SECONDS取代旧的DIFY_AGENT_SHELLCTL_AUTH_TOKEN和DIFY_AGENT_SHELLCTL_ENTRYPOINT也已移除。如果你要启用 E2B 云沙箱需要设置运行时后端和 E2B 相关参数DIFY_AGENT_RUNTIME_BACKENDe2b DIFY_AGENT_E2B_API_KEYyour_e2b_api_key DIFY_AGENT_E2B_TEMPLATEyour_template_id DIFY_AGENT_E2B_SHELLCTL_PORT5000 DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS3600 DIFY_AGENT_RUN_TIMEOUT_SECONDS3600如果继续用本地沙箱则保留本地后端并配置端点DIFY_AGENT_RUNTIME_BACKENDlocal DIFY_AGENT_LOCAL_SANDBOX_ENDPOINThttp://sandbox:8194 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKENyour_local_token统一追踪默认关闭要开启就加OPS_TRACE_UNIFIED_ENABLEDtrue OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS3600TiDB Vector 的全文与混合检索也是默认关闭TIDB_VECTOR_ENABLE_FULLTEXT_SEARCHtrue认证加固方面如果要启用 Cloudflare TurnstileTURNSTILE_SITE_KEYyour_site_key TURNSTILE_SECRET_KEYyour_secret_key TURNSTILE_ALLOWED_HOSTNAMESyour.domain.com TURNSTILE_EMAIL_CODE_VERIFY_REQUIREDtrue EMAIL_CODE_LOGIN_MAX_ATTEMPTS5 EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES15企业级密钥管理如果要用 Azure Key VaultKEY_PROVIDER_TYPEazure_keyvault AZURE_KEYVAULT_VAULT_URLhttps://your-vault.vault.azure.net/ AZURE_KEYVAULT_KEY_SIZE2048 AZURE_KEYVAULT_ROTATION_INTERVAL_DAYS90对话自动清理任务按需开启ENABLE_CONVERSATION_CLEANUP_TASKtrue CONVERSATION_CLEANUP_TASK_INTERVAL86400 CONVERSATION_CLEANUP_BATCH_SIZE1000默认值变化要特别注意APP_MAX_EXECUTION_TIME和WORKFLOW_MAX_EXECUTION_TIME都从 1200 提到 3600OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES从 60 提到 780GRAPH_ENGINE_SCALE_UP_THRESHOLD从 3 变成 0。如果你之前显式设过这些值要确认是否还符合预期。Docker Compose 文件也有变化docker/docker-compose.yaml和docker/docker-compose.middleware.yaml被修改新增了docker/docker-compose.e2b.yaml。如果你自定义过 compose需要把本地改动重新应用到新文件上尤其是端口映射、卷挂载和环境变量注入部分。配置改完启动服务docker compose up -d源码部署的话流程是停 API、Worker、Web拉代码cd api uv sync然后跑迁移uv run flask db upgrade再重建 Web 前端重启 API 和 Worker。迁移包含add_workflow_version_number、add_workspace_skill_management、add_agent_home_snapshot_ledger等不需要手动回填flask db upgrade会自动处理。4. 验证请求确认新特性真的生效了服务起来不代表新特性生效Dify 1.17.0 很多功能默认关闭需要逐项验证。这一节给一套可执行的验证清单按优先级排。第一项确认版本和迁移状态。进 API 容器执行docker compose exec api flask db current输出应该显示最新的迁移版本号。如果显示的还是旧版本说明flask db upgrade没跑成功回去看日志。第二项验证可复用 LLM 环境变量。在 Dify 控制台新建一个工作流加两个 LLM 节点在节点配置里选择引用同一个共享 LLM 变量比如for_summarize。然后修改这个共享变量的模型或参数观察两个节点是否同步变化。这个特性在 DSL 导入导出、片段、RAG 管道里都会保持引用关系可以顺手导出 DSL 再导入确认引用没丢。第三项验证 Agent 沙箱后端。如果你启用了 E2B创建一个带代码执行或 shell 的 Agent 应用发布后运行一次看执行日志里沙箱环境是否是云端 E2B。同时验证 Home Snapshots发布 Agent 时系统会捕获主目录状态后续运行从快照恢复。你可以故意在构建时装一个包发布后运行确认包还在。第四项验证技能管理。进工作区设置找到技能管理器创建一个草稿技能走一遍草稿到发布到版本的生命周期。然后在 Agent 里让 Agent 发现并调用这个技能。Web UI 里有技能列表、构建面板和文件编辑器可以逐个点一遍。第五项验证统一追踪。开启OPS_TRACE_UNIFIED_ENABLED后跑一个包含工作流、聊天流、节点、循环、迭代、嵌套工作流的复杂流程然后去 Phoenix 或 LangSmith 看 span 树是否完整。新增的 GenAI span 应该能看到 LLM TTFT、Agent ReAct 步骤、工具调用和失败的 LLM 节点。第六项验证循环内人工输入。建一个 Loop 或 Iteration 节点在内部插入人工输入表单运行到该节点时应该能暂停刷新页面后还能恢复。这个特性对调试和已安装应用都适用。第七项验证图像直传多模态模型。在 LLM 节点或 Agent 里上传一张图片确认能直接传给多模态模型而不是被静默丢弃。同时检查音频 ASR 是否支持audio/x-m4a。第八项验证 Go to Anything。在任意控制台页面按CtrlKMac 是⌘K看命令面板能否搜索应用、Agent、技能、知识库、插件和工作流节点。如果这些验证里有一项不通过先别急着回滚大概率是配置没开或者环境变量没生效。下一节按真实报错来排查。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth升级 Dify 1.17.0 后遇到的报错很多不是版本 bug而是配置迁移没做全。下面按真实报错逐个拆。401 Unauthorized。这个最常见分两种。一种是模型调用返回 401说明 API Key 无效或 Base URL 配错。检查 Dify 模型供应商里的 Base URL 是否是https://taotoken.net/apiKey 是否和控制台里创建的一致。另一种是 Dify 自身接口返回 401通常是DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN或短期 Agent 授权令牌配置不一致。1.17.0 引入了短期 Agent 授权令牌如果你自定义过认证逻辑要确认令牌过期时间设置合理。local proxy failed。这个报错通常出现在 Agent 沙箱连接阶段。如果你把DIFY_AGENT_RUNTIME_BACKEND设成了e2b但DIFY_AGENT_E2B_API_KEY或DIFY_AGENT_E2B_TEMPLATE没填沙箱就连不上。反过来如果你继续用本地沙箱要确认DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT指向的 sandbox 服务已经起来并且DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN和 sandbox 侧一致。1.17.0 还新增了出站 HTTP 连接阶段 5 秒限制如果沙箱出站请求慢也会表现为连接失败可以调DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT。reading choices 相关报错。这类报错一般出现在模型返回结构解析阶段典型信息是读取choices字段失败。原因通常是模型返回了非标准结构或者流式响应在终端事件时没有干净结束。1.17.0 修复了 SSE 流在终端事件时干净结束的问题如果你还遇到先确认 Dify 版本确实是 1.17.0再检查模型供应商是否返回了 OpenAI 兼容格式。用 TaoToken 的模型对话页面单独测一次能快速区分是模型侧还是 Dify 侧的问题。OAuth 相关报错。1.17.0 新增了add_oauth_provider_app_auto_authorize迁移引入了静默 OAuth 授权标志同时把 OAuth 客户端等资源绑定到所有者和应用范围。如果你之前配过 OAuth 登录升级后要重新检查 OAuth 客户端的授权范围。报错信息里如果出现auto_authorize或 scope 不匹配去数据库确认迁移是否执行再检查 OAuth 应用配置。Codex auth.json / CC Switch / Cline MCP 场景。如果你在 Dify 之外还用 Codex、CC Switch 或 Cline 这类工具接模型配置三件套要写全Base URL、Key、Model ID。Base URL 用https://taotoken.net/apiKey 用控制台创建的Model ID 按实际模型填。这三者缺一个都会报认证或模型不存在。Dify 1.17.0 的可复用 LLM 环境变量思路其实一样把这三件套抽成共享配置改一处全局生效。迁移卡住或超时。add_conversation_cleanup_index在大表上建索引可能很慢。如果卡住先确认数据库连接正常再看是否有锁等待。建议在低峰期执行必要时可以先手动建索引再跑迁移。另外GRAPH_ENGINE_SCALE_UP_THRESHOLD默认值从 3 变成 0如果你之前依赖这个阈值做扩缩容要重新评估。服务起来但新特性没生效。先查.env是否被正确加载Docker Compose 下改完.env要docker compose up -d重建容器不是 restart。再确认对应开关是否设为true统一追踪、TiDB 全文检索、对话清理任务都是默认关闭的。6. 迁移决策与后续接入入口回到最初的问题Dify 1.17.0 值不值得迁。如果你在用 Agent 做生产级任务E2B 云沙箱和 Home Snapshots 带来的隔离性和可重现性是实打实的提升技能管理让能力沉淀有了版本控制统一追踪补上了可观测性这块短板。如果你只是跑简单工作流升级的主要收益在稳定性修复和安全加固比如工作流时间戳标准化、Redis Streams 事件丢失修复、SSRF 出站加固这些对生产环境同样重要。迁移的决策点在于配置工作量。环境变量变化多自定义 compose 需要重新合并大表索引迁移可能耗时。建议先在测试环境完整走一遍第 3 节的配置和第 4 节的验证清单确认无误再上生产。生产升级前务必备份数据卷tar -cvf volumes-$(date %s).tgz volumes这条命令别省。模型接入这块Dify 1.17.0 的可复用 LLM 环境变量让多节点共享配置变得简单但前提是模型入口本身稳定。TaoToken 的 API 地址https://taotoken.net/api可以直接作为 OpenAI 兼容 Base URL 填进 Dify 模型供应商Key 在https://taotoken.net/api-keys管理接入细节看https://taotoken.net/doc。调试模型返回结构时用https://taotoken.net/model-chat单独验证能快速定位是模型侧还是 Dify 侧的问题。如果你要跑长期编码类 Agent 或大量自动化任务https://taotoken.net/coding-plan有对应的额度方案可以参考。最后给一个实操建议升级完成后先别急着开所有新特性。按“可复用 LLM 环境变量 → 技能管理 → 统一追踪 → E2B 沙箱”的顺序逐项开启和验证每开一项跑一次核心工作流确认没问题再开下一项。这样出问题时能快速定位到具体是哪个特性引入的比一次性全开再排查高效得多。