# Ragflow-Plus 环境配置教程

本文档涵盖了部署和运行 Ragflow-Plus 所需的环境变量、服务端点和系统参数的配置。环境配置定义了系统如何连接到外部服务、管理认证以及适应不同的部署环境。

有关部署已配置系统的信息，请参阅 Docker 部署。有关配置外部服务依赖，请参阅 外部服务设置。有关 AI 模型特定配置，请参阅 AI 模型与 LLM 配置。

1. 配置架构 #

Ragflow-Plus 使用分层配置系统，通过环境变量、配置文件和运行时检测适应不同的部署环境。

1.1 配置流程 #

┌─────────────────────────────────────────┐
│      配置源 (Configuration Sources)       │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │ .env 文件│  │ Docker   │  │运行时│  │
│  │          │  │ 环境变量 │  │检测  │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      配置处理 (Configuration Processing)  │
│  ┌──────────────────────────────────┐  │
│  │ database.py                      │  │
│  │ 环境解析                         │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ service_conf.yaml                │  │
│  │ 服务映射                         │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ Flask 配置                       │  │
│  │ 管理后端                         │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      目标服务 (Target Services)           │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌────┐ │
│  │MySQL │  │ES    │  │MinIO │  │Redis│ │
│  └──────┘  └──────┘  └──────┘  └────┘ │
│  ┌──────────────────────────────────┐  │
│  │ Ragflow Core                     │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ Management Backend/Frontend       │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

2. 主环境文件 #

主环境配置在 .env 文件中定义，包含所有系统范围的参数和服务凭证。

2.1 核心服务配置 #

2.1.1 镜像配置 #

# 核心镜像
RAGFLOW_IMAGE=zstar1003/ragflowplus:v0.5.0
RAGFLOWPLUS_MANAGEMENT_WEB_IMAGE=zstar1003/ragflowplus-management-web:v0.5.0
RAGFLOWPLUS_MANAGEMENT_SERVER_IMAGE=zstar1003/ragflowplus-management-server:v0.5.0

2.1.2 服务端口配置 #

# 服务端口
SVR_HTTP_PORT=9380
MYSQL_PORT=5455
ES_PORT=1200
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
REDIS_PORT=6379

2.1.3 时区和系统配置 #

# 时区设置
TIMEZONE=Asia/Shanghai

# Hugging Face 镜像端点
HF_ENDPOINT=https://hf-mirror.com

# macOS 兼容性
MACOS=false

2.2 应用配置 #

2.2.1 Flask 环境配置 #

# Flask 环境
FLASK_ENV=development

# CORS 配置
CORS_ALLOWED_ORIGINS=http://localhost:8888,http://localhost:80

2.2.2 文件上传限制 #

# 最大文件大小（字节）
MAX_CONTENT_LENGTH=10737418240  # 10GB

3. 环境检测和适配 #

系统通过运行时检测自动适应 Docker 和本地环境。

3.1 Docker 环境检测 #

系统通过检查 /.dockerenv 文件来判断是否运行在 Docker 容器中：

def is_running_in_docker():
    # 检查是否存在/.dockerenv文件
    return os.path.exists('/.dockerenv')

3.2 环境适配逻辑 #

根据运行环境选择合适的主机地址和端口：

Docker 环境：

• MySQL: mysql:3306
• MinIO: minio:9000
• Elasticsearch: es01:9200
• Redis: redis:6379

本地环境：

• MySQL: localhost:5455
• MinIO: localhost:9000
• Elasticsearch: localhost:1200
• Redis: localhost:6379

4. 数据库配置类 #

4.1 数据库连接配置 #

4.1.1 MySQL 配置 #

DB_CONFIG = {
    "host": MYSQL_HOST,  # Docker: "mysql", 本地: "localhost"
    "port": MYSQL_PORT,  # Docker: 3306, 本地: 5455
    "user": "root",
    "password": os.getenv("MYSQL_PASSWORD", "infini_rag_flow"),
    "database": "rag_flow",
}

4.1.2 MinIO 配置 #

