# MinIO 高可用配置指南

## 📋 MinIO 高可用说明

### ❌ MinIO 不需要传统的主从配置

**重要说明**：MinIO **不是**传统的主从复制架构，而是采用**分布式集群模式**。

**原因**：
- MinIO 是对象存储服务，不是关系型数据库
- MinIO 使用**纠删码（Erasure Code）**技术实现数据冗余
- MinIO 集群模式中，所有节点都是**对等的**，没有主从概念
- MinIO 支持**站点复制（Site Replication）**用于跨站点数据同步

---

## 🎯 双机部署方案选择

针对您的**67/68双机部署场景**，有两种高可用方案：

### 方案A：MinIO 集群模式（推荐）⭐

**特点**：
- ✅ **高可用**：任意节点故障，集群仍可用
- ✅ **数据一致性**：实时同步，无延迟
- ✅ **性能优秀**：分布式读写，负载均衡
- ✅ **自动故障转移**：节点故障自动切换
- ⚠️ **要求**：两台机器网络互通，需要配置 Docker 网络

**适用场景**：生产环境，对数据一致性要求高

---

### 方案B：MinIO 主从同步（简单方案）

**特点**：
- ✅ **配置简单**：使用 `mc mirror` 命令同步
- ✅ **独立部署**：两台机器独立运行，互不影响
- ⚠️ **数据延迟**：同步存在延迟（秒级到分钟级）
- ⚠️ **手动切换**：主节点故障需要手动切换
- ⚠️ **单点风险**：主节点故障时，从节点可能数据不完整

**适用场景**：开发/测试环境，或对实时性要求不高的场景

---

## 🚀 方案A：MinIO 集群模式配置（推荐）

### 前置条件

✅ **网络互通**：67和68机器可以互相访问  
✅ **Docker 网络**：需要配置跨主机 Docker 网络  
✅ **数据目录**：每台机器准备独立的 MinIO 数据目录  

---

### 配置步骤

#### 第一步：配置 Docker 跨主机网络（可选，推荐使用 host 模式）

**方案1：使用 host 网络模式（最简单）**

修改 `docker-compose-minio-cluster.yml`，使用 `host` 网络：

```yaml
version: '3.8'

services:
  # MinIO节点1 (机器67)
  minio1:
    image: minio/minio:RELEASE.2025-04-22T22-12-26Z
    container_name: minio1
    command: server --address ":9000" --console-address ":9001" http://172.16.0.67:9000/data http://172.16.0.68:9000/data
    environment:
      TZ: Asia/Shanghai
      MINIO_ROOT_USER: ruoyi
      MINIO_ROOT_PASSWORD: ruoyi123
      MINIO_COMPRESS: "off"
    volumes:
      - /docker/minio/data1:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    network_mode: "host"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  # MinIO节点2 (机器68)
  minio2:
    image: minio/minio:RELEASE.2025-04-22T22-12-26Z
    container_name: minio2
    command: server --address ":9000" --console-address ":9001" http://172.16.0.67:9000/data http://172.16.0.68:9000/data
    environment:
      TZ: Asia/Shanghai
      MINIO_ROOT_USER: ruoyi
      MINIO_ROOT_PASSWORD: ruoyi123
      MINIO_COMPRESS: "off"
    volumes:
      - /docker/minio/data2:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    network_mode: "host"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3
```

**⚠️ 注意**：使用 host 模式时，两台机器不能同时使用相同的端口，需要调整端口映射。

**方案2：使用 Docker Bridge 网络（需要配置跨主机网络）**

如果使用 Docker Bridge 网络，需要配置 Docker Swarm 或使用第三方网络插件（如 Weave、Calico）。

---

#### 第二步：在机器67部署 MinIO 节点1

```bash
# 1. 创建数据目录
mkdir -p /docker/minio/data1

# 2. 进入配置文件目录
cd /path/to/部署文档/生产环境双机部署方案/配置文件/

# 3. 启动 MinIO 节点1（只启动 minio1 服务）
docker-compose -f docker-compose-minio-cluster.yml up -d minio1

# 4. 检查服务状态
docker ps | grep minio
curl http://127.0.0.1:9000/minio/health/live
```

---

#### 第三步：在机器68部署 MinIO 节点2

```bash
# 1. 创建数据目录
mkdir -p /docker/minio/data2

# 2. 进入配置文件目录
cd /path/to/部署文档/生产环境双机部署方案/配置文件/

# 3. 启动 MinIO 节点2（只启动 minio2 服务）
docker-compose -f docker-compose-minio-cluster.yml up -d minio2

# 4. 检查服务状态
docker ps | grep minio
curl http://127.0.0.1:9000/minio/health/live
```

