引入minio

2025-09-02 16:50:35 +08:00
parent e4d4bc5b6a
commit e5ace37c68
12 changed files with 28231 additions and 144 deletions
--- a/MIGRATION-GUIDE.md
+++ b/MIGRATION-GUIDE.md
@@ -0,0 +1,186 @@
+# 文件迁移到 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. 验证网络连接和权限设置