很多人本地装完 Dify 和 RAGFlow 两个项目，各自都能用，但让 Dify 去查 RAGFlow 的知识库时就卡住：容器之间互相访问不到、端口写成本机地址、上传完文档检索没结果。这篇按工程落地顺序给一份清单：先规划资源与网络，再配检索端点，最后按固定顺序联调排查。
很多人本地把 Dify 和 RAGFlow 都装起来了，各自打开控制台都能跑，文档也能传，但一到让 Dify 去查 RAGFlow 的知识库就卡住：要么容器之间互相访问不到，要么端口写成了宿主机回环地址，要么上传完文档检索回来是空的。这几种现象看着像三个问题，其实大半是同一类原因——网络口径和调用链路没对齐。
这篇按工程落地顺序给一份可执行的清单：先规划资源与网络分工，再把 RAGFlow 的检索能力接进 Dify，然后调请求参数和超时，最后按固定顺序联调排查。每一步都给出怎么验证，别光看配置写没写对。
先规划资源与网络，别等装完再改
Dify 和 RAGFlow 都不是轻量单进程，各自会拉起 Web、API、数据库、缓存，RAGFlow 还带自己的向量存储和文档解析。本机内存与磁盘要按两套叠加预留，别按单个项目的推荐值来。具体门槛去 /models/deploy 做一遍部署测算，那里会按你选的组件给出资源口径。
| 规划项 | 做法 | 出错后果 |
|---|---|---|
| 端口分工 | 两个 Web 控制台、两套 API、各库端口各占一个，写进端口对照表贴在手边 | 启动时报端口占用，或改完一处忘改另一处 |
| 容器间寻址 | 同一 Docker 网络内用容器名互访，不写宿主机回环地址 | 一方连不上，日志里全是连接超时 |
| 跨机寻址 | 服务要出网络访问宿主机时才用本机地址，并确认监听地址不是只绑到本地 | |
| 数据目录 | 用命名卷或显式挂载路径，备份和整体重置都方便 | |
| 环境隔离 | 测试库和生产库分开，别在一套数据上反复改配置 |
最容易踩的坑是两种寻址方式混用：编排文件里一半服务写容器名、一半写本机地址，本地能通一次，换个启动顺序就断。定死一条规则——只要两个服务在同一个网络里，一律用容器名；只有确实要访问宿主机上跑的东西，才用本机地址，并且单独标出来。
把 RAGFlow 的检索能力接进 Dify
先别急着配 Dify。在 RAGFlow 侧把知识库建好、文档传完、等解析到完成状态，再去连。拿不到可用的知识库标识，后面配什么都是空的。解析没跑完就去测检索，返回空结果，会让人误以为是接口配错了。
- 接法一：走 RAGFlow 的检索接口，当成 Dify 的外部知识源，适合固定查某个或某几个库；
- 接法二：把 RAGFlow 包装成工具交给 Dify 调用，适合需要按问题动态选库、或要在调用前先做一层路由；
- 密钥、基地址、知识库标识全部放环境变量，不要硬编码进编排文件，换环境只改一处；
- Dify 侧第三方供应商和自定义接口地址怎么填，可对照 /official-api/providers 里同类平台的接入口径；
- 先在命令行里单独打一次检索请求，确认返回体里真的有片段，再回 Dify 里配。
请求参数、超时与降级怎么设
本地解析大文档慢是常态，超时如果沿用全局默认值，很容易把正常的慢请求判成失败，然后触发重试，堆在一起把资源吃满。检索接口的超时建议单独设，不和别的一般长。连接、读取、整体三层分开的思路，站内那篇超时清单讲得比较细，可以直接照搬结构。
- 分层超时
- 连接超时短、读取超时长、整体兜底最长，三层不要取同一个值
- 重试
- 次数限制在个位数，且只对可重试的错误重试，避免慢请求堆积
- 降级
- 检索失败时让流程退回到直接回答并标注未命中，而不是整个对话报错
- 并发
- 按本机资源定，别按线上习惯给，本地两路并行解析就可能把内存占满
不适用的情况也要说清楚：如果你的知识库很小、检索几乎瞬间返回，就没必要把超时调得很宽松，那反而会让真正的挂死拖很久才暴露。判断标准是看本地实测的检索耗时分布，而不是照抄别人的参数。
联调不通报错时，按这个顺序查
- 容器到容器进其中一个容器，直接访问对方的健康检查地址。不通就是网络或端口问题，跟业务逻辑无关，先修这一层。
- 接口到接口在宿主机用命令行单独打一次检索请求，确认返回体里确实有检索到的片段和条数。
- 链路到结果回 Dify 看编排日志，确认检索节点执行过、参数带对了、命中的片段有没有进到下一环。
- 通用排查代理、环境变量、证书这类本地常见问题，按站内既有清单走一遍，别一上来就怀疑代码。
- 单变量复测每次只改一个配置，改完立刻重测；一次改三处，出了结果也不知道是哪处的功劳。
这套顺序的价值在于把问题切成互不重叠的三段：网络、接口、编排。三段里只要有一段的验证没做，后面所有报错都可能指向错误的方向，排查记录也就没意义了。
跑通之后：留评测和日志，别只靠感觉
链路通了只是开始。检索质量会随切片方式、检索参数、文档本身的变化而漂移，靠每次手动问几句感觉好不好，很快就不准了。固定一组自己的问题当回归集，改动之后重跑一遍，看命中的片段有没有变差。
- 日志里至少留住知识库标识、检索关键词、命中条数和耗时，出问题能复盘到具体一次请求；
- 回归集不用大，覆盖你真实会问的几类问题就够，关键是每次改动都跑同一组；
- 文档清洗这类前置环节要一起看：进料脏了，调参救不回来，清洗清单值得先过一遍；
- 两个环境分开，别在测试机上改生产用的库，长期维护会省很多事。
最后提醒一句，本地这套配置的性能数字、资源占用，别用别人贴出来的值套自己机器。到 /tools/speed-test 和 /models/deploy 看你当次的实测与测算结果，才是有意义的参照。
下一步把自己机器的资源和端口先理一遍，再去部署测算页对一遍口径，能省掉后面大半的联调时间。→常见问题
两个项目必须装在同一台机器上吗？
不必。同一台胜在省资源、调试方便，但资源紧张时分开部署更稳，此时容器名互访不成立，要改成真实的 IP 或域名并放行端口。判断标准很简单：本机内存能不能同时容纳两套数据库与向量存储，吃不下就分开。
Dify 里检索不到内容，先怀疑哪里？
先确认 RAGFlow 里那篇文档是不是真的解析完成、能不能在其自身界面里搜到结果，这一步不过关就不是 Dify 的问题。过关了再看容器互访和密钥，最后才看参数。顺序反了会浪费大量时间在业务配置上。
本地跑这套东西，性能上最容易忽略什么？
最容易忽略的是解析与向量化那一段，占内存也占时间，控制台响应慢往往不是检索慢。做法是把大文档拆小再传，串行处理不要并行，并发数按本机资源保守设置，别照搬线上参数。
