docs(minio): add setup guide documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
ea6ede598d
commit
6bf23fc8d3
|
|
@ -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
|
||||
```
|
||||
Loading…
Reference in New Issue