rclone 配置与使用 QingStor 对象存储后端：完整指南-平芜编程栈

rclone 配置与使用 QingStor 对象存储后端：完整指南

【免费下载链接】rclone"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone

rclone 的qingstor后端将"云端存储的 rsync"能力带到了青云（QingCloud）的 QingStor 对象存储服务上，支持桶（bucket）管理、文件增删同步、分片（multipart）上传等完整操作。本指南以 docs/content/qingstor.md 为核心骨架，结合仓库中 backend/qingstor/ 的源码实现，带你完成从交互式配置、常用命令到高级选项调优的完整实践，并深入剖析其认证、分片上传与区域（zone）机制背后的底层原理。

QingStor 远程路径的基本写法

QingStor 与绝大多数对象存储一样，通过remote:bucket的形式表达路径，remote是在 rclone 配置中定义的后端名称，bucket是 QingStor 中的存储桶名。路径规范如下：

列出所有桶：直接使用remote:，这也是rclone lsd remote:的标准用法；
访问桶内内容：remote:bucket；
深入子目录：remote:bucket/path/to/dir。

这种三段式路径（远程名、桶、目录）在 NewFs 构造逻辑中被解析：源码用bucket.Split把 root 拆成rootBucket与rootDirectory两部分，分别记录桶名和桶内目录前缀，后续所有 API 调用都基于这两个字段展开。

交互式创建 QingStor 远程

完整配置会话

在终端运行rclone config即可进入交互式向导。以下是创建一个名为remote的 QingStor 远程的完整过程：

No remotes found, make a new one? n) New remote r) Rename remote c) Copy remote s) Set configuration password q) Quit config n/r/c/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / QingStor Object Storage \ "qingstor" [snip] Storage> qingstor Get QingStor credentials from runtime. Only applies if access_key_id and secret_access_key is blank. Choose a number from below, or type in your own value 1 / Enter QingStor credentials in the next step \ "false" 2 / Get QingStor credentials from the environment (env vars or IAM) \ "true" env_auth> 1 QingStor Access Key ID - leave blank for anonymous access or runtime credentials. access_key_id> access_key QingStor Secret Access Key (password) - leave blank for anonymous access or runtime credentials. secret_access_key> secret_key Enter an endpoint URL to connection QingStor API. Leave blank will use the default value "https://qingstor.com:443" endpoint> Zone connect to. Default is "pek3a". Choose a number from below, or type in your own value / The Beijing (China) Three Zone 1 | Needs location constraint pek3a. \ "pek3a" / The Shanghai (China) First Zone 2 | Needs location constraint sh1a. \ "sh1a" zone> 1 Number of connection retry. Leave blank will use the default value "3". connection_retries> Remote config Configuration complete. Options: - type: qingstor - env_auth: false - access_key_id: access_key - secret_access_key: secret_key - endpoint: - zone: pek3a - connection_retries: Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y

配置完成后，该远程的信息会持久化在 rclone 配置文件中。需要强调的是，整个选项集合由 backend/qingstor/qingstor.go 中注册到fs.RegInfo.Options的配置项自动生成（文档中 "autogenerated options" 区域的来源即是它），修改选项注册后需运行make backenddocs重新生成文档，因此配置项名称与源码一一对应。

新远程的基本用法

配置完remote后即可执行常用操作：

查看全部存储桶：

rclone lsd remote:

新建一个桶：

rclone mkdir remote:bucket

列出桶内内容：

rclone ls remote:bucket

将本地目录同步到远端桶，并删除桶内多余文件（交互式确认删除）：

rclone sync --interactive /home/local/directory remote:bucket

关于mkdir背后的细节：Mkdir最终会走到 makeBucket。该实现有一个值得注意的容错逻辑——QingStor 删除桶后需要约 60 秒同步状态，因此当对刚被删除的桶执行创建时，它会通过GetStatistics轮询等待状态变为可创建（最多重试 120 次），避免 "桶仍处于 deleted 状态" 导致的 409 Conflict 错误。同时 makeBucket 使用bucket.Cache缓存桶的创建状态，避免重复发起创建请求。

常用功能与关键行为

使用 --fast-list 降低 API 请求次数

