[工具] aria2 + AriaNg 配置

核心概念
aria2 是后端下载引擎，负责实际的下载任务；
AriaNg 是 Web 前端控制面板，通过 RPC 接口与 aria2 通信，两者配合使用，为您提供类似常规下载软件的图形化操作体验

一、 aria2 (后端下载引擎)#

1. 多平台安装#

根据您的操作系统执行对应的安装命令：

平台	安装命令
Arch Linux	`sudo pacman -S aria2`
Debian / Ubuntu	`sudo apt install aria2`
Fedora	`sudo dnf install aria2`
macOS	`brew install aria2`

2. 基础命令行使用#

在配置复杂的 RPC 服务之前，您可以直接使用 aria2c 命令进行简单下载：

普通下载：aria2c "https://example.com/file.zip"
下载到指定目录：aria2c -d /path/to/dir "URL"
指定文件名：aria2c -o "new_name.zip" "URL"
分段并发下载（加速）：aria2c -s 16 -x 16 "URL"
从文件列表批量下载：aria2c -i list.txt

命令行与后台服务的冲突
当您按照下文配置了 systemd/Launch Agents 自启动服务后：

不建议再运行 aria2c --conf-path=... "URL"：因为后台服务已占用了 RPC 端口（6800）和会话文件，再次运行会因“端口已被占用”而报错

如果您只想临时下载：请直接运行 aria2c "URL"（不带配置文件），这会启动一个独立的临时进程，不会干扰后台服务

如果您想通过命令行向后台服务添加任务：建议使用 aria2p 等工具，或直接在 AriaNg 界面操作

进阶：使用 aria2p 进行命令行管理
如果您希望在终端中像使用 top 一样管理后台的 aria2 任务，推荐安装 aria2p，它可以让你直接在命令行中添加、暂停、删除任务，而无需打开浏览器

3. 环境与基础配置#

3.1 创建必要文件#

所有平台的配置路径建议统一为 ~/.config/aria2：

1
mkdir -p ~/.config/aria2
2
touch ~/.config/aria2/aria2.session

文件作用说明

aria2.conf：主配置文件，定义下载目录、RPC 端口、安全令牌等运行参数

aria2.session：会话保存文件，记录未完成任务的状态，确保重启后进度不丢失

3.2 编写配置文件#

配置必读
rpc-secret 用于保护 RPC 接口，即便在本地使用，也建议设置令牌以防止恶意网页跨站访问您的 aria2 接口

Fish Shell 用户
由于 Fish 不支持 <<EOF (Heredoc) 语法，请先输入 bash 切换环境再执行以下命令，或者使用 bash -c '...' 运行

1
cat <<EOF > ~/.config/aria2/aria2.conf
2
# 下载设置
3
dir=$HOME/Downloads
4
file-allocation=falloc
5
continue=true
6

7
# RPC 设置 (用于 AriaNg 连接)
8
enable-rpc=true
9
rpc-allow-origin-all=true
10
rpc-listen-all=true
11
# 令牌设置（不需要则注释掉下面这行）
12
rpc-secret=YOUR_SECRET_TOKEN
13

14
# 进度保存
15
input-file=$HOME/.config/aria2/aria2.session
16
save-session=$HOME/.config/aria2/aria2.session
17
save-session-interval=60
18

19
# 性能优化
20
max-concurrent-downloads=5
21
max-connection-per-server=16
22
min-split-size=10M
23
split=10
24

25
# 代理（示例）
26
#all-proxy=http://127.0.0.1:7897
27
#no-proxy=localhost,127.0.0.1,::1
28
EOF

4. 设置自动启动#

🐧 Linux (使用 systemd)#

适用于 Arch, Debian, Ubuntu, Fedora 等发行版：

1
mkdir -p ~/.config/systemd/user/
2

3
cat <<EOF > ~/.config/systemd/user/aria2.service
4
[Unit]
5
Description=Aria2 RPC Service
6
After=network.target
7

8
[Service]
9
ExecStart=/usr/bin/aria2c --conf-path=%h/.config/aria2/aria2.conf
10

11
[Install]
12
WantedBy=default.target
13
EOF
14

15
# 启动并激活服务
16
systemctl --user daemon-reload
17
systemctl --user enable aria2
18
systemctl --user start aria2

Linux (systemctl) 维护

查看运行状态：systemctl --user status aria2

实时追踪日志：journalctl --user -u aria2 -f

重启服务：systemctl --user restart aria2

🍎 macOS (使用 Launch Agents)#

由于 macOS 下的 brew services 对自定义配置文件的支持有限，建议使用 Launch Agents 实现完美自启：

