骏耀K歌（junyao-ktv）是一款专为家庭或小型聚会设计的局域网K歌系统，运行于飞牛fnOS或Docker环境，支持x86_64与aarch64架构。核心体验为手机扫码点歌、电视/投影仪全屏播放，MV曲库与应用数据统一存储于共享目录。系统基于HLS多音轨实现原唱/伴唱实时切换，无需中断播放或重置进度；转码优先调用VAAPI/NVENC硬件加速，失败时自动回退libx264软编。当前版本1.1.1支持渐进式扫描与边转边播，HLS缓存每日自动清理以控制磁盘占用，曲库管理后台需密码保护。
核心功能与技术实现细节
该系统围绕“低延迟、高兼容、易维护”设计，关键技术点如下：
- 双音轨无缝切换：利用HLS多音轨特性，原唱/伴唱切换不中断播放流，进度条可任意拖拽寻址，避免传统方案重新加载导致的卡顿
- 硬件转码自适应：默认尝试VAAPI（Intel/AMD核显）或NVENC（NVIDIA独显），设备不可用时静默降级至libx264软编，保障基础可用性
- 渐进式处理：曲库扫描与视频转码均采用增量模式，新增歌曲无需全量重建索引；点歌时若缓存未就绪，边转码边推送已生成片段，首帧响应快
- 缓存生命周期管理：HLS转码缓存保留天数由
HLS_CACHE_MAX_AGE_DAYS控制（默认3天），超期且未被访问的缓存自动删除，源MV文件始终保留 - 格式广泛兼容：支持.mp4/.mkv/.avi/.flv/.mov/.webm/.mpg等主流封装，降低曲库准备门槛
- 安全隔离：曲库增删改操作需密码验证，防止误操作或未经授权的修改
部署配置与硬件加速启用指南
系统提供两种部署路径，硬件加速需满足前置条件：
飞牛fnOS原生安装
使用官方fnpack工具打包生成.fpk文件，通过应用中心“手动安装”或CLI命令appcenter-cli install-fpk junyao-ktv.fpk部署。注意fnpack工具需单独从飞牛开发者文档获取，不包含在项目仓库中。
Docker容器部署
根据宿主机GPU类型选择对应compose配置：
| 硬件类型 | 关键配置项 | 注意事项 |
|---|---|---|
| Intel/AMD核显 | devices: /dev/dri:/dev/dri + VAAPI_DEVICE=/dev/dri/renderD128 | 驱动已装且设备节点存在，否则自动软编 |
| NVIDIA独显 | runtime: nvidia + NVIDIA_VISIBLE_DEVICES=all + NVIDIA_DRIVER_CAPABILITIES=compute,video,utility | 宿主机需预装驱动+nvidia-container-toolkit |
| 无GPU/不确定 | 注释devices/runtime相关行 | 纯软编可用，CPU占用较高 |
通用环境变量说明：
PORT: 服务端口（容器内固定8080，映射端口在ports段调整）DATA_DIR/MV_DIR: 数据与曲库持久化路径，docker compose会自动创建HLS_CACHE_MAX_AGE_DAYS: 缓存保留天数，设0禁用自动清理（不推荐）
重要提醒：NVIDIA配置未经实测，仅按官方文档编写；若遇转码失败，检查nvidia-smi输出及容器日志中的编码器初始化错误。
使用边界与维护建议
尽管设计简洁，仍需注意以下实操限制：
- 网络依赖：手机点歌与电视播放必须在同一局域网，跨网段或公网访问需额外配置反向代理与认证
- 双音轨优先级：推荐使用原生双音轨MV文件以获得最佳切换体验；单音轨双声道文件虽兼容，但切换时可能有轻微音量跳变
- 歌手头像匹配：
/singer目录下图片文件名需与歌曲元数据中的歌手名精确匹配（大小写敏感），否则不显示头像 - 缓存清理时机：自动清理在每日固定时间触发，非实时；若磁盘紧张，可临时调低
HLS_CACHE_MAX_AGE_DAYS或手动删除/data/hls_cache子目录 - 密码重置：首次设置密码后无找回机制，遗忘需删除
/data/config.db重启重新设置（会丢失曲库编辑记录） - 性能瓶颈：软编模式下4K@60fps转码可能卡顿，建议此类素材预处理为1080p或启用硬件加速
对于家庭用户，该系统提供了接近商用KTV的点歌体验且零订阅成本；对NAS玩家而言，其Docker友好性与缓存自管理机制适合长期托管。但需注意：它不是流媒体平台，不提供在线曲库，所有内容依赖本地准备。首次部署建议先用少量测试视频验证转码链路，再批量导入曲库，避免大规模转码阻塞初始体验。
