RAGFlow 项目配置与部署指南

作者：Manus AI 日期：2026年1月22日

摘要

RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在通过融合前沿的 RAG 技术与 Agent 能力，为大型语言模型提供卓越的上下文层 [1]。基于您提供的文件列表，该项目采用 Docker Compose 进行部署，以简化环境依赖（如 MySQL、MinIO、Redis 等）的管理。本指南将详细分析项目文件结构，并提供配置和启动 RAGFlow 服务的具体步骤。

1. 核心文件结构分析

理解项目文件结构是成功配置的第一步。以下表格总结了您提供的文件列表中，对配置和部署至关重要的文件和目录的功能：

文件/目录	功能描述	关键配置内容
`.env`	核心环境变量文件。包含 Docker 容器所需的重要环境变量，用于配置依赖服务的凭证、端口映射和镜像版本等。	`MYSQL_PASSWORD`, `MINIO_PASSWORD`, `SVR_HTTP_PORT`, `RAGFLOW_IMAGE`
`service_conf.yaml.template`	后端服务配置模板。定义 RAGFlow 核心服务的业务逻辑配置，如 LLM 供应商、日志级别等。容器启动时会基于此模板生成 `service_conf.yaml`。	LLM 配置（`factory`、`api_key`）、数据库连接信息（通过 `.env` 变量替换）
`docker-compose.yml`	默认部署编排文件。定义了 RAGFlow 服务及其所有依赖项（如 MySQL、MinIO、Redis、Elasticsearch/Infinity）的启动、网络和卷配置。	服务定义、端口映射、卷挂载
`docker-compose-CN-oc9.yml`	国内/OceanBase 优化版。可能针对国内用户优化了镜像源，或替换了默认的 MySQL 依赖为 OceanBase [2]。	依赖服务替换、镜像源配置
`nginx/` 目录	反向代理配置。包含 Nginx 配置文件，用于处理 HTTP/HTTPS 请求转发，通常默认监听 80 端口，并将请求转发给 RAGFlow 后端服务。	`nginx.conf`, `proxy.conf`, `ragflow.conf`
`entrypoint.sh`	容器启动入口脚本。负责在容器启动时执行初始化任务，例如根据 `.env` 文件替换模板变量，生成最终的 `service_conf.yaml` 文件，并启动 RAGFlow 服务。	环境初始化逻辑
`init.sql`	数据库初始化脚本。用于首次启动时创建 RAGFlow 所需的数据库和表结构。	SQL DDL/DML 语句

2. RAGFlow 配置步骤详解

RAGFlow 的配置主要集中在两个文件：.env 和 service_conf.yaml.template。

2.1. 步骤一：配置环境变量（`.env`）

您需要编辑或创建 .env 文件，以定义您的部署环境参数。如果项目中存在 .env.single-bucket-example，可以将其复制为 .env 并进行修改。

关键配置项说明：

变量名	默认值	作用	建议修改
`MYSQL_PASSWORD`	`ragflow`	MySQL 数据库的 root 密码。	强烈建议修改为强密码。
`MINIO_PASSWORD`	`ragflow`	MinIO 对象存储的密码。	强烈建议修改为强密码。
`REDIS_PASSWORD`	`ragflow`	Redis 缓存的密码。	强烈建议修改为强密码。
`SVR_HTTP_PORT`	`9380`	RAGFlow Web 服务的 HTTP 访问端口。	如果 9380 端口被占用，请修改。
`RAGFLOW_IMAGE`	`infiniflow/ragflow:latest`	RAGFlow Docker 镜像版本。	建议使用官方推荐的稳定版本号，例如 `v0.20.5`。
`TZ`	`Asia/Shanghai`	容器的时区设置。	保持默认或根据需要修改。
`MEM_LIMIT`	`8073741824`	容器内存限制（字节），约 8GB。	根据您的服务器内存资源进行调整。

2.2. 步骤二：配置后端服务（`service_conf.yaml.template`）

该文件是 RAGFlow 业务逻辑的核心配置。您需要关注 LLM (大语言模型) 相关的配置，以确保 RAGFlow 可以连接到您选择的模型服务。

LLM 配置示例：

在 service_conf.yaml.template 中，您会找到类似以下结构的配置块，用于定义可用的 LLM 供应商：

llm_models:
  - factory: "OpenAI"
    api_key: "${OPENAI_API_KEY}" # 这里的变量会在启动时被替换
    model: "gpt-4"
    ...

操作要点：

API 密钥：确保您在 .env 文件中定义了相应的 API 密钥变量（例如 OPENAI_API_KEY），或者直接在模板中替换为您的密钥（不推荐，建议使用环境变量）。
供应商选择：RAGFlow 支持多种 LLM 供应商，如 OpenAI、DeepSeek、Moonshot、Tongyi-Qianwen 等 [3]。请根据您使用的模型修改 factory 和 model 字段。

3. 部署与启动服务

完成上述配置后，您可以使用 Docker Compose 启动 RAGFlow 服务。

3.1. 选择 Compose 文件

根据您的环境选择合适的 docker-compose 文件：

标准部署：使用 docker-compose.yml。
MacOS 部署：使用 docker-compose-macos.yml。
国内/OceanBase 部署：使用 docker-compose-CN-oc9.yml。

3.2. 启动命令

在项目根目录下执行以下命令（假设您选择 docker-compose.yml）：

docker compose -f docker-compose.yml up -d

-f：指定要使用的 Compose 文件。
up：创建并启动容器。
-d：在后台运行容器（分离模式）。

3.3. 停止与清理

当您需要停止服务或进行配置更改时，执行以下命令：

docker compose -f docker-compose.yml down

3.4. 访问 RAGFlow

服务启动成功后，您可以通过浏览器访问 RAGFlow 的 Web 界面：

访问地址：http://<您的主机IP>:<SVR_HTTP_PORT>
默认端口：如果未修改 .env 中的 SVR_HTTP_PORT，则为 http://<您的主机IP>:9380。

参考文献

[1] RAGFlow 官方文档. RAGFlow 简介. URL: https://ragflow.docs-hub.com/docs/dev/configurations/ [2] RAGFlow GitHub 仓库. docker-compose-CN-oc9.yml. URL: https://github.com/infiniflow/ragflow/ [3] RAGFlow 官方文档. LLM 配置. URL: https://ragflow.docs-hub.com/docs/dev/configurations/#llm-service-configuration