安装与网络
排查 WebUI 安装、下载、代理、镜像、磁盘和路径问题。
安装会依次准备实例 Python、Core、依赖和可选资源。进度百分比按阶段计算，不代表下载字节；某个阶段停留较久时应先确认日志是否仍在输出。
先定位失败阶段
在安装工作区展开日志，记录当前阶段和最后一条正常输出。
从第一次出现
error、异常或非零退出的位置开始阅读，不只看最终“安装失败”。在任务中心打开同一安装活动，复制保留输出；看到截断标记时尽快保存现场。
按下面的错误类型只修改一个相关设置，再重试同一个安装操作。
网络、代理和镜像
| 现象 | 优先检查 |
|---|---|
| 连接超时、重置、DNS 失败 | 当前网络、代理模式、代理端口、防火墙 |
| SSL 或证书错误 | 系统时间、HTTPS 检查软件、代理方式和目标证书 |
| 只有 GitHub/Hugging Face/PyPI 失败 | 对应镜像或目标站点是否可用 |
| 文件校验或大小不一致 | 镜像缓存、下载中断；切回官方来源重新获取 |
| 返回 401/403 | 地址是否需要认证、Token 权限、限流或地区策略 |
代理决定“怎样连接”，镜像决定“连接哪个来源”。先验证代理和直连差异，再调整对应镜像；同时修改多项会让结果无法判断。
修改代理后，已经启动的安装子进程仍保留旧环境。先让旧任务进入失败、取消或完成终态，再重新创建任务。
路径、权限和磁盘
- 实例根目录应使用独立、可写且不会与其他实例重叠的目录。
- 路径不存在、包含危险重叠、经过符号链接或目标已有冲突文件时，按界面提示选择新目录。
- 检查系统盘和实例所在磁盘；Python 包安装和解压可能还会使用临时空间。
- 遇到拒绝访问时检查文件是否被 WebUI、终端、编辑器、安全软件或另一个应用进程占用。
- 不要为了通过校验而关闭完整性检查或手动合并不明来源文件。
依赖和 PyTorch 安装失败
No module named、编译失败或包版本冲突通常来自实例环境：
- 记录具体包名、要求版本和最早的安装错误。
- 确认安装选项与当前 WebUI 类型和操作系统匹配。
- PyTorch 失败时恢复“自动”或类型默认选项，并核对显卡驱动。
- 扩展依赖失败时先确认是可选扩展，不要立即重建整个 Core。
- 确需手动处理时使用实例终端，并在操作前创建快照。
取消、清理和重试
取消只是请求。点击取消后等待任务进入“已取消”或明确失败；只有界面出现“重试进程清理”时才执行清理。清理完成后再“重试安装”，不要同时创建同路径的新实例。
若实例记录已保存但任务尚未启动，重新打开该实例并点击“开始安装”，不需要删除记录或重新创建同名实例。
不要把 WebUI 内部错误当作安装错误
安装完成并已经获得 WebUI 地址后，模型、扩展、节点和生成错误应进入 WebUI 上游问题，而不是反复重装应用运行环境。