LuBan.CloudStorage 2026.7.17.1

English | 中文

LuBan.CloudStorage

作者: yswenli | 联系邮箱: yswenli@outlook.com | 代码仓库: https://github.com/yswenli/luban-framework

一套接口，三大云商 —— 云存储、云存储、对象存储 无缝切换，代码零改动。

Related Projects: LuBan.Framework | LuBan.Common | LuBan.Orm | LuBan.VideoKit | LuBan.Web.Core

为什么选择 LuBan.CloudStorage？

项目要对接云存储，但选型总在变：今天用多云存储。每次切换都要重写上传下载逻辑？

LuBan.CloudStorage 通过统一的 ICloudStorageClient 接口屏蔽底层差异：

• 工厂模式 + 缓存实例，切换云商只需改一个枚举值
• 上传支持本地文件路径和 Stream 两种方式
• 下载区分大文件（流式）和小文件（字节数组）
• SAS 临时 URI 生成，安全分享私有资源
• FileHandler 集成文件验证、MD5 去重、视频缩略图自动生成
• UrlUpdateHelper + NewUrlAttribute 自动刷新过期的临时 URL

快速预览

// 从配置创建（自动读取 Nacos 中的 UploadOptions）
var client = CloundStorageClientFactory.Create();

// 或手动指定配置
var client = CloundStorageClientFactory.Create(new CloudStorageOptions
{
    SupplierType = EnumSupplierType.Aliyun,
    Id = "your-access-key-id",
    Key = "your-access-key-secret",
    ContainerName = "my-bucket",
    Endpoint = "https://oss-cn-shenzhen.aliyuncs.com"
});

// 上传文件
await client.UploadAsync("documents/report.pdf", localFilePath);
await client.UploadAsync("images/logo.png", imageStream);

// 下载文件
using var stream = await client.DownloadAsync("documents/report.pdf");
var bytes = await client.DownloadContentAsync("config/app.json");

// 生成临时访问链接
var sasUri = await client.GetSasUri("private/contract.pdf", DateTimeOffset.Now.AddHours(2));

// 判断文件是否存在
var exists = await client.ExistAsync("documents/report.pdf");

安装

dotnet add package LuBan.CloudStorage

功能概览

详细用法

配置示例

{
  "UploadOptions": {
    "Path": "upload/{yyyy}/{MM}/{dd}",
    "MaxSize": 134217728,
    "ExtensionNames": [".jpg", ".png", ".pdf", ".docx", ".mp4"],
    "EnableMd5": true,
    "EnableCloudStorage": true,
    "CloudStorageOptions": {
      "Id": "your-access-key-id",
      "Key": "your-access-key-secret",
      "SupplierType": 1,
      "ContainerName": "my-bucket",
      "Endpoint": "https://oss-cn-shenzhen.aliyuncs.com",
      "EnableDownloadCache": false,
      "EnableUploadCache": false
    }
  }
}

SupplierType 枚举值：1 = 云存储，2 = Azure，3 = 对象存储

FileHandler 文件上传

// 注入使用（IScoped 生命周期）
public class FileController
{
    readonly FileHandler _fileHandler;

    // 上传小文件（字节数组）
    var dbFile = await _fileHandler.HandleUploadFileAsync(
        domain: "https://api.example.com",
        rootPath: "/data",
        bytes: fileBytes,
        fileName: "report.pdf",
        length: fileBytes.Length,
        savePath: null);

    // 上传大文件（流式，自动计算 MD5）
    var dbFile = await _fileHandler.HandleUploadFileAsync(
        domain: "https://api.example.com",
        rootPath: "/data",
        stream: requestStream,
        fileName: "video.mp4",
        length: contentLength,
        savePath: null);

    // 上传视频（自动生成封面缩略图）
    var dbFile = await _fileHandler.HandleUploadVideoFileAsync(
        domain: "https://api.example.com",
        rootPath: "/data",
        videoContentStream: videoStream,
        fileName: "lecture.mp4",
        length: contentLength,
        savePath: null,
        posterTime: "00:00:03");
}

NewUrlAttribute 自动刷新 URL

public class CourseDto
{
    public string Title { get; set; }

    [NewUrl(60)]
    public string CoverUrl { get; set; }
}

// 使用时自动刷新过期的 SAS URL
await UrlUpdateHelper.UpdateUrlsAsync(courseDto);

使用提示

• CloundStorageClientFactory 内部使用 ConcurrentDictionary 缓存实例，相同供应商类型不会重复创建
• 启用 EnableUploadCache 会先写入本地再上传，适合网络不稳定的环境
• 启用 EnableDownloadCache 会将远程文件缓存到本地，后续请求直接读取本地文件
• FileHandler 内置 MD5 去重机制，相同文件不会重复上传
• 上传路径支持日期模板，如 upload/{yyyy}/{MM}/{dd} 会自动替换为当天日期
• FileHandler.ComputeMd5StreamAsync 采用流式计算 MD5，避免大文件占用过多内存

许可证

Copyright (c) yswenli. All rights reserved.