引言
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. 备份自定义 compose 和环境文件：
cd docker
cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak
cp .env .env.$(date +%s).bak 2>/dev/null || true2. 获取最新代码：
git fetch --tags
git checkout main # 或目标发布标签3. 停止服务：
docker compose down4. 备份数据卷：
tar -cvf volumes-$(date +%s).tgz volumes5. 检查环境变量变化并重新应用本地定制（记得
EDITION→DEPLOYMENT_EDITION）。6. 升级：
docker compose up -d
1. 停止 API 服务器、Worker 和 Web 前端。
2. 获取最新代码：
git fetch --tags
git checkout main # 或目标发布标签3. 更新 Python 依赖：
cd api
uv sync4. 运行迁移：
uv run flask db upgrade5. 重建/重启 Web 前端，然后重启 API 服务器和 Worker。
代码地址：github.com/langgenius/dify
Dify 1.17.0 是一次全面的飞跃，尤其在Agent 基础设施、企业级安全和可观测性方面。E2B 云沙箱和 Home Snapshots 让 Agent 具备生产级的隔离与一致性；技能管理开启了能力复用的新篇章；统一追踪和可复用 LLM 环境变量大幅提升开发与运维效率。安全加固和访问控制修复也表明 Dify 团队对生产环境的高度重视。
我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。
热门跟贴