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配置正确，可以正常使用！"，说明配置成功。
|