媒体服务
Bonita 目前以 Emby 为主要对接对象：观看记录、收藏、新媒体入库、合集都可以同步。先在 服务设置 里填好连接，再按需要打开 Webhook 或跑全量同步。
连接 Emby
打开 服务设置 → Emby API：
- 填写服务器地址，例如
http://192.168.1.10:8096 - 填写 用户名（只处理这个用户的观看 / 收藏事件）
- 填写 API Key
- 打开启用，点 测试连接，成功后再保存
用户名必须和 Emby 里实际使用的账户一致。Webhook 里其它用户的事件会被直接忽略。
Webhook（实时）
服务设置页会给出当前实例的 Webhook 地址，一般是：
http://<Bonita地址>:12346/api/v1/webhooks/emby在 Emby：控制台 → 通知 → 添加通知 → Webhooks，把上面的 URL 填进去。
建议勾选这些事件：
| Emby 事件 | Bonita 行为 |
|---|---|
| Playback（播放结束 / scrobble） | 同步观看进度；播完则标已看 |
| Mark Played | 标记已看 |
| Mark Unplayed | 标记未看 |
| Rate（收藏） | 同步收藏 / 取消收藏 |
| New Media Added | 新媒体入库时建立对应媒体项 |
Emby 和 Bonita 不在同一台机器时，不要用 localhost，改成 Bonita 的局域网 IP 或主机名。
Webhook 适合日常即时同步。漏掉的事件靠下面的全量同步补上。
全量同步
两条路径：
- 定时任务：默认每 900 秒（15 分钟）从已启用的 Emby 拉一次。间隔由环境变量 /
config.yaml的WATCH_HISTORY_SYNC_INTERVAL控制 - 手动：打开 工具 → 同步 Emby 观看历史
同步方向：
- 从服务器拉取（默认）— Emby → Bonita。默认不覆盖 Bonita 里已经记下的已看 / 收藏；要覆盖就勾选强制更新
- 回写到服务器 — Bonita → Emby，覆盖电影、剧集、番号视频。取消已看 / 取消收藏同样需要强制更新
把旧 Emby 迁到新 Emby 时可以：
- 旧服务器记录同步进 Bonita
- 新服务器片库刮削 / 入库一次，让路径或番号对得上
- 再从 Bonita 回写到新服务器
媒体项
媒体项 是同步结果的本地视图，支持按类型、观看、收藏、番号筛选，也可以手动增改。
匹配大致按这个顺序：转移记录的目标路径（对应 Emby 条目路径）、IMDB/TMDB/TVDB、番号。所以：
- 输出目录尽量就是 Emby 在扫的那套文件
- 番号片依赖刮削或记录里的番号
- 对不上的视频仍会作为无关联条目建出来，之后可以再改
页面上的 清理重复项 用来合并重复媒体项。
合集
合集以 Bonita 为准。流程：
- 点 添加要同步的合集，搜索 Emby 里的 BoxSet，加入列表（加入时会拉一次成员）
- 从服务器拉取 — 只增加 Emby 里有、本地还没有的成员，不会在 Bonita 里删除
- 在 Bonita 里添加或移除成员（媒体项本身不会被删）
- 回写服务器 — 把当前成员列表推到 Emby；这时才会在 Emby 合集里去掉你删掉的项
还没有加入同步列表的合集不会被改动。