vfs

package
v1.2.17 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package vfs 提供虚拟文件系统抽象层，支持本地文件系统和远程存储（WebDAV、SFTP等）

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CloseAll 

func CloseAll()

CloseAll 关闭所有注册的文件系统

func IsRemoteURL 

func IsRemoteURL(storeURL string) bool

IsRemoteURL 判断 URL 是否为远程存储

func List 

func List() []string

List 列出所有注册的文件系统

func Register 

func Register(key string, fs FileSystem)

Register 注册文件系统实例

func Unregister 

func Unregister(key string)

Unregister 注销文件系统实例

Types

type BackendType 

type BackendType int

BackendType 文件存储后端类型 

const (
	LocalDisk BackendType = 1 + iota
	SMB
	SFTP
	WebDAV
	S3
	FTP
)

func GetBackendType 

func GetBackendType(storeURL string) BackendType

GetBackendType 获取 URL 对应的后端类型

func (BackendType) String 

func (f BackendType) String() string

type DirEntry 

type DirEntry interface {
	fs.DirEntry
}

DirEntry 目录项接口，兼容 fs.DirEntry

func NewDirEntry 

func NewDirEntry(info FileInfo) DirEntry

NewDirEntry 创建新的 DirEntry

type FTPFS 

type FTPFS struct {
	// contains filtered or unexported fields
}

FTPFS FTP 文件系统实现

func NewFTPFS 

func NewFTPFS(urlStr string, opts ...Options) (*FTPFS, error)

NewFTPFS 创建 FTP 文件系统实例 urlStr 格式: ftp://user:pass@host:port/path 或 ftps://user:pass@host:port/path

func (*FTPFS) BaseURL 

func (f *FTPFS) BaseURL() string

BaseURL 返回基础 URL

func (*FTPFS) Close 

func (f *FTPFS) Close() error

Close 关闭连接

func (*FTPFS) Exists 

func (f *FTPFS) Exists(p string) (bool, error)

Exists 检查路径是否存在

func (*FTPFS) GetBasePath 

func (f *FTPFS) GetBasePath() string

GetBasePath 返回 FTP 基础路径

func (*FTPFS) IsDir 

func (f *FTPFS) IsDir(p string) (bool, error)

IsDir 检查是否为目录

func (*FTPFS) IsRemote 

func (f *FTPFS) IsRemote() bool

IsRemote 返回是否为远程文件系统

func (*FTPFS) JoinPath 

func (f *FTPFS) JoinPath(elem ...string) string

JoinPath 连接路径（使用 Unix 风格的路径分隔符）

func (*FTPFS) Open 

func (f *FTPFS) Open(p string) (File, error)

Open 打开文件用于读取

func (*FTPFS) OpenReaderAtSeeker 

func (f *FTPFS) OpenReaderAtSeeker(p string) (ReaderAtSeeker, error)

OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader FTP 不支持随机访问（ReadAt），统一下载到内存并缓存以避免重复下载

func (*FTPFS) ReadDir 

func (f *FTPFS) ReadDir(p string) ([]DirEntry, error)

ReadDir 读取目录

func (*FTPFS) ReadFile 

func (f *FTPFS) ReadFile(p string) ([]byte, error)

ReadFile 读取文件内容

func (*FTPFS) RelPath 

func (f *FTPFS) RelPath(basePath, targetPath string) (string, error)

RelPath 计算相对路径

func (*FTPFS) Stat 

func (f *FTPFS) Stat(p string) (FileInfo, error)

Stat 获取文件信息

func (*FTPFS) Type 

func (f *FTPFS) Type() BackendType

Type 返回后端类型

type File 

type File interface {
	io.Reader
	io.Closer
	io.Seeker

	// Stat 获取文件信息
	Stat() (FileInfo, error)

	// ReadAt 在指定偏移量处读取
	ReadAt(p []byte, off int64) (n int, err error)
}

File 文件接口，提供基本的文件读取操作

type FileCache 

type FileCache struct {
	// contains filtered or unexported fields
}

FileCache 文件缓存管理器 用于缓存远程文件系统读取的文件，减少网络请求

func NewFileCache 

func NewFileCache(cacheDir string, debug bool) *FileCache

NewFileCache 创建文件缓存管理器

func (*FileCache) Clear 

