第26章 Cloudreve 远程下载功能配置指南

第26章：远程下载

​Cloudreve 可以结合 aria2 或 qBittorrent 实现远程下载功能。用户可创建磁力链接、HTTP 链接（仅限 Aria2）及种子文件的下载任务。任务由服务器执行下载，完成后文件将自动归入用户目录。 从节点也支持远程下载，从而将任务分发至多台服务器，避免主节点资源过载。负责远程下载的每个节点需运行一套 Cloudreve 及下载器（Aria2/qBittorrent）实例，文件的下载与传输均在目标节点上完成。

​配置 添加节点 若需在从节点处理远程下载，请先参考从节点文档将节点添加至 Cloudreve。若计划在与 Cloudreve 主机相同的服务器上处理远程下载，可跳过此步骤。

准备下载器 请在目标节点服务器上安装 Aria2 或 qBittorrent。注意 qBittorrent 仅支持下载磁力链接或种子文件。确保下载器运行时与 Cloudreve 进程共享同一文件系统，至少需具备用于存储下载文件的共享挂载点。

Aria2 Aria2 安装请查阅官方文档。 启动 Aria2 时，需在配置文件中启用 RPC 服务并设置 RPC Secret 供后续使用。

ini # 启用 RPC 服务 enable-rpc=true # RPC 监听端口 rpc-listen-port=6800 # RPC 授权令牌，可自定义 rpc-secret=

也可通过命令行直接启动 Aria2 并指定 RPC 服务参数：

bash aria2c --enable-rpc --rpc-secret=your_rpc_secret --rpc-listen-port=6800

在官方镜像中使用 Aria2 Cloudreve 官方镜像已内置同容器运行的 Aria2，无需额外安装。其监听本地回环地址 6800 端口，且未设置 RPC 令牌。 若需进行 BT 下载，启动 Cloudreve 镜像时请将 6888 端口映射至宿主机，例如：

bash docker run -d --name cloudreve \ -p 5212:5212 \ -p 6888:6888 \ -p 6888:6888/udp \ ...

若条件允许，建议为 Cloudreve 容器使用 host 网络模式，以获得更优的传输性能：

bash docker run -d --name cloudreve \ --network host \ ...

qBittorrent 下载 4.4 以上版本的 qBittorrent，启动后在设置中启用 Web UI 服务，并配置用户名与密码。

配置节点 配置并启动下载器后，请在 Cloudreve 节点设置中勾选远程下载，并配置下载器参数：

RPC 服务器地址 / Web UI 地址 请输入 Aria2 RPC 服务器地址或 qBittorrent Web UI 地址。

RPC 授权令牌 / 访问凭证 请输入 Aria2 RPC Secret 或 qBittorrent Web UI 的用户名和密码。

临时下载目录 请指定下载文件的存储目录。若留空，系统将使用默认临时下载目录，通常位于与 Cloudreve 同级的 data/temp 目录下。Cloudreve 需具备该目录的读、写及执行权限。

重要 请确保该目录的绝对路径对 Cloudreve 和下载器均可访问，且两者指向同一目录。 在非容器环境中，通常不会出现问题。但若 Cloudreve 或下载器运行在容器中，由于文件系统隔离，Cloudreve 无法访问下载器下载的文件。（对于包含同容器运行 Aria2 的官方完整镜像，无需担心 Aria2 下载器路径问题）。

若 Cloudreve 运行在容器中，下载器运行在宿主机上，请将容器的 /cloudreve/data 目录挂载至宿主机的相同目录 /cloudreve/data；或在节点下载器配置中指定其他目录（如 /var/www/cloudreve/download/temp），并将该目录挂载至宿主机相同路径，例如：

bash docker run -d --name cloudreve \ -v /var/www/cloudreve/download/temp:/var/www/cloudreve/data/temp \ -p 5212:5212 \ cloudreve/cloudreve:latest

若下载器运行在容器中，Cloudreve 运行在宿主机上，请将宿主机上下载器对应的 /cloudreve/data 目录挂载至相同路径 /cloudreve/data；或在节点下载器配置中指定其他目录（如 /var/www/cloudreve/download/temp），并将该目录挂载至宿主机相同路径，例如：

bash docker run -d --name qbittorrent \ -v /var/www/cloudreve/download/temp:/var/www/cloudreve/data/temp \ -p 6800:6800 \ xxx/aria2:latest

若下载器和 Cloudreve 分别运行在不同的容器中，请将两个容器的 /cloudreve/data 目录均挂载至宿主机的相同路径 /cloudreve/data；或在节点下载器配置中指定其他目录（如 /var/www/cloudreve/download/temp），并将 Cloudreve 及下载器容器的 /var/www/cloudreve/download/temp 目录均挂载至宿主机的相同路径 /var/www/cloudreve/download/temp。

下载器任务参数 配置 Cloudreve 在创建下载任务时传递给下载器的额外参数。 针对 Aria2，请查阅官方文档了解可用参数，并以 JSON 格式填入。例如，需限制下载速度、最大并行下载数、指定 Tracker 列表、限制种子时间等：

json { "max-download-limit": "100K", "max-concurrent-downloads": 5, "bt-tracker": [ "udp://tracker.coppersurfer.tk:6969/announce", "udp://tracker.opentrackr.org:1337/announce", "udp://tracker.leechers-paradise.org:6969/announce" ], "seed-ratio": 1.0, "seed-time": 1000 }

除配置全局参数外，还可在用户组设置中以相同 JSON 格式配置用户组级别参数。

配置用户组 完成节点下载器配置后，请在对应的用户组编辑页面启用远程下载权限。

常见问题 任务完成或失败后，下载的文件未被删除。 Cloudreve 会延迟几分钟执行文件删除。若文件长时间未被删除，请检查 Cloudreve 是否拥有下载临时目录的权限。

下载完成后任务转移失败，错误信息包含 no such file or directory。 请检查 Cloudreve 与下载器是否共享同一文件系统，或确认下载临时目录是否挂载至同一目录。

BT 下载速度过慢或无速度。 下载任务由对应的下载器处理，无法通过 Cloudreve 优化。一种可能的解决方案是手动添加 Tracker 服务器。例如，可在 Aria2 配置文件中指定 Tracker：

ini bt-tracker=udp://tracker.coppersurfer.tk:6969/announce,http://tracker.internetwarriors.net:1337/announce,udp://tracker.opentrackr.org:1337/announce

上述 Tracker 列表仅供参考，需根据实际需求填写。可使用 trackerslist 项目中每日更新的最佳 Tracker 列表。

远程下载列表中的任务状态未实时更新？ Cloudreve 使用异步队列监控和处理下载任务，因此任务进度可能存在延迟。请耐心等待。

测试下载器通信时出现错误 ... dial tcp xxx: connect: connection refused...。 请检查下载器是否正常运行，并确认 RPC 服务器地址（Aria2）或 Web UI 地址（qBittorrent）是否正确。若运行在容器中，请检查相应端口是否已映射至宿主机。

添加 qBittorrent 下载任务后，重试 x 次后仍显示 failed to get task status。 对于磁力链接，qBittorrent 可能短时间内无法获取详细链接信息，导致任务未能创建。 对于通过种子文件创建的任务，请检查主站 URL 设置是否正确，因为下载器将通过此 URL 下载种子文件。 对于 HTTP 链接文件，qBittorrent 不支持 HTTP 下载，请使用 Aria2 下载器。 其他情况下，qBittorrent 中可能已存在相同的任务，无法重复创建。

Aria2 任务报错 Infohash is already registered Aria2 中已存在相同的任务，目前不支持重复创建。