故障排查
先判断错误发生在哪一层，再进入对应的处理步骤。
排查问题时，最重要的是先确定失败发生在 Hanafubuki、安装环境、实例启动，还是已经运行的 WebUI 内部。不同层级使用的日志、重试方式和求助对象都不相同。
不要连续点击重试
取消、停止和清理都需要后端确认终态。旧任务仍在运行或等待清理时反复重试，可能继续占用实例、端口或文件，并让新的日志覆盖真正的首次错误。
五分钟排查流程
停止重复操作
不要继续启动、安装或删除。记录当前页面、实例名称、发生时间和刚才执行的操作。
找到第一个失败任务
先展开当前页面右下角的状态项，再打开标题栏任务中心。选择最早出现失败的相关任务，而不是只看后续连带失败。
保存完整错误
复制任务输出或终端日志。保留错误前后的上下文、Python traceback 最后一段和命令退出状态，不要只截取一句错误标题。
判断错误归属
根据下面的“发生位置”表进入对应专题。一次只修改一个相关设置，然后执行同一个操作验证。
仍无法解决时收集诊断
复现后生成实例或应用诊断包。分享前解压检查并脱敏，同时附上复现步骤、版本和完整日志。
错误发生在哪一层
| 现象 | 通常属于 | 下一步 |
|---|---|---|
| Hanafubuki 无法正常打开，或应用 Python、Micromamba、Git 未就绪 | 应用运行环境 | 应用与运行环境 |
| Python/Core 安装、下载、解压或校验失败 | 安装、网络或存储 | 安装与网络 |
| 点击启动后进程退出、没有地址、端口冲突或页面无法打开 | 实例启动 | 实例启动与访问 |
| 已经打开 WebUI，但生成、模型、扩展、节点或工作流报错 | WebUI 上游 | WebUI 上游问题 |
| 页面提示任务占用、等待清理、维护锁或无法确认进程结束 | 任务生命周期 | 任务占用与清理 |
| 不知道应提供哪些日志，或者需要向维护者求助 | 信息收集 | 日志、诊断与求助 |
| Agent 模型请求或 MCP 连接失败 | Agent 配置 | 提供商与模型 / MCP |
如何判断 WebUI 是否已经启动
以下信息说明问题已经越过安装阶段：
- 实例工作区显示 WebUI 启动任务，而不是 Python/Core 安装任务。
- “实例信息”中可以看到 WebUI 运行阶段或捕获到的地址。
- 浏览器或嵌入页面已经打开 WebUI 界面。
- 错误出现在点击生成、加载模型、运行节点、使用扩展或执行工作流之后。
如果 WebUI 地址可以访问，但页面内部功能失败，应优先查 WebUI、扩展和模型，而不是重装 Hanafubuki 的应用运行环境。
先看错误，再决定动作
| 关键词或状态 | 优先含义 |
|---|---|
connection、timeout、DNS、SSL | 网络、代理、镜像或目标服务 |
No module named、ImportError | 实例依赖或扩展依赖，不是应用 Python 本身 |
| CUDA、Torch、显卡不可用 | 驱动与实例 PyTorch 组合 |
address already in use | 启动端口已被其他进程占用 |
No such file、拒绝访问 | 路径、文件是否存在、权限或安全软件占用 |
| 等待清理、cleanup、maintenance | 原任务尚未释放资源，应继续原操作的清理流程 |
错误关键词只能用于确定排查方向，不能代替完整日志。同一个 ImportError 可能来自 Core、扩展或用户脚本，需要通过 traceback 中的实际文件路径区分。
什么时候不要继续尝试
- 删除、迁移或重装页面仍显示待恢复或待清理。
- 任务中心仍有同一实例的安装、启动、终端或管理任务运行。
- 磁盘出现 I/O 错误、文件系统只读或空间接近耗尽。
- 准备执行删除、Git 重置、批量卸载依赖等不可逆操作，但尚未创建快照和备份。
- 解决方案来自其他启动器或不同 WebUI 类型，尚未确认路径和操作在 Hanafubuki 中的对应关系。