文件上传-Minio

官网

https://cool-js.com

插件开发文档

视频教程

1、插件开发

2、插件发布与使用

介绍

替换系统的文件上传服务，使用 MinIO 对象存储作为文件上传服务。

标识

调用插件的时候需要用到标识，标识是唯一的，不能重复，建议使用英文，不要使用中文，对应插件 plugin.json 中的 key 字段

标识：upload-minio（注：本插件是 hook 插件，调用时使用标识：upload）
Hook：upload （替换系统的 upload）

配置

{
  "endPoint": "必须，MinIO服务器地址（不要包含http://或https://前缀）",
  "port": "必须，MinIO API端口（通常是9000，而不是控制台端口9001）",
  "useSSL": "必须，是否使用SSL（true/false）",
  "accessKey": "必须，MinIO的accessKey",
  "secretKey": "必须，MinIO的secretKey",
  "bucket": "必须，MinIO的bucket名称",
  "region": "可选，MinIO的区域",
  "publicDomain": "可选，自定义公共访问域名",
  "expiry": "可选，预签名URL的过期时间（秒），默认3600",
  "s3ForcePathStyle": "可选，是否强制使用路径样式访问（true/false），默认为true"
}

重要说明：关于 MinIO 配置

MinIO 端口

MinIO 通常有两个端口：

API 端口 (默认为 9000)：用于 S3 API 请求，所有文件操作都必须使用此端口
Console 端口 (默认为 9001)：用于 MinIO 控制台 Web 界面

当配置此插件时，必须使用 API 端口（通常是 9000）而不是控制台端口（9001）。如果使用错误的端口，可能会遇到 S3 API Requests must be made to API port 错误。

endPoint 格式

在配置 endPoint 时，不要包含 http:// 或 https:// 前缀，只需要提供主机名或 IP 地址。例如：

正确：minio.example.com 或 192.168.1.100
错误：http://minio.example.com 或 https://192.168.1.100

如果您添加了协议前缀，可能会导致认证错误。

注意

前端签名直传用于浏览器安全限制，在传输的时候会有跨域访问的情况，因此需要到 MinIO 管理控制台，添加跨域规则，还需要配置对应的权限。

对于 MinIO 的跨域配置，可以通过设置 CORS 规则来实现：

mc admin config set myminio cors <<EOF
{
  "cors": {
    "enable": true,
    "allowedOrigins": ["*"],
    "allowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "allowedHeaders": ["*"],
    "exposeHeaders": ["ETag", "Content-Length", "Content-Type"],
    "maxAgeSeconds": 3600
  }
}
EOF

前端cl-upload组件中把拼接的key去掉，不然有错误

确保已经安装并配置 MinIO Client 工具，用于管理 MinIO 服务。

常见问题排查

错误: S3 API Requests must be made to API port
- 检查您是否使用了正确的 API 端口（通常是 9000）
- 确保 MinIO 服务器已启动并正常运行
- 使用 mc admin info myminio 验证服务器连接
错误: The request signature we calculated does not match the signature you provided
- 检查 accessKey 和 secretKey 是否正确
- 确保 endPoint 不包含 http:// 或 https:// 前缀
- 将 s3ForcePathStyle 设置为 true
- 确认 MinIO 服务器的时间与您的系统时间同步，时间差异过大会导致签名验证失败
- 使用最新版本的 MinIO 客户端库
跨域问题
- 确认已正确配置 CORS 设置
- 重启 MinIO 服务器以使 CORS 配置生效
文件访问权限
- 检查 Bucket 策略是否正确设置为公共可读
- 使用 mc policy set download myminio/yourbucket 快速设置为可下载

方法

下面是插件提供的一些方法

 /**
   * 获得上传模式
   */
  getMode(): Promise<Mode>;

  /**
   * 获得原始操作对象
   * @returns
   */
  getMetaFileObj(): Promise<any>;

  /**
   * 下载并上传
   * @param url
   * @param fileName 文件名
   */
  downAndUpload(url: string, fileName?: string): Promise<string>;

  /**
   * 指定Key(路径)上传，本地文件上传到存储服务
   * @param filePath 文件路径
   * @param key 路径一致会覆盖源文件
   */
  uploadWithKey(filePath, key): Promise<string>;

  /**
   * 上传文件
   * @param ctx
   * @param key 文件路径
   */
  upload(ctx): Promise<any>;

调用示例

@Inject()
pluginService: PluginService;

// 获得上传模式
await this.pluginService.invoke('upload', 'getMode');

更新日志

v1.0.2 (2024-05-15)
- 修复 "The request signature we calculated does not match the signature you provided" 错误
- 增加对错误 endPoint 格式的自动处理（去除协议前缀）
- 添加 s3ForcePathStyle 配置选项
- 增强日志和错误提示
v1.0.1 (2024-05-01)
- 修复 "S3 API Requests must be made to API port" 错误
- 添加 pathStyle 配置，使用路径样式访问
- 增强错误处理和日志记录
v1.0.0 (2024-03-31)
- 初始版本