跳转到主要内容

用 Docker 搭建 24/7 常驻 aria2 下载服务器

完全由你掌控的完整、可靠部署：小型 Alpine 容器中的 aria2 引擎、规范的 aria2.conf、可选的 AriaNg WebUI、安全的远程访问、下载后自动处理与健康检查。适用于任何 Linux 主机、Synology、QNAP、Unraid 或 VPS。

最后核对 2026-09 · aria2 v1.37.0 · Docker Engine 24+ / Compose v2

开始之前

为什么用 Docker，我们构建什么

用容器运行 aria2，可获得隔离、可复现、长期在线的下载器，更新或迁移时无需触碰主机。整个栈由三个独立部分组成：

1. 引擎（aria2c）

多协议下载器，读取挂载的 aria2.conf，并在端口 6800 上提供 JSON-RPC。

2. WebUI（可选）

AriaNg 或在线 WebUI通过 RPC 与引擎通信，完全可替换。

3. 存储

两个挂载：/downloads（数据）与 /config（会话、日志、钩子），两者都保存在容器之外。

我们从 alpine 构建自己的小镜像，使指南准确且可移植 – 不依赖无法检查的第三方镜像隐藏环境变量。（也可用社区镜像作为捷径，但请按其自身文档核对变量。）

三个文件

创建一个目录（如 /opt/aria2），把这三个文件放在一起。

1. aria2.conf

aria2.conf 
dir=/downloads
continue=true
file-allocation=falloc
max-concurrent-downloads=5
max-connection-per-server=16
min-split-size=10M
split=16

# --- RPC（任何 WebUI 都需要） ---
enable-rpc=true
rpc-listen-all=true
rpc-listen-port=6800
rpc-secret=CHANGE_ME_STRONG_SECRET
# 浏览器 WebUI 需要；见安全说明
rpc-allow-origin-all=true

# --- BitTorrent ---
bt-max-peers=128
# listen ports must match the ports published in docker-compose.yml
listen-port=6888
dht-listen-port=6888
enable-dht=true
enable-peer-exchange=true
bt-enable-lpd=true
seed-ratio=1.0
disk-cache=64M

# --- 会话持久化（跨重启保留） ---
save-session=/config/aria2.session
input-file=/config/aria2.session
save-session-interval=60
log=/config/aria2.log

2. Dockerfile

Dockerfile 
FROM alpine:3.20
RUN apk add --no-cache aria2 ca-certificates tzdata bash
COPY aria2.conf /etc/aria2/aria2.conf
VOLUME ["/downloads", "/config"]
EXPOSE 6800 6888 6888/udp
# aria2 refuses to start if input-file is missing, so create the session file first
ENTRYPOINT ["sh", "-c", "touch /config/aria2.session && exec aria2c --conf-path=/etc/aria2/aria2.conf"]

3. docker-compose.yml

docker-compose.yml 
services:
  aria2:
    build: .
    container_name: aria2
    restart: unless-stopped
    environment:
      - TZ=UTC
    volumes:
      - ./aria2-config:/config
      - ./downloads:/downloads
    ports:
      - "6800:6800"      # JSON-RPC（保持私有！）
      - "6888:6888"      # BitTorrent TCP
      - "6888:6888/udp"  # BitTorrent DHT UDP

引擎会把 aria2.session 与 aria2.log 写入 ./aria2-config，因此它们留在主机上，跨重启与镜像重建都能保留。

5 分钟部署

mkdir -p /opt/aria2/aria2-config /opt/aria2/downloads
cd /opt/aria2
# 将 aria2.conf、Dockerfile、docker-compose.yml 保存到此处

docker compose up -d --build      # 首次构建后启动
docker compose ps                 # 确认正在运行
docker compose logs -f aria2      # 观察启动

确认 RPC 端点响应（替换密钥）：

curl -s http://127.0.0.1:6800/jsonrpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"aria2.getVersion","params":["token:CHANGE_ME_STRONG_SECRET"]}'

返回包含 version 字段的 JSON，说明引擎与密钥都正确。

配置与保护

本栈中的关键 aria2.conf 设置
设置原因
rpc-secret必需。没有它，任何能访问 6800 端口的人都能控制你的下载。
rpc-allow-origin-all=true允许浏览器 WebUI（AriaNg、本站 WebUI）调用 RPC。只有在端口保持私有时才安全。
file-allocation=falloc快速预留空间并减少碎片（不支持的文件系统用 none）。
disk-cache=64M在内存中批量写入，减少微写入，延长磁盘寿命。
continue=true跨重启恢复未完成的下载。
save-session / input-file持久化队列；重启后自动恢复。

切勿将 6800 端口发布到公网。 将其绑定在主机/局域网，并通过 VPN 或带认证的反向代理访问（见下）。

添加 WebUI

选择适合你工作流的方式：

  ariang:
    image: nginx:alpine
    container_name: ariang
    restart: unless-stopped
    volumes:
      - ./ariang:/usr/share/nginx/html:ro
    ports:
      - "6880:80"

