应用与运行环境
排查 Hanafubuki 启动、应用 Python、Micromamba、Git 和更新问题。
Hanafubuki 的应用运行环境用于执行管理能力，与每个 WebUI 实例自己的 Python 和 Core 相互独立。先判断失败的是应用级运行时，还是某个实例内部依赖。
判断是否属于应用层
通常属于应用层的现象：
- 应用打开后一直停留在运行环境准备阶段。
- 首页提示应用 Python、Micromamba 或 Git 准备失败。
- 所有实例的安装和管理能力都同时不可用。
- 设置或实例列表无法读取，但尚未开始具体 WebUI 任务。
- 应用更新下载、安装或重启失败。
如果只有一个实例启动时报 ModuleNotFoundError、CUDA 或扩展错误，通常应改查实例环境，而不是应用 Python。
运行环境准备失败
不要从其他安装包复制 Python、Micromamba、Conda 或 Launcher Code 覆盖受管目录。应用会校验自己的组件集合，手动替换可能产生新的完整性错误。
应用 Python 或 Git 切换后无变化
应用 Python 版本和 Git 来源在下次启动生效：
- 等待正在运行的安装、管理和 Agent 任务结束。
- 保存新的版本或来源。
- 正常退出所有 Hanafubuki 窗口。
- 重新启动后返回运行环境页核对实际路径和版本。
修改这些设置不会重装实例 Python，也不会修复某个 WebUI 扩展的依赖。
Windows SmartScreen 阻止应用启动
当前 Windows 安装包与便携版尚未签名。首次启动安装程序、免安装版或 Launcher 时，如果系统显示 Windows 已保护你的电脑。Microsoft Defender SmartScreen 阻止了无法识别的应用启动。运行此应用可能会导致你的电脑存在风险。，请确认文件来自本站，然后点击“更多信息”，再点击“仍然运行”。
“仍然运行”只会在展开“更多信息”后显示。只对从本站下载并核对过名称与平台的文件执行此操作；第三方转载或来源不明的文件应删除并重新下载。
macOS 提示应用已损坏
当前 macOS 安装包与便携版尚未签名。首次打开时如果系统提示 “Hanafubuki” is damaged and can't be opened 或 “Hanafubuki Launcher” is damaged and can't be opened，请不要移到废纸篓。确认文件来自本站后，按照安装 Hanafubuki 的 macOS 步骤对相应 .app 执行 xattr -dr com.apple.quarantine，然后重新打开。
只对从本站下载并核对过名称与平台的应用移除隔离属性；第三方转载或来源不明的文件应删除并重新下载。
应用界面或窗口异常
应用仍能操作时，先记录出现异常的页面并正常重启。若异常只发生在嵌入式 WebUI，先尝试从“实例信息”使用捕获地址在外部浏览器打开，以区分 WebUI 页面问题和应用窗口呈现问题。
窗口无法打开、持续白屏或启动即退出时：
- 记录操作系统、Hanafubuki 版本和发生时间。
- 检查应用日志与操作系统崩溃记录。
- 不要先删除应用数据目录；其中包含实例记录、设置和诊断材料。
- 使用应用诊断包向 Hanafubuki 维护者报告，而不是向 WebUI 扩展作者报告。
更新失败
| 阶段 | 优先检查 |
|---|---|
| 无法检查更新 | 网络、代理、系统时间和更新源可达性 |
| 下载失败 | 任务输出、磁盘空间、临时目录和安全软件 |
| 安装包打不开 | 平台和架构是否正确、文件是否完整、系统安全提示 |
| 重启后仍是旧版本 | 是否真正完成安装、启动的是否为旧位置副本 |
更新失败不应通过删除实例目录处理。应用安装位置和实例根目录是两个不同范围。
仍无法恢复
生成应用诊断包，并附上启动失败阶段、运行环境页截图、应用日志和近期改动。若应用完全无法进入设置页，保留现有应用数据，不做覆盖安装以外的清理，先向维护者确认需要哪些文件。