jurong_circle_black/MIGRATION-GUIDE.md

# 文件迁移到 MinIO 指南

本指南将帮助您将现有的本地静态文件迁移到 MinIO 对象存储。

## 迁移前准备

### 1. 确保 MinIO 配置正确

确保 `.env` 文件中的 MinIO 配置正确：

```env
MINIO_ENDPOINT=your-minio-server
MINIO_PORT=9000
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key
MINIO_USE_SSL=false
MINIO_PUBLIC_URL=https://minio.yourdomain.com
```

### 2. 确保存储桶已创建

确保以下存储桶在 MinIO 中已存在：
- `avatars` - 用户头像
- `products` - 产品图片
- `documents` - 文档文件

### 3. 备份数据库

**重要：在开始迁移前，请务必备份数据库！**

```bash
mysqldump -u username -p database_name > backup_before_migration.sql
```

## 执行迁移

### 1. 运行迁移脚本

```bash
cd jurong_circle_black
node migrate-to-minio.js
```

### 2. 监控迁移过程

脚本会显示详细的迁移进度：
- 扫描本地文件
- 逐个上传到 MinIO
- 更新数据库中的文件路径引用
- 生成迁移报告

## 迁移后验证

### 1. 检查迁移报告

查看生成的 `migration-report.json` 文件：

```json
{
  "migrationDate": "2024-01-15T10:30:00.000Z",
  "totalFiles": 150,
  "successCount": 148,
  "failedCount": 2,
  "migratedFiles": [...],
  "failedFiles": [...]
}
```

### 2. 验证文件访问

- 检查用户头像是否正常显示
- 检查产品图片是否正常显示
- 检查文档下载是否正常

### 3. 验证数据库更新

检查数据库中的文件路径是否已更新：

```sql
-- 检查用户头像路径
SELECT id, username, avatar FROM users WHERE avatar LIKE 'https://minio%' LIMIT 10;

-- 检查产品图片路径
SELECT id, name, image_url FROM products WHERE image_url LIKE 'https://minio%' LIMIT 10;
```

## 文件组织结构

迁移后，文件将按以下结构组织：

```
MinIO 存储桶/
├── avatars/
│   ├── 2024/
│   │   ├── 01/
│   │   │   ├── 15/
│   │   │   │   ├── 1640995200000_a1b2c3d4.jpg
│   │   │   │   └── 1640995300000_b2c3d4e5.png
│   │   │   └── 16/
│   │   └── 02/
│   └── 2023/
├── products/
│   ├── 2024/
│   │   ├── 01/
│   │   │   ├── 15/
│   │   │   └── 16/
│   │   └── 02/
│   └── 2023/
└── documents/
    ├── 2024/
    └── 2023/
```

## 故障排除

### 常见问题

1. **连接 MinIO 失败**
   - 检查 MinIO 服务是否运行
   - 验证网络连接
   - 确认访问密钥正确

2. **存储桶不存在**
   - 在 MinIO 控制台创建所需的存储桶
   - 确保存储桶名称与配置一致

3. **权限问题**
   - 确保 MinIO 用户有读写权限
   - 检查存储桶策略设置

4. **部分文件迁移失败**
   - 查看迁移报告中的失败文件列表
   - 检查文件是否损坏或被占用
   - 手动重新上传失败的文件

### 回滚方案

如果迁移出现问题，可以通过以下步骤回滚：

1. **恢复数据库备份**
   ```bash
   mysql -u username -p database_name < backup_before_migration.sql
   ```

2. **重新配置文件上传路径**
   - 修改 `routes/upload.js` 使用本地存储
   - 确保 `uploads` 目录存在且有正确权限

## 迁移完成后的清理

### 1. 删除本地文件（可选）

**警告：只有在确认迁移成功且系统运行正常后才执行此操作！**

```bash
# 备份 uploads 目录
mv uploads uploads_backup_$(date +%Y%m%d)

# 或者直接删除（谨慎操作）
# rm -rf uploads
```

### 2. 更新部署脚本

更新生产环境的部署脚本，移除对 `uploads` 目录的依赖。

### 3. 更新备份策略

确保备份策略包含 MinIO 数据的备份。

## 注意事项

1. **迁移时间**：根据文件数量和大小，迁移可能需要较长时间
2. **网络稳定性**：确保网络连接稳定，避免迁移中断
3. **存储空间**：确保 MinIO 有足够的存储空间
4. **并发限制**：脚本已添加延迟避免过快请求，如需调整可修改代码
5. **文件路径**：迁移后的文件路径将包含日期文件夹结构

## 技术支持

如果在迁移过程中遇到问题，请：

1. 查看控制台输出的错误信息
2. 检查 `migration-report.json` 中的详细信息
3. 确保 MinIO 服务正常运行
4. 验证网络连接和权限设置