参考资料
https://github.com/junkai-li/NetCoreKevin

https://gitee.com/netkevin-li/NetCoreKevin

kevin.FileStorage

kevin.FileStorage

概述

kevin.FileStorage 是一个用于文件存储和处理的模块，旨在为应用程序提供统一的文件操作接口，支持阿里云对象存储（OSS）和腾讯云对象存储（COS）。该模块通过抽象接口 IFileStorage 定义了文件上传、下载、删除和获取临时访问URL等核心功能，使得开发者可以轻松地在不同云存储服务之间切换，而无需修改上层业务逻辑。该模块适用于需要云存储支持的应用程序，特别是在文件管理和分发场景中。

系统架构

kevin.FileStorage 模块采用接口驱动的设计模式，通过依赖注入的方式将具体的云存储实现集成到应用程序中。核心组件包括：

• IFileStorage：定义文件存储操作的接口。
• AliCloudStorage：阿里云OSS的具体实现。
• TencentCloudStorage：腾讯云COS的具体实现。
• ServiceCollectionExtensions：提供依赖注入配置的扩展方法。

以下是模块的架构图，展示了组件之间的关系：

核心组件

IFileStorage 接口

IFileStorage 接口定义了文件存储的核心操作，包括：

• FileUpload：上传文件到云存储。
• FileDownload：从云存储下载文件到本地。
• FileDelete：删除云存储中的文件。
• GetFileTempUrl：生成文件的临时访问URL，支持设置过期时间。

AliCloudStorage

AliCloudStorage 类实现了 IFileStorage 接口，使用阿里云OSS SDK（Aliyun.OSS）进行文件操作。它通过 IOptionsMonitor<FileStorageSetting> 注入配置信息，包括访问节点、账户凭据和存储桶名称。

TencentCloudStorage

TencentCloudStorage 类同样实现了 IFileStorage 接口，使用腾讯云COS SDK（COSXML）进行文件操作。它也通过 IOptionsMonitor<FileStorageSetting> 获取配置信息，包括应用ID、区域、凭据和存储桶名称。

配置模型

• 阿里云配置：包括 Endpoint（访问节点）、AccessKeyId（账户ID）、AccessKeySecret（账户密钥）和 BucketName（存储桶名称）。
• 腾讯云配置：包括 AppId（应用ID）、Region（区域）、SecretId（密钥ID）、SecretKey（密钥值）和 BucketName（存储桶名称）。

服务集成

通过 ServiceCollectionExtensions 类提供的扩展方法，可以将文件存储服务注册到依赖注入容器中。例如：

• AddAliCloudStorage：注册阿里云存储服务。
• AddTencentCloudStorage：注册腾讯云存储服务。

实现模式

kevin.FileStorage 模块采用以下实现模式：

• 接口抽象：通过 IFileStorage 接口实现存储服务的抽象，方便扩展新的云存储提供商。
• 依赖注入：使用 Microsoft.Extensions.DependencyInjection 进行服务配置和注入，增强模块的灵活性和可测试性。
• 配置管理：通过 IOptionsMonitor 动态读取配置，支持运行时配置更新。

示例代码

配置服务

// 在 Startup.cs 或 Program.cs 中配置阿里云存储
services.AddAliCloudStorage(options =>
{
    options.Endpoint = "oss-cn-hangzhou.aliyuncs.com";
    options.AccessKeyId = "your-access-key-id";
    options.AccessKeySecret = "your-access-key-secret";
    options.BucketName = "your-bucket-name";
});

// 配置腾讯云存储
services.AddTencentCloudStorage(options =>
{
    options.AppId = "your-app-id";
    options.Region = "ap-guangzhou";
    options.SecretId = "your-secret-id";
    options.SecretKey = "your-secret-key";
    options.BucketName = "your-bucket-name";
});

文件操作

// 注入 IFileStorage 服务
public class FileService
{
    private readonly IFileStorage _fileStorage;

    public FileService(IFileStorage fileStorage)
    {
        _fileStorage = fileStorage;
    }

    // 上传文件
    public bool UploadFile(string localPath, string remotePath)
    {
        return _fileStorage.FileUpload(localPath, remotePath, "custom-file-name.txt");
    }

    // 下载文件
    public bool DownloadFile(string remotePath, string localPath)
    {
        return _fileStorage.FileDownload(remotePath, localPath);
    }

    // 删除文件
    public bool DeleteFile(string remotePath)
    {
        return _fileStorage.FileDelete(remotePath);
    }

    // 获取临时访问URL
    public string GetTempUrl(string remotePath)
    {
        return _fileStorage.GetFileTempUrl(remotePath, TimeSpan.FromHours(1), "custom-download-name.txt");
    }
}

数据流

文件操作的数据流如下图所示，展示了从应用程序到云存储服务的请求和响应过程：

集成点

kevin.FileStorage 模块通过以下方式与外部系统集成：

• 阿里云OSS：使用 Aliyun.OSS SDK 与阿里云对象存储服务交互。
• 腾讯云COS：使用 COSXML SDK 与腾讯云对象存储服务交互。
• 依赖注入：通过 Microsoft.Extensions.DependencyInjection 与应用程序的依赖注入容器集成。

性能分析

性能特性

• 文件上传/下载：受限于网络带宽和文件大小，建议对大文件使用分块上传或下载以提高效率。
• 临时URL生成：生成临时访问URL的操作通常很快，但频繁调用可能增加服务器负担，建议缓存URL直到过期。

优化建议

1. 分块处理：对于大文件，建议实现分块上传和下载功能，以减少内存占用和提高传输效率。
2. 并行处理：对多个小文件的操作可以并行处理，以缩短总处理时间。
3. 缓存机制：缓存常用的文件或临时URL，减少对云存储服务的重复请求。
4. 异步操作：文件操作应尽量使用异步方式，避免阻塞主线程。

安全考虑

1. 凭据保护：存储账户的凭据（如 AccessKeySecret 和 SecretKey）应妥善保管，避免硬编码到代码中，建议使用环境变量或安全的配置管理工具。
2. 权限控制：为存储桶设置最小权限原则，仅允许必要的操作和访问范围。
3. 临时URL：通过设置合理的过期时间（如 GetFileTempUrl 中的 expiry 参数）限制文件的访问时长，防止未授权访问。
4. 数据加密：对敏感文件，建议在上传前进行客户端加密，或启用云存储服务的服务器端加密功能。

故障排查指南

• 文件上传失败：检查本地文件路径是否正确，网络连接是否稳定，以及存储桶是否有写入权限。
• 文件下载失败：确认远程文件路径是否正确，存储桶是否有读取权限，以及本地存储空间是否足够。
• 临时URL无效：检查URL是否已过期，或者文件是否已被删除或移动。
• 配置错误：验证配置参数（如 AccessKeyId、SecretKey 等）是否正确，确保存储桶名称和区域配置无误。

参考资料