qingstor后端实现了ListR接口（声明于 Features 填充与接口断言中，fs.ListRer在文件末尾被断言确认），因此支持--fast-list选项。启用后，rclone 会以更少的 API 事务换取更高的内存占用，适合桶内对象极多、希望降低请求开销的场景。其原理与通用--fast-list一致，详见 rclone 全局文档的 --fast-list 章节。

从实现上看，ListR 方法会在请求中不设置分隔符（delimiter为空），一次性拉取前缀下的所有对象键，并通过marker游标分页。当remote:不带桶名时，它还会先列出所有桶、再逐桶递归汇总，这正是"一次递归、多桶合并"的效率来源。相比之下，普通List每次只返回一个目录层级。

分片上传与大于 5 GiB 的大文件

rclone 通过 QingStor 的 multipart upload API 支持上传超过 5 GiB 的文件，前提是分片大小配置合理。需要注意的是：使用分片上传的文件没有有效的 MD5 校验和。这一点在源码中有双重印证：

Object.Hash 会先用正则^[0-9a-f]{32}$校验对象的 ETag 是否为合法 MD5，若 ETag 不匹配（典型的分片上传产物），则返回空校验和并打日志Invalid md5sum (probably multipart uploaded) - ignoring；
upload.go 中的并发上传注释也明确提示：将分片并发数设为大于 1 时，multipart 上传的校验和会"损坏"（上传内容本身不受影响）。

文件是否走分片上传由 Object.Update 判定：当size < 0（未知大小）或size >= upload_cutoff时选择uploader.upload()（分片路径），否则调用singlePartUpload直接 PUT。分片上限方面，常量定义中maxSizeForCopy = 5 GiB是服务端 COPY 操作的对象大小上限，而 upload.go 的常量规定单分片最小4 MiB、最多10000个分片——这决定了超大文件需要调大chunk_size才能在分片数上限内完成上传。

清理不完整的分片上传：QingStor不会自动回收未完成的分片上传（中断上传后遗留的服务端资源），因此需要定期手动清理：

rclone cleanup remote:bucket # 仅清理指定桶 rclone cleanup remote: # 清理所有桶

后端将清理逻辑实现在 CleanUp / cleanUpBucket：通过ListMultipartUploads分页枚举所有上传任务，仅对创建时间超过 24 小时的发起AbortMultipartUpload中止。也就是说，rclone cleanup是 24 小时以内的中断上传无法被此命令清理，需自行等待或删除整个对象。

桶与区域（Zone）的绑定关系

rclone 允许在任意 zone 下列出所有桶（rclone lsd），因为列桶请求 listBuckets 只携带了Location: &f.zone参数向服务端点发起ListBuckets；但桶内容的访问只能在桶创建时所在的 zone 进行。若从错误的 zone 访问某个桶的内容，QingStor 会返回如下错误：

incorrect zone, the bucket is not in 'XXX' zone

从代码结构看，无论是 list 列表操作还是 readMetaData，都会通过f.svc.Bucket(bucket, f.zone)显式绑定当前配置的 zone 再发起请求，因此 zone 配错会直接导致桶访问失败。所以，zone 必须与目标桶的所在地域严格一致。

认证方式与优先级

QingStor 后端支持两种凭据注入方式，按优先级从高到低排列：

配置文件直填（最高优先级）：通过rclone config设置access_key_id与secret_access_key。两个字段在选项注册中都被标记为Sensitive: true，rclone 会对其做混淆存储。
运行时凭据：将配置文件中的env_auth设为true，并预先导出以下环境变量：
- Access Key ID：QS_ACCESS_KEY_ID或QS_ACCESS_KEY
- Secret Access Key：QS_SECRET_ACCESS_KEY或QS_SECRET_KEY

认证逻辑在 qsServiceConnection 中实际执行，其行为可以概括为：

env_auth = true：跳过空值校验，凭据交给底层 SDK 从运行时获取；
access_key_id与secret_access_key同时为空且未开启env_auth：回退为匿名访问；
仅密钥 ID 为空或仅 Secret 为空：分别返回access_key_id not found/secret_access_key not found错误。

受限文件名字符与编码规则

