Aria2 Pro – 更好用的 Aria2 Docker 容器镜像

发布于 2020-05-30  858 次阅读

原文地址 https://p3terx.com/archives/docker-aria2-pro.html

前言

Aria2 是一个功能非常强大且功能非常齐全的下载工具，它支持 BT、磁力、HTTP、FTP 等下载协议，常用做离线下载的服务端。目前有非常多的 Aria2 Docker 方案，大多都整合了 We­bUI 和文件管理功能，看似很好很强大，实际上都只是做了打包的工作，完全没有考虑到核心的下载体验和资源占用等问题。这也导致很多人在初次使用 Aria2 时会遇到 BT 下载无速度、文件残留占用空间、任务丢失等问题，所以会觉得 Aria2 并不好用，但事实并非如此。Aria2 完美配置是博主经过长时间使用和研究官方文档后总结出来的一套配置方案，其最初目的是为了解决这些问题，经过一年多时间的打磨已经积累了大量的使用者和良好的口碑，其中不乏一些知名开源项目开发者、影视字幕组、科技视频 UP 主。之前一直使用一键脚本作为部署方案，但在万物容器化的当下，作为 Docker 萌新的我决定要尝试一番。在经历了 4 个月时间的学（tiao）习（piao）和 1 个多月时间的打（tuo）磨（yan）后，基于 Aria2 完美配置和特殊定制优化的 Aria2 Docker 方案终于完成了，为了和一般的 Aria2 方案做区分所以将其取名为 Aria2 Pro。

镜像特点

  • 使用 Aria2 完美配置方案

    • BT 下载率高、速度快
    • 重启不丢失任务进度、不重复下载
    • 下载错误或取消下载自动删除未完成的文件防止磁盘空间占用
    • 下载完成自动清除.aria2后缀名文件
    • 更好的 PT 下载支持
    • 防版权投诉、防迅雷吸血优化

  • 使用 aria2-builder 项目最新静态编译二进制文件

    • 多平台：amd64, i386, arm64, armhf（VPS、群辉、树莓派等常见 CPU 平台完美支持）
    • 全功能：Async DNS, BitTorrent, Firefox3 Cookie, GZip, HTTPS, Message Digest, Metalink, XML-RPC, SFTP
    • 解除单服务器线程数限制，最大值无上限
    • 最新依赖库，下载更安全、稳定、快速
    • 持续更新最新版本

  • 支持与 RCLONE 联动

    • 自动上传 OneDrive 、Google Drive 等网盘
    • 百度网盘转存到其它网盘
    • 多网盘自由选择
  • 支持新一代互联网协议 IPv6
  • 定时自动更新 BT tracker 列表（无需重启即刻生效）
  • 用户文件权限自动配置功能
  • 下载完成文件自动归档功能
  • 配置文件持久化，支持使用 watchtower 更新容器。
  • 极简设计，专注下载，简单易用，少即是多。

项目地址

GitHub: https://github.com/P3TERX/docker-aria2-pro

Docker Hub: https://hub.docker.com/r/p3terx/aria2-pro

支持本项目欢迎随手点个 star，可以让更多的人发现、使用并受益。你的支持是我持续开发维护的动力。

基础使用

使用的前提是必须要精通 Docker CLI，因为 Aria2 Pro 所拥有的强大的技术细节与功能需要扎实的技术功底才能轻松驾驭。

  • 最基本的启动命令如下，你只需要替换<TOKEN>字段即可启动。更强大的功能请详细阅读后文。
docker run -d \
    --name aria2-pro \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=<TOKEN> \
    -e RPC_PORT=6800 \
    -e LISTEN_PORT=6888 \
    -v ~/aria2-config:/config \
    -v ~/aria2-downloads:/downloads \
    p3terx/aria2-pro
  • 配置防火墙开放必要的端口，内网机器在路由器设置端口转发。
  • 使用你喜欢的 WebUI 或 App 进行连接，强烈推荐 AriaNg。
  • 体验高速远程离线下载的乐趣。

选项参数说明

Docker 基本选项

--name aria2-pro - 容器名称，可自定义以示区分。

--restart unless-stopped - 设置容器重启策略，详情参见 Docker 官方文档。

--log-opt max-size=1m - 日志大小限制为 1MB，防止 Aria2 持续下载产生大量的日志占用磁盘空间。

--network host - 使用 host 网络模式。直接使用宿主机网络，免去端口映射导致的部分性能损失，且灵活性更高，可更方便的配置使用 IPv6 网络。host 模式仅适用于 Docker 17.06+ ，如果你的 Docker 版本低于此，请先升级。

