macOS系统配置Aria2

前言

Aria2是什么

Aria2是一款自由、跨平台命令行界面的下载管理器，支持的下载协议有：HTTP、HTTPS、FTP、Bittorrent以及Metalink。
Aria2的另一个特性便是可以使用JSON-RPC和XML-RPC进行HTTP远程下载控制，JSON-RPC接口可通过WebSocket获得。

本人主要拿来下载种子Bittorrent文件以及多线程下载。

配置前的准备工作

安装 Homebrew 。
会使用 vim 或者其他编辑器。
常用命令：
在打开的vim 界面中按 i 键进入编辑模式；按 Esc 键退出编辑模式，进入命令行模式；使用 :wq 命令保存并退出。

Docker安装方式（可选）

2024/03/14 更新：
如果会使用docker，可以通过安装docker镜像而不影响本地环境。点击查看docker的轻量化安装教程，镜像的话可以选择Aria2-Pro。具体安装教程请参照仓库README文件（包含中文教程），本文不做展开。
本次更新只是多提供了一个选择，无需docker安装的忽略本小节即可。

安装并配置Aria2

1
2
3
4
5
6
7
# 使用 Homebrew 安装 aria2
brew install aria2

# 创建配置文件aria2.conf和空对话文件aria2.session
mkdir ~/.aria2 && cd ~/.aria2
touch aria2.conf
touch aria2.session

编辑配置文件 aria2.conf ：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
## 文件保存相关 ##

# 文件的保存路径(可使用绝对路径或相对路径), 默认: Mac下Downloads下载文件夹
dir=${HOME}/Downloads
# 启用磁盘缓存, 0为禁用缓存, 需1.16以上版本, 默认:16M
disk-cache=32M
# 文件预分配方式, 能有效降低磁盘碎片, 默认:prealloc
# 预分配所需时间: none < falloc ? trunc < prealloc
# falloc和trunc则需要文件系统和内核支持
# NTFS建议使用falloc, EXT3/4建议trunc, MAC 下需要注释此项
#file-allocation=none
# 断点续传
continue=true

## 下载连接相关 ##

# 最大同时下载任务数, 运行时可修改, 默认:5
#max-concurrent-downloads=5
# 同一服务器连接数, 添加时可指定, 默认:1, 最大值16
max-connection-per-server=5
# 最小文件分片大小, 添加时可指定, 取值范围1M -1024M, 默认:20M
# 假定size=10M, 文件为20MiB 则使用两个来源下载; 文件为15MiB 则使用一个来源下载
min-split-size=10M
# 单个任务最大线程数, 添加时可指定, 默认:5
#split=5
# 分片选择算法,有助于视频的边下边播同时兼顾减少建立连接的次数
stream-piece-selector=geom
# 整体下载速度限制, 运行时可修改, 默认:0
#max-overall-download-limit=0
# 单个任务下载速度限制, 默认:0
#max-download-limit=0
# 整体上传速度限制, 运行时可修改, 默认:0
#max-overall-upload-limit=0
# 单个任务上传速度限制, 默认:0
#max-upload-limit=0
# 禁用IPv6, 默认:false
#disable-ipv6=true
# 连接超时时间, 默认:60
#timeout=60
# 最大重试次数, 设置为0表示不限制重试次数, 默认:5
#max-tries=5
# 设置重试等待的秒数, 默认:0
#retry-wait=0

## 进度保存相关 ##

# 日志文件
log-level=notice
log=${HOME}/.aria2/aria2.log
# 从会话文件中读取下载任务
# 需提前创建一个空文件否则会报错
input-file=${HOME}/.aria2/aria2.session
# 在Aria2退出时保存`错误/未完成`的下载任务到会话文件
save-session=${HOME}/.aria2/aria2.session
# 定时保存会话, 0为退出时才保存, 需1.16.1以上版本, 默认:0
save-session-interval=60

# 强制保存会话, 即使任务已经完成, 默认:false
# 较新的版本开启后会在任务完成后依然保留.aria2文件
#force-save=true

## RPC相关设置 ##

