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

前言

Aria2 是一个功能非常强大且功能非常齐全的下载工具,它支持 BT、磁力、HTTP、FTP 等下载协议,常用做离线下载的服务端。目前有非常多的 Aria2 Docker 方案,大多都整合了 WebUI 和文件管理功能,看似很好很强大,但他们都忽略了核心的下载体验。Aria2 在没有经过精心配置的情况下并不好用,很多人在初次使用 Aria2 时会遇到 BT 下载无速度、文件残留占用空间、任务丢失等问题。Aria2 完美配置这个项目就是为了解决这些问题而诞生的,而且经过一年多时间的打磨可以完全称得上完美,也已经积累了大量的使用者和良好的口碑,其中不乏一些知名开源项目开发者、影视字幕组、科技视频UP主。虽然一键安装脚本又不是不能用,但在万物容器化的当下,作为 Docker 萌新的我决定挑战自我。在经历了4个月时间的学(tiao)习(piao)和1个多月时间的打(gu)磨(gu)后,基于 Aria2 完美配置的 Docker 方案 Aria2 Pro 终于完成了。

镜像特点

  • 使用 Aria2 完美配置方案

    • BT 下载率高、速度快
    • 重启后不丢失任务进度、不重复下载
    • 下载错误或取消下载自动删除未完成的文件防止磁盘空间占用
    • 下载完成自动清除.aria2后缀名文件
    • 自动获取 BT tracker,进一步提升 BT 下载速度
    • 更好的 PT 下载支持
    • 防版权投诉、防迅雷吸血
  • 使用 aria2-builder 项目最新静态编译二进制文件

    • 多平台:amd64, i386, arm64, armhf
    • 全功能:Async DNS, BitTorrent, Firefox3 Cookie, GZip, HTTPS, Message Digest, Metalink, XML-RPC, SFTP
    • 最新依赖库,提供更安全、稳定、快速的下载体验
    • 通过 CI 服务持续更新最新版本
  • 支持与 RCLONE 联动

    • 自动上传 OneDrive 、Google Drive 等网盘
    • 百度网盘加速下载并转存到其它网盘
    • 自由选择上传网盘
  • 配置文件持久化,支持使用 watchtower 自动更新容器。
  • 极简设计,专注下载,简单易用,少即是多。

项目地址

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

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

支持项目请随手点个star,让更多的人发现、使用并受益。

基础使用

  • 启动命令示例。(不要无脑复制粘贴,请详细阅读选项参数说明)
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 进行连接,推荐 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 - 下载目录映射。左边为宿主机路径供自定义,不要有中文

文件权限设置

-e PUID=$UID, -e PGID=$GID - 设置容器内账户UIDGID。目的是修正非 root 账户使用中遇到的文件权限问题。$UID$GID这两个变量分别为当前启动此容器账户的UIDGID值,如果映射的目录权限不是当前执行启动命令的用户或者使用 GUI 创建容器请务必执行id命令手动获取并设置,比如-e PUID=1000。本项目对文件权限的处理方法参考了 LinuxServer.io 的项目,有关信息详见 Understanding PUID and PGID

Aria2 配置选项环境变量

用于设置一些可能需要自定义的 Aria2 配置选项。

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

-e RPC_SECRET=<TOKEN> - RPC 密钥设置,即 WebUI 连接时需要填写的密码。默认密码:P3TERX

-e RPC_PORT=6800 - RPC 端口设置,忽略则可通过配置文件修改。如果你使用 brige 网络模式请忽略此项,使用默认的6800端口进行映射。

-e LISTEN_PORT=6888 - BT 监听端口(TCP)、DHT 监听端口(UDP)设置,即 Aria2 配置中listen-portdht-listen-port选项定义的端口,默认值6888。PT 下载建议定义为 5 位数,比如2523651413。如果你使用 brige 网络模式请忽略此项,使用默认的6888端口进行映射。

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

其它环境变量

-e UMASK_SET=022 - umask 设置,默认值022

-e RCLONE=enable - 开启 RCLONE 联动功能。首次启动容器会自动安装 RCLONE,且每次重启会自动更新。

