媒体代理

xylplm2026/3/14大约 5 分钟媒体代理EmbyJellyfinPlex

🚀 媒体服务 - 媒体代理

📌 功能概述

媒体服务新增了统一的 媒体代理 能力，用来处理 Emby、Jellyfin、Plex 的播放请求。

相比旧版“拿到直链就跳转”的单一路径，新方案会根据客户端能力、直链可用性和网络环境，自动选择最合适的播放方式，在兼容性与稳定性之间取得更好平衡。

✨ 核心能力

统一代理三类媒体服务器：Emby、Jellyfin、Plex 共用同一套播放代理主链路，减少不同服务之间的行为差异
三段式播放分发：优先尝试直链跳转；不适合跳转时改为服务端中继；直链失败时再回退到原媒体服务器代理
客户端感知分发：可根据客户端、设备、请求头、请求方式等条件决定是直出、转中继还是回源
直链可用性探测：返回给客户端前会优先探测直链是否可用，避免把无效链接直接下发给播放器
PlaybackInfo 预处理：在播放前预热媒体路径缓存，并对播放源顺序做优化，改善多版本资源和不同客户端的播放体验
更完整的路径解析：支持路径缓存、API 补查、路径映射、白名单、.strm 解析、符号链接解析、二次 URL 映射等能力
图片与字幕缓存增强：除了播放链路，还补充了图片、字幕等静态资源的代理与缓存优化
Go 内置代理替代旧方案：代理能力由 Go 服务直接提供，逐步替代依赖外部 nginx 模板的旧实现

🎯 主要解决的问题

某些客户端不稳定跟随 302 跳转
私网直链返回给外网客户端后无法访问
Range 拖动、HEAD 探测、跨域等兼容性不稳定
直链获取失败时，过去只能直接播放失败，缺少自动兜底
Emby、Jellyfin、Plex 之前的代理逻辑分散，维护成本高

⚙️ 工作原理

媒体代理会把一次播放请求拆成 4 个阶段：

识别请求
根据请求路径自动判断当前是 Emby、Jellyfin 还是 Plex，并识别这是播放、下载、转码、图片还是 PlaybackInfo 请求。
解析媒体源
从缓存或媒体服务器接口中获取真实文件路径，然后依次完成：
- .strm 链接解析
- 路径映射
- 白名单判断
- 直链获取
- 直链地址二次改写
决定分发方式
代理会综合客户端类型、请求方法、是否为私网直链、直链探测结果、是否命中代理规则等信息，生成最终分发策略。
执行响应并自动降级
如果首选方案失败，会自动切换到下一层兜底方案，尽量保证客户端还能继续播放。

🔁 三种分发模式

1) 直链跳转（Redirect）

适合客户端能直接访问目标地址、并且直链稳定可用的场景。此时代理返回 302/307，让客户端直接去播放真实资源。

2) 直链中继（Relay Link）

适合客户端不方便直接访问直链，或者直链带有敏感鉴权、私网地址、兼容性较差的场景。此时由服务端代替客户端去请求真实直链，再把数据流式转发给播放器。

3) 原站代理（Relay Origin）

当直链解析失败、中继失败、命中强制代理规则，或者请求本身更适合走原媒体服务器时，会自动回退到原媒体服务器继续处理。

🧭 典型处理流程

客户端发起播放请求
  -> 识别媒体服务器类型与请求意图
  -> 解析真实媒体路径与直链
  -> 判断当前应走 Redirect / Relay Link / Relay Origin
  -> 首选方案失败时自动降级
  -> 返回最终可播放结果

🛡️ 兼容性与稳定性设计

对 GET、HEAD、Range 等常见播放请求做兼容处理
对私网直链、跨域、跳转次数、防环路等场景做保护
对同一资源的直链获取、探测和路由决策做缓存，减少重复请求
保留回滚能力，联调期间出现兼容问题时可以切回旧链路

📌 与旧代理方案的区别

旧方案更偏向“拿到直链就跳转”，新方案改为“先判断，再分发，再自动兜底”
旧方案依赖外部 nginx 模板，新方案以 Go 内部代理为主
新方案更强调客户端兼容性，尤其是移动端、拖动播放、私网链接和多种播放器差异
新方案把 Emby、Jellyfin、Plex 的代理能力统一到同一套架构里，后续维护和扩展更容易

⚠️ 使用注意事项

确保媒体服务器可以正常访问
API 密钥需要具有足够权限以获取媒体库信息
建议设置一个默认媒体服务器用于媒体状态检查
定期同步媒体库以保持数据准确性
若启用了媒体代理，建议同时确认代理端口、外网访问地址与直链可达性配置正确