很多人卡在两个地方：一是 RAGFlow 用 Docker 起来后，模型供应商里填 Ollama 的地址怎么写都不通；二是容器里访问不到宿主机上的 Ollama，日志只报连接被拒。这篇按「先起 Ollama、再起 RAGFlow、最后在容器网络里对齐地址」的顺序把操作步骤和排查顺序列出来，并说明什么条件下这套本地方案不合适。
本地用 Docker 把 RAGFlow 跑起来，再接上 Ollama，卡人的地方其实就两个：一是模型供应商里 Ollama 的地址怎么写都不通，二是容器里根本访问不到宿主机上的 Ollama，日志里只有连接被拒。这两个问题的根子是同一个——你以为填的是「本机」，但容器里的本机跟你坐着的机器不是一回事。
这篇不讲概念，只按「先起 Ollama、再起 RAGFlow、最后在容器网络里对齐地址」的顺序给步骤和排查顺序。需要提醒的是，这套本地方案的适用面有限，最后会专门说说什么条件下别硬上，免得你调了半天发现方向就不对。
部署前先定好三件事：机器规格、模型来源、数据放哪
RAGFlow 自带文档解析和向量检索那一套组件，Ollama 又要同时把模型权重装进内存，两边抢内存是启动失败最常见的原因。先确认宿主机内存和磁盘够不够，别等容器起一半被系统杀掉才回头查。具体规格线到 /models/deploy 相关的部署测算页核对当时的数字，不同组件组合的占用差别不小。
- 模型侧先把 Ollama 单独跑通，把要用的对话模型和嵌入模型都拉好，别等 RAGFlow 起来再去下，否则前端长时间转圈，你会误判成配置错误
- 目录和数据卷提前规划：镜像、模型权重、上传的文档这三类数据体量差别很大，分开挂载，之后单独扩容或备份都省事
- 先想清楚这台机器是只给自己用还是要给同事用，这决定后面要不要换方案，不然部署完才发现方向不对
Docker 起服务的顺序与看日志的方法
RAGFlow 的 Docker 编排一般会同时拉起多个服务，起来之后不要立刻打开页面，先看容器状态是不是都到运行态，再看应用容器的启动日志有没有反复重启。遇到组件起不来，按固定顺序查，比凭感觉翻日志快得多。
- 看容器是否退出先确认每个容器是运行态还是退出态，退出的看退出码和最后几十行日志，多数启动失败在这一步就能定位到
- 查端口占用如果容器反复重启，优先怀疑端口被别的服务占了，逐个核对编排里映射出来的端口
- 再看资源占用排完上面两项还起不来，去看内存和磁盘的实时占用，解析或检索相关组件对内存尤其敏感
- 最后才开页面确认服务稳定运行几分钟没有重启，再去浏览器访问，避免把启动中的转圈当成故障
如果卡在检索层组件的选择或兼容性上，可以对照 /stacks/vector-dbs 了解不同检索层的差异，再决定要不要换。Windows 上用 Docker Desktop 的，宿主机地址的写法跟 Linux 不一样，这条下一节展开。
Ollama 地址怎么填：分「RAGFlow 在容器里」和「RAGFlow 在宿主机」两种情况
判断标准很简单：RAGFlow 跑在哪，它眼里的「本机」就在哪。RAGFlow 在容器里时，容器内的本机地址指的是容器自己，填了必然连不上；RAGFlow 跑在宿主机进程里时，填本机地址通常能通，但前提是 Ollama 允许外部监听，只绑本地回环的话外面进不来。
| RAGFlow 运行位置 | 地址该怎么写 | 常见结果 |
|---|---|---|
| 容器里（Docker 编排） | 用编排里的服务名，或宿主机在编排中定义的别名 | 填本机地址一定连不上 |
| 宿主机进程直接跑 | 填本机地址，前提是 Ollama 对外监听 | Ollama 只绑回环时会失败 |
| Docker Desktop（Windows/macOS） | 用宿主机在编排中的专用别名 | 直接写本机地址大多不通 |
- 接口路径要写全，协议、主机、端口、接口前缀缺一段就是 404 或者连不上；不确定前缀怎么拼，先用命令行单独请求一次 Ollama 的接口，确认能返回再填进 RAGFlow
- 填完先做连通测试，通过了再去配模型；地址通了但模型列表是空的，通常是模型没拉下来，或者那是嵌入类模型，需要在对应类型里分别指定
- 一次问答一般要配三类模型：对话模型负责生成，嵌入模型负责转向量，重排类模型可选；基础字段口径可参考 /ai-dict 里的术语解释
地址填不对，九成不是配置写错了，是你把「容器的本机」当成了「你的本机」。
把知识库串起来：模型分工、切片参数、检索验证
地址通了只是第一步，真正决定问答质量的是切片和模型分工。嵌入模型一旦换了，已有的解析结果要重建，否则检索出来的内容会错乱，这一点很多人踩过坑才发现。
- 切片长度按资料类型调：规整的说明书可以切长一点，扫描件和表格密集的文档切短一点，并开启对应的 OCR 处理，否则文字根本进不了库
- 文档解析完成后先看分块数量和内容预览，再去做检索测试；检索结果全是无关片段，先怀疑切片而不是模型，回头调切片再重建
- 上线前用一批固定问题做对照测试，把问题、命中的片段、回答一起记下来，之后换模型或调参数才有基线可比。检索链路各环节的分工可对照 /stacks/frameworks
这套流程里没有哪一步是「跑通一次就永远对」的，参数和资料一变，效果就可能回退，所以留好基线记录比调参本身更重要。
什么情况下别走这套本地方案
多人同时用、文档量大且更新频繁的时候，单机 Docker 这套会最先卡在解析和内存上。这时候更合适的做法是把模型调用换成远程接口，本地只留 RAGFlow 负责解析和检索，取舍思路可以到 /official-api 比一比调用成本再决定。
- 需要稳定对外的服务别放在开发机或家用机器上，临时重启、待机、网络波动都会让知识库时好时坏
- 只想快速验证问答效果、不打算长期维护的，用更轻的客户端方案更省事
- 本地套件的运维成本主要集中在镜像更新和模型体积上，这两件事不会因为跑起来就消失，得提前接受
常见问题
RAGFlow 里 Ollama 的地址到底填什么？
看 RAGFlow 跑在哪。它跑在容器里，就别填本机回环地址，本机回环在容器内指向容器自己；要用编排里给宿主机或 Ollama 服务定义的名称加端口。它跑在宿主机进程里，填本机地址一般能通，前提是 Ollama 允许外部访问。填完先单独请求一次接口确认通了再保存。
为什么地址填对了还是提示连不上？
按这个顺序查：先在能访问 Ollama 的地方单独请求一次它的接口，确认服务本身可用；再看两边是不是在同一个容器网络里；再看 Ollama 的监听范围是不是只绑了本地回环；最后看防火墙或安全组有没有挡住端口。多数情况是第二步或第三步，跟地址字符串本身无关。
本地部署后模型必须用 Ollama 吗，能不能换成远程接口？
可以混着用。RAGFlow 通常把对话和嵌入分开配，你可以对话走本地 Ollama、嵌入走远程接口，反过来也行。注意嵌入模型一旦更换，之前解析入库的数据要重建，否则检索会不准。混合方案的好处是把吃内存的部分挪出去，本机只留文档处理和检索。
