ragflow本地部署docker

很多团队决定把知识库从公有云搬到自建机器，第一关不是模型选型，而是 Docker 这一步能不能跑起来：镜像拉不动、向量库连不上、端口冲突、上传的文档解析不出来。这篇按部署顺序给一份可对照执行的清单，涉及算力与镜像选择的部分，去站内看当时的数字和规格，别照抄别人机器上的配置。

决定把知识库从公有云搬到自建机器，第一关往往不是模型选型，而是 Docker 这一步能不能顺利跑起来：镜像拉不动、向量库连不上、端口被占、上传的文档解析不出来。这几个问题里任何一个卡住，后面调参、接模型都无从谈起。所以这篇不讲概念，按落地顺序给一份能对着执行的清单，从机器条件、容器划分、Compose 编排，到首次入库验收和上线后的排查顺序。

要先说一句：下面的步骤给的是顺序和判断标准，不帮你决定配置大小。算力、加速卡规格、文档量对应的机器档位，各家环境差别很大，去站内部署测算与硬件规格相关页面核对当时的数字和口径，别照抄别人机器上的参数。私有化部署没有标准答案，只有适合你文档量级和团队运维能力的答案。

动手之前先把机器条件对齐

部署失败十有八九是这个阶段没对齐。先把前提条件列清楚，再考虑装什么。前提分三类：CPU 指令集是否被镜像支持、内存和磁盘余量够不够解析你的文档、是否需要 GPU 加速。解析方式不同，内存占用差别可能是几倍，扫描件 OCR 和大表格解析尤其吃资源，这点心里要有数。

• 硬性前提三件套：CPU 指令集兼容性、内存与磁盘余量、是否上 GPU。三者缺一个，后面都可能卡在半路
• 内网出口策略先确认：镜像仓库、Python 包源、模型权重下载地址是否可达。不通就提前配代理或搭本地镜像源，别等拉取超时才回头找
• 部署方式定调：单机 all-in-one 适合验证和小组试用，拆分多容器适合要独立扩容、独立备份的场景。先想清楚是哪种，别做到一半改架构
• 按自己的文档量级反推机器，而不是先买卡再想装什么。怎么反推，去站内部署测算页面看当时的对照口径

目录与容器角色怎么划分

机器条件对齐后，别急着写编排文件，先画一张容器角色图。把应用服务、向量库、关系库、缓存、模型推理分别标出来，哪些是必需、哪些是可选的替代方案。这张图决定了后面数据卷怎么挂、端口怎么开、故障时先看谁。图没画清楚就动手，后面改起来会更乱。

数据卷要单独挂到宿主机固定路径，配置文件和持久化数据分开存放。很多人升级时习惯直接删容器重建，如果数据没独立挂出来，一起就没了。端口规划尽量一次到位：对外只暴露一个入口，内部服务走容器网络的别名通信，不要靠 IP 硬编码，否则换网络环境时要改一堆地方。

每个容器都留资源上限，尤其是解析环节。大文件解析时内存可能短时间飙高，没上限就可能把宿主机内存吃满，拖垮同机上其他服务。上限设多少要结合你实际文档大小测，别拍脑袋。

用 Compose 把编排写出来的步骤

有了容器图，Compose 就不是从零写，而是把图翻译成文件。原则是先做最小可运行版本，验证完核心通路再往上加服务。一上来就把所有可选组件都写进去，出了错很难定位是谁的问题。

1. 写最小可运行版本只保留核心服务，确保能登录、能建库、能传一个测试文档三条通路都通。三条没全通之前不要加新组件
2. 固定镜像 tag用具体版本号而不是默认标签。回滚时能对上是哪一次改动引发的问题，这个习惯在出故障时会救你
3. 环境变量集中管理数据库口令、对象存储地址这类放进单独一份环境变量文件，不要写死在编排文件里，方便切换环境
4. 用健康检查控制启动顺序让应用等向量库就绪再启动。顺序错乱最常见的表现就是启动时报连接失败，其实不是坏了，是启动太早

