diff --git a/backend/infrastructure/minio/docs/setup-guide.md b/backend/infrastructure/minio/docs/setup-guide.md new file mode 100644 index 00000000..51ab7114 --- /dev/null +++ b/backend/infrastructure/minio/docs/setup-guide.md @@ -0,0 +1,201 @@ +# 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 ` | 创建存储桶 | +| `./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 配置 (可选) + +```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 +```