FluxDown aria2 RPC 兼容层 — 现有 aria2 工具零改动对接

为什么做 aria2 兼容

aria2 是下载界的「标准协议」——大量现成工具（AriaNg、yaaw、Aria2-GUI、IDM 的 aria2 后端、各种网盘 aria2 离线脚本、甚至迅雷离线 aria2 输出）都用 aria2.addUri / aria2.addTorrent 这套 JSON-RPC 接口。如果 FluxDown 不兼容，这些工具链在 FluxDown 上都跑不通。

FluxDown 在 17800 端口的 /jsonrpc 路由上完整实现了 aria2 的 JSON-RPC 2.0 接口——所有现有 aria2 客户端零改动就能对接。

基本用法

aria2 RPC 的认证是 token 机制（不是 Bearer）：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "aria2.addUri",
  "params": ["token:<access_key>", ["https://example.com/file.zip"]]
}

对应 curl：

curl -X POST http://127.0.0.1:17800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "aria2.addUri",
    "params": ["token:'"$TOKEN"'", ["https://example.com/file.zip"]]
  }'

支持的 aria2 方法

FluxDown 覆盖了 aria2 客户端最常用的方法：

aria2 方法	对应 FluxDown 功能
`aria2.addUri`	加 HTTP/FTP/BT(磁力) 任务
`aria2.addTorrent`	加种子文件任务
`aria2.pause` / `aria2.resume`	暂停/恢复任务
`aria2.remove`	移除任务
`aria2.tellStatus`	查任务状态
`aria2.getGlobalStat`	查全局速度、活跃数
`aria2.purgeDownloadResult`	清理已完成/失败任务
`aria2.changeGlobalOption`	改全局设置
`aria2.getSessionInfo`	会话信息

和官方 REST API 的关系

维度	aria2 兼容层	官方 REST API
设计目的	兼容 aria2 生态	FluxDown 自身完整管理
覆盖范围	aria2 客户端常用方法	FluxDown 全部功能（队列/RSS/Webhook 等）
认证	`params[0] = "token:<key>"`	`Authorization: Bearer` header
新特性	不会覆盖 FluxDown 独有功能	有
迁移成本	零（现有 aria2 工具直接用）	需要改脚本

典型对接场景

AriaNg（Web UI）

打开 AriaNg 设置 → RPC。
JSON-RPC Path 填 /jsonrpc。
Secret 填 FluxDown 的 Access Key（不带 "token:" 前缀）。
地址 http://127.0.0.1:17800 → 连接。

网盘 aria2 离线下载脚本

很多网盘（阿里、夸克、115）的「离线下载」支持把任务投给 aria2 RPC——把 RPC 地址从默认的 127.0.0.1:6800 改成 FluxDown 的 127.0.0.1:17800 就行。

aria2c 命令行

aria2c 有一个 --enable-rpc 模式，但如果你已经在跑 FluxDown，直接让 aria2c 连接 FluxDown 的 RPC 端口：

aria2c --rpc-addr=127.0.0.1:17800 --rpc-secret=<token> --uri=https://...

注意：aria2c 自己的下载引擎不会启动——它只是作为一个 RPC 客户端把任务发给 FluxDown。

已知的不完全兼容

FluxDown 不会 100% 复现 aria2 的所有行为——比如 aria2 的 .aria2 控制文件、pieceSelect 参数、一些高级 BitTorrent 选项在 FluxDown 里有不同的实现或不支持。对于 95% 的 aria2 客户端来说这些差异不可见，但极个别做深度 BT 调优的脚本可能需要调整。