媒体管理
媒体管理把散落在多个存储节点、多个网盘挂载源上的目录聚合成统一的媒体库，面向需要集中维护片源、元数据与可见范围的管理员。
能做什么
- 一个库挂多个来源目录，跨节点、跨网盘聚合成同一个条目。
- 三档手动同步，全量与强制先跑预览再落库。
- 作品 / 季 / 集三级元数据覆盖，覆盖值优先于刮削结果。
- 每个来源三项数据体检：孤儿资源、类型异常、残留来源。
- 按挂载源设置访问范围，控制哪些用户看得到、播得了。
界面与操作
库与来源目录
中央媒体库不扫描磁盘，只聚合文件管理里已经整理好的来源目录：刮削在存储节点侧完成，媒体侧负责同步与聚合。
| 项 | 说明 |
|---|---|
| 媒体类型 | 只有三档：不限 / 电影 / 剧集。没有动漫、音乐、照片这类独立库类型 |
| 新建表单字段 | 名称、类型、封面图 URL（选填，支持本地上传）、启用开关、来源目录数组 |
| 来源目录三要素 | 文件节点（取在线或待注册的存储节点）、挂载源、目录路径（目录选择器逐级浏览） |
| 来源的其他字段 | 排序、同步模式、是否启用同步 |
| 库卡片显示 | 标题数、来源数、上次同步时间、启用/停用开关、影/剧角标 |
| 封面缺省 | 回退到该库首个媒体项的海报 |
| 侧边栏排序 | 真实库与虚拟库可混合拖拽排序 |
条目列表
「媒体项」页签只做浏览与检索，能力边界很明确：
| 有 | 没有 |
|---|---|
| 关键词搜索 | 排序控件 |
| 分页，每页 24 / 48 / 60 / 96 / 120，默认 60 | 类型筛选器 |
| 网格 / 列表双视图、总数显示、刷新 | 批量选择与批量操作 |
| 卡片显示 2:3 海报、影/剧角标、年份、同步时间 | 评分、演员表 |
列表视图额外显示原始标题与挂载源名。条目数据结构里没有评分字段；后端库里有演职员数据，但后台 UI 不呈现。
条目详情
| 区域 | 内容 |
|---|---|
| 作品信息页签 | 海报、标题、原始标题、类型标签、年份、时长、简介、TMDB 外链、逐字段的「覆盖」徽标 |
| 季与剧集页签（仅剧集） | 集列表按季号 + 集号分组去重；同一集有多个文件时标「N 个版本」，并列出版本的文件名、容器与大小 |
| 文件来源抽屉 | 每个文件来源的挂载源 / 节点 / 库路径 / 父目录 / 文件名 / 大小 / 容器格式 / 同步时间；支持来源内搜索，也可删除单个文件来源（删除后重建聚合） |
| 操作 | 设置 / 修改 / 删除覆盖；重新刮削并修复同步（增量刮削 / 覆盖刮削，返回提交、跳过与失败的数量与任务号）；从媒体库删除此项 |
三级元数据覆盖
覆盖是人工改写刮削结果。优先级只有一条：覆盖值 > 原始刮削值，留空的字段不覆盖。
| 作用域 | 可覆盖字段 |
|---|---|
| 作品 | 标题、原始标题、上映/首播日期、时长（仅电影）、简介、类型标签、封面、扩展属性 JSON |
| 季（需指定季号） | 季标题、季封面 |
| 集（需指定季号与集号） | 集标题、集封面（缩略图）、集简介 |
| 细节 | 说明 |
|---|---|
| 类型标签预设 | 18 个：动作 / 喜剧 / 剧情 / 爱情 / 科幻 / 动画 / 悬疑 / 惊悚 / 恐怖 / 犯罪 / 纪录片 / 历史 / 传记 / 音乐 / 奇幻 / 冒险 / 家庭 / 战争 |
| 扩展属性 JSON | 收在「高级设置」折叠区里 |
| 封面字段 | URL 输入 + 本地文件上传 + 实时缩略预览 |
| 封面地址形态 | 兼容 http(s) 绝对地址、站内路径与 TMDB 相对路径（以 / 开头时自动拼成 TMDB 图片地址） |
同步与预览
三档手动同步的按钮就在每张来源卡片上。自动链路有两条：「中央媒体库同步」每 300 秒增量同步已启用的库；「同步队列处理」每 30 秒消费存储节点推来的变更队列。
| 模式 | 行为 | 用户编辑 | 是否先预览 |
|---|---|---|---|
| 增量同步 | 按游标只处理新增变更 | 保留 | 直接执行 |
| 全量同步 | 全量比对，并删除存储侧已不存在的差集 | 保留 | 先预览 |
| 强制全量覆盖 | 清空该来源数据后重插 | 清除 | 先预览 |
预览会算清：将新增与将更新的同步项、将删除的同步项与将消失的聚合项、以及因其他来源仍存在而保留下来的聚合项，另有预览告警。删除清单逐条列出，并标出该项是否含用户编辑、涉及哪些字段、是否只剩这一个来源；含用户编辑的项会显示「含用户编辑: 字段名」，可以逐条勾选「保留」。
执行同步另起一个后台任务，关闭弹窗不中断它，刷新页面后会恢复进度轮询。预览超时 10 分钟，同步超时 60 分钟。
数据体检
每个来源有三项体检，换节点、换网盘之后特别有用：
| 体检项 | 检测什么 | 处理动作 |
|---|---|---|
| 孤儿资源 | 媒体侧有记录但存储侧已无对应数据的同步项 | 手动比对 → 计数 → 删除，连带清理明细、流、演职员、同步项与无引用聚合项 |
| 类型异常 | 条目媒体类型与库设定类型不一致 | 检测 → 修复，触发一次全量同步 |
| 残留来源 | 已不属于任何来源配置的历史同步数据 | 检测 → 清理，适合处理重新接入存储节点后留下的旧节点数据 |
媒体源访问控制
访问控制挂在来源目录上，粒度是「存储节点 + 挂载源」。
| 维度 | 说明 |
|---|---|
| 授权对象 | 同一个「存储节点 + 挂载源」被多个媒体库引用时，一次配置作用于该挂载源下的全部目录 |
| 不是授权对象 | 挂载源类型、库路径、单文件 / TMDB 条目 / 季 / 集 |
| 同名编码 | 不同节点上的同名挂载编码是两个独立授权对象 |
| 公开 | 任意有效用户可见可播 |
| 受限 | 仅显式授权的用户可见可播 |
| 查不到策略记录 | 按受限处理（fail-closed） |
| 初始化 | 升级时已被引用的来源批量设为公开，避免突然断播；新接入的默认受限 |
| 配置入口（来源侧） | 媒体管理 → 媒体库 → 来源目录页签 → 每张来源卡片的「访问范围」行，一键在「公开 · 点击设为受限 / 受限 · 点击设为公开」之间切换，并显示「N 人获授权」 |
| 配置入口（用户侧） | 用户管理 → 用户详情「媒体来源 (N)」页签，只列受限来源供勾选；用户列表的批量「来源授权」只对受限挂载源执行授权或撤销，不影响公开来源 |
| 软过滤（媒体查询层） | 媒体库、搜索、最新、继续观看、详情、版本、季 / 集 / NextUp / Upcoming、Similar、图片、字幕、虚拟库 |
| 硬拦截（播放节点输出层） | 视频、下载、字幕在输出任何字节前校验实际来源为公开，或该用户已获授权 |
| 聚合语义 | 聚合项只要有一个可访问来源就显示，但只展示、只播放可访问版本；全部来源受限时整项隐藏 |
| 剧集判定 | 按每一集各自判定，一部剧所有集都不可访问时整部剧不显示 |
| 拒绝响应 | 用户态统一表现为不存在（404 或从集合省略），不泄露受限内容存在性 |
| 撤权边界 | 保存后清理媒体侧与各播放节点的权限缓存，新建播放信息、视频、下载与后续 Range 请求立即拒绝；已开始传输的同一条 HTTP 响应不强制中断 |
| 管理员语义 | 管理接口始终可查看与配置来源，但管理员走用户态播放器时不自动绕过来源权限 |
生产启用前先在测试环境跑通
媒体源访问控制已实现，但自动化测试、压测与端到端验证尚未完成，生产启用前建议先在测试环境验证一遍。
关键规则
| 情况 | 结果 |
|---|---|
| 想清空一个库的全部来源 | 不允许，至少保留一个来源；要清空须删除整库 |
| 更改已同步来源的目录 | 二次确认「原有同步数据将被清除」 |
| 节点失联 | 来源卡片提供「恢复节点」 |
| 删掉条目最后一个文件来源 | 条目消失 |
| 跑强制全量覆盖 | 清除用户编辑；增量与全量保留 |
| 库级的描述、匹配模式、刮削模式、元数据来源与 ffmpeg 开关 | 都没有 UI 可改 |
| 刮削发生在哪 | 存储节点侧：刮削队列每 15 秒、文件变更增量刮削每 15 秒、剧集简介剧照补全每天 04:30（Asia/Shanghai）、媒体探测信息回填每 3600 秒（默认停用，需在调度中心手动启用）；媒体侧只聚合。详见刮削与元数据 |
| 条目的容器格式与文件大小 | 由播放节点内嵌 ffprobe 在播放时异步补全，不阻塞播放，也不替代存储侧的 TMDB / NFO 刮削 |