故障排查

Web UI 无法访问

• 确认容器 etkn 正在运行。
• 确认管理端口 5257 已映射且没有被旧版 ETK 占用。
• 查看容器日志，确认数据库迁移和 Uvicorn 启动成功。
• 访问 /api/health，正常应返回 {"status":"ok"}。

前端白屏或静态文件 401/HTML

先重启容器并清理浏览器缓存。如果是热更新覆盖静态文件，检查 /app/static 目录为 755、文件为 644，且 /assets/index-*.js 返回 text/javascript。

任务显示成功但没有入库

生成 STRM 不代表核心任务完成。打开任务中心的完整历史日志，确认“刮削元数据、翻译、媒体分析、Emby 扫描、ItemID 校验”都已完成。失败日志只按当前根任务和正式后代链展示。

批量剧集变成一集一个任务

剧集顶层任务应该按剧名/季度展示，分集只是内部处理项。如果列表出现一集一个根任务，先不要重复提交，下载该批任务日志并反馈根任务编号。

TG 通知没有收到

• Bot Token 是否已保存。
• TG 配置中的全局 Chat ID 或管理员个人 Telegram ID 是否填写。
• 机器人是否已加入群组/频道并拥有发消息权限。
• 入库通知类型是否勾选。
• 发版通知使用 GitHub Secrets TELEGRAM_TOKEN 和 TELEGRAM_TO，其中 TELEGRAM_TO 填群组/频道 Chat ID 或 @频道用户名，不是 Bot 用户名。

共享池或影巢转存后没有整理

打开资源获取任务，确认是否创建了后续整理任务。若转存刚完成，115 目录可能仍在同步，旧版逻辑会等待 2/4/6 秒后再扫描，仍不可见时会创建延迟补扫。

虚拟库打不开或播放无兼容流

• 确认端口 8097 已映射。
• 确认 Emby 配置中的虚拟库反代地址和端口正确。
• 确认允许转码配置符合客户端需求。
• 浏览器使用混合库返回，其他客户端按电影/剧集类型返回，这是旧版兼容分流。

识别到错误片名或进入错误分类

查看整理任务的识别诊断，确认文件名、父目录、规则锁定类型和 MoviePilot 辅助结果。新版沿用旧版识别顺序；裸文件没有父目录时不会把“待整理”“115”等合成目录当作片名。

洗版后残留 STRM 或空目录

新的洗版替换会清理旧 STRM 及同名前缀字幕、NFO、图片和 BIF，并回收无媒体的季、剧、年份目录。历史残留不会自动批量删除，可在确认路径后通过整理记录执行重组或清理。

仍然无法判断

请从任务中心下载指定根任务的完整日志，至少包含片名、失败阶段、诊断编号和后续任务号。不要只提供容器最后几行全局日志。