Cache

存储系统

Cache

cache 远程存储包装了另一个现有的远程存储，并为诸如 rclone mount 之类的长期运行任务存储文件结构及其数据。

状态

缓存后端代码可以正常工作，但目前没有维护者，因此存在一些未解决的 bug 未得到修复。

缓存后端最终将被逐步淘汰，转而使用 VFS 缓存层，后者能更紧密地集成到 rclone 中。

在此之前，我们建议仅在你发现没有它就无法工作的情况下使用缓存后端。网上有许多文档描述了如何使用缓存后端来减少 API 调用，但总体而言，这些文档已经过时，在那些场景中不再需要使用缓存后端了。

配置

要开始使用，你只需要有一个可以用 cache 进行配置的现有远程存储。

以下是一个如何创建名为 test-cache 的远程存储的示例。首先运行：

 rclone config

这将引导你完成一个交互式的设置过程：

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> test-cache
Type of storage to configure.
Choose a number from below, or type in your own value
[snip]
XX / Cache a remote
   \ "cache"
[snip]
Storage> cache
Remote to cache.
Normally should contain a ':' and a path, e.g. "myremote:path/to/dir",
"myremote:bucket" or maybe "myremote:" (not recommended).
remote> local:/test
Optional: The URL of the Plex server
plex_url> http://127.0.0.1:32400
Optional: The username of the Plex user
plex_username> dummyusername
Optional: The password of the Plex user
y) Yes type in my own password
g) Generate random password
n) No leave this optional password blank
y/g/n> y
Enter the password:
password:
Confirm the password:
password:
The size of a chunk. Lower value good for slow connections but can affect seamless reading.
Default: 5M
Choose a number from below, or type in your own value
 1 / 1 MiB
   \ "1M"
 2 / 5 MiB
   \ "5M"
 3 / 10 MiB
   \ "10M"
chunk_size> 2
How much time should object info (file size, file hashes, etc.) be stored in cache. Use a very high value if you don't plan on changing the source FS from outside the cache.
Accepted units are: "s", "m", "h".
Default: 5m
Choose a number from below, or type in your own value
 1 / 1 hour
   \ "1h"
 2 / 24 hours
   \ "24h"
 3 / 24 hours
   \ "48h"
info_age> 2
The maximum size of stored chunks. When the storage grows beyond this size, the oldest chunks will be deleted.
Default: 10G
Choose a number from below, or type in your own value
 1 / 500 MiB
   \ "500M"
 2 / 1 GiB
   \ "1G"
 3 / 10 GiB
   \ "10G"
chunk_total_size> 3
Remote config
--------------------
[test-cache]
remote = local:/test
plex_url = http://127.0.0.1:32400
plex_username = dummyusername
plex_password = *** ENCRYPTED ***
chunk_size = 5M
info_age = 48h
chunk_total_size = 10G

你可以按照以下方式使用它：

列出你的驱动器顶级目录

rclone lsd test-cache:

列出你的驱动器中的所有文件

rclone ls test-cache:

启动缓存挂载

rclone mount --allow-other test-cache: /var/tmp/test-cache

写入特性

离线上传

为了使通过缓存进行的写入操作更加可靠，后端现在支持此功能，可通过指定 cache-tmp-upload-path 来启用。

使用此功能时，文件会经历以下状态：

上传开始（通常是通过在缓存远程存储上复制文件）
当文件复制到临时位置完成后，该文件成为缓存远程存储的一部分，其外观和行为与其他文件相同（包括读取操作）
经过 cache-tmp-wait-time 后，且该文件轮到上传时，将使用 rclone move 命令将文件移动到云存储提供商
在上传过程中，文件仍然可以读取，但大多数修改操作将被禁止
一旦移动完成，文件将解锁以允许修改，此时它就像其他普通文件一样
如果文件在从临时路径实际删除时正在通过 cache 进行读取，cache 会在不中断读取的情况下将源切换到云存储提供商（不过可能会有短暂的卡顿）

文件按顺序上传，一次只上传一个文件。上传任务将存储在队列中，并按照添加的顺序进行处理。队列和临时存储在重启后会保留，但可以在启动时使用 --cache-db-purge 标志清除。

写入支持

支持通过 cache 进行写入操作。需要注意的是，挂载的缓存远程存储不会为上传操作添加任何重试或回退机制。这将取决于被包装的远程存储的实现。为了实现可靠的写入，建议使用 离线上传 功能。

cache-writes 功能涵盖了一种特殊情况，当启用该功能时，文件数据将在上传的同时进行缓存，这样在上传完成后，文件数据可以立即从缓存存储中获取。

读取特性

多连接

