故障排查

Web UI 无法访问

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

前端白屏或静态文件异常

先强制刷新浏览器并确认打开的是当前 ETKN 地址。如果是刚更新容器，检查 /app/static 下目录为 755、文件为 644，并确认 /assets/index-*.js 返回 JavaScript MIME，而不是 HTML。

任务显示成功但没有入库

“生成 STRM”或“资源转存成功”不等于核心入库结束。打开任务中心的根任务详情，继续检查识别、整理、元数据、媒体信息和内置媒体服务刷新等后续步骤。整理记录可以确认最终入库方式和处理结果。

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

剧集通常以剧名/季度作为根任务，分集是根任务内部的处理项。先查看任务详情中的后代项，不要因为列表看起来分散就重复提交同一季度。

Telegram 没有收到通知或 Bot 不响应

• 确认 Bot Token 已保存且没有失效。
• 确认全局 Chat ID，或管理员账号的 Telegram ID 已填写。
• 确认机器人已加入群组/频道并有发消息权限。
• 确认对应通知类型已勾选。
• Bot 轮询和频道监听是两套配置，Bot 正常不代表频道监听已经登录。

共享池、re0 或 MoviePilot 资源没有继续整理

先确认资源获取任务是否创建了后续整理任务，再检查来源状态、115 目录同步状态和任务链日志。MoviePilot 报告下载或转移完成，只说明外部环节结束，不代表 ETKN 已经完成入库。

虚拟媒体库打不开或无法播放

• 确认 8097 已映射或已通过反向代理发布。
• 确认客户端填写的是 ETKN 可访问地址，而不是容器内地址。
• 确认当前用户有该虚拟媒体库的访问权限。
• 远程资源需要先解析为客户端可访问的直链；ETKN 不按客户端 UA 或 Range 请求自动长时间中转远程视频。

识别到错误片名或分类

在任务中心查看识别诊断，确认文件名、父目录、规则和 MoviePilot 辅助结果。需要人工修正时，从整理记录进入纠错或重组，不要直接重复提交整批资源。

洗版后残留旧文件或空目录

先打开整理记录确认替换和清理事件是否成功。历史残留不会因为一次普通刷新自动批量删除；涉及物理文件删除时，先确认目标路径和版本，再执行明确的清理操作。

仍然无法判断

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