RAGFlow：深度文档理解的本地 RAG 引擎｜部署与使用全指南
本文基于 2026 年 RAGFlow 的真实项目状态撰写（最新稳定版
v0.27.3，最新发布v1.0.0-rc2Go 架构版，2026-10-26 仍有提交）。所有命令、参数与端口均来自官方仓库docker/.env、conf/service_conf.yaml与官方文档，可直接复现。
一、项目简介与适用场景
RAGFlow 是由 Infiniflow 主导开发的开源检索增强生成（RAG）引擎，核心在于 DeepDOC（深度文档理解）：它能在把文档切分为知识块之前，先用版面分析、OCR、表格识别等能力"读懂"复杂排版的原文，从而显著降低 RAG 系统中最常见的"切块错位 → 召回跑偏 → 幻觉"问题。
官方一句定位：基于深度文档理解的开源 RAG 引擎，擅长解析复杂格式（PDF/Word/扫描件/表格）并实现可控召回，适合企业知识库与私有文档问答。
当前（2026 年）项目已发展到 1.0 架构，后端从原来的 Python 服务统一重构为 Go 单体二进制（一个二进制同时承担 Admin、Syncer、Ingestor、API 等角色），启动更轻、依赖更少。GitHub Stars 超过 9.2 万，贡献者 450+，仍处于高频活跃维护状态（每周多次提交、每月多个 Release）。
适用场景
二、核心功能逐条拆解
DeepDOC 深度文档理解 在切块前先做版面分析、OCR、表格识别，从非结构化/半结构化复杂格式中提取"高质量"文本，真正做到 Quality in, quality out。
模板化切块（Template-based Chunking） 提供多种面向不同文档版式与文件类型的切块模板（如通用、论文、表格、书籍、法律等），切块过程可视、可解释，支持人工干预。
知识编译（Knowledge Compilation） 在文档与数据集层面把内容编译为结构化知识产物：Wiki、图谱（Graph）、树（Tree）、页面索引（PageIndex）、思维导图（Mind Map）、时间线（Timeline）、技能（Skills），可配置模型与处理规则并重新生成。
Agentic 检索（多步检索） 面对复杂问题，模型会先拆解问题、多轮检索与推理、交叉验证证据，再生成有据可依的答案；支持 Low / Medium / High / Ultra 四档"思考深度"。
可信引用、降低幻觉 文本切块可视化，支持人工干预；答案附带关键引用与可溯源证据，减少幻觉。
异构数据源兼容 支持 Word、PPT、Excel、TXT、图片、PDF、扫描件、结构化数据、网页，以及邮件（.msg/.eml）、Salesforce/SharePoint/Slack/OneDrive 等数据源连接器。
自动化 RAG 工作流 面向个人到大型企业的流式编排；可配置 LLM 与 Embedding 模型；多路召回 + 融合重排（rerank）；提供直观 API。
三、全套官方链接
四、硬件与环境前置要求
4.1 最低 / 推荐配置
架构平台提示：官方原生 Docker 镜像面向 Linux x86-64。Linux ARM64 当前不是官方支持的本地构建目标（Go 镜像依赖 x86-64 原生库）。macOS 在官方文档中标注为"暂不支持"作为原生构建目标；在 macOS 上可通过 Docker Desktop 的 Linux VM 运行该 Linux 镜像（Apple Silicon 需 Rosetta/模拟，性能与稳定性未获官方保证）。生产环境强烈建议使用 Linux x86-64 主机。
4.2 GPU 与显存建议
默认
DEVICE=cpu：DeepDOC 的版面分析、OCR、表格识别在开源 1.0 版本中采用 CPU 推理，无需 GPU 即可运行。如需用 GPU 加速 Embedding（TEI）与 DeepDOC 推理：将
DEVICE设为gpu并在COMPOSE_PROFILES中加入tei-gpu，使用docker-compose-gpu.yml。显存建议：若本地部署 Embedding 模型
BAAI/bge-m3约需 21GB RAM/vRAM，Qwen3-Embedding-0.6B约需 25GB。仅做 API 接入云端大模型时，无需独立显卡，纯 CPU 即可。
4.3 其他依赖
Elasticsearch 文档引擎要求宿主机
vm.max_map_count ≥ 262144（Infinity 引擎则无需）。源码编译还需：Go（见
go.mod，当前约 Go 1.27）、Clang 20、LLD 20、CMake ≥ 4.0、PCRE2 开发文件。
五、多平台部署实战
下面所有示例使用 v1.0.0-rc2（当前官方 Quickstart 指定的 Go 架构版本）。生产可按需替换为稳定版标签（如
v0.27.3）。
5.1 Docker 部署（推荐，跨平台通用）
Linux（Ubuntu/CentOS 等）
# 1) Elasticsearch 文档引擎需设置 vm.max_map_count（Infinity 可跳过）
sysctl vm.max_map_count
sudo sysctl -w vm.max_map_count=262144
# 永久生效：在 /etc/sysctl.conf 加入 vm.max_map_count=262144
# 2) 克隆仓库
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
# 3) 切换到发布标签
git checkout v1.0.0-rc2
# 4) 后台启动（CPU 版）
docker compose -f docker-compose.yml up -d
# 5) 查看状态
docker ps
docker logs --tail 50 ragflow-cpu
# 6) 健康检查（返回 HTTP 200 即就绪）
curl -f http://localhost/api/v1/system/healthz
# 7) 浏览器访问 http://<你的机器IP>（默认 80 端口，可省略）
容器名默认为 ragflow-cpu（CPU）或 ragflow-gpu（GPU）。
GPU 版（用 GPU 加速 Embedding / DeepDOC）
cd ragflow/docker
git checkout v1.0.0-rc2
# 方式一：直接用 GPU compose 文件
docker compose -f docker-compose-gpu.yml up -d
# 方式二：或用默认文件并把 DEVICE 改为 gpu（编辑 docker/.env 后）
# DEVICE=gpu
# docker compose -f docker-compose.yml up -d
国内镜像（拉取官方镜像失败时）：编辑 docker/.env，将 RAGFLOW_IMAGE 替换为： - 华为云：swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v1.0.0-rc2 - 阿里云：registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v1.0.0-rc2
也可使用 nightly 标签拉取最新夜间构建。
5.2 Windows 部署（Docker Desktop）
安装 Docker Desktop for Windows，启用 WSL2 后端。
在 PowerShell / Terminal 中：
powershell git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker git checkout v1.0.0-rc2 docker compose -f docker-compose.yml up -d设置
vm.max_map_count（WSL2 中执行）：powershell wsl -d docker-desktop sysctl -w vm.max_map_count=262144或在%USERPROFILE%\.wslconfig中加入：ini [wsl2] vm.max_map_count=262144浏览器访问
http://localhost（Docker Desktop 端口已映射到本机）。
5.3 macOS 部署（Docker Desktop，注意平台限制）
安装 Docker Desktop for Mac。
若使用 Elasticsearch，在 Docker Desktop 的 Linux VM 中设置
vm.max_map_count（通过Settings → Resources → Advanced的vm.max_map_count，或在终端用docker run --rm --privileged alpine sysctl -w vm.max_map_count=262144，具体以 Docker Desktop 版本为准）。终端执行：
bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker git checkout v1.0.0-rc2 docker compose -f docker-compose.yml up -d访问
http://localhost。⚠️ Apple Silicon（ARM64）Mac 运行的是 x86-64 Linux 镜像，需 Rosetta 模拟，官方未承诺稳定性；仅建议评估/开发使用，生产请用 Linux x86-64。
5.4 源码编译部署（开发 / 调试）
适合需要改动代码或深度调试的开发者，需要 Go 工具链。
# 1) 克隆并准备工具链（Go 见 go.mod，当前约 1.27；另需 Clang 20 / LLD 20 / CMake >=4.0 / PCRE2）
git clone https://github.com/infiniflow/ragflow.git
cd ragflow
# 2) 下载本地开发依赖（原生静态库 + 运行时资源：cl100k 词表、DeepDoc .ort 权重、Embedding tokenizer）
uv run tools/scripts/download_dev_deps.py
# 3) 编译全部服务
./build.sh --all
# 4) 启动依赖服务（ES 需先设 vm.max_map_count）
sudo sysctl -w vm.max_map_count=262144
docker compose --env-file docker/.env -f docker/docker-compose-base.yml up -d --wait es01 mysql minio nats kvrocks
# 5) 执行数据库迁移
./bin/ragflow_server --migrate
# 6) 在四个终端分别启动服务：
./bin/ragflow_server --admin # 管理，端口 9381
./bin/ragflow_server --ingestor # 摄取
./bin/ragflow_server --syncer # 同步
./bin/ragflow_server # API（默认 9380）
源码运行需确保
conf/service_conf.yaml中的主机/端口指向本机可访问地址。
六、配置文件参数全解
RAGFlow 部署主要由两份配置驱动：
docker/.env：控制镜像版本、文档引擎、各类中间件（ES/MySQL/MinIO/…）的端口与密码、对外暴露端口。conf/service_conf.yaml（模板service_conf.yaml.template）：运行期服务连接参数（被.env中的变量渲染）。
6.1 docker/.env 参数逐条说明
安全警告：
.env顶部明确提示——不要使用默认密码部署到非本地环境。上线前务必修改ELASTIC_PASSWORD、MYSQL_PASSWORD、MINIO_PASSWORD、OCEANBASE_PASSWORD、REDIS_PASSWORD、ADMIN_DEFAULT_PASSWORD等全部口令。可openssl rand -hex 32生成随机串。
6.2 conf/service_conf.yaml 参数逐条说明
该文件按"服务段"组织，多数值通过 ${ENV} 引用 .env 变量，便于统一管控。
七、启动 / 后台常驻 / 开机自启 / 改端口
7.1 后台常驻启动
docker compose up -d 本身就是"后台/分离"模式。确认就绪：
docker ps # 依赖显示 healthy、ragflow 容器运行中
curl -f http://localhost/api/v1/system/healthz # HTTP 200 即就绪
docker logs -f ragflow-cpu # 查看实时日志
7.2 修改 Web 端口（Docker）
编辑 ragflow/docker/.env，修改对外端口：
SVR_WEB_HTTP_PORT=8080
然后重建生效：
cd ragflow/docker
docker compose -f docker-compose.yml up -d
访问 http://<IP>:8080。健康检查也需带上端口：curl -f http://localhost:8080/api/v1/system/healthz。 其它中间件端口（ES ES_PORT、MinIO MINIO_PORT、MySQL EXPOSE_MYSQL_PORT 等）同理在 .env 修改。
7.3 开机自启
方式 A：利用 Compose 重启策略（推荐） docker-compose.yml 中服务通常已配置 restart: unless-stopped。只需保证 Docker 守护进程开机启动：
Linux（systemd）：
sudo systemctl enable --now docker之后容器随 Docker 自动拉起。
方式 B：systemd 托管整个 RAGFlow（以 Linux 为例） 新建 /etc/systemd/system/ragflow.service：
[Unit]
Description=RAGFlow (docker compose)
Requires=docker.service
After=docker.service
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/ragflow/docker
ExecStart=/usr/bin/docker compose -f docker-compose.yml up -d
ExecStop=/usr/bin/docker compose -f docker-compose.yml down
TimeoutStartSec=0
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now ragflow
Windows / macOS 可在 Docker Desktop 设置中勾选 "Start Docker Desktop when you log in"，并确保容器
restart: unless-stopped，实现登录即自启。
八、功能实操教程
以下以 Docker 部署、默认 80 端口为例。每一步对应 Web 界面操作。
8.1 初始化与登录
浏览器打开
http://<你的机器IP>（默认 80 端口）。首次启动后，超级管理员账号为
admin@ragflow.io，密码为.env中ADMIN_DEFAULT_PASSWORD（默认admin）。登录后请立即修改密码。若页面提示"网络异常/network anormal"，多半是服务尚未就绪——先确认
curl -f http://localhost/api/v1/system/healthz返回 200 再登录。
8.2 配置大模型（Model Providers）
RAGFlow 是 RAG 引擎，需配合 LLM 才能问答。进入 右上角头像 → Model providers：
点击所需模型厂商（OpenAI、DeepSeek、通义千问、Ollama、vLLM、OpenAI-API-Compatible 等），填入
API key与Base URL。点击 Set default models，设置默认： - Chat model（对话模型） - Embedding model（向量化模型） - Rerank model（重排，可选） - Image-to-text model（图文，可选）
也可本地部署模型（Ollama / vLLM），详见官方 Deploy Local Models。启用本地 Embedding 需在
.env的COMPOSE_PROFILES中加入tei-cpu/tei-gpu并配置TEI_MODEL。
注意：选定 Embedding 模型并解析过文件后，不可再更改该数据集的 Embedding 模型（必须保证同一数据集各文件处于同一向量空间）。
8.3 创建知识库 / 数据集（Dataset）
顶部中间点击 Dataset 标签 → Create dataset。
输入数据集名称，点 OK，进入该数据集的 Configuration 配置页。
选择 Embedding 模型 与 切块模板（Chunking method）。RAGFlow 提供多种面向不同版式的模板（通用、论文、表格、书籍、法律等）。
进入数据集页，点击 + Add file → Local files 上传文档。 - 支持格式：文档（PDF、DOC、DOCX、TXT、MD、MDX）、表格（CSV、XLSX、XLS）、图片（JPEG、JPG、PNG、TIF、GIF）、幻灯片（PPT、PPTX），以及邮件、网页等。
在文件条目中点击 播放按钮 ▶ 开始解析（parsing）。解析可在后台进行，进度可见。
8.4 查看切块与人工干预
点击"解析完成"的文件，进入 Chunk 页查看切块结果。
悬停每个快照可快速预览切块内容；双击文本块可手动添加关键词/问题，提升该块在相关查询中的排名权重。
在 Retrieval testing 的
Test text中输入问题做检索自测，确认召回与引用是否正确（RAGFlow 会给出带引用的可信回答）。
8.5 创建 AI 对话（Chat）
顶部中间点击 Chat → Create chat 创建助手。
进入配置页，在右侧 Chat setting 中： - 命名助手并指定关联的 数据集。 - Empty response：若希望答案严格限定在数据集内，填写兜底回复（检索不到时统一返回）；留空则允许模型"自由发挥"（可能产生幻觉）。
编辑 System prompt（初学可先用默认）。
在 Model 下拉选择对话模型。
开始对话。
8.6 API 调用
第一步：获取 API Key 右上角头像 → API keys（或 Model providers 相关入口）→ 创建 Key，妥善保存。
第二步：对话补全示例（HTTP API）
export RAGFLOW_API_KEY="<你的API_KEY>"
export RAGFLOW_HOST="http://<你的机器IP>" # 默认 80 端口可省略 :80
# 列出对话，获取 chat_id
curl -X POST "${RAGFLOW_HOST}/api/v1/chats" \
-H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"name": "我的知识库助手", "dataset_ids": ["<数据集ID>"]}'
# 发起对话
curl -X POST "${RAGFLOW_HOST}/api/v1/chats/<chat_id>/completions" \
-H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"question": "请基于知识库回答：……", "stream": false}'
检索（Retrieval）示例：
curl -X POST "${RAGFLOW_HOST}/api/v1/retrieval" \
-H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"question": "……", "dataset_ids": ["<数据集ID>"], "top_k": 5}'
完整接口见官方 HTTP API Reference。也可使用 Python SDK：
pip install ragflow-sdk。
九、全套报错故障排查
1. 端口被占用 / 权限不足（如 80 端口）
现象：
docker compose up报错bind: address already in use或permission denied（绑定 80/443 需特权）。解决：修改
docker/.env的SVR_WEB_HTTP_PORT（如8080），或释放占用端口；Linux 非 root 绑定 1024 以下端口需特权/转发。
2. Elasticsearch 启动失败：max virtual memory areas vm.max_map_count is too low
现象：
es01容器反复重启或bootstrap checks failed。解决：
sudo sysctl -w vm.max_map_count=262144，并在/etc/sysctl.conf永久写入；Docker Desktop 在对应 VM 中设置。改用DOC_ENGINE=infinity可规避此要求。
3. 显存 / 内存不足（OOM）
现象：容器被 Kill、
docker logs出现OOMKilled、解析卡死。解决：调大
MEM_LIMIT；减小ingestor.page_concurrency；为宿主机增加内存；本地 Embedding 模型（如Qwen3-Embedding-0.6B约需 25GB）改用语义更小的BAAI/bge-small-en-v1.5（约 1.2GB），或直接接入云端 Embedding API。
4. 镜像拉取失败（网络/墙）
现象：
docker compose pull超时或manifest unknown。解决：在
.env将RAGFLOW_IMAGE改为华为云swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v1.0.0-rc2或阿里云registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v1.0.0-rc2；或尝试nightly标签。
5. 数据库版本不匹配：Refusing to start: database was migrated by a newer version
现象：Go 服务拒绝启动。
解决：生产请用版本 ≥ 数据库迁移版本的二进制；本地开发在
.env设RAGFLOW_DEV_MODE=true后重新up -d（会禁用降级检查）。回滚版本时参见第十节。
6. GPU 不可用 / DEVICE=gpu 但无显卡
现象：GPU 版容器报错找不到 CUDA / 设备。
解决：确认宿主机有 NVIDIA 驱动并安装
nvidia-container-toolkit；或在.env改回DEVICE=cpu，用docker-compose.yml而非docker-compose-gpu.yml。
7. 模型/权重下载失败（HuggingFace 不可达）
现象：首次解析或启动 TEI 时卡在下载。
解决：在
.env取消注释HF_ENDPOINT=https://hf-mirror.com使用国内镜像；或手动下载权重挂载到对应目录。
8. 登录提示"网络异常"但服务在跑
现象：页面报错 network anormal。
解决：这是服务未就绪的典型表现。先
curl -f http://localhost/api/v1/system/healthz确认返回 200，再登录；并检查docker logs -f ragflow-cpu是否仍在做数据库迁移。
9. 防火墙 / 外部无法访问
现象：本机可访问，局域网/公网打不开。
解决：确认云服务器安全组/系统防火墙放行
SVR_WEB_HTTP_PORT；若改过端口需带端口访问；反向代理（nginx）需配置trusted_proxies。
10. 解析卡住 / 无切块
现象：文件解析长时间无进展。
解决：检查
ragflow-cpu日志中的摄取错误；确认已配置可用的 Embedding 模型；确认.env中TEI_MODEL资源充足；必要时调大ingestor并发参数。
11. 中文/分词异常或过滤失效
现象：中文检索过滤不正常。
解决：在数据集设置中正确选择文档语言；确保 Embedding 模型对中英文支持良好；升级到已修复该问题的版本（官方已在
v0.26.4修复"filter failed to use Chinese"）。
十、升级 / 回滚 / 卸载教程
10.1 升级
cd ragflow/docker
# 1) 拉取最新代码并切换到新标签
git checkout main && git pull
git checkout v0.27.3 # 或最新稳定版
# 2) 拉取最新镜像
docker compose -f docker-compose.yml pull
# 3) 重启（自动执行数据库迁移）
docker compose -f docker-compose.yml up -d
升级前务必备份数据（见 10.4）。
跨大版本（尤其 0.x → 1.0 架构）建议先读 Release Notes，确认迁移路径。
10.2 版本回退（回滚）
cd ragflow/docker
git checkout v0.27.2 # 切回旧标签
docker compose -f docker-compose.yml up -d
Compose 使用命名数据卷（MySQL/MinIO/ES 等），回滚镜像不会删除数据。
注意：数据库迁移通常是单向的。从新版本回退到旧版本时，若新版本已执行更高版本迁移，旧二进制可能拒绝启动（见故障 5）。此时要么保留新版本，要么从备份恢复旧版本的数据快照。开发环境可临时
RAGFLOW_DEV_MODE=true，但生产不推荐。
10.3 数据备份
RAGFlow 的状态主要在 Docker 命名卷中。先查看卷：
docker volume ls | grep ragflow
备份单个卷（以 ragflow_mysql_data 为例）：
docker run --rm -v ragflow_mysql_data:/data -v /backup:/backup alpine \
tar czf /backup/mysql_data_$(date +%F).tar.gz -C /data .
对 ragflow_minio_data（对象存储/原文）、ragflow_esdata（索引）等同样处理。也可直接备份整个 ragflow/docker 所在主机的相关目录与卷。
10.4 彻底卸载
cd ragflow/docker
# 停止并删除容器，但保留数据卷
docker compose -f docker-compose.yml down
# 停止并删除容器 + 数据卷（彻底清除，不可恢复！）
docker compose -f docker-compose.yml down -v
# 删除镜像（可选）
docker rmi infiniflow/ragflow:v1.0.0-rc2
仅
down（不带-v）会保留卷，数据可随下次up -d恢复。需彻底清空时务必加
-v，并确认已无重要数据。
十一、商用许可与合规风险提示
11.1 Apache-2.0 商用要点
RAGFlow 采用 Apache License 2.0，对商业使用总体友好：
✅ 可商用、可修改、可再分发：可将其用于公司内部系统或集成进商业产品。
✅ 包含专利授权（patent grant）：贡献者授予使用者明示的专利许可，降低专利风险。
⚠️ 署名与声明：分发修改版或再分发时，需保留
LICENSE与NOTICE（如有），并在衍生软件中说明变更、保留版权/许可声明。⚠️ 商标：Apache-2.0 不授予商标权。不可在商业宣传中暗示"官方授权/背书"，除非获得书面许可；请勿使用 RAGFlow 名称/Logo 作为你产品的商标。
⚠️ 免责声明：软件按"原样"提供，作者不对适用性、无侵权等作担保。
11.2 数据隐私与合规
数据驻留：RAGFlow 默认本地/私有化部署，文档原文与索引存于你自己的 MySQL/MinIO/ES 等组件中，数据不出域，适合对数据主权有要求的政企场景。
合规框架：处理个人信息/敏感文档时，需遵循所在司法辖区法规（如中国《个人信息保护法 PIPL》、欧盟 GDPR 等）——包括告知同意、最小必要、访问审计、留存期限与删除机制。
模型调用风险：若接入云端 LLM / Embedding API（OpenAI、通义、DeepSeek 等），上传的文档片段会离开本地，进入第三方服务。对保密数据应使用本地模型（Ollama/vLLM/TEI）或私有化大模型网关。
访问控制：上线前修改所有默认口令（
ADMIN_DEFAULT_PASSWORD、ELASTIC_PASSWORD、MYSQL_PASSWORD、MINIO_PASSWORD等），配置 HTTPS（可用SVR_WEB_HTTPS_PORT+ 反向代理证书），并通过防火墙/安全组限制访问来源。审计与日志：生产环境建议开启
log段日志、必要时启用otel追踪，保留操作审计以满足合规审查。
结语：RAGFlow 凭借 DeepDOC 深度文档理解与可控召回，是企业级私有知识库问答的优选开源方案。按本文从 Docker 一键部署、配置模型、创建数据集到 API 集成，即可在本地快速跑通端到端 RAG 流程。生产部署请务必修改默认口令、做好数据备份并关注版本迁移说明。