---
url: https://eoht.net/vps/serve/aria2-ariang.md
description: 使用 Docker 部署 Aria2 Pro 和 AriaNg，明确下载目录权限、RPC 密钥、宿主机端口与容器端口，并验证浏览器连接和下载文件落盘。
---

# Docker 搭建 aria2 + AriaNg {#docker-aria2-ariang-setup}

本文采用 [P3TERX/Aria2-Pro-Docker](https://github.com/P3TERX/Aria2-Pro-Docker) 的镜像与参数。需要已有可用的 Docker Engine、可写的持久化目录，以及未占用的宿主机端口。已有同名容器时先查看其挂载和配置，不要直接删除重建。

示例将 RPC 和 AriaNg 网页绑定到宿主机回环地址，通过 SSH 隧道访问，适合 VPS。若改成局域网地址或反向代理，应同时配置访问限制及 TLS；不要在公网直接暴露明文 RPC。

## 安装 aria2 {#install-aria2}

### 拉取 aria2 镜像 {#pull-aria2-image}

```sh
docker pull p3terx/aria2-pro
```

### 启动容器 {#start-aria2-container}

先选择下载文件的宿主机所有者。`download` 是示例账户名，必须替换为已经存在、且需要读写下载文件的账户；用当前账户可改为 `aria2_file_user=$(id -un)`。不要依赖 Shell 自动提供 `$UID` / `$GID`，也不要把 UID、GID 当成用户名。

以下步骤在同一 Bash 会话执行；`/srv/aria2/downloads` 若改为 NAS 路径，先确认实际挂载已就绪、读写权限和数值 UID/GID 一致。

```bash
aria2_file_user='download'
aria2_uid=$(id -u "$aria2_file_user") &&
  aria2_gid=$(id -g "$aria2_file_user") &&
  sudo install -d -m 0755 -o "$aria2_uid" -g "$aria2_gid" \
    /srv/aria2/config /srv/aria2/downloads
```

账户不存在或目录创建失败时停止。已有目录含其他数据时，应先核对现有权限，不要递归改动整块 NAS 的所有者。输入自设的高强度 RPC 密钥；这里使用 Bash 的隐藏输入，避免把密钥直接写入命令历史：

```bash
read -r -s -p '输入自设的 RPC 密钥：' aria2_rpc_secret
printf '\n'
```

确认变量非空后创建容器：

```bash
: "${aria2_uid:?先选择文件所有者}"
: "${aria2_gid:?先选择文件所属组}"
: "${aria2_rpc_secret:?RPC 密钥不能为空}"
docker run -d \
  --name aria2 \
  --restart unless-stopped \
  --log-opt max-size=1m \
  -e PUID="$aria2_uid" \
  -e PGID="$aria2_gid" \
  -e UMASK_SET=022 \
  -e RPC_SECRET="$aria2_rpc_secret" \
  -e RPC_PORT=6800 \
  -e LISTEN_PORT=16888 \
  -p 127.0.0.1:16800:6800 \
  -p 16888:16888 \
  -p 16888:16888/udp \
  -v /srv/aria2/config:/config \
  -v /srv/aria2/downloads:/downloads \
  p3terx/aria2-pro
unset aria2_rpc_secret
```

**参数和目录对应关系**

| 参数 | 本文配置 | 作用 |
| --- | --- | --- |
| `PUID` / `PGID` | `id -u` / `id -g` 的结果 | 下载文件使用的用户和组；与 FileRun 等共享目录时需协调相同的数值身份及权限 |
| `UMASK_SET` | `022` | 新文件的权限掩码；其他用户通常只有读取权限 |
| `RPC_SECRET` | 自设密钥 | AriaNg 连接 RPC 时使用，不沿用镜像默认密钥 |
| `RPC_PORT` | 容器内 `6800` | 宿主机通过 `127.0.0.1:16800` 转发到此端口 |
| `LISTEN_PORT` | `16888` | BT TCP 与 DHT UDP 监听端口，此处容器内外保持一致 |
| `/srv/aria2/config:/config` | 配置目录 | 持久化配置和会话数据 |
| `/srv/aria2/downloads:/downloads` | 下载目录 | AriaNg 中使用 `/downloads`，宿主机查看 `/srv/aria2/downloads` |

容器环境和生成的配置会保存 RPC 密钥，具有 Docker 管理权限的账户可以读取它。若仅下载 HTTP / HTTPS 文件，不使用 BT，可省略两个 `16888` 端口映射；使用 BT 入站时还需核对防火墙、云安全组及 NAT 转发。

## 安装 AriaNg {#install-ariang}

### 拉取 AriaNg 镜像 {#pull-ariang-image}

```sh
docker pull p3terx/ariang
```

### 启动容器 {#start-ariang-container}

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

### 配置 RPC {#configure-aria2-rpc}

在自己电脑的终端建立 SSH 隧道，将 `user@server.example.com` 替换为实际 SSH 登录地址；端口在本机已占用时需相应调整转发与浏览器设置。保持此连接打开：

```sh
ssh -N -L 16880:127.0.0.1:16880 -L 16800:127.0.0.1:16800 user@server.example.com
```

浏览器访问 `http://127.0.0.1:16880`，打开 **AriaNg 设置** 中的 RPC 配置。以下截图辅助定位，字段名称以当前界面为准。

![aria2+AriaNg =688x](https://i.eoht.net/docs/202404290014327.webp)

![aria2+AriaNg =688x](https://i.eoht.net/docs/202404290015325.webp "配置RPC")

| 字段 | 本文填写值 |
| --- | --- |
| RPC 别名 | 自定义 |
| RPC 地址 | `127.0.0.1`，对应浏览器所在电脑的 SSH 转发入口 |
| RPC 端口 | `16800`，不是容器内的 `6800` |
| RPC 路径 | `jsonrpc`（完整请求路径为 `/jsonrpc`） |
| RPC 协议 / 请求方法 | HTTP / POST，传输由 SSH 隧道保护 |
| RPC 密钥 | 创建 aria2 容器时输入的同一密钥 |

AriaNg 是浏览器端界面，RPC 请求由浏览器发出，不是由 AriaNg 容器发出。因此，不能直接填另一个容器的内部名称。若通过 HTTPS 反向代理访问网页，RPC 也需使用浏览器可达的 HTTPS / WSS 地址，避免混合内容被拦截。

## 验证与排查 {#verify-aria2-downloads}

```sh
docker ps --filter name=aria2 --filter name=ariang
docker logs --tail 50 aria2
docker logs --tail 50 ariang
docker port aria2
docker port ariang
```

刷新 AriaNg，确认显示“已连接”，再添加一个有权下载的小文件。验证任务完成，并在宿主机 `/srv/aria2/downloads` 检查文件大小、所有者及内容。

无法连接时按 SSH 隧道、宿主机端口 `16800`、RPC 密钥、容器日志的顺序排查；显示已连接但下载失败时检查下载 URL、服务器出站网络和目录写入权限。配置及下载文件位于挂载目录，后续更新容器应保留这些目录并先备份配置。