Bitzsoft.Integrations.FileStorage.Kingsoft 1.0.0-alpha.3

Bitzsoft.Integrations.FileStorage.Kingsoft

金山云 KS3 文件存储实现。

功能特性

• 完整实现 IFileStore 接口：覆盖所有文件与存储桶操作
• 扩展接口 IKingsoftKs3FileStore：金山云 KS3 文件存储服务标识接口，支持未来扩展
• 预签名 URL：生成带过期时间的下载地址和上传地址
• 存储桶管理：创建、删除、判断存储桶是否存在
• 文件元数据：保存文件时支持设置 ContentType
• 配置提供器模式：通过 IKingsoftKs3ConfigProvider 抽象配置获取，支持静态配置或动态配置中心
• IHttpClientFactory 集成：通过 Microsoft.Extensions.Http 管理 HTTP 连接

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.FileStorage.Kingsoft

PackageReference

<PackageReference Include="Bitzsoft.Integrations.FileStorage.Kingsoft" Version="1.0.0" />

配置

appsettings.json

{
  "KingsoftKs3": {
    "Endpoint": "ks3-cn-beijing.ksyuncs.com",
    "AccessKeyId": "your-access-key-id",
    "SecretAccessKey": "your-secret-access-key",
    "DefaultBucketName": "my-app-bucket",
    "HttpClientName": "FileStorage",
    "UploadUrlExpiration": 3600,
    "DownloadUrlExpiration": 43200
  }
}

注册服务

使用 DI 扩展方法（推荐）

using Bitzsoft.Integrations.FileStorage.Kingsoft;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 注册 HttpClient 工厂
services.AddHttpClient("FileStorage");

// 一行注册金山云 KS3 文件存储服务
services.AddBitzsoftKingsoftKs3FileStorage(options =>
{
    options.Endpoint = "ks3-cn-beijing.ksyuncs.com";
    options.AccessKeyId = "your-access-key-id";
    options.SecretAccessKey = "your-secret-access-key";
    options.DefaultBucketName = "my-app-bucket";
});

从 IConfiguration 绑定配置

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Kingsoft;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();

// 注册 HttpClient 工厂（KingsoftKs3FileStore 通过 IHttpClientFactory 创建 HTTP 客户端）
services.AddHttpClient("FileStorage");

// 注册处理器工厂
services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 从配置节绑定 KingsoftKs3Options
services.AddSingleton<IKingsoftKs3ConfigProvider>(sp =>
{
    var options = configuration.GetSection("KingsoftKs3").Get<KingsoftKs3Options>();
    return new KingsoftKs3ConfigProvider(options);
});

services.AddSingleton<IKingsoftKs3FileStore, KingsoftKs3FileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IKingsoftKs3FileStore>());

使用 IOptions 模式

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Kingsoft;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

services.AddHttpClient("FileStorage");

services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 配置选项
services.Configure<KingsoftKs3Options>(
    configuration.GetSection("KingsoftKs3"));

// KingsoftKs3ConfigProvider 内部通过 IOptions<KingsoftKs3Options> 获取配置
services.AddSingleton<IKingsoftKs3ConfigProvider, KingsoftKs3ConfigProvider>();
services.AddSingleton<IKingsoftKs3FileStore, KingsoftKs3FileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IKingsoftKs3FileStore>());

使用示例

保存文件并获取下载链接

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Kingsoft;

public class ReportService
{
    private readonly IKingsoftKs3FileStore _fileStore;

    public ReportService(IKingsoftKs3FileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<string> UploadReportAsync(Stream pdfStream, string reportName)
    {
        // 保存 PDF 到默认存储桶
        var result = await _fileStore.SaveFileAsync(
            pdfStream, $"{reportName}.pdf");

        // 生成 12 小时有效的下载链接
        var downloadUrl = await _fileStore.GenerateDownloadUrlAsync(
            result.FilePath);

        return downloadUrl;
    }
}

通过 IFileStore 抽象使用

using Bitzsoft.Integrations.FileStorage;

public class ContractService
{
    private readonly IFileStore _fileStore;

    public ContractService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> UploadContractAsync(
        Stream contractStream, string contractId)
    {
        var args = new SaveFileArgs($"{contractId}.pdf", contractStream)
        {
            ContentType = "application/pdf"
        };

        return await _fileStore.SaveFileAsync(args);
    }
}

从远程 URL 拉取文件到金山云 KS3

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Kingsoft;

public class MediaSyncService
{
    private readonly IFileStore _fileStore;

    public MediaSyncService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> SyncExternalImageAsync(string imageUrl, string saveAs)
    {
        var args = new SaveFileByUrlArgs(saveAs, imageUrl)
        {
            BucketName = "media-assets"
        };

        return await _fileStore.SaveFileByUrlAsync(args);
    }
}

复制与移动文件

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Kingsoft;

public class FileOrganizer
{
    private readonly IFileStore _fileStore;

    public FileOrganizer(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task ArchiveFileAsync(string sourceFile, string archivePath)
    {
        // 复制文件到归档路径
        await _fileStore.CopyFileAsync(sourceFile, archivePath);

        // 删除原文件（等同于 MoveFileAsync）
        await _fileStore.DeleteFileAsync(sourceFile);
    }

    public async Task MoveToBucketAsync(
        string fileName, string sourceBucket, string destBucket)
    {
        var sourceArgs = new FileStorageArgs(fileName) { BucketName = sourceBucket };
        var destArgs = new FileStorageArgs(fileName) { BucketName = destBucket };

        await _fileStore.MoveFileAsync(sourceArgs, destArgs);
    }
}

核心类型一览

依赖

• Bitzsoft.Integrations.Compatibility -- 基础工具库
• Bitzsoft.Integrations.FileStorage -- 多云文件存储抽象层
• AWSSDK.S3 -- AWS S3 SDK（金山云 KS3 兼容 S3 协议）
• Microsoft.Extensions.Http -- HttpClient 工厂支持

相关包

• Bitzsoft.Integrations.FileStorage -- 多云文件存储抽象层
• Bitzsoft.Integrations.FileStorage.Minio -- MinIO 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aliyun -- 阿里云 OSS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Azure -- Azure Blob Storage 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aws -- AWS S3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Tencent -- 腾讯云 COS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Huawei -- 华为云 OBS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Qiniu -- 七牛云 Kodo 文件存储实现
• Bitzsoft.Integrations.FileStorage.Upyun -- 又拍云文件存储实现
• Bitzsoft.Integrations.FileStorage.Nas -- NAS / 本地文件系统存储实现
• Bitzsoft.Integrations.FileStorage.All -- 全部云存储实现聚合包