# ragflow-docker

**Repository Path**: hulu_fly/ragflow-docker

## Basic Information

- **Project Name**: ragflow-docker
- **Description**: ragflow  docker 部署

- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# README

<details open>
<summary>📗 目录</summary>

- 🐳 [Docker Compose](#-docker-compose)
- 🐬 [Docker 环境变量](#-docker-环境变量)
- 🐋 [服务配置](#-服务配置)
- 📋 [配置示例](#-配置示例)

</details>

## 🐳 Docker Compose

- **docker-compose.yml**  
  搭建 RAGFlow 及其依赖项的运行环境。
- **docker-compose-base.yml**  
  搭建 RAGFlow 依赖服务的运行环境：Elasticsearch/[Infinity](https://github.com/infiniflow/infinity)、MySQL、MinIO 和 Redis。

> [!CAUTION]
> 我们不再主动维护 **docker-compose-CN-oc9.yml** 和 **docker-compose-macos.yml**，请自行承担使用风险。不过，欢迎您提交 Pull Request 来改进这些文件。

## 🐬 Docker 环境变量

[.env](./.env) 文件包含 Docker 的重要环境变量。

### Elasticsearch

- `STACK_VERSION`  
  Elasticsearch 的版本。默认值为 `8.11.3`。
- `ES_PORT`  
  将 Elasticsearch 服务暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的服务。默认值为 `1200`。
- `ELASTIC_PASSWORD`  
  Elasticsearch 的密码。

### Kibana

- `KIBANA_PORT`  
  将 Kibana 服务暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的服务。默认值为 `6601`。
- `KIBANA_USER`  
  Kibana 的用户名。默认值为 `rag_flow`。
- `KIBANA_PASSWORD`  
  Kibana 的密码。默认值为 `infini_rag_flow`。

### 资源管理

- `MEM_LIMIT`  
  特定 Docker 容器在运行时可以使用的最大内存量（字节）。默认值为 `8073741824`。

### MySQL

- `MYSQL_PASSWORD`  
  MySQL 的密码。
- `MYSQL_PORT`  
  从 RAGFlow 容器连接 MySQL 的端口。默认值为 `3306`。如果使用外部 MySQL，请修改此值。
- `EXPOSE_MYSQL_PORT`  
  将 MySQL 服务暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的 MySQL 数据库。默认值为 `5455`。

### MinIO

- `MINIO_CONSOLE_PORT`  
  将 MinIO 控制台界面暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的 Web 控制台。默认值为 `9001`。
- `MINIO_PORT`  
  将 MinIO API 服务暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的 MinIO 对象存储服务。默认值为 `9000`。
- `MINIO_USER`  
  MinIO 的用户名。
- `MINIO_PASSWORD`  
  MinIO 的密码。

### Redis

- `REDIS_PORT`  
  将 Redis 服务暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的 Redis 服务。默认值为 `6379`。
- `REDIS_PASSWORD`  
  Redis 的密码。

### RAGFlow

- `SVR_HTTP_PORT`  
  将 RAGFlow 的 HTTP API 服务暴露到宿主机的端口，允许**外部**访问 Docker 容器内运行的服务。默认值为 `9380`。
- `SVR_WEB_HTTP_PORT`  
  将 RAGFlow 的 Web 界面（HTTP）暴露到宿主机的端口。默认值为 `80`。
- `SVR_WEB_HTTPS_PORT`  
  将 RAGFlow 的 Web 界面（HTTPS）暴露到宿主机的端口。默认值为 `443`。
- `API_PROXY_SCHEME`  
  nginx 后端路由模式。默认值为 `python`（纯 Python 后端）。可选值：
  - `python`：所有 API 请求转发给 Python 服务器
  - `hybrid`：Python + Go 混合模式，按路径分发
  - `go`：全部转发给 Go 服务器
- `RAGFLOW_IMAGE`  
  Docker 镜像版本。默认值为 `infiniflow/ragflow:v0.25.6`。RAGFlow Docker 镜像不包含嵌入模型。

> [!TIP]  
> 如果无法下载 RAGFlow Docker 镜像，可以尝试以下镜像源。  
> 
> - 对于 `nightly` 版本：  
>   - `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly` 或  
>   - `RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightly`。

### 时区

- `TZ`  
  本地时区。默认值为 `'Asia/Shanghai'`。

### Hugging Face 镜像站点

- `HF_ENDPOINT`  
  huggingface.co 的镜像站点。默认禁用。如果您访问 Hugging Face 主域名受限，可以取消该行的注释来启用。

### macOS

- `MACOS`  
  macOS 优化选项。默认禁用。如果您的操作系统是 macOS，可以取消该行的注释来启用。

### 最大文件大小

- `MAX_CONTENT_LENGTH`  
  每个上传文件的最大文件大小（字节）。如果您希望更改 128MB 的文件大小限制，可以取消该行的注释。更改后，请确保同步更新 `nginx/nginx.conf` 中的 `client_max_body_size` 值。

### 文档批量处理大小

- `DOC_BULK_SIZE`  
  文档解析时单批次处理的文档分块数。默认值为 `4`。

### 嵌入批量处理大小

- `EMBEDDING_BATCH_SIZE`  
  嵌入向量化时单批次处理的文本分块数。默认值为 `16`。

## 🐋 服务配置

[service_conf.yaml](./service_conf.yaml) 指定了 RAGFlow 的系统级配置，供其 API 服务器和任务执行器使用。在 Docker 化部署中，该文件会根据 [service_conf.yaml.template](./service_conf.yaml.template) 文件自动生成（将所有环境变量替换为其实际值）。

- `ragflow`
  - `host`：API 服务器在 Docker 容器内的 IP 地址。默认值为 `0.0.0.0`。
  - `port`：API 服务器在 Docker 容器内的服务端口。默认值为 `9380`。

- `mysql`
  - `name`：MySQL 数据库名称。默认值为 `rag_flow`。
  - `user`：MySQL 的用户名。
  - `password`：MySQL 的密码。
  - `port`：MySQL 在 Docker 容器内的服务端口。默认值为 `3306`。
  - `max_connections`：MySQL 数据库的最大并发连接数。默认值为 `100`。
  - `stale_timeout`：超时时间（秒）。

- `minio`
  - `user`：MinIO 的用户名。
  - `password`：MinIO 的密码。
  - `host`：MinIO 在 Docker 容器内的服务 IP *和*端口。默认值为 `minio:9000`。

- `oceanbase`
  - `scheme`：连接方案。设置为 `mysql` 则使用 MySQL 配置，设置为其他值则使用下方配置。
  - `config`：
    - `db_name`：OceanBase 数据库名称。
    - `user`：OceanBase 的用户名。
    - `password`：OceanBase 的密码。
    - `host`：OceanBase 服务的主机名。
    - `port`：OceanBase 的端口。

- `oss`
  - `access_key`：用于向 OSS 服务发起认证请求的 Access Key ID。
  - `secret_key`：用于向 OSS 服务发起认证请求的 Secret Access Key。
  - `endpoint_url`：OSS 服务端点的 URL。
  - `region`：OSS Bucket 所在的区域。
  - `bucket`：文件存储所在的 OSS Bucket 名称。当您希望将所有文件存储在指定 Bucket 中时，需要配置此项。
  - `prefix_path`：可选。在 OSS Bucket 中为文件名添加的前缀路径，有助于组织 Bucket 中的文件。

- `s3`：
  - `access_key`：用于向 S3 服务发起认证请求的 Access Key ID。
  - `secret_key`：用于向 S3 服务发起认证请求的 Secret Access Key。
  - `endpoint_url`：兼容 S3 协议的服务端点 URL。当使用 S3 兼容协议而非默认的 AWS S3 端点时，需要配置此项。
  - `bucket`：文件存储所在的 S3 Bucket 名称。当您希望将所有文件存储在指定 Bucket 中时，需要配置此项。
  - `region`：S3 Bucket 所在的 AWS 区域。这对于将请求导向正确的数据中心非常重要。
  - `signature_version`：可选。用于认证请求的签名版本，常用版本包括 `v4`。
  - `addressing_style`：可选。S3 端点的寻址风格，可选 `path` 或 `virtual`。
  - `prefix_path`：可选。在 S3 Bucket 中为文件名添加的前缀路径，有助于组织 Bucket 中的文件。

- `oauth`
  使用第三方账号注册或登录 RAGFlow 的 OAuth 配置。
  - `<channel>`：自定义渠道 ID。
    - `type`：认证类型，可选值包括 `oauth2`、`oidc`、`github`。默认为 `oauth2`，当提供 `issuer` 参数时默认为 `oidc`。
    - `icon`：图标 ID，可选值包括 `github`、`sso`，默认为 `sso`。
    - `display_name`：渠道名称，默认为渠道 ID 的首字母大写格式。
    - `client_id`：必需，分配给客户端应用的唯一标识符。
    - `client_secret`：必需，客户端应用的密钥，用于与认证服务器的通信。
    - `authorization_url`：获取用户授权的基础 URL。
    - `token_url`：用于交换授权码并获取访问令牌的 URL。
    - `userinfo_url`：用于获取用户信息（用户名、邮箱等）的 URL。
    - `issuer`：身份提供商的基础 URL。OIDC 客户端可以通过 `issuer` 动态获取身份提供商的元数据（`authorization_url`、`token_url`、`userinfo_url`）。
    - `scope`：请求的权限范围，以空格分隔的字符串。例如 `openid profile email`。
    - `redirect_uri`：必需，认证流程中授权服务器重定向以返回结果的 URI。必须与在认证服务器上注册的回调 URI 匹配。格式：`https://your-app.com/v1/user/oauth/callback/<channel>`。对于本地配置，可直接使用 `http://127.0.0.1:80/v1/user/oauth/callback/<channel>`。

- `user_default_llm`  
  新 RAGFlow 用户使用的默认 LLM。默认禁用。要启用此功能，请取消 **service_conf.yaml.template** 中对应行的注释。  
  - `factory`：LLM 供应商。可选值：
    - `"OpenAI"`
    - `"DeepSeek"`
    - `"Moonshot"`
    - `"Tongyi-Qianwen"`
    - `"VolcEngine"`
    - `"ZHIPU-AI"`
  - `api_key`：指定 LLM 的 API 密钥。您需要在线申请您的模型 API 密钥。

> [!TIP]  
> 如果您未在此处设置默认 LLM，请在 RAGFlow 界面的**设置**页面中配置默认 LLM。

## 📋 配置示例

### 🔒 HTTPS 配置

#### 前置条件

- 一个指向您服务器的已注册域名
- 服务器上开放 80 和 443 端口
- 已安装 Docker 和 Docker Compose

#### 获取和配置证书（Let's Encrypt）

如果您希望实例通过 `https` 访问，请按以下步骤操作：

1. **安装 Certbot 并获取证书**
   ```bash
   # Ubuntu/Debian
   sudo apt update && sudo apt install certbot
   
   # CentOS/RHEL
   sudo yum install certbot
   
   # 获取证书（请替换为您实际的域名）
   sudo certbot certonly --standalone -d your-ragflow-domain.com
   ```

2. **定位证书文件**  
   生成后，证书文件位于：
   - 证书：`/etc/letsencrypt/live/your-ragflow-domain.com/fullchain.pem`
   - 私钥：`/etc/letsencrypt/live/your-ragflow-domain.com/privkey.pem`

3. **更新 docker-compose.yml**  
   在 `docker-compose.yml` 中为 `ragflow-cpu`（以及 `ragflow-gpu`，如使用 GPU）服务添加证书和 nginx 配置挂载：
   ```yaml
   services:
     ragflow-cpu:
       # ...现有配置...
       volumes:
         # ...其他现有卷挂载...
         # SSL 证书
         - /etc/letsencrypt/live/your-ragflow-domain.com/fullchain.pem:/etc/nginx/ssl/fullchain.pem:ro
         - /etc/letsencrypt/live/your-ragflow-domain.com/privkey.pem:/etc/nginx/ssl/privkey.pem:ro
         # HTTPS nginx 配置（挂载到不同路径，防止被 entrypoint.sh 覆盖）
         - ./nginx/ragflow.https.conf:/etc/nginx/ragflow.https.conf:ro
         - ./nginx/proxy.conf:/etc/nginx/proxy.conf:ro
   
   ```

4. **更新 nginx 配置**  
   编辑 `nginx/ragflow.https.conf`，将 `your-ragflow-domain.com` 替换为您实际的域名。

5. **更新 entrypoint.sh**  
   `entrypoint.sh` 启动时会自动选择 nginx 配置，需要加入 HTTPS 优先检测，防止 HTTP 配置覆盖 HTTPS 配置。在 nginx 配置选择段（约第 182 行起）的最前面插入：
   ```bash
   HTTPS_CONF="/etc/nginx/ragflow.https.conf"

   # Check if HTTPS is enabled (certificate files + https conf exist)
   if [ -f "/etc/nginx/ssl/fullchain.pem" ] && [ -f "${HTTPS_CONF}" ]; then
       cp -f "${HTTPS_CONF}" "$NGINX_CONF_DIR/ragflow.conf"
       echo "HTTPS mode detected: applied nginx config from ragflow.https.conf"
   elif [ -n "$API_PROXY_SCHEME" ]; then  # 将原来的 if 改为 elif
       # ... 原有逻辑保持不变 ...
   ```

6. **重启服务**
   ```bash
   docker-compose down
   docker-compose up -d
   ```

> [!IMPORTANT]
> - 确保您的域名 DNS A 记录指向服务器的 IP 地址
> - 使用 `--standalone` 模式获取证书前，请停止占用 80/443 端口的服务

> [!TIP]
> 对于开发或测试环境，可以使用自签名证书，但浏览器会显示安全警告。

#### 替代方案：使用已有证书

如果您已经拥有其他提供商签发的 SSL 证书：

1. 将证书文件放置在 Docker 可访问的目录中
2. 更新 `docker-compose.yml` 中的卷路径，指向您的证书文件
3. 确保证书文件包含完整的证书链
4. 按照上方 Let's Encrypt 指南的步骤 4-6 继续操作