func (c *FileCache) Clear()

Clear 清空所有缓存

func (*FileCache) ClearOlderThan 

func (c *FileCache) ClearOlderThan(duration time.Duration)

ClearOlderThan 清除超过指定时间的缓存

func (*FileCache) Delete 

func (c *FileCache) Delete(path string)

Delete 删除缓存

func (*FileCache) Get 

func (c *FileCache) Get(path string) ([]byte, bool)

Get 从缓存获取文件内容 优先从内存缓存获取，然后从磁盘缓存获取

func (*FileCache) Set 

func (c *FileCache) Set(path string, data []byte)

Set 设置缓存

func (*FileCache) Size 

func (c *FileCache) Size() int

Size 返回缓存条目数量

type FileInfo 

type FileInfo interface {
	fs.FileInfo
}

FileInfo 文件信息接口，兼容 fs.FileInfo

func NewFileInfo 

func NewFileInfo(name string, size int64, mode fs.FileMode, modTime time.Time, isDir bool) FileInfo

NewFileInfo 创建新的 FileInfo

type FileSystem 

type FileSystem interface {
	// Open 打开文件用于读取
	Open(path string) (File, error)

	// Stat 获取文件或目录的信息
	Stat(path string) (FileInfo, error)

	// ReadDir 读取目录内容
	ReadDir(path string) ([]DirEntry, error)

	// ReadFile 读取整个文件内容
	ReadFile(path string) ([]byte, error)

	// Type 返回文件系统后端类型
	Type() BackendType

	// BaseURL 返回文件系统的基础URL或路径
	BaseURL() string

	// Close 关闭文件系统连接（对于远程文件系统）
	Close() error

	// IsRemote 返回是否为远程文件系统
	IsRemote() bool

	// JoinPath 连接路径，根据文件系统类型使用正确的分隔符
	JoinPath(elem ...string) string

	// RelPath 计算相对路径
	RelPath(basePath, targetPath string) (string, error)

	// Exists 检查路径是否存在
	Exists(path string) (bool, error)

	// IsDir 检查路径是否为目录
	IsDir(path string) (bool, error)

	// OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader
	// 这对于需要随机访问的压缩包格式很重要
	// 如果文件系统不支持 Seek，会将数据读取到内存中
	// 返回的 Reader 必须实现 io.Reader, io.ReaderAt, io.Seeker
	OpenReaderAtSeeker(path string) (ReaderAtSeeker, error)
}

FileSystem 虚拟文件系统接口 提供统一的文件系统操作，支持本地和远程存储

func Get 

func Get(key string) (FileSystem, bool)

Get 获取已注册的文件系统实例

func GetOrCreate 

func GetOrCreate(storeURL string, opts ...Options) (FileSystem, error)

GetOrCreate 获取或创建文件系统实例 如果已存在则返回现有实例，否则创建新实例并注册

func New 

func New(storeURL string, opts ...Options) (FileSystem, error)

New 根据 URL 创建对应的文件系统实例

type LocalFS 

type LocalFS struct {
	// contains filtered or unexported fields
}

LocalFS 本地文件系统实现

func NewLocalFS 

func NewLocalFS(basePath string, opts ...Options) (*LocalFS, error)

NewLocalFS 创建本地文件系统实例

func (*LocalFS) BaseURL 

func (l *LocalFS) BaseURL() string

BaseURL 返回基础路径

func (*LocalFS) Close 

func (l *LocalFS) Close() error

Close 关闭文件系统（本地文件系统无需关闭）

func (*LocalFS) Exists 

func (l *LocalFS) Exists(path string) (bool, error)

Exists 检查路径是否存在

func (*LocalFS) IsDir 

func (l *LocalFS) IsDir(path string) (bool, error)

IsDir 检查是否为目录

func (*LocalFS) IsRemote 

func (l *LocalFS) IsRemote() bool

IsRemote 返回是否为远程文件系统

func (*LocalFS) JoinPath 

func (l *LocalFS) JoinPath(elem ...string) string

JoinPath 连接路径

func (*LocalFS) Open 

func (l *LocalFS) Open(path string) (File, error)

Open 打开文件

func (*LocalFS) OpenReaderAtSeeker 

func (l *LocalFS) OpenReaderAtSeeker(path string) (ReaderAtSeeker, error)

OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader

func (*LocalFS) ReadDir 

func (l *LocalFS) ReadDir(path string) ([]DirEntry, error)

ReadDir 读取目录

func (*LocalFS) ReadFile 

func (l *LocalFS) ReadFile(path string) ([]byte, error)

ReadFile 读取文件内容

func (*LocalFS) RelPath 

func (l *LocalFS) RelPath(basePath, targetPath string) (string, error)

RelPath 计算相对路径

func (*LocalFS) Stat 

func (l *LocalFS) Stat(path string) (FileInfo, error)

Stat 获取文件信息

func (*LocalFS) Type 

func (l *LocalFS) Type() BackendType

Type 返回后端类型

type Options 

type Options struct {
	// CacheEnabled 是否启用文件缓存
	CacheEnabled bool

	// CacheDir 缓存目录路径
	CacheDir string

	// Timeout 连接超时（秒）
	Timeout int

	// Debug 是否启用调试日志
	Debug bool

	// UseRangeRequests 是否使用 HTTP Range 请求进行按需读取（默认 true）
	// 启用后，大文件将按需下载片段而不是完整下载
	UseRangeRequests bool
}

Options 文件系统配置选项

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions 返回默认配置选项

type RangeReaderAtSeeker 

type RangeReaderAtSeeker struct {
	// contains filtered or unexported fields
}

RangeReaderAtSeeker 基于 HTTP Range 请求的 ReaderAtSeeker 实现 支持按需下载文件片段，避免下载整个文件

func NewRangeReaderAtSeeker 

func NewRangeReaderAtSeeker(client *gowebdav.Client, path string, size int64, debug bool) *RangeReaderAtSeeker

NewRangeReaderAtSeeker 创建新的 RangeReaderAtSeeker

func (*RangeReaderAtSeeker) Read 

func (r *RangeReaderAtSeeker) Read(p []byte) (n int, err error)

Read 实现 io.Reader 接口

func (*RangeReaderAtSeeker) ReadAt 

func (r *RangeReaderAtSeeker) ReadAt(p []byte, off int64) (n int, err error)

ReadAt 实现 io.ReaderAt 接口

func (*RangeReaderAtSeeker) Seek 

func (r *RangeReaderAtSeeker) Seek(offset int64, whence int) (int64, error)

Seek 实现 io.Seeker 接口

type ReaderAtSeeker 

type ReaderAtSeeker interface {
	io.Reader
	io.ReaderAt
	io.Seeker
}

ReaderAtSeeker 接口，组合了 io.Reader, io.ReaderAt, io.Seeker 用于支持需要随机访问的压缩包格式

type S3FS 

type S3FS struct {
	// contains filtered or unexported fields
}

S3FS S3 文件系统实现

func NewS3FS 

func NewS3FS(urlStr string, opts ...Options) (*S3FS, error)

NewS3FS 创建 S3 文件系统实例 urlStr 格式: s3://accessKey:secretKey@endpoint/bucket/prefix

func (*S3FS) BaseURL 

func (s *S3FS) BaseURL() string

BaseURL 返回基础 URL

func (*S3FS) Close 

func (s *S3FS) Close() error

Close 关闭连接（S3 HTTP 客户端无状态，无需特殊处理）

func (*S3FS) Exists 

func (s *S3FS) Exists(p string) (bool, error)

Exists 检查路径是否存在

func (*S3FS) GetBasePath 

func (s *S3FS) GetBasePath() string

GetBasePath 返回 S3 基础路径（前缀）

func (*S3FS) IsDir 

func (s *S3FS) IsDir(p string) (bool, error)

IsDir 检查是否为目录（S3 中通过前缀模拟目录）

func (*S3FS) IsRemote 

func (s *S3FS) IsRemote() bool

IsRemote 返回是否为远程文件系统

func (*S3FS) JoinPath 

func (s *S3FS) JoinPath(elem ...string) string

JoinPath 连接路径（使用 / 分隔符）

func (*S3FS) Open 

func (s *S3FS) Open(p string) (File, error)

Open 打开文件用于读取

func (*S3FS) OpenReaderAtSeeker 

func (s *S3FS) OpenReaderAtSeeker(p string) (ReaderAtSeeker, error)

OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader 下载到内存并缓存，避免重复下载 两种策略： 小文件（<1MB）: 直接下载到内存+缓存 大文件: 也下载到内存+缓存（S3 Range 请求虽可行，但为保持简单先用全量下载+缓存，与 SMB 一致）

func (*S3FS) ReadDir 

func (s *S3FS) ReadDir(p string) ([]DirEntry, error)

ReadDir 读取目录（通过 S3 前缀列出对象和公共前缀）

func (*S3FS) ReadFile 

func (s *S3FS) ReadFile(p string) ([]byte, error)

ReadFile 读取文件内容

func (*S3FS) RelPath 

func (s *S3FS) RelPath(basePath, targetPath string) (string, error)

RelPath 计算相对路径

func (*S3FS) Stat 

func (s *S3FS) Stat(p string) (FileInfo, error)

Stat 获取文件信息

func (*S3FS) Type 

func (s *S3FS) Type() BackendType

Type 返回后端类型

type SFTPFS 

type SFTPFS struct {
	// contains filtered or unexported fields
}

SFTPFS SFTP 文件系统实现

func NewSFTPFS 

func NewSFTPFS(urlStr string, opts ...Options) (*SFTPFS, error)

NewSFTPFS 创建 SFTP 文件系统实例 urlStr 格式: sftp://user:pass@host:port/path

func (*SFTPFS) BaseURL 

func (s *SFTPFS) BaseURL() string

BaseURL 返回基础 URL

func (*SFTPFS) Close 

func (s *SFTPFS) Close() error

Close 关闭连接

func (*SFTPFS) Exists 

func (s *SFTPFS) Exists(p string) (bool, error)

Exists 检查路径是否存在

func (*SFTPFS) GetBasePath 

func (s *SFTPFS) GetBasePath() string

GetBasePath 返回 SFTP 基础路径

func (*SFTPFS) IsDir 

func (s *SFTPFS) IsDir(p string) (bool, error)

IsDir 检查是否为目录

func (*SFTPFS) IsRemote 

func (s *SFTPFS) IsRemote() bool

IsRemote 返回是否为远程文件系统

func (*SFTPFS) JoinPath 

func (s *SFTPFS) JoinPath(elem ...string) string

JoinPath 连接路径（使用 Unix 风格的路径分隔符）

func (*SFTPFS) Open 

func (s *SFTPFS) Open(p string) (File, error)

Open 打开文件用于读取 如果启用了缓存，会先检查缓存，未命中则从服务器读取并缓存

func (*SFTPFS) OpenReaderAtSeeker 

func (s *SFTPFS) OpenReaderAtSeeker(p string) (ReaderAtSeeker, error)

OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader SFTP 原生支持随机访问，可以直接使用 SFTP 文件句柄

func (*SFTPFS) ReadDir 

func (s *SFTPFS) ReadDir(p string) ([]DirEntry, error)

ReadDir 读取目录

func (*SFTPFS) ReadFile 

func (s *SFTPFS) ReadFile(p string) ([]byte, error)

ReadFile 读取文件内容

func (*SFTPFS) RelPath 

func (s *SFTPFS) RelPath(basePath, targetPath string) (string, error)

RelPath 计算相对路径

func (*SFTPFS) Stat 

func (s *SFTPFS) Stat(p string) (FileInfo, error)

Stat 获取文件信息

func (*SFTPFS) Type 

func (s *SFTPFS) Type() BackendType

Type 返回后端类型

type SMBFS 

type SMBFS struct {
	// contains filtered or unexported fields
}

SMBFS SMB 文件系统实现

func NewSMBFS 

func NewSMBFS(urlStr string, opts ...Options) (*SMBFS, error)

NewSMBFS 创建 SMB 文件系统实例 urlStr 格式: smb://workgroup;user:password@server/share/folder/books

func (*SMBFS) BaseURL 

func (s *SMBFS) BaseURL() string

BaseURL 返回基础 URL

func (*SMBFS) Close 

func (s *SMBFS) Close() error

Close 关闭连接

func (*SMBFS) Exists 

func (s *SMBFS) Exists(p string) (bool, error)

Exists 检查路径是否存在

func (*SMBFS) GetBasePath 

func (s *SMBFS) GetBasePath() string

GetBasePath 返回 SMB 基础路径

func (*SMBFS) IsDir 