# 启用RPC, 默认:false
enable-rpc=true
# 允许所有来源, 默认:false
rpc-allow-origin-all=true
# 允许非外部访问, 默认:false
rpc-listen-all=true
# RPC监听端口, 端口被占用时可以修改, 默认:6800
rpc-listen-port=6800
# 设置的RPC授权令牌
# 此处使用`openssl rand -base64 32`命令生成<TOKEN>
# 此次需要自行配置，将<TOKEN>整体替换为你的RPC“密码”
rpc-secret=<TOKEN>
# 是否启用 RPC 服务的 SSL/TLS 加密,
# 启用加密后 RPC 服务需要使用 https 或者 wss 协议连接
#rpc-secure=true
# 在 RPC 服务中启用 SSL/TLS 加密时的证书文件,
# 使用 PEM 格式时，您必须通过 --rpc-private-key 指定私钥
#rpc-certificate=/path/to/certificate.pem
# 在 RPC 服务中启用 SSL/TLS 加密时的私钥文件
#rpc-private-key=/path/to/certificate.key

## HTTP 设置 ##

# 自定义 User Agent
user-agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.85 Safari/537.36

## BT/PT下载相关 ##

# 当下载的是一个种子(以.torrent结尾)时, 自动开始BT任务, 默认:true
follow-torrent=true
# BT监听端口, 当端口被屏蔽时使用, 默认:6881-6999
listen-port=6881-6999
# 单个种子最大连接数, 默认:55
#bt-max-peers=55

### DHT 功能, 仅对 BT 生效, PT 无效###
# 打开 DHT (IPv4) 功能
enable-dht=true
# 打开 DHT (IPv6) 功能
enable-dht6=true
# DHT网络监听端口, 默认:6881-6999
dht-listen-port=6881-6999
# 本地节点查找
bt-enable-lpd=true
# 种子交换
enable-peer-exchange=true
# DHT (IPv4) 路由表文件路径
dht-file-path=${HOME}/.aria2/dht.dat
# DHT (IPv6) 路由表文件路径
dht-file-path6=${HOME}/.aria2/dht6.dat

# 客户端伪装, PT需要
peer-id-prefix=-UT341-
peer-agent=uTorrent/341(109279400)(30888)

# 同一服务器连接数
# 每个种子限速, 对少种的PT很有用, 默认:50K
#bt-request-peer-speed-limit=50K
# 当种子的分享率达到这个数时, 自动停止做种, 0为一直做种, 默认:1.0
seed-ratio=0
# BT校验相关, 默认:true
#bt-hash-check-seed=true
# 继续之前的BT任务时, 无需再次校验, 默认:false
bt-seed-unverified=true
# 保存磁力链接元数据为种子文件(.torrent文件), 默认:false
bt-save-metadata=true