# 数据卷目录规划示例（路径按自己环境替换）；mkdir -p /data/ragflow/{config,data,logs}；chown -R 1000:1000 /data/ragflow；# 拉起前先做一次配置校验；docker compose config

编排文件写完后，先用校验命令确认语法和变量替换没问题，再真正启动。启动后别急着测业务，先看容器是不是都处于运行状态，有反复重启的直接进日志，通常是依赖没起来或者配置项写错了。

模型与向量服务接进来

这一步要区分两条路。嵌入模型负责把文档和问题转成向量，生成模型负责最后组织答案。嵌入模型建议尽量放本机，因为调用量大且对延迟敏感；生成模型可以自建推理服务，也可以接外部接口，各有取舍——自建可控但占资源，外接省机器但依赖网络。

• 接外部接口时统一走一层网关，把地址、密钥、超时集中管理，别散落在多个容器配置里
• 给模型服务单独做连通性验证，先确认单条请求能返回，再让知识库去调它，否则报错时说不清是谁的问题
• 做好降级预案：模型服务不稳定时能切回本地小模型，至少保证检索和引用可用。具体能力对比去站内模型库和嵌入模型页面核对
• 注意维度匹配：嵌入模型的输出维度必须和向量库配置一致，接错模型最典型的表现就是建库或检索直接失败

模型这块最容易踩的坑是只看名字不看规格。同一个模型不同量化版本、不同上下文长度，占用的显存和实际效果差别不小。选型前把你要接的模型规格拉到站内资料库对一遍，再决定放在哪台机器上。

第一次跑通：从入库到问答的验收顺序

第一次跑通不要直接问一个复杂问题看回答好不好。把流程拆成上传、解析、切片、向量化、检索、生成六段，逐段确认输出。哪一段没输出，问题就锁定在那一段，比一上来测整条链高效得多。

测试文档集要小而完整：长文、表格、扫描件各准备一份。这三类基本能覆盖清理和切片环节的主要问题。解析失败和切片过碎是两类问题，前者的错在解析器或资源，后者要调切片参数，别混在一起改。

上线后最常见的四类故障与排查顺序

自建部署的故障有很强的规律性，按固定顺序过一遍，能省掉大量无效排查。原则是先看容器状态再进日志，先确认进程活着再谈业务逻辑。进程都不在，后面一切都是空谈。

• 第一类：镜像拉不动。先测内网到镜像仓库的连通性，再确认 tag 是否存在，跟本地代码无关
• 第二类：连不上依赖。看服务发现和网络别名，向量库、关系库未就绪时应用启动会直接失败
• 第三类：端口被占。用端口查看命令确认占用进程，再回去改编排里的映射，别改一半又忘了
• 第四类：磁盘写满。向量库和日志增长最快，加磁盘告警比事后清理更省事
• 解析卡住多半是内存不足或外部解析服务超时；答非所问多半是切片与检索参数问题，两类分开处理

把每次故障的现象、动过的配置、恢复动作各记一行。这份记录在团队换人接手时比任何文档都管用，因为它是真实发生过的路径。

跑起来之后要长期维护的几件事

跑通不等于能长期用。私有化部署的成本大头其实在运维。升级、备份、资源监控、并发控制、访问安全，这几件事没做，早晚会出问题。

1. 升级前先备份备份数据卷和编排文件，再用同一份测试文档集跑验收，确认检索结果没退化再正式切换
2. 加资源监控与磁盘告警向量库体积增长往往比预期快，磁盘写满会导致写入失败，提前告警比事后扩容从容
3. 控制并发入口问答和文档解析同时打满会互相抢资源，必要时让解析排队处理，保证在线问答的响应
4. 收紧访问面把服务收在内网或加一层鉴权，别让部署在公网的实例裸奔，尤其带外部模型接口密钥的实例

还有一件事值得提前想：团队规模一旦扩大，部署方式、模型选型、成本结构都会变。哪些情况下当前方案不适用，怎么判断该拆分或上云，去站内指南中心看对应场景的说明，比临时拍脑袋决定靠谱。