使用CloudFS连接本地磁盘与多种云存储

2026年03月10日周二 | 分类 Tech | 标签 opensource cloudfs

快速导航

多驱动支持，存储接入更自由
中间件机制，让文件系统能力可以组合
像操作文件系统一样操作云端资源
快速开始
适合哪些项目？
总结

在应用开发中，文件存储常常不是一个“简单上传下载”的问题。

你可能会遇到这些场景：

开发环境使用本地磁盘
生产环境切换到 S3 对象存储
企业内网需要接入 SMB / SFTP
用户希望挂载 WebDAV / OneDrive / Google Drive
文件分发依赖 GitHub Release
后续还要支持更多云盘或私有存储服务

如果每一种存储都单独适配，业务代码很快就会被各种 SDK、认证方式、路径规则和异常处理淹没。

CloudFS 正是为了解决这个问题而生。

CloudFS 是一个 Go 语言云存储抽象库，它将本地磁盘、多种云盘和常见存储协议统一到一套类似文件系统的接口中。开发者只需要面向 cloudfs.FS 编程，就可以完成常见文件操作。

例如：

 1// 列出目录文件
 2files, err := fs.List(ctx, "/")
 3
 4// 读取文件
 5r, err := fs.Open(ctx, "/file.txt")
 6
 7// 创建或上传文件
 8w, err := fs.Create(ctx, "/docs/hello.txt")
 9
10// 移动文件
11err = fs.Move(ctx, "/old.txt", "/archive")

底层到底是本地目录、S3、WebDAV、SFTP、SMB、Google Drive，还是 OneDrive，对于业务代码来说不再重要。

多驱动支持，存储接入更自由

CloudFS 已内置丰富的驱动支持：

Local：本地文件系统
FTP / SFTP：传统文件传输协议
S3：兼容 S3 的对象存储
SMB：企业内网文件共享
WebDAV：常见网盘与文件服务协议
Google Drive / OneDrive：主流云盘
GitHub / GitHub Release：适合文件分发场景
Upyun / Openlist / Foxel
115 / Quark

这意味着你可以用同一套业务逻辑连接不同存储后端。

典型使用方式包括：

开发环境使用 local
生产环境使用 s3
企业部署使用 smb 或 sftp
个人网盘场景支持 webdav、gdrive、onedrive
文件下载场景接入 github-release

直接创建驱动：

1fs, err := webdav.New(&webdav.Option{
2    Endpoint: "https://example.com/dav",
3    Username: "user",
4    Password: "pass",
5})

也可以通过统一工厂动态创建：

1fs, err := driver.New("webdav", map[string]any{
2    "endpoint": "https://example.com/dav",
3    "username": "user",
4    "password": "pass",
5})

如果配置已经是 JSON，还可以使用：

driver.NewFromString
driver.Exists
driver.VerifyOption

这对于配置化系统、后台管理平台、插件化应用非常友好。

中间件机制，让文件系统能力可以组合

CloudFS 不只是封装驱动，它还提供了可组合的中间件机制。

你可以像搭积木一样增强文件系统能力：

缓存中间件：缓存目录列表和文件信息，减少远端请求
限流中间件：控制访问频率，避免触发服务限制
压缩中间件：写入时压缩，读取时自动解压
加密中间件：支持文件内容、文件名、目录名加密
Hook 中间件：支持路径映射、文件过滤、自定义处理
Prefix 中间件：将某个目录前缀映射为文件系统根路径

示例：

1fs, err = cloudfs.New(
2    fs,
3    middleware.PrefixFS("/data"),
4    middleware.CacheFS(&middleware.CacheOption{}),
5)

像操作文件系统一样操作云端资源

CloudFS 的核心接口非常直观：

 1type FS interface {
 2    List(context.Context, string, ...ListOption) ([]FileInfo, error)
 3    Move(context.Context, string, string) error
 4    Copy(context.Context, string, string) error
 5    Rename(context.Context, string, string) error
 6    Remove(context.Context, string) error
 7    MakeDir(context.Context, string) error
 8    Stat(context.Context, string) (FileInfo, error)
 9    Open(context.Context, string) (File, error)
10    Create(context.Context, string) (FileWriter, error)
11    Close() error
12}

它保留了 Go 开发者熟悉的接口风格：

io.Reader
io.Seeker
io.Closer
io.WriteCloser
io/fs.FileInfo

因此，CloudFS 很容易和现有 Go 生态集成。

文件信息也在标准 io/fs.FileInfo 基础上增加了：

Path()：完整路径
Type()：文件类型
ExtraInfo()：驱动额外元数据

既保留标准语义，也给不同存储驱动留下扩展空间。

快速开始

安装 CloudFS：

1go get github.com/honmaple/cloudfs

只引入需要的驱动：

1import "github.com/honmaple/cloudfs/driver/webdav"

或者一次性注册全部内置驱动：

1import _ "github.com/honmaple/cloudfs/driver/all"

完整示例：

 1package main
 2
 3import (
 4    "context"
 5    "io"
 6    "strings"
 7
 8    "github.com/honmaple/cloudfs/driver/local"
 9)
10
11func main() {
12    fs, err := local.New(&local.Option{
13        Path: "/tmp/cloudfs",
14    })
15    if err != nil {
16        panic(err)
17    }
18    defer fs.Close()
19
20    ctx := context.Background()
21
22    _ = fs.MakeDir(ctx, "/docs")
23
24    w, _ := fs.Create(ctx, "/docs/hello.txt")
25    _, _ = io.Copy(w, strings.NewReader("hello cloudfs"))
26    _ = w.Close()
27
28    files, _ := fs.List(ctx, "/docs")
29    for _, file := range files {
30        println(file.Path(), file.Name(), file.Size())
31    }
32}