TJC.Cyclops.CloudStorage 2026.4.29.2

Cyclops.CloudStorage

☁️ 统一云存储解决方案 ☁️

Cyclops.CloudStorage 是企服版框架中的云存储SDK，提供了统一的云存储访问接口，实现了阿里云、微软Azure和MinIO云存储服务的无缝集成。该项目采用工厂模式设计，使开发者能够使用统一的API访问不同的云存储服务，极大地简化了多平台云存储的开发工作。

🌟 核心特性

• 统一云存储接口：提供 ICloudStorageClient 接口，统一不同云存储服务的调用方式
• 多云存储支持：支持阿里云OSS、微软Azure Blob Storage、MinIO等多种云存储服务
• 工厂模式：通过 CloundStorageClientFactory 统一创建和管理云存储客户端实例
• 完整的文件操作：支持文件上传、下载、删除、检查存在性等核心功能
• SAS URI生成：支持生成具有时效性的文件访问链接
• 异步API：提供完整的异步操作支持，提高应用性能
• 安全配置：支持HTTPS、超时设置、错误重试等安全和可靠性配置
• 缓存支持：支持上传/下载缓存，提高性能

🛠️ 技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • Aliyun.OSS.SDK.NetCore (2.14.1) - 阿里云OSS SDK
  • Azure.Storage.Blobs (12.26.0) - Azure Blob Storage SDK
  • Minio (7.0.0) - MinIO客户端SDK
  • Cyclops.Common - 公共功能库

📦 安装

dotnet add package TJC.Cyclops.CloudStorage

🚀 快速开始

1. 创建云存储客户端

using Cyclops.CloudStorage;

// 方式一：使用配置对象创建
var options = new CloudStorageOptions
{
    Id = "aliyun-access-key-id",
    Key = "aliyun-access-key-secret",
    SupplierType = EnumSupplierType.Aliyun,
    ContainerName = "my-bucket",
    Endpoint = "oss-cn-hangzhou.aliyuncs.com"
};
var client = CloundStorageClientFactory.Create(options);

// 方式二：从配置中心自动读取配置
var client = CloundStorageClientFactory.Create();

2. 上传文件

using Cyclops.CloudStorage;

// 从文件路径上传
await client.UploadAsync("remote-file.jpg", "local-file.jpg");

// 从流上传
using (var stream = new FileStream("local-file.jpg", FileMode.Open))
{
    await client.UploadAsync("remote-file.jpg", stream);
}

3. 下载文件

using Cyclops.CloudStorage;

// 下载文件流（适合大文件）
using (var stream = await client.DownloadAsync("remote-file.jpg"))
{
    if (stream != null)
    {
        using (var fileStream = new FileStream("downloaded-file.jpg", FileMode.Create))
        {
            await stream.CopyToAsync(fileStream);
        }
    }
}

// 下载文件内容（适合小文件）
var fileContent = await client.DownloadContentAsync("remote-file.jpg");
if (fileContent != null)
{
    await File.WriteAllBytesAsync("downloaded-file.jpg", fileContent);
}

📖 使用指南

删除文件

using Cyclops.CloudStorage;

// 删除远程文件
bool success = await client.DeleteAsync("remote-file.jpg");
if (success)
{
    Console.WriteLine("文件删除成功");
}
else
{
    Console.WriteLine("文件删除失败");
}

获取文件SAS URI

using Cyclops.CloudStorage;

// 生成24小时内有效的SAS访问链接
var sasUri = await client.GetSasUri("remote-file.jpg", DateTimeOffset.UtcNow.AddHours(24));
Console.WriteLine($"临时访问链接: {sasUri}");
// sasUri可用于临时访问文件，无需凭证

检查文件是否存在

using Cyclops.CloudStorage;

// 检查文件是否存在
bool exists = await client.ExistAsync("remote-file.jpg");
if (exists)
{
    Console.WriteLine("文件存在");
}
else
{
    Console.WriteLine("文件不存在");
}

🔧 配置说明

阿里云OSS配置

using Cyclops.CloudStorage;

var options = new CloudStorageOptions
{
    Id = "LTAI5t666666666666666",      // AccessKeyId
    Key = "66666666666666666666666666666666",  // AccessKeySecret
    SupplierType = EnumSupplierType.Aliyun,
    ContainerName = "my-bucket",
    Endpoint = "oss-cn-hangzhou.aliyuncs.com"
};

微软Azure Blob Storage配置

using Cyclops.CloudStorage;

var options = new CloudStorageOptions
{
    Id = "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=66666666666666666666666666666666==;EndpointSuffix=core.windows.net",
    Key = "",  // Azure使用连接字符串，Key可为空
    SupplierType = EnumSupplierType.Azure,
    ContainerName = "my-container",
    Endpoint = "https://myaccount.blob.core.windows.net"
};

MinIO配置

using Cyclops.CloudStorage;

var options = new CloudStorageOptions
{
    Id = "minioadmin",      // AccessKey
    Key = "minioadmin",     // SecretKey
    SupplierType = EnumSupplierType.MinIO,
    ContainerName = "my-bucket",
    Endpoint = "http://localhost:9000"
};

📋 支持的云存储服务

• 阿里云OSS：稳定可靠的对象存储服务，适合各种规模的应用
• 微软Azure Blob Storage：全球分布的云存储服务，适合国际化应用
• MinIO：开源的对象存储服务器，适合私有部署场景

⚠️ 使用注意事项

1. 凭证安全：请妥善保管云存储访问凭证，避免硬编码到代码中，推荐使用配置中心或环境变量
2. 权限管理：确保配置的访问凭证具有足够的权限执行相应操作
3. 错误处理：所有操作都应添加适当的错误处理逻辑，特别是网络相关操作
4. 连接关闭：使用完流后，确保正确关闭，避免资源泄漏
5. SAS URI安全：SAS URI具有时效性，请根据实际需要设置合适的过期时间
6. 容器创建：确保指定的容器/存储桶已创建，否则可能会导致操作失败
7. 路径格式：云端文件路径应使用斜杠(/)分隔，避免使用反斜杠()
8. 文件大小：注意云存储服务对单个文件大小的限制，大文件可能需要特殊处理

🚀 性能优化建议

1. 缓存配置：根据需要启用上传/下载缓存，提高性能

   options.EnableDownloadCache = true;
   options.EnableUploadCache = true;
   

2. 超时设置：对于大文件传输，适当调整超时时间

   options.TimeOut = 300;  // 5分钟
   

3. 错误重试：设置合适的重试次数，提高稳定性

   options.MaxErrorRetry = 5;
   

4. 文件大小处理：大文件优先使用流操作，小文件可以使用字节数组

🤝 贡献

我们欢迎社区贡献！如果您有任何想法或建议，欢迎提交 Issue 或 Pull Request。

📄 许可证

MIT License

Cyclops.CloudStorage - 让云存储访问变得简单统一，为您的应用提供可靠的存储解决方案！✨