容器目录映射

-v ~/aria2-config:/config - 配置目录映射，配置文件持久化。左边为宿主机路径供自定义，不要有中文、不要混用配置文件。

-v ~/aria2-downloads:/downloads - 下载目录映射。左边为宿主机路径供自定义，不要有中文。

映射目录不存在会自动创建，但只会创建映射目录的本体，故创建映射目录的所在目录（上级目录）必须存在。一般来说是使用对应的账户先创建相应的目录再映射，由于 Aria2 Pro 有权限自动设置功能，所以这个步骤可以省略。

用户文件权限设置

-e PUID=$UID, -e PGID=$GID - 设置容器内账户 UID(用户 ID) 与 GID(用户组 ID)，容器将自动配置文件权限。在 CLI 中 $UID 与 $GID 这两个变量分别为当前登录的执行容器启动命令账户的 UID 与 GID 值。

如果管理文件的账户不是当前登录的账户或者使用 GUI 创建容器请务必执行 id 命令手动获取并填写。比如我的账户为 p3terx，那么就执行 id p3terx：

$ id p3terx
uid=1000(p3terx) gid=100(users) ...

Aria2 配置选项环境变量

用于设置一些可能需要自定义的 Aria2 配置选项，方便一键部署。

TIPS: 以下环境变量定义后将直接写入配置文件，通过变量定义后无法通过配置文件修改，因为每次容器重启会自动修正为环境变量定义的值。你也可以选择忽略它们，直接在容器创建后修改配置文件。

-e RPC_SECRET=<TOKEN> - RPC 密钥设置，即 We­bUI 连接时需要填写的密码。如果没有设置，配置文件中的默认密码为 P3TERX。

-e RPC_PORT=6800 - RPC 端口设置。如果你使用 bridge 网络模式请忽略此项，使用默认的 6800 端口进行映射。

-e LISTEN_PORT=6888 - BT 监听端口（TCP）、DHT 监听端口（UDP）设置，即 Aria2 配置中 listen-port 与 dht-listen-port 选项定义的端口，配置文件中的默认值为 6888。PT 下载建议定义为任意未占用的 5 位数端口，比如 25236、51413。如果你使用 bridge 网络模式请忽略此项，使用默认的 6888 端口进行映射。

-e DISK_CACHE=<SIZE> - 磁盘缓存设置，默认值 64M。本地路由器或 NAS 建议在有足够的内存空闲情况下设置为适当的大小以减少磁盘 I/​O 延长硬盘寿命，比如 128M、256M 等，但不要超过可用内存空间大小。

IPV6_MODE=enable - 开启 IPv6 功能。此变量等于设定配置文件中的选项 disable-ipv6=false 与 enable-dht6=true。可间接提升 BT 下载速率，但需要网络完整支持 IPv6 ，否则会导致部分功能异常，甚至无法下载。

特殊模式环境变量

-e SPECIAL_MODE=move - 开启文件自动归档功能，即在文件下载完成后把文件移动到指定目录。默认移动到下载目录下的 completed 子目录。有关详情在后面的进阶玩法章节。

-e SPECIAL_MODE=rclone - 开启 RCLONE 联动功能。首次启动容器会在容器内自动安装 RCLONE，且每次重启会自动更新。有关详情在后面的进阶玩法章节。

其它环境变量

-e UMASK_SET=022 - umask 设置，默认值 022。

-e TRACKERS=no - 禁用自动获取 BT tracker 。PT 下载必需禁用。

-e TZ=<TIME ZONE> - 时区设置，默认时区为 Asia/Shanghai，若无特殊需求无需自定义。

bridge 网络模式

bridge 网络模式下需要把容器内部的端口映射到宿主机，它是 Docker 默认的网络模式，所以很多 Docker 镜像的默认使用说明都包含端口映射的参数，也包括在 2020 年 3 月 28 日之前的本项目。bridge 网络模式主要是用于网络隔离，这对于一般用户而言没有多大用处，而且端口映射多了一层 NAT ，会有一定的性能损失。如果要使用 IPv6 网络还需要进行一些列复杂的设置。所以对于全新部署且没有特殊需求不会用到下面这些参数。

-p 6800:6800 - RPC 通讯端口映射，左边为宿主机端口供自定义。

-p 6888:6888 - BT 监听端口（TCP）映射，即 Aria2 配置中 listen-port 选项定义的端口。左边为宿主机端口，PT 下载建议定义为任意未占用的 5 位数端口，比如 25236、51413。

