227 lines
4.6 KiB
Markdown
227 lines
4.6 KiB
Markdown
# MinIO S3存储配置指南
|
||
|
||
## 概述
|
||
|
||
本指南提供了在本项目中正确配置MinIO S3存储的详细说明，包括解决501错误的方案。
|
||
|
||
## ✅ 已验证的配置
|
||
|
||
基于测试验证，以下配置可以正常工作：
|
||
|
||
### 环境变量配置
|
||
|
||
```bash
|
||
# 存储类型
|
||
STORAGE_TYPE=s3
|
||
|
||
# 上传目录
|
||
UPLOAD_DIR=/opt/projects/nice/uploads
|
||
|
||
# MinIO S3配置
|
||
S3_ENDPOINT=http://localhost:9000
|
||
S3_REGION=us-east-1
|
||
S3_BUCKET=test123
|
||
S3_ACCESS_KEY_ID=7Nt7OyHkwIoo3zvSKdnc
|
||
S3_SECRET_ACCESS_KEY=EZ0cyrjJAsabTLNSqWcU47LURMppBW2kka3LuXzb
|
||
S3_FORCE_PATH_STYLE=true
|
||
|
||
# 可选配置
|
||
S3_PART_SIZE=8388608 # 8MB分片大小
|
||
S3_MAX_CONCURRENT_UPLOADS=6 # 最大并发上传数
|
||
```
|
||
|
||
### 代码配置示例
|
||
|
||
```typescript
|
||
const storeOptions = {
|
||
partSize: 8388608, // 8MB
|
||
maxConcurrentPartUploads: 6,
|
||
expirationPeriodInMilliseconds: 60 * 60 * 24 * 1000, // 24小时
|
||
useTags: false, // 🔑 重要：禁用标签功能
|
||
s3ClientConfig: {
|
||
bucket: 'test123',
|
||
region: 'us-east-1',
|
||
credentials: {
|
||
accessKeyId: '7Nt7OyHkwIoo3zvSKdnc',
|
||
secretAccessKey: 'EZ0cyrjJAsabTLNSqWcU47LURMppBW2kka3LuXzb',
|
||
},
|
||
endpoint: 'http://localhost:9000',
|
||
forcePathStyle: true, // 🔑 MinIO必需
|
||
},
|
||
};
|
||
```
|
||
|
||
## 🔧 已实施的修复
|
||
|
||
### 1. 标签功能修复
|
||
|
||
- **问题**: S3Store默认启用标签功能，但MinIO可能不完全支持
|
||
- **解决方案**: 修改代码确保`useTags: false`时不传递`Tagging`参数
|
||
- **影响的方法**:
|
||
- `saveMetadata()`
|
||
- `completeMetadata()`
|
||
- `uploadIncompletePart()`
|
||
|
||
### 2. 重试机制
|
||
|
||
- **问题**: 间歇性的501错误可能是网络或服务器临时问题
|
||
- **解决方案**: 为`uploadPart()`方法添加指数退避重试机制
|
||
- **配置**: 最多重试3次，间隔2^n秒
|
||
|
||
### 3. 错误增强
|
||
|
||
- **问题**: 原始501错误信息不够详细
|
||
- **解决方案**: 提供更友好的错误消息和诊断建议
|
||
|
||
## 🧪 测试验证
|
||
|
||
运行以下测试脚本验证配置：
|
||
|
||
```bash
|
||
# 基础连接测试
|
||
node test-minio-config.js
|
||
|
||
# 完整场景测试（如果支持ES模块）
|
||
node test-real-upload.js
|
||
|
||
# 特定问题调试
|
||
node debug-exact-error.js
|
||
```
|
||
|
||
## 📋 最佳实践
|
||
|
||
### 1. MinIO服务配置
|
||
|
||
确保MinIO服务正确启动：
|
||
|
||
```bash
|
||
# 检查MinIO状态
|
||
docker ps | grep minio
|
||
|
||
# 查看MinIO日志
|
||
docker logs <minio-container-name>
|
||
|
||
# 重启MinIO（如果需要）
|
||
docker restart <minio-container-name>
|
||
```
|
||
|
||
### 2. 存储桶设置
|
||
|
||
```bash
|
||
# 使用MinIO客户端创建存储桶
|
||
mc mb minio/test123
|
||
|
||
# 设置存储桶策略（如果需要公共访问）
|
||
mc policy set public minio/test123
|
||
```
|
||
|
||
### 3. 网络配置
|
||
|
||
- 确保端口9000可访问
|
||
- 检查防火墙设置
|
||
- 验证DNS解析（如果使用域名）
|
||
|
||
## ❌ 常见问题
|
||
|
||
### 501 Not Implemented错误
|
||
|
||
**可能原因**:
|
||
|
||
1. MinIO版本过旧，不支持某些S3 API
|
||
2. 对象标签功能不受支持
|
||
3. 特定的HTTP头或参数不被识别
|
||
4. 网络连接问题
|
||
|
||
**解决方案**:
|
||
|
||
1. ✅ 确保`useTags: false`
|
||
2. ✅ 使用重试机制
|
||
3. 检查MinIO版本并升级
|
||
4. 验证网络连接
|
||
|
||
### XML解析错误
|
||
|
||
**症状**: `char 'U' is not expected.:1:1`
|
||
|
||
**原因**: MinIO返回HTML错误页面而非XML响应
|
||
|
||
**解决方案**:
|
||
|
||
1. 检查MinIO服务状态
|
||
2. 验证访问密钥和权限
|
||
3. 确认存储桶存在
|
||
|
||
### 权限错误
|
||
|
||
**解决方案**:
|
||
|
||
1. 验证访问密钥ID和密钥
|
||
2. 检查存储桶策略
|
||
3. 确认用户权限
|
||
|
||
## 🔍 诊断工具
|
||
|
||
### 检查MinIO连接
|
||
|
||
```javascript
|
||
const { S3 } = require('@aws-sdk/client-s3');
|
||
|
||
const s3Client = new S3({
|
||
endpoint: 'http://localhost:9000',
|
||
region: 'us-east-1',
|
||
credentials: {
|
||
accessKeyId: 'your-access-key',
|
||
secretAccessKey: 'your-secret-key',
|
||
},
|
||
forcePathStyle: true,
|
||
});
|
||
|
||
// 测试连接
|
||
s3Client
|
||
.listBuckets()
|
||
.then((result) => {
|
||
console.log('连接成功:', result.Buckets);
|
||
})
|
||
.catch((error) => {
|
||
console.error('连接失败:', error);
|
||
});
|
||
```
|
||
|
||
### 监控上传过程
|
||
|
||
启用调试日志：
|
||
|
||
```bash
|
||
DEBUG=tus-node-server:stores:s3store npm start
|
||
```
|
||
|
||
## 📚 相关资源
|
||
|
||
- [MinIO文档](https://docs.min.io/)
|
||
- [AWS S3 API参考](https://docs.aws.amazon.com/s3/latest/API/)
|
||
- [TUS协议规范](https://tus.io/protocols/resumable-upload.html)
|
||
|
||
## 🆘 故障排除检查清单
|
||
|
||
- [ ] MinIO服务运行正常
|
||
- [ ] 存储桶`test123`存在
|
||
- [ ] 访问密钥配置正确
|
||
- [ ] `useTags: false`已设置
|
||
- [ ] `forcePathStyle: true`已设置
|
||
- [ ] 端口9000可访问
|
||
- [ ] 上传目录权限正确
|
||
- [ ] 代码已重新编译
|
||
|
||
---
|
||
|
||
## 🎯 快速验证
|
||
|
||
运行此命令进行快速验证：
|
||
|
||
```bash
|
||
cd /opt/projects/nice/packages/storage
|
||
npm run build && node test-minio-config.js
|
||
```
|
||
|
||
如果看到"✅ 测试完成：MinIO配置正确，可以正常使用！"，说明配置成功。
|