-e TRACKERS=no - 禁用自动获取 BT tracker ,供 PT 下载需求使用。

-e TZ=Asia/Shanghai - 时区设置,镜像默认时区Asia/Shanghai,若无特殊需求无需自定义。

bridge 网络模式端口映射说明

bridge 网络模式下需要把容器内部的端口映射到宿主机,它是 Docker 默认的网络模式,所以很多 Docker 镜像的默认使用说明都包含端口映射的参数,也包括在2020年3月28日之前的本项目。端口映射多了一层 NAT ,会有一定的性能损失,所以对于全新部署且没有特殊需求不会用到下面这些参数,并推荐使用 host 网络模式进行部署。

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

-p 6888:6888 - BT 监听端口(TCP)映射,即 Aria2 配置中listen-port选项定义的端口。左边为宿主机端口,PT 下载建议定义为 5 位数,比如2523651413

-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

注意事项

  • 如果你对 Docker 一无所知,请先学习相关基础知识后再使用。
  • GIDUID设置对于非 root 账户非常重要,你不应该错过这个细节,否则可能导致不必要的麻烦。
  • 容器启动命令有关路径与端口参数中:(冒号)右边的值为容器内部固定值,无需修改也不能修改,否则无法正常工作。这是很多 Docker 新手经常犯的错误。
  • Aria2 配置文件中所有关于路径的选项参数默认情况下修改无效,每次重启后会自动修正为正确的值。目的是为了防止错误修改后导致容器工作异常,TLS 设置相关路径除外。如果你有修改的需求,且知道自己在做什么可以在进阶玩法中找到解除限制的彩蛋。
  • 映射目录不存在会自动创建,但只会创建映射目录的本体,故创建映射目录的所在目录(上级目录)必须存在。路径不要有中文。
  • Aria2 Pro 镜像中没有内置配置文件,而是在容器启动时从 P3TERX/aria2.conf 项目进行下载(配置目录没有配置文件的情况下)。目的是方便维护与更新,在不更新镜像的情况下可对配置与脚本中的问题进行快速修复。更新最新配置方案或者想恢复初始配置文件只需删除配置文件并重启容器即可。
  • BT 强制加密已默认开启,理论上可以防版权投诉、防迅雷吸血,在测试使用中没有发现对下载速度有影响,但是否具有普适性还有待观察和研究。如果你在使用中遇到了问题,可以手动修改配置文件去关闭。
  • 必须配置防火墙开放端口或端口转发设置,这对 BT 下载尤为重要,否则 Aria2 将无法与外界进行数据交换,影响下载率和速度。
  • 某些 NAS 系统比如 OpenMediaVault 由于挂载盘默认使用了noexec特征,如果配置文件目录映射到了挂载盘下可能会导致附加功能脚本没有执行权限(功能不完整),解决方法可参考《OpenMediaVault 使用中遇到的问题和解决方案 #1 - permission denied》。
  • 其它有关 Aria2 的注意事项参见本博客历史文章,这里不再赘述。
  • 作者不会对使用此项目造成的损失承担任何责任,使用前请务必阅读整个使用教程再考虑是否使用。
  • 在中国大陆地区使用可能需要处理网络问题。已做针对性优化,但国情如此,实属无奈。

进阶玩法

使用 Aria2 Pro Docker 镜像创建多个容器,你甚至可以在同一设备上使用 Aria2 同时进行 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 分别通过68016802端口连接到这两个容器中的 Aria2 。
  • Enjoy !

RCLONE 自动上传


点击查看

  • 启动命令加入-e RCLONE=enable参数开启 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 RCLONE=enable \
    p3terx/aria2-pro
  • 首次配置可使用docker exec -it aria2-pro rclone config命令进入 RCLONE 交互菜单选项,配置方法可参考:《Rclone 安装配置教程》。
