Docker 搭建 aria2+AriaNg 完全指南 | 高效下载管理与图形化控制教程

什么是 aria2 和 AriaNg

aria2 简介

aria2 是一款轻量级、多协议、多来源的命令行下载工具，支持以下特性：

• 多协议支持：HTTP/HTTPS、FTP、SFTP、BitTorrent、Metalink
• 多线程下载：支持分段下载，最大化利用带宽
• 低资源占用：内存占用小，适合在 VPS 或服务器上长期运行
• RPC 接口：支持 JSON-RPC 和 XML-RPC，可通过 Web 界面远程控制
• 跨平台：支持 Linux、macOS、Windows 等操作系统

AriaNg 简介

AriaNg 是一个基于 Web 的 aria2 图形化管理界面，提供以下功能：

• 现代化 UI：简洁直观的操作界面
• 实时监控：实时显示下载速度、上传速度、连接数等信息
• 批量操作：支持批量添加、删除、暂停、开始任务
• 文件管理：查看下载文件详情，选择性下载 BT 任务中的特定文件
• 移动端适配：响应式设计，支持手机和平板访问

安装 aria2

前置要求

• 已安装 Docker 和 Docker Compose
• 服务器有足够的存储空间
• 开放相应的防火墙端口

使用拉取 aria2 镜像

``sh docker pull p3terx/aria2-pro

`p3terx/aria2-pro` 是一个经过优化的 aria2 镜像，相比官方镜像有以下优势：

- 预配置了优化的下载参数
- 支持自动更新配置文件
- 内置证书生成工具
- 完善的日志管理

### 启动容器

``sh
docker run -d \
--name aria2 \
--restart unless-stopped \
--log-opt max-size=1m \
-e PUID=$UID \
-e PGID=$GID \
-e UMASK_SET=022 \
-e RPC_SECRET=password \
-e RPC_PORT=6800 \
-e LISTEN_PORT=6888 \
-p 16800:6800 \
-p 16888:6888 \
-p 16888:6888/udp \
-v /root/aria2/config:/config \
-v /mnt/nas_share/downloads:/downloads \
p3terx/aria2-pro

用户和组设定

PUID=$UID 、PGID=$GID 这 2 个定义用户和用户组的环境变量，限定了 aria2 以什么用户和用户组运行，不指定则默认使用 nobady 用户 和 nogroup 用户组，但在使用 FileRun 网盘 时，会因权限问题无法删除或改名 aria2 下载好的文件，所以 PUID 和 GUID 要指定为和 WEB 环境的运行用户和用户组 一致，比如 WEB 环境运行的用户及对应的用户组都是 WWW，对应的 uid 和 gid 都是 1001，那就要指定 PUID=1001、PGID=1001，这样在 FileRun 网盘中就可以正常的进行删除和修改操作了

如何获取 UID 和 GID

可以通过以下命令查看当前用户的 UID 和 GID：

id $USER

输出示例：

uid=1000(mac) gid=1000(mac) groups=1000(mac)

环境变量详解

• -e UMASK_SET=022 : 设置 umask，默认值 022；umask 用于控制创建文件的默认权限，022 表示创建的文件权限为 644（所有者可读写，其他人只读），目录权限为 755
• -e RPC_SECRET= : 设置 RPC 密钥，用于 AriaNg 与 Aria2 的通讯验证使用；建议使用强密码，包含字母、数字和特殊字符
• -e RPC_PORT=6800 : 设置 PRC 通讯端口（与宿主主机的端口映射一致）；如需更改，确保与端口映射一致
• -e LISTEN_PORT=6888 : BT 监听端口（TCP）、DHT 监听端口（UDP）设置，即 Aria2 配置中 listen-port 与 dht-listen-port 选项定义的端口。如果没有设置，配置文件中的默认值为 6888。
• -v /root/aria2/config:/config : 配置文件挂载到指定的宿主主机目录/root/aria2/config 中，宿主主机的目录根据实际情况自行修改；
• -v /root/aria2/downloads:/downloads : 将/downloads挂载到宿主主机的/root/aria2/downloads:/downloads 目录，即 FileRun 的数据目录中，方便下载完成直接在网盘中查看；

端口映射详解

