以下是完整的部署方案文档，包含 systemd 管理 rclone 挂载 MinIO 桶的步骤、新增挂载的方法以及常见问题处理。

---

# Rclone + Systemd 挂载 MinIO 桶到 CentOS 9 完整方案

## 1. 概述

本方案使用 **systemd 模板单元** 管理多个 MinIO 桶的挂载，相较于 `/etc/fstab` 更稳定、可控，支持网络依赖、自动重启和开机自启。所有桶统一挂载到 `/mnt/oss/<bucket-name>` 目录下。

### 适用环境
- CentOS 9 Stream / RHEL 9 及其衍生版
- MinIO 兼容 S3 接口
- rclone v1.74+ 已安装

---

## 2. 安装与准备

### 2.1 安装 rclone 及依赖

```bash
# 启用 CRB 仓库（CentOS 9 需要）
sudo dnf config-manager --set-enabled crb
# 安装 rclone 和 fuse
sudo dnf install -y rclone fuse fuse-devel
```

### 2.2 加载 fuse 内核模块并启用 user_allow_other

```bash
sudo modprobe fuse
echo fuse | sudo tee /etc/modules-load.d/fuse.conf
# 启用允许其他用户访问挂载点
sudo sed -i 's/# user_allow_other/user_allow_other/' /etc/fuse.conf
```

### 2.3 验证安装

```bash
rclone --version
```

---

## 3. 配置 rclone 连接 MinIO

### 3.1 创建配置文件

编辑 `/root/.config/rclone/rclone.conf`（若目录不存在则创建）：

```ini
[oss]
type = s3
provider = Minio
access_key_id = YOUR_ACCESS_KEY
secret_access_key = YOUR_SECRET_KEY
endpoint = http://YOUR_MINIO_IP:9000
# 如果 MinIO 使用路径风格请求，取消下面注释
# force_path_style = true
```

**参数说明**：
- `oss`：远程端点名称，后续挂载时使用 `oss:bucket-name`
- `access_key_id` / `secret_access_key`：MinIO 的 AK/SK
- `endpoint`：MinIO API 地址（不是 Web 控制台地址）

### 3.2 测试连接

```bash
rclone ls oss:your-bucket-name
```
若能列出文件，说明配置成功。

---

## 4. 创建挂载点目录

```bash
# 创建基础目录
sudo mkdir -p /mnt/oss

# 为每个桶创建子目录（示例，按需创建）
sudo mkdir -p /mnt/oss/{level2-csv,level2-feather,orderbook,stock-bar-1m,stock-twap-1m,stock-vwap-1m,exit4-price,stock-bar-daily}
```

> 挂载目录名称建议与桶名一致，便于管理。

---

## 5. 创建 systemd 模板单元

### 5.1 编写服务模板

创建文件 `/etc/systemd/system/rclone-mount@.service`，内容如下：

```ini
[Unit]
Description=Rclone Mount for %I
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
User=root
ExecStart=/usr/bin/rclone mount --daemon \
    --config=/root/.config/rclone/rclone.conf \
    --allow-other \
    --vfs-cache-mode=full \
    --vfs-write-back 0 \
    oss:%i /mnt/oss/%i
ExecStop=/bin/fusermount -uz /mnt/oss/%i
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

**关键参数说明**：
- `%I`：模板实例名称，例如 `orderbook`，对应桶名和挂载点子目录名
- `--daemon`：让 rclone 以后台进程运行
- `--vfs-cache-mode=full`：支持随机读写，可改为 `writes` 或 `off` 根据需求
- `Restart=on-failure`：挂载异常退出时自动重试
- `ExecStop`：卸载时使用 `fusermount -uz` 强制卸载

### 5.2 重新加载 systemd

```bash
sudo systemctl daemon-reload
```

---

## 6. 启用并启动挂载服务

### 6.1 为单个桶启用

```bash
sudo systemctl enable rclone-mount@orderbook
sudo systemctl start rclone-mount@orderbook
```

### 6.2 批量启用所有桶（以你的 8 个桶为例）

```bash
for bucket in level2-csv level2-feather orderbook stock-bar-1m stock-twap-1m stock-vwap-1m exit4-price stock-bar-daily; do
    sudo systemctl enable rclone-mount@$bucket
    sudo systemctl start rclone-mount@$bucket
