引言Dify 作为一款优秀的开源 LLM 应用开发平台持续以惊人的速度迭代。2026 年 8 月 28 日Dify 正式发布1.17.0版本。本次更新堪称里程碑不仅带来了Agent 运行时架构的重构支持 E2B 云沙箱、Home Snapshots、技能管理还引入了可复用 LLM 环境变量、循环内人工输入、统一追踪、Cloudflare Turnstile、Azure Key Vault、TiDB 向量全文搜索等大量重磅功能。此外安全加固、可访问性大幅提升、工作流稳定性改进以及大量 Bug 修复让这个版本成为生产环境升级的优选。本文将基于官方发布说明全面解析 Dify 1.17.0 的所有新特性、改进、安全增强、环境变量变更、数据库迁移以及升级指南帮助开发者和运维人员快速了解并顺利升级。一、Agent 领域重大升级从本地沙箱到云端 E2B再到技能管理1. E2B 云沙箱支持此前 Dify Agent 的 shell/代码执行只能运行在本地沙箱中。1.17.0 引入了E2B 云沙箱后端用户可以通过设置DIFY_AGENT_RUNTIME_BACKEND选择后端。新增的docker-compose.e2b.yaml文件可以直接部署 E2B 组件栈同时 E2B 流量经过身份验证模板也会在发布时同步。这意味着 Agent 执行环境可以弹性扩展、隔离性更好非常适合生产级部署。2. 构建时 Home Snapshots主目录快照当 Agent 构建被应用发布时系统会捕获 Agent 沙箱主目录的完整状态——包括已安装的包、准备的文件和工作状态。后续运行已发布的 Agent 时将从该快照恢复主目录确保 Agent 从构建时的精确文件系统状态启动。这一特性极大地提升了 Agent 的可重现性和一致性。3. 工作区级别的 Skill 管理Skills技能是可复用、带版本控制的能力包包含代码和工具定义Agent 可以发现并调用它们。1.17.0 新增了工作区级别的技能管理器支持草稿 → 发布 → 版本生命周期并配套 Web UI技能列表、构建面板、文件编辑器。开发者可以像管理代码库一样管理 Agent 技能实现能力沉淀与共享。4. 上下文感知的历史压缩长对话不再撑爆模型上下文窗口。Dify 会解析每个模型的有效窗口并分层压缩先清理旧的工具结果然后总结更早的历史从而在预算内保留最近的上下文。这显著提升了长时间运行的 Agent 的稳定性和成本效率。二、可复用 LLM 环境变量一处定义处处引用在复杂工作流中多个 LLM 节点往往需要配置相同的提供商、模型、模式和参数。1.17.0 允许用户定义一次共享的 LLM 环境变量例如for_summarize、for_research然后在任意 LLM 节点中引用。当需要切换模型或调整参数时只需修改一处所有节点自动同步。该引用关系在 DSL 导入导出、片段、RAG 管道和协作编辑中都能正确保持极大降低了维护成本。三、循环与迭代节点内支持人工输入Human-in-the-Loop此前人工输入表单只能在主流程中暂停和恢复。1.17.0 实现了在 Loop 和 Iteration 节点内部使用人工输入并且支持跨页面刷新正确暂停和恢复适用于调试和已安装的应用。这使得在重复性工作中加入审核、批准等人工干预步骤成为可能大幅扩展了工作流的适用场景。四、统一追踪Provider-Neutral Unified TracingOPS_TRACE_UNIFIED_ENABLED开启后系统在核心层一次性组装完整的父子 span 树工作流、聊天流、消息、节点、循环、迭代、嵌套工作流然后仅将传输委托给轻量级适配器。首批适配器包括Phoenix和LangSmith默认关闭完全向后兼容。新增的 GenAI span 可以展示 LLM TTFT、Agent ReAct 步骤、工具调用以及失败的 LLM 节点为深度可观测性提供了强大支持。五、Cloudflare Turnstile 验证码支持为了防护认证端点被滥用1.17.0 引入了可选的Turnstile 挑战用于登录和邮箱验证码登录流程。管理员可以配置站点密钥、密钥和允许的主机名。这为自托管实例增加了一层机器人防护且无需牺牲用户体验Turnstile 通常无需用户交互。六、Azure Key Vault / 可插拔 KMS新版本引入了KMS 提供者抽象并首先支持 Azure Key Vault用于密钥配置、加密和解密支持密钥轮换配置。这是迈向外部管理加密密钥的重要一步满足企业级安全合规需求。七、TiDB Vector 全文与混合搜索TiDB Vector 部署现在可以启用全文检索和混合检索TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH默认关闭使用多语言全文索引与向量搜索结合提升检索效果。八、更广泛的模型与文件处理图像文件直接传递给多模态模型LLM 节点和 Agent 现在可以将图像文件直接传递给多模态模型非视觉附件不再被静默丢弃。多模态检索指导帮助用户为包含图像的知识库正确选择嵌入模型。音频 ASR 支持audio/x-m4a音频 MIME 类型验证更准确。九、Go to Anything (⌘K / CtrlK)在任何控制台页面按下⌘KWindows/Linux 为CtrlK即可打开命令面板快速跳转到应用、Agent、技能、知识库、插件或工作流节点或通过斜杠命令触发快捷操作。本版本中Agent 和技能也可被搜索图标命令系统在所有域中重构以保持一致性。十、其他新增功能ODTOpenDocument Text文档提取。工具插件的日期 / 日期选择器参数类型。老挝语lo-LA语言支持。旧对话自动清理任务ENABLE_CONVERSATION_CLEANUP_TASK控制数据增长。市场直接嵌入集成分类工具/插件发现更流畅。十一、改进亮点1. 大规模可访问性a11y优化数百处控制台改进使其对键盘和屏幕阅读器友好真实的button语义、图标操作的辅助名称、认证/安装页面的主标题、键盘可访问的成员/工具选择器以及正确的 ARIA 状态。2. 工作流创作体验提升工作流生成器现在优先推荐已安装和配置的工具。画布状态在历史更新后得到保留不再出现刷新渲染循环。3. 工作流与运行时稳定性Web 工作流运行可重现。SSE 流在终端事件时干净结束。stop在非流式节点间被正确遵守。暂停的工作流清除过期的取消信号。默认执行时间从 1200 秒提高到 3600 秒。4. 内部质量大量单元测试迁移到真实 ORM 模型 / SQLite 会话类型更严格不影响用户行为。十二、安全增强认证加固Turnstile 挑战、邮箱验证码尝试限制和令牌过期、暂停电子邮件域处理、短期 Agent 授权令牌。访问控制 / 所有权范围数据集、文档、RAG、对话、工作区凭证、OAuth 客户端等资源均绑定到其所有者和应用范围关闭了多个未授权访问路径。SSRF 与出站加固出站 HTTP 连接阶段限制为 5 秒Agent/binding 下载和运行超时可配置SSRF 阻止错误消息更准确。十三、Bug 修复精选防止 Redis Streams 中丢失workflow_started事件以及被取代执行的运行丢失/重复。将工作流时间戳标准化为 naive UTC为失败、取消和中断的运行保留快照和历史。防止跨标签页聊天对话切换不再丢弃 Agent 聊天中的非视觉附件。修复 Qwen/VL 系统消息顺序合并系统消息并置于最前。修复 Elasticsearch-JA 适配器的document_id映射和 VectorType。避免 Bedrock 空 schema 字段。所有 nginx 上游使用动态 DNS 解析。保留文本上传的 UTF-8 字节大小。大量 Web/UI 修复恢复邮箱验证码和密码表单提交、移动端登录溢出、Toast 堆叠、模型选择器间距等。十四、环境变量变更新增变量Agent 运行时 / 沙箱DIFY_AGENT_RUNTIME_BACKENDDIFY_AGENT_RUN_TIMEOUT_SECONDSDIFY_AGENT_SANDBOX_FILES_BASE_URLDIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMITDIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDSDIFY_AGENT_E2B_API_KEYDIFY_AGENT_E2B_TEMPLATEDIFY_AGENT_E2B_SHELLCTL_PORTDIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDSDIFY_AGENT_LOCAL_SANDBOX_ENDPOINTDIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKENDIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUTDIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUTDIFY_AGENT_OUTBOUND_HTTP_WRITE_TIMEOUTDIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUTDIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRYDIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONSDIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONSAGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDSAGENT_BACKEND_HOME_SNAPSHOT_TIMEOUT_SECONDS认证 / 安全TURNSTILE_SITE_KEYTURNSTILE_SECRET_KEYTURNSTILE_ALLOWED_HOSTNAMESTURNSTILE_EMAIL_CODE_VERIFY_REQUIREDEMAIL_CODE_LOGIN_MAX_ATTEMPTSEMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTESKEY_PROVIDER_TYPEAZURE_KEYVAULT_VAULT_URLAZURE_KEYVAULT_KEY_SIZEAZURE_KEYVAULT_ROTATION_INTERVAL_DAYS知识库 / 检索TIDB_VECTOR_ENABLE_FULLTEXT_SEARCHTIDB_ON_QDRANT_ESTIMATED_STORAGE_LIMITS_MBKNOWLEDGE_UPLOAD_FILE_SIZE_LIMIT_FOR_PAID_PLAN追踪 / 可观测性OPS_TRACE_UNIFIED_ENABLEDOPS_TRACE_PARENT_CONTEXT_TTL_SECONDS其他ENABLE_CONVERSATION_CLEANUP_TASKCONVERSATION_CLEANUP_TASK_INTERVALCONVERSATION_CLEANUP_BATCH_SIZEUPLOAD_SKILL_FILE_SIZE_LIMITPLUGIN_MAX_FILE_SIZEMARKDOWN_FORM_FIELD_NAME_EXTRA_CHARSDEPLOYMENT_EDITION替代EDITION移除变量EDITION→ 重命名为DEPLOYMENT_EDITIONENTERPRISE_ENABLEDAGENT_BACKEND_RUN_TIMEOUT_SECONDS→ 被DIFY_AGENT_RUN_TIMEOUT_SECONDS取代DIFY_AGENT_SHELLCTL_AUTH_TOKENDIFY_AGENT_SHELLCTL_ENTRYPOINT修改默认值APP_MAX_EXECUTION_TIME1200 → 3600WORKFLOW_MAX_EXECUTION_TIME1200 → 3600OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES60 → 780GRAPH_ENGINE_SCALE_UP_THRESHOLD3 → 0十五、Docker Compose 变更docker/docker-compose.yaml— 修改docker/docker-compose.middleware.yaml— 修改docker/docker-compose.e2b.yaml—新增E2B Agent 沙箱组件栈十六、数据库迁移本版本包含以下新迁移社区版相关add_workflow_version_number— 工作流版本号部署 v2add_oauth_provider_app_auto_authorize— 静默 OAuth 授权标志add_conversation_cleanup_index— 支持对话清理任务add_workspace_skill_management— 工作区技能管理add_agent_home_snapshot_ledger、make_home_snapshot_references_nullable— Agent 构建时 Home Snapshot 台账及可空引用replace_agent_runtime_sessions_with_*、remove_agent_drive、clean_legacy_agent_soul_files、simplify_agent_v2_output_contract— 新 Agent 运行时这些迁移无需手动回填命令升级时运行flask db upgrade即可。十七、升级指南重要提示包含新数据库迁移升级时必须执行。环境变量变化显著大量新增、EDITION重命名为DEPLOYMENT_EDITION、多个默认值修改请仔细检查.env并更新。Docker Compose 配置有变化新增了docker-compose.e2b.yaml自定义 compose 文件需重新应用本地修改。add_conversation_cleanup_index迁移会在现有数据上创建索引若对话表很大执行时间可能较长。Docker Compose 部署备份自定义 compose 和环境文件cddockercpdocker-compose.yaml docker-compose.yaml.$(date%s).bakcp.env .env.$(date%s).bak2/dev/null||true获取最新代码gitfetch--tagsgitcheckout main# 或目标发布标签停止服务dockercompose down备份数据卷tar-cvfvolumes-$(date%s).tgz volumes检查环境变量变化并重新应用本地定制记得EDITION→DEPLOYMENT_EDITION。升级dockercompose up-d源码部署停止 API 服务器、Worker 和 Web 前端。获取最新代码gitfetch--tagsgitcheckout main# 或目标发布标签更新 Python 依赖cdapi uvsync运行迁移uv run flask db upgrade重建/重启 Web 前端然后重启 API 服务器和 Worker。结语代码地址github.com/langgenius/difyDify 1.17.0 是一次全面的飞跃尤其在Agent 基础设施、企业级安全和可观测性方面。E2B 云沙箱和 Home Snapshots 让 Agent 具备生产级的隔离与一致性技能管理开启了能力复用的新篇章统一追踪和可复用 LLM 环境变量大幅提升开发与运维效率。安全加固和访问控制修复也表明 Dify 团队对生产环境的高度重视。