---

#### 第四步：验证集群状态

```bash
# 安装 MinIO 客户端（mc）
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

# 配置集群别名
mc alias set minio-cluster http://172.16.0.67:9000 ruoyi ruoyi123

# 查看集群信息
mc admin info minio-cluster

# 查看集群状态
mc admin heal minio-cluster --dry-run
```

**正常输出应该显示两个节点都正常：**

```
●  minio1:9000
   Uptime: 1h
   Version: RELEASE.2025-04-22T22-12-26Z
   ...

●  minio2:9000
   Uptime: 1h
   Version: RELEASE.2025-04-22T22-12-26Z
   ...
```

---

#### 第五步：配置应用连接

**修改后端配置**，连接到 MinIO 集群：

```yaml
# application.yml
oss:
  endpoint: http://172.16.0.67:9000  # 可以连接到任意节点
  accessKey: ruoyi
  secretKey: ruoyi123
  bucketName: ruoyi
```

**或者使用 Nginx 负载均衡**：

```nginx
upstream minio_backend {
    server 172.16.0.67:9000 weight=1 max_fails=3 fail_timeout=30s;
    server 172.16.0.68:9000 weight=1 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    listen 9000;
    server_name minio.example.com;
    
    location / {
        proxy_pass http://minio_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

---

## 🔄 方案B：MinIO 主从同步配置（简单方案）

### 配置步骤

#### 第一步：在机器67部署主 MinIO

```bash
# 使用单机模式部署
docker run -d \
  --name minio-master \
  -p 9000:9000 \
  -p 9001:9001 \
  -e TZ=Asia/Shanghai \
  -e MINIO_ROOT_USER=ruoyi \
  -e MINIO_ROOT_PASSWORD=ruoyi123 \
  -e MINIO_COMPRESS=off \
  -v /docker/minio/data:/data \
  minio/minio:RELEASE.2025-04-22T22-12-26Z \
  server --address ":9000" --console-address ":9001" /data
```

---

#### 第二步：在机器68部署从 MinIO

```bash
# 使用单机模式部署
docker run -d \
  --name minio-slave \
  -p 9000:9000 \
  -p 9001:9001 \
  -e TZ=Asia/Shanghai \
  -e MINIO_ROOT_USER=ruoyi \
  -e MINIO_ROOT_PASSWORD=ruoyi123 \
  -e MINIO_COMPRESS=off \
  -v /docker/minio/data:/data \
  minio/minio:RELEASE.2025-04-22T22-12-26Z \
  server --address ":9000" --console-address ":9001" /data
```

---

#### 第三步：配置同步脚本

在机器68上创建同步脚本：

```bash
# 创建同步脚本
cat > /opt/minio-sync.sh <<'EOF'
#!/bin/bash

# 安装 MinIO 客户端（如果未安装）
if ! command -v mc &> /dev/null; then
    wget -q https://dl.min.io/client/mc/release/linux-amd64/mc -O /usr/local/bin/mc
    chmod +x /usr/local/bin/mc
fi

# 配置别名
mc alias set minio-master http://172.16.0.67:9000 ruoyi ruoyi123
mc alias set minio-slave http://172.16.0.68:9000 ruoyi ruoyi123

# 执行同步（watch 模式：实时监控并同步）
mc mirror --watch --remove minio-master/ruoyi minio-slave/ruoyi
EOF

chmod +x /opt/minio-sync.sh
```

---

#### 第四步：配置定时同步（可选，如果不用 watch 模式）

```bash
# 创建定时同步脚本（每5分钟同步一次）
cat > /opt/minio-sync-cron.sh <<'EOF'
#!/bin/bash

# 安装 MinIO 客户端（如果未安装）
if ! command -v mc &> /dev/null; then
    wget -q https://dl.min.io/client/mc/release/linux-amd64/mc -O /usr/local/bin/mc
    chmod +x /usr/local/bin/mc
fi

# 配置别名
mc alias set minio-master http://172.16.0.67:9000 ruoyi ruoyi123
mc alias set minio-slave http://172.16.0.68:9000 ruoyi ruoyi123

# 执行同步
mc mirror --remove minio-master/ruoyi minio-slave/ruoyi
EOF

chmod +x /opt/minio-sync-cron.sh

# 添加到 crontab（每5分钟同步一次）
(crontab -l 2>/dev/null; echo "*/5 * * * * /opt/minio-sync-cron.sh >> /var/log/minio-sync.log 2>&1") | crontab -
```

---

#### 第五步：启动同步服务

```bash
# 使用 systemd 管理同步服务
cat > /etc/systemd/system/minio-sync.service <<'EOF'
[Unit]
Description=MinIO Sync Service
After=network.target