-p 6888:6888/udp - DHT 监听端口（UDP）映射，即 Aria2 配置中 dht-listen-port 选项定义的端口。可与 BT 监听端口不同。PT 下载可忽略。

bridge 网络模式启动命令示例：

docker run -d \
    --name aria2-pro \
    --restart unless-stopped \
    --log-opt max-size=1m \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=<TOKEN> \
    -p 6800:6800 \
    -p 6888:6888 \
    -p 6888:6888/udp \
    -v ~/aria2-config:/config \
    -v ~/aria2-downloads:/downloads \
    p3terx/aria2-pro

注意事项

  • 作者不会对使用此项目造成的损失承担任何责任，使用前请务必详细阅读整个文档再考虑是否使用。
  • GID与UID设置对于非 root 账户非常重要，你不应该错过这个细节，否则可能导致不必要的麻烦。
  • 容器启动命令有关路径与端口参数中:(冒号) 右边的值为容器内部的固定值（常识），不要去修改，否则可能导致无法正常工作。
  • Aria2 配置文件中某些没必要修改的选项参数和已通过环境变量设定的选项参数默认情况下修改无效，重启后会自动修复为正确的值。（为了防止错误修改后导致容器工作异常所做的自我修复功能，比如可以防止把容器内的路径改成容器外的路径之类的迷惑行为）
  • 由于 Aria2 暂时没有 UPnP 功能，所以必须配置防火墙开放监听端口或端口转发设置，这对 BT 下载尤为重要，否则 Aria2 将无法与外界进行数据交换，影响下载率和速度。有关详情参见《Aria2 无法下载磁力链接、BT 种子和速度慢的解决方案》。
  • 某些 NAS 系统比如 OpenMediaVault 由于挂载盘默认使用了noexec特征，如果配置文件目录映射到了挂载盘下可能会导致附加功能脚本没有执行权限，解决方法可参考《OpenMediaVault 使用中遇到的问题和解决方案 #1 - permission denied》。
  • 在中国大陆地区使用可能需要处理网络问题。已做针对性优化，但国情都懂的。
  • 其它有关 Aria2 使用的注意事项因为精力有限暂未做整理，可查看本博客其它 Aria2 文章了解。

其它说明

配置文件相关

  • Aria2 Pro 镜像中没有内置配置文件，而是在容器启动时从 P3TERX/aria2.conf 项目进行下载（配置目录没有相应文件的情况下）。目的是方便维护与更新，在不更新镜像的情况下可对配置与脚本中的问题进行快速修复。更新最新配置方案或者想恢复初始配置文件只需删除配置文件目录中的所有文件并重启容器即可。
  • 默认开启 BT 强制加密，理论上有一定的防版权投诉和防迅雷吸血的效果，在测试使用中没有发现对下载速度有影响，但是否具有普适性还有待观察和研究。如果你在使用中遇到了问题，可以手动修改配置文件去关闭。
  • 出于安全性的考虑，配置目录中配置文件的权限为600、脚本为700，如需编辑需要使用设定的账户。
  • 配置文件无法下载一般是容器的网络没有通导致的。

重启防任务丢失

重启后下载进度不会丢失，不会重复下载，但这更多的是防止意外。任务非常多时重启可能有极小概率会导致部分正在进行的任务下载失败，所以手动重启建议先暂停任务再重启。

解除单服务器线程限制

Aria2 Pro 不仅仅只是解除了单服务线程数的限制，还有特殊的防掉线程优化以及增强配置选项，这是其他项目所不具备的。Aria2 官方对单服务器线程数进行限制必然是有他们自己的考虑，但我个人认为自由软件就是要自由，所以解除了这个限制，让所有人可以自由选择。不过无脑的增加线程数并不会让下载速度飞起来，有时会起到反作用，甚至导致无限重启。合理的设置才是正道。

开启 IPv6 功能

在开启 IPv6 后 BT 下载有一定的资源搜寻能力提升，能连接到更多的用户，间接可提升 BT 下载速率，这对于没有公网 IPv4 的小伙伴是一个福音。由于需要网络完整支持 IPv6，否则会导致部分功能异常，所以目前默认是关闭的。

  • 使用 host 网络模式只需在宿主机 IPv6 网络正常的情况下在容器启动命令中添加IPV6_MODE=enable环境变量或者后续修改配置文件中有关 IPv6 的选项并重启即可。
  • 使用 briage 、 macvlan 等网络模式则还需要配置 Docker 使容器获得 全球单拨 IPv6 地址并且容器网络正常。由于配置过程太过复杂，所以一般来说并不推荐。

