Moonfin多服务器统一库如何工作?一套Jellyfin/Emby双协议API层架构解析
Moonfin多服务器统一库如何工作?一套Jellyfin/Emby双协议API层架构解析
Moonfin 是一款高级版 Jellyfin 与 Emby 双协议媒体客户端,用一份 Flutter 代码库覆盖手机、平板、桌面、Android TV、Apple TV 和 Web。本文带你完整读懂它最核心的两大设计:多服务器统一库——把多台媒体服务器合并成一个可浏览、可搜索的界面;以及双协议 API 层——让同一套上层代码同时驾驭 Jellyfin 和 Emby 两套接口。
什么是多服务器统一库?
很多家庭用户不止一台媒体服务器:一台跑电影的 Jellyfin、一台跑电视剧的 Emby、还有一台放在别处的轻量库。传统客户端只能一次连接一台服务器,切换服务器意味着重新浏览、重新搜索、重新加载。
Moonfin 的做法是把所有已登录的服务器"摊平":继续观看、下一集、最新入库、收藏、流派、影棚……每一行内容都来自多台服务器的并行拉取与合并,界面上你看到的只有一条完整的媒体流。
双协议API层:三层架构设计
统一库之所以成立,前提是上层代码完全不需要知道"对面"是 Jellyfin 还是 Emby。Moonfin 在 packages/ 下用三个包实现了这套分层:
1️⃣ 抽象层:server_core 定义"一个媒体服务器长什么样"
核心是一份抽象基类 MediaServerClient,它把服务器能力切成约 20 个 API 接口:AuthApi(认证)、ItemsApi(媒体条目查询)、PlaybackApi(播放)、ImageApi(海报)、LiveTvApi(直播)、一系列 Admin*Api(管理面板)……
上层仓库(Repository)只依赖这些接口,从不依赖具体协议。差异能力则用可空接口优雅表达,例如 media_server_client.dart#L70-L83:
syncPlayApi(同步观影)——仅 Jellyfin 有,Emby 返回 nullembyAdminApi——仅 Emby 有的管理端点,Jellyfin 上为 nullclientLogApi、gamesApi——插件/版本差异能力
2️⃣ 实现层:server_jellyfin 与 server_emby 各写一套
两个协议包提供完全对等的具体实现:
- JellyfinMediaServerClient:基于 Dio,用
MediaBrowser认证头签名每个请求 - EmbyMediaServerClient:按 Emby 4.8+ 的 REST 约定实现同一组抽象接口
两个实现各自约 20 个 *Api 文件,把抽象接口落到真实的 HTTP 路径与参数上。对上层而言,JellyfinMediaServerClient 和 EmbyMediaServerClient 都是"一个 MediaServerClient",可互换。
3️⃣ 工厂层:按服务器类型"发牌"
MediaServerClientFactory 负责根据服务器类型创建对应客户端,并按 serverId 缓存——一台服务器一个客户端实例,这正是统一库能并发访问多台服务器的基础。工厂还会把客户端包进 ConnectivityAwareMediaServerClient,让离线下载目录与在线请求自动路由。
服务器类型如何自动识别?
连接时客户端会询问服务器的产品名和版本号,ServerType.detect() 据此判定:名字里含 "jellyfin" 就是 Jellyfin;版本号形如 4.x.x.x 四段且主版本小于 10 的判定为 Emby。
判定完成后,FeatureDetector 根据"协议 + 版本"输出能力开关:
| 能力 | Jellyfin | Emby |
|---|---|---|
| 同步观影 SyncPlay | ✅ | ❌(接口为 null) |
| Trickplay 缩略图拖拽 | ✅ | ✅(走 BIF 方式) |
| Quick Connect 快速连接 | ✅(10.9+ 支持预填链接) | ❌ |
| 歌词 | ✅ | ❌ |
| 片头片尾跳过 | ✅(MediaSegments) | ✅(章节标记) |
UI 层只需问 FeatureDetector,就能自动隐藏当前服务器不支持的入口,而不是直接报错。
统一库的数据流:并行拉取、容错合并
所有合并逻辑集中在 MultiServerRepository。一次"刷新首页"的完整流程:
- 建立会话:
getLoggedInServers()遍历所有已登录服务器,为每台取回 token 和用户 ID,组装成 ServerUserSession(服务器 + 用户 + 客户端三元组),并缓存 5 秒避免重复构建。 - 并行扇出:
Future.wait向所有服务器同时发起请求,每台服务器有 8 秒超时(第49行);拉"继续观看"这类行时每台服务器取limit × 3的候选量,合并后再截取,保证排序公平。 - 单台容错:
_gatherPerServer()(第1236-1257行)让某台服务器超时或报错只影响它自己——返回空列表;只有全部服务器都失败才抛出异常,UI 保留上一轮内容。 - 去重与排序:合并时以
serverId_itemId为唯一键去重,再按"最后播放时间""年份""社区评分"等统一排序,生成一条 HomeRow 交给界面。 - 分页加载:
loadMore()按行 ID 加服务器 ID 分别追踪每台服务器的偏移量(第599-981行),下拉加载更多时每台服务器各自翻页,互不干扰。
多服务器时,库名会自动带上来源,如"我的电影(Emby-Home)",让用户始终知道内容来自哪台机器。
权限与可见性:合并不能越界
统一库把多台服务器拼在一起,权限边界却必须保持。LibraryScopeService 区分了两个容易混淆的概念:
- Access(访问权):管理员给用户开放的媒体文件夹,由服务器在接口层面强制执行;
- Visibility(可见性):用户自己在"我的媒体"里隐藏的库。两个服务器的递归/搜索接口都不会替你过滤它,所以客户端必须把查询范围手动收窄到可见库 ID 列表。
它的哲学是"失败开放":解析出权限异常时宁可全量展示,也不把界面刷成空白。
两协议的真实差异,客户端如何抹平
双协议并非处处相同,Moonfin 在几处关键差异上做了针对性补偿:
- Token 参数大小写:Jellyfin 12 用小写
api_key还是大写ApiKey与 Emby 不同,ServerType 为每种类型提供tokenQueryParam,URL 拼装时自动适配。 - 字幕 Drop 方法:Emby 不认识,
supportsSubtitleDrop让流请求自动省略该参数(server_type.dart#L8-L9)。 - 直播 HLS 封装:Emby 的直播 HLS 只有 MPEG-TS 分段能正常工作,MediaStreamResolver.preferMpegTsHlsForLive() 会在请求前把 Emby 设备档案里的 TS 转码条目提到 fMP4 之前,Jellyfin 则无需处理。
播放层:同样的分层思想复用
统一库解决"看到什么",播放层解决"怎么播"。播放侧沿用同一套三层结构:
- playback_core:定义
PlayerService、MediaStreamResolver等抽象,管播放生命周期; - playback_jellyfin 与 playback_emby:各自实现播放会话上报——开始、进度、停止——映射到本协议的
/Sessions/Playing系列接口。
播放器因此只需面对一个 PlayerService,协议差异继续被封在实现层里,和浏览层完全同构。
总结:一套架构,双重收益
| 设计 | 位置 | 收益 |
|---|---|---|
抽象 MediaServerClient + 可空能力接口 |
server_core | 上层零协议感知 |
双实现 server_jellyfin / server_emby |
packages/server_jellyfin、packages/server_emby | 差异封装在最底层 |
| 类型自动检测 + 特性探测 | server_type.dart、feature_detector.dart | UI 自适应,不报错 |
| 并行扇出 + 容错合并 | multi_server_repository.dart | 多服务器像一台一样流畅 |
| 作用域过滤 | library_scope_service.dart | 合并不越权、不露隐藏库 |
对普通用户,这套架构意味着:添加多台服务器后无需来回切换,一个界面看全所有片源;同时连接 Jellyfin 和 Emby 也完全没问题。想深入更多功能(离线下载、Live TV、游戏库),可阅读 README.md 中的功能清单与 CONTRIBUTING.md 了解开发规范。


