企业官网建设流程全解析

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 到 20G；Ragflow 的镜像更重，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 留在 80，Ragflow 改成 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.git

2.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文件的格式也要注意：KEY=value中间不要有空格，不要加引号，否则 Compose 解析出来会把引号当成值的一部分，导致配置完全失效。

2.3 启动、等待健康检查与初始化管理员账号

配置完成后的启动命令很简单：

docker compose up -d

第一次执行会拉取所有镜像，耗时取决于网络状况，十几分钟到半小时都正常。拉取完成后，用docker compose ps查看服务状态：

docker compose ps

看到Up不代表服务已经就绪，因为容器内部的进程可能还在初始化。比较稳妥的做法是直接看 API 服务的日志：

docker compose logs -f api --tail=100

一直刷到类似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 界面的模型配置里，如果你用本地 Ollama，Base URL 一样不能填localhost，得填宿主机可访问的地址。Windows Docker Desktop 通常可以直接填http://host.docker.internal:11434，Linux 下如果不行就参考前面 Dify 的做法，在编排文件里加extra_hosts映射。

嵌入模型我推荐用nomic-embed-text这类轻量模型，实测中文效果可以接受，资源占用也低。聊天模型可以根据你的硬件条件选qwen2.5之类的 7B 模型，或者干脆接外部 API。这里有个经验：嵌入模型和聊天模型不要混用同一个服务地址，因为两者的调用接口不一样，配置错了一个环节会导致解析成功、效果为空的情况。

Ragflow 的另一个核心点是文档解析。上传 PDF、Word、Excel 之后，系统会先执行解析和切片，再向量化入库。对于扫描版 PDF，Ragflow 内置了 OCR 能力，但非常吃内存，批量处理时内存不足就会卡在解析步骤。我实际测试下来，一次性不要上传超过几十个文件，大批量分批处理反而更稳。

顺带提一句：如果你想做批量文件入库，可以用 Ragflow 的 SDK 写个小脚本循环上传，比界面里一个个拖效率高得多，这个我会在下一节展开说。

3.3 启动后的健康检查与资源调整

Ragflow 启动之后，最怕的是 Elasticsearch 容器因为内存不足反复退出。ES 是吃内存大户，默认堆内存设置经常跟小机器不匹配。检查方法：

docker compose logs -f elasticsearch --tail=50

如果看到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_count=262144

并写入/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

日常操作对照整理成表格：

docker compose stop和docker compose down的区别是：前者只是暂停容器，数据卷和容器本身都保留，想重新启动用docker compose start即可；后者会删除容器，但数据卷还在，下次up会重新创建容器并挂载原数据卷。日常维护用stop就够了，down主要用于升级编排文件后需要重建容器的场景。

这套命令不只适用于 Dify 和 Ragflow，你在这台机器上用 Docker 装 MySQL 8.0、Redis 主从集群，套路一模一样。已经熟悉 Compose 的话，日常中间件部署基本都是这个模板。

4.2 批量上传与文件解析的实用操作

Ragflow 批量处理文件，界面操作适合小批量，如果文件数量多，我建议用 SDK 或者 API。先安装 SDK：

pip install ragflow-sdk

然后写个简单的批量上传脚本：

from ragflow_sdk import RagFlow rag = RagFlow(api_key="<你的API_KEY>", base_url="http://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_URL=http://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-x（Intel 平台）或 AMD-V（AMD 平台）。进系统后确认以下 Windows 功能都启用：Hyper-V、Windows 虚拟机监控程序平台、适用于 Linux 的 Windows 子系统。

如果 BIOS 和功能都开了还是报错，检查是否安装了新版 VirtualBox 之类的其他虚拟化软件，它们可能跟 Docker Desktop 抢虚拟化资源。我的处理顺序是：先开 BIOS，再启用 WSL2，最后安装或重置 Docker Desktop。绝大多数情况到第二步就能解决。

网络不通的问题也经常出现。容器起来了，页面访问不了，先分清是宿主机到容器端口不通，还是容器到外部网络不通。从宿主机测端口用：

• Linux：curl http://127.0.0.1:80
• Windows CMD：先启用 Telnet 客户端，再执行telnet 127.0.0.1 80，能连上说明端口映射正常

如果端口通但页面 502，问题多半在应用内部，看容器日志比折腾网络更有效。如果端口都不通，优先看docker compose ps确认容器是否真的 UP，以及日志里有没有崩溃重启的迹象。容器之间互相访问用服务名：Dify 的 API 连接数据库写的是db:5432，而不是localhost:5432；Ragflow 的服务端连接 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 替你提前验一遍。