在 AriaNg 设置中，将 RPC 主机设为你的服务器、端口设为 6800，并粘贴 rpc-secret。

NAS 与平台说明

Linux / VPS / Raspberry Pi

按 5 分钟部署操作。Pi 上把 disk-cache 保持适中，并预期吞吐较低。

Synology DSM 7+

Container Manager → 项目 → 创建；粘贴 compose。挂载使用真实 DSM 路径（如 /volume1/docker/aria2/config 与 /volume1/downloads）。

QNAP / Unraid

Container Station → 创建应用，或 Unraid 的 Compose 插件。将 /config 映射到 appdata，/downloads 映射到共享。

文件属主

若其他应用（Plex/Jellyfin/Arr）需读取文件，请设置容器用户或 chown。我们的 Alpine 镜像默认以 root 运行；向服务加入 user: "1000:1000" 以匹配主机 UID/GID。

安全远程访问（HTTPS 反向代理）

要通过互联网访问 WebUI，请在前面放置带认证的 HTTPS 代理，切勿直接暴露 6800。此外，现代浏览器会阻止 HTTPS 页面调用明文 RPC（混合内容），因此需要 TLS + WebSocket 转发。

Nginx：TLS + WebSocket RPC + Basic 认证 
server {
    listen 443 ssl;
    server_name aria2.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    auth_basic "aria2";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:6880;      # AriaNg
        proxy_set_header Host $host;
    }

    location /jsonrpc {
        proxy_pass http://127.0.0.1:6800/jsonrpc;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;              # 保持 WebSocket
    }
}

多层防护：HTTPS、认证层（Basic 认证或身份代理）、强 rpc-secret 与防火墙。VPN（WireGuard/Tailscale）是最简单的免暴露方案。

下载后自动化

aria2 通过 on-download-complete 在下载完成时执行命令。将其加入 aria2.conf 并挂载脚本：

# aria2.conf 中
on-download-complete=/config/on-complete.sh
on-download-error=/config/on-error.sh

# /config/on-complete.sh  (chmod +x)
#!/bin/bash
GID="$1"; NUM_FILES="$2"; TARGET_PATH="$3"   # $3 是第一个文件的路径
logger "aria2 完成: $TARGET_PATH"
# 示例:
#   rclone move "$(dirname "$TARGET_PATH")" remote:downloads/
#   unzip -o "$TARGET_PATH" -d "$(dirname "$TARGET_PATH")"
#   curl -s "https://ntfy.sh/mytopic" -d "下载完成: $(basename "$TARGET_PATH")"

$1 = GID，$2 = 文件数，$3 = 第一个文件的路径。钩子要快且不阻塞；重活放到后台。

健康与监控

    healthcheck:
      test: ["CMD-SHELL", "aria2c --version >/dev/null && wget -qO- http://127.0.0.1:6800/jsonrpc --post-data='{\"jsonrpc\":\"2.0\",\"id\":\"h\",\"method\":\"aria2.getVersion\",\"params\":[\"token:CHANGE_ME_STRONG_SECRET\"]}' >/dev/null"]
      interval: 60s
      timeout: 10s
      retries: 3

故障排查

WebUI 显示“Disconnected”/ RPC 失败

检查三点：容器在运行（docker compose ps）、端口 6800 已映射、密钥与 rpc-secret 一致。若 WebUI 通过 HTTPS 加载，其 RPC 调用也必须是 HTTPS/WSS（混合内容规则）– 使用上面的反向代理。

种子 0 个 Peer / DHT 0 节点

映射并转发一个 TCP 与 UDP 端口（此处用 6888），并通过Tracker 列表或配置中的 bt-tracker=… 加入新 Tracker。DHT 一旦能访问网络就会启动。

写入下载时权限不足

容器以其用户（默认 root）写入。要么设置 user: "1000:1000" 匹配主机，要么 chown ./downloads 让容器用户可写。

重启后下载从 0 开始

会话持久化未配置。确保 save-session、input-file、save-session-interval 指向已挂载路径（此处为 /config/aria2.session）且 continue=true。

6800 端口被占用 / 容器无法启动

主机上另一个 aria2 或应用占用了 6800。修改主机映射（如 "6801:6800"）或停止该进程。

常见问题

需要 WebUI 容器吗？

不需要。AriaNg、本站在线 WebUI或任何 RPC 客户端都能直接与引擎通信。WebUI 只是 RPC API 之上的可选装饰。

如何更新 aria2？

有新 Alpine 包时重建镜像：docker compose build --no-cache && docker compose up -d。配置、会话与下载都保存在挂载中。

p3terx/aria2-pro 这类社区镜像可以吗？

只要核对其文档化的变量即可。本指南构建自己的最小镜像以保证配置明确且可移植，但维护良好的社区镜像是有效的捷径。