# BT 服务器地址
# 逗号分隔的 BT 服务器地址. 如果服务器地址在 --bt-exclude-tracker 选项中, 其将不会生效.
bt-tracker=udp://tracker.coppersurfer.tk:6969/announce,udp://tracker.leechers-paradise.org:6969/announce,udp://tracker.opentrackr.org:1337/announce,udp://p4p.arenabg.com:1337/announce,udp://9.rarbg.to:2710/announce,udp://9.rarbg.me:2710/announce,udp://tracker.internetwarriors.net:1337/announce,udp://exodus.desync.com:6969/announce,udp://tracker.tiny-vps.com:6969/announce,udp://tracker.moeking.me:6969/announce,udp://retracker.lanta-net.ru:2710/announce,udp://open.stealth.si:80/announce,udp://open.demonii.si:1337/announce,udp://tracker.torrent.eu.org:451/announce,udp://tracker.cyberia.is:6969/announce,udp://denis.stalker.upeer.me:6969/announce,udp://tracker3.itzmx.com:6961/announce,udp://ipv4.tracker.harry.lu:80/announce,udp://valakas.rollo.dnsabr.com:2710/announce,udp://tracker.nyaa.uk:6969/announce,udp://retracker.netbynet.ru:2710/announce,udp://opentor.org:2710/announce,udp://explodie.org:6969/announce,http://explodie.org:6969/announce,udp://zephir.monocul.us:6969/announce,udp://xxxtor.com:2710/announce,udp://tracker.zum.bi:6969/announce,udp://tracker.yoshi210.com:6969/announce,udp://tracker.uw0.xyz:6969/announce,udp://tracker.sbsub.com:2710/announce,udp://tracker.lelux.fi:6969/announce,udp://tracker.iamhansen.xyz:2000/announce,udp://tracker.filemail.com:6969/announce,udp://tracker.dler.org:6969/announce,udp://retracker.sevstar.net:2710/announce,udp://retracker.akado-ural.ru:80/announce,udp://open.nyap2p.com:6969/announce,udp://chihaya.toss.li:9696/announce,udp://bt2.archive.org:6969/announce,udp://bt1.archive.org:6969/announce,udp://bt.okmp3.ru:2710/announce,https://tracker.nanoha.org:443/announce,http://tracker.torrentyorg.pl:80/announce,http://tracker.opentrackr.org:1337/announce,http://tracker.internetwarriors.net:1337/announce,http://tracker.bt4g.com:2095/announce,http://t.nyaatracker.com:80/announce,http://retracker.sevstar.net:2710/announce,http://pow7.com:80/announce,http://mail2.zelenaya.net:80/announce,http://h4.trakx.nibba.trade:80/announce,udp://tracker4.itzmx.com:2710/announce,udp://tracker2.itzmx.com:6961/announce,udp://tracker.zerobytes.xyz:1337/announce,udp://tracker.swateam.org.uk:2710/announce,udp://tr.bangumi.moe:6969/announce,udp://qg.lorzl.gq:2710/announce,udp://opentracker.i2p.rocks:6969/announce,udp://bt2.54new.com:8080/announce,https://tracker.opentracker.se:443/announce,https://tracker.lelux.fi:443/announce,http://www.loushao.net:8080/announce,http://vps02.net.orel.ru:80/announce,http://tracker4.itzmx.com:2710/announce,http://tracker3.itzmx.com:6961/announce,http://tracker2.itzmx.com:6961/announce,http://tracker1.itzmx.com:8080/announce,http://tracker01.loveapp.com:6789/announce,http://tracker.zerobytes.xyz:1337/announce,http://tracker.yoshi210.com:6969/announce,http://tracker.nyap2p.com:8080/announce,http://tracker.lelux.fi:80/announce,http://tracker.bz:80/announce,http://opentracker.i2p.rocks:6969/announce,http://open.acgnxtracker.com:80/announce
# BT 排除服务器地址
bt-exclude-tracker=

# 启用后台进程
daemon=false

# 部分事件hook
# 如果使用Aria2 Explorer插件请注释或者删除该部分内容
# 即 on-bt-download-complete 和 on-download-complete
# BT下载完成(如有做种将包含做种，如需调用请务必确定设定完成做种条件)
on-bt-download-complete=${HOME}/.aria2/download-complete-hook.sh
# 下载完成
on-download-complete=${HOME}/.aria2/download-complete-hook.sh
# 下载错误
on-download-error=

# 代理 仅支持 HTTP 协议
#all-proxy=http://127.0.0.1:1087

本配置文件注意事项如下:

默认开启 RPC 模式。
已设置RPC授权令牌，请自行修改为自己的。
已经添加 BT tracker 。
如果使用后文提到的Aria2 Explorer插件，请注释或者删除配置文件末尾的部分事件hook内容。

设置为开机自启动

创建用户启动文件

1
2
touch ~/Library/LaunchAgents/aria2.plist
vim ~/Library/LaunchAgents/aria2.plist

写入如下：

2023/11/16 更新：
经评论区老哥提醒，由于brew安装位置的不同(M系列芯片默认安装位置可能在/opt/homebrew/bin/目录下)，下面文件中的ProgramArguments参数需要自行修改为本机aria2c的位置，可以使用which命令查看具体位置：
示例文件中的相关参数目录还是以上图我的aria2c目录/usr/local/bin/aria2c为例，你可能需要修改为/opt/homebrew/bin/aria2c或者其他自定义目录。

2023.10.13 更新：
感谢评论区小伙伴的提醒，aria2在macOS Sonoma版本使用下述plist“不能”自启动。
根据官方issue#2083讨论，该bug是由于aria2的依赖 gettext 导致的，截止文章更新时该bug应该已经修复，使用brew upgrade更新全部依赖即可。
如果仍然无法使用，可以使用以下plist文件内容：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>EnvironmentVariables</key>
    <dict>
        <key>LC_MESSAGES</key>
        <string>C</string>
    </dict>
    <key>KeepAlive</key>
    <true/>
    <key>Label</key>
    <string>aria2</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/aria2c</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/Users/用户名/Downloads</string>
