飞牛OS系统架构重构与影视模块升级 产品需求文档（PRD）
文档信息
| 项目 |
内容 |
| 文档名称 |
飞牛OS系统架构重构与影视模块升级PRD |
| 版本 |
V1.0 |
| 日期 |
2026年6月27日 |
| 状态 |
初稿 |
| 涉及模块 |
存储模块、下载中心、通知中心、调度任务中心、刮削模块、影视模块 |
一、背景与目标
1.1 背景
飞牛OS（fnOS）作为基于Linux内核深度定制的国产NAS操作系统，采用分层架构设计——底层驱动层兼容x86_64及ARM架构，中间服务层集成ZFS/Btrfs等文件系统，应用层提供可视化Web管理界面。当前系统在存储管理、下载能力、影视刮削等方面已具备基础能力，但随着用户需求的多样化和复杂化，现有架构在以下方面存在提升空间：
- 存储管理对网盘的支持不够体系化，缺乏统一的网盘存储抽象层
- 下载工具分散管理，缺少统一的下载调度与协议路由能力
- 通知机制依赖各应用独立实现，缺乏集中化的通知中心
- 任务调度能力分散，缺少统一的调度框架
- 刮削逻辑单一，无法满足用户对多数据源、自定义属性的需求
- 影视搜索能力薄弱，缺乏插件化扩展能力
1.2 目标
本需求旨在重新定义飞牛OS的系统架构模块，构建一套高内聚、低耦合、可扩展的系统能力底座，同时升级影视模块的搜索与刮削体验，为用户提供更智能、更高效的私有云媒体管理体验。
二、系统架构模块重构
2.1 存储模块（Storage Module）
2.1.1 模块概述
存储模块是飞牛OS的数据持久化底座，需统一管理本地存储与网盘存储两种存储类型，提供统一的存储抽象层与访问接口。
2.1.2 本地存储
保持现有能力，支持：
- 本地硬盘的挂载与管理（支持NTFS/exFAT/FAT32等非Linux原生文件系统）
- 存储池管理（ZFS/Btrfs等）
- 文件共享协议（SMB/WebDAV/NFS）
2.1.3 网盘存储
功能需求：
| 需求编号 |
需求描述 |
优先级 |
| S-01 |
支持主流网盘的远程挂载（阿里云盘、百度网盘、115网盘、夸克网盘、天翼云盘等），挂载后可像本地目录一样访问 |
P0 |
| S-02 |
网盘存储内置WebDAV服务能力，为.strm文件（流式媒体引用文件）的长期存储与访问提供协议支持 |
P0 |
| S-03 |
部分网盘（如115网盘）需支持离线下载功能，用户可将下载链接提交至网盘离线下载，下载完成后自动同步至挂载目录 |
P1 |
| S-04 |
保存至网盘的链接提供**“无效预览直接保存”**选项——即用户可跳过文件内容预览，直接将链接指向的文件保存至指定目录 |
P2 |
技术要点：
- 每个网盘挂载点分配唯一的存储模块ID（如挂载的第一块115网盘id为6）
- 存储地址格式：
{存储模块ID}+{路径}，如 6:/movie/crisis.mp4
2.2 下载中心（Download Center）
2.2.1 模块概述
下载中心作为所有下载任务的统一入口与管理中枢，整合系统内所有下载工具，提供统一的下载任务管理界面与协议路由能力。
2.2.2 功能需求
| 需求编号 |
需求描述 |
优先级 |
| D-01 |
整合系统内所有下载软件（Aria2、qBittorrent、115网盘离线下载等），提供统一的任务列表与管理界面 |
P0 |
| D-02 |
支持默认下载器设置，用户可设定全局默认下载工具 |
P0 |
| D-03 |
支持按协议配置下载器：HTTP/HTTPS/FTP链接自动路由至Aria2，磁力链接/BT种子自动路由至115网盘离线下载或qBittorrent |
P0 |
| D-04 |
下载任务的状态、进度、速度、剩余时间等信息由下载中心统一汇总展示 |
P0 |
| D-05 |
下载完成后支持自动转移至指定目录 |
P1 |
2.2.3 协议-下载器路由规则示例
| 协议类型 |
默认下载器 |
可切换选项 |
| HTTP/HTTPS/FTP |
Aria2 |
qBittorrent |
| 磁力链接（Magnet） |
115网盘离线下载 |
qBittorrent, Aria2 |
| BT种子（.torrent） |
qBittorrent |
115网盘离线下载 |
| FTP/SFTP |
Aria2 |
- |
2.3 通知中心（Notification Center）
2.3.1 模块概述
通知中心作为系统级消息总线，统一接收来自各模块的事件通知，并通过多种渠道推送给用户。
2.3.2 功能需求
| 需求编号 |
需求描述 |
优先级 |
| N-01 |
支持多种通知渠道：App推送、邮件（SMTP）、Webhook、Gotify、Server酱、钉钉、微信等 |
P1 |
| N-02 |
下载完成通知：Aria2等支持Webhook的下载器，下载完成后直接通过Webhook告知通知中心 |
P0 |
| N-03 |
对于不支持Webhook的下载器（如部分网盘离线下载），系统需根据文件大小与当前下载速度自动计算预估完成时间，生成轮询调度任务，周期性查询下载状态，完成后触发通知 |
P0 |
| N-04 |
通知中心统一管理所有系统事件通知（下载完成、刮削完成、系统告警等） |
P0 |
2.3.3 轮询调度逻辑
text
输入：下载任务ID、文件总大小、当前下载速度
处理：
1. 计算预估剩余时间 = (文件总大小 - 已下载大小) / 当前下载速度
2. 根据预估时间动态调整轮询间隔（预估时间长则轮询间隔大，反之则小）
3. 每次轮询获取最新下载状态
4. 若下载完成 → 触发通知 → 销毁轮询任务
5. 若下载失败 → 触发告警通知 → 销毁轮询任务或重试
输出：轮询调度任务（注册至调度任务中心）
2.4 调度任务中心（Scheduler Center）
2.4.1 模块概述
调度任务中心是系统所有后台任务的统一调度与管理平台，提供任务注册、执行、监控与生命周期管理能力。
2.4.2 任务分类
| 任务类型 |
定义 |
示例 |
| 即时任务 |
用户触发后立即执行的一次性任务 |
用户点击“立即刮削”、手动下载 |
| 定时任务 |
按预设时间规则周期性执行的任务 |
每日凌晨3点增量备份、定时限速 |
| 轮询任务 |
按固定或动态间隔周期性检查状态的任务 |
下载进度轮询、网盘文件同步状态检查 |
2.4.3 功能需求
| 需求编号 |
需求描述 |
优先级 |
| T-01 |
提供统一的任务注册接口，各模块可向调度中心注册任务 |
P0 |
| T-02 |
支持任务的暂停、恢复、取消、重试 |
P0 |
| T-03 |
支持任务优先级设置与队列管理，可设置最大并发任务数N，超出任务进入等待队列 |
P1 |
| T-04 |
提供任务执行日志与状态追踪 |
P1 |
| T-05 |
定时任务支持Cron表达式配置 |
P1 |
2.5 刮削模块（Scraper Module）
2.5.1 模块概述
刮削模块负责自动为影视文件获取元数据（海报、简介、演员、评分等），构建媒体库海报墙。本需求旨在改变当前单一刮削源的现状，实现多源、可配置、智能化的刮削能力。
2.5.2 触发机制
刮削任务由通知中心的事件驱动触发：
- 下载完成 → 通知中心发送“下载完成”事件
- 刮削模块监听该事件 → 判断文件是否位于需要刮削的媒体目录
- 若在刮削目录内 → 自动提交刮削任务至调度任务中心
2.5.3 刮削数据源配置
| 路径特征 |
刮削数据源 |
说明 |
路径包含 movie |
TMDB + 豆瓣 |
电影类目，双源互补 |
路径包含 animation |
Bangumi + 豆瓣 |
动漫类目，Bangumi为动漫专业数据库 |
路径包含 tv 或 series |
TMDB + 豆瓣 |
剧集类目 |
| 其他 |
TMDB（默认） |
兜底方案 |
说明：刮削源应支持用户自定义优先级和启用/禁用。
2.5.4 刮削信息存储结构
每条刮削记录需存储以下信息：
| 字段 |
类型 |
说明 |
示例 |
media_id |
string |
媒体唯一标识 |
UUID |
title |
string |
媒体标题 |
生化危机7 |
original_title |
string |
原始标题 |
Resident Evil 7 |
year |
int |
发行年份 |
2017 |
genre |
string[] |
类型 |
[动作, 科幻, 恐怖] |
plot |
string |
剧情简介 |
- |
poster_url |
string |
海报URL |
- |
rating |
float |
评分 |
8.2 |
actors |
string[] |
演员列表 |
- |
director |
string |
导演 |
- |
season_info |
string |
剧集归属信息 |
生化危机系列 |
storage_id |
string |
存储模块ID |
6 |
storage_path |
string |
存储路径 |
/movie/crisis.mp4 |
is_private |
boolean |
是否私有 |
false |
owner |
string |
归属人 |
user_123 |
scrape_source |
string |
刮削数据源 |
TMDB+豆瓣 |
custom_attributes |
map |
自定义属性（扩展） |
{"series": "生化危机系列"} |
2.5.5 功能需求
| 需求编号 |
需求描述 |
优先级 |
| SC-01 |
监听通知中心的“下载完成”事件，自动判断文件是否位于刮削目录 |
P0 |
| SC-02 |
根据文件路径自动选择刮削数据源组合 |
P0 |
| SC-03 |
支持用户自定义刮削源优先级（本地NFO > TMDB > 豆瓣） |
P1 |
| SC-04 |
刮削信息支持自定义属性扩展（如剧集归属、系列标记等） |
P1 |
| SC-05 |
记录存储模块ID与完整路径，支持多存储位置的媒体溯源 |
P0 |
| SC-06 |
支持影视私有标记与归属人记录，为后续权限控制奠基 |
P1 |
| SC-07 |
支持刮削失败后的自动重试（由调度任务中心管理） |
P2 |
三、影视模块调整
3.1 搜索功能升级
3.1.1 当前问题
- TV端输入汉字不便，首字母搜索支持不完善
- 模糊搜索能力弱，如搜索“JS”无法匹配“芝加哥警署”
- 搜索结果仅限本地媒体库，无法扩展至外部资源
3.1.2 功能需求
| 需求编号 |
需求描述 |
优先级 |
| M-01 |
搜索范围覆盖全部非私密影视信息（is_private=false的媒体记录） |
P0 |
| M-02 |
支持中文首字母搜索（如输入“ZJG”可匹配“芝加哥警署”） |
P0 |
| M-03 |
支持字母全拼匹配（如输入“zhijiage”可匹配“芝加哥警署”） |
P0 |
| M-04 |
支持模糊搜索（部分匹配、拼音模糊匹配） |
P1 |
| M-05 |
TV端首字母搜索优化：支持1-2个字母的搜索，不限制最低输入长度 |
P0 |
3.2 搜索插件系统
3.2.1 模块概述
为满足用户对第三方影视资源网站（如4K影视站、资源聚合站）的搜索需求，引入搜索插件系统，允许用户安装、配置第三方搜索插件，扩展影视资源获取渠道。
3.2.2 搜索流程
text
用户输入关键词（如“凡人修仙传”）
↓
搜索插件并发执行（用户可启用/禁用单个插件）
↓
插件1: https://seedxxxxxx/s/凡人修仙传/ → 解析HTML → 返回结果列表
插件2: https://othersite.com/search?q=凡人修仙传 → 解析HTML → 返回结果列表
↓
各插件结果按统一格式聚合展示
↓
用户选择具体资源条目（如“凡人修仙传动漫版”）
↓
插件进入详情页解析 → 提取磁力链接、夸克网盘链接、123网盘链接等
↓
用户点击“获取详情” → 资源链接保存至网盘常用路径
↓
通知中心发送“下载任务已提交”通知
3.2.3 插件规范
插件元数据：
json
{
"id": "plugin_xxx",
"name": "4K影视搜索",
"version": "1.0.0",
"author": "xxx",
"description": "搜索4K影视资源",
"search_url": "https://seedxxxxxx/s/{keyword}/",
"icon": "https://xxx/icon.png"
}
搜索结果返回格式（统一规范）：
json
{
"items": [
{
"title": "凡人修仙传动漫版",
"year": "2024",
"cover": "https://xxx/cover.jpg",
"source": "plugin_xxx",
"detail_url": "https://seedxxxxxx/detail/123"
}
]
}
详情页解析结果格式：
json
{
"title": "凡人修仙传动漫版",
"year": "2024",
"cover": "https://xxx/cover.jpg",
"description": "剧情简介...",
"download_links": [
{
"type": "magnet",
"url": "magnet:?xt=urn:btih:xxx",
"source": "磁力链接"
},
{
"type": "quark",
"url": "https://pan.quark.cn/s/xxx",
"source": "夸克网盘"
},
{
"type": "123pan",
"url": "https://www.123pan.com/s/xxx",
"source": "123网盘"
}
]
}
3.2.4 功能需求
| 需求编号 |
需求描述 |
优先级 |
| P-01 |
提供搜索插件管理界面：安装、启用/禁用、卸载插件 |
P0 |
| P-02 |
定义并开放标准化的插件搜索规范（输入输出格式） |
P0 |
| P-03 |
支持插件并发搜索，结果聚合展示 |
P0 |
| P-04 |
用户点击资源详情后，解析提取多种下载链接（磁力、夸克、123等） |
P0 |
| P-05 |
点击“获取详情”后，资源自动保存至用户预设的网盘常用路径 |
P0 |
| P-06 |
保存操作等同于“下载”行为，需触发通知中心发送通知 |
P0 |
| P-07 |
支持社区插件源，用户可添加第三方插件仓库 |
P1 |
四、模块关系图
text
**─────────────────────────────────────────────────────────────────────**
** 用户交互层 **
** **──────────** **──────────** **──────────** **──────────────** **
** ** 影视模块 ** ** 下载中心 ** ** 文件管理 ** ** 搜索插件管理 ** **
** **────**─────** **────**─────** **────**─────** **──────**───────** **
**───────**─────────────**─────────────**───────────────**──────────────**
** ** ** **
▼ ▼ ▼ ▼
**─────────────────────────────────────────────────────────────────────**
** 服务层 **
** **──────────────────────────────────────────────────────────────** **
** ** 调度任务中心 ** **
** ** **──────────** **──────────** **──────────** ** **
** ** ** 即时任务 ** ** 定时任务 ** ** 轮询任务 ** ** **
** ** **──────────** **──────────** **──────────** ** **
** **──────────────────────────**───────────────────────────────────** **
** ** **
** **──────────────────────────**───────────────────────────────────** **
** ** ▼ ** **
** ** 通知中心（事件总线） ** **
** ** 下载完成事件 刮削完成事件 系统告警事件 任务状态事件 ** **
** **──────────────────────────**───────────────────────────────────** **
** ** **
** **──────────** **──────────** **──────────** **──────────────** **
** ** 刮削模块 ** ** 存储模块 ** ** 下载中心 ** ** 搜索插件系统 ** **
** ** ** ** **──────** ** ** **──────** ** ** ** **
** ** TMDB ** ** **本地 ** ** ** **Aria2 ** ** ** 插件1 插件2 ** **
** ** 豆瓣 ** ** **存储 ** ** ** **──────** ** ** ** **
** ** Bangumi ** ** **──────** ** ** **115离 ** ** ** ** **
** ** ** ** **──────** ** ** **线下载** ** ** ** **
** ** ** ** **网盘 ** ** ** **──────** ** ** ** **
** ** ** ** **存储 ** ** ** **qBitt ** ** ** ** **
** ** ** ** **──────** ** ** **──────** ** ** ** **
** **──────────** **──────────** **──────────** **──────────────** **
**─────────────────────────────────────────────────────────────────────**
**
▼
**─────────────────────────────────────────────────────────────────────**
** 基础设施层 **
** **──────────────────────────────────────────────────────────────** **
** ** Linux内核（Debian深度定制） + 硬件抽象层 ** **
** ** x86_64 / ARM 双平台支持 ** **
** **──────────────────────────────────────────────────────────────** **
**─────────────────────────────────────────────────────────────────────**
五、非功能性需求
| 类别 |
需求描述 |
| 性能 |
刮削任务并发数不低于5个；搜索插件响应时间不超过3秒 |
| 扩展性 |
存储模块支持新增网盘类型；搜索插件支持热加载 |
| 可靠性 |
任务调度支持失败重试（最多3次）；通知发送失败有降级方案 |
| 安全性 |
私有影视仅归属人及授权用户可见；网盘凭证加密存储 |
| 兼容性 |
保持对现有飞牛OS版本的向下兼容，支持x86_64及ARM架构 |
六、优先级总结
| 优先级 |
功能模块 |
核心需求 |
| P0（必须） |
存储模块 |
网盘挂载、WebDAV支持、存储ID体系 |
| P0（必须） |
下载中心 |
统一管理、协议路由、115离线下载 |
| P0（必须） |
通知中心 |
Webhook通知、轮询调度 |
| P0（必须） |
调度任务中心 |
三类任务统一调度 |
| P0（必须） |
刮削模块 |
事件驱动、多源刮削、完整存储结构 |
| P0（必须） |
影视模块 |
首字母/全拼搜索、搜索插件系统 |
| P1（重要） |
存储模块 |
无效预览直接保存 |
| P1（重要） |
通知中心 |
多渠道通知（邮件、钉钉、微信等） |
| P1（重要） |
刮削模块 |
自定义刮削源优先级、私有/归属人 |
| P1（重要） |
影视模块 |
模糊搜索、社区插件源 |
| P2（增强） |
刮削模块 |
刮削失败自动重试 |
2026-6-27 00:26:14