为了应对运行 rclone 的本地 PC 与云存储提供商之间的高延迟问题，缓存远程存储可以将对云存储提供商的多个请求拆分为对较小文件块的请求，并在本地将这些块组合起来，这样在读取器通常需要数据之前，数据几乎可以立即可用。

这类似于在线播放媒体文件时的缓冲机制。Rclone 会围绕当前标记位置进行操作，但会始终尽力提前准备数据。

Plex 集成

与 Plex 有直接集成，这使得缓存能够在读取过程中检测文件是否正在播放。这有助于缓存根据需求调整对云存储提供商的查询方式。

扫描操作将使用最少数量的工作线程（1 个），而在确认文件正在播放时，缓存将部署配置数量的工作线程。

这种集成开启了进一步提高性能的可能性，未来将对此进行探索。

注意： 如果未配置 Plex 选项，cache 将按照其配置选项运行，不会调整任何设置。

如何启用？运行 rclone config 并在远程存储中添加所有 Plex 选项（端点、用户名和密码），该功能将自动启用。

受影响的设置：

cache-workers：在确认播放时为 配置的值，其他时间为 1

证书验证

当 Plex 服务器配置为仅接受安全连接时，可以使用 .plex.direct URL 来确保证书验证成功。这些 URL 由 Plex 内部用于安全连接到 Plex 服务器。

这些 URL 的格式如下：

https://ip-with-dots-replaced.server-hash.plex.direct:32400/

ip-with-dots-replaced 部分可以是任何 IPv4 地址，其中的点号已被替换为连字符，例如 127.0.0.1 变为 127-0-0-1。

要获取 server-hash 部分，最简单的方法是访问

https://plex.tv/api/resources?includeHttps=1&X-Plex-Token=your-plex-token

此页面将列出你账户下所有可用的 Plex 服务器，每个服务器至少有一个 .plex.direct 链接。复制一个 URL 并将 IP 地址替换为所需的地址。这可以用作 plex_url 的值。

已知问题

挂载和 –dir-cache-time

--dir-cache-time 控制着挂载层的第一层目录缓存。作为与 cache 后端独立的缓存机制，它将根据配置的时间管理自己的条目。

为了避免出现目录缓存数据过时，而 cache 中数据正确的情况，请尝试将 --dir-cache-time 设置为比 --cache-info-age 更短的时间。默认值已经按照这种方式进行了配置。

Windows 支持 - 实验性

Windows mount 功能存在一些问题，仍需要进一步研究。在针对此操作系统进行修复之前，应将其视为实验性的。

大多数问题似乎与 Linux 系列和 Windows 文件系统之间的差异有关，因为缓存严重依赖这些文件系统。

非常感谢你提供有关此操作系统上缓存行为的任何报告或反馈。

限流风险

缓存后端的未来版本将利用云存储提供商的池化功能进行同步，同时使通过它进行的写入操作更能容忍失败。

目前有一些增强功能正在开发中，但与此同时，存在一个合理的担忧，即过期的缓存列表可能会因对非常大的挂载进行重复查询而导致云存储提供商的限流或封禁。

一些建议：

不要为条目信息使用非常小的间隔（--cache-info-age）
虽然写入操作尚未优化，但你仍然可以通过 cache 进行写入，如果配置得当，这样做的好处是可以同时将文件添加到缓存中。

未来的增强功能：

cache 和 crypt

一个常见的场景是使用 crypt 远程存储在云存储提供商中对数据进行加密。crypt 使用类似的技术包装现有远程存储，并以无缝的方式处理这种转换。

按以下顺序包装远程存储存在一个问题： 云远程存储 -> crypt -> cache

在测试过程中，我发现按此顺序配置远程存储时会遇到很多封禁问题。我怀疑这可能与 crypt 在云存储提供商上打开文件的方式有关，这会让云存储提供商认为我们正在下载整个文件，而不是小文件块。按以下顺序组织远程存储会得到更好的结果： 云远程存储 -> cache -> crypt

绝对远程路径

cache 无法区分被包装远程存储的相对路径和绝对路径。 remote 配置设置和命令行中给出的任何路径都将按原样传递给被包装的远程存储，但在将文件块存储到磁盘时，路径将通过去除任何前导 / 字符而变为相对路径。

对于大多数后端类型，这种行为无关紧要，但有些后端中，前导 / 会改变有效目录，例如在 sftp 后端中，以 / 开头的路径相对于 SSH 服务器的根目录，而没有 / 的路径相对于用户主目录。因此，sftp:bin 和 sftp:/bin 将共享相同的缓存文件夹，即使它们在 SSH 服务器上代表不同的目录。

缓存和远程控制 (–rc)

缓存支持 rclone 中的新 --rc 模式，并可以通过以下端点进行远程控制：默认情况下，如果你不添加该标志，监听器将被禁用。

rc cache/expire

