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