moviepilot doctor 是 MoviePilot 的离线诊断与自救入口，适合 WebUI、后端 API、Agent 或插件都不可用时使用。
它不会调用 MoviePilot 后端 API，而是直接检查本地配置、运行时文件、进程、端口、日志、依赖、数据库、前端资源和 Docker 环境。提交 Issue 前，也可以先用 doctor 收集诊断信息，减少来回补充日志的成本。
如果页面打不开、后端无法启动、插件导致启动异常，优先执行
moviepilot doctor查看诊断结果；需要提交 Issue 时建议附带 doctor 摘要。
moviepilot doctor
moviepilot doctor --json
moviepilot doctor --fix
安全模式启动：
moviepilot start --safe
如果容器仍在运行，或已经进入诊断保活状态：
docker exec -it <container> moviepilot doctor
docker exec -it <container> moviepilot doctor --json
docker exec -it <container> moviepilot doctor --fix
使用 Docker Compose 时，也可以进入对应服务执行：
docker compose exec <service> moviepilot doctor
其中 <container> 是容器名或容器 ID，<service> 是 compose 文件中的服务名。
如果容器已经完全退出，可以用同一个镜像临时挂载配置目录运行 doctor：
docker run --rm --entrypoint python -v <config-dir>:/config <image> -m app.cli doctor
其中 <config-dir> 是宿主机上的 MoviePilot 配置目录，<image> 是当前使用的 MoviePilot 镜像。
moviepilot doctor --json
moviepilot doctor --fix
moviepilot doctor --deep
--json：输出结构化诊断结果，适合保存、上报或交给 Issue 反馈流程使用--fix：在白名单范围内执行安全修复--deep：执行更深入的检查，可能会比默认诊断慢一些Doctor 默认执行只读检查，主要包括：
API_TOKEN、PORT、NGINX_PORT、代理格式、安全模式version.txt、service.js 或核心静态文件是否存在/config、虚拟环境和容器内 moviepilot 命令是否可用--deep 会启用可能较慢或更依赖当前网络、数据库环境的检查，例如 PostgreSQL TCP 连通性。
moviepilot doctor --fix 只做白名单安全修复，避免误伤用户数据。
当前主要修复范围：
API_TOKEN 生成合规值Doctor 不会自动删除数据库、修改 Docker Compose、回滚迁移、批量禁用插件或删除用户数据。遇到需要人工确认的风险操作时，它只会给出处理建议。
moviepilot start --safe 或 MOVIEPILOT_SAFE_MODE=true 会在本次启动中跳过：
安全模式不修改用户配置，适合插件、调度任务或 Agent 导致后端无法启动时先恢复后台入口。修复问题后，移除 MOVIEPILOT_SAFE_MODE=true 或使用普通 moviepilot start 重启即可恢复完整能力。
Docker 环境建议临时添加环境变量后重启容器：
MOVIEPILOT_SAFE_MODE=true
Docker 镜像默认启用：
MOVIEPILOT_DOCKER_KEEPALIVE_ON_FAILURE=true
当后端主进程非正常退出时，entrypoint 不会立刻退出容器，而是打印一次 doctor 报告并保持容器运行，方便继续执行：
docker exec -it <container> moviepilot doctor
通过前端内建重启、系统内置重启入口或用户手动触发的正常重启，会被识别为用户意图，不会进入诊断保活，也不会影响原有的内建手动重启流程。
如果需要恢复旧行为，可设置：
MOVIEPILOT_DOCKER_KEEPALIVE_ON_FAILURE=false
Dockerfile 同时提供 HEALTHCHECK，用于标记容器健康状态。是否自动重启仍由 Docker Compose、NAS 平台或 Docker restart policy 决定。
Issue 反馈相关 skill 已支持调用：
moviepilot doctor --json
诊断摘要会写入预览和最终 Issue 正文，完整 doctor JSON 会保存在运行时 diagnostics 文件中，默认不会直接贴入 Issue，避免公开本机路径和过长输出。
公开粘贴诊断结果前，仍建议检查是否包含本机路径、域名、用户名等不希望公开的信息。