• -p 16800:6800，为 RPC 通讯端口映射，AriaNg 通过此端口与 aria2 通信
• -p 16888:6888，为 BT 监听端口（TCP）映射，即 Aria2 配置中 listen-port 选项定义的端口；用于 BT 下载时的 Peer 连接
• -p 16888:6888/udp，为 DHT 监听端口（UDP）映射，即 Aria2 配置中 dht-listen-port 选项定义的端口。用于 DHT 网络发现

防火墙配置

如果服务器启用了防火墙，需要开放相应端口：

# Ubuntu/Debian (ufw)
sudo ufw allow 16800/tcp
sudo ufw allow 16888/tcp
sudo ufw allow 16888/udp

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=16800/tcp
sudo firewall-cmd --permanent --add-port=16888/tcp
sudo firewall-cmd --permanent --add-port=16888/udp
sudo firewall-cmd --reload

高级配置选项

如果需要更精细的控制，可以创建自定义配置文件：

1. 创建配置文件目录

mkdir -p /root/aria2/config
cd /root/aria2/config

2. 创建 aria2.conf 配置文件

# 基本设置
dir=/downloads
input-file=/config/aria2.session
save-session=/config/aria2.session
save-session-interval=60

# 下载速度限制（字节/秒）
max-overall-download-limit=0
max-download-limit=0

# 上传速度限制（字节/秒）
max-overall-upload-limit=0
max-upload-limit=0

# 最大同时下载任务数
max-concurrent-downloads=5

# HTTP/FTP 设置
max-connection-per-server=16
min-split-size=1M
split=16

# BT 设置
bt-max-peers=100
bt-request-peer-speed-limit=5M
bt-stop-timeout=300
enable-dht=true
enable-dht6=true
peer-id-prefix=-TR2940-
user-agent=Transmission/2.94

# 断点续传
continue=true

# 日志
log=/config/aria2.log
log-level=warn

# RPC 设置
enable-rpc=true
rpc-allow-origin-all=true
rpc-listen-all=true
rpc-listen-port=6800
rpc-secret=your_secure_password_here

3. 使用自定义配置启动

docker run -d \
--name aria2 \
--restart unless-stopped \
--log-opt max-size=1m \
-e PUID=$UID \
-e PGID=$GID \
-e UMASK_SET=022 \
-p 16800:6800 \
-p 16888:6888 \
-p 16888:6888/udp \
-v /root/aria2/config:/config \
-v /mnt/nas_share/downloads:/downloads \
-v /root/aria2/config/aria2.conf:/etc/aria2/aria2.conf \
p3terx/aria2-pro

安装 AriaNg

拉取 AriaNg 镜像

docker pull p3terx/ariang

启动容器

docker run -d \
--name ariang \
--log-opt max-size=1m \
--restart unless-stopped \
-p 16880:6880 \
p3terx/ariang

如果需要 HTTPS 访问，可以使用 Nginx 反向代理（详见后文安全配置部分）。

配置 RPC

访问 http://你的服务器 ip:16880 访问 AriaNg 的 web 管理界面，点击AriaNg 设置菜单，再点击全局 右边的标签

• RPC 别名随意填就好，例如"My Aria2"
• RPC 地址填写你服务器的域名或 IP，后面的端口号就是前面启动的 aria2 的 RPC 通讯端口（示例中为 16800）
• RPC 协议选默认的 HTTP
• RPC Http 请求方法使用默认的 POST
• RPC 密钥填写前面启动的 aria2 的 RPC 密钥（RPC_SECRET）

配置完刷新一下页面，如果状态显示 已连接 就 ok 了

使用指南

添加下载任务

HTTP/FTP 下载

1. 点击界面上的"+"按钮
2. 选择"新建下载"
3. 输入下载链接（支持多个链接，每行一个）
4. 点击"立即下载"

BT 磁力链下载

1. 点击"+"按钮
2. 选择"BT 下载"或"磁力链接"
3. 粘贴磁力链接或上传.torrent 种子文件
4. 选择要下载的文件（可选择性下载部分文件）
5. 点击"立即下载"

批量操作

• 全选任务：在任务列表左上角点击复选框
• 批量删除：选中多个任务后，点击底部的删除按钮
• 批量移动：选中任务后，可批量移动到不同的分类