QingStor 桶内的文件名需要经过 rclone 的标准"文件名编码"处理，规则如下：

控制字符0x00–0x1F与/会被替换，替换规则与默认受限字符集（锚点#restricted-characters）一致；注意0x7F不会被替换；
非法 UTF-8 字节同样会被替换（详见 Invalid UTF-8 bytes 锚点#invalid-utf8），因为它们无法出现在 JSON 字符串中。

这一行为在选项注册的默认值中得到了源码级确认：后端的--qingstor-encoding默认值为Slash,Ctl,InvalidUtf8三者的组合，即对/、控制字符与非法 UTF-8 做转义。完整的编码机制说明见 overview 的 Encoding 章节。

标准选项（Standard options）

以下为 qingstor 后端全部标准配置项，均由 backend/qingstor/qingstor.go 的选项注册表驱动，除rclone config交互式配置外，也可直接写入配置文件或通过环境变量覆盖。

--qingstor-env-auth

从运行时获取 QingStor 凭据（仅当access_key_id与secret_access_key均为空时生效）。

Config：env_auth
环境变量：RCLONE_QINGSTOR_ENV_AUTH
类型：bool
默认值：false
可选值：
- false：在下一步手动输入 QingStor 凭据；
- true：从环境变量或 IAM 获取运行时凭据。

--qingstor-access-key-id

QingStor Access Key ID。留空表示匿名访问或使用运行时凭据。

Config：access_key_id
环境变量：RCLONE_QINGSTOR_ACCESS_KEY_ID
类型：string
必填：否（敏感项，存储时会被混淆）

--qingstor-secret-access-key

QingStor Secret Access Key（密码）。留空表示匿名访问或使用运行时凭据。

Config：secret_access_key
环境变量：RCLONE_QINGSTOR_SECRET_ACCESS_KEY
类型：string
必填：否（敏感项，存储时会被混淆）

--qingstor-endpoint

连接 QingStor API 的 endpoint URL。留空使用默认值https://qingstor.com:443。

Config：endpoint
环境变量：RCLONE_QINGSTOR_ENDPOINT
类型：string
必填：否

