fenghuo/packages/storage/MINIO_CONFIGURATION_GUIDE.md

MinIO S3存储配置指南

概述

本指南提供了在本项目中正确配置MinIO S3存储的详细说明，包括解决501错误的方案。

✅ 已验证的配置

基于测试验证，以下配置可以正常工作：

环境变量配置

# 存储类型
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   # 最大并发上传数

代码配置示例

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错误信息不够详细
• 解决方案: 提供更友好的错误消息和诊断建议

🧪 测试验证

运行以下测试脚本验证配置：

# 基础连接测试
node test-minio-config.js

# 完整场景测试（如果支持ES模块）
node test-real-upload.js

# 特定问题调试
node debug-exact-error.js

📋 最佳实践

1. MinIO服务配置

确保MinIO服务正确启动：

# 检查MinIO状态
docker ps | grep minio

# 查看MinIO日志
docker logs <minio-container-name>

# 重启MinIO（如果需要）
docker restart <minio-container-name>

2. 存储桶设置

# 使用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连接

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);
	});

监控上传过程

启用调试日志：

DEBUG=tus-node-server:stores:s3store npm start

📚 相关资源

• MinIO文档
• AWS S3 API参考
• TUS协议规范

🆘 故障排除检查清单

• MinIO服务运行正常
• 存储桶test123存在
• 访问密钥配置正确
• useTags: false已设置
• forcePathStyle: true已设置
• 端口9000可访问
• 上传目录权限正确
• 代码已重新编译

---

🎯 快速验证

运行此命令进行快速验证：

cd /opt/projects/nice/packages/storage
npm run build && node test-minio-config.js

如果看到"✅ 测试完成：MinIO配置正确，可以正常使用！"，说明配置成功。