媒体代理
媒体服务 - 媒体代理
功能概述
媒体代理为 Emby、Jellyfin、Plex 提供统一的播放代理入口。播放请求进入代理后，会先尝试解析真实媒体路径并生成可用直链；成功时返回 302 让客户端直接播放，未命中或解析失败时则继续交由原媒体服务器处理。
核心能力
- 统一识别 Emby、Jellyfin、Plex 的播放相关请求
- 解析媒体真实路径，并结合路径映射、网盘挂载路径规则和远程链接信息完成播放前准备
- 支持
.strm和 HTTP 链接场景，能够继续追踪到实际可用的播放地址 - 通过存储侧的直链能力获取可播放地址
- 对最终直链做必要改写后返回
302 - 当路径解析失败、直链获取失败或当前请求不适合直链时，自动回退到原媒体服务器
- 对浏览器播放场景补充播放信息、跨域和直放兼容处理
- 成功分发后可选发送媒体播放通知
工作逻辑
1. 接收播放请求
代理会先识别当前请求来自哪类媒体服务器，并判断它是播放、播放信息获取、元数据补查，还是与播放上下文有关的请求。
这一步的目的，是先把真正需要增强处理的播放链路挑出来；普通请求仍然可以直接交给原媒体服务器处理。
2. 补齐媒体路径
播放请求进入增强链路后，会先尝试解析真实媒体路径。解析顺序大致如下：
- 优先利用已有的播放信息补齐路径
- 信息不足时，再向媒体服务器补查
- 对路径执行映射、网盘挂载路径判断和必要的规范化处理
- 如果遇到
.strm或远程链接，继续解析出内部真实路径或提取码
这一层的重点不是“直接播放”，而是先把媒体实际对应的文件位置尽可能找准。
3. 生成播放直链
解析到媒体路径后，代理会尝试通过存储侧的直链能力获取最终播放地址。
在这一步中，代理会根据路径情况决定是直接处理常规路径，还是优先处理命中网盘挂载路径的内容。拿到直链后，还会根据配置对返回地址做进一步调整，确保客户端拿到的是最终可访问的播放链接。
4. 返回结果
如果直链准备成功，代理会返回 302，让客户端直接访问目标地址；如果失败，则继续回到原媒体服务器的处理链路。
对于播放器来说，这个过程通常是无感的，表现出来就是“能直放时优先直放，不能直放时继续按原来的方式播放”。
服务差异
Emby / Jellyfin
Emby 和 Jellyfin 的逻辑比较接近，重点在播放前准备和浏览器兼容性：
- 会利用播放信息中的媒体源内容提前整理出播放路径
- 会尽量把影片条目和具体媒体源对应到同一条可复用的路径信息，减少重复补查
- 对浏览器场景下的 HTTP
.strm会额外增强直放能力 - 会处理浏览器播放中的跨域细节，降低 Web 端直放失败的概率
- 对探测类请求和转码类请求保持更保守的处理方式，避免影响原播放器行为
简单理解，就是 Emby / Jellyfin 更偏向“先把播放信息整理好，再决定能不能顺利直放”。
Plex
Plex 的播放链路更依赖上下文补齐，重点在于把分散的播放信息重新拼起来：
- 会结合元数据、播放队列和播放进度等信息，补齐播放项目和文件之间的关系
- 当一次播放请求本身提供的信息不完整时，会先把上下文补齐，再继续解析路径
- 对
.strm内容也会继续向下解析，尽量还原出实际可用的目标地址 - 路径和上下文都准备完成后，再尝试生成直链；否则继续交给 Plex 原服务处理
简单理解，Plex 更像是“先把播放上下文拼完整，再进入直链流程”。
配置思路
如果要让媒体代理稳定工作，通常重点关注下面几类配置：
代理通知- 用于控制是否发送播放通知
网盘挂载路径- 适合填写一类已经明确可直接处理的路径前缀
- 命中后会优先按网盘挂载路径进入直链准备
媒体路径映射- 用于把媒体服务器上的实际路径转换成
mlist能识别的路径 - 如果媒体服务器路径和存储路径不一致，这一项通常是最关键的
- 用于把媒体服务器上的实际路径转换成
使用建议
- 先确认媒体服务器本身能正常播放，再开启媒体代理排查代理链路
- 优先保证路径映射正确，再考虑网盘挂载路径
.strm场景建议分别在浏览器端和常用客户端上验证一次- 如果某类请求本身更依赖原播放器行为，例如探测、转码或特殊客户端请求，代理会更倾向保守处理
- 要保证 API Key 具备读取媒体信息的权限，否则路径补查会失败
- 建议用一两部实际常看的影片先验证链路，再扩大到全库使用
总结
可以把媒体代理理解成一条统一的播放增强链路：
识别播放请求 -> 补齐媒体路径 -> 尝试生成直链 -> 成功则 302 -> 失败则继续走原媒体服务器
对使用者来说，最重要的不是内部实现细节，而是把路径映射、链接可达性和客户端兼容性三件事配好。只要这三部分正确，媒体代理就能在 Emby、Jellyfin、Plex 的常见播放场景里提供更稳定的直放体验。