done
```

### 6.3 验证挂载

```bash
# 查看服务状态
sudo systemctl status 'rclone-mount@*'

# 检查挂载点
mount | grep rclone

# 测试访问
ls /mnt/oss/orderbook
```

---

## 7. 管理命令

| 操作 | 命令 |
|------|------|
| 查看所有挂载服务状态 | `systemctl status 'rclone-mount@*'` |
| 重启指定桶的挂载 | `systemctl restart rclone-mount@orderbook` |
| 停止挂载 | `systemctl stop rclone-mount@orderbook` |
| 禁用开机自启 | `systemctl disable rclone-mount@orderbook` |
| 查看某桶的挂载日志 | `journalctl -u rclone-mount@orderbook -f` |
| 手动卸载（紧急） | `fusermount -uz /mnt/oss/orderbook` |

---

## 8. 新增挂载点的方法

后续如果需要挂载新的 MinIO 桶（例如 `new-bucket`），只需执行以下三步：

### 8.1 创建挂载点目录

```bash
sudo mkdir -p /mnt/oss/new-bucket
```

### 8.2 启用服务

```bash
sudo systemctl enable rclone-mount@new-bucket
sudo systemctl start rclone-mount@new-bucket
```

### 8.3 验证

```bash
ls /mnt/oss/new-bucket
```

> 无需修改任何配置文件，模板 `rclone-mount@.service` 会自动处理。

---

## 9. 卸载所有挂载点（如需移除）

```bash
# 停止所有 rclone 挂载服务
sudo systemctl stop 'rclone-mount@*'
# 可选：禁用所有
sudo systemctl disable 'rclone-mount@*'
# 手动确认无残留
mount | grep rclone
```

---

## 10. 常见问题与解决

### 10.1 挂载后 `ls` 为空或 `Transport endpoint is not connected`

**原因**：缓存目录权限问题或网络断开。

**解决**：
```bash
# 重启对应服务
sudo systemctl restart rclone-mount@orderbook
# 或清理缓存（若使用默认缓存 /root/.cache/rclone）
rm -rf /root/.cache/rclone/vfs/oss/orderbook
```

### 10.2 服务启动失败，日志显示 `fuse: device not found`

**解决**：加载 fuse 模块并设置开机加载：
```bash
sudo modprobe fuse
echo fuse | sudo tee /etc/modules-load.d/fuse.conf
```

### 10.3 `allow_other` 不生效

**解决**：检查 `/etc/fuse.conf` 是否包含 `user_allow_other` 且未注释，修改后无需重启服务，重新挂载即可。

### 10.4 开机后挂载未自动拉起

**原因**：网络依赖未完全满足。

**解决**：确认服务文件中已包含 `After=network-online.target` 和 `Wants=network-online.target`。若仍有问题，可添加延时：
```ini
ExecStartPre=/bin/sleep 5
```

### 10.5 如何调整缓存目录或 VFS 模式？

编辑 `/etc/systemd/system/rclone-mount@.service`，修改 `ExecStart` 中的参数，例如：
```bash
--cache-dir=/tmp/rclone-cache \
--vfs-cache-mode=writes
```
修改后执行：
```bash
sudo systemctl daemon-reload
sudo systemctl restart rclone-mount@your-bucket
```

---

## 11. 备份与恢复建议

- **备份 rclone 配置**：`cp /root/.config/rclone/rclone.conf /safe/location`
- **备份 systemd 模板**：`cp /etc/systemd/system/rclone-mount@.service /safe/location`
- 重装系统后，只需恢复这两个文件，重新 `systemctl enable` 即可。

---

## 12. 总结

通过 systemd 模板单元管理 MinIO 桶挂载，具有以下优点：

- **一次配置，无限新增**：新增桶只需 `systemctl enable/start rclone-mount@newbucket`
- **开机自启，网络感知**：等待网络就绪后挂载，避免启动失败
- **自动恢复**：挂载异常退出时自动重试
- **统一管理**：日志、状态、启停均通过 systemctl 完成

> 本方案已在 CentOS 9 Stream + rclone v1.74 环境下验证通过。

如有其他问题，可通过 `journalctl -u rclone-mount@your-bucket -n 50` 查看详细日志并定位。