</dict>
</plist>
主要是添加了一个LC_MESSAGES='C'键值对。请注意，万不得已才使用上述修改内容，因为该bug按理说已经得到官方修复。

以下为原文件内容（默认使用该文件即可，出现问题无法解决再尝试上述修改文件）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>KeepAlive</key>
    <true/>
    <key>Label</key>
    <string>aria2</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/aria2c</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/Users/用户名/Downloads</string>
</dict>
</plist>

注意事项：
一定要记得替换WorkingDirectory参数下的用户名，以及检查ProgramArguments参数下的目录是否正确。

1
2
3
4
5
# 检查plist语法是否正确
plutil ~/Library/LaunchAgents/aria2.plist

# 修改文件权限
chmod 644 ~/Library/LaunchAgents/aria2.plist

添加并启用自启动项

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 添加自启动项: aria2
launchctl load ~/Library/LaunchAgents/aria2.plist

# 删除自启动项: aria2
launchctl unload ~/Library/LaunchAgents/aria2.plist

# 启动服务: aria2
launchctl start aria2

# 停止服务: aria2
launchctl stop aria2

# 强制添加 加上-w参数
# 这个命令是最后无奈之举才尝试运行，不推荐
launchctl load -w ~/Library/LaunchAgents/aria2.plist

注意事项：
如果以前添加过aria2启动项，再次操作时记得先删除启动项再重新添加！
2024/03/14 更新：
如果提示诸如Load failed: 5: Input/output error Try running launchctl bootstrap as root for richer errors.此类的错误，请先按照上述指引检查aria2c路径或者尝试更新全部brew依赖。若没有解决请尝试先删除启动项再进行load。如果还是不行，可以加上-w参数强制添加。实在不行请评论区反馈或者查看以往评论进行尝试。

添加自动更新 BT tracker 功能

创建 trackers-list-aria2.sh 脚本

1
2
touch ~/.aria2/trackers-list-aria2.sh
vim ~/.aria2/trackers-list-aria2.sh

脚本内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/bin/bash
# 文件名 trackers-list-aria2.sh
# aria2 设置文件路径
CONF=${HOME}/.aria2/aria2.conf

# 设置选择的 trackerlist （可选 all_aria2.txt, best_aria2.txt, http_aria2.txt）
trackerfile=all_aria2.txt
# downloadfile=https://raw.githubusercontent.com/ngosang/trackerslist/master/${trackerfile}
downloadfile=https://trackerslist.com/${trackerfile}

list=$(curl -fsSL ${downloadfile})
if ! grep -q "bt-tracker" "${CONF}" ; then
    echo -e "\033[34m==> 添加 bt-tracker 服务器信息......\033[0m"
    echo -e "\nbt-tracker=${list}" >> "${CONF}"
else
    echo -e "\033[34m==> 更新 bt-tracker 服务器信息.....\033[0m"
    sed -i '' "s@bt-tracker.*@bt-tracker=${list}@g" "${CONF}"
fi

## 重启 aria2 服务
echo -e "\033[34m==> 停止 aria2 服务......\033[0m"
launchctl stop aria2
echo -e "\033[34m==> 启动 aria2 服务......\033[0m"
launchctl start aria2

设置运行权限：

1
chmod +x ~/.aria2/trackers-list-aria2.sh

设置任务计划程序实现自动更新

编译当前用户任务计划：

1
crontab -e

可用 crontab -l 查看当前用户任务计划。文件内容如下：

1
2
MAILTO = ""
0 18 * * * ~/.aria2/trackers-list-aria2.sh

2022/05/27 更新：
添加 MAILTO = “” 配置避免终端出现 You have new mail 提示。
如果已经出现此类通知，输入 mail 即可查看并消除。

或者直接输入：

1
(crontab -l 2&> /dev/null; echo "0 18 * * * ~/.aria2/trackers-list-aria2.sh") | crontab

以上表示：
每天下午 6 点自动更新 BT tracker 并重启 aria2 服务。
取消计划任务：
1
crontab -e
然后手动删除内容，或者直接运行：
1
crontab -l 2&> /dev/null| sed "/trackers-list-aria2.sh/d" | crontab