MINIO_CONFIG = {
    "endpoint": f"{MINIO_HOST}:{MINIO_PORT}",
    "access_key": os.getenv("MINIO_USER", "rag_flow"),
    "secret_key": os.getenv("MINIO_PASSWORD", "infini_rag_flow"),
    "secure": False,
}

4.1.3 Elasticsearch 配置 #

ES_CONFIG = {
    "host": f"http://{ES_HOST}:{ES_PORT}",
    "user": os.getenv("ELASTIC_USER", "elastic"),
    "password": os.getenv("ELASTIC_PASSWORD", "infini_rag_flow"),
    "use_ssl": os.getenv("ES_USE_SSL", "false").lower() == "true",
}

4.1.4 Redis 配置 #

REDIS_CONFIG = {
    "host": REDIS_HOST,
    "port": REDIS_PORT,
    "password": os.getenv("REDIS_PASSWORD", "infini_rag_flow"),
    "decode_responses": False,
}

4.2 连接工厂函数 #

系统提供连接工厂函数来创建数据库和服务连接：

def get_db_connection():
    """创建MySQL数据库连接"""
    try:
        conn = mysql.connector.connect(**DB_CONFIG)
        return conn
    except Exception as e:
        print(f"MySQL连接失败: {str(e)}")
        raise e

def get_minio_client():
    """创建MinIO客户端连接"""
    return Minio(
        endpoint=MINIO_CONFIG["endpoint"],
        access_key=MINIO_CONFIG["access_key"],
        secret_key=MINIO_CONFIG["secret_key"],
        secure=MINIO_CONFIG["secure"]
    )

5. 管理系统认证 #

5.1 认证配置 #

# 管理系统管理员
MANAGEMENT_ADMIN_USERNAME=admin
MANAGEMENT_ADMIN_PASSWORD=12345678

# JWT 密钥
MANAGEMENT_JWT_SECRET=20250409

5.2 认证流程 #

1. 用户登录：使用用户名和密码进行认证
2. JWT 生成：系统生成 JWT 令牌
3. 令牌验证：后续请求使用 JWT 令牌进行验证

6. 服务配置文件 #

6.1 service_conf.yaml #

主服务配置文件位于 conf/service_conf.yaml，支持环境变量替换：

ragflow:
  host: ${RAGFLOW_HOST:-0.0.0.0}
  http_port: 9380

mysql:
  name: '${MYSQL_DBNAME:-rag_flow}'
  user: '${MYSQL_USER:-root}'
  password: '${MYSQL_PASSWORD:-infini_rag_flow}'
  host: '${MYSQL_HOST:-mysql}'
  port: 3306
  max_connections: 100
  stale_timeout: 30

minio:
  user: '${MINIO_USER:-rag_flow}'
  password: '${MINIO_PASSWORD:-infini_rag_flow}'
  host: '${MINIO_HOST:-minio}:9000'

es:
  hosts: 'http://${ES_HOST:-es01}:9200'
  username: '${ES_USER:-elastic}'
  password: '${ELASTIC_PASSWORD:-infini_rag_flow}'

redis:
  db: 1
  password: '${REDIS_PASSWORD:-infini_rag_flow}'
  host: '${REDIS_HOST:-redis}:6379'

6.2 配置优先级 #

配置优先级从高到低：

1. 环境变量：直接设置的环境变量
2. .env 文件：.env 文件中的配置
3. 默认值：代码中的默认值

7. 环境变量完整列表 #

7.1 核心服务变量 #

变量名	默认值	说明
RAGFLOW_IMAGE	zstar1003/ragflowplus:v0.5.0	主应用镜像
RAGFLOWPLUS_MANAGEMENT_WEB_IMAGE	zstar1003/ragflowplus-management-web:v0.5.0	管理前端镜像
RAGFLOWPLUS_MANAGEMENT_SERVER_IMAGE	zstar1003/ragflowplus-management-server:v0.5.0	管理后端镜像
SVR_HTTP_PORT	9380	主应用 HTTP 端口
TIMEZONE	Asia/Shanghai	系统时区

