添加媒体
Provider 是 SyncTV 把外部媒体解析成播放结果的适配层。接入前先回答三个问题：
| 问题 | 影响 |
|---|---|
| 媒体是否能被客户端直接访问 | 决定直连还是代理 |
| 上游是否要求特殊 header 或 Cookie | 决定客户端能否直连，或必须走 SyncTV proxy |
| 凭据属于用户还是实例 | 决定是否需要用户绑定、Provider instance 或凭据加密 key |
内置 Provider 类型包括 alist、bilibili、emby、direct-url、rtmp 和 live-proxy。远程 Provider instance 用数据库持久化的连接信息接入另一组 Provider 服务，不是 media_providers YAML 对象。
- 配置
security.credential_encryption_key或_file，确保 Provider 凭据可以加密保存。 - 确认本地 Provider timeout：
media_providers.<type>.request_timeout_seconds和connect_timeout_seconds。 - 如需远程 Provider，通过管理 API/CLI 创建 Provider instance。
- 用管理员账号测试登录、浏览、搜索、解析和播放。
- 分别测试直连、代理和 Range seek。
- 观察 Provider 错误率、proxy 错误、slice cache 命中和上游状态码。
适合：网盘、挂载目录、文件浏览和搜索。
重点：
- 常见操作是登录、列目录、搜索、选择文件并添加到播放列表。
- 上游 URL 可能要求固定
User-Agent。 - 如果浏览器不能设置要求的 header，应选择代理播放。
- 目录很大时优先分页、搜索和缓存，不要让客户端无限滚动触发大量上游请求。
验收：列表可打开，搜索可用，直连和代理至少一种可播放，seek 后没有持续 4xx/5xx。
适合：已有媒体库、剧集、字幕和转码能力。
重点：
- SyncTV Provider 返回的播放结果可能包含多个 playback mode、字幕和 metadata。
- 客户端应按
default_mode和PlaybackClientProfile选择播放 URL。 - 如果用户设备不支持某些编码或容器，应请求转码或选择兼容结果。
- 上游库账号、服务器地址和 TLS 策略要由管理员或用户绑定明确管理。
验收：媒体列表、播放 URL、字幕、转码或直连模式都能按客户端能力选择。
适合：解析 Bilibili 视频，使用二维码或短信等方式维护凭据。
重点：
- 对
Referer、User-Agent、Cookie 和 Range 请求敏感。 - 直连和代理使用的 header 必须一致。
- 凭据过期时应引导用户重新登录，不要把上游认证失败当作 SyncTV token 失效。
- 上游限流或 CDN 变化会表现为 Provider 临时不可用。
验收：解析成功，代理请求带正确 header，seek 可用，凭据过期时错误可理解。
适合：已有稳定 URL、对象存储公开链接、内网媒体地址。
重点：
- 只有客户端能访问该 URL 时才适合直连。
- 如果 URL 只在服务端网络可访问，使用 proxy。
- 尽量使用支持 Range 的上游，提升 seek 和 slice cache 效果。
- 带签名过期时间的 URL 需要刷新播放信息。
验收：客户端能 GET/Range，或 SyncTV proxy 能代表客户端访问。
适合：房间内直播推流、HLS/FLV 播放。
重点：
- RTMP 是推流入口，不是普通点播 Provider。
- 房间成员需要
live_control权限才能管理直播和创建推流 key。 - 多副本下必须明确 HLS backend：本地 publisher-node proxy、
shared_file或 OSS。 - 直播路径比点播更依赖端口、存储和长连接 drain。
验收：推流 key 可创建，RTMP 推流成功，HLS/FLV 可播放，多副本不会随机 404。
本地 Provider 和远程 Provider
Section titled “本地 Provider 和远程 Provider”| 模式 | 配置位置 | 适用场景 |
|---|---|---|
| 本地内置 Provider | media_providers YAML 配置 timeout | SyncTV 进程直接访问 Alist、Emby、Bilibili 等上游 |
| Provider instance | 管理 API/CLI 持久化到数据库 | 多实例、多凭据、多远程服务 |
| 远程 Provider | Provider instance 的 endpoint、tls、jwt_secret 等 | 把 Provider 能力拆到独立服务或网络边界 |
远程 Provider 自己访问上游媒体所需的配置，应放在远程 Provider 服务的部署配置中；SyncTV 只保存连接远程 Provider 所需的信息。
- 配置
security.credential_encryption_key_file，并把真实 key 放在 Secret Manager 或 Kubernetes Secret。 - 每个 Provider 凭据明确归属：用户级、实例级或远程 Provider 服务级。
- 禁止把 Cookie、token、API key 写进
sourceConfig、URL query、日志或截图。 - 凭据轮换前先确认旧凭据是否还被播放列表、用户默认 Provider 或远程实例引用。
密钥轮换见 安全加固与密钥轮换。
| 现象 | 先查 |
|---|---|
| 列表可用但播放失败 | 播放 URL、header、代理模式、上游 Range |
| 直连可播但代理失败 | Provider 给 proxy 的 header、上游是否拒绝服务端 IP |
| 代理可播但直连失败 | 浏览器是否能设置 header、CORS、客户端网络是否能访问上游 |
| Bilibili 偶发 403 | Cookie、Referer、User-Agent、上游 CDN 策略 |
| 多副本直播 404 | publisher 节点、HLS backend、共享存储或 OSS 配置 |