dify 1.17.0发布：Agent沙箱云端化、技能管理、统一追踪等超多新特性！

引言

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 Tracing）

OPS_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 类型验证更准确。

在任何控制台页面按下⌘K（Windows/Linux 为Ctrl+K）即可打开命令面板，快速跳转到应用、Agent、技能、知识库、插件或工作流节点，或通过斜杠命令触发快捷操作。本版本中，Agent 和技能也可被搜索，图标命令系统在所有域中重构以保持一致性。

十、其他新增功能

• •ODT（OpenDocument Text）文档提取。

• •工具插件的日期 / 日期选择器参数类型。

• •老挝语（lo-LA）语言支持。

• •旧对话自动清理任务（ENABLE_CONVERSATION_CLEANUP_TASK），控制数据增长。

• •市场直接嵌入集成分类，工具/插件发现更流畅。

数百处控制台改进使其对键盘和屏幕阅读器友好：真实的语义、图标操作的辅助名称、认证/安装页面的主标题、键盘可访问的成员/工具选择器以及正确的 ARIA 状态。

2. 工作流创作体验提升

• • 工作流生成器现在优先推荐已安装和配置的工具。

• • 画布状态在历史更新后得到保留，不再出现刷新渲染循环。

• • Web 工作流运行可重现。

• • SSE 流在终端事件时干净结束。

• •stop在非流式节点间被正确遵守。

• • 暂停的工作流清除过期的取消信号。

• • 默认执行时间从 1200 秒提高到 3600 秒。

大量单元测试迁移到真实 ORM 模型 / SQLite 会话，类型更严格，不影响用户行为。

十二、安全增强

• •认证加固：Turnstile 挑战、邮箱验证码尝试限制和令牌过期、暂停电子邮件域处理、短期 Agent 授权令牌。

• •访问控制 / 所有权范围：数据集、文档、RAG、对话、工作区凭证、OAuth 客户端等资源均绑定到其所有者和应用范围，关闭了多个未授权访问路径。

• •SSRF 与出站加固：出站 HTTP 连接阶段限制为 5 秒，Agent/binding 下载和运行超时可配置，SSRF 阻止错误消息更准确。

• • 防止 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_BACKEND

• •DIFY_AGENT_RUN_TIMEOUT_SECONDS

• •DIFY_AGENT_SANDBOX_FILES_BASE_URL

• •DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT

• •DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS

• •DIFY_AGENT_E2B_API_KEY

• •DIFY_AGENT_E2B_TEMPLATE

• •DIFY_AGENT_E2B_SHELLCTL_PORT

• •DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS

• •DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT

• •DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

• •DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT

• •DIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUT

• •DIFY_AGENT_OUTBOUND_HTTP_WRITE_TIMEOUT

• •DIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUT

• •DIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRY

• •DIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONS

• •DIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONS

• •AGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDS

• •AGENT_BACKEND_HOME_SNAPSHOT_TIMEOUT_SECONDS

认证 / 安全

• •TURNSTILE_SITE_KEY

• •TURNSTILE_SECRET_KEY

• •TURNSTILE_ALLOWED_HOSTNAMES

• •TURNSTILE_EMAIL_CODE_VERIFY_REQUIRED

• •EMAIL_CODE_LOGIN_MAX_ATTEMPTS

• •EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES

• •KEY_PROVIDER_TYPE

• •AZURE_KEYVAULT_VAULT_URL

• •AZURE_KEYVAULT_KEY_SIZE

• •AZURE_KEYVAULT_ROTATION_INTERVAL_DAYS

知识库 / 检索

• •TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH

• •TIDB_ON_QDRANT_ESTIMATED_STORAGE_LIMITS_MB

• •KNOWLEDGE_UPLOAD_FILE_SIZE_LIMIT_FOR_PAID_PLAN

追踪 / 可观测性

• •OPS_TRACE_UNIFIED_ENABLED

• •OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS

其他

• •ENABLE_CONVERSATION_CLEANUP_TASK

• •CONVERSATION_CLEANUP_TASK_INTERVAL

• •CONVERSATION_CLEANUP_BATCH_SIZE

• •UPLOAD_SKILL_FILE_SIZE_LIMIT

• •PLUGIN_MAX_FILE_SIZE

• •MARKDOWN_FORM_FIELD_NAME_EXTRA_CHARS

• •DEPLOYMENT_EDITION（替代EDITION）

• •EDITION→ 重命名为DEPLOYMENT_EDITION

• •ENTERPRISE_ENABLED

• •AGENT_BACKEND_RUN_TIMEOUT_SECONDS→ 被DIFY_AGENT_RUN_TIMEOUT_SECONDS取代

• •DIFY_AGENT_SHELLCTL_AUTH_TOKEN

• •DIFY_AGENT_SHELLCTL_ENTRYPOINT

• •APP_MAX_EXECUTION_TIME：1200 → 3600

• •WORKFLOW_MAX_EXECUTION_TIME：1200 → 3600

• •OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES：60 → 780

• •GRAPH_ENGINE_SCALE_UP_THRESHOLD：3 → 0

• •docker/docker-compose.yaml— 修改

• •docker/docker-compose.middleware.yaml— 修改

• •docker/docker-compose.e2b.yaml—新增（E2B Agent 沙箱组件栈）

本版本包含以下新迁移（社区版相关）：

• •add_workflow_version_number— 工作流版本号（部署 v2）

• •add_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迁移会在现有数据上创建索引，若对话表很大，执行时间可能较长。

1. 1. 备份自定义 compose 和环境文件：

   cd docker
   cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak
   cp .env .env.$(date +%s).bak 2>/dev/null || true

2. 2. 获取最新代码：

   git fetch --tags
   git checkout main   # 或目标发布标签

3. 3. 停止服务：

   docker compose down

4. 4. 备份数据卷：

   tar -cvf volumes-$(date +%s).tgz volumes

5. 5. 检查环境变量变化并重新应用本地定制（记得EDITION→DEPLOYMENT_EDITION）。

6. 6. 升级：

   docker compose up -d

1. 1. 停止 API 服务器、Worker 和 Web 前端。

2. 2. 获取最新代码：

   git fetch --tags
   git checkout main   # 或目标发布标签

3. 3. 更新 Python 依赖：

   cd api
   uv sync

4. 4. 运行迁移：

   uv run flask db upgrade

5. 5. 重建/重启 Web 前端，然后重启 API 服务器和 Worker。

代码地址：github.com/langgenius/dify

Dify 1.17.0 是一次全面的飞跃，尤其在Agent 基础设施、企业级安全和可观测性方面。E2B 云沙箱和 Home Snapshots 让 Agent 具备生产级的隔离与一致性；技能管理开启了能力复用的新篇章；统一追踪和可复用 LLM 环境变量大幅提升开发与运维效率。安全加固和访问控制修复也表明 Dify 团队对生产环境的高度重视。

我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。