Emby / Jellyfin 媒体库刷新
OStrm 可以在 STRM 任务完成后通知 Emby 或 Jellyfin 刷新媒体库。每个任务都可以独立选择不刷新、刷新全部媒体库，或精确刷新某个媒体库。
工作流程
STRM 任务完成
↓
判断本次是否需要刷新
↓
全部刷新：提交全库扫描请求
指定媒体库：按媒体库 ID 校验并提交目录更新
↓
将刷新结果写入任务通知和日志刷新请求是异步提交给媒体服务器的。OStrm 显示“已提交刷新请求”表示 Emby 或 Jellyfin 已接受请求，不表示媒体服务器已经扫描完全部文件。
使用前准备
请先准备：
- 一台 OStrm 容器能够访问的 Emby 或 Jellyfin 服务器
- 该媒体服务器生成的 API Key
- 已经指向 OStrm STRM 输出目录的媒体库
网络地址
“API 根地址”由 OStrm 后端访问，不是由浏览器访问。多个容器使用同一 Docker Compose 网络时，应填写服务名，例如 http://jellyfin:8096，不要填写只指向 OStrm 容器自身的 localhost。
添加媒体服务器
- 打开「系统设置」。
- 找到「Emby / Jellyfin」。
- 点击「添加服务器」。
- 填写配置并点击「测试连接」。
- 测试成功后点击「保存服务器」。
配置字段
| 字段 | 说明 | 示例 |
|---|---|---|
| 配置名称 | 供任务选择的唯一名称 | 客厅 Jellyfin |
| 类型 | Emby 或 Jellyfin | Jellyfin |
| API 根地址 | 完整的 HTTP/HTTPS API 根路径，不含查询参数 | http://jellyfin:8096 |
| API Key | 媒体服务器生成的访问密钥 | abcdef... |
| 启用此服务器 | 停用后保留配置，但任务不能使用它刷新 | 默认启用 |
常见地址格式：
Jellyfin：http://jellyfin:8096
Emby：http://emby:8096/emby如果媒体服务器配置了反向代理子路径，应把该子路径包含在 API 根地址中。地址末尾的 / 会被自动移除；地址不能包含用户名、密码、查询参数或 URL 片段。
编辑已有服务器时，API Key 留空表示保留原密钥。
连接测试检查什么
连接测试会：
- 读取媒体服务器系统信息和版本。
- 使用当前 API Key 获取媒体库列表。
- 返回服务器名称、版本和媒体库数量。
只有测试成功并能读取媒体库列表后，才建议把服务器分配给任务。
在任务中配置刷新
打开目标任务的「编辑」窗口，在「任务完成后刷新媒体库」中选择刷新范围。
不刷新
默认选项。任务完成后不调用媒体服务器 API，适合由媒体服务器自身定时扫描的场景。
刷新全部媒体库
选择一个媒体服务器后，OStrm 会调用媒体服务器的全库刷新接口。
适合：
- 多个 OStrm 任务共同写入同一组媒体库
- 媒体库目录关系复杂
- 不关心扫描范围，希望配置尽可能简单
全量任务每次完成都会提交刷新。增量任务只有检测到新增、变更、清理或重命名时才提交刷新。
刷新指定媒体库
选择媒体服务器后，OStrm 会实时读取媒体库列表。再选择目标媒体库，任务会同时保存媒体库 ID 和名称快照。
执行时，OStrm 会：
- 再次读取服务器上的媒体库列表。
- 按保存的媒体库 ID 确认目标仍然存在。
- 获取该媒体库的所有目录路径。
- 提交精确的目录更新请求。
系统不会按名称猜测新媒体库，也不会在目标失效时回退为全部刷新，避免意外扫描其他媒体库。
增量与全量任务的刷新时机
| 任务模式 | 刷新条件 |
|---|---|
| 全量 | 任务完成后始终提交刷新 |
| 增量 | 处理了视频、清理了失效 STRM，或发生目录/文件重命名时提交刷新 |
| 增量且无变化 | 跳过刷新，并记录“增量任务没有媒体变化” |
刷新失败不会回滚已经生成的 STRM 文件，但任务通知会标记为“部分完成”，并列出媒体服务器、刷新范围、目标媒体库和失败原因。
配置变化与失效处理
媒体库被删除或重建
编辑任务时，如果服务器连接成功但已保存的媒体库 ID 不再存在，选择框会显示：
⚠️ 已失效：原媒体库名称此时不能继续保存原选择。请重新选择媒体库，或把刷新范围改为“全部”或“不刷新”。
如果只是暂时无法连接服务器，页面会显示“暂时无法验证”，保留原配置，并允许保存其他修改。
媒体服务器被停用
已停用的服务器仍会显示在任务中，但不能保存为启用刷新状态。可以重新启用服务器、选择其他服务器，或关闭刷新。
删除媒体服务器配置
仍被任务引用的媒体服务器不能删除。请先编辑提示中列出的任务，解除引用后再删除。
常见问题
测试连接返回 HTTP 401
API Key 无效、已撤销，或类型选择错误。请在 Emby/Jellyfin 中重新生成 API Key，并确认服务器类型和 API 根地址正确。
无法连接媒体服务器
从 OStrm 容器所在网络检查地址和端口。Docker 部署时优先使用 Compose 服务名；如果媒体服务器位于宿主机或其他设备，请填写 OStrm 容器可以访问的局域网地址。
测试成功但没有媒体库
确认媒体服务器中已经创建媒体库，并且 API Key 具备读取媒体库信息的权限。然后重新测试连接。
精确刷新提示媒体库没有目录路径
目标媒体库没有返回可刷新的 Locations。请检查媒体服务器中的媒体库目录配置，或者临时改用“刷新全部媒体库”。
如何确认刷新是否触发
启用 任务通知 后，通知会显示媒体服务器、刷新范围、目标媒体库和刷新结果；也可以在 OStrm 日志及媒体服务器日志中核对请求。