飞牛OS中RAGFLOW本地知识库部署

紫飞机

# 飞牛OS系统安装RAGFLOW及配套软件（基于Docker Compose）

本文整合RAGFLOW部署核心流程，适用于飞牛OS系统，按「环境准备→配置→启动→验证→维护」顺序编写，新手可直接复制命令执行，配套软件（MySQL、Valkey、MinIO、Nginx）将随RAGFLOW自动部署。


## 一、前提准备（必做！）
### 1. 环境要求
- 操作系统：飞牛OS（基于Linux，兼容Ubuntu/Debian命令集）
- 依赖工具：Docker（≥20.10）、Docker Compose（≥v2）、`net-tools`（端口查看）、`iptables-persistent`（防火墙规则保存）


### 2. 安装Docker与Docker Compose
若未安装，执行以下命令（飞牛OS通用）：
```bash
# 1. 安装依赖包
yum install -y yum-utils device-mapper-persistent-data lvm2

# 2. 添加Docker源
yum-confi**anager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 3. 安装Docker
yum install -y docker-ce-20.10.24 docker-ce-cli-20.10.24 containerd.io

# 4. 安装Docker Compose（v2，通过pip）
yum install -y python3-pip
pip3 install docker-compose>=2.16.0

# 5. 启动Docker并设置开机自启
systemctl start docker && systemctl enable docker

# 6. 验证安装（出现版本号即成功）
docker --version && docker compose version

3. 创建工作目录

统一部署目录，便于后续维护：

# 创建目录并进入（固定路径，后续操作均在此目录执行）
mkdir -p /opt/my-service && cd /opt/my-service

二、步骤1：上传并检查核心文件

RAGFLOW部署需6类关键文件，需先上传至/opt/my-service目录（文件来源：RAGFLOW官方包或自定义配置）：

1. 核心文件清单

• docker-compose.yml（主启动配置）
• docker-compose-base.yml（基础服务配置，含MySQL/Valkey等）
• .env（环境变量，存储密码/端口）
• service_conf.yaml.template（服务配置模板）
• entrypoint.sh（启动脚本）
• nginx/（目录，含ragflow.conf、proxy.conf、nginx.conf）

2. 检查文件完整性

执行命令确认文件无缺失，缺失需重新上传：

ls -la

预期输出：包含上述所有文件/目录，无遗漏。

三、步骤2：配置环境变量（.env文件）

.env存储数据库密码、服务端口等敏感信息，需修改默认值避免风险：

1. 编辑.env文件

nano .env

2. 关键参数配置（必改项）

# 1. MySQL配置（必须修改默认密码，避免泄露）
MYSQL_ROOT_PASSWORD=YourStrongMySQLRootPwd123  # 自定义MySQL根密码
MYSQL_DATABASE=ragflow                          # 数据库名（固定不变）
MYSQL_USER=ragflow_user                         # 数据库用户（固定不变）
MYSQL_PASSWORD=YourRagflowDBPwd456              # 数据库用户密码（自定义）

# 2. 服务端口（避免与飞牛OS现有服务冲突，默认即可，冲突则修改）
RAGFLOW_PORT=8000                               # RAGFLOW核心服务端口
NGINX_PORT=80                                    # Nginx访问端口（如80被占用，改8080）

# 3. 数据存储（固定路径，无需修改）
DATA_DIR=./data

# 4. 管理员密码（RAGFLOW登录用，自定义）
ADMIN_PASSWORD=YourRagflowAdminPwd789

3. 保存退出

按 Ctrl+O → 回车确认 → 按 Ctrl+X 退出编辑。

四、步骤3：生成服务配置文件（service_conf.yaml）

基于模板生成实际配置，确保与.env的数据库参数一致：

1. 复制模板文件

cp service_conf.yaml.template service_conf.yaml

2. 编辑服务配置

nano service_conf.yaml

3. 同步数据库参数（关键！）

找到db配置块，修改为.env中对应的参数：

db:
  # 格式：mysql+pymysql://[MYSQL_USER]:[MYSQL_PASSWORD]@mysql:3306/[MYSQL_DATABASE]?charset=utf8mb4
  url: mysql+pymysql://ragflow_user:YourRagflowDBPwd456@mysql:3306/ragflow?charset=utf8mb4

• 替换ragflow_user：与.env的MYSQL_USER一致
• 替换YourRagflowDBPwd456：与.env的MYSQL_PASSWORD一致
• 替换ragflow：与.env的MYSQL_DATABASE一致

4. 保存退出

同步骤2.3。

五、步骤4：配置Nginx（确保请求转发正确）

Nginx负责转发前端请求到RAGFLOW服务，需匹配.env的NGINX_PORT：

1. 编辑Nginx核心配置

nano nginx/ragflow.conf

2. 关键配置调整

# 1. 监听端口：必须与.env的NGINX_PORT一致（如.env改8080，此处也改8080）
listen 80;

# 2. 反向代理：指向RAGFLOW服务（固定为ragflow:[RAGFLOW_PORT]，无需改）
location ~ ^/(v1|api) {
    proxy_pass http://ragflow:8000;  # 8000对应.env的RAGFLOW_PORT
    include proxy.conf;              # 加载代理配置（无需修改）
}

# 3. 前端SPA路由处理（解决刷新404，保留默认）
location / {
    root /ragflow/web/dist;          # RAGFLOW前端资源路径（固定）
    index index.html;
    try_files $uri $uri/ /index.html;
}

3. 保存退出

同步骤2.3。

六、步骤5：设置启动脚本权限（避免执行失败）

entrypoint.sh为RAGFLOW启动脚本，需赋予可执行权限：

chmod +x entrypoint.sh

七、步骤6：一键启动RAGFLOW及配套服务

首次启动会自动拉取MySQL、Valkey、MinIO、RAGFLOW等镜像（耗时取决于网络，耐心等待）：

1. 启动命令

根据Docker Compose版本选择（执行后显示done即启动中）：

# 若为Docker Compose v2（推荐，大部分环境）
docker compose up -d

# 若为Docker Compose v1（旧版本，命令无空格）
docker-compose up -d

八、步骤7：验证服务运行状态

1. 检查容器状态

确保所有容器为Up或healthy（无Exited/Restarting）：

docker compose ps

关键服务状态要求：

• ragflow-mysql：healthy（数据库就绪）
• ragflow-redis（Valkey）：Up
• ragflow-server（RAGFLOW核心）：Up

2. 检查服务日志（排查启动失败）

若容器状态异常，查看RAGFLOW日志定位问题：

# 实时查看日志，按Ctrl+C退出
docker compose logs -f ragflow

常见日志错误：

• 数据库连接失败：检查.env与service_conf.yaml的MySQL参数是否一致
• 端口占用：日志含port is already allocated，修改.env的NGINX_PORT或RAGFLOW_PORT，重启服务

3. 检查端口监听

确认Nginx和RAGFLOW端口已正常监听：

# 替换80为.env的NGINX_PORT，8000为RAGFLOW_PORT
ss -tulnp | grep -E ":80|:8000"

预期输出：含docker-proxy进程（端口映射成功）。

九、步骤8：配置飞牛OS防火墙（允许外部访问）

飞牛OS默认启用防火墙，需开放NGINX_PORT（如80），否则外部无法访问：

1. 开放端口（永久生效）

# 替换80为.env的NGINX_PORT（如8080）
firewall-cmd --add-port=80/tcp --permanent

# 重新加载防火墙规则
firewall-cmd --reload

2. 验证防火墙规则

firewall-cmd --list-ports | grep 80  # 替换80为实际NGINX_PORT

预期输出：含80/tcp（规则生效）。

十、步骤9：浏览器访问RAGFLOW

1. 获取飞牛OS服务器IP

ip addr

找到网卡（如eth0）的inet地址（示例：192.168.1.100）。

2. 访问RAGFLOW

在本地浏览器输入（与服务器同局域网）：

http://服务器IP:NGINX_PORT  # 示例：http://192.168.1.100:80

3. 登录系统

• 用户名：admin（默认）
• 密码：.env中配置的ADMIN_PASSWORD（如YourRagflowAdminPwd789）

登录后看到RAGFLOW控制台，即部署成功！

十一、常用维护命令（后续操作）

操作需求	命令（在/opt/my-service目录执行）
停止所有服务	docker compose down 或 docker-compose down
重启所有服务	docker compose restart 或 docker-compose restart
实时查看RAGFLOW日志	docker compose logs -f ragflow 或 docker-compose logs -f ragflow
进入RAGFLOW容器内部	docker compose exec ragflow bash 或 docker-compose exec ragflow bash
备份数据（关键！）	cp -r ./data /opt/my-service_data_backup_$(date +%Y%m%d)
查看已安装Docker镜像	docker images

十二、高频问题排查（飞牛OS专属）

1. 镜像拉取超时（context deadline exceeded）

• 原因：Docker Hub网络慢
• 解决方案：配置国内镜像加速器

  # 编辑Docker配置
  nano /etc/docker/daemon.json
  # 粘贴以下内容（**/阿里云加速器）
  {
    "registry-mirrors": ["https://hub-mirror.c.163.com", "https://swr.cn-north-4.myhuaweicloud.com"]
  }
  # 重启Docker
  systemctl daemon-reload && systemctl restart docker
  

2. MySQL容器状态为unhealthy

• 原因1：数据卷权限不足

  # 找到MySQL数据卷路径
  docker volume inspect my-service_mysql_data | grep Mountpoint
  # 赋予权限（示例路径，替换为实际输出）
  chmod 777 /var/lib/docker/volumes/my-service_mysql_data/_data
  # 重启MySQL
  docker restart ragflow-mysql
  

• 原因2：init.sql脚本缺失
  • 从RAGFLOW官方包找回init.sql，放入/opt/my-service目录，重启服务。

3. 浏览器访问404

• 原因1：Nginx监听端口与.env不一致
  • 重新执行步骤4，确认nginx/ragflow.conf的listen与NGINX_PORT一致。
• 原因2：RAGFLOW服务未启动
  • 执行docker compose restart ragflow-server，查看日志排查。

十三、注意事项

1. 数据备份：定期执行步骤11的备份命令，避免./data目录丢失（含MySQL数据、文档数据）。
2. 版本升级：升级前需停止服务，替换新版本配置文件，再启动。
3. 端口冲突：若飞牛OS已装Nginx，需修改.env的NGINX_PORT为8080/8888等未占用端口。
4. 安全建议：生产环境中，chmod 777仅用于测试，需改为chmod 755并限制目录所有者。

baowen

配几张效果图撒