从缓存后端清除远程存储。支持清除目录或文件。如果缓存被 crypt 包装，它支持加密和未加密的文件名。

参数：

remote = 远程存储路径 (必需)
withData = true/false 以同时删除缓存数据（文件块） (可选，默认值为 false)

标准选项

以下是 cache（缓存远程存储）特定的标准选项。

–cache-remote

要缓存的远程存储。

通常应包含 : 和路径，例如 “myremote:path/to/dir”、“myremote:bucket” 或 “myremote:"（不推荐）。

属性：

配置项：remote
环境变量：RCLONE_CACHE_REMOTE
类型：字符串
是否必需：是

–cache-plex-url

Plex 服务器的 URL。

属性：

配置项：plex_url
环境变量：RCLONE_CACHE_PLEX_URL
类型：字符串
是否必需：否

–cache-plex-username

Plex 用户的用户名。

属性：

配置项：plex_username
环境变量：RCLONE_CACHE_PLEX_USERNAME
类型：字符串
是否必需：否

–cache-plex-password

Plex 用户的密码。

注意：输入此选项的值必须进行加密处理 - 请参阅 rclone obscure。

属性：

配置项：plex_password
环境变量：RCLONE_CACHE_PLEX_PASSWORD
类型：字符串
是否必需：否

–cache-chunk-size

文件块（部分文件数据）的大小。

对于较慢的连接，使用较小的数值。如果更改了块大小，任何已下载的块将失效，需要清除 cache-chunk-path，否则会出现意外的 EOF 错误。

属性：

配置项：chunk_size
环境变量：RCLONE_CACHE_CHUNK_SIZE
类型：SizeSuffix
默认值：5Mi
示例：
- “1M”
  - 1 MiB
- “5M”
  - 5 MiB
- “10M”
  - 10 MiB

–cache-info-age

缓存文件结构信息（目录列表、文件大小、时间等）的时长。如果所有写入操作都通过缓存进行，那么可以安全地将此值设置得非常大，因为缓存存储也会实时更新。

属性：

配置项：info_age
环境变量：RCLONE_CACHE_INFO_AGE
类型：Duration
默认值：6h0m0s
示例：
- “1h”
  - 1 小时
- “24h”
  - 24 小时
- “48h”
  - 48 小时

–cache-chunk-total-size

文件块在本地磁盘上可以占用的总大小。

如果缓存超过此值，它将开始删除最旧的文件块，直到低于此值。

属性：

配置项：chunk_total_size
环境变量：RCLONE_CACHE_CHUNK_TOTAL_SIZE
类型：SizeSuffix
默认值：10Gi
示例：
- “500M”
  - 500 MiB
- “1G”
  - 1 GiB
- “10G”
  - 10 GiB

高级选项

以下是 cache（缓存远程存储）特定的高级选项。

–cache-plex-token

用于身份验证的 Plex 令牌 - 通常自动设置。

属性：

配置项：plex_token
环境变量：RCLONE_CACHE_PLEX_TOKEN
类型：字符串
是否必需：否

–cache-plex-insecure

连接到 Plex 服务器时跳过所有证书验证。

属性：

配置项：plex_insecure
环境变量：RCLONE_CACHE_PLEX_INSECURE
类型：字符串
是否必需：否

–cache-db-path

存储文件结构元数据数据库的目录。

远程存储名称将用作数据库文件名。

属性：

配置项：db_path
环境变量：RCLONE_CACHE_DB_PATH
类型：字符串
默认值："$HOME/.cache/rclone/cache-backend”

–cache-chunk-path

缓存文件块的目录。

部分文件数据（文件块）在本地存储的路径。远程存储名称将追加到最终路径。

此配置遵循 --cache-db-path。如果你为 --cache-db-path 指定了自定义位置，而没有为 --cache-chunk-path 指定位置，则 --cache-chunk-path 将使用与 --cache-db-path 相同的路径。

属性：

配置项：chunk_path
环境变量：RCLONE_CACHE_CHUNK_PATH
类型：字符串
默认值："$HOME/.cache/rclone/cache-backend"

–cache-db-purge

在启动时清除此远程存储的所有缓存数据。

属性：

配置项：db_purge
环境变量：RCLONE_CACHE_DB_PURGE
类型：布尔值
默认值：false

–cache-chunk-clean-interval

缓存应多久对文件块存储进行一次清理。

默认值对大多数人来说应该是合适的。如果你发现缓存经常超过 “cache-chunk-total-size”，可以尝试降低此值，以强制更频繁地进行清理。

属性：

配置项：chunk_clean_interval
环境变量：RCLONE_CACHE_CHUNK_CLEAN_INTERVAL
类型：Duration
默认值：1m0s

–cache-read-retries

从缓存存储读取时的重试次数。