自建兼容服务或内网环境通常需要自定义该值。源码用正则^(?:(http|https)://)*(\w+\.(?:[\w\.])*)(?::(\d{0,5}))*$解析 endpoint（见 qsParseEndpoint），支持省略协议与端口三种写法（如https://qingstor.com:443、http://qingstor.com、qingstor.com）；省略端口时，https默认 443、http默认 80。

--qingstor-zone

连接的 Zone，默认pek3a。

Config：zone
环境变量：RCLONE_QINGSTOR_ZONE
类型：string
必填：否
可选值：
- pek3a：北京三区，location constraint 为pek3a；
- sh1a：上海一区，location constraint 为sh1a；
- gd2a：广东二区，location constraint 为gd2a。

值得注意的是，文档选项表默认列出三个区域，而源码实现会在 NewFs 中对空 zone 回填pek3a，因此即使配置文件中不写 zone，也会落到北京三区；后续实际支持的区域以青云官方为准，可自行在选项示例中扩展。

高级选项（Advanced options）

高级选项与标准选项同属后端 Options 结构体，供需要调优吞吐或处理特殊场景的用户使用。

--qingstor-connection-retries

连接重试次数。

Config：connection_retries
环境变量：RCLONE_QINGSTOR_CONNECTION_RETRIES
类型：int
默认值：3

注意：从源码注释看，QingStor Go SDK v3.1 尚未原生支持该参数透传（见 qsServiceConnection 的注释unsupported in v3.1），重试行为主要由 rclone 公共的 HTTP 客户端与 pacer 机制兜底。

--qingstor-upload-cutoff

切换为分片上传的大小阈值。超过该值的文件将以chunk_size为粒度分片上传；取值范围为 0～5 GiB。

Config：upload_cutoff
环境变量：RCLONE_QINGSTOR_UPLOAD_CUTOFF
类型：SizeSuffix
默认值：200Mi

上限 5 GiB 由常量定义与校验函数强制保证，setUploadCutoff只允许设置不超过maxUploadCutoff的值。注意该值与"单次普通 PUT 上限 5 GiB"是两个不同概念：超过 cutoff 仅是触发分片上传的开关。

--qingstor-chunk-size

上传分片大小。当文件大于upload_cutoff时，将以该尺寸进行分片上传。

Config：chunk_size
环境变量：RCLONE_QINGSTOR_CHUNK_SIZE
类型：SizeSuffix
默认值：4Mi

参数联动关系需格外注意：

每个传输在内存中会缓冲upload_concurrency个该尺寸的分片，即"每传输内存占用 ≈ chunk_size × upload_concurrency"；
在高速链路上传输大文件且内存充足时，调大该值可显著提升吞吐；
单分片最小为 4 MiB（常量minMultiPartSize，由 checkUploadChunkSize 校验），且分片总数不能超过 10000（见 multiPartUpload 的分片数上限检查），因此理论上单文件上限约 5 GiB × …（实际受 QingStor 侧约束）需通过增大分片来满足超大文件需求。

--qingstor-upload-concurrency

multipart 上传的并发分片数，即同一文件同时上传的分片数量。

Config：upload_concurrency
环境变量：RCLONE_QINGSTOR_UPLOAD_CONCURRENCY
类型：int
默认值：1

重要警告：若设置为大于 1，分片上传产生的校验和会变得不可用（上传本身不受影响）。并发实现的底层证据在 upload.go 的 readChunk/send：多个 goroutine 会各自从同一io.ReadSeeker上io.Copy数据进入同一个hashMd5，导致最终 MD5 与对象内容不一致——这正是文档警告的技术根源。适用场景是"少量大文件、高速链路、带宽未被充分利用"时，调大该值可能提速。

--qingstor-encoding

后端使用的文件名编码。

Config：encoding
环境变量：RCLONE_QINGSTOR_ENCODING
类型：Encoding
默认值：Slash,Ctl,InvalidUtf8

含义与可选组合详见 overview 的 Encoding 章节，一般无需改动。

--qingstor-description

该远程的描述信息，便于在多个远程中标识用途。

Config：description
环境变量：RCLONE_QINGSTOR_DESCRIPTION
类型：string
必填：否

能力边界与已知限制

rclone about不被 qingstor 后端支持。这意味着：

无法通过 rclone about 命令查询桶的容量/配额信息；
基于此能力，qingstor 后端无法作为 rclone mount 时确定剩余空间的后端，也不能在 union 远程中作为策略mfs（most free space）的成员参与"选择剩余空间最大者"的挂载选择。

该限制的直接来源是 Features 声明：特性列表中并未包含About能力。更完整的"可选能力（optional features）"对照表见 overview 文档，其中列出了所有不支持rclone about的后端清单。

此外还有几点实现层面的边界值得了解：

修改时间精度：Precision()返回fs.ModTimeNotSupported（见 Precision），QingStor 侧并不原生保存可精确复用的修改时间；SetModTime通过"把对象 Copy 到自身"来更新元数据，且对大于 5 GiB 的对象（maxSizeForCopy）直接跳过，仅记录调试日志（见 SetModTime）；
支持的哈希：仅支持 MD5（见 Hashes 与 Object.Hash），且如前文所述，分片上传的对象 ETag 不是合法 MD5，会被视为无校验和；
mime 类型：后端支持读取与写入对象的 ContentType（Features 中的ReadMimeType/WriteMimeType），上传时由 Object.Update 调用fs.MimeType(ctx, src)自动推断。

小结

QingStor 后端是一个功能完整的 rclone 存储适配层：通过rclone config几分钟即可创建远程，之后lsd/mkdir/ls/sync/cleanup等命令即可完成桶与文件的生命周期管理。理解 zone 与桶的地域绑定、掌握upload_cutoff/chunk_size/upload_concurrency三参数的联动关系（尤其是并发分片会导致 MD5 失效的限制），是稳定、高效使用该后端的关键。若需深入源码，建议从 backend/qingstor/qingstor.go（远程与对象抽象、认证、列举）和 backend/qingstor/upload.go（单分片与 multipart 上传通道）两个文件入手，对照 backend/qingstor/qingstor_test.go 中基于fstests框架的集成测试（TestQingStor:）理解其行为契约。