我给飞牛 fnOS 写了个「Aria2 桥接」：任何支持 Aria2 的软件，都能把任务推进「下载中心」

我给飞牛 fnOS 写了个「Aria2 桥接」：任何支持 Aria2 的软件，都能把任务推进「下载中心」

飞牛「下载中心」是我在 NAS 上最常用的功能之一：磁力、BT、HTTP 直链都收，任务统一在系统里管，文件直接落进存储池。但它有个说不上是缺点的限制——它只服务飞牛自己。外面那些只认「标准下载器协议」的软件（DBO、Motrix、AriaNg，以及一堆只让你填 host / port / secret 的下载工具）没法把任务交给它。

这篇介绍我为解决这件事写的原生 fpk：下载中心接入Aria2（包名 aria2bridge）。它在 NAS 本机起一个标准 Aria2 JSON-RPC 服务，把请求翻译成飞牛下载中心的接口调用；查询任务时再反着翻译回来，所以进度、速度、暂停 / 继续 / 删除都是双向同步的。纯 Python 标准库实现，不需要装任何 pip 依赖。

一、问题出在哪：接口是「私有」的

飞牛下载中心背后跑的其实是 qBittorrent 引擎（系统接口 stat.qbittorrent 会返回 connected 与 DHT 节点数）。但它的 WebUI / RPC 端口并不对局域网开放——在这台机器上扫了一遍常用端口，NAS 只对外开了 80 / 443 / 5666 / 5667 / 9208，qBittorrent 与 aria2 的 RPC 口都在里面，从别的设备连不上。

飞牛自己的网页端能操作下载中心，靠的是 5666 上一套带登录态的 WebSocket 接口，方法名长这样：

• appcgi.downloadcenter.task.query —— 查任务

• appcgi.downloadcenter.task.addUris —— 添加下载链接

• appcgi.downloadcenter.pause / resume / rm —— 暂停 / 继续 / 删除

• appcgi.downloadcenter.config.getDefaultSaveDir —— 读默认保存目录

这套接口要登录态，也不是给第三方软件准备的。于是局面很清楚：一边是软件只会说 Aria2 / qBittorrent 两种协议，一边是下载中心只认自己的那套。中间缺一个翻译层——这就是这个 fpk 要做的事。

二、做法：在本机开一个「假」Aria2

下载软件（DBO / Motrix / AriaNg …）
        │  Aria2 JSON-RPC：http://<NAS-IP>:6800/jsonrpc
        ▼
aria2bridge（本机监听 0.0.0.0:6800）
        │  appcgi.downloadcenter.*（复用飞牛账号登录态）
        ▼
   trim-cli ── WebSocket ──▶ fnOS 接口 :5666
        ▼
飞牛「下载中心」→ 引擎下载 → 进度回读

几个实现上的关键点：

• 伪装协议：监听 6800（与 Aria2 官方默认端口一致），完整实现 Aria2 的 JSON-RPC。客户端以为对面是 aria2，其实后面站着飞牛下载中心。

• 复用官方通道：包里内置了一个 8 MB 左右的 trim-cli 二进制，通过 ws://127.0.0.1:5666 调用飞牛自己的接口，不逆向、不碰引擎端口。

• 登录态自愈：会话文件落在应用自己的数据目录，一旦检测到失效会自动用配置里的账号重新登录——不用你去应用中心点重启。

• gid 转换：飞牛的任务 id 是数字，桥接把它转成 16 位十六进制，客户端拿到的是标准 aria2 gid。

• 零依赖：http.server + subprocess，没有第三方包，不需要 pip。

三、安装：三步

第 1 步：导入 fpk

应用中心 → 手动安装 → 从电脑上传 aria2bridge.fpk，走一遍「未经验证应用」确认即可。fpk 里声明了依赖 python312，没装过 Python 3.12 运行环境的机器，飞牛会连带装上。