func (s *SMBFS) IsDir(p string) (bool, error)

IsDir 检查是否为目录

func (*SMBFS) IsRemote 

func (s *SMBFS) IsRemote() bool

IsRemote 返回是否为远程文件系统

func (*SMBFS) JoinPath 

func (s *SMBFS) JoinPath(elem ...string) string

JoinPath 连接路径（使用正斜杠，go-smb2 使用正斜杠）

func (*SMBFS) Open 

func (s *SMBFS) Open(p string) (File, error)

Open 打开文件用于读取

func (*SMBFS) OpenReaderAtSeeker 

func (s *SMBFS) OpenReaderAtSeeker(p string) (ReaderAtSeeker, error)

OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader SMB 文件句柄支持 Seek，但不一定支持 ReadAt 所有文件都会下载到内存以确保兼容性，并缓存以避免重复下载

func (*SMBFS) ReadDir 

func (s *SMBFS) ReadDir(p string) ([]DirEntry, error)

ReadDir 读取目录

func (*SMBFS) ReadFile 

func (s *SMBFS) ReadFile(p string) ([]byte, error)

ReadFile 读取文件内容

func (*SMBFS) RelPath 

func (s *SMBFS) RelPath(basePath, targetPath string) (string, error)

RelPath 计算相对路径

func (*SMBFS) Stat 

func (s *SMBFS) Stat(p string) (FileInfo, error)

Stat 获取文件信息

func (*SMBFS) Type 

func (s *SMBFS) Type() BackendType

Type 返回后端类型

type WebDAVFS 

type WebDAVFS struct {
	// contains filtered or unexported fields
}

WebDAVFS WebDAV 文件系统实现

func NewWebDAVFS 

func NewWebDAVFS(urlStr string, opts ...Options) (*WebDAVFS, error)

NewWebDAVFS 创建 WebDAV 文件系统实例 urlStr 格式: webdav://user:pass@host:port/path 或 http://user:pass@host:port/path

func (*WebDAVFS) BaseURL 

func (w *WebDAVFS) BaseURL() string

BaseURL 返回基础 URL

func (*WebDAVFS) Close 

func (w *WebDAVFS) Close() error

Close 关闭连接

func (*WebDAVFS) Exists 

func (w *WebDAVFS) Exists(p string) (bool, error)

Exists 检查路径是否存在

func (*WebDAVFS) GetBasePath 

func (w *WebDAVFS) GetBasePath() string

GetBasePath 返回 WebDAV 基础路径

func (*WebDAVFS) IsDir 

func (w *WebDAVFS) IsDir(p string) (bool, error)

IsDir 检查是否为目录

func (*WebDAVFS) IsRemote 

func (w *WebDAVFS) IsRemote() bool

IsRemote 返回是否为远程文件系统

func (*WebDAVFS) JoinPath 

func (w *WebDAVFS) JoinPath(elem ...string) string

JoinPath 连接路径（使用 URL 风格的路径分隔符）

func (*WebDAVFS) Open 

func (w *WebDAVFS) Open(p string) (File, error)

Open 打开文件用于读取 如果启用了缓存，会先检查缓存，未命中则从服务器读取并缓存

func (*WebDAVFS) OpenReaderAtSeeker 

func (w *WebDAVFS) OpenReaderAtSeeker(p string) (ReaderAtSeeker, error)

OpenReaderAtSeeker 打开文件并返回支持 Seek 的 Reader 如果启用了 UseRangeRequests，将使用 RangeReaderAtSeeker 进行按需读取 否则将整个文件下载到内存（向后兼容）

func (*WebDAVFS) ReadDir 

func (w *WebDAVFS) ReadDir(p string) ([]DirEntry, error)

ReadDir 读取目录

func (*WebDAVFS) ReadFile 

func (w *WebDAVFS) ReadFile(p string) ([]byte, error)

ReadFile 读取文件内容

func (*WebDAVFS) RelPath 

func (w *WebDAVFS) RelPath(basePath, targetPath string) (string, error)

RelPath 计算相对路径

func (*WebDAVFS) Stat 

func (w *WebDAVFS) Stat(p string) (FileInfo, error)

Stat 获取文件信息

func (*WebDAVFS) Type 

func (w *WebDAVFS) Type() BackendType

Type 返回后端类型

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.