Docker Aria2 Best Practice

Meticulously Designed

核心特性

长期迭代，精心打磨的下载体验。

全平台支持

统一 Tag 支持 x86-64, arm64, armhf。无论你是高性能服务器还是树莓派/NAS，都能完美运行。

反吸血功能

特殊的 a2b-latest 镜像可屏蔽迅雷、QQ旋风、百度网盘等只下载不上传的吸血客户端，维护 P2P 生态。

完美权限控制

支持 PUID/PGID 环境变量映射。以指定用户身份运行，彻底解决 NAS 下文件权限混乱的问题。

智能脚本

内置自动更新 Trackers，下载完成自动移动文件、清理垃圾文件、删除空目录，省心省力。

回收站机制

独有的回收站功能，防止误删文件。支持保留目录结构移动到回收站或已完成目录。

极致轻量

基于 Alpine Linux 构建，镜像体积仅约 10MB。内存占用极低，性能释放无压力。

快速部署

选择你喜欢的部署方式，一键启动。

bash — docker run

docker run -d \
  --name=aria2 \
  -e PUID=1026 \
  -e PGID=100 \
  -e TZ=Asia/Shanghai \
  -e SECRET=yourtoken \
  -e CACHE=512M \
  -e PORT=6800 \
  -e WEBUI=true \
  -e WEBUI_PORT=8080 \
  -e UT=true \
  -p 6800:6800 \
  -p 8080:8080 \
  -p 6881:6881 \
  -p 6881:6881/udp \
  -v $PWD/config:/config \
  -v $PWD/downloads:/downloads \
  --restart unless-stopped \
  superng6/aria2:webui-latest

docker-compose.yml

version: "3.1"
services:
  aria2:
    image: superng6/aria2:webui-latest
    container_name: aria2
    network_mode: host # 推荐使用 host 模式性能更好
    environment:
      - PUID=1026
      - PGID=100
      - TZ=Asia/Shanghai
      - SECRET=yourtoken
      - CACHE=512M
      - WEBUI=true
    volumes:
      - $PWD/config:/config
      - $PWD/downloads:/downloads
    restart: unless-stopped

配置参数

核心环境变量说明，更多配置请查看 /config/setting.conf

变量名 (ENV)	默认值	说明
PUID / PGID	1026 / 100	运行用户的 UID 和 GID，权限管理关键
SECRET	yourtoken	Aria2 RPC 连接密钥 (Token)
CACHE	128M	磁盘缓存大小，大内存机器建议调大
WEBUI	true	是否开启内置 AriaNg Web 控制台
UT	true	启动时是否自动更新 Trackers 列表
SMD	true	是否保存磁力链接为种子文件
BTPORT	32516	BT/DHT 监听端口，建议映射到公网

高级设置详解 (setting.conf)

容器启动后会在 /config 目录下生成 setting.conf。此文件控制了容器的高级功能，无需重启容器，修改即刻生效。

remove-task 默认: rmaria

删除任务后的操作。

delete: 删除任务后同时删除文件
recycle: 删除文件至回收站 (需开启回收站功能)
rmaria: 只删除 .aria2 文件 (保留下载的文件)

move-task 默认: false

下载完成后是否移动文件。

true: 下载完成后保留目录结构移动到完成目录
dmof: (推荐) 非自定义目录的单文件不移动；自定义目录或多文件任务保留目录结构移动
false: 不移动

content-filter 默认: false

文件过滤功能开关。开启后，任务下载完成后会自动删除不需要的文件（如 html, url, txt 等，可在 文件过滤.conf 中配置）。

handle-torrent 默认: backup-rename

对磁力链接生成的种子文件的处理。

retain: 默认保留
delete: 删除种子文件
backup: 备份种子文件到 /config/backup-torrent
rename: 重命名种子文件
backup-rename: 重命名并备份 (推荐)

remove-repeat-task 默认: true

检测重复任务。若已完成目录有当前任务，则取消下载并删除任务文件。

文件过滤配置 (文件过滤.conf)

当 content-filter=true 时生效。配置文件位于 /config/文件过滤.conf。

文件过滤.conf

# 排除小文件 (低于此大小的文件将在下载完成后被删除)
min-size=10M

# 保留文件类型 (其它文件类型将在下载完成后被删除)
include-file=mp4|mkv|rmvb|mov|avi|srt|ass

# 排除文件类型 (排除的文件类型将在下载完成后被删除)
exclude-file=html|url|lnk|txt|jpg|png

# 按关键词排除 (包含以下关键字的文件将在下载完成后被删除)
keyword-file=广告1|广告2|广告3

教程与常见问题

群晖 NAS 权限问题详解

群晖用户最常见的问题是文件无法下载或无法删除。这是因为 Docker 容器默认以 root 运行，而群晖文件系统有严格的权限控制。

开启 SSH 功能，登录群晖后台。
输入 id 你的用户名 获取 UID 和 GID。
在 Docker 环境变量中设置 PUID 和 PGID。
重要：在群晖 File Station 中，右键点击 docker 配置文件夹和下载文件夹，选择属性 -> 权限。
确保该用户拥有“读取”和“写入”权限。

目录结构与挂载

建议的目录挂载方式：

/config

配置文件目录。包含 aria2.conf, setting.conf, logs, ssl 证书等。请务必持久化保存。

/downloads

默认下载目录。所有下载文件将保存于此。

WebUI 如何访问？

默认端口为 8080。浏览器访问 http://your-ip:8080 即可。内置 AriaNg 面板，已配置好连接。

如何开启 SSL？

将证书文件放置在 /config/ssl 目录下，并修改 /config/aria2.conf 文件，取消相关 SSL 配置行的注释即可。

下载速度慢怎么办？

1. 确保 BTPORT (默认32516) 端口在路由器上做了端口转发（UDP+TCP）。
2. 容器会自动更新 Trackers 列表以优化连接，无需手动干预。
3. 如果是内网环境，确保 NAT 类型不是严格型。

关于 a2b-latest 镜像

superng6/aria2:a2b-latest 镜像集成了 aria2b 功能，用于屏蔽迅雷、QQ旋风、百度网盘等吸血客户端。使用此镜像需要开启 NET_ADMIN 权限 (Docker run增加 --cap-add NET_ADMIN)，并映射 /lib/modules:/lib/modules。