添加下载通知

2024.08.19 更新：
如果使用后文提到的Aria2 Explorer插件，请忽略本小节内容。

最终效果：当下载完成会在屏幕右上角弹出一个提示框显示具体下载完成的文件名，同时语音播报：“有个文件下载完成，请查收！”

创建 download-complete-hook.sh 脚本

2024.08.19 更新：
如果使用后文提到的Aria2 Explorer插件，请忽略本小节内容。

1
2
touch ~/.aria2/download-complete-hook.sh
vim ~/.aria2/download-complete-hook.sh

脚本内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
#!/bin/sh
# 文件名 download-complete-hook.sh
# 给aria2 RPC添加一个下载完成通知 for macOS
# 变量 3 表示下载完成文件的路径
# 具体提示框设置可参考`https://code-maven.com/display-notification-from-the-mac-command-line`。
# 不支持设置自定义图标

fname=`basename $3`
osascript <<EOF
display notification "$fname 已经下载完成！" with title "【下载完成】"
say "有个文件下载完成，请查收！"
EOF

设置运行权限：

1
chmod +x ~/.aria2/download-complete-hook.sh

添加 Hook 设置

上面的 aria2.conf 配置文件已经包含了如下内容，使用上面文件的可以直接跳过此部分。
除此之外，如果使用后文提到的Aria2 Explorer插件，也可以删除配置文件中关于这部分的内容。

在 aria2 设置文件 aria2.conf 加入如下内容：

1
2
3
4
# BT下载完成(如有做种将包含做种，如需调用请务必确定设定完成做种条件)
on-bt-download-complete=${HOME}/.aria2/download-complete-hook.sh
# 下载完成
on-download-complete=${HOME}/.aria2/download-complete-hook.sh

Aria2 web UI

无需安装，直接使用浏览器打开： AriaNg版 UI 。

PRC 设置

根据 aria2.conf 配置文件中的 PRC 相关设置项进行设置。

安装浏览器下载插件

Aria2 Explorer

2024.08.19 更新：
首先感谢评论区老哥Chlorine的提醒，让我能够有机会继续完善本章节。

推荐配合Aria2 Explorer浏览器插件使用，Aria2-Explorer 能够自动拦截浏览器下载任务并通过JSON-RPC接口导出到Aria2进行高速下载并内置AriaNG作为管理前端。点击Chrome插件地址进行安装以及查看具体使用教程，其实主要是修改Server地址和RPC密钥。

除此之外，如果使用了这个插件，可以配合插件本身具备的通知功能，适当删减aria2.conf配置文件以及跳过添加下载通知等相关章节内容，所有关于通知功能的内容都可以直接删除和跳过，进一步缩减配置文件和过程的复杂性。

Aria2 for Chrome

2024.08.19 更新：
更加推荐前面提到的Aria2 Explorer插件。

Aria2 for Chrome插件

内置一个离线 AriaNg版 UI
整合右键下载菜单

内置的离线AriaNg版也需要 设置PRC ，否则无法成功连接。

仅供参考

网盘文件下载

网盘直链下载助手：需要通过安装拓展插件 Violentmonkey 或者 Tampermonkey 等脚本管理器来启用。

使用方法

配合Aria2 for Chrome插件使用。

选择要下载的文件，点击下载助手页面里的“Aria下载”或者“RPC下载”推送到Aria2 UI界面。
使用鼠标点击相应选项后，选择“发送链接”，然后确定下载。

感谢

GitHub作者沙漠之子

Hello，Aria2

前言#

Aria2是什么#

配置前的准备工作#

Docker安装方式（可选）#

安装并配置Aria2#

设置为开机自启动#

创建用户启动文件#

添加并启用自启动项#

添加自动更新 BT tracker 功能#

创建 trackers-list-aria2.sh 脚本#

设置任务计划程序 实现自动更新#

添加下载通知#

创建 download-complete-hook.sh 脚本#

添加 Hook 设置#

Aria2 web UI#

PRC 设置#

安装浏览器下载插件#

Aria2 Explorer#

Aria2 for Chrome#

仅供参考#

网盘文件下载#

使用方法#

感谢#

前言