# Ubuntu 24.04 上的 RAGFlow 需要挂载 Windows SMB 共享
你的场景本质是：**Ubuntu 24.04 上的 RAGFlow 需要挂载 Windows SMB 共享（域环境/或工作组共享），让知识库可以读取文件。**
下面给你一套可落地的方案（推荐用 CIFS 挂载）。
---
# 一、核心思路
Linux 访问 Windows 共享 = **SMB/CIFS 挂载成本地目录**
最终目标类似：
```
\\192.168.0.83\市场部
↓
/mnt/ragflow/share/market
```
然后 RAGFlow 直接读 Linux 本地路径即可。
---
# 二、安装必要组件（Ubuntu 24.04）
```bash
sudo apt update
sudo apt install -y cifs-utils
```
---
# 三、创建挂载目录
```bash
sudo mkdir -p /mnt/ragflow/market
```
---
# 四、创建凭据文件（强烈推荐，不要明文写在 mount 命令里）
```bash
sudo nano /etc/smb-cred-shuncom
```
写入：
```
username=xxxx
password=xxxxxxxxx
domain=shuncom
```
> ⚠️ 如果你们是 AD 域用户，这个 domain 很关键
> 如果不确定，也可以尝试：
```
domain=SHUNCOM
```
保存后：
```bash
sudo chmod 600 /etc/smb-cred-shuncom
```
---
# 五、手动测试挂载（关键步骤）
```bash
sudo mount -t cifs //192.168.0.83/市场部 /mnt/ragflow/market \
-o credentials=/etc/smb-cred-shuncom,vers=3.0,iocharset=utf8
```
---
# 六、如果报错（非常常见，逐个排查）
## 1️⃣ 如果提示 authentication failed
尝试改：
```
vers=2.1
或
vers=3.0
或
vers=1.0（不推荐但兼容老系统）
```
---
## 2️⃣ 如果域认证失败（AD环境常见）
改成：
```
-o username=xxxx,domain=xxxxxx,sec=ntlmssp
```
或：
```
sec=ntlmv2
```
---
## 3️⃣ 如果中文目录乱码或无法访问
确保：
```
iocharset=utf8
```
---
## 4️⃣ 如果 ping 通但 mount 不通
检查 SMB 端口：
```bash
nc -zv 192.168.0.83 445
```
必须通：
```
445/tcp open
```
---
# 七、设置开机自动挂载（推荐）
编辑：
```bash
sudo nano /etc/fstab
```
加入：
```
//192.168.0.83/市场部 /mnt/ragflow/market cifs credentials=/etc/smb-cred-shuncom,vers=3.0,iocharset=utf8,_netdev 0 0
#安全的写法
//192.168.0.83/市场部 /mnt/ragflow/market cifs credentials=/etc/smb-cred-shuncom,vers=3.0,iocharset=utf8,_netdev,nofail,x-systemd.automount,x-systemd.device-timeout=10 0 0
```
# 三、每个关键参数解释（非常重要）
## 1️⃣ `_netdev`
👉 告诉系统这是网络文件系统
- 延迟到网络可用后再挂载
- 防止系统启动阶段卡死
---
## 2️⃣ `nofail` ⭐（最重要）
👉 即使挂载失败，也：
- 不阻塞启动
- 不进入 emergency mode
- 系统正常进桌面
---
## 3️⃣ `x-systemd.automount` ⭐（强烈推荐）
👉 这是关键优化：
- 开机不立即挂载
- 访问目录时才挂载（按需挂载）
- 极大减少启动依赖风险
效果：
```
你 ls /mnt/ragflow/market 才触发挂载
```
## 4️⃣ `x-systemd.device-timeout=10`
👉 最多等 10 秒
- 避免 Windows 服务器挂起时 Linux 卡死
---
## 5️⃣ `vers=3.0`
保持 SMB3（Windows 11 / Server 2019+ 推荐）
---
# 八、RAGFlow 接入方式
RAGFlow 通常支持：
### 方法1（推荐）
直接使用本地路径：
```
/mnt/ragflow/market
```
作为知识库数据源
---
### 方法2（如果是 Docker 部署 RAGFlow）
需要挂载 volume：
```yaml
volumes:
- /mnt/ragflow/market:/data/market
```
然后 RAGFlow 读：
```
/data/market
```
---
# 九、你当前环境特别说明（很关键）
你提供的信息：
- Ubuntu 24.04：✔ OK
- DNS 可解析 shuncom.local：✔ AD 正常
- Windows 共享可访问（Win11测试OK）：✔ SMB正常
- 域账号：shuncom/7004：✔ AD用户
👉 说明问题大概率只在：
> Linux CIFS 参数 / SMB版本 / 域认证方式
---
# 十、如果你想“一步到位稳定方案”（推荐）
在 AD 环境里最稳定写法：
```bash
sudo mount -t cifs //192.168.0.83/市场部 /mnt/ragflow/market \
-o username=7004,domain=shuncom,sec=ntlmssp,vers=3.0,iocharset=utf8
```
---
# 如果你愿意，我可以帮你进一步做：
### ✔ 自动诊断挂载失败原因（根据报错日志）
### ✔ RAGFlow + SMB + Docker 最佳生产部署方案
### ✔ AD域统一权限映射（避免权限乱）
### ✔ 多共享目录自动同步方案（rsync / inotify）
只要把你 mount 报错贴出来就能精确定位。
你这个问题已经进入 **RAGFlow + Docker + SMB共享生产级挂载设计** 了，我直接给你一个最稳的方案（避免容器内挂 Windows 共享踩坑）。
---
# 一、核心结论（非常重要）
👉 **不要在 Docker 容器内部直接 mount Windows SMB**
原因：
- 容器没有 systemd / mount 管理能力
- 权限容易炸（cifs-utils + cap\_sys\_admin）
- 重启容器会丢挂载
- RAGFlow 多服务架构（es / go / python）会不一致
---
# 二、正确架构（推荐）
## ✅ 标准企业做法
```
Windows SMB
↓
Ubuntu宿主机 mount CIFS
↓
Docker bind mount
↓
RAGFlow容器读取本地目录
```
---
# 三、你应该这样做（最佳实践）
## Step 1：宿主机挂载 SMB（你之前已经在做）
```bash
sudo mkdir -p /mnt/ragflow/market
```
```bash
sudo mount -t cifs //192.168.0.83/市场部 /mnt/ragflow/market \
-o username=7004,domain=shuncom,vers=3.0,iocharset=utf8,nofail,_netdev,x-systemd.automount
```
---
## Step 2：修改 docker-compose.yml（关键）
你上传的 `docker-compose.yml` 我已经看过结构了（RAGFlow 标准 compose）。
👉 找到 **ragflow 服务（API / server / web）**
一般类似：
```yaml
services:
ragflow:
volumes:
```
---
## Step 3：加一行 bind mount
```yaml
services:
ragflow:
volumes:
- /mnt/ragflow/market:/data/market
```
---
# 四、在 RAGFlow 里怎么用
挂载后你在知识库里直接填：
```
/data/market
```
---
# 五、如果你“强行想在容器内 mount”（不推荐）
可以，但必须满足：
## docker 必须加权限：
```yaml
privileged: true
```
或：
```yaml
cap_add:
- SYS_ADMIN
devices:
- /dev/fuse
```
并且安装：
```bash
cifs-utils
```
在容器里 mount：
```bash
mount -t cifs //192.168.0.83/市场部 /data/market ...
```
❌ 但问题很多：
- 容器重启挂载消失
- 安全风险高
- RAGFlow 多进程不可控
- 不符合生产最佳实践
👉 **不推荐**
---
# 六、你当前 `.env` 的影响（重要）
你 `.env` 里这些不影响挂载：
- Elasticsearch
- MinIO
- MySQL
- RAGFlow\_IMAGE
👉 SMB挂载完全不属于 RAGFlow 内部配置层
---
# 七、最佳生产方案（总结）
## ✔ 推荐唯一方案
### 1️⃣ Ubuntu挂载 SMB
### 2️⃣ docker bind mount
### 3️⃣ RAGFlow读本地路径
---
# 八、增强稳定性（建议你加）
## 1️⃣ 防止 SMB 掉线卡住
fstab：
```fstab
//192.168.0.83/市场部 /mnt/ragflow/market cifs credentials=/etc/smb-cred-shuncom,vers=3.0,nofail,x-systemd.automount,x-systemd.device-timeout=10 0 0
```
---
## 2️⃣ Docker自动重启不丢数据
```yaml
restart: always
```
---
## 3️⃣ 防止 RAGFlow 索引失败（重要）
建议加一个“本地缓存目录”：
```
/mnt/ragflow/cache
```
避免 SMB 慢导致 embedding 卡顿
---
# 九、如果你想进一步优化（进阶）
我可以帮你做这些生产级增强：
### 🚀 1. SMB + 本地缓存双层知识库
### 🚀 2. 自动同步 Windows → Linux（rsync/robocopy）
### 🚀 3. RAGFlow 多数据源容错（SMB挂了自动切本地）
### 🚀 4. 企业级权限隔离（AD用户映射到RAGFlow）
---
# 如果你下一步想做这个👇
👉 “知识库自动同步 + 不依赖SMB实时挂载”
我可以给你一个更稳定的架构（很多企业最后都会升级到这一层）。