# MinIO 对象存储配置指南

## 文件结构

```
backend/infrastructure/minio/
├── docker-compose.yml      # MinIO Docker 配置
├── deploy.sh               # 部署管理脚本
├── .env.example            # 环境变量示例
├── README.md               # 使用文档
├── docs/
│   └── setup-guide.md      # 本文档
└── nginx/
    ├── minio.szaiai.com.conf   # Nginx 反向代理配置
    └── install.sh              # Nginx 配置安装脚本
```

## 功能特性

### 1. MinIO 服务

| 端口 | 用途 |
|------|------|
| 9000 | S3 API |
| 9001 | Web Console |

自动初始化默认存储桶：
- `avatars` - 用户头像 (公开读取)
- `documents` - 用户文档 (私有)
- `resources` - 应用资源 (公开读取)
- `backups` - 备份文件 (私有)

### 2. deploy.sh 命令

| 命令 | 说明 |
|------|------|
| `./deploy.sh up` | 启动服务 |
| `./deploy.sh down` | 停止服务 |
| `./deploy.sh restart` | 重启服务 |
| `./deploy.sh status` | 查看状态 |
| `./deploy.sh health` | 健康检查 |
| `./deploy.sh logs` | 查看日志 |
| `./deploy.sh logs -f` | 实时日志 |
| `./deploy.sh create-bucket <name>` | 创建存储桶 |
| `./deploy.sh list-buckets` | 列出存储桶 |
| `./deploy.sh info` | 服务器信息 |
| `./deploy.sh backup` | 备份配置 |

### 3. Nginx 配置

用于与 Kong 部署在同一服务器 (Server A: 192.168.1.100)

| 域名 | 用途 |
|------|------|
| `minio.szaiai.com` | S3 API 端点 |
| `console.minio.szaiai.com` | 管理控制台 |
| `cdn.szaiai.com` | 静态资源 CDN (带缓存) |

## 部署步骤

### 步骤 1: 配置环境变量

```bash
cd backend/infrastructure/minio

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件，修改 MINIO_ROOT_PASSWORD
vim .env
```

**必须修改的配置：**
```env
MINIO_ROOT_PASSWORD=your_secure_password_here
```

### 步骤 2: 创建数据目录

```bash
# 创建数据存储目录
sudo mkdir -p /data/minio

# 设置权限 (MinIO 容器使用 UID 1000)
sudo chown -R 1000:1000 /data/minio
```

### 步骤 3: 启动服务

```bash
./deploy.sh up
```

### 步骤 4: 验证服务

```bash
# 查看运行状态
./deploy.sh status

# 健康检查
./deploy.sh health

# 列出存储桶
./deploy.sh list-buckets
```

### 步骤 5: 安装 Nginx 反向代理 (可选)

> **何时需要 Nginx？**
> - 需要通过域名访问 (如 minio.szaiai.com)
> - 需要 HTTPS 加密
> - 需要 CDN 缓存静态资源
>
> 如果仅内网直接访问 MinIO (通过 IP:9000/9001)，可跳过此步骤。

```bash
cd nginx

# 第一步：安装 Nginx 配置文件
sudo ./install.sh

# 第二步：配置 SSL 证书 (需要先完成第一步)
sudo ./install.sh --ssl
```

## 网络拓扑

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Server A (192.168.1.100) - Gateway & Storage                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Internet                                                                   │
│      │                                                                      │
│      ▼                                                                      │
│  ┌─────────────┐                                                            │
│  │   Nginx     │ :80/:443                                                   │
│  │  (SSL终止)  │                                                            │
│  └──────┬──────┘                                                            │
│         │                                                                   │
│    ┌────┴────┬──────────────┐                                               │
│    │         │              │                                               │
│    ▼         ▼              ▼                                               │
│ ┌──────┐ ┌──────┐    ┌───────────┐                                          │
│ │ Kong │ │MinIO │    │  MinIO    │                                          │
│ │:8000 │ │:9000 │    │  Console  │                                          │
│ └──────┘ │(API) │    │  :9001    │                                          │
│          └──┬───┘    └───────────┘                                          │
│             │                                                               │
│             ▼                                                               │
│     ┌───────────────┐                                                       │
│     │  /data/minio  │                                                       │
│     │   (Volume)    │                                                       │
│     └───────────────┘                                                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## 后端服务集成

在后端服务的 `.env` 中添加以下配置：

```env
# MinIO Configuration
MINIO_ENDPOINT=192.168.1.100
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=admin
MINIO_SECRET_KEY=your_minio_password
MINIO_BUCKET_AVATARS=avatars
MINIO_BUCKET_DOCUMENTS=documents
MINIO_PUBLIC_URL=https://cdn.szaiai.com
```

## 常见问题

### Q: MinIO 无法启动？

```bash
# 检查日志
./deploy.sh logs

# 检查数据目录权限
ls -la /data/minio
sudo chown -R 1000:1000 /data/minio
```

### Q: 无法连接到 MinIO？

```bash
# 检查端口是否监听
netstat -tlnp | grep 9000

# 检查防火墙
sudo ufw status
sudo ufw allow 9000
sudo ufw allow 9001
```

### Q: 上传文件失败？

```bash
# 检查磁盘空间
df -h /data/minio

# 检查存储桶是否存在
./deploy.sh list-buckets
```