javycoder / fnos_music_ext

# fnmusic-ext · 飞牛音乐扩展
**保留飞牛音乐原生体验，为本地曲库补上在线搜索、播放、推荐与收藏能力。**
GitHub · Gitee 镜像 · 下载安装包 · 更新日志 · 详细安装指南
`fnmusic-ext` 是面向 fnOS（飞牛私有云）官方音乐应用 `trim.music` 的无侵入增强扩展。安装后，仍在熟悉的飞牛音乐 Web 端或 App 中搜索、听歌、收藏和管理歌单；音源与扩展设置则通过「fnMusic 扩展管理」完成。
扩展通过可逆接管官方后端 Unix Socket 实现协议中继与数据适配，**不修改官方程序、二进制或 nginx 配置，不直接写入官方数据库**。曲库数据库仅只读访问，收藏、歌单等业务写入通过官方接口完成；停止扩展即可恢复官方直连。
## 能做什么
### 在原生音乐里搜索与播放
- **本地优先的在线搜索**：本地曲库结果排在前面，当前所选音源的在线结果随后展示，并标注来源。网易与洛雪支持按需深分页，musicdl 仅参与首屏，详见搜索分页说明。
- **播放、歌词与封面适配**：在线歌曲可直接点播，优先复用曲库中已核对的本地文件；支持歌词与封面补全，在线封面默认通过同源代理返回，兼顾官方手机 App。
- **在线播放与下载分别选音质**：播放提供「高音质 / 平衡 / 流畅」偏好；App 下载提供「跟随 App / 无损原文件 / MP3 320k」。原文件交付不代表音源一定提供无损，实际品质受源站、账号权益与歌曲资源限制。
- **标准档转码**：为 App 的在线歌曲播放提供 AAC/HLS 分片，为标准档下载提供 MP3 320k，相关能力依赖 ffmpeg。网易无 VIP 权益时，部分歌曲会标记 `[VIP]`，可能仅能试听，扩展不会绕过账号权限。
### 推荐与歌单
- **每日推荐与热门推荐**：两个独立总开关；每日推荐按账户隔离，依次使用可用的音源原生推荐、明确启用的大模型推荐、本地曲库兜底。配置接口不会自动启用大模型；关闭大模型用途不关闭每日推荐歌单。
- **猜你喜欢**：默认使用纯本地计算：当前用户排除本地收藏后至少有 20 首有效本地歌曲时，显示在每日推荐下方，每次最多 20 首；首次读取生成，缓存 30 分钟，到期后下次读取更新，新增收藏或删除曲目后下次读取及时剔除。可在「高级 · 大模型」明确勾选大模型猜你喜欢，按个人口味、本地探索与新歌联动生成；歌曲数量可设为 0–100 的整数（默认 20，0 停止生成和展示），本地候选至少 20 首的门槛不变。启用保存后后台预生成首批；每批首次被客户端获取后开始计时，达到生成间隔后后台预生成下一批，未获取的批次不按时间过期或轮换。取消勾选恢复旧的纯本地行为，隐藏参数但保留已保存值。
- **公共推荐歌单**：在管理页浏览并勾选网易推荐、分类、精品、榜单歌单，以及洛雪歌单广场与榜单；支持关键词搜索网易/洛雪公共歌单，分类与搜索结果可连续加载到上游实际可返回的尽头，作为只读歌单显示在音乐页。默认关闭；musicdl 暂不接入此功能。
- **网易账号歌单**：扫码登录后，可将账号自建歌单以只读方式展示在飞牛音乐中。
- **网易云歌单常驻**：开启后，切到 musicdl 或洛雪仍可显示、播放网易歌单。账号歌单需要登录，网易公共歌单可匿名使用；此时网易服务会额外常驻，**不代表搜索变为多音源聚合**。
- **多用户收藏隔离**：家庭成员的在线红心收藏彼此独立；可选将在线收藏下载落库，再通过官方接口绑定本地歌曲。
### 从在线试听到本地曲库
- **边听边存**：在线听歌时后台缓存，可将完整下载的歌曲保存进官方曲库，后续优先复用本地文件。
- **缓存与下载目录分开设置**：支持飞牛文件选择器或手动路径；保存前校验可写性，两类目录不能相同或互为父子。更换缓存目录会迁移去重标记，不迁移旧音频缓存。
- **封面与歌词落盘**：落库歌曲可自动内嵌封面；可选下载同名 `.lrc` 歌词（默认关闭）。
- **自定义文件名**：支持 `{artist}`、`{title}`、`{source}`，默认 `{artist} - {title}`；规则对新落盘歌曲生效。
### 一个管理入口
「fnMusic 扩展管理」集中提供音源切换、网易扫码、musicdl 平台选择、洛雪脚本管理、音质与储存设置、推荐与大模型配置。
- 常用配置支持热生效，无需反复重装；不在热重载白名单内的配置仍需重启服务。
- 「设置」页提供外观主题：跟随系统（默认）、浅色或深色，切换后界面立即生效。
- 「边听边存」页提供「清理垃圾文件（Beta）」：清理遗留的临时文件与过期日志并显示回收空间；执行前有风险提示，请谨慎操作。
- 「关于」页支持检查正式版更新：优先 GitHub，失败回退 Gitee；发现新版后展示说明并跳转下载页，**不会自动安装，也不会推送预发布更新**。
- 运行日志按天滚动保留 3 天，可在「关于 → 导出日志」下载 `.logzip`，便于反馈问题；导出带脱敏处理，分享前仍请检查内容。
## 音源怎么选
**主音源三选一，可随时在管理页切换。** 洛雪的「多个脚本同时激活」与网易的「歌单常驻」是附加能力，不改变主音源单选规则。
| 主音源 | 适合的使用方式 | 使用前须知 |
| :--- | :--- | :--- |
| **网易云 musicbox** | 网易搜索、账号歌单与每日推荐 | 支持扫码登录；会员、付费与试听限制取决于账号权益 |
| **musicdl** | 按平台选择在线搜索来源 | 当前集成 57 个平台；可用性随上游变化，建议只启用自己验证可靠的平台 |
| **洛雪 lxmusic** | 使用自己信任的洛雪自定义源脚本 | 搜索、歌词与榜单由内置平台接口提供，播放解析交给用户脚本；不附送可用源 |
洛雪脚本可通过 **URL、电脑上传 `.js`、NAS 文件选择**三种方式导入，支持备注、测试、多个脚本同时激活与解析失败接力。**导入前请自行审查来源安全，不要使用来历不明的脚本。** 脚本在音源服务的 Node.js 运行时中执行：Docker 部署在容器内，原生部署在宿主机上，不能将其视为安全沙箱。
musicdl 平台编号与短名见 平台清单。洛雪解析实现基于 XCQ0607/lxserver，项目使用 pdone/lx-music-source 中的源进行验证，不保证所有第三方脚本兼容或长期可用。
## 安装与开始使用
### 前置条件
1. fnOS 已安装并启动官方 **飞牛音乐**应用。
2. 选择一种音源部署方式：**Docker（默认）**，或无需 Docker 的 **native 原生部署**。代理始终在宿主机运行，两种音源形态不能同时部署。
3. 确保 NAS 能访问所选音源；账号权限、网络条件与源站可用性会直接影响结果。
4. CPU 架构需为 `x86_64` 或 `aarch64/ARM64`；ARM32 暂不支持。
### 推荐：应用中心安装 FPK
1. 从 GitHub Releases 下载最新正式版 `f