文件管理

下载完成后，可以在"已完成"标签页查看下载的文件：

• 查看文件详情（大小、路径、哈希值等）
• 对于 BT 任务，可以重新选择要下载的文件
• 直接删除不需要的文件

性能优化建议

1. 调整并发连接数

根据服务器性能和网络状况调整：

# 编辑 docker run 命令或使用 docker-compose
-e MAX_CONCURRENT_DOWNLOADS=10 \
-e MAX_CONNECTION_PER_SERVER=16 \

推荐配置：

• 低配 VPS（1 核 1G）：并发 3-5，单文件连接 8-16
• 中配 VPS（2 核 2G）：并发 5-10，单文件连接 16-32
• 高配服务器：并发 10+，单文件连接 32+

2. 优化分段下载

# 在 aria2.conf 中添加
split=16
min-split-size=1M

• split: 单个文件分割成多少段下载，值越大速度越快，但占用资源越多
• min-split-size: 最小分段大小，避免过小文件分段过多

3. BT 下载优化

# 增加 Peer 数量
bt-max-peers=100

# 提高请求速度
bt-request-peer-speed-limit=5M

# 延长等待时间（避免热门资源过早停止）
bt-stop-timeout=600

4. 启用缓存

# 磁盘缓存，减少 IO 压力
file-alloc=trunc

可选值：

• none: 不预先分配空间（速度快，可能产生碎片）
• falloc: 使用 fallocate 预先分配（最快，但需要文件系统支持）
• prealloc: 预先分配空间（较慢，兼容性好）
• trunc: 使用 trunc 系统调用（默认值，平衡性能和兼容性）

5. 会话保存

防止意外中断后丢失下载进度：

input-file=/config/aria2.session
save-session=/config/aria2.session
save-session-interval=60

安全配置建议

1. 使用强密码

确保 RPC_SECRET 使用强密码：

# 生成随机密码
openssl rand -base64 32

示例输出：

KjH8sN3pL9mQ2rT5vX7zA0bC4dE6fG8hI1jK3lM5nO7=

2. 配置 HTTPS 访问

使用 Nginx 反向代理实现 HTTPS：

1. 安装 Nginx

apt install nginx -y  # Debian/Ubuntu
yum install nginx -y  # CentOS/RHEL

2. 创建 Nginx 配置

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:16880;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

3. 申请 SSL 证书（使用 Let's Encrypt）

apt install certbot python3-certbot-nginx -y
certbot --nginx -d your-domain.com

3. 限制 RPC 访问来源

如果不需要外网访问 RPC，可以限制 IP：

docker run -d \
...
-e RPC_LISTEN_ALL=false \
p3terx/aria2-pro

或在防火墙中限制：

sudo ufw allow from 192.168.1.0/24 to any port 16800

4. 定期更新镜像

# 定期更新镜像
docker pull p3terx/aria2-pro
docker pull p3terx/ariang

# 重启容器应用更新
docker restart aria2
docker restart ariang

常见问题排查

1. 无法连接到 aria2

问题表现：AriaNg 显示"未连接"或连接超时

排查步骤：

1. 检查容器是否运行

docker ps | grep aria2

2. 查看容器日志

docker logs aria2

3. 检查端口是否监听

netstat -tlnp | grep 6800

4. 确认防火墙规则

sudo ufw status

5. 测试 RPC 连接

curl http://localhost:16800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"aria2.getGlobalStat","id":"1","params":["token:your_rpc_secret"]}'

2. 下载速度慢

可能原因：

• 并发连接数过低
• 单文件连接数不足
• 服务器带宽限制
• 资源本身速度慢（尤其是冷门 BT 资源）

解决方案：

1. 增加并发连接数（见性能优化部分）
2. 更换下载源（如果是 HTTP 下载）
3. 检查服务器带宽使用情况

iftop  # 实时查看网络流量

3. BT 下载无速度

可能原因：

• Peer 数量太少
• DHT 网络未启用
• 端口未正确映射

解决方案：

1. 检查 Peer 数量

docker exec aria2 aria2c --help | grep bt-max-peers

2. 确认端口映射

docker port aria2

3. 检查防火墙是否放行 UDP 端口

sudo ufw allow 16888/udp

4. 尝试添加更多 Tracker

