Moonfin多服务器统一库如何工作?一套Jellyfin/Emby双协议API层架构解析

原创2026-10-24 22:12:551,694 阅读

Moonfin多服务器统一库如何工作?一套Jellyfin/Emby双协议API层架构解析

Moonfin 是一款高级版 Jellyfin 与 Emby 双协议媒体客户端,用一份 Flutter 代码库覆盖手机、平板、桌面、Android TV、Apple TV 和 Web。本文带你完整读懂它最核心的两大设计:多服务器统一库——把多台媒体服务器合并成一个可浏览、可搜索的界面;以及双协议 API 层——让同一套上层代码同时驾驭 Jellyfin 和 Emby 两套接口。

什么是多服务器统一库?

很多家庭用户不止一台媒体服务器:一台跑电影的 Jellyfin、一台跑电视剧的 Emby、还有一台放在别处的轻量库。传统客户端只能一次连接一台服务器,切换服务器意味着重新浏览、重新搜索、重新加载。

Moonfin 的做法是把所有已登录的服务器"摊平":继续观看、下一集、最新入库、收藏、流派、影棚……每一行内容都来自多台服务器的并行拉取与合并,界面上你看到的只有一条完整的媒体流。

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 返回 null
  • embyAdminApi——仅 Emby 有的管理端点,Jellyfin 上为 null
  • clientLogApi、gamesApi——插件/版本差异能力

2️⃣ 实现层:server_jellyfin 与 server_emby 各写一套

两个协议包提供完全对等的具体实现:

两个实现各自约 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。一次"刷新首页"的完整流程:

  1. 建立会话:getLoggedInServers() 遍历所有已登录服务器,为每台取回 token 和用户 ID,组装成 ServerUserSession(服务器 + 用户 + 客户端三元组),并缓存 5 秒避免重复构建。
  2. 并行扇出:Future.wait 向所有服务器同时发起请求,每台服务器有 8 秒超时(第49行);拉"继续观看"这类行时每台服务器取 limit × 3 的候选量,合并后再截取,保证排序公平。
  3. 单台容错:_gatherPerServer()(第1236-1257行)让某台服务器超时或报错只影响它自己——返回空列表;只有全部服务器都失败才抛出异常,UI 保留上一轮内容。
  4. 去重与排序:合并时以 serverId_itemId 为唯一键去重,再按"最后播放时间""年份""社区评分"等统一排序,生成一条 HomeRow 交给界面。
  5. 分页加载:loadMore() 按行 ID 加服务器 ID 分别追踪每台服务器的偏移量(第599-981行),下拉加载更多时每台服务器各自翻页,互不干扰。

多服务器时,库名会自动带上来源,如"我的电影(Emby-Home)",让用户始终知道内容来自哪台机器。

Moonfin统一导航界面,一个入口浏览来自多台Jellyfin与Emby服务器的媒体库

权限与可见性:合并不能越界

统一库把多台服务器拼在一起,权限边界却必须保持。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,协议差异继续被封在实现层里,和浏览层完全同构。

Moonfin双协议播放界面,同一播放器适配Jellyfin与Emby的直连和转码流

总结:一套架构,双重收益

设计 位置 收益
抽象 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 了解开发规范。

登录后查看全文
Moonfin-Core