媒体 Provider

Provider 配置是什么？

Media Provider 是 SyncTV 访问外部媒体来源的方式，例如：

视频平台：Bilibili、Twitch、YouTube、抖音、TikTok、虎牙、斗鱼、AcFun、CCTV。
媒体服务器与文件服务：Alist、Cloudreve、Emby/Jellyfin。
NAS 与私有云：FNOS、QNAP、Synology、Nextcloud、Seafile、TrueNAS。
Direct URL、RTMP、live proxy。
远程 Provider instance。

media_providers 只配置本进程内置的 local provider adapter。每个 provider 都有明确的配置项：

media_providers:
  alist:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10
  bilibili:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10
  emby:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

远程 Provider instance 不是这个 YAML 对象。它通过管理 API/CLI 持久化到数据库，只保存 SyncTV 连接远程 Provider 所需的连接信息，例如 endpoint、tls、jwt_secret、custom_ca、timeout、insecure_tls 和 providers。远程 Provider 自己访问 Alist、Emby 或 Bilibili 所需的配置，应放在远程 Provider 服务自己的部署配置中。

按场景接入 Alist、Emby/Jellyfin、Bilibili、直链、RTMP 或远程 Provider 时，先读添加媒体。

各 Provider 的绑定方式、资源类型和动态播放列表能力见 Provider 使用手册。实现与扩展流程见 Provider 开发指南。

Provider instance

每个来源都可以指定 Provider instance。空 instance name 表示默认 local instance；具名 instance 可以指向本地独立配置或远程 gRPC backend。管理员通过 Provider instance 管理接口配置 endpoint、TLS、认证 secret、超时和允许的 Provider 列表。

用户凭据会保存 provider_instance_name。同一个上游服务器通过多个 instance 绑定时会生成独立的凭据作用域。创建媒体和播放列表时，App 会把所选 instance 写入资源绑定，播放、封面和动态列表请求沿用该 instance。

本地 Provider 超时配置

`request_timeout_seconds`

默认值：30。作用：一次该 provider 的上游 HTTP 请求最多等待多久。

`connect_timeout_seconds`

默认值：10。作用：该 provider 建立上游 TCP 连接最多等待多久。

如果 connect_timeout_seconds 大于同一 provider 的 request_timeout_seconds，配置校验会提示不合理。

Alist 示例：

media_providers:
  alist:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

Emby 示例：

media_providers:
  emby:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

Bilibili 示例：

media_providers:
  bilibili:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

其余内置 Provider 使用相同的 timeout contract。仅启用该 Provider 支持的配置项；协议端点、Cookie、token、账号密码和 API key 通过用户绑定接口持久化。

Page 与 Cursor 能力

Provider 列表 API 通过 protobuf oneof 返回 page 或 cursor 模式。Cloudreve 会根据服务器能力返回当前模式；Bilibili 历史、Twitch 和 YouTube 使用上游原生 cursor；传统目录和索引通常使用 page/offset。

客户端将 cursor 视为 opaque token。部署者无需配置 cursor 生成规则。

Provider 请求头原则

SyncTV 的底层 proxy 不应该自己猜测和转发客户端原始请求头。Provider 应该明确决定上游请求需要哪些 header，例如：

User-Agent
Referer
Range
Provider 特定认证 header

这样做的好处：

行为可预测。
不会把客户端不该转发的 header 泄露给上游。
不同 Provider 可以按自己的要求设置直连和代理 header。

Alist 提示

Alist 可能返回对 User-Agent 有要求的 URL。SyncTV 会尽量保证：

Provider 自己发起的请求使用的 UA。
返回给客户端直连时要求客户端使用的 UA。
代理模式转发到上游时使用的 UA。

三者在语义上保持一致。

如果客户端无法设置某些 header，就应该选择代理模式，而不是直连。

Bilibili 提示

Bilibili 对请求头更敏感，尤其是：

User-Agent
Referer
Cookie 或鉴权相关 header
Range 请求

如果你发现直连可用但代理不可用，或代理可用但直连不可用，优先检查 Provider 返回给客户端的 header 与代理上游请求 header 是否一致。

凭据加密

如果你保存 Provider 凭据，生产环境应该配置：

security:
  credential_encryption_key_file: "/run/secrets/credential_encryption_key"

否则，创建或更新某些 Provider 凭据可能会被拒绝，或者已有加密凭据无法读取。