AriaNg (WebUI)

Aria2 前端面板 (GUI、WebUI) AriaNg 使用教程

RPC 服务 SSL/TLS 加密

  • 使用 web server 反代 RPC 端口（推荐）。
  • 复制证书到配置目录下，修改配置文件中的相关参数。注意路径前缀为容器内的路径，即/config/。

进阶玩法

Aria2 Pro 具有非常多的隐藏功能与玩法等待你去发觉，比如通过创建多个容器，你甚至可以在同一设备上同时进行 BT 下载、PT 下载、自动上传 OneDrive 、自动上传 Google Drive 等功能，但不仅限于这些。想象力没有上限，需要自己思考。授人以鱼不如授人以渔，所以只写大概思路与示例。

PT 下载

NOTICE: 不知出于何种原因某些 PT 站对 Aria2 有特殊检测机制，可能存在封号风险，使用前需要注意 PT 站的相关规则与条款。

  • PT 下载需要加入-e TRACKERS=no参数禁用自动获取 BT tracker ，然后设定 BT 端口为任意五位数端口，比如25236。启动命令示例：
docker run -d \
    --name aria2-pro \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e RPC_PORT=6800 \
    -e LISTEN_PORT=25236 \
    -v ~/aria2-config:/config \
    -v ~/aria2-downloads:/downloads \
    -e TRACKERS=no \
    p3terx/aria2-pro
  • 修改配置文件中与 PT 相关的参数（配置文件中有注释说明）。

TIPS: 如果有持续做种的需求，建议开启强制保存，否则重启后已完成列表会被清空。开启强制保存后如果文件被删除或被移走会引发重复下载，正确的做法是删除已完成列表中的相关任务。

同时使用 BT 与 PT

  • 使用 Aria2 Pro 镜像创建名为aria2-bt的容器 RPC 端口设置为6801，BT 端口设置为6999，配置目录设置为~/aria2-bt-config，下载目录设置为~/bt-downloads。启动命令示例：
docker run -d \
    --name aria2-bt \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e RPC_PORT=6801 \
    -e LISTEN_PORT=6999 \
    -v ~/aria2-bt-config:/config \
    -v ~/bt-downloads:/downloads \
    p3terx/aria2-pro
  • 使用 Aria2 Pro 镜像创建名为aria2-pt的容器 RPC 端口设置为6802，BT 监听端口设置为25236，PT 下载不需要设置 DHT 端口所以忽略，配置目录设置为~/aria2-pt-config，下载目录设置为~/pt-downloads，加入-e TRACKERS=no参数禁用自动获取 BT tracker 。启动命令示例：
docker run -d \
    --name aria2-pt \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e RPC_PORT=6802 \
    -e LISTEN_PORT=25236 \
    -v ~/aria2-pt-config:/config \
    -v ~/pt-downloads:/downloads \
    -e TRACKERS=no \
    p3terx/aria2-pro
  • 修改~/aria2-pt-config/aria2.conf中关于 PT 的必要的配置，重启容器。
  • 使用 AriaNg 分别通过6801和6802端口连接到这两个容器中的 Aria2 。
  • Enjoy !

联动 RCLONE 自动上传

文件下载到本地后自动调用 RCLONE 上传到指定网盘，本地不保留文件，实现 OneDrive 和 Google Drive 等网盘的伪离线下载。

  • 启动命令加入-e SPECIAL_MODE=rclone参数设定特殊模式环境变量后开启 RCLONE 自动上传功能，容器初次启动会安装 RCLONE ，且每次重启会自动更新 RCLONE。启动命令示例：
docker run -d \
    --name aria2-pro \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e RPC_PORT=6800 \
    -e LISTEN_PORT=6888 \
    -v ~/aria2-config:/config \
    -v ~/rclone-downloads:/downloads \
    -e SPECIAL_MODE=rclone \
    p3terx/aria2-pro
  • 之前若使用过 RCLONE 直接把配置文件（rclone.conf）复制到 Aria2 Pro 配置目录下即可。 RCLONE 配置文件可以在宿主机的默认位置找到：~/.config/rclone/rclone.conf
  • 初次使用或者想要配置 RCLONE 可使用docker exec -it aria2-pro rclone config命令进入容器内的 RCLONE 交互菜单选项，配置方法可参考：《Rclone 安装配置教程》。
  • 最后你需要修改 Aria2 Pro 配置文件目录下autoupload.sh文件中的网盘名称与目标路径这两个选项。下载目录不要修改，容器已经对此进行定义。

RCLONE 自动上传指定网盘

