From 6bf23fc8d38601f69d54b5de1970038bc4f12007 Mon Sep 17 00:00:00 2001
From: hailin <hailin.zhao@gdzx.xyz>
Date: Sun, 7 Dec 2025 21:14:30 -0800
Subject: [PATCH] docs(minio): add setup guide documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../infrastructure/minio/docs/setup-guide.md  | 201 ++++++++++++++++++
 1 file changed, 201 insertions(+)
 create mode 100644 backend/infrastructure/minio/docs/setup-guide.md

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 <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 配置 (可选)
+
+```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
+```