技术细节与开发 - MiCat-S/Mi302 GitHub Wiki

繁體中文 | 简体中文 | English

这一页写给想了解内部运作或参与开发的人：请求流程、路径怎么匹配、已实现的 Emby 接口、管理 API、代码结构、怎么运行测试，以及参考过的项目。

Mi302 是一个 FastAPI 程序，用 uvicorn 运行，数据存在 SQLite（data/library.db）。

1. 扫描：把媒体库文件夹里的 .strm、普通视频文件、nfo、图片写进数据库，见 媒体库与扫描。
2. 浏览：播放器调用 Emby API（/Users/{id}/Views、/Items…），Mi302 从数据库组装出 Emby 的 BaseItemDto。
3. 播放信息：POST /Items/{id}/PlaybackInfo。strm 项目返回 Protocol=Http、IsRemote=true，只允许直接播放（关闭转码），DirectStreamUrl 指回 /videos/{id}/stream.{格式}。
4. 串流：播放器请求 /Videos/{id}/stream、/Videos/{id}/original.xxx 或 /Items/{id}/Download：
   • strm 项目：读取 strm 内容，应用路径替换；带 pickcode 就用播放器的 User-Agent 向 115 获取直链，否则可以先跟随上游的重定向；最后返回 302 Location: <真实地址>。
   • 普通视频文件：直接发送文件，支持 Range。
5. 进度：/Sessions/Playing… 记录续播位置和已看，也用来学习片头片尾，见 片头片尾跳过。

细节见 播放与外网访问。Mi302 对外报告自己是 Emby Server 4.8.11.0。

每个进来的 HTTP 请求先整理路径，再匹配路由：

• 路径里的英文字母转成小写，其他字符不动（/Persons/Émilie 的 É 保留），所以路径不区分大小写。
• 去掉开头的 /emby、/mediabrowser，有没有这个前缀都可以。
• 去掉结尾的 /。
• 查询参数的名称不区分大小写（ParentId、parentid 都可以）。

其他：

• 错误响应是纯文本，和 Emby 一样。
• CORS 全开。
• FastAPI 自动生成的 API 文档在 /api-docs。

token 依次从这些地方查找：

1. 请求头 X-Emby-Token、X-MediaBrowser-Token。
2. 请求头 X-Emby-Authorization（或 Authorization）里的 Token="…"，格式是 MediaBrowser Client="…", Device="…", DeviceId="…", Version="…", Token="…"。
3. 查询参数 api_key、X-Emby-Token、ApiKey、X-MediaBrowser-Token。

token 由 POST /Users/AuthenticateByName 签发。同一个用户在同一台设备（DeviceId）重新登录时，旧的 token 作废。API 密钥（配置文件的 api_keys，或在网页上创建的）以管理员的身份运行（按名称排序的第一个管理员），给 MoviePilot 这类程序用；它不能调用 /web/api/… 和 /p115/…。

路径里有用户（/Users/{id}/…）或带 UserId 参数时，读写的是那个人的观看记录、续播点和收藏。普通用户只能指定自己，指定别人返回 403；管理员和 API 密钥可以指定别人，找不到那个人返回 404。id 不区分大小写，也接受带连字符的 GUID 写法。没指定就是登录的人。

路径按 Emby 的写法列出，实际上不区分大小写。除了标注“不用登录”的，都要带 token。

/Items 的查询参数：ParentId、Recursive、IncludeItemTypes（含 Person 时同时搜索人物）、ExcludeItemTypes、Ids、PersonIds、Person、IsFolder、SearchTerm、NameStartsWith、Years、Genres、Filters（IsPlayed、IsUnplayed、IsFavorite、IsResumable）、IsPlayed、IsFavorite、SortBy、SortOrder、StartIndex、Limit、Fields（MediaSources、People、Chapters）、UserId。

StartIndex、Limit 是负数或无法识别时当作没给。/Items 和 /Shows/{id}/Episodes 没给 Limit 就是全部，和 Emby 一样；最新、继续观看、接着看默认 20 项，人物搜索默认 50 项，这几个最多 500 项。Limit=0 只返回总数。

SortBy 支持：SortName、Name、DateCreated、DateLastContentAdded、PremiereDate、ProductionYear、CommunityRating、CriticRating、Runtime、Random、DatePlayed、PlayCount、IndexNumber、ParentIndexNumber、AiredEpisodeOrder。

返回空结果的接口（让播放器不报错）：/Users/{id}/Items/{id}/Intros、/Items/{id}/Similar、/Movies/{id}/Similar、/Shows/{id}/Similar、/Videos/{id}/AdditionalParts、/Items/{id}/CriticReviews、/Users/{id}/Items/{id}/LocalTrailers、/Users/{id}/Items/{id}/SpecialFeatures、/Items/{id}/SpecialFeatures、/Items/{id}/ThemeMedia。

管理页面 /web 用的 API。115 的文件、文件夹 id 有 19 位，超过 JavaScript 能精确表示的整数，返回时一律是字符串；传进来时字符串、数字都接受。除了 /web/api/setup，都要用管理员账号登录后的 token（放在 X-Emby-Token 请求头），API 密钥不行。请求和响应都是 JSON。

GET /web 是管理页面本身，/web/115 跳转到 /web#115。

embyserver/ 下的每个模块：

数据库 library.db 的数据表：meta（服务器 id、115 登录状态、同步进度等）、users、tokens、items、user_data（观看记录、收藏）、p115_index（115 文件 id 对应本地路径）、media_info、people、person_names、intro_obs、mp_no_image。

需要 Python 3.10 以上。在 venv 里：

pip install -r requirements.txt pytest ruff
python -m pytest
ruff check embyserver tests

测试也会用 node --check 检查管理页面的 JavaScript 语法（没有 node 就跳过），并检查文档：Wiki 的链接和锚点都找得到、每一页都在侧栏、三种语言的配置文件参考都写到每一个键。

改了 install.sh 之后：

shellcheck install.sh

• DDSRem-Dev/MoviePilot-Plugins：302 播放流程参考 embyreverseproxy 插件，区别是 Mi302 背后不需要真的 Emby，Emby API 自己实现；115 扫码登录和获取直链的流程参考 p115strmhelper。
• StrmAssistant（Emby 神医助手）：X-mediainfo.json 沿用它“媒体信息持久化”的格式；片头片尾的学习方法参考它的“片头探测 - 播放行为”。
• xiao-vvv/emby-mediainfo（MIT 许可）：ffprobe 到 Emby 字段的对照、探测的限速和 115 熔断规则改写自这个项目，版权声明保留在 embyserver/mediainfo.py。