使用不同的容器进行下载并通过 RCLONE 自动上传到不同的网盘。

  • 使用 Aria2 Pro 镜像创建名为aria2-onedrive的容器 RPC 端口设置为6803，BT 端口设置33333，配置目录为~/aria2-onedrive-config，下载目录为~/onedrive-downloads。启动命令示例：
docker run -d \
    --name aria2-onedrive \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e RPC_PORT=6803 \
    -e LISTEN_PORT=33333 \
    -v ~/aria2-onedrive-config:/config \
    -v ~/onedrive-downloads:/downloads \
    -e SPECIAL_MODE=rclone \
    p3terx/aria2-pro
  • 使用 Aria2 Pro 镜像创建名为aria2-gdrive的容器 RPC 端口设置为6804，BT 端口设置44444，配置目录为~/aria2-gdrive-config，下载目录为~/gdrive-downloads。启动命令示例：
docker run -d \
    --name aria2-gdrive \
    --restart unless-stopped \
    --log-opt max-size=1m \
    --network host \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e RPC_PORT=6804 \
    -e LISTEN_PORT=44444 \
    -v ~/aria2-gdrive-config:/config \
    -v ~/gdrive-downloads:/downloads \
    -e SPECIAL_MODE=rclone \
    p3terx/aria2-pro
  • 参考上个章节分别配置这两个容器的 RCLONE 。
  • 使用 AriaNg 分别通过6803和6804端口连接到这两个容器中的 Aria2 。
  • Enjoy !

文件自动归档

下载完成后自动移动文件到指定目录。

启动命令中增加 -e SPECIAL_MODE=move 参数添加环境变量即可，默认情况下文件将移动到下载目录下的 completed 子目录。

若要移动到下载目录以外的某个目录，除了添加必须的环境变量以外，还需要额外对一个目录进行映射，但不能是下载目录下的子目录（目录映射套娃的后果自行体会）。考虑到此目录可能用于共享，故容器不会对这个目录进行权限更改，宿主机端的目录需提前创建并设置好相应的权限。

比如将容器内的 /completed 映射到宿主机的 ~/aria2-completed 目录：

docker run -d \
    --name aria2-pro \
    --restart unless-stopped \
    --network host \
    --log-opt max-size=1m \
    -e PUID=$UID \
    -e PGID=$GID \
    -e RPC_SECRET=P3TERX \
    -e SPECIAL_MODE=move \
    -v ~/aria2-config:/config \
    -v ~/aria2-downloads:/downloads \
    -v ~/aria2-completed:/completed \
    p3terx/aria2-pro:test

最后还需要编辑配置目录下的 move.sh 脚本，将 TARGET_DIR 环境变量的值设置为容器内的路径，比如上面例子中的 /completed。

目前这个功能只是一个简单雏形，未来可能会增加自动分类归档功能。

遇到问题如何处理

很多问题的产生都是没仔细阅读文档和基础知识薄弱所导致的，认真学习基础知识，仔细阅读文档中的每一个字，你会发现答案就在其中。

以下是一些基本的排错流程，视实际情况而定，不要无脑复制粘贴。

重启

Aria2 Pro 具有自我修复机制，遇到问题首先重启。如果你修改过配置文件和附加功能脚本，先删除后重启。

docker restart aria2-pro

重装

docker rm -f aria2-pro
docker rmi p3terx/aria2-pro
rm -rf ~/aria2-config
docker pull p3terx/aria2-pro
docker run <...>

更新

也许你的问题在最新的版本中已经得到解决，多多关注项目页面动态。一些重要更新会在 Aria2 Channel 推送。

以下是使用 Watchtower 一键更新 Aria2 Pro 镜像与容器的命令：

docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower -cR \
    aria2-pro

查看日志

查看日志才能更好的找到问题的根本，即使你看不懂，也要学会如何查看。

  • 查看实时日志
docker logs -f --tail 30 aria2-pro
  • 导出日志
docker logs aria2-pro > ~/aria2-pro.log

提问

你可以加入 Aria2 TG 群和小伙伴们一起讨论。但要注意提问的方式和提供有用的信息，提问前最好去了解《提问的智慧》，这能更好的帮助你去解决问题和节约时间。诸如 “为什么不能使用？”、“那你能帮帮我吗？” 之类的问题应该没有人会知道。

提交 BUG

提交 BUG 请前往项目 issues 页面，但请注意您需要先知道什么是 BUG 。

更多 Aria2 教程

相关 TG 群组：Aria2 Group

重要更新推送频道：Aria2 Channel

或许明日太阳西下倦鸟已归时