驱动文档

本文档汇总 CloudFS 内置驱动的注册名、用途、参数、示例和已知限制。

总览

Local

注册名：local

用途：访问本机目录。

参数：

未导出的运行时字段：

• Bookmark：仅用于 macOS 特定场景
• DirPerm：内部目录权限，当前默认 0755

示例：

1fs, err := driver.New("local", map[string]any{
2	"path": "/data/files",
3})

注意事项：

• path 必须是绝对路径
• filepath.Clean(path) 之后必须和原始值一致，否则会返回 fs.ErrInvalid
• Windows 下会自动处理斜杠转换

FTP

注册名：ftp

参数：

示例：

1fs, err := driver.New("ftp", map[string]any{
2	"host": "127.0.0.1",
3	"username": "demo",
4	"password": "secret",
5})

注意事项：

• 建立连接时使用 10 秒超时
• Copy() 走库内通用复制逻辑，本质是“下载后再上传”

SFTP

注册名：sftp

参数：

示例：

1fs, err := driver.New("sftp", map[string]any{
2	"host": "sftp.example.com",
3	"username": "demo",
4	"private_key": privateKeyPEM,
5})

注意事项：

• HostKey 校验当前使用 ssh.InsecureIgnoreHostKey()
• private_key 需要是可被 ssh.ParsePrivateKey() 解析的 PEM 内容

S3

注册名：s3

参数：

示例：

1fs, err := driver.New("s3", map[string]any{
2	"endpoint": "https://s3.example.com",
3	"bucket": "files",
4	"region": "us-east-1",
5	"access_key": "key",
6	"secret_key": "secret",
7	"force_path_style": true,
8	"list_version": "v2",
9})

注意事项：

• 目录是通过以 / 结尾的空对象模拟的
• Copy() 文件使用服务端复制，目录使用递归复制
• Stat() 会先按文件查询，再退化为目录前缀判断

SMB

注册名：smb

参数：

示例：

1fs, err := driver.New("smb", map[string]any{
2	"host": "192.168.1.10",
3	"username": "demo",
4	"password": "secret",
5	"share_name": "public",
6})

注意事项：

• 驱动内部自动应用 TrimPrefixFS(..., "/")，因为 SMB 不接受以 / 开头的底层路径
• MakeDir() 使用权限 0700

WebDAV

注册名：webdav

参数：

示例：

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

注意事项：

• 当前实现会把 DirPerm 强制设为 0755
• Stat() 会把 WebDAV 的 403/404 映射到 os.ErrPermission / os.ErrNotExist

Foxel

注册名：foxel

参数：

示例：

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

注意事项：

• 驱动启动时会自动登录并缓存 Bearer Token
• 请求遇到 401 时会自动重登一次
• List() 内部分页大小固定为 500

OpenList

注册名：openlist

参数：

示例：

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

List() 支持的附加参数：

示例：

1files, err := fs.List(ctx, "/secret", cloudfs.ListOption{
2	"password": "dir-pass",
3})

注意事项：

• 实现依赖 OpenList/Alist 风格接口
• 构造时会立即登录

UpYun

注册名：upyun

参数：

示例：

1fs, err := driver.New("upyun", map[string]any{
2	"bucket": "demo-space",
3	"operator": "demo",
4	"password": "secret",
5})

注意事项：

• Close() 被显式实现为空操作，避免 SDK 内部 panic

Google Drive

注册名：gdrive

参数：

示例：

1fs, err := driver.New("gdrive", map[string]any{
2	"credentials_file": "/path/to/service-account.json",
3	"root_id": "root",
4	"supports_all_drives": true,
5})

注意事项：

• 三种认证方式按顺序择一：credentials、credentials_file、access_token
• 如果设置 shared_drive_id 且未设置 root_id，根目录会自动使用 shared_drive_id
• 读取 Google Docs/Sheets/Slides 等原生文档时，必须提供 export_mime_type
• Create() 对已存在同名文件会执行覆盖更新

OneDrive

注册名：onedrive

参数：

示例：

1fs, err := driver.New("onedrive", map[string]any{
2	"access_token": token,
3	"drive_id": "b!xxxx",
4})

注意事项：

• drive_id 优先于 user_id
• Copy() 走 Graph 异步复制接口，可能返回 202 并等待轮询完成

115 网盘

注册名：pan115

参数：

示例：

1fs, err := driver.New("pan115", map[string]any{
2	"cookie": cookie,
3})

List() 支持的附加参数：

注意事项：

• 驱动内部会校验 Cookie 并执行登录检查
• 返回值中的 ExtraInfo() 常含 id、pick_code
• Create() 未实现，因此是只读下载驱动
• 返回的 FS 还会被 quark.WrapFS(d, 180) 包装，用于把“路径接口”映射成上游的 ID 风格访问

Quark

注册名：quark

参数：

示例：

1fs, err := driver.New("quark", map[string]any{
2	"cookie": cookie,
3})

注意事项：

• 原始驱动接口主要基于文件 ID 和父目录 ID，不是普通路径
• New() 返回时会自动调用 WrapFS(d, 60)，把外部路径转换为上游 ID 访问
• Copy() 和 Create() 未实现，所以适合只读/下载型场景

GitHub

注册名：github

参数：

示例：

1fs, err := driver.New("github", map[string]any{
2	"owner": "honmaple",
3	"repo": "cloudfs",
4	"ref": "main",
5})

路径模型：

• 固定 repo 与 ref 时：/README.md
• 固定 repo，但未固定 ref 且启用 show_branch/show_tag 时：/main/README.md
• 都未固定时：/cloudfs/main/README.md

注意事项：

• 只支持浏览和下载，不支持写操作
• 分支和标签名中若包含 /，对外会使用 URL 编码

GitHub Release

注册名：github-release

参数：

示例：

1fs, err := driver.New("github-release", map[string]any{
2	"owner": "cli",
3	"repo": "cli",
4	"release": "GitHub CLI 2.0.0",
5})

路径模型：

• 固定 repo 和 release 时：/gh_2.0.0_checksums.txt
• 未固定 release 时：/GitHub%20CLI%202.0.0/gh_2.0.0_checksums.txt

注意事项：

• Release 目录层级使用 Release 名称，不是 tag
• 只支持浏览和下载 Release 资产

Mirror

注册名：mirror

参数：

示例：

1fs, err := driver.New("mirror", map[string]any{
2	"endpoint": "https://mirrors.example.com",
3	"format": "tuna",
4})

注意事项：

• 这是只读驱动
• Stat() 依赖 HTTP HEAD 返回的 Content-Type、Content-Length、Last-Modified
• 如果镜像站目录页结构不同，可能需要扩展解析函数

驱动选择建议

• 本地或挂载目录优先使用 local
• 标准 NAS/服务器文件共享可选 sftp、smb、webdav
• 对象存储优先使用 s3
• 需要 SaaS 网盘集成时可选 gdrive、onedrive
• 仅读场景可考虑 github、github-release、mirror、pan115、quark