Bitzsoft.Integrations.FileStorage.Nas 1.0.0-alpha.7

Bitzsoft.Integrations.FileStorage.Nas

NAS / 本地文件系统存储实现。

功能特性

• 完整实现 IFileStore 接口：覆盖所有文件与存储桶操作
• 扩展接口 INasFileStore：NAS 文件存储服务标识接口，支持未来扩展
• 下载 URL 生成：通过 Domain + 路径拼接生成下载地址
• 存储桶管理：创建、删除、判断存储桶是否存在（映射为 BasePath 下的子目录）
• 文件元数据：保存文件时支持设置 ContentType
• 配置提供器模式：通过 INasConfigProvider 抽象配置获取，支持静态配置或动态配置中心
• IHttpClientFactory 集成：通过 Microsoft.Extensions.Http 管理 HTTP 连接
• 无第三方 SDK 依赖：基于 System.IO 原生文件操作
• 兼容所有 NAS 供应商：威联通、群晖、绿联、华为等，依赖操作系统 SMB/NFS 挂载

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.FileStorage.Nas

PackageReference

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

配置

appsettings.json

{
  "Nas": {
    "BasePath": "/mnt/nas",
    "DefaultBucketName": "default",
    "Domain": "http://cdn.example.com",
    "HttpClientName": "FileStorage",
    "DownloadUrlExpiration": 43200,
    "UploadUrlExpiration": 3600
  }
}

注册服务

使用 DI 扩展方法（推荐）

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

var services = new ServiceCollection();

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

// 一行注册 NAS 文件存储服务
services.AddBitzsoftNasFileStorage(options =>
{
    options.BasePath = "/mnt/nas";
    options.DefaultBucketName = "default";
    options.Domain = "http://cdn.example.com";
});

从 IConfiguration 绑定配置

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

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

var services = new ServiceCollection();

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

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

// 从配置节绑定 NasOptions
services.AddSingleton<INasConfigProvider>(sp =>
{
    var options = configuration.GetSection("Nas").Get<NasOptions>();
    return new NasConfigProvider(options);
});

services.AddSingleton<INasFileStore, NasFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<INasFileStore>());

使用 IOptions 模式

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Nas;
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<NasOptions>(
    configuration.GetSection("Nas"));

// NasConfigProvider 内部通过 IOptions<NasOptions> 获取配置
services.AddSingleton<INasConfigProvider, NasConfigProvider>();
services.AddSingleton<INasFileStore, NasFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<INasFileStore>());

使用示例

保存文件并获取下载链接

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Nas;

public class ReportService
{
    private readonly INasFileStore _fileStore;

    public ReportService(INasFileStore 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 拉取文件到 NAS

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Nas;

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.Nas;

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

核心类型一览

部署场景

本实现基于 System.IO 原生文件操作，不依赖任何第三方 SDK 或网络协议。文件的存储位置完全由 BasePath 配置决定，支持以下两种典型场景。

场景一：本地文件系统（小项目 / 开发环境）

将文件存储在项目发布目录内或服务器本地路径，适用于单机部署、开发测试或小型应用。

目录结构：

/var/www/myapp/              ← 应用发布目录
├── app.dll
├── appsettings.json
└── data/                    ← BasePath 指向此目录
    ├── invoices/            ← 存储桶（子目录）
    │   ├── 2024-001.pdf
    │   └── 2024-002.pdf
    └── avatars/             ← 存储桶（子目录）
        └── user-123.jpg

配置：

{
  "Nas": {
    "BasePath": "/var/www/myapp/data",
    "DefaultBucketName": "uploads",
    "Domain": "https://myapp.example.com/data"
  }
}

生成的下载 URL 示例：https://myapp.example.com/data/invoices/2024-001.pdf

需要在 Web 服务器（如 Nginx）中配置 /data 路径的静态文件服务，将请求映射到 BasePath 目录。

场景二：NAS 挂载（生产环境 / 多实例）

将文件存储在 NAS 设备的挂载路径，适用于多实例部署、容器环境或需要集中管理文件的场景。支持所有主流 NAS 供应商。

前提条件：

运维人员需要先将 NAS 共享目录挂载到服务器本地路径：

# 威联通 QNAP（SMB 挂载）
mount -t cifs //192.168.1.100/share /mnt/nas -o username=admin,password=xxx

# 群晖 Synology（NFS 挂载）
mount -t nfs 192.168.1.101:/volume1/data /mnt/nas

# 绿联 UGREEN（SMB 挂载）
mount -t cifs //192.168.1.102/public /mnt/nas -o username=admin,password=xxx

# 华为家庭存储（NFS 挂载）
mount -t nfs 192.168.1.103:/share /mnt/nas

# Windows 共享目录（SMB/CIFS）
net use Z: \\192.168.1.100\share /user:admin xxx

目录结构：

/mnt/nas/                    ← BasePath 指向 NAS 挂载点
├── invoices/                ← 存储桶
├── contracts/               ← 存储桶
└── media/                   ← 存储桶

配置：

{
  "Nas": {
    "BasePath": "/mnt/nas",
    "DefaultBucketName": "default",
    "Domain": "https://files.mycompany.com"
  }
}

应用层面无需关心底层 NAS 协议（SMB/NFS/CIFS），只需操作挂载后的本地路径。NAS 供应商的兼容性由操作系统保证。

场景对比

依赖

• Bitzsoft.Integrations.Compatibility，基础工具库
• Bitzsoft.Integrations.FileStorage，多云文件存储抽象层
• 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.Kingsoft，金山云 KS3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Qiniu，七牛云 Kodo 文件存储实现
• Bitzsoft.Integrations.FileStorage.Upyun，又拍云文件存储实现
• Bitzsoft.Integrations.FileStorage.All，全部云存储实现聚合包