实例启动与访问
排查 WebUI 进程退出、启动参数、端口、地址和页面访问问题。
启动问题需要区分三个阶段：进程是否创建、WebUI 是否完成初始化、应用是否捕获到可访问地址。看到“正在启动”不代表 WebUI 已经就绪。
阅读启动状态
进入实例工作区查看启动接管页面，或在“实例信息”中查看实时启动阶段、警告、捕获地址和最近失败。
| 现象 | 说明 |
|---|---|
| 启动任务立即失败 | 参数校验、Python、Core、依赖或进程创建失败 |
| 日志持续输出但没有地址 | WebUI 仍在加载模型/扩展，或没有输出可识别的监听地址 |
| 进程退出并有 Python traceback | Core、扩展、依赖或 PyTorch 在初始化时失败 |
| 已捕获地址但嵌入页面打不开 | 地址监听、浏览器呈现、代理或 WebView 问题 |
| 外部浏览器可以打开 | WebUI 本身已运行，重点检查嵌入呈现而不是重装实例 |
启动后立即退出
展开启动日志，找到进程退出前第一段完整异常。
检查 traceback 路径属于 WebUI Core、某个扩展还是 Python 包。
核对最近修改的启动参数、环境变量、Core 版本、扩展和 PyTorch。
只撤销一项最近改动后重试；需要大范围调整前先创建快照。
仍失败时收集实例诊断包，并保留失败启动活动。
如果日志明确来自某个扩展，先禁用、更新或回退该扩展；如果来自 Core 与扩展接口不兼容，应同时核对两者版本。不要先卸载所有 Python 包，这会破坏进一步定位所需的环境。
启动参数和环境变量
- 在“启动”页检查原始参数解析错误、未知参数和互斥选项。
- 原始参数只填写传给 WebUI 的内容，不包含 Python 或启动脚本。
- “仅本次忽略”只适合确认当前分支仍接受该参数，不应长期跳过同一警告。
- 修改参数或环境变量后必须重新启动 WebUI，刷新页面不会改变已运行进程。
- 不要用自定义
PATH、PYTHONPATH、MAMBA_*或CONDA_*覆盖受管环境。
端口和地址
出现端口占用或无法连接时：
- 从启动日志确认实际监听地址和端口，不要只假设为
7860。 - 使用任务中心和系统工具确认是否有旧 WebUI 或其他服务占用端口。
- 旧任务属于 Hanafubuki 时，先完成原任务停止和清理，不要直接杀进程后立即重启。
- 需要改端口时在实例启动参数中使用当前 WebUI 支持的端口选项。
- 重启后确认日志、捕获地址和浏览器打开的端口一致。
监听 127.0.0.1 通常只允许本机访问；监听所有网卡或开放远程连接会扩大安全边界。不要为了排查本地页面而无条件开启远程访问。
有地址但页面打不开
依次检查：
- WebUI 进程是否仍在运行，而不是启动后立刻退出。
- 地址中的协议、主机和端口是否与日志一致。
- 使用系统浏览器打开捕获地址，区分 WebUI 服务和嵌入 WebView。
- 浏览器代理、翻译扩展、缓存或安全软件是否修改了本地页面请求。
- WebUI 是否配置了认证、子路径或仅允许特定主机访问。
页面能打开但生成、模型或节点失败时，启动已经成功，应转到 WebUI 上游问题。
管理功能暂不可用
实例管理能力可能在 WebUI 尚未准备、管理 API 恢复中、维护操作占用或旧任务未清理时暂不可用。先查看“实例信息”的管理 API 和运行状态，等待恢复或使用界面提供的重试。维护页仍可用于查看和恢复实例生命周期操作。