故障排查

Web UI 无法访问

检查容器是否运行，端口 5257 是否映射。
查看容器日志确认 Web 服务是否启动成功。

Webhook 无响应

确认 Emby Webhook 地址为 http://<服务器IP>:5257/webhook/emby。
检查 Emby 事件类型是否勾选。

反向代理无虚拟库

确认虚拟库已启用。
检查端口是否映射。
查看启动日志是否生成 Nginx 配置。

任务不执行

任务链开关是否开启。
Cron 表达式是否合法。
同一时间只能执行一个后台任务。

全量生成 STRM 时 Emby 大量入库通知

先检查 Emby 媒体库是否开启了实时监控，以及是否开启了 NFO 读取。

ETK 全量生成 STRM 时会暂停自己的实时监控队列，但无法拦截 Emby 自己监听文件系统。如果 Emby 直接监听 STRM 目录，.strm 文件生成或覆盖会绕过 ETK，直接触发大量 Emby 扫描。

处理方式：

关闭 Emby 媒体库实时监控，尤其是 STRM 媒体库。
开启 Emby 的 NFO 读取，让 Emby 优先读取 ETK 生成的本地元数据。
让 ETK 全量处理完统一触发 Emby 扫描。
全量同步、洗版、批量整理期间不要让 Emby 自己抢先扫描目录。

元数据补全异常

TMDb API Key 是否正确。
豆瓣 Cookie 是否配置（如遇登录限制）。
网络代理是否可用。

中心资源库搜不到资源

先确认共享资源中心已启用。
执行一次 共享资源维护。
检查本地资源是否已经入库，并且有 TMDb ID。
电影按 TMDb ID 聚合，同一部电影只显示一张卡。
剧集按剧名聚合，进入详情页后再切换季。

电影详情里资源重复

正常情况下，同一 SHA1 只应该显示一个资源。

如果看到重复：

先刷新页面。
执行共享资源维护。
如果仍然重复，可能是中心端聚合数据未更新，需要等待中心维护或反馈给管理员。

秒传一直排队

同一个资源不会短时间高频派发签名任务，这是为了避免触发 115 风控。
如果提供签名的设备离线，需要等待其他可用设备。
有 115 分享的资源可以优先使用转存。

贡献点明细标题显示为横线

贡献点明细会尽量从资源记录和历史事件中补标题。

如果仍然显示 -：

可能是很旧的历史记录，中心端已经没有可用标题来源。
新产生的秒传、转存和求共享流水通常会显示影片或剧名。

纯净版或短剧标签不正确

纯净版和短剧判断依赖 TMDb 集时长和视频物理时长。
动漫不会参与短剧和纯净版判断。
刚入库的资源可能需要执行共享维护补齐元数据。