由于从缓存流中读取与下载文件数据是独立的，读取器可能会遇到缓存中没有更多数据的情况。大多数情况下，如果缓存无法再提供文件数据，这可能表示存在连接问题。

对于非常慢的连接，可以将此值增加到能够提供数据的程度，但你的体验会非常卡顿。

属性：

配置项：read_retries
环境变量：RCLONE_CACHE_READ_RETRIES
类型：整数
默认值：10

–cache-workers

应并行运行多少个工作线程来下载文件块。

较高的值意味着更多的并行处理（需要更好的 CPU）以及对云存储提供商更多的并发请求。这会影响多个方面，如云存储提供商的 API 限制、运行 rclone 的硬件压力，但也意味着流将更加流畅，读取器可以更快地获取数据。

注意：如果启用了可选的 Plex 集成，此设置将根据执行的读取类型进行调整，此处指定的值将用作最大工作线程数。

属性：

配置项：workers
环境变量：RCLONE_CACHE_WORKERS
类型：整数
默认值：4

–cache-chunk-no-memory

禁用流式传输期间用于存储文件块的内存缓存。

默认情况下，缓存会在流式传输期间将文件数据也保留在 RAM 中，以便尽快提供给读取器。

此临时数据在读取后会立即被清除，并且存储的文件块数量不会超过工作线程数。然而，根据其他设置（如 “cache-chunk-size” 和 “cache-workers”），如果同时存在并行流（同时读取多个文件），此内存占用可能会增加。

如果硬件允许，使用此功能可以在流式传输期间提供更好的整体性能，但如果本地机器没有足够的 RAM，也可以禁用此功能。

属性：

配置项：chunk_no_memory
环境变量：RCLONE_CACHE_CHUNK_NO_MEMORY
类型：布尔值
默认值：false

–cache-rps

限制每秒对源文件系统的请求数（-1 表示禁用）。

此设置对缓存每秒向云存储提供商远程存储发出的请求数设置了硬限制，并尝试通过在读取之间设置等待时间来遵守该值。

如果你发现通过缓存访问云存储提供商时被封禁或限制，并且知道较低的每秒请求数可以解决问题，则可以使用此设置。

所有其他设置的良好平衡应该会使此设置变得无用，但它仍然可供特殊情况使用。

注意：这将限制流式传输期间的请求数，但对云存储提供商的其他 API 调用（如目录列表）仍将正常进行。

属性：

配置项：rps
环境变量：RCLONE_CACHE_RPS
类型：整数
默认值：-1

–cache-writes

在通过文件系统写入时缓存文件数据。

如果你需要在通过缓存上传文件后立即读取这些文件，可以启用此标志，以便在上传期间将文件数据同时存储在缓存存储中。

属性：

配置项：writes
环境变量：RCLONE_CACHE_WRITES
类型：布尔值
默认值：false

–cache-tmp-upload-path

在文件上传之前保留临时文件的目录。

这是缓存将用作临时存储的路径，用于存储需要上传到云存储提供商的新文件。

指定一个值将启用此功能。如果不指定，则此功能将完全禁用，文件将直接上传到云存储提供商。

属性：

配置项：tmp_upload_path
环境变量：RCLONE_CACHE_TMP_UPLOAD_PATH
类型：字符串
是否必需：否

–cache-tmp-wait-time

文件在本地缓存中存储多长时间后再上传。

这是文件在临时位置 cache-tmp-upload-path 中必须等待的时间，然后才会被选择上传。

请注意，一次只上传一个文件，如果为此目的形成了队列，则上传可能需要更长时间才能开始。

属性：

配置项：tmp_wait_time
环境变量：RCLONE_CACHE_TMP_WAIT_TIME
类型：Duration
默认值：15s

–cache-db-wait-time

等待数据库可用的时间 - 0 表示无限期等待。

任何时候只能有一个进程打开数据库，因此 rclone 会等待此时间段，直到数据库可用，否则会给出错误。

如果将其设置为 0，则它将永远等待。

属性：

配置项：db_wait_time
环境变量：RCLONE_CACHE_DB_WAIT_TIME
类型：Duration
默认值：1s

–cache-description

远程存储的描述。

属性：

配置项：description
环境变量：RCLONE_CACHE_DESCRIPTION
类型：字符串
是否必需：否

后端命令

以下是 cache 后端特定的命令。

使用以下命令运行它们

rclone backend COMMAND remote:

下面的帮助信息将解释每个命令需要哪些参数。

有关如何传递选项和参数的更多信息，请参阅 backend 命令。

这些命令可以使用 rc 命令 backend/command 在运行的后端上执行。

stats

以 JSON 格式打印缓存后端的统计信息。

rclone backend stats remote: [选项] [<参数>+]

Box Chunker