4.5 KiB
影音模块架构
影音覆盖电影、剧集、音乐和有声书，在统一应用外壳（首页、书架、影音、我的）中使用 #/media/... 路由，与阅读共用 V3 主题（shared/theme）；服务端在独立 Worker 线程中运行。首页（#/）汇总继续阅读与继续观看/收听，阅读正文引擎由 React 页面托管生命周期。
数据与服务边界
全站 business_settings.modules.mediaEnabled 和个人 users.media_enabled 保存在核心数据库，不依赖影音 worker。升级保留已有用户影音权限；新用户遵循 newUserMediaEnabled。总开关关闭时启动不会打开 media.db 或启动 worker，运行中可串行停止、重新启动；生命周期每两秒复核共享数据库设置，关闭超时十秒终止 worker。自动任务停止后不再派发新任务，重新开启不会自动恢复已中断任务。
普通接口、播放票据、后台播放授权均重新读取核心账号权限，已有代理流每秒复核；前端按有效能力隐藏入口、停止播放器并清理影音查询缓存，纯阅读首次打开不初始化播放器。完整行为及第三方直链限制见模块开关。
- 阅读与账号数据保存在 reader.db，影音目录、版本、章节、收藏、播放进度和配置保存在 media.db。两库及签名密钥必须成对备份和恢复。
- 主服务先开放阅读，仅在全站开启影音时异步启动影音 Worker。关闭时返回 MEDIA_DISABLED，准备中返回 MEDIA_STARTING，失败返回 MEDIA_UNAVAILABLE；不会把影音启动或扫描任务排入阅读请求队列。
- MediaLibraries 管理媒体库权限与接入配置；MediaStorage 隔离本地目录和 OpenList。媒体资源引用不是外部下载 URL。
- MediaScanner 收集资源与资料，发布阶段通过独立事务原子更新目录，保留稳定身份、人工整理及已存在的进度。目录或远端旁车读取失败不发布不完整快照。
- 查询线程、发布线程及账号权限投影的边界见写入隔离。
领域结构
媒体库限定内容类型和访问范围。作品（电影、剧集、单集、歌手、专辑、曲目或有声书）可以包含多个版本；版本包含有序章节或播放部分，每部分引用一个文件资源。一个文件可产生多个内嵌章节，因此文件、作品、版本、章节不能混用身份。
手工调整作品归属、版本合并或拆分不会移动源文件；扫描保留人工组织和资料覆盖。不同版本不会因名称相同就自动混合播放。
元数据与播放
本地库使用 ffprobe 探测标签、编码、时长和章节，并读取同目录 NFO、封面、歌词、字幕。在线资料由 TMDB 和 MusicBrainz 适配器提供；用户审阅候选后确认覆盖，原文件不写回。
OpenList 使用 fs/list 与 fs/get，只读扫描，按需解析临时下载地址。播放方式由服务配置「媒体播放」决定：自动（默认）和直连模式在流票据鉴权后以 307 跳转让浏览器直连临时地址，失败或需要时由 Reader 授权接口代理 Range；代理模式始终经服务端转发。令牌不交给前端或下载源；远程内嵌资料暂不探测。具体配置与驱动限制见OpenList。
Web 音频使用浏览器媒体能力，视频采用 DPlayer；Android 使用 Media3。播放会话、流票据、进度并发和即时撤权由服务端控制。后台授权与进程恢复见后台播放。不提供转码、TVBox/JAR、云盘登录或影音离线下载。