前置条件
- 1已注册腾讯云账号
- 2一台腾讯云服务器：**4 核 CPU / 16GB 内存 / 50GB 磁盘起步**（低于此配置无法启动）
- 3服务器已安装 Docker 24.0+ 与 Docker Compose v2.26.1+
- 4已准备一个大模型 API Key（或本机已跑起 Ollama）
读完想动手？新用户首单 8 折上云
服务器 + 大模型 API + 对象存储，新用户首购享 20% 补贴
RAGFlow 腾讯云部署完整指南
RAGFlow 是国产团队 infiniflow 开源的 RAG（检索增强生成）引擎。它和普通知识库工具最大的区别在于深度文档理解：不是简单地把 PDF 切成一段段文字，而是识别表格结构、还原排版、区分标题与正文，最后给出的答案能点回原文的具体位置。
这个能力对哪些场景是刚需？
- 制度与合同库：几百份文件扔进去，员工直接问，答错能追回到原文哪一条
- 财报与研报：表格能认结构，比纯文本切分靠谱得多
- 客服与 Helpdesk：答案必须可溯源，不能张口就来
代价是硬件门槛高。这篇教程先把门槛讲清楚，再带你一步步部署。
第一步：认清硬件门槛（这一步省不了）
RAGFlow 不是轻量级工具，下面这些是官方标注的最低要求，不是推荐配置：
| 项目 | 最低要求 | 说明 |
|---|---|---|
| CPU | ≥ 4 核（x86） | 只支持 x86，ARM 需自行构建镜像 |
| 内存 | ≥ 16 GB | 硬门槛，8GB 起不来 |
| 磁盘 | ≥ 50 GB | 镜像解压后约占 7GB，加上文档与索引 |
| Docker | ≥ 24.0.0 | |
| Docker Compose | ≥ v2.26.1 | |
| Python | ≥ 3.13 | 仅源码运行方式需要 |
警告
⚠️ 内存是硬指标。低于 16GB 时 Elasticsearch 会启动失败，进而整个 RAG 流程卡死。这不是优化能解决的问题，必须升配。
机型对照
| 场景 | 推荐配置 | 说明 |
|---|---|---|
| 个人验证 / 小团队 | 4C16G | 最低可用，文档量控制在几百份内 |
| 部门级知识库 | 8C32G | 几千份文档，多人同时使用 |
| 企业级 | 16C64G + SSD | 大量文档 + 高频查询 |
| 需要 GPU 加速解析 | 上述配置 + GPU 实例 | 在 .env 里设 DEVICE=gpu |
如果你现在的机器只有 8GB，两条路：升配，或者改用 MaxKB 腾讯云部署教程（4C8G 就能跑，单镜像一条命令起步）。
前往 腾讯云轻量应用服务器 选购页，注意轻量机型里选 16GB 内存那一档，别只看 CPU 核数。
第二步：系统参数（必做，漏了一定失败）
RAGFlow 内置的 Elasticsearch 对内核参数有硬性要求。这一步漏掉的话后面必炸，先做完：
1# 检查当前值
2sysctl vm.max_map_count如果小于 262144，按下面改：
1# 临时生效（重启后失效）
2sudo sysctl -w vm.max_map_count=262144
3
4# 永久生效（推荐）
5echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
6sudo sysctl -p再次确认：
1sysctl vm.max_map_count
2# 输出 vm.max_map_count = 262144 才算通过警告
⚠️ 很多人只执行了临时生效那一行，服务器重启后 RAGFlow 起不来，排查半天找不到原因。两条都执行。
第三步：安装 Docker 环境
3.1 安装 Docker
1sudo apt-get update
2sudo apt-get install -y ca-certificates curl gnupg lsb-release
3
4sudo install -m 0755 -d /etc/apt/keyrings
5curl -fsSL https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu/gpg \
6 | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
7sudo chmod a+r /etc/apt/keyrings/docker.gpg
8
9echo \
10 "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
11 https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu \
12 $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
13
14sudo apt-get update
15sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
16
17sudo usermod -aG docker $USER
18newgrp docker3.2 校验版本（必须达标）
1docker --version # 需 >= 24.0.0
2docker compose version # 需 >= v2.26.1Ubuntu 22.04 默认源里的 compose 版本可能偏低，装完务必核对。版本不够就手动装新版：
1sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
2 -o /usr/local/bin/docker-compose
3sudo chmod +x /usr/local/bin/docker-compose3.3 配置镜像加速
腾讯云给每台机器分配了专属加速地址，在控制台「容器镜像服务 → 镜像加速器」查看，形如 https://xxxxxx.mirror.swr.myqcloud.com：
1sudo mkdir -p /etc/docker
2sudo tee /etc/docker/daemon.json <<'EOF'
3{
4 "registry-mirrors": [
5 "https://你的专属地址.mirror.swr.myqcloud.com"
6 ]
7}
8EOF
9sudo systemctl daemon-reload
10sudo systemctl restart docker第四步：部署 RAGFlow
4.1 克隆仓库并锁定版本
1cd /opt
2sudo git clone https://github.com/infiniflow/ragflow.git
3cd ragflow/docker务必切换到稳定版本，直接用 main 分支可能拉到不稳定的每日构建：
1# 查看所有可用版本
2git tag | tail -20
3
4# 切换到稳定版（以实际最新 tag 为准）
5sudo git checkout -f v0.25.6警告
⚠️ 仓库里的 entrypoint.sh 必须与 Docker 镜像版本匹配，跳过 checkout 这一步容易出现容器内脚本与镜像不一致的诡异问题。
4.2 启动服务
CPU 环境（大多数情况）：
1sudo docker compose -f docker-compose.yml up -dGPU 环境（想加速文档解析）：
1# 在 .env 顶部加一行（注意是第 1 行）
2sudo sed -i '1i DEVICE=gpu' .env
3
4# 再启动
5sudo docker compose -f docker-compose.yml up -d首次启动会拉取多个镜像（ ragflow-server、MySQL、MinIO、Elasticsearch、Redis），需要几分钟到十几分钟，取决于带宽。
4.3 确认启动成功（别急着开浏览器）
这一步很多人跳过，然后打开页面看到 network abnormal 就以为部署失败了。
1docker logs -f docker-ragflow-cpu-1看到类似下面的输出才算真正就绪：
1 ____ ___ ______ ______ __
2 / __ \ / | / ____/ / ____// /____ _ __
3 / /_/ // /| | / / __ / /_ / // __ \| | /| / /
4 / / , // ___ |/ /_/ / / __/ / // /_/ / /| |/ /
5/_/ |_//_/ |_|\____/ /_/ /_/ \____/ |/|__/
6
7Running on all addresses (0.0.0.0)警告
⚠️ 容器名可能随版本变化（有的是 docker-ragflow-server-1）。拿不准就先 docker ps 看实际容器名。
4.4 访问与注册
浏览器打开：
http://服务器IP
默认 HTTP 端口是 80，可以省略端口号。首次进入直接注册管理员账号——第一个注册的账号就是管理员，务必用强密码。
警告
⚠️ 如果你的服务器 80 端口被占用，改 docker-compose.yml 里的 80:80 为 8080:80（或其它端口），然后 docker compose down && docker compose up -d 重启生效。也可以在 .env 里改 SVR_WEB_HTTP_PORT。
第五步：接入模型
RAGFlow 本身不带大模型，必须接一个才能对话。它支持 30+ 家模型提供商，也支持本地模型。
5.1 接云端模型（最快）
右上角头像 →「模型提供商」，选你要接的厂商（DeepSeek、通义千问、智谱、OpenAI 等），填入 API Key，点「确定」。
5.2 接本地 Ollama（数据不出内网）
如果你已经按 GLM 腾讯云部署教程 或 Qwen3 腾讯云部署教程 在服务器上跑起了 Ollama：
- 在模型提供商列表里找到 Ollama
- Base URL 填
http://host.docker.internal:11434 - 模型名填你在 Ollama 里拉好的标签（如
glm4:9b） - 点「确定」
警告
⚠️ RAGFlow 跑在 Docker 里，localhost 指的是容器自己。必须用 host.docker.internal 访问宿主机服务，并在 docker-compose.yml 里确保有对应的 extra_hosts 配置（部分版本需手动添加 - "host.docker.internal:host-gateway"）。
5.3 设置默认模型
「系统设置 → 默认模型」里指定：
- 聊天模型：用于生成答案
- 嵌入模型（Embedding）：用于文档向量化，非常重要
- Rerank 模型（可选）：二次排序，能明显提升召回精度
嵌入模型一旦选定，更换后已有文档需要重新解析，所以一开始就选好，别中途换。
5.4 验证模型可用
添加完成后务必点「测试」按钮，看到返回成功再往下走。模型调不通时，后面所有报错都会被归咎到知识库身上，很容易排查错方向。
第六步：构建知识库
6.1 创建知识库
「知识库 → 创建知识库」，关键配置项：
| 配置项 | 建议 | 说明 |
|---|---|---|
| 语言 | 中文 | 影响分词与解析 |
| 权限 | 按需选「团队」或「私有」 | 私有只有自己可见 |
| 嵌入模型 | 与默认一致 | 中途更换需重新解析 |
| 解析方法 | 见下表 | 这是 RAGFlow 的核心差异点 |
6.2 解析方法怎么选
RAGFlow 提供多种解析模板，选错了效果差很多：
| 模板 | 适用文档 | 特点 |
|---|---|---|
| General | 通用文档 | 平衡之选，不知道选什么就用它 |
| Table | 表格多的文档 | 强化表格结构识别 |
| Paper | 学术论文 | 处理分栏与参考文献 |
| Resume | 简历 | 提取结构化字段 |
| Laws | 法规条文 | 按条款切分 |
| Manual | 产品手册 | 保留章节层级 |
| QA | 问答对 | 成对存储 |
| Book | 长篇书籍 | 按章节深度切分 |
实践建议：制度文件用 Laws 或 General；财报研报用 Table；产品手册用 Manual。
6.3 上传与解析
上传文件后，RAGFlow 会自动解析。**必须等解析状态变成「成功」**才能开始问答——这一步对复杂 PDF 可能要几分钟。
点开文件可以看到分块预览，这是 RAGFlow 最有价值的功能之一：你能直接看到文档被切成了什么样，切得不对可以手动调整分块。
6.4 开始问答与验证溯源
在知识库里新建「聊天」，问一个只有你的文档才知道答案的问题。
正确答案会带引用标记，点开能看到原文出处和具体位置。如果答案不带引用，说明检索没命中，要回去检查解析质量或嵌入模型，别直接上线。
第七步：对接业务系统
7.1 API 调用
RAGFlow 提供完整的 HTTP API，「API → API Key」里创建密钥。
1curl -X POST http://服务器IP/api/v1/chats/会话ID/completions \
2 -H "Authorization: Bearer 你的APIKey" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "question": "年假怎么申请？",
6 "stream": false
7 }'7.2 挂进聊天工具
RAGFlow 支持接入企业微信、飞书、钉钉等渠道（在「渠道」配置里）。对内部团队来说，这才是知识库真正被用起来的入口——员工不用记网址，在群里 @ 一下就问了。
如果你要自建机器人后端，可以看 chatgpt-on-wechat + NoneBot 腾讯云部署教程。
第八步：运维与安全
8.1 备份
定期备份这几个卷，别等数据丢了才想到：
1# 查看数据卷
2docker volume ls | grep ragflow
3
4# 备份 MySQL（含用户与知识库元数据）
5docker exec docker-mysql-1 mysqldump -u root -p密码 ragflow > ragflow_$(date +%F).sql警告
⚠️ 文档本身存在 MinIO 里，完整的备份要连 MinIO 数据一起做。生产环境建议直接对 /var/lib/docker/volumes 做快照。
8.2 不要直接暴露 80 端口到公网
RAGFlow 自带登录，但仍建议：
- 用 Nginx 反向代理 + HTTPS
- 只放行必要端口（22 / 80 / 443）
- 管理员账号设强密码，定期更换
如果你已经按 1Panel 腾讯云部署教程 装了面板，可以直接用它的反向代理功能配 HTTPS，比手写 Nginx 配置省事得多。
8.3 更新
1cd /opt/ragflow
2sudo git fetch --tags
3sudo git checkout -f v新版本号
4cd docker
5sudo docker compose -f docker-compose.yml pull
6sudo docker compose -f docker-compose.yml up -d更新前先备份，跨大版本升级可能涉及数据结构变更。
20 条故障排查
| # | 现象 | 原因 | 解决 |
|---|---|---|---|
| 1 | 容器起不来 / ES 反复重启 | vm.max_map_count 未设置 | 执行第二步，设为 262144 并持久化 |
| 2 | 页面提示 network abnormal | 还在初始化 | docker logs -f 等 ASCII Logo 出现 |
| 3 | 内存占用爆满被 OOM | 内存不足 16GB | 升配，无其它办法 |
| 4 | docker compose 报版本错误 | 版本低于 v2.26.1 | 手动装新版 compose |
| 5 | 镜像拉取极慢 | 没配镜像加速 | 配置专属加速地址 |
| 6 | 80 端口冲突 | 已有服务占用 | 改 docker-compose.yml 端口映射 |
| 7 | 上传文档后一直解析中 | 文档过大或复杂 | 拆分文件；或用 GPU 模式加速 |
| 8 | 解析结果乱码 | PDF 是扫描件 | 用带 OCR 的解析模板 |
| 9 | 答案不带引用 | 检索没命中 | 检查嵌入模型；调整分块；确认解析成功 |
| 10 | 模型添加后测试失败 | Base URL 或 Key 错误 | Ollama 要用 host.docker.internal |
| 11 | RAGFlow 连不上本地 Ollama | 用了 localhost | 改为 host.docker.internal:11434 |
| 12 | 表格识别乱成一团 | 用了 General 模板 | 换成 Table 模板重新解析 |
| 13 | 更换嵌入模型后搜不到东西 | 旧索引不兼容 | 重新解析全部文档 |
| 14 | 磁盘快速占满 | 索引与上传文件堆积 | 定期清理；扩容磁盘 |
| 15 | 登录页打不开 | 服务未就绪或防火墙 | 看日志；检查安全组放行 |
| 16 | 升级后功能异常 | 版本不匹配 | 确认 git tag 与镜像版本一致 |
| 17 | 多人使用变慢 | CPU/内存打满 | 升配；或限制并发解析任务 |
| 18 | API 返回 401 | API Key 无效或过期 | 重新生成 Key；检查 Authorization 头格式 |
| 19 | 中文搜索效果差 | 语言选错 | 知识库语言设为中文 |
| 20 | 数据丢失 | 没备份 + 执行了 down -v | ⚠️ docker compose down -v 会删卷，生产环境严禁使用 |
警告
⚠️ 第 20 条是数据事故高发点：down 和 down -v 差一个参数，后者会删除所有数据卷。日常重启用 docker compose restart，需要重建容器时用不带 -v 的 down。
落地建议
- 先把内存买够 —— 16GB 是硬门槛，在这上面省钱只会浪费更多时间。
- 内核参数一次做到位 —— 临时 + 永久两条命令都执行，避免重启后踩坑。
- 嵌入模型一开始就定好 —— 中途更换等于全部文档重新解析。
- 用分块预览检查解析质量 —— 这是 RAGFlow 相比其它工具的核心优势，不看就浪费了。
- 知识库的价值在「被用」 —— 挂进群里比单独一个网址有用得多，员工不会主动去打开新系统。
常见问题
Q为什么 RAGFlow 要求 16GB 内存，我 8GB 的机器不行吗？
不行。RAGFlow 内置 Elasticsearch 做全文与向量检索，加上 MySQL、MinIO、Redis 等多个组件，8GB 机器连容器都拉不起来。这是官方文档明确标注的硬门槛，不是保守建议。如果你的预算只够 8GB，建议改用 MaxKB 腾讯云部署教程，单镜像、4C8G 就能跑。
QRAGFlow 和 MaxKB、FastGPT 有什么不同，该选哪个？
定位不同。RAGFlow 主打**深度文档理解**——能把 PDF 表格、扫描件、复杂排版还原成结构化内容，答案带原文溯源，适合制度库、合同库、财报研报这类要求「答错能追责」的场景，代价是硬件门槛高。MaxKB 与 FastGPT 更轻，开箱即用、配置简单，适合快速搭一个内部问答。要精度和溯源选 RAGFlow，要快和省事选后者。
Q部署完打开页面提示 network abnormal 是失败了吗？
不是。这是 RAGFlow 还在初始化，后台组件没全部就绪。执行 `docker logs -f docker-ragflow-cpu-1`（或对应的容器名），看到 ASCII Logo 与「Running on all addresses」之后再刷新页面。第一次启动通常要等几分钟，急不得。