# 获取最新 Tracker 列表
wget -N https://raw.githubusercontent.com/XIU2/TrackersListCollection/master/all.txt

# 在 AriaNg 中添加：设置 -> Aria2 配置 -> BT/Tracker -> Tracker 服务器

4. 权限问题

问题表现：下载的文件无法删除或修改

解决方案：

1. 确认 PUID 和 PGID 设置正确

docker exec aria2 id

2. 检查挂载目录权限

ls -la /mnt/nas_share/downloads

3. 修正权限

chown -R 1000:1000 /mnt/nas_share/downloads
chmod -R 755 /mnt/nas_share/downloads

5. 容器无法启动

排查步骤：

1. 查看日志

docker logs --tail 100 aria2

2. 检查配置文件语法

docker exec aria2 aria2c --conf-path=/etc/aria2/aria2.conf

3. 检查端口占用

lsof -i :6800
lsof -i :6888

4. 重新创建容器

docker rm -f aria2
# 重新执行 docker run 命令

使用 Docker Compose 管理（推荐）

使用 Docker Compose 可以更方便地管理多个容器：

1. 创建 docker-compose.yml 文件

version: '3'

services:
  aria2:
    image: p3terx/aria2-pro
    container_name: aria2
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK_SET=022
      - RPC_SECRET=your_secure_password
      - RPC_PORT=6800
      - LISTEN_PORT=6888
    ports:
      - "16800:6800"
      - "16888:6888"
      - "16888:6888/udp"
    volumes:
      - /root/aria2/config:/config
      - /mnt/nas_share/downloads:/downloads
    networks:
      - download-network

  ariang:
    image: p3terx/ariang
    container_name: ariang
    restart: unless-stopped
    ports:
      - "16880:6880"
    depends_on:
      - aria2
    networks:
      - download-network

networks:
  download-network:
    driver: bridge

2. 启动服务

docker-compose up -d

3. 管理服务

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 更新镜像
docker-compose pull
docker-compose up -d

扩展功能

1. 集成 FileRun 网盘

如前所述，通过正确设置 PUID/PGID，可以让 aria2 与 FileRun 网盘无缝集成：

• 下载路径设置为 FileRun 的数据目录
• 下载完成后自动在网盘中查看
• 在线播放下载的视频文件
• 通过网盘分享文件

2. 自动化脚本

可以编写脚本实现自动化操作：

示例：自动清理已完成任务

#!/bin/bash

RPC_SECRET="your_password"
RPC_PORT="16800"

# 获取所有完成任务
curl http://localhost:${RPC_PORT}/jsonrpc \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\":\"2.0\",
    \"method\":\"aria2.tellStopped\",
    \"id\":\"1\",
    \"params\":[\"token:${RPC_SECRET}\", 0, 1000, [\"gid\", \"status\"]],
  }" | jq '.result[] | select(.status == "complete") | .gid' \
  | xargs -I {} curl http://localhost:${RPC_PORT}/jsonrpc \
    -H "Content-Type: application/json" \
    -d "{
      \"jsonrpc\":\"2.0\",
      \"method\":\"aria2.removeDownloadResult\",
      \"id\":\"1\",
      \"params\":[\"token:${RPC_SECRET}\", \"{}\"],
    }"

3. 浏览器扩展

安装浏览器扩展快速添加下载任务：

• Chrome: Aria2 Integration
• Firefox: Aria2 Download Manager

安装后，右键点击下载链接即可发送到 aria2。

总结

通过本文的教程，您已经完成了：

• ✅ 使用 Docker 部署 aria2 和 AriaNg
• ✅ 配置了 RPC 连接和图形化管理界面
• ✅ 了解了性能优化和安全配置的最佳实践
• ✅ 掌握了常见问题的排查方法
• ✅ 学习了使用 Docker Compose 管理容器

现在您可以享受高效、便捷的下载体验了！无论是 HTTP 文件、BT 种子还是磁力链接，aria2 都能为您提供出色的下载性能。配合 AriaNg 的友好界面，管理下载任务变得前所未有的简单。

参考资源

• aria2 官方文档
• AriaNg 官方网站
• p3terx/aria2-pro GitHub
• Tracker 列表收集项目
• Docker 官方文档