Dify 和 Ragflow 这两个开源 AI 平台最近是真心火一个主打 LLM 应用编排和知识库问答一个专攻 RAG 检索增强生成部署需求天天有人问。但很多人的第一道坎就卡在启动上Docker 环境没准备好、端口冲突、模型连不上、容器一直重启随手一搜全是报错。这篇文章就把我用 Docker 启动这两个平台的完整过程写透从环境选型、编排文件配置到日常运维命令和高频报错排查全部基于实际跑通的经验适合刚接触自部署的开发者也适合已经被各种启动报错折磨过一轮的人直接对照排查。1. 先把部署路子选对Compose、资源与端口规划1.1 为什么推荐 Docker Compose而不是 docker run 硬拉很多刚接触 Docker 的人有个误区觉得启动服务就是docker run一把梭。但 Dify 和 Ragflow 都不是单个容器能搞定的项目。Dify 的典型架构包含 API 服务、Worker 异步任务、Web 前端、PostgreSQL、Redis、Sandbox 沙箱、SSRF 防护代理旧版本还带向量数据库Ragflow 更不用说服务端、MySQL、Redis、Elasticsearch 或 Infinity 向量库、MinIO 对象存储一套下来至少五六个容器。用docker run一个个启动这些容器你得手动建网络、配依赖顺序、指定容器间通信的 hostname还要处理数据卷挂载随便一个环节错了容器之间就连不上。Docker Compose 的价值就在于把多容器定义成一组服务通过一个docker-compose.yml就能一键拉起、统一停止、统一查看日志而且所有服务自动进入同一个网络容器间直接用服务名互相访问。官方也都默认提供 Compose 编排文件这是最省心、最不容易出错的路子没有之一。1.2 硬件与系统要求别等启动失败才回头看配置先说硬性指标。Dify 官方给的最低配置是 2 核 4G但我实测下来4G 内存只能勉强跑起来模型推理一开就容易卡死建议 8G 起步。Ragflow 的胃口更大因为要跑文档解析、向量化、检索官方推荐至少 4 核 16G磁盘 50G 以上我自己用 8G 内存的小机器跑过传小文件还行批量上传 PDF 或者解析大表格的时候直接 OOM容器被系统杀掉。磁盘空间也别忽略。Dify 的镜像加数据卷跑起来之后大约占 15 到 20GRagflow 的镜像更重ES 索引和 MinIO 存储都会持续增长建议至少留 30G 空闲。系统方面Windows 用户基本绕不开 Docker Desktop后端推荐选 WSL2 而不是 Hyper-V兼容性更好启动更快。Linux 上直接装 Docker Engine 就行用systemctl start docker拉起守护进程。要注意 CentOS 7 这类老系统内核 3.10 对 Docker 新特性的支持很勉强如果遇到容器网络异常或者 iptables 报错优先考虑升级系统而不是死磕配置这是我在生产环境踩出来的经验。1.3 端口、域名与存储规划一次想清楚后面少返工两个平台默认都占用 80 端口如果同一台机器要同时跑 Dify 和 Ragflow端口必须提前错开。Dify 的默认入口是 80通过内置 Nginx 转发Ragflow 默认入口也是 80在docker/.env里有SVR_HTTP_PORT之类的参数可以改。我习惯把 Dify 留在 80Ragflow 改成 8080这样访问地址分别是http://服务器IP/和http://服务器IP:8080/。改端口的具体方式要看版本。Dify 有的版本在.env里直接有 nginx 端口的变量有的版本要改docker-compose.yaml里的端口映射建议先打开编排文件搜80:80或者ports关键字确认改哪里再动手。Ragflow 则是优先看docker/.env里的端口变量。数据卷规划是很多人忽略的重灾区。两个平台的数据都存在 Docker Volume 里Dify 的 PostgreSQL 数据、Ragflow 的 MinIO 文件、ES 索引全部在 volume 里。这意味着docker compose down -v会把所有数据清空没有后悔药。我建议部署之前就在项目目录外的独立磁盘分区规划好数据目录通过volumes字段显式挂载到宿主机后面备份迁移会省很多事。提示docker compose down只会删除容器和网络数据卷保留docker compose down -v会连数据卷一起删。这条命令我强调多少遍都不为过。2. Dify 启动实操从拉取编排文件到完成初始化2.1 获取官方编排文件clone 项目而不是裸跑镜像启动 Dify 的第一步我建议直接拉官方仓库不要自己从零写 Compose 文件。git clone https://github.com/langgenius/dify.git cd dify/docker为什么要 clone 整个项目因为 Dify 的docker目录下自带完整的docker-compose.yaml和.env.example这些编排文件经过官方持续维护服务之间的依赖关系、健康检查、数据卷挂载都是现成的。你只需要复制环境变量模板、填几个关键配置然后docker compose up -d就能跑起来。如果直接去 Docker Hub 拉镜像还得自己补一套编排文件得不偿失。仓库体积不算小要是带宽紧张可以加--depth 1做浅克隆只拉最新提交git clone --depth 1 https://github.com/langgenius/dify.git2.2 配置 .env密钥、端口与外部服务进入dify/docker目录后第一步复制环境变量模板cp .env.example .env编辑.env之前先做一件必须的事生成密钥。Dify 用SECRET_KEY做会话加密和数据签名不设置或者用默认值生产环境会有安全隐患。生成方式openssl rand -base64 42把输出的字符串填到.env里的SECRET_KEY后面。接下来检查端口配置。默认情况下 Dify 的入口是 80如果你这台机器已经有别的 Web 服务占用 80就把编排文件里的端口映射改掉比如改成8081:80。模型供应商的 API Key 可以之后在 Web 界面里配但如果你打算用本地 Ollama我强烈建议先确认访问地址。容器内部访问宿主机不能用localhost在 Linux 上很多环境也没有 Docker Desktop 自动注入的host.docker.internal域名。这种场景我一般直接在编排文件里的 API 服务下加一段extra_hosts: - host.docker.internal:host-gateway这样容器里就能用http://host.docker.internal:11434访问宿主机的 Ollama 了。这个坑非常经典后面排查凭据验证失败那节还会提到。.env文件的格式也要注意KEYvalue中间不要有空格不要加引号否则 Compose 解析出来会把引号当成值的一部分导致配置完全失效。2.3 启动、等待健康检查与初始化管理员账号配置完成后的启动命令很简单docker compose up -d第一次执行会拉取所有镜像耗时取决于网络状况十几分钟到半小时都正常。拉取完成后用docker compose ps查看服务状态docker compose ps看到Up不代表服务已经就绪因为容器内部的进程可能还在初始化。比较稳妥的做法是直接看 API 服务的日志docker compose logs -f api --tail100一直刷到类似Running on http://0.0.0.0:5001或者Application startup complete的日志再访问http://服务器IP/install初始化管理员账号。首次安装会要求你设置管理员邮箱和密码这个账号就是之后登录 Dify 工作台用的超级管理员密码强度建议至少 12 位混合字符。如果访问页面出现 502大概率是 Web 容器还没准备好等一两分钟再刷新。如果反复刷新都不行就去查docker compose logs -f web的日志看是不是 Nginx 转发目标连不上也可能是 api 容器崩了这时候优先看 api 日志而不是瞎猜。3. Ragflow 启动实操模型配好才算真正跑通3.1 部署命令与版本选择不同分支要分清Ragflow 的部署套路和 Dify 类似官方仓库里也带编排文件git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker docker compose up -d这里有个容易踩坑的细节Ragflow 的仓库分支比较多main分支对应的是开发版本如果你只是想稳定使用建议切到最新的 release 分支或者直接下载 release 包。我在测试时吃过亏用 main 分支的编排文件拉起来的镜像版本和文档对不上接口路径和配置项都有差异排查起来非常痛苦。Ragflow 的编排文件在docker目录下启动前同样先看一下.env文件。里面除了端口配置还有两个值得关注的变量一个是RAGFLOW_IMAGE指定服务端镜像版本升级时改这里就能统一控制另一个是对象存储和数据库的密码类配置如果要在多台机器之间迁移这些配置要保持一致。启动完成后检查容器状态docker compose ps curl -s http://localhost/api/v1/ping如果返回值里能看到{code: 0}说明服务端已经正常响应。然后浏览器访问http://服务器IP第一次注册的账号会成为系统管理员。Ragflow 的注册页默认是开放的如果部署在公网服务器上建议尽快设置访问控制或者干脆只在内网访问。3.2 嵌入模型与解析引擎配置决定 RAG 效果的关键Ragflow 跑起来只是第一步真正让它“能用”的关键是模型配置。Ragflow 需要两类模型聊天模型负责生成回答嵌入模型负责把文档切成向量。很多人的 RAG 知识库搭好之后检索一片空白十有八九是嵌入模型没配好。在 Ragflow 界面的模型配置里如果你用本地 OllamaBase URL 一样不能填localhost得填宿主机可访问的地址。Windows Docker Desktop 通常可以直接填http://host.docker.internal:11434Linux 下如果不行就参考前面 Dify 的做法在编排文件里加extra_hosts映射。嵌入模型我推荐用nomic-embed-text这类轻量模型实测中文效果可以接受资源占用也低。聊天模型可以根据你的硬件条件选qwen2.5之类的 7B 模型或者干脆接外部 API。这里有个经验嵌入模型和聊天模型不要混用同一个服务地址因为两者的调用接口不一样配置错了一个环节会导致解析成功、效果为空的情况。Ragflow 的另一个核心点是文档解析。上传 PDF、Word、Excel 之后系统会先执行解析和切片再向量化入库。对于扫描版 PDFRagflow 内置了 OCR 能力但非常吃内存批量处理时内存不足就会卡在解析步骤。我实际测试下来一次性不要上传超过几十个文件大批量分批处理反而更稳。顺带提一句如果你想做批量文件入库可以用 Ragflow 的 SDK 写个小脚本循环上传比界面里一个个拖效率高得多这个我会在下一节展开说。3.3 启动后的健康检查与资源调整Ragflow 启动之后最怕的是 Elasticsearch 容器因为内存不足反复退出。ES 是吃内存大户默认堆内存设置经常跟小机器不匹配。检查方法docker compose logs -f elasticsearch --tail50如果看到OpenJDK 64-Bit Server VM warning内存相关的报错或者容器反复重启就需要调整 ES 的 JVM 参数。Ragflow 的.env文件里通常会有 ES 相关的内存配置项比如ES_JVM_OPTS或jvm_options把-Xms和-Xmx改小一些比如-Xms2g -Xmx2g然后重启 ES 容器。如果日志里出现max virtual memory areas vm.max_map_count之类的错误这是 Linux 内核参数不够执行sudo sysctl -w vm.max_map_count262144并写入/etc/sysctl.conf永久生效。这类问题在部署 ES 系组件时几乎是必踩的提前设置好能省不少排查时间。4. 日常运维命令速查启动、日志、备份与批量处理4.1 容器生命周期命令对照表两个平台的运维命令套路完全一致前提是你得在各自项目对应的docker目录下执行因为 Compose 默认读取当前目录下的docker-compose.yaml。如果你习惯在任意目录下执行需要用-f指定编排文件路径docker compose -f /path/to/ragflow/docker/docker-compose.yml up -d日常操作对照整理成表格操作场景Dify 命令在 dify/docker 目录Ragflow 命令在 ragflow/docker 目录启动全部服务docker compose up -ddocker compose up -d停止全部服务保留数据docker compose stopdocker compose stop重启全部服务docker compose restartdocker compose restart查看运行状态docker compose psdocker compose ps查看 API 日志docker compose logs -f api --tail100docker compose logs -f ragflow-server --tail100删除容器和网络保留数据卷docker compose downdocker compose down删除容器、网络和数据卷谨慎docker compose down -vdocker compose down -v只启动依赖数据库docker compose up -d db redisdocker compose up -d mysql redisdocker compose stop和docker compose down的区别是前者只是暂停容器数据卷和容器本身都保留想重新启动用docker compose start即可后者会删除容器但数据卷还在下次up会重新创建容器并挂载原数据卷。日常维护用stop就够了down主要用于升级编排文件后需要重建容器的场景。这套命令不只适用于 Dify 和 Ragflow你在这台机器上用 Docker 装 MySQL 8.0、Redis 主从集群套路一模一样。已经熟悉 Compose 的话日常中间件部署基本都是这个模板。4.2 批量上传与文件解析的实用操作Ragflow 批量处理文件界面操作适合小批量如果文件数量多我建议用 SDK 或者 API。先安装 SDKpip install ragflow-sdk然后写个简单的批量上传脚本from ragflow_sdk import RagFlow rag RagFlow(api_key你的API_KEY, base_urlhttp://localhost) dataset rag.create_dataset(批量测试数据集) dataset.upload_documents([a.pdf, b.docx, c.xlsx]) # 轮询解析状态 for doc in dataset.documents(): print(doc.name, doc.status)API Key 在哪里拿登录 Ragflow 后在头像菜单的账号信息或者 API 管理页面里可以生成。这个脚本逻辑很简单创建数据集、上传文档、轮询状态等status变为成功文件就完成了解析和向量化可以直接进知识库问答了。Dify 侧也有批量上传能力Dify 的知识库数据集页面支持一次拖拽多个文件。如果你把 Dify 当作 RAG 平台用可以在知识库里创建数据集后再配合工作流的“知识检索”节点把检索结果喂给大模型生成回答这就是 Dify 典型的“知识库加流水线”玩法。注意工作流里知识库召回的内容太多时很容易触发上下文超长解决办法是控制召回条数和切片长度而不是无脑加大模型上下文窗口。4.3 数据备份与迁移最容易被忽略的 down -v 坑备份 Dify 或 Ragflow 的数据核心是把容器里的数据卷完整拷出来。最直接的做法是先停服务再从宿主机打包。先看数据卷列表docker volume ls | grep dify docker volume ls | grep ragflow找到目标卷后用临时容器打包到宿主机目录docker run --rm -v volume名称:/data -v $(pwd):/backup alpine tar czf /backup/dify-data-$(date %Y%m%d).tar.gz /data迁移到新机器时先用相同版本的编排文件把空容器跑起来确认数据卷创建成功然后把 tar 包里的内容解压回目标卷再重启服务。这里有个更偷懒但非常有效的方案如果两个平台的数据目录是通过volumes显式挂载到宿主机路径的直接打包宿主机目录即可恢复时解压到原路径再启动容器数据就回来了。我在实操中还遇到过一个顺手坑迁移后容器起不来排查发现是新机器上的.env里密码配置跟旧数据不一致导致数据库认证失败。所以迁移时务必把原来的.env一起带过去不要在新机器上重新生成一堆配置否则数据库里的存量数据会因为密码不匹配而无法访问。5. 高频报错排查这些坑我基本都踩过5.1 凭据校验失败与镜像拉取问题Dify 在配置模型供应商时经常报an error occurred during credentials validation这个报错有几种完全不同的来源。第一种是部署阶段拉镜像时就报类似关键词的错通常是因为 Docker Desktop 的登录态过期或者镜像仓库凭据配置有问题。试一下docker login重新认证或者检查~/.docker/config.json是否被写入了异常配置。如果拉的是私有镜像确保登录的账号有权限。第二种是 Web 界面里填模型供应商的 API Key 时后端校验失败。这种情况先确认 Key 本身没问题然后考虑容器网络。如果你填的是http://localhost:11434指向本地 Ollama容器内部访问的是自己根本连不到宿主机必须换成宿主机可访问的地址。我前面提到的host.docker.internal就是干这个用的。Linux 下如果没有这个域名在编排文件里加extra_hosts映射是标准解法。提示在容器里排查网络问题时可以临时进入容器执行curl http://host.docker.internal:11434或者telnet端口确认容器到宿主机链路是否通再决定是修网络还是修地址配置。5.2 Unstructured API URL 未配置的解决思路Dify 上传 docx、pdf、xlsx 这类富格式文档时如果界面报dify unstructured api url is not configured for doc file processing这个报错的意思是 Dify 把这类文档的解析工作外包给了 Unstructured 服务但你的部署环境没有启用这个组件。解决办法分三条路。第一条路启用编排文件里的 Unstructured 服务。打开docker/docker-compose.yaml搜索unstructured关键字把对应的服务段取消注释或启用然后在.env里设置UNSTRUCTURED_API_URLhttp://unstructured:8000执行docker compose up -d重新创建容器。第二条路如果你不想多跑一个吃内存的解析服务遇到 docx 这类文件先在本地转成纯文本或者 Markdown 再上传这样走 Dify 默认的文本解析通道不依赖 Unstructured。第三条路自己另外部署一个 Unstructured API然后把UNSTRUCTURED_API_URL指向那个外部地址。我实际生产中用的是第一种因为知识库里经常要传原始格式文件纯文本转换会丢失排版信息影响后续切片的语义完整性。但我建议在测试环境先只传 txt 和 md确认 Dify 整体流程没问题后再开 Unstructured减少变量。5.3 Docker Desktop 虚拟化检测失败与网络不通Windows 用户启动 Docker Desktop 时如果提示virtualization support not detected这是电脑的虚拟化能力没开或者没被正确识别。先重启进 BIOS开启 Intel VT-xIntel 平台或 AMD-VAMD 平台。进系统后确认以下 Windows 功能都启用Hyper-V、Windows 虚拟机监控程序平台、适用于 Linux 的 Windows 子系统。如果 BIOS 和功能都开了还是报错检查是否安装了新版 VirtualBox 之类的其他虚拟化软件它们可能跟 Docker Desktop 抢虚拟化资源。我的处理顺序是先开 BIOS再启用 WSL2最后安装或重置 Docker Desktop。绝大多数情况到第二步就能解决。网络不通的问题也经常出现。容器起来了页面访问不了先分清是宿主机到容器端口不通还是容器到外部网络不通。从宿主机测端口用Linuxcurl http://127.0.0.1:80Windows CMD先启用 Telnet 客户端再执行telnet 127.0.0.1 80能连上说明端口映射正常如果端口通但页面 502问题多半在应用内部看容器日志比折腾网络更有效。如果端口都不通优先看docker compose ps确认容器是否真的 UP以及日志里有没有崩溃重启的迹象。容器之间互相访问用服务名Dify 的 API 连接数据库写的是db:5432而不是localhost:5432Ragflow 的服务端连接 ES 同样用服务名。这个概念不理解很多网络问题都排查不出头绪。5.4 Ragflow 解析失败与 Elasticsearch 资源冲突Ragflow 上传文档后一直停在“解析中”大概率是三个原因嵌入模型配置不对、内存不足、ES 崩了。先看ragflow-server日志如果里面有连接嵌入模型超时的报错回头检查模型供应商的 Base URL 和 API Key。如果是内存不足日志里通常会有 OOM 相关字样把批量上传改成小批量或者加内存。ES 崩了的表现是docker compose ps里 ES 容器反复重启。除了前面说的调整 JVM 堆内存还可以检查 ES 的健康状态curl -s http://localhost:9200/_cluster/health返回status: yellow或red说明集群状态异常需要查看对应容器的日志。ES 在 BMI 部署场景里是最容易出问题的组件资源有限的情况下建议优先保证 ES 的稳定性再考虑同时跑大文件解析。另外提一个针对 PDF 的实战经验Ragflow 对文字型 PDF 的解析质量很好但如果是扫描件加复杂表格解析时间会成倍增加。对这种文件我的做法是先拆页、转成图像质量更清晰的版本再上传或者直接用 OCR 预处理避免在解析阶段大量消耗内存和 CPU。解析这一环搞定了RAG 的效果才有保障。回想我最早部署这些内容的时候走了不少弯路在 CentOS 7 上折腾 Docker 网络卡了一整天不知道down -v会清空数据差点弄丢整库知识填模型地址用了 localhost怎么配都报凭据失败。后来我才慢慢理解这类开源平台的部署其实就三板斧先把 Compose 编排文件吃透再把模型网络地址搞清楚最后学会看日志。这套方法论我后来装 MySQL、Redis 这些中间件时也一直在用。最后再分享一个小技巧启动任何 Compose 服务之前先执行docker compose config检查一下编排文件语法这个命令能帮你提前发现缩进错误、变量引用错误和环境变量缺失与其等服务起不来再翻日志不如让 Compose 替你提前验一遍。