[Service]
Type=simple
ExecStart=/opt/minio-sync.sh
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# 启动服务
systemctl daemon-reload
systemctl enable minio-sync
systemctl start minio-sync

# 查看服务状态
systemctl status minio-sync
```

---

## ✅ 配置验证

### 验证集群模式（方案A）

```bash
# 1. 检查集群节点状态
mc admin info minio-cluster

# 2. 测试上传文件
echo "test" > test.txt
mc cp test.txt minio-cluster/ruoyi/

# 3. 检查文件是否在两个节点都存在
mc ls minio-cluster/ruoyi/

# 4. 模拟节点故障（停止一个节点）
docker stop minio1

# 5. 验证集群是否仍可用
mc ls minio-cluster/ruoyi/  # 应该仍然可以访问
```

---

### 验证主从同步（方案B）

```bash
# 1. 在主节点上传文件
mc alias set minio-master http://172.16.0.67:9000 ruoyi ruoyi123
echo "test" > test.txt
mc cp test.txt minio-master/ruoyi/

# 2. 等待同步（watch 模式立即同步，定时同步需要等待）
sleep 10

# 3. 检查从节点是否有文件
mc alias set minio-slave http://172.16.0.68:9000 ruoyi ruoyi123
mc ls minio-slave/ruoyi/

# 4. 检查同步日志
tail -f /var/log/minio-sync.log
# 或
journalctl -u minio-sync -f
```

---

## 📊 方案对比

| 特性 | 方案A：集群模式 | 方案B：主从同步 |
|------|---------------|----------------|
| **配置复杂度** | 中等（需要网络配置） | 简单（独立部署） |
| **数据一致性** | ✅ 实时同步，强一致性 | ⚠️ 存在延迟（秒级到分钟级） |
| **高可用性** | ✅ 自动故障转移 | ⚠️ 需要手动切换 |
| **性能** | ✅ 分布式读写，负载均衡 | ⚠️ 主节点压力大 |
| **故障恢复** | ✅ 自动恢复 | ⚠️ 需要手动干预 |
| **适用场景** | 生产环境 | 开发/测试环境 |

---

## 🔍 常见问题排查

### 问题1：集群节点无法互相访问

**症状**：集群启动后，节点状态异常

**解决方法**：
```bash
# 1. 检查网络连通性
ping 172.16.0.67
ping 172.16.0.68
telnet 172.16.0.67 9000
telnet 172.16.0.68 9000

# 2. 检查防火墙
firewall-cmd --list-all | grep 9000

# 3. 检查 Docker 网络
docker network ls
docker network inspect minio-cluster
```

---

### 问题2：主从同步延迟大

**症状**：主节点上传文件后，从节点长时间看不到

**解决方法**：
```bash
# 1. 检查同步服务状态
systemctl status minio-sync

# 2. 检查同步日志
journalctl -u minio-sync -n 100

# 3. 手动触发同步
/opt/minio-sync-cron.sh

# 4. 如果使用 watch 模式，检查网络延迟
ping -c 10 172.16.0.67
```

---

### 问题3：集群节点数据不一致

**症状**：两个节点文件数量不一致

**解决方法**：
```bash
# 1. 检查集群健康状态
mc admin heal minio-cluster --dry-run

# 2. 执行修复
mc admin heal minio-cluster

# 3. 检查节点状态
mc admin info minio-cluster
```

---

## 📚 相关文档

- [生产环境双机部署方案.md](../生产环境双机部署方案.md) - 完整部署方案
- [MinIO性能优化配置](../中间件配置/minio-performance-optimization.md) - MinIO性能优化
- [MinIO安全配置](../设计文档/database/oss/minio-security-solution.md) - MinIO安全配置
- [配置文件/docker-compose-minio-cluster.yml](./配置文件/docker-compose-minio-cluster.yml) - 集群配置文件

---

## 🎯 推荐方案

**针对您的双机部署场景，推荐使用：**

### ✅ 方案A：MinIO 集群模式

**理由**：
1. **高可用**：任意节点故障，集群仍可用
2. **数据一致性**：实时同步，无延迟
3. **自动故障转移**：无需手动干预
4. **性能优秀**：分布式读写，负载均衡

**配置要点**：
- 使用 `host` 网络模式，避免 Docker 网络配置复杂
- 两台机器使用不同的端口映射（或使用 Nginx 负载均衡）
- 确保两台机器网络互通，防火墙开放相应端口

---

**📝 文档版本**: v1.0  
**🔄 最后更新**: 2025-01-27  
**✅ 适用场景**: 67/68双机部署 MinIO 高可用配置