Dify 实战踩坑 — Workflow 编排 × RAG 调优 × 多租户方案

Dify 在生产环境落地时会遇到各种真实问题：Workflow 长任务超时、RAG 检索召回率低、多租户数据隔离不彻底、自定义 Tool 无法调试。本文从实际项目中总结的踩坑经验，每个坑都附解决方案和代码示例。

一、Workflow 编排踩坑

坑1：节点执行超时。 LLM 节点处理长文本时可能超过 30s 默认超时，导致 Workflow 失败。解决：在环境变量中调大 CELERY_TASK_TIME_LIMIT=300，并对 LLM 节点单独配置 timeout: 120。坑2：迭代节点变量传递。 迭代节点中内部节点的输出变量不会自动合并到外部，需要在迭代节点后加一个 UpdateVariable 节点手动合并。

二、RAG 检索调优

坑1：召回率低。 默认 Top-3 检索可能遗漏关键上下文。解决：Top-K 调到 8-10，加入 RRF 重排序（加权融合向量距离和 BM25 分数）。坑2：跨语言检索。 中文查询命不中英文文档中的对应内容。解决：使用 multilingual Embedding 模型（如 intfloat/multilingual-e5-large），并在分段时保持原文不翻译。

三、多租户隔离方案

坑1：数据隔离不彻底。 Dify 默认的 tenant_id 过滤是应用层级的，PostgreSQL 层没有强制隔离。解决：Row-Level Security（RLS）策略，在数据库层面强制 tenant_id 过滤。注意向量数据库的租户隔离通过 collection 前缀实现。

四、自定义 Tool 开发

坑1：Tool 参数 Schema 不匹配。 Dify 的 Tool 参数使用 JSON Schema 定义，嵌套对象的描述不够直观。解决：利用 api/core/tools/provider 下的 ProviderBase 基类，严格执行 Schema 校验。利用 validate_credentials() 做连接测试。

五、API 限流与安全

坑1：未配置限流导致 API 被刷。 Dify 默认没有开启 API 限流。解决：在 Nginx 层配置 limit_req_zone，配合后端 Redis-based rate limiter。建议：API 密钥鉴权（必需）、速率限制（必需）、CORS 白名单（必需）、HTTPS（必需）。

六、经验总结

Dify 是强大的 LLM 应用平台，但生产落地需要注意：Workflow 的超时和变量传递机制理解透彻、RAG 系统需要不断调优检索参数和 Embedding 模型选择、多租户场景必须做数据库级隔离、自定义 Tool 要严格校验 Schema。一句话建议：先在小流量下跑熟再上线，监控告警提前到位。