VPS Tutorials
Aria2 and AriaNg on a VPS: Private RPC and Cloud Downloads (2026)
Deploy Aria2 with Docker or systemd, protect AriaNg and JSON-RPC with HTTPS, validate tracker updates, budget traffic and local cloud-mount cache, and recover interrupted downloads.

An always-on VPS can finish authorized downloads while your own computer is offline. Aria2 handles direct HTTP/HTTPS/FTP/SFTP links, BitTorrent, magnets and Metalink, with AriaNg as a browser frontend and JSON-RPC for automation. qBittorrent or Transmission may fit a mainly torrent workflow better; see the qBittorrent guide. Check provider traffic limits and permitted use before running persistent transfers.
This guide covers Docker and native installation, configuration, a protected frontend, automation, cloud mounts and recovery. The examples need private RPC access and a strong secret before startup; HTTPS alone does not fix an exposed backend port.
| Aria2 | qBittorrent | Transmission | |
|---|---|---|---|
| Protocols | HTTP(S), FTP/SFTP where compiled, BT/magnets, Metalink | BT/magnets | BT/magnets |
| Interface | Separate frontend such as AriaNg | WebUI | WebUI |
| Resources | Usually a modest backend; workload-dependent | More extensive torrent interface | Lightweight torrent workflow |
| API | JSON-RPC | WebAPI | RPC |
| Direct links | Yes | Not its primary function | Not its primary function |
| Private trackers | Check permitted clients and seeding policy | Often a convenient fit | Check tracker policy |
| Best fit | Mixed direct links and automation | Torrent-focused use | Simple torrent service |
For direct links and scripted submissions, choose Aria2. Do not treat resource rankings as measured guarantees or add public trackers to private torrents against their rules.
On Ubuntu/Debian:
sudo apt update
sudo apt install -y aria2
aria2c --version
The original recommends 1.36 or later; use a maintained distribution package or reviewed image with the features you need. BitTorrent is not simply unavailable below 1.36. Inspect the installed version/build, particularly SFTP support and host-key verification. Unsupported distributions such as CentOS 7 need migration or a separately maintained package strategy.
The Docker example uses a community image, not an official security or performance guarantee. Before starting it, replace the secret and change the RPC publication to 127.0.0.1:6800:6800. Review peer ports 6881 separately according to the torrent use case. Pin a reviewed image version and match download-directory ownership to PUID/PGID:
# docker-compose.yml
services:
aria2:
image: p3terx/aria2-pro
container_name: aria2
restart: unless-stopped
environment:
- PUID=1000
- PGID=1000
- UMASK_SET=022
- RPC_SECRET=换成你自己的长随机串
- RPC_PORT=6800
- DISK_CACHE=64M
- SPECIAL_MODE=move
volumes:
- ./aria2-config:/config
- /mnt/downloads:/downloads
ports:
- "6800:6800"
- "6881:6881"
- "6881:6881/udp"
RPC_SECRET must be a strong private random value. AriaNg and API clients need it. Image-specific post-download settings such as SPECIAL_MODE require their own documentation; remove actions you have not configured or tested.
docker compose up -d
docker compose logs -f aria2 # 看有没有报错
Create /etc/aria2/aria2.conf if absent. Adapt the broad RPC settings before launch: bind RPC to loopback for a host proxy/tunnel and do not leave placeholder secrets or the tracker placeholder. Restrict configuration and session-file access because they can contain secrets or URLs:
# 下载目录
dir=/mnt/downloads
# RPC 配置 —— 让 AriaNg 和脚本能连进来
enable-rpc=true
rpc-listen-all=true
rpc-allow-origin-all=true
rpc-listen-port=6800
rpc-secret=换成你自己的长随机串
# 会话文件:重启后保住未完成的下载
save-session=/etc/aria2/aria2.session
input-file=/etc/aria2/aria2.session
save-session-interval=60
# 并发与分片(决定了下载速度)
continue=true
max-concurrent-downloads=5
max-connection-per-server=16
split=16
min-split-size=10M
# 磁盘
file-allocation=falloc
disk-cache=64M
# BT 相关
follow-torrent=true
enable-dht=true
bt-enable-lpd=true
bt-max-peers=128
seed-time=0
bt-tracker=(见下文,别留空)
# 日志
log=/var/log/aria2/aria2.log
log-level=warn
split and max-connection-per-server control splitting and per-server connections. split=16/max-connection-per-server=16 are examples, not a promise to saturate bandwidth. Some servers permit fewer connections or throttle aggressively; try 5 or a measured lower value.
min-split-size=10M prevents splitting very small files. Reducing the threshold to 1M can create excessive connections and 403 responses.
rpc-allow-origin-all=true allows browser origins broadly; use it only with a protected RPC path and only if the frontend needs it. Same-origin proxying can avoid unnecessary CORS access.
seed-time=0 stops seeding after completion. An alternative example is a 60-minute policy. Private trackers may require continued seeding; follow their actual rules and budget upload traffic.
For file-allocation, falloc requests filesystem-supported preallocation, while none skips it. On an unsuitable filesystem falloc may fail or perform poorly; evaluate trunc as an alternative. continue=true permits resuming where the source/protocol and control files support it; it does not guarantee every server supports ranges.
Tracker health is only one factor in torrent speed. Seeds, peers, DHT, reachability and provider policy matter too. Review a current public tracker list for authorized public torrents:
# 下载最新的 tracker 列表并替换进配置
curl -s https://trackerslist.com/best_aria2.txt
The list belongs after bt-tracker=, comma-separated. Do not install this original daily script unchanged: it inserts unvalidated network text into sed and restarts the service even after a bad response.
# /etc/cron.daily/aria2-tracker
#!/bin/bash
CONF=/etc/aria2/aria2.conf
NEW=$(curl -s https://trackerslist.com/best_aria2.txt)
sed -i "s|^bt-tracker=.*|bt-tracker=$NEW|" $CONF
systemctl restart aria2
A safer update pattern validates the response, treats URLs as data and changes the file atomically. This example requires Python 3 and runs as the aria2 account, which already owns the configuration in the native setup:
#!/usr/bin/env python3
import os
import re
import stat
import tempfile
from pathlib import Path
from urllib.parse import urlsplit
from urllib.request import urlopen
config = Path('/etc/aria2/aria2.conf')
with urlopen('https://trackerslist.com/best_aria2.txt', timeout=20) as response:
raw = response.read(262145)
if len(raw) > 262144:
raise SystemExit('Tracker response exceeds limit; configuration unchanged.')
trackers = [value.strip() for value in raw.decode('utf-8').strip().split(',')]
if not 1 <= len(trackers) <= 500:
raise SystemExit('Invalid tracker count; configuration unchanged.')
for value in trackers:
parsed = urlsplit(value)
if (parsed.scheme not in ('http', 'https', 'udp') or not parsed.hostname
or parsed.username or parsed.password or any(c.isspace() for c in value)):
raise SystemExit('Invalid tracker URL; configuration unchanged.')
original = config.read_text()
if len(re.findall(r'^bt-tracker=.*$', original, re.M)) != 1:
raise SystemExit('Expected one bt-tracker setting; configuration unchanged.')
updated = re.sub(r'^bt-tracker=.*$', lambda _: 'bt-tracker=' + ','.join(trackers), original, flags=re.M)
mode = stat.S_IMODE(config.stat().st_mode)
descriptor, temporary = tempfile.mkstemp(dir=config.parent, prefix='.tracker-')
try:
with os.fdopen(descriptor, 'w') as handle:
handle.write(updated)
handle.flush()
os.fsync(handle.fileno())
os.chmod(temporary, mode)
os.replace(temporary, config)
finally:
if os.path.exists(temporary):
os.unlink(temporary)
Install the reviewed script as root-owned /usr/local/sbin/update-aria2-trackers, executable and not writable by aria2. A root-managed daily job can run it with runuser -u aria2 -- /usr/local/sbin/update-aria2-trackers and restart aria2 only if it exits successfully. Save sessions and schedule restarts around active downloads. Keep a private configuration backup. This pattern does not establish that every listed tracker is trustworthy or appropriate for a private torrent.
Package installation does not always create the required service. The example runs as aria2:
# /etc/systemd/system/aria2.service
[Unit]
Description=Aria2 Download Service
After=network-online.target
Wants=network-online.target
[Service]
User=aria2
ExecStart=/usr/bin/aria2c --conf-path=/etc/aria2/aria2.conf
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
# 建个专用用户和目录,别用 root 跑下载器
sudo useradd -r -s /usr/sbin/nologin aria2
sudo mkdir -p /etc/aria2 /var/log/aria2 /mnt/downloads
sudo touch /etc/aria2/aria2.session
sudo chown -R aria2:aria2 /etc/aria2 /var/log/aria2 /mnt/downloads
sudo systemctl daemon-reload
sudo systemctl enable --now aria2
sudo systemctl status aria2
Do not run the downloader as root. Check config/secret permissions, writable download/session/log paths, and avoid applying the recursive ownership example to unrelated directories. Configure log rotation and space monitoring.
AriaNg is a browser client, not the download engine. Review the image and change its published mapping to 127.0.0.1:6880:6880 before startup:
ariang:
image: p3terx/ariang
container_name: ariang
restart: unless-stopped
ports:
- "6880:6880"
The original direct-address examples http://你的IP:6880 and http://你的IP:6800/jsonrpc are not the recommended public configuration. A browser's localhost is the user's computer, not the VPS. For a tunnel, forward both needed ports; for HTTPS, configure the proxy endpoint below.
- Set the RPC address to the endpoint actually reachable by the browser.
- Enter
RPC_SECRETprivately; a frontend page or extension with access to it can control downloads.
RPC secrets must not travel over plaintext public connections. This Caddy example serves the frontend and proxies JSON-RPC:
aria.yourdomain.com {
reverse_proxy /jsonrpc localhost:6800
reverse_proxy localhost:6880
}
Automatic certificate issuance needs correct DNS and reachable challenge ports; HTTP-01 commonly needs 80 as well as HTTPS 443. Add identity/IP restrictions for remote administration where appropriate.
- Configure AriaNg with
https://aria.yourdomain.com/jsonrpc. - Keep RPC 6800 and frontend 6880 private; preserve authorized SSH and the certificate challenge route.
sudo ufw allow 443/tcp
sudo ufw deny 6800
sudo ufw deny 6880
These UFW rules alone do not close Docker-published ports. First bind them to loopback or remove publication, then verify actual exposure from an authorized external network, including IPv6 and the Docker firewall backend. See the Caddy guide.
Paste an authorized direct link, magnet or torrent into AriaNg. The browser sends the request; the VPS performs the transfer.
Extensions such as Aria2 Explorer can submit a link through a configured RPC endpoint. Review extension trust and permissions before storing the secret or cookies; use only on devices/accounts you control.
Aria2 exposes JSON-RPC 2.0. The following calls run on the VPS, where localhost points to the private service. Replace the token placeholder without publishing the actual credential:
# 添加一个下载任务
curl -s http://localhost:6800/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "aria2.addUri",
"params": ["token:你的RPC_SECRET", ["https://example.com/file.zip"]]
}'
# 查看所有下载任务
curl -s http://localhost:6800/jsonrpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"aria2.tellActive","params":["token:你的RPC_SECRET"]}'
# 全局暂停
curl -s http://localhost:6800/jsonrpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"aria2.pauseAll","params":["token:你的RPC_SECRET"]}'
The token: prefix is required. Methods include aria2.addUri, aria2.tellActive, aria2.tellStatus, aria2.pause/pauseAll, aria2.remove and aria2.getGlobalStat. Automations such as RSS submissions also need duplicate handling, credentials, logs and failure recovery; do not mistake the endpoint alone for a complete scheduler.
AriaNg's responsive interface can work in a phone browser through the protected endpoint. Maintain authentication and device security as on desktop.
An rclone-mounted path can be used as the download directory:
dir=/mnt/cloud/downloads
This does not eliminate local storage use. Aria2 can write pieces out of order, while the cloud upload happens through VFS staging.
- Use
--vfs-cache-mode fullonly after testing the application's seek/write behavior and completed uploads. - Budget local cache: a 50 GB download can need tens of GB until upload completes. Prevent the downloader from falling back to an unmounted local directory.
See rclone mounts, inspect df -h before large transfers, and keep disk recovery available.
Keep rpc-secret private through loopback/tunnel or authenticated HTTPS. rpc-listen-all=true means broad listening; a proxy does not automatically close that bypass. Check IPv4/IPv6 and Docker publication explicitly.
For metered VPS traffic, set realistic download and upload/seeding limits:
# 全局限速 10M/s
curl -s http://localhost:6800/jsonrpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"aria2.changeGlobalOption","params":["token:你的RPC_SECRET",{"max-overall-download-limit":"10M"}]}'
max-overall-download-limit=10M persists a download cap. Aria2's 10M notation is a byte-rate limit, not 10 megabits per second; check units and total monthly transfer. A speed cap alone does not cap total usage. See traffic monitoring. Download/distribute only authorized material and follow provider/torrent-service terms.
AriaNg cannot connect: systemctl status aria2, ss -lntp | grep 6800, actual protected route, secret, then browser CORS. Enable rpc-allow-origin-all=true only when needed and contained, not as an access-control fix.
Unauthorized: verify the secret and token: prefix.
Torrent has no speed: inspect peers/seeds, tracker health bt-tracker, DHT/UDP reachability and provider policy. Tracker problems are not a proven 90% cause. Change ports only within authorized firewall/provider rules.
Direct link stops: check source expiry, range support, authentication and throttling. Try split/max-connection-per-server at 1–2 connections. --header="Cookie: xxx" or --load-cookies can supply authorized cookies; keep exported cookies secret.
Disk I/O saturation: file-allocation/falloc compatibility, storage latency and excessive concurrency; see I/O troubleshooting.
Tasks missing after reboot: save-session and input-file must point to the same writable persistent file. Keep aria2 control files and actual download data too.
1 vCPU/1 GB VPS: possible for light workloads, not guaranteed throughput. disk-cache and connection buffers consume memory. Original starting examples reduce disk-cache to 16M, split to 8 and tasks to 2; measure before adding work.
-
rpc-secretis strong and private. - RPC uses a private tunnel or protected HTTPS route.
- 6800/6880 bypasses are closed, including Docker; required SSH/challenge ports remain usable.
- Downloader runs as a dedicated ordinary account.
-
continue=true,save-sessionandinput-filesupport persistent recovery. -
bt-trackeris appropriate and updates validate data before applying. -
max-overall-download-limitmatches traffic limits; uploads are budgeted too. - Disk and monthly-traffic alerts work.
- Cloud mounts use reviewed
vfs-cache-mode full, enough cache and verified upload completion.