Documentation
¶
Overview ¶
Package remote 提供多种远程存储方式的统一接口。
Index ¶
- Constants
- Variables
- type COSClient
- func (c *COSClient) Close() error
- func (c *COSClient) Delete(ctx context.Context, remotePath string) error
- func (c *COSClient) Download(ctx context.Context, remotePath string) ([]byte, error)
- func (c *COSClient) Exists(ctx context.Context, remotePath string) (bool, error)
- func (c *COSClient) List(ctx context.Context, options ListOptions) (ListResult, error)
- func (c *COSClient) PresignUpload(ctx context.Context, remotePath string, opts *PresignOptions) (string, map[string]string, error)
- func (c *COSClient) Upload(ctx context.Context, remotePath string, data []byte) error
- type COSConfig
- type Client
- type Error
- type FTPClient
- func (c *FTPClient) Close() error
- func (c *FTPClient) Delete(ctx context.Context, remotePath string) error
- func (c *FTPClient) Download(ctx context.Context, remotePath string) ([]byte, error)
- func (c *FTPClient) List(ctx context.Context, options ListOptions) (ListResult, error)
- func (c *FTPClient) Upload(ctx context.Context, remotePath string, data []byte) error
- type FTPConfig
- type FileInfo
- type ListOptions
- type ListResult
- type OSSClient
- func (c *OSSClient) Close() error
- func (c *OSSClient) Delete(ctx context.Context, remotePath string) error
- func (c *OSSClient) Download(ctx context.Context, remotePath string) ([]byte, error)
- func (c *OSSClient) Exists(ctx context.Context, remotePath string) (bool, error)
- func (c *OSSClient) HeadObjectMeta(ctx context.Context, remotePath string) (*ObjectMeta, error)
- func (c *OSSClient) List(ctx context.Context, options ListOptions) (ListResult, error)
- func (c *OSSClient) OpenDownload(ctx context.Context, remotePath string, opts *OpenDownloadOptions) (io.ReadCloser, error)
- func (c *OSSClient) PresignGet(ctx context.Context, remotePath string, opts *PresignDownloadOptions) (string, map[string]string, error)
- func (c *OSSClient) PresignUpload(ctx context.Context, remotePath string, opts *PresignOptions) (string, map[string]string, error)
- func (c *OSSClient) Upload(ctx context.Context, remotePath string, data []byte) error
- type OSSConfig
- type ObjectExister
- type ObjectMeta
- type ObjectMetaReader
- type OpenDownloadOptions
- type PresignDownloadOptions
- type PresignDownloader
- type PresignOptions
- type PresignUploader
- type SFTPClient
- func (c *SFTPClient) Close() error
- func (c *SFTPClient) Delete(ctx context.Context, remotePath string) error
- func (c *SFTPClient) Download(ctx context.Context, remotePath string) ([]byte, error)
- func (c *SFTPClient) List(ctx context.Context, options ListOptions) (ListResult, error)
- func (c *SFTPClient) Upload(ctx context.Context, remotePath string, data []byte) error
- type SFTPConfig
- type StreamDownloader
Constants ¶
const ( TypeFTP = "ftp" // FTP存储类型 TypeSFTP = "sftp" // SFTP存储类型 TypeCOS = "cos" // 腾讯云COS存储类型 TypeOSS = "oss" // 阿里云OSS存储类型 )
存储类型常量定义
Variables ¶
var ErrObjectNotFound = errors.New("remote object not found")
ErrObjectNotFound 表示远程对象不存在。 上层可通过 errors.Is(err, ErrObjectNotFound) 区分「对象不存在」与「请求失败」， 避免把权限不足、网络异常等错误误判为对象缺失。
var ErrPresignNotSupported = errors.New("current storage type does not support presigned upload")
ErrPresignNotSupported 表示当前存储类型不支持预签名上传。
Functions ¶
This section is empty.
Types ¶
type COSClient ¶
type COSClient struct {
// contains filtered or unexported fields
}
COSClient 实现了腾讯云COS存储的客户端。 注意：COSClient是并发安全的，因为底层COS SDK客户端本身是并发安全的。
func NewCOSClient ¶
NewCOSClient 创建一个新的COS客户端。
参数：
- config COSConfig: COS 配置，Url 为空时会使用 Bucket 与 Region 自动构造
返回值：
- *COSClient: 初始化后的 COS 客户端
- error: 配置错误时返回错误
使用示例：
client, err := NewCOSClient(COSConfig{SecretId: "xxx", SecretKey: "xxx", Bucket: "bucket-1250000000", Region: "ap-guangzhou"})
func (*COSClient) Exists ¶ added in v0.14.0
Exists 判断指定对象是否已存在于COS中。 底层使用 HEAD Object，只取对象元信息不下载内容，开销较低。 参数：
- ctx context.Context: 上下文，可用于控制探测超时
- remotePath string: 对象在存储桶中的路径（Key）
返回值：
- bool: 对象存在返回 true；对象不存在返回 false
- error: 网络异常或权限不足时返回错误
使用示例：
ok, err := client.Exists(ctx, "images/2026/08/xxx.png")
func (*COSClient) List ¶
func (c *COSClient) List(ctx context.Context, options ListOptions) (ListResult, error)
List 实现了Client接口的List方法。
func (*COSClient) PresignUpload ¶ added in v0.14.0
func (c *COSClient) PresignUpload(ctx context.Context, remotePath string, opts *PresignOptions) (string, map[string]string, error)
PresignUpload 生成用于上传指定对象的预签名 URL，客户端需使用 PUT 方法上传文件内容。 参数：
- ctx context.Context: 上下文
- remotePath string: 对象在存储桶中的路径（Key）
- opts *PresignOptions: 预签名选项，nil 时表示使用默认选项（默认有效期 10 分钟，不签名额外请求头）
返回值：
- string: 预签名 URL
- map[string]string: 需要在上传请求中原样携带的已签名请求头，恒为非 nil
- error: 生成过程中出现的错误
说明：
- COS 仅对 Content-Type 等特定请求头以及 x-cos- 前缀的请求头参与签名， 因此自定义元数据需使用 x-cos-meta- 前缀才会真正生效，其他 key 不会参与签名。
- 签名默认签入 Host，客户端必须使用返回的域名访问，不可改写。
使用示例：
url, headers, err := client.PresignUpload(ctx, "images/2026/08/xxx.png", &PresignOptions{
Expires: 10 * time.Minute,
ContentType: "image/jpeg",
Metadata: map[string]string{"x-cos-meta-uid": "12345"},
})
type Client ¶
type Client interface {
Upload(ctx context.Context, remotePath string, data []byte) error
Download(ctx context.Context, remotePath string) ([]byte, error)
Delete(ctx context.Context, remotePath string) error
List(ctx context.Context, options ListOptions) (ListResult, error)
Close() error
}
Client 定义了远程存储的统一接口。 注意：所有方法都应是并发安全的。
type FTPClient ¶
type FTPClient struct {
// contains filtered or unexported fields
}
FTPClient 实现了FTP存储的客户端。 注意：FTPClient是并发安全的。
func (*FTPClient) List ¶
func (c *FTPClient) List(ctx context.Context, options ListOptions) (ListResult, error)
List 实现了Client接口的List方法。 注意：FTP 的 Prefix 表示待列出内容的目录路径，非对象前缀。 列出前会检测/恢复连接，返回结果按文件名排序后做本地分页。
type FileInfo ¶
type FileInfo struct {
Name string // 文件名
Size int64 // 文件大小（字节）
ModTime time.Time // 修改时间
IsDir bool // 是否为目录
}
FileInfo 定义了文件的元数据信息
type ListOptions ¶
type ListOptions struct {
Prefix string // 文件名前缀过滤或目录路径，可选
Marker string // 分页标记，可选
MaxKeys int // 每次返回的最大文件数量，可选
}
ListOptions 定义了分页和过滤选项 注意：不同存储类型对 Prefix 的语义不同：
- COS/OSS：对象键前缀过滤
- FTP/SFTP：待列出内容的目录路径
type ListResult ¶
type ListResult struct {
Files []FileInfo // 文件信息列表
NextMarker string // 下一个分页标记
IsTruncated bool // 是否还有更多数据
}
ListResult 定义了List方法的返回结果
type OSSClient ¶
type OSSClient struct {
// contains filtered or unexported fields
}
OSSClient 实现了阿里云OSS存储的客户端。 注意：OSSClient是并发安全的，因为底层OSS SDK客户端本身是并发安全的。
func NewOSSClient ¶
NewOSSClient 创建一个新的OSS客户端。
func (*OSSClient) Exists ¶ added in v0.14.0
Exists 判断指定对象是否已存在于OSS中。 底层使用 HeadObject，只取对象元信息不下载内容，开销较低。 参数：
- ctx context.Context: 上下文，可用于控制探测超时
- remotePath string: 对象在存储桶中的路径（Key）
返回值：
- bool: 对象存在返回 true；对象不存在返回 false
- error: 网络异常或权限不足时返回错误
使用示例：
ok, err := client.Exists(ctx, "images/2026/08/xxx.png")
func (*OSSClient) HeadObjectMeta ¶ added in v0.18.1
HeadObjectMeta 读取指定对象的元信息，不下载对象内容。 底层使用 HeadObject，元数据中的自定义字段（如 x-oss-meta-sha256）会去除前缀后放入 Metadata。 - remotePath: 对象在存储桶中的路径（Key）。
返回值：
- *ObjectMeta: 对象元信息；Metadata 一定非 nil。
- error: 对象不存在时返回包装了 ErrObjectNotFound 的错误；其它异常返回请求错误。
使用示例：
meta, err := client.HeadObjectMeta(ctx, "releases/pkg.zip")
if errors.Is(err, ErrObjectNotFound) { /* 对象不存在 */ }
sha256 := meta.Metadata["sha256"]
func (*OSSClient) List ¶
func (c *OSSClient) List(ctx context.Context, options ListOptions) (ListResult, error)
List 实现了Client接口的List方法。
func (*OSSClient) OpenDownload ¶ added in v0.18.1
func (c *OSSClient) OpenDownload(ctx context.Context, remotePath string, opts *OpenDownloadOptions) (io.ReadCloser, error)
OpenDownload 打开指定对象的下载流，不在内存中缓存完整对象。 底层使用 GetObject，返回的 io.ReadCloser 由调用方负责关闭。 - remotePath: 对象在存储桶中的路径（Key）。 - opts: 下载选项，nil 时表示下载完整对象；设置 Range 时只读取指定范围。
返回值：
- io.ReadCloser: 流式读取器；读取阶段的错误会在 Read 时返回。
- error: 建立下载流失败时返回错误；对象不存在时返回包装了 ErrObjectNotFound 的错误。
使用示例：
reader, err := client.OpenDownload(ctx, "releases/pkg.zip", nil)
if err != nil { return err }
defer reader.Close()
_, _ = io.Copy(io.MultiWriter(file, hasher), reader)
func (*OSSClient) PresignGet ¶ added in v0.18.1
func (c *OSSClient) PresignGet(ctx context.Context, remotePath string, opts *PresignDownloadOptions) (string, map[string]string, error)
PresignGet 生成用于下载指定对象的预签名 URL。 底层使用 OSS Go SDK V2 的 GetObject 预签名能力，签名版本为 V4（OSS4-HMAC-SHA256）。 - remotePath: 对象在存储桶中的路径（Key）。 - opts: 下载选项，nil 时表示使用默认选项（仅签名 bucket 与 key，默认有效期 10 分钟）。
返回值：
- string: 预签名 URL。
- map[string]string: 使用该 URL 发起请求时需要携带的已签名请求头。
- error: 生成过程中出现的错误。
签名契约（与 PresignUpload 相同）：请求必须原样携带返回的 SignedHeaders， 被签名的头缺失或值不一致时服务端返回 403 SignatureDoesNotMatch。
使用示例：
url, headers, err := client.PresignGet(ctx, "releases/pkg.zip", &PresignDownloadOptions{
Expires: 60 * time.Minute,
ResponseContentDisposition: "attachment;filename=pkg.zip",
})
func (*OSSClient) PresignUpload ¶ added in v0.13.24
func (c *OSSClient) PresignUpload(ctx context.Context, remotePath string, opts *PresignOptions) (string, map[string]string, error)
PresignUpload 生成用于上传指定对象的预签名 URL（OSS 为 V4 签名 OSS4-HMAC-SHA256）。 - remotePath: 对象在存储桶中的路径（Key）。 - opts: 预签名选项，nil 时表示使用默认选项（仅签名 bucket 与 key，默认有效期 10 分钟）。 返回值：
- string: 预签名 URL。
- map[string]string: 需要在上传请求中携带的已签名请求头。
- error: 生成过程中出现的错误。
签名契约（浏览器直传必读）：
客户端发起 PUT 时必须原样携带返回的 SignedHeaders（键名与值都不能改）， 且不得额外出现任何被签名的头。被签名的头缺失或值不一致，OSS 会返回 403 SignatureDoesNotMatch；未被签名的头（如 Accept、Origin）不影响校验。
opts.ContentType 为空时 Content-Type 不参与签名，此时若客户端是浏览器 fetch 且 body 为带 type 的 Blob/File，浏览器会自动补发一个未签名的 Content-Type 头， 同样触发 403 SignatureDoesNotMatch。规避方式二选一： - 签发时显式传入 ContentType 并将返回的 SignedHeaders 交由前端原样携带 （fetch/XHR 显式设置该头后浏览器不再自动补）； - 或保证上传 body 为无 type 的 Blob（浏览器不自动补头）。
使用示例：
url, headers, err := client.PresignUpload(ctx, "images/2026/08/xxx.png",
&PresignOptions{Expires: 10 * time.Minute, ContentType: "image/jpeg"})
// 前端：fetch(url, { method: "PUT", headers, body: file }) —— headers 原样透传
type ObjectExister ¶ added in v0.14.0
type ObjectExister interface {
// Exists 判断指定对象是否已存在于存储中。
// - remotePath: 对象在存储中的相对路径（Key）。
// 返回值：
// - bool: 对象存在返回 true，不存在返回 false。
// - error: 探测过程中出现异常时返回错误。
Exists(ctx context.Context, remotePath string) (bool, error)
}
ObjectExister 定义了支持对象存在性探测的存储类型需要实现的接口。 注意：该接口是可选的，FTP/SFTP 等不支持低成本探测的存储类型无需实现； 未实现时上层会按「对象存在」处理，以保持原有秒传行为不被改变。
该接口与 PresignUploader 成对出现：预签名上传存在「客户端拿到URL却未真正上传」的情况， 秒传命中时必须探测对象是否真实存在。服务端直传的存储类型（FTP/SFTP）不存在这个问题。 目前 OSS 与 COS 均已实现 PresignUploader，因此两者也一并实现了本接口； 若后续为其他存储类型补充 PresignUploader，请同步实现本接口。
type ObjectMeta ¶ added in v0.18.1
type ObjectMeta struct {
Size int64 // 对象大小（字节）
ContentType string // 对象 Content-Type
LastModified time.Time // 最后修改时间
ETag string // 对象 ETag
Metadata map[string]string // 自定义元数据
}
ObjectMeta 定义了对象元信息。 Metadata 为自定义元数据（已去除 x-oss-meta- 等存储类型前缀），例如 sha256 对应 x-oss-meta-sha256。
type ObjectMetaReader ¶ added in v0.18.1
type ObjectMetaReader interface {
// HeadObjectMeta 读取指定对象的元信息，不下载对象内容。
// - remotePath: 对象在存储桶中的路径（Key）。
// 返回值：
// - *ObjectMeta: 对象元信息。
// - error: 对象不存在时返回包装了 ErrObjectNotFound 的错误；其它异常返回请求错误。
HeadObjectMeta(ctx context.Context, remotePath string) (*ObjectMeta, error)
}
ObjectMetaReader 定义了支持读取对象元信息的存储类型需要实现的接口。
type OpenDownloadOptions ¶ added in v0.18.1
type OpenDownloadOptions struct {
Range string // HTTP Range 请求头，例如 bytes=0-1023；为空表示下载完整对象
}
OpenDownloadOptions 定义了流式下载的可选参数。
type PresignDownloadOptions ¶ added in v0.18.1
type PresignDownloadOptions struct {
Expires time.Duration // 预签名 URL 的有效期，为零时使用存储类型的默认有效期
ResponseContentDisposition string // 覆盖响应头 Content-Disposition，例如 attachment;filename=xxx.zip
ResponseContentType string // 覆盖响应头 Content-Type
ResponseCacheControl string // 覆盖响应头 Cache-Control
}
PresignDownloadOptions 定义了生成预签名下载 URL 的可选参数。 不同存储类型对字段的支持程度可能不同，不支持的字段会被忽略。
type PresignDownloader ¶ added in v0.18.1
type PresignDownloader interface {
// PresignGet 生成用于下载指定对象的预签名 URL。
// - remotePath: 对象在存储桶中的路径（Key）。
// - opts: 下载选项，nil 时表示使用默认选项。
// 返回值：
// - string: 预签名 URL。
// - map[string]string: 使用该 URL 发起请求时需要携带的已签名请求头。
// - error: 生成过程中出现的错误。
PresignGet(ctx context.Context, remotePath string, opts *PresignDownloadOptions) (string, map[string]string, error)
}
PresignDownloader 定义了支持预签名下载的存储类型需要实现的接口。 注意：该接口是可选的，FTP/SFTP 等不支持预签名 URL 的存储类型无需实现。
type PresignOptions ¶ added in v0.13.24
type PresignOptions struct {
Expires time.Duration // 预签名 URL 的有效期，为零时使用存储类型的默认有效期
ContentType string // 上传文件的 Content-Type，为空时不参与签名（见 PresignUpload 的签名契约说明）
Metadata map[string]string // 自定义元数据，为空时不参与签名
}
PresignOptions 定义了生成预签名 URL 的可选参数。 不同存储类型对字段的支持程度可能不同，不支持的字段会被忽略。
type PresignUploader ¶ added in v0.13.24
type PresignUploader interface {
// PresignUpload 生成用于上传指定对象的预签名 URL。
// - remotePath: 对象在存储桶中的路径（Key）。
// - opts: 预签名选项，nil 时表示使用默认选项。
// 返回值：
// - string: 预签名 URL。
// - map[string]string: 需要在上传请求中携带的已签名请求头。
// - error: 生成过程中出现的错误。
PresignUpload(ctx context.Context, remotePath string, opts *PresignOptions) (string, map[string]string, error)
}
PresignUploader 定义了支持预签名上传的存储类型需要实现的接口。 注意：该接口是可选的，FTP/SFTP 等不支持预签名 URL 的存储类型无需实现。
type SFTPClient ¶
type SFTPClient struct {
// contains filtered or unexported fields
}
SFTPClient 实现了SFTP存储的客户端。 注意：SFTPClient是并发安全的。
func NewSFTPClient ¶
func NewSFTPClient(config SFTPConfig, args ...ssh.HostKeyCallback) (*SFTPClient, error)
NewSFTPClient 创建一个新的SFTP客户端。 - config SFTP 连接配置 - args 可选的主机密钥回调，未提供时使用 ssh.InsecureIgnoreHostKey 返回值：
- 创建成功返回 *SFTPClient
- 地址格式错误、认证信息缺失或连接失败时返回错误
func (*SFTPClient) Close ¶
func (c *SFTPClient) Close() error
Close 实现了Client接口的Close方法。 关闭 SFTP 客户端和底层 SSH 连接，并将内部引用置空，标记客户端为已关闭状态。
func (*SFTPClient) Delete ¶
func (c *SFTPClient) Delete(ctx context.Context, remotePath string) error
Delete 实现了Client接口的Delete方法。 删除前会检测/恢复连接。
func (*SFTPClient) List ¶
func (c *SFTPClient) List(ctx context.Context, options ListOptions) (ListResult, error)
List 实现了Client接口的List方法。 注意：SFTP 的 Prefix 表示待列出内容的目录路径，非对象前缀。 列出前会检测/恢复连接，返回结果按文件名排序后做本地分页。
type StreamDownloader ¶ added in v0.18.1
type StreamDownloader interface {
// OpenDownload 打开指定对象的下载流。
// - remotePath: 对象在存储桶中的路径（Key）。
// - opts: 下载选项，nil 时表示下载完整对象。
// 返回值：
// - io.ReadCloser: 调用方负责关闭；读取过程中的错误会在 Read 时返回。
// - error: 建立下载流失败时返回错误；对象不存在时返回包装了 ErrObjectNotFound 的错误。
OpenDownload(ctx context.Context, remotePath string, opts *OpenDownloadOptions) (io.ReadCloser, error)
}
StreamDownloader 定义了支持流式下载的存储类型需要实现的接口。 与 Client.Download 一次性读入内存不同，本接口返回流式读取器，适合大文件边读边算。
Source Files