rclone 配置与使用 QingStor 对象存储后端完整指南【免费下载链接】rclonersync 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/rclonerclone 的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) - ignoringupload.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: truerclone 会对其做混淆存储。运行时凭据将配置文件中的env_auth设为true并预先导出以下环境变量Access Key IDQS_ACCESS_KEY_ID或QS_ACCESS_KEYSecret Access KeyQS_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均为空时生效。Configenv_auth环境变量RCLONE_QINGSTOR_ENV_AUTH类型bool默认值false可选值false在下一步手动输入 QingStor 凭据true从环境变量或 IAM 获取运行时凭据。--qingstor-access-key-idQingStor Access Key ID。留空表示匿名访问或使用运行时凭据。Configaccess_key_id环境变量RCLONE_QINGSTOR_ACCESS_KEY_ID类型string必填否敏感项存储时会被混淆--qingstor-secret-access-keyQingStor Secret Access Key密码。留空表示匿名访问或使用运行时凭据。Configsecret_access_key环境变量RCLONE_QINGSTOR_SECRET_ACCESS_KEY类型string必填否敏感项存储时会被混淆--qingstor-endpoint连接 QingStor API 的 endpoint URL。留空使用默认值https://qingstor.com:443。Configendpoint环境变量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。Configzone环境变量RCLONE_QINGSTOR_ZONE类型string必填否可选值pek3a北京三区location constraint 为pek3ash1a上海一区location constraint 为sh1agd2a广东二区location constraint 为gd2a。值得注意的是文档选项表默认列出三个区域而源码实现会在 NewFs 中对空 zone 回填pek3a因此即使配置文件中不写 zone也会落到北京三区后续实际支持的区域以青云官方为准可自行在选项示例中扩展。高级选项Advanced options高级选项与标准选项同属后端 Options 结构体供需要调优吞吐或处理特殊场景的用户使用。--qingstor-connection-retries连接重试次数。Configconnection_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为粒度分片上传取值范围为 05 GiB。Configupload_cutoff环境变量RCLONE_QINGSTOR_UPLOAD_CUTOFF类型SizeSuffix默认值200Mi上限 5 GiB 由 常量定义与校验函数 强制保证setUploadCutoff只允许设置不超过maxUploadCutoff的值。注意该值与单次普通 PUT 上限 5 GiB是两个不同概念超过 cutoff 仅是触发分片上传的开关。--qingstor-chunk-size上传分片大小。当文件大于upload_cutoff时将以该尺寸进行分片上传。Configchunk_size环境变量RCLONE_QINGSTOR_CHUNK_SIZE类型SizeSuffix默认值4Mi参数联动关系需格外注意每个传输在内存中会缓冲upload_concurrency个该尺寸的分片即每传输内存占用 ≈ chunk_size × upload_concurrency在高速链路上传输大文件且内存充足时调大该值可显著提升吞吐单分片最小为 4 MiB常量minMultiPartSize由 checkUploadChunkSize 校验且分片总数不能超过 10000见 multiPartUpload 的分片数上限检查因此理论上单文件上限约 5 GiB × …实际受 QingStor 侧约束需通过增大分片来满足超大文件需求。--qingstor-upload-concurrencymultipart 上传的并发分片数即同一文件同时上传的分片数量。Configupload_concurrency环境变量RCLONE_QINGSTOR_UPLOAD_CONCURRENCY类型int默认值1重要警告若设置为大于 1分片上传产生的校验和会变得不可用上传本身不受影响。并发实现的底层证据在 upload.go 的 readChunk/send多个 goroutine 会各自从同一io.ReadSeeker上io.Copy数据进入同一个hashMd5导致最终 MD5 与对象内容不一致——这正是文档警告的技术根源。适用场景是少量大文件、高速链路、带宽未被充分利用时调大该值可能提速。--qingstor-encoding后端使用的文件名编码。Configencoding环境变量RCLONE_QINGSTOR_ENCODING类型Encoding默认值Slash,Ctl,InvalidUtf8含义与可选组合详见 overview 的 Encoding 章节一般无需改动。--qingstor-description该远程的描述信息便于在多个远程中标识用途。Configdescription环境变量RCLONE_QINGSTOR_DESCRIPTION类型string必填否能力边界与已知限制rclone about不被 qingstor 后端支持。这意味着无法通过 rclone about 命令 查询桶的容量/配额信息基于此能力qingstor 后端无法作为 rclone mount 时确定剩余空间的后端也不能在 union 远程中作为策略mfsmost free space的成员参与选择剩余空间最大者的挂载选择。该限制的直接来源是 Features 声明特性列表中并未包含About能力。更完整的可选能力optional features对照表见 overview 文档其中列出了所有不支持rclone about的后端清单。此外还有几点实现层面的边界值得了解修改时间精度Precision()返回fs.ModTimeNotSupported见 PrecisionQingStor 侧并不原生保存可精确复用的修改时间SetModTime通过把对象 Copy 到自身来更新元数据且对大于 5 GiB 的对象maxSizeForCopy直接跳过仅记录调试日志见 SetModTime支持的哈希仅支持 MD5见 Hashes 与 Object.Hash且如前文所述分片上传的对象 ETag 不是合法 MD5会被视为无校验和mime 类型后端支持读取与写入对象的 ContentTypeFeatures 中的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:理解其行为契约。【免费下载链接】rclonersync 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考