7.2 数据库变量 #

变量名	默认值	说明
MYSQL_HOST	mysql (Docker) / localhost (本地)	MySQL 主机
MYSQL_PORT	3306 (Docker) / 5455 (本地)	MySQL 端口
MYSQL_PASSWORD	infini_rag_flow	MySQL 密码
MYSQL_DBNAME	rag_flow	MySQL 数据库名
MYSQL_USER	root	MySQL 用户名

7.3 存储服务变量 #

变量名	默认值	说明
MINIO_HOST	minio (Docker) / localhost (本地)	MinIO 主机
MINIO_PORT	9000	MinIO 端口
MINIO_USER	rag_flow	MinIO 用户名
MINIO_PASSWORD	infini_rag_flow	MinIO 密码
ES_HOST	es01 (Docker) / localhost (本地)	Elasticsearch 主机
ES_PORT	9200 (Docker) / 1200 (本地)	Elasticsearch 端口
ELASTIC_PASSWORD	infini_rag_flow	Elasticsearch 密码
REDIS_HOST	redis (Docker) / localhost (本地)	Redis 主机
REDIS_PORT	6379	Redis 端口
REDIS_PASSWORD	infini_rag_flow	Redis 密码

7.4 管理系统变量 #

变量名	默认值	说明
MANAGEMENT_ADMIN_USERNAME	admin	管理员用户名
MANAGEMENT_ADMIN_PASSWORD	12345678	管理员密码
MANAGEMENT_JWT_SECRET	20250409	JWT 密钥
CORS_ALLOWED_ORIGINS	http://localhost:8888,http://localhost:80	CORS 允许的源
MAX_CONTENT_LENGTH	10737418240	最大文件大小（10GB）

8. 配置最佳实践 #

8.1 环境变量管理 #

1. 使用 .env 文件：将所有敏感信息存储在 .env 文件中
2. 不要提交到版本控制：将 .env 添加到 .gitignore
3. 使用环境变量模板：提供 .env.example 作为模板
4. 定期更新密码：定期更换默认密码

8.2 配置文件分离 #

1. 开发环境：使用 docker/.env.dev
2. 生产环境：使用 docker/.env.prod
3. 测试环境：使用 docker/.env.test

8.3 配置验证 #

在启动前验证关键配置项：

# 检查必需的环境变量
python -c "
import os
required_vars = ['MYSQL_PASSWORD', 'ELASTIC_PASSWORD', 'MINIO_PASSWORD']
for var in required_vars:
    if not os.getenv(var):
        print(f'警告: {var} 未设置')
    else:
        print(f'✓ {var} 已设置')
"

8.4 配置文档化 #

记录所有配置项的含义和默认值，便于团队协作和维护。

9. 常见配置问题 #

9.1 连接失败 #

问题：无法连接到数据库或存储服务

解决方案：

1. 检查环境变量是否正确设置
2. 验证服务是否正在运行
3. 检查网络连接和端口映射
4. 确认 Docker 环境检测是否正确

9.2 端口冲突 #

问题：端口已被占用

解决方案：

1. 修改 .env 文件中的端口配置
2. 检查是否有其他服务占用端口
3. 使用 netstat 或 lsof 检查端口占用

9.3 认证失败 #

问题：管理系统认证失败

解决方案：

1. 检查 MANAGEMENT_ADMIN_USERNAME 和 MANAGEMENT_ADMIN_PASSWORD
2. 验证 MANAGEMENT_JWT_SECRET 是否正确
3. 检查 CORS 配置是否允许前端访问

10. 总结 #

Ragflow-Plus 的环境配置系统提供了灵活的配置管理：

• 分层配置：支持环境变量、配置文件和运行时检测
• 环境适配：自动适应 Docker 和本地环境
• 安全配置：敏感信息通过环境变量管理
• 配置验证：提供配置验证机制
• 最佳实践：遵循配置管理最佳实践

通过合理配置环境变量，可以轻松部署和管理 Ragflow-Plus 系统。