如果之前使用过 RCLONE 可以在宿主机的默认位置找到 RCLONE 的配置文件(~/.config/rclone/rclone.conf),复制到 Aria2 Pro 配置目下即可。
  • 最后你需要修改 Aria2 Pro 配置文件目录下autoupload.sh文件中的网盘名称与目标路径这两个选项。下载目录不要修改,容器已经对此进行定义。

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 RCLONE=enable \
    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 RCLONE=enable \
    p3terx/aria2-pro
  • 参考上个章节分别配置这两个容器的 RCLONE 。
  • 使用 AriaNg 分别通过68036804端口连接到这两个容器中的 Aria2 。
  • Enjoy !

BitTorrent tracker 自动更新


点击查看

由于 Aria2 更新 BT tracker 需要重启才会生效,故 Aria2 Pro 的 BT tracker 更新策略为容器启动时自动获取。更新 BT tracker 重启容器即可。得益于 Aria2 完美配置方案的特性,重启后下载进度不会丢失,不会重复下载,有下载任务时进行重启也无需担心发生问题,你可以通过设置容器定时重启来实现定时更新 BT tracker ,但是并不建议这样做,因为当任务非常多时重启可能有小概率会导致部分任务下载失败,建议还是先暂停任务再重启。重启防任务丢失更多的是防止意外。

RPC 服务 SSL/TLS 加密设置


点击查看

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

其它


点击查看

在配置文件目录新建HelloWorld文件可以解锁固定的配置项,这对于想深度客制化的小伙伴可能有用,但使用不当可能导致容器工作异常。这算是一个彩蛋吧,毕竟 Aria2 Pro 的定位是即开即用。

遇到问题如何处理

90% 以上出现的问题都是没仔细阅读教程和基础知识薄弱导致的,认真学习基础知识,仔细阅读教程中的每一个字,你会发现答案就在其中。

以下是一些基本的排错方法,视实际情况而定,不要无脑复制粘贴

重启

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


本博客已开设 Telegram 频道,欢迎小伙伴们订阅关注。

添加新评论

已有 19 条评论

我只想说站长nb

为什么容器用p3terx:x:888:888::/home/p3terx:/bin/false运行,导致挂在的磁盘都没写权限

你要正确的设置GIDUID,两个都是888说明你没有设置,仔细看教程。

下载大文件报错 ,超过11G的就报错,小文件正常,单独往容器里面cp这个大文件是正常的,用qbittorrent下载也正常。
Exception: [AbstractDiskWriter.cc:224] errNum=13 errorCode=15 Failed to open the file , cause: Permission denied

不应该会出现这种情况,我测试下了个 20G 的文件没有这个问题。这个提示的是没有权限,你检查下GIDUID是否设置正确。

不能下载aria2.conf
stdout: [[32mINFO[0m] Doanload 'aria2.conf' ...
stderr: curl: (7) Failed to connect to p3terx.github.io port 443: Connection refused

pazu pazu 回复 @pazu
0 0

梯子也已经搭好,youtube、github.com等网站可以正常浏览,就是不能下载 aria2.conf,不知道为什么?

它会自己重试下载的,如果是重复一直提示,那么说明 DNS 被污染了。如果只是在日志中提示一次,忽略就行。

非常棒!本想自己动手做一个,发现这个实现的更好,直接拿来用了!感谢

# 保存磁力链接元数据为种子文件(.torrent文件), 默认:false
bt-save-metadata=true

这一条我选false和true都会保存为种子,我删掉这一条是不是就磁力链接可以不保存为种子。

wang wang 回复 @wang
0 0

我换成false,把ariaNg关掉,再重启就好了。

有没有考虑过把aria2和ariaNG整合到一个docker里啊。。

不考虑,没必要。

Jay Jay 回复 @P3TERX
0 0

那能不能做下NAS系统比如群晖的适配优化呢?

test test 回复 @Jay
0 0

DS281+装了没问题

一下载就报下面的错误

[ERROR] CUID#62 - Exception caught while allocating file space.
Exception: [AbstractDiskWriter.cc:561] errNum=95 errorCode=17 fallocate failed. cause: Operation not supported

内核或者文件系统不支持 falloc 文件分配方式,修改配置文件的第 51 行file-allocation选项的参数为none并重启容器。

方便、实用,太好了

很好用,感谢 :)