手动安装 fpk 的完整流程（包结构、安装钩子、升级卸载时的数据保留逻辑）之前单独写过一篇：飞牛OS 手动安装 fpk 教程。

第 2 步：填安装向导

有一点必须提前说：接入用的账号不能开启两步验证，否则登录会失败。账号密码只保存在 NAS 本机（应用配置目录 etc/config.json），除了本机调用飞牛的登录接口，不参与任何其他网络请求。

第 3 步：打开状态页自检

装完桌面会多一个图标，点开就是应用的状态页：

点一下「自检」，会给出三行结果：

• login：飞牛账号登录态

• task_query：下载中心任务接口（正常会返回当前任务数）

• default_save_dir：读到的默认保存目录

三行都正常，说明桥接已经通了，可以去配置下载软件了。

四、接入：把四个参数填进你的下载软件

状态页第一张卡片就是通用接入参数，每行都带「复制」按钮：

• 主机 Host：NAS 的局域网 IP

• 端口 Port：6800

• 密钥 Secret：向导里设置的那个

• RPC 地址：http://<NAS-IP>:6800/jsonrpc

以我这次的目标软件 DBO（DB_Online） 为例，它的 Aria2 下载器配置项与桥接参数一一对应：

其他软件同理：只要它能填「Aria2 RPC 地址 + 密钥」就能接上（Motrix、AriaNg，以及各种内置 Aria2 客户端的下载工具）。接好之后，软件里添加的 http / https / ftp / 磁力任务会直接出现在飞牛「下载中心」的任务列表里；反过来在下载中心暂停、继续、删除，软件里看到的任务状态也跟着变。

五、支持哪些 Aria2 方法

协议层实现得比较完整，常用方法都在：

getVersion 会返回 1.37.0（Aria2 兼容版本号），enabledFeatures 里带一个 bridged-to-fnos-downloadcenter 作为标记。

任务状态映射：

六、保存目录是怎么定的

客户端推任务时带的保存目录（Aria2 里的 dir 参数）按三种情况处理：

1. 以 /vol?/ 开头的真实路径 → 原样交给下载中心；

2. 命中配置里的 dir_map 映射规则 → 按规则替换（把客户端那边的路径折成存储池路径）；

3. 其他情况或留空 → 用下载中心自己的「默认保存目录」（首次自动读取，缓存 10 分钟）。

所以最简单的用法就是：软件里保存路径留空，任务会全部按下载中心默认目录落盘。

七、排错清单

八、已知限制

• 不支持 ed2k：飞牛 task.addUris 只接受 http / https / ftp / sftp / magnet，ed2k 链接会被上游拒绝，桥接不背这个锅；

• 只做协议翻译，不改下载策略：做种比例、限速、连接数这些仍由飞牛下载中心自己管；

• 目前只有 x86 包：Intel / AMD 机型可用，ARM 机型（瑞芯微等）需要另行编译；

• 状态页本身不带鉴权：局域网内能打开 6800 的人就能看到密钥，所以别把 6800 直接映射到公网，密钥也建议改掉默认值。

九、下载

GitHub Releases：https://github.com/jjsxjxj/fnos-aria2-bridge/releases/latest （页面里的 aria2bridge.fpk 可直接下载；完整源码与文档也在这个仓库，欢迎 star）

夸克网盘：https://pan.quark.cn/s/9ac24706ef83

手机端也可以直接复制口令 /~712d3bFEcC~:/，打开夸克 App 会自动跳转到分享页。

包内是明文 Python：应用本体 app/bridge.py 没有混淆，把 fpk 当 tar.gz 解开就能读，不放心可以先看代码再装——源码也已经在 GitHub 仓库开源，修了什么、每次改动的说明都在 README 的版本历史里。

既然是给自己写的工具，就没打算把它做成通用下载器——它只干一件事：让「下载中心」被外面那些软件用起来。装完在 DBO 里点一下下载、切到飞牛网页看任务在跑，这件事就算成了。