TJC.Cyclops.CloudStorage 2026.2.4.1

Cyclops.CloudStorage

项目概述

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

核心功能模块

1. 统一云存储接口 (ICloudStorageClient)

提供了统一的云存储操作接口，定义了文件上传、下载、删除等核心功能：

• 文件上传：支持从本地文件路径或流上传文件到云端
• 文件下载：支持下载文件流（适合大文件）和文件内容（适合小文件）
• 文件删除：支持删除云端文件
• SAS URI生成：支持生成具有时效性的文件访问链接
• 文件存在性检查：支持检查文件是否存在于云端存储
• 异步API：提供完整的异步操作支持，提高应用性能

2. 云存储客户端工厂 (CloundStorageClientFactory)

工厂类负责创建和管理云存储客户端实例，实现了单例缓存机制：

• 客户端创建：根据配置创建对应的云存储客户端
• 实例缓存：缓存已创建的客户端实例，提高性能
• 无参创建：支持从配置中心自动读取配置创建客户端
• 线程安全：使用锁机制确保线程安全

3. 云存储类型枚举 (EnumSupplierType)

定义了支持的云存储服务类型：

• 阿里云：支持阿里云OSS服务
• 微软Azure：支持Azure Blob Storage服务
• MinIO：支持开源对象存储MinIO服务

4. 云存储配置 (CloudStorageOptions)

提供了详细的云存储配置选项：

• 基本认证信息：包含ID、Key等认证凭证
• 端点配置：指定云存储服务的访问端点
• 容器/存储桶配置：指定存储容器名称
• 性能配置：支持超时时间、错误重试次数等性能调优选项
• 缓存配置：支持上传/下载缓存配置

技术栈

• 开发框架：.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 - 公共功能库
  • Cyclops.Orm - 数据访问层
  • Cyclops.VideoKit - 视频处理工具包

环境依赖要求

• .NET 8.0 SDK 或更高版本
• 引用的Cyclops.Common、Cyclops.Orm和Cyclops.VideoKit项目
• 对应云存储服务的访问凭证和权限

安装与配置

安装方式

可以通过以下方式安装Cyclops.CloudStorage包：

1. NuGet包管理器：

   Install-Package TJC.Cyclops.CloudStorage
   

2. .NET CLI：

   dotnet add package TJC.Cyclops.CloudStorage
   

配置方式

使用Cyclops.CloudStorage需要进行以下配置：

1. 通过代码配置

// 创建云存储配置
var cloudStorageOptions = new CloudStorageOptions
{
    Id = "your-access-key-id",          // 访问密钥ID
    Key = "your-access-key-secret",     // 访问密钥Secret
    SupplierType = EnumSupplierType.Aliyun, // 选择云存储类型
    ContainerName = "your-bucket-name",   // 存储桶名称
    Endpoint = "your-endpoint",          // 服务端点
    TimeOut = 60,                         // 超时时间（秒）
    MaxErrorRetry = 3                     // 最大错误重试次数
};

// 使用工厂创建客户端
var storageClient = CloundStorageClientFactory.Create(cloudStorageOptions);

2. 通过配置文件配置

通过Nacos配置中心配置UploadOptions中的CloudStorageOptions部分。

核心功能代码示例

1. 创建云存储客户端

// 方式一：使用配置对象创建
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. 上传文件

// 从文件路径上传
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 (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);
}

4. 删除文件

// 删除远程文件
bool success = await client.DeleteAsync("remote-file.jpg");

5. 获取文件SAS URI

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

6. 检查文件是否存在

// 检查文件是否存在
bool exists = await client.ExistAsync("remote-file.jpg");

支持的云存储服务

1. 阿里云OSS

配置示例

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

2. 微软Azure Blob Storage

配置示例

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

3. MinIO

配置示例

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

性能优化建议

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

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

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

   options.TimeOut = 300;  // 5分钟
   

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

   options.MaxErrorRetry = 5;
   

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

使用注意事项

1. 凭证安全：请妥善保管云存储访问凭证，避免硬编码到代码中，推荐使用配置中心或环境变量

2. 权限管理：确保配置的访问凭证具有足够的权限执行相应操作

3. 错误处理：所有操作都应添加适当的错误处理逻辑，特别是网络相关操作

4. 连接关闭：使用完流后，确保正确关闭，避免资源泄漏

5. SAS URI安全：SAS URI具有时效性，请根据实际需要设置合适的过期时间

6. 容器创建：确保指定的容器/存储桶已创建，否则可能会导致操作失败

7. 路径格式：云端文件路径应使用斜杠(/)分隔，避免使用反斜杠(\)

贡献者

• yswenli

许可证

保留所有权利