rclone Swift 后端完整实践OpenStack 对象存储的配置、认证、大对象分块与分页调优【免费下载链接】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本文围绕 rclone 仓库中的 Swift 后端文档 展开系统讲解 SwiftOpenStack Object Storage远程端的完整配置流程、OpenStack 标准认证变量、5 GiB 大对象SLO/DLO分块上传机制、修改时间与 MD5 的存储方式以及分页、重试等高级调优选项读完后可直接完成 Rackspace Cloud Files、OVH Object Storage 等 Swift 兼容服务的接入与运维并能结合 后端源码 理解每个选项在底层的具体行为。1. Swift 后端是什么rclone 的swift后端对接OpenStack Object StorageSwift协议。凡是实现了该协议的存储服务都可以直接作为远程端使用典型商业实现包括 Rackspace Cloud Files、Memset Memstore、OVH Object Storage、Oracle Cloud Storage、Blomp Cloud Storage、IBM Cloud Object Storage (Swift) 等。后端的注册入口在 swift.gofs.Register(fs.RegInfo{ Name: swift, Description: OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH), NewFs: NewFs, ... })该后端基于github.com/ncw/swift/v2客户端库实现见 swift.go 的 import从源码结构看它实现了fs.Purger、fs.PutStreamer、fs.Copier、fs.ListRer、fs.ListPer、fs.MimeTyper等接口接口断言即支持服务端 Copy、流式上传、递归列举与容器清空。路径规范Swift 是桶bucket型后端容器container对应 bucket。路径写作remote:containerlsd命令下remote:列出全部容器容器内还可带子目录例如remote:container/path/to/dir。2. 基础操作命令配置完成后常用命令如下remote为远程端名称# 列出所有容器 rclone lsd remote: # 创建新容器 rclone mkdir remote:container # 列出容器内容 rclone ls remote:container # 把本地目录同步到远程容器并删除容器中多余文件 rclone sync --interactive /home/local/directory remote:container其中--interactive会逐条确认每个删除动作。列举时 rclone 使用Limit: 1000的分页常量读取目录listChunks 常量根级别列举容器走listContainers源码并会把容器状态写入 bucket 缓存以减少重复的“容器是否存在”探测。3. 交互式配置rclone config运行rclone config进入交互式配置。以下是文档给出的完整配置会话示例No remotes found, make a new one\? n) New remote s) Set configuration password q) Quit config n/s/q n name remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH) \ swift [snip] Storage swift Get swift credentials from environment variables in standard OpenStack form. Choose a number from below, or type in your own value 1 / Enter swift credentials in the next step \ false 2 / Get swift credentials from environment vars. Leave other fields blank if using this. \ true env_auth true User name to log in (OS_USERNAME). user API key or password (OS_PASSWORD). key Authentication URL for server (OS_AUTH_URL). Choose a number from below, or type in your own value 1 / Rackspace US \ https://auth.api.rackspacecloud.com/v1.0 2 / Rackspace UK \ https://lon.auth.api.rackspacecloud.com/v1.0 3 / Rackspace v2 \ https://identity.api.rackspacecloud.com/v2.0 4 / Memset Memstore UK \ https://auth.storage.memset.com/v1.0 5 / Memset Memstore UK v2 \ https://auth.storage.memset.com/v2.0 6 / OVH \ https://auth.cloud.ovh.net/v3 7 / Blomp Cloud Storage \ https://authenticate.ain.net auth User ID to log in - optional - most swift systems use user and leave this blank (v3 auth) (OS_USER_ID). user_id User domain - optional (v3 auth) (OS_USER_DOMAIN_NAME) domain Tenant name - optional for v1 auth, this or tenant_id required otherwise (OS_TENANT_NAME or OS_PROJECT_NAME) tenant Tenant ID - optional for v1 auth, this or tenant required otherwise (OS_TENANT_ID) tenant_id Tenant domain - optional (v3 auth) (OS_PROJECT_DOMAIN_NAME) tenant_domain Region name - optional (OS_REGION_NAME) region Storage URL - optional (OS_STORAGE_URL) storage_url Auth Token from alternate authentication - optional (OS_AUTH_TOKEN) auth_token AuthVersion - optional - set to (1,2,3) if your auth URL has no version (ST_AUTH_VERSION) auth_version Endpoint type to choose from the service catalogue (OS_ENDPOINT_TYPE) Choose a number from below, or type in your own value 1 / Public (default, choose this if not sure) \ public 2 / Internal (use internal service net) \ internal 3 / Admin \ admin endpoint_type Remote config -------------------- [test] env_auth true user key auth user_id domain tenant tenant_id tenant_domain region storage_url auth_token auth_version endpoint_type -------------------- y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d y该远程端名为remote确认后即可按第 2 节的方式使用。注意交互过程中的[test]段是 rclone 生成的待确认配置实际保存时以name输入的远程名作为段名。4. 标准配置项全表以下为 Swift 后端全部标准选项源自 swift.md 自动生成段与 Options 结构体 一一对应。每个选项都可通过配置文件键、命令行--swift-xxx标志或RCLONE_SWIFT_XXX环境变量设置。标志配置键环境变量类型默认值说明--swift-env-authenv_authRCLONE_SWIFT_ENV_AUTHboolfalse从标准 OpenStack 环境变量读取凭据选用后其余字段留空--swift-useruserRCLONE_SWIFT_USERstring—登录用户名OS_USERNAME--swift-keykeyRCLONE_SWIFT_KEYstring—API key 或密码OS_PASSWORD--swift-authauthRCLONE_SWIFT_AUTHstring—认证 URLOS_AUTH_URL可选值见第 3 节会话中的 Rackspace/Memset/OVH/Blomp 预设--swift-user-iduser_idRCLONE_SWIFT_USER_IDstring—v3 认证的用户 IDOS_USER_ID多数 Swift 系统留空--swift-domaindomainRCLONE_SWIFT_DOMAINstring—用户域v3 认证OS_USER_DOMAIN_NAME--swift-tenanttenantRCLONE_SWIFT_TENANTstring—租户名v1 认证可选其他版本必填其一OS_TENANT_NAME或OS_PROJECT_NAME--swift-tenant-idtenant_idRCLONE_SWIFT_TENANT_IDstring—租户 IDOS_TENANT_ID--swift-tenant-domaintenant_domainRCLONE_SWIFT_TENANT_DOMAINstring—租户域v3 认证OS_PROJECT_DOMAIN_NAME--swift-regionregionRCLONE_SWIFT_REGIONstring—区域名OS_REGION_NAME--swift-storage-urlstorage_urlRCLONE_SWIFT_STORAGE_URLstring—存储 URLOS_STORAGE_URL--swift-auth-tokenauth_tokenRCLONE_SWIFT_AUTH_TOKENstring—外部认证得到的 TokenOS_AUTH_TOKEN--swift-application-credential-idapplication_credential_idRCLONE_SWIFT_APPLICATION_CREDENTIAL_IDstring—应用凭据 IDOS_APPLICATION_CREDENTIAL_ID--swift-application-credential-nameapplication_credential_nameRCLONE_SWIFT_APPLICATION_CREDENTIAL_NAMEstring—应用凭据名OS_APPLICATION_CREDENTIAL_NAME--swift-application-credential-secretapplication_credential_secretRCLONE_SWIFT_APPLICATION_CREDENTIAL_SECRETstring—应用凭据密钥OS_APPLICATION_CREDENTIAL_SECRET--swift-auth-versionauth_versionRCLONE_SWIFT_AUTH_VERSIONint0认证 URL 不带版本号时设为 1/2/3ST_AUTH_VERSION--swift-endpoint-typeendpoint_typeRCLONE_SWIFT_ENDPOINT_TYPEstringpublic服务目录端点类型public默认拿不准就选它/internal内网/admin--swift-storage-policystorage_policyRCLONE_SWIFT_STORAGE_POLICYstring新建容器时的存储策略默认、pcsOVH Public Cloud Storage、pcaOVH Public Cloud Archive创建后不可更改在源码中这些字段被解析进 Options 结构体随后由swiftConnection源码映射为swift.Connection的UserName、ApiKey、AuthUrl、Tenant、EndpointType等字段并应用全局--connect-timeout/--timeout放大 10 倍与 rclone 的 HTTP transport。5. 认证方式详解5.1 从 OpenStack 凭据文件配置OpenStack 凭据文件通常长这样去掉注释后export OS_AUTH_URLhttps://a.provider.net/v2.0 export OS_TENANT_IDffffffffffffffffffffffffffffffff export OS_TENANT_NAME1234567890123456 export OS_USERNAME123abc567xy echo Please enter your OpenStack Password: read -sr OS_PASSWORD_INPUT export OS_PASSWORD$OS_PASSWORD_INPUT export OS_REGION_NAMESBG1 if [ -z $OS_REGION_NAME ]; then unset OS_REGION_NAME; fi对应的 rclone 配置文件中把$OS_USERNAME等占位符替换为变量实际值上例中OS_USERNAME是123abc567xy[remote] type swift user $OS_USERNAME key $OS_PASSWORD auth $OS_AUTH_URL tenant $OS_TENANT_NAME注意region可能需要也可能不需要设置——建议先不设置试一下。5.2 从环境变量配置env_auth如果偏好使用标准 OpenStack 环境变量配置时选env_auth true并把其余字段全部留空。rclone 随后会用标准 OpenStack 环境变量补全任何空的配置项——源码中对应swiftConnection里的c.ApplyEnvironment()调用源码变量清单即ncw/swift库Connection.ApplyEnvironment所支持的那一套OS_USERNAME、OS_PASSWORD、OS_AUTH_URL、OS_TENANT_NAME、OS_REGION_NAME等。5.3 外部认证auth_token storage_url如果 OpenStack 使用了 rclone 或底层 swift 库尚未支持的非标准认证方式可以先在外部完成认证例如手动执行 openstack 命令换取 token然后只传auth_token与storage_url两个配置项。两者同时提供时其余认证变量全部被忽略——rclone 不会尝试认证而是假定已认证并直接使用这两个值访问服务。实现上这一行为由 auth.go 中的auth类型完成它是一个swift.Authenticator装饰器StorageUrl()/Token()优先返回外部传入的固定值仅在未提供时才回落到父认证器newAuth 在认证完成后包裹原认证器允许只覆盖二者之一。源码中的错误处理也很直白应用凭据缺少 secret、或既无auth又无storage_urlauth_token时swiftConnection会分别报key not found、auth not found、user name or user id not found for authentication。5.4 不使用配置文件也可以完全不写配置文件用环境变量方式source openstack-credentials-file export RCLONE_CONFIG_MYREMOTE_TYPEswift export RCLONE_CONFIG_MYREMOTE_ENV_AUTHtrue rclone lsd myremote:6. 大对象处理5 GiB 限制与分块上传Swift 不能透明存储超过5 GiB的文件因此 rclone 引入分块机制这也是 Swift 后端最复杂的部分。相关选项详见第 8 节高级选项全表为chunk_size、no_chunk、no_large_objects、use_segments_container。6.1 分块判定与 DLO 上传流程分块判定的源码逻辑在 Object.Updateif (size int64(o.fs.opt.ChunkSize) || (size -1 !o.fs.opt.NoChunk)) !o.fs.opt.NoLargeObjects { err o.updateChunks(ctx, in, headers, size, contentType)即文件大于chunk_size默认5Gi见 defaultChunkSize 常量这也是其最大取值或是无确定长度的流式上传size -1且未设no_chunk时走 updateChunks 分块路径按 Swift 的动态大对象DLO方式上传newSegmentedUpload源码为本次上传生成唯一路径目标路径/时间戳-128字符随机串/段文件按00000000、00000001…… 编号segmentPath循环上传各段失败时若leave_parts_on_error为false默认onFail会BulkDelete 已上传的失败段源码避免产生孤儿段。设为true则可跨会话断点续传全部段就绪后 uploadManifest 上传一个 0 字节 manifest 对象携带X-Object-Manifest头指向段集合完成 DLO 组装。6.2 段的存放位置_segments 容器 vs .file-segments 目录use_segments_containerTristate默认unset决定段的位置true段放入目标容器名_segments附加容器原容器无重复数据false段放入容器根下的.file-segments/目录列举时该目录被隐藏listContainerRoot 中的过滤逻辑unset默认rclone 自动选择。判定规则在 NewFsWithConnection——默认取false除非authURL 命中已知需要true的正则needFileSegmentsDirectoryain.net/blomp.com/praetector.com/signmy.name/rackfactory.com即 Rackspace/Blomp 系命中时 DEBUG 日志会打印Auto set use_segments_container to ...。文档也说明部分服务商如 Blomp不允许创建附加容器必须用目录模式。创建_segments容器时makeContainer 会把父容器的X-Storage-Policy复制过去fetchStoragePolicy 先 HEAD 父容器读取策略保证段与主体存储策略一致。6.3 无大对象环境的性能开关no_large_objects设为true后rclone 假定不存在 SLO/DLO从而省去识别大对象所需的 HEAD 请求识别逻辑 isLargeObject 会直接返回 false在 swift 到 swift 加--checksum的传输中性能提升明显。该选项隐含no_chunk不再有任何分块上传大于 5 GiB 的文件将直接上传失败。注意风险若环境中实际存在 SLO/DLO下载仍会成功但 hash 会不正确Remove/Copy 等操作会失败。7. 修改时间、MD5 与增量同步7.1 mtime 存储在对象元数据中修改时间以X-Object-Meta-Mtime元数据epoch 浮点数精确到 1 ns存储在对象上。这是事实标准官方 python-swiftclient 等也如此。实现见 Object.SetModTime写入与 Object.ModTime读取。读取 mtime 需要一次额外的元数据 API 调用因此后端 Features 声明了SlowModTime: true源码。配合--update与--use-server-modtime使用时ModTime()会跳过元数据读取、直接返回对象最后上传时间o.lastModified见 ModTime 首行分支从而省掉额外 API 调用用“本地 mtime 比最后上传时间新”来判断是否需要上传——这对大量文件的场景效率更高。7.2 MD5 支持与大对象例外Swift 后端声明支持 MD5Hashes。但Swift API 对分段文件SLO/DLO不返回正确的 MD5SUM因此 rclone 对这类对象返回空 hash 而不做校验——源码中Object.Hash先检测X-Object-Manifest/X-Static-Large-Object头命中即返回空值源码。这就是文档“Limitations”一节的实现依据。另一个 Swift 特有细节列举时 DLO 会以 0 字节返回rclone 在 newObjectWithInfo 中为所有非目录标记的 0 字节对象补一次完整元数据读取来修正大小no_large_objects开启时跳过。7.3 文件名编码与受限字符默认编码为Slash,InvalidUtf8SharedOptions 中 encoding 默认值受限字符替换表如下字符值替换为NUL0x00␀/0x2F无效 UTF-8 字节同样会被替换因为它们无法用于 JSON 字符串参见 overview 的 Invalid UTF-8 一节。7.4 --fast-listSwift 支持--fast-list以更多内存换取更少的事务数一次递归列举代替逐目录遍历。ListR实现位于 源码选项说明见 flags.md。8. 高级选项全表以下为 Swift 后端全部高级选项对应 swift.md 自动生成段定义见 SharedOptions标志配置键环境变量类型默认值说明--swift-leave-parts-on-errorleave_parts_on_errorRCLONE_SWIFT_LEAVE_PARTS_ON_ERRORboolfalse失败时不中止abort分块上传跨会话续传时应设为true--swift-fetch-until-empty-pagefetch_until_empty_pageRCLONE_SWIFT_FETCH_UNTIL_EMPTY_PAGEboolfalse分页时始终取到空页为止列举对象偏少或重复 sync 复制了未变对象时考虑启用安全但可能多发 API 调用--swift-partial-page-fetch-thresholdpartial_page_fetch_thresholdRCLONE_SWIFT_PARTIAL_PAGE_FETCH_THRESHOLDint0当前页大小达到上限百分比阈值时继续取下一页用途同上是一对分页兼容 workaround--swift-chunk-sizechunk_sizeRCLONE_SWIFT_CHUNK_SIZESizeSuffix5Gi超过该大小即分块5 GiB 为最大取值即默认下只有更大的文件才被分块最小取值为 1 字节checkUploadChunkSize--swift-no-chunkno_chunkRCLONE_SWIFT_NO_CHUNKboolfalse流式上传rcat、mount --vfs-cache-mode off时不分块将流式上传上限限制在 5 GiB换来更易处理且带 MD5SUM 的对象普通 copy 仍按chunk_size分块--swift-no-large-objectsno_large_objectsRCLONE_SWIFT_NO_LARGE_OBJECTSboolfalse禁用 SLO/DLO 支持省去 HEAD 请求大幅提升性能尤其--checksum的 swift→swift 传输隐含no_chunk5 GiB 文件上传会失败--swift-use-segments-containeruse_segments_containerRCLONE_SWIFT_USE_SEGMENTS_CONTAINERTristateunset段存放位置选择true_segments附加容器false容器根.file-segments目录Blomp 等必须unset自动判定见 6.2 节--swift-encodingencodingRCLONE_SWIFT_ENCODINGEncodingSlash,InvalidUtf8后端文件名编码规则--swift-descriptiondescriptionRCLONE_SWIFT_DESCRIPTIONstring—远程端描述其中fetch_until_empty_page/partial_page_fetch_threshold两个参数会被原样传入 swift 客户端swiftConnection 中的赋值用于兼容未正确实现分页的 Swift 服务端。9. 限流、重试与错误处理Swift 后端对 API 调用统一走 pacer初始化最小休眠 10 ms并按 HTTP 状态码决定重试var retryErrorCodes []int{ 401, // Unauthorized (e.g. Token has expired) 408, // Request Timeout 409, // Conflict 429, // Rate exceeded 500, // Get occasional 500 Internal Server Error 503, // Service Unavailable/Slow Down - Reduce your request rate 504, // Gateway Time-out }retryErrorCodes 与 shouldRetry对 429 响应还会解析Retry-After头shouldRetryHeaders不超过 60 秒则立即短暂休眠后重试超过 60 秒则安排延迟重试——这正是第 11 节 OVH 归档场景中出现NOTICE: Received retry after error - sleeping until ...消息的来源。10. 已知限制LimitationsSwift API 对分段文件动态/静态大对象不返回正确的 MD5SUMrclone 不会对这类对象检查或使用 MD5SUM非分块对象≤5 GiB的 MD5 可用且是后端唯一支持的 hash 类型修改时间依赖对象元数据默认会引入额外元数据请求可用--use-server-modtime规避见 7.1 节。11. 故障排查Troubleshooting11.1Failed to create file system for remote:: Bad Request由于底层 swift 库的特性Swift 认证失败时返回的是含糊的 “Bad Request” 而不是更合理的错误。这通常意味着用户名/密码错误可用--dump bodies进一步排查。另一种可能是不该设置 region 时设置了 region例如 OVH。11.2Failed to create file system: Response didnt have storage url and auth token最常见原因是配置 swift 远程端时漏填了 tenant租户。12. 案例接入 OVH Cloud Archive用rclone config配置swift后端选择 OVH 的 auth URL并把storage_policy设为pcaOVH Public Cloud Archive上传与普通对象存储无异直接运行move/copy/sync即可。上传后的对象在 OVH 控制台显示为 “Frozen”冻结状态取回正常执行rclone copy。如果对象处于冻结状态rclone 会请求解冻全部对象并在输出末尾打印如下消息并等待2019/03/23 13:06:33 NOTICE: Received retry after error - sleeping until 2019-03-23T13:16:33.48165716401:00 (9m59.99985121s)rclone 会等待服务端指定的时间由 429 响应的Retry-After头驱动见第 9 节后自动重试 copy。13. 相关源码与测试入口后端主实现backend/swift/swift.go连接/认证、列举、大对象分块、hash、ModTime外部认证装饰器backend/swift/auth.go测试backend/swift/swift_test.go接口测试、backend/swift/swift_internal_test.go内部逻辑测试如编码、路径拆分等文档docs/content/swift.md其中“Standard options / Advanced options”为make backenddocs从fs.RegInfo自动生成文件内保留了autogenerated options标记修改选项后应以该流程校验文档同步性。【免费下载链接】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），仅供参考 rclone Swift 后端完整实践：OpenStack 对象存储的配置、认证、大对象分块与分页调优
rclone Swift 后端完整实践OpenStack 对象存储的配置、认证、大对象分块与分页调优【免费下载链接】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本文围绕 rclone 仓库中的 Swift 后端文档 展开系统讲解 SwiftOpenStack Object Storage远程端的完整配置流程、OpenStack 标准认证变量、5 GiB 大对象SLO/DLO分块上传机制、修改时间与 MD5 的存储方式以及分页、重试等高级调优选项读完后可直接完成 Rackspace Cloud Files、OVH Object Storage 等 Swift 兼容服务的接入与运维并能结合 后端源码 理解每个选项在底层的具体行为。1. Swift 后端是什么rclone 的swift后端对接OpenStack Object StorageSwift协议。凡是实现了该协议的存储服务都可以直接作为远程端使用典型商业实现包括 Rackspace Cloud Files、Memset Memstore、OVH Object Storage、Oracle Cloud Storage、Blomp Cloud Storage、IBM Cloud Object Storage (Swift) 等。后端的注册入口在 swift.gofs.Register(fs.RegInfo{ Name: swift, Description: OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH), NewFs: NewFs, ... })该后端基于github.com/ncw/swift/v2客户端库实现见 swift.go 的 import从源码结构看它实现了fs.Purger、fs.PutStreamer、fs.Copier、fs.ListRer、fs.ListPer、fs.MimeTyper等接口接口断言即支持服务端 Copy、流式上传、递归列举与容器清空。路径规范Swift 是桶bucket型后端容器container对应 bucket。路径写作remote:containerlsd命令下remote:列出全部容器容器内还可带子目录例如remote:container/path/to/dir。2. 基础操作命令配置完成后常用命令如下remote为远程端名称# 列出所有容器 rclone lsd remote: # 创建新容器 rclone mkdir remote:container # 列出容器内容 rclone ls remote:container # 把本地目录同步到远程容器并删除容器中多余文件 rclone sync --interactive /home/local/directory remote:container其中--interactive会逐条确认每个删除动作。列举时 rclone 使用Limit: 1000的分页常量读取目录listChunks 常量根级别列举容器走listContainers源码并会把容器状态写入 bucket 缓存以减少重复的“容器是否存在”探测。3. 交互式配置rclone config运行rclone config进入交互式配置。以下是文档给出的完整配置会话示例No remotes found, make a new one\? n) New remote s) Set configuration password q) Quit config n/s/q n name remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / OpenStack Swift (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH) \ swift [snip] Storage swift Get swift credentials from environment variables in standard OpenStack form. Choose a number from below, or type in your own value 1 / Enter swift credentials in the next step \ false 2 / Get swift credentials from environment vars. Leave other fields blank if using this. \ true env_auth true User name to log in (OS_USERNAME). user API key or password (OS_PASSWORD). key Authentication URL for server (OS_AUTH_URL). Choose a number from below, or type in your own value 1 / Rackspace US \ https://auth.api.rackspacecloud.com/v1.0 2 / Rackspace UK \ https://lon.auth.api.rackspacecloud.com/v1.0 3 / Rackspace v2 \ https://identity.api.rackspacecloud.com/v2.0 4 / Memset Memstore UK \ https://auth.storage.memset.com/v1.0 5 / Memset Memstore UK v2 \ https://auth.storage.memset.com/v2.0 6 / OVH \ https://auth.cloud.ovh.net/v3 7 / Blomp Cloud Storage \ https://authenticate.ain.net auth User ID to log in - optional - most swift systems use user and leave this blank (v3 auth) (OS_USER_ID). user_id User domain - optional (v3 auth) (OS_USER_DOMAIN_NAME) domain Tenant name - optional for v1 auth, this or tenant_id required otherwise (OS_TENANT_NAME or OS_PROJECT_NAME) tenant Tenant ID - optional for v1 auth, this or tenant required otherwise (OS_TENANT_ID) tenant_id Tenant domain - optional (v3 auth) (OS_PROJECT_DOMAIN_NAME) tenant_domain Region name - optional (OS_REGION_NAME) region Storage URL - optional (OS_STORAGE_URL) storage_url Auth Token from alternate authentication - optional (OS_AUTH_TOKEN) auth_token AuthVersion - optional - set to (1,2,3) if your auth URL has no version (ST_AUTH_VERSION) auth_version Endpoint type to choose from the service catalogue (OS_ENDPOINT_TYPE) Choose a number from below, or type in your own value 1 / Public (default, choose this if not sure) \ public 2 / Internal (use internal service net) \ internal 3 / Admin \ admin endpoint_type Remote config -------------------- [test] env_auth true user key auth user_id domain tenant tenant_id tenant_domain region storage_url auth_token auth_version endpoint_type -------------------- y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d y该远程端名为remote确认后即可按第 2 节的方式使用。注意交互过程中的[test]段是 rclone 生成的待确认配置实际保存时以name输入的远程名作为段名。4. 标准配置项全表以下为 Swift 后端全部标准选项源自 swift.md 自动生成段与 Options 结构体 一一对应。每个选项都可通过配置文件键、命令行--swift-xxx标志或RCLONE_SWIFT_XXX环境变量设置。标志配置键环境变量类型默认值说明--swift-env-authenv_authRCLONE_SWIFT_ENV_AUTHboolfalse从标准 OpenStack 环境变量读取凭据选用后其余字段留空--swift-useruserRCLONE_SWIFT_USERstring—登录用户名OS_USERNAME--swift-keykeyRCLONE_SWIFT_KEYstring—API key 或密码OS_PASSWORD--swift-authauthRCLONE_SWIFT_AUTHstring—认证 URLOS_AUTH_URL可选值见第 3 节会话中的 Rackspace/Memset/OVH/Blomp 预设--swift-user-iduser_idRCLONE_SWIFT_USER_IDstring—v3 认证的用户 IDOS_USER_ID多数 Swift 系统留空--swift-domaindomainRCLONE_SWIFT_DOMAINstring—用户域v3 认证OS_USER_DOMAIN_NAME--swift-tenanttenantRCLONE_SWIFT_TENANTstring—租户名v1 认证可选其他版本必填其一OS_TENANT_NAME或OS_PROJECT_NAME--swift-tenant-idtenant_idRCLONE_SWIFT_TENANT_IDstring—租户 IDOS_TENANT_ID--swift-tenant-domaintenant_domainRCLONE_SWIFT_TENANT_DOMAINstring—租户域v3 认证OS_PROJECT_DOMAIN_NAME--swift-regionregionRCLONE_SWIFT_REGIONstring—区域名OS_REGION_NAME--swift-storage-urlstorage_urlRCLONE_SWIFT_STORAGE_URLstring—存储 URLOS_STORAGE_URL--swift-auth-tokenauth_tokenRCLONE_SWIFT_AUTH_TOKENstring—外部认证得到的 TokenOS_AUTH_TOKEN--swift-application-credential-idapplication_credential_idRCLONE_SWIFT_APPLICATION_CREDENTIAL_IDstring—应用凭据 IDOS_APPLICATION_CREDENTIAL_ID--swift-application-credential-nameapplication_credential_nameRCLONE_SWIFT_APPLICATION_CREDENTIAL_NAMEstring—应用凭据名OS_APPLICATION_CREDENTIAL_NAME--swift-application-credential-secretapplication_credential_secretRCLONE_SWIFT_APPLICATION_CREDENTIAL_SECRETstring—应用凭据密钥OS_APPLICATION_CREDENTIAL_SECRET--swift-auth-versionauth_versionRCLONE_SWIFT_AUTH_VERSIONint0认证 URL 不带版本号时设为 1/2/3ST_AUTH_VERSION--swift-endpoint-typeendpoint_typeRCLONE_SWIFT_ENDPOINT_TYPEstringpublic服务目录端点类型public默认拿不准就选它/internal内网/admin--swift-storage-policystorage_policyRCLONE_SWIFT_STORAGE_POLICYstring新建容器时的存储策略默认、pcsOVH Public Cloud Storage、pcaOVH Public Cloud Archive创建后不可更改在源码中这些字段被解析进 Options 结构体随后由swiftConnection源码映射为swift.Connection的UserName、ApiKey、AuthUrl、Tenant、EndpointType等字段并应用全局--connect-timeout/--timeout放大 10 倍与 rclone 的 HTTP transport。5. 认证方式详解5.1 从 OpenStack 凭据文件配置OpenStack 凭据文件通常长这样去掉注释后export OS_AUTH_URLhttps://a.provider.net/v2.0 export OS_TENANT_IDffffffffffffffffffffffffffffffff export OS_TENANT_NAME1234567890123456 export OS_USERNAME123abc567xy echo Please enter your OpenStack Password: read -sr OS_PASSWORD_INPUT export OS_PASSWORD$OS_PASSWORD_INPUT export OS_REGION_NAMESBG1 if [ -z $OS_REGION_NAME ]; then unset OS_REGION_NAME; fi对应的 rclone 配置文件中把$OS_USERNAME等占位符替换为变量实际值上例中OS_USERNAME是123abc567xy[remote] type swift user $OS_USERNAME key $OS_PASSWORD auth $OS_AUTH_URL tenant $OS_TENANT_NAME注意region可能需要也可能不需要设置——建议先不设置试一下。5.2 从环境变量配置env_auth如果偏好使用标准 OpenStack 环境变量配置时选env_auth true并把其余字段全部留空。rclone 随后会用标准 OpenStack 环境变量补全任何空的配置项——源码中对应swiftConnection里的c.ApplyEnvironment()调用源码变量清单即ncw/swift库Connection.ApplyEnvironment所支持的那一套OS_USERNAME、OS_PASSWORD、OS_AUTH_URL、OS_TENANT_NAME、OS_REGION_NAME等。5.3 外部认证auth_token storage_url如果 OpenStack 使用了 rclone 或底层 swift 库尚未支持的非标准认证方式可以先在外部完成认证例如手动执行 openstack 命令换取 token然后只传auth_token与storage_url两个配置项。两者同时提供时其余认证变量全部被忽略——rclone 不会尝试认证而是假定已认证并直接使用这两个值访问服务。实现上这一行为由 auth.go 中的auth类型完成它是一个swift.Authenticator装饰器StorageUrl()/Token()优先返回外部传入的固定值仅在未提供时才回落到父认证器newAuth 在认证完成后包裹原认证器允许只覆盖二者之一。源码中的错误处理也很直白应用凭据缺少 secret、或既无auth又无storage_urlauth_token时swiftConnection会分别报key not found、auth not found、user name or user id not found for authentication。5.4 不使用配置文件也可以完全不写配置文件用环境变量方式source openstack-credentials-file export RCLONE_CONFIG_MYREMOTE_TYPEswift export RCLONE_CONFIG_MYREMOTE_ENV_AUTHtrue rclone lsd myremote:6. 大对象处理5 GiB 限制与分块上传Swift 不能透明存储超过5 GiB的文件因此 rclone 引入分块机制这也是 Swift 后端最复杂的部分。相关选项详见第 8 节高级选项全表为chunk_size、no_chunk、no_large_objects、use_segments_container。6.1 分块判定与 DLO 上传流程分块判定的源码逻辑在 Object.Updateif (size int64(o.fs.opt.ChunkSize) || (size -1 !o.fs.opt.NoChunk)) !o.fs.opt.NoLargeObjects { err o.updateChunks(ctx, in, headers, size, contentType)即文件大于chunk_size默认5Gi见 defaultChunkSize 常量这也是其最大取值或是无确定长度的流式上传size -1且未设no_chunk时走 updateChunks 分块路径按 Swift 的动态大对象DLO方式上传newSegmentedUpload源码为本次上传生成唯一路径目标路径/时间戳-128字符随机串/段文件按00000000、00000001…… 编号segmentPath循环上传各段失败时若leave_parts_on_error为false默认onFail会BulkDelete 已上传的失败段源码避免产生孤儿段。设为true则可跨会话断点续传全部段就绪后 uploadManifest 上传一个 0 字节 manifest 对象携带X-Object-Manifest头指向段集合完成 DLO 组装。6.2 段的存放位置_segments 容器 vs .file-segments 目录use_segments_containerTristate默认unset决定段的位置true段放入目标容器名_segments附加容器原容器无重复数据false段放入容器根下的.file-segments/目录列举时该目录被隐藏listContainerRoot 中的过滤逻辑unset默认rclone 自动选择。判定规则在 NewFsWithConnection——默认取false除非authURL 命中已知需要true的正则needFileSegmentsDirectoryain.net/blomp.com/praetector.com/signmy.name/rackfactory.com即 Rackspace/Blomp 系命中时 DEBUG 日志会打印Auto set use_segments_container to ...。文档也说明部分服务商如 Blomp不允许创建附加容器必须用目录模式。创建_segments容器时makeContainer 会把父容器的X-Storage-Policy复制过去fetchStoragePolicy 先 HEAD 父容器读取策略保证段与主体存储策略一致。6.3 无大对象环境的性能开关no_large_objects设为true后rclone 假定不存在 SLO/DLO从而省去识别大对象所需的 HEAD 请求识别逻辑 isLargeObject 会直接返回 false在 swift 到 swift 加--checksum的传输中性能提升明显。该选项隐含no_chunk不再有任何分块上传大于 5 GiB 的文件将直接上传失败。注意风险若环境中实际存在 SLO/DLO下载仍会成功但 hash 会不正确Remove/Copy 等操作会失败。7. 修改时间、MD5 与增量同步7.1 mtime 存储在对象元数据中修改时间以X-Object-Meta-Mtime元数据epoch 浮点数精确到 1 ns存储在对象上。这是事实标准官方 python-swiftclient 等也如此。实现见 Object.SetModTime写入与 Object.ModTime读取。读取 mtime 需要一次额外的元数据 API 调用因此后端 Features 声明了SlowModTime: true源码。配合--update与--use-server-modtime使用时ModTime()会跳过元数据读取、直接返回对象最后上传时间o.lastModified见 ModTime 首行分支从而省掉额外 API 调用用“本地 mtime 比最后上传时间新”来判断是否需要上传——这对大量文件的场景效率更高。7.2 MD5 支持与大对象例外Swift 后端声明支持 MD5Hashes。但Swift API 对分段文件SLO/DLO不返回正确的 MD5SUM因此 rclone 对这类对象返回空 hash 而不做校验——源码中Object.Hash先检测X-Object-Manifest/X-Static-Large-Object头命中即返回空值源码。这就是文档“Limitations”一节的实现依据。另一个 Swift 特有细节列举时 DLO 会以 0 字节返回rclone 在 newObjectWithInfo 中为所有非目录标记的 0 字节对象补一次完整元数据读取来修正大小no_large_objects开启时跳过。7.3 文件名编码与受限字符默认编码为Slash,InvalidUtf8SharedOptions 中 encoding 默认值受限字符替换表如下字符值替换为NUL0x00␀/0x2F无效 UTF-8 字节同样会被替换因为它们无法用于 JSON 字符串参见 overview 的 Invalid UTF-8 一节。7.4 --fast-listSwift 支持--fast-list以更多内存换取更少的事务数一次递归列举代替逐目录遍历。ListR实现位于 源码选项说明见 flags.md。8. 高级选项全表以下为 Swift 后端全部高级选项对应 swift.md 自动生成段定义见 SharedOptions标志配置键环境变量类型默认值说明--swift-leave-parts-on-errorleave_parts_on_errorRCLONE_SWIFT_LEAVE_PARTS_ON_ERRORboolfalse失败时不中止abort分块上传跨会话续传时应设为true--swift-fetch-until-empty-pagefetch_until_empty_pageRCLONE_SWIFT_FETCH_UNTIL_EMPTY_PAGEboolfalse分页时始终取到空页为止列举对象偏少或重复 sync 复制了未变对象时考虑启用安全但可能多发 API 调用--swift-partial-page-fetch-thresholdpartial_page_fetch_thresholdRCLONE_SWIFT_PARTIAL_PAGE_FETCH_THRESHOLDint0当前页大小达到上限百分比阈值时继续取下一页用途同上是一对分页兼容 workaround--swift-chunk-sizechunk_sizeRCLONE_SWIFT_CHUNK_SIZESizeSuffix5Gi超过该大小即分块5 GiB 为最大取值即默认下只有更大的文件才被分块最小取值为 1 字节checkUploadChunkSize--swift-no-chunkno_chunkRCLONE_SWIFT_NO_CHUNKboolfalse流式上传rcat、mount --vfs-cache-mode off时不分块将流式上传上限限制在 5 GiB换来更易处理且带 MD5SUM 的对象普通 copy 仍按chunk_size分块--swift-no-large-objectsno_large_objectsRCLONE_SWIFT_NO_LARGE_OBJECTSboolfalse禁用 SLO/DLO 支持省去 HEAD 请求大幅提升性能尤其--checksum的 swift→swift 传输隐含no_chunk5 GiB 文件上传会失败--swift-use-segments-containeruse_segments_containerRCLONE_SWIFT_USE_SEGMENTS_CONTAINERTristateunset段存放位置选择true_segments附加容器false容器根.file-segments目录Blomp 等必须unset自动判定见 6.2 节--swift-encodingencodingRCLONE_SWIFT_ENCODINGEncodingSlash,InvalidUtf8后端文件名编码规则--swift-descriptiondescriptionRCLONE_SWIFT_DESCRIPTIONstring—远程端描述其中fetch_until_empty_page/partial_page_fetch_threshold两个参数会被原样传入 swift 客户端swiftConnection 中的赋值用于兼容未正确实现分页的 Swift 服务端。9. 限流、重试与错误处理Swift 后端对 API 调用统一走 pacer初始化最小休眠 10 ms并按 HTTP 状态码决定重试var retryErrorCodes []int{ 401, // Unauthorized (e.g. Token has expired) 408, // Request Timeout 409, // Conflict 429, // Rate exceeded 500, // Get occasional 500 Internal Server Error 503, // Service Unavailable/Slow Down - Reduce your request rate 504, // Gateway Time-out }retryErrorCodes 与 shouldRetry对 429 响应还会解析Retry-After头shouldRetryHeaders不超过 60 秒则立即短暂休眠后重试超过 60 秒则安排延迟重试——这正是第 11 节 OVH 归档场景中出现NOTICE: Received retry after error - sleeping until ...消息的来源。10. 已知限制LimitationsSwift API 对分段文件动态/静态大对象不返回正确的 MD5SUMrclone 不会对这类对象检查或使用 MD5SUM非分块对象≤5 GiB的 MD5 可用且是后端唯一支持的 hash 类型修改时间依赖对象元数据默认会引入额外元数据请求可用--use-server-modtime规避见 7.1 节。11. 故障排查Troubleshooting11.1Failed to create file system for remote:: Bad Request由于底层 swift 库的特性Swift 认证失败时返回的是含糊的 “Bad Request” 而不是更合理的错误。这通常意味着用户名/密码错误可用--dump bodies进一步排查。另一种可能是不该设置 region 时设置了 region例如 OVH。11.2Failed to create file system: Response didnt have storage url and auth token最常见原因是配置 swift 远程端时漏填了 tenant租户。12. 案例接入 OVH Cloud Archive用rclone config配置swift后端选择 OVH 的 auth URL并把storage_policy设为pcaOVH Public Cloud Archive上传与普通对象存储无异直接运行move/copy/sync即可。上传后的对象在 OVH 控制台显示为 “Frozen”冻结状态取回正常执行rclone copy。如果对象处于冻结状态rclone 会请求解冻全部对象并在输出末尾打印如下消息并等待2019/03/23 13:06:33 NOTICE: Received retry after error - sleeping until 2019-03-23T13:16:33.48165716401:00 (9m59.99985121s)rclone 会等待服务端指定的时间由 429 响应的Retry-After头驱动见第 9 节后自动重试 copy。13. 相关源码与测试入口后端主实现backend/swift/swift.go连接/认证、列举、大对象分块、hash、ModTime外部认证装饰器backend/swift/auth.go测试backend/swift/swift_test.go接口测试、backend/swift/swift_internal_test.go内部逻辑测试如编码、路径拆分等文档docs/content/swift.md其中“Standard options / Advanced options”为make backenddocs从fs.RegInfo自动生成文件内保留了autogenerated options标记修改选项后应以该流程校验文档同步性。【免费下载链接】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），仅供参考