创建自启动配置文件：

1
mkdir -p ~/Library/LaunchAgents
2

3
cat <<EOF > ~/Library/LaunchAgents/homebrew.mxcl.aria2.plist
4
<?xml version="1.0" encoding="UTF-8"?>
5
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
6
<plist version="1.0">
7
<dict>
8
    <key>Label</key>
9
    <string>homebrew.mxcl.aria2</string>
10
    <key>ProgramArguments</key>
11
    <array>
12
        <string>$(which aria2c)</string>
13
        <string>--conf-path=$HOME/.config/aria2/aria2.conf</string>
14
    </array>
15
    <key>RunAtLoad</key>
16
    <true/>
17
    <key>KeepAlive</key>
18
    <true/>
19
    <key>StandardOutPath</key>
20
    <string>$HOME/.config/aria2/aria2.log</string>
21
    <key>StandardErrorPath</key>
22
    <string>$HOME/.config/aria2/aria2.log</string>
23
</dict>
24
</plist>
25
EOF

加载并启动服务：

1
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.aria2.plist

路径说明
如果您是 Apple Silicon (M1/M2/M3) 用户，aria2c 的路径通常为 /opt/homebrew/bin/aria2c，请根据 which aria2c 的实际输出修改 plist 文件中的路径

macOS (launchctl) 维护

启动服务：launchctl load ~/Library/LaunchAgents/homebrew.mxcl.aria2.plist

停止/卸载服务：launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.aria2.plist

查看运行日志：tail -f ~/.config/aria2/aria2.log

查看服务状态：launchctl list | grep aria2

二、 AriaNg (前端控制面板)#

1. 获取方式#

Arch Linux: yay -S ariang-git (静态文件位于 /usr/share/webapps/ariang)
通用方法: 从 GitHub Releases 下载并解压 AriaNg-x.x.x.zip

2. 访问方式#

Linux (systemd) 自动化部署
对于 Linux 用户（尤其是安装了 ariang 包的 Arch 用户），建议使用 systemd 托管 AriaNg，使其在后台运行并随开机自启：
Terminal window
1
mkdir -p ~/.config/systemd/user/
2

3
cat <<EOF > ~/.config/systemd/user/ariang.service
4
[Unit]
5
Description=AriaNg Web Interface
6
After=network.target
7

8
[Service]
9
ExecStart=/usr/bin/python3 -m http.server -d /usr/share/webapps/ariang 8000
10
Restart=always
11

12
[Install]
13
WantedBy=default.target
14
EOF
15

16
# 启动并启用服务
17
systemctl --user daemon-reload
18
systemctl --user enable --now ariang.service
访问地址：http://localhost:8000

其他访问方式

直接访问：浏览器打开解压目录下的 index.html

临时启动：在 AriaNg 目录运行 python3 -m http.server 8000

专业 Web 服务器：使用 Nginx/Apache 部署静态目录

3. 连接到后端#

打开 AriaNg，进入 AriaNg 设置 -> RPC
填入 Aria2 地址 (localhost)、端口 (6800) 及 RPC 秘钥 (YOUR_SECRET_TOKEN)
点击“重新加载”，状态显示“已连接”即告成功

关于配置存储
AriaNg 的设置保存在浏览器的 Local Storage 中，清除浏览器缓存或更换浏览器后，需要重新填写连接信息

进阶：快捷连接 URL
您可以直接通过带参数的 URL 访问来自动填好配置： http://localhost:8000/#!/settings/rpc/set/ws/localhost/6800/jsonrpc/BASE64_ENCODED_SECRET

三、常见问题排查 (Troubleshooting)#

连接失败排查清单

进程检查：systemctl --user status aria2 (Linux) 或 launchctl list (macOS)

端口检查：ss -tulpn | grep 6800 (Linux) 或 netstat -an | grep 6800 (macOS) 确认端口已监听

密钥匹配：aria2.conf 中的 rpc-secret 必须与 AriaNg 填写的完全一致

混合内容拦截：若通过 HTTPS 访问 AriaNg 但 RPC 是 WS，请在浏览器地址栏允许“不安全内容”加载

一、 aria2 (后端下载引擎)#

1. 多平台安装#

2. 基础命令行使用#

3. 环境与基础配置#

3.1 创建必要文件#

3.2 编写配置文件#

4. 设置自动启动#

🐧 Linux (使用 systemd)#

🍎 macOS (使用 Launch Agents)#

二、 AriaNg (前端控制面板)#

1. 获取方式#

2. 访问方式#

3. 连接到后端#

三、 常见问题排查 (Troubleshooting)#

三、常见问题排查 (Troubleshooting)#