WinBoat 启动失败排查：3 分钟定位根因，让 Linux 上的 Windows 应用重新跑起来

WinBoat 启动失败排查3 分钟定位根因让 Linux 上的 Windows 应用重新跑起来【免费下载链接】winboatRun Windows apps on Linux with ✨ seamless integration项目地址: https://gitcode.com/GitHub_Trending/wi/winboatWinBoat 在 Linux 上启动失败时整个 Windows 应用环境都会瘫痪。WinBoat 用容器加虚拟机在 Linux 里跑 Windows并把应用集成为原生窗口链路长任何一环出错都有痕迹。按症状→链路→分档三步做 WinBoat 启动故障排查3 分钟定位到根因。症状速查30 秒匹配故障位置打开 WinBoat 界面或直接敲命令先对号入座故障现象最可能原因先查哪里容器状态 Exited点击启动无反应Docker 守护进程未启动或用户不在 docker 组运行docker ps看是否报权限错误容器 Running但界面显示 Guest API - Offline容器内 Guest Server 未装完或已崩溃访问 127.0.0.1:47271 的 health 接口compose up 报端口已被分配47270–47274 主机端口被占用用ss -ltnp找占用进程启动报错含 no such file or directory 或 no such device容器引用了已拔出的 USB 设备属于陈旧容器直接重建容器安装卡在 Creating OEM AssetsGuest Server 资源文件不完整查看 install.log首次安装在预检阶段失败内存/CPU 不达标或 KVM 未开启运行free -h、ls /dev/kvm 按启动链路定位根因WinBoat 的启动是一条固定链路依赖服务 → 配置文件 → 端口与资源 → 容器与 Guest Server。按顺序排查某一步症状对上就停在那修。依赖服务Docker、KVM、用户组各查一遍确认问题出在这一步docker ps报 permission denied → 用户不在 docker 组docker ps报连接失败 → 守护进程没起ls /dev/kvm无输出 → KVM 没开应用界面预检不过 → 上面任一项或 FreeRDP 版本低于 3.x对应的修法守护进程没起sudo systemctl start docker再执行sudo systemctl enable docker保证开机自启权限问题把用户加进 docker 组重新登录后再启动KVM 缺失进 BIOS/UEFI 打开虚拟化Intel 找 VT-xAMD 找 SVM注意官方明确不支持 Docker Desktop用 Podman 的话版本必须是 4.x读 Compose 文件找到配置文件并重新生成确认问题出在这一步文件默认在~/.local/share/winboat-app/docker-compose.yml文件缺失或 compose up 报 YAML 解析错误 → 就是这里配合看同目录的 install.log能确认安装流程卡在哪一个状态对应的修法删掉这个文件重新打开 WinBoat 走安装流程。安装器会自动重写 compose、OEM 资产和 guest token整套生成逻辑在 src/renderer/lib/install.ts。如果文件还在、只是容器被手动删了WinBoat 检测到存储文件夹里有磁盘镜像data.img 或 qcow2时会自动用旧 compose 把容器重建回来不用重装 Windows。端口被占与资源不足一步找到占用进程确认问题出在这一步docker compose up的报错含 port is already allocated或系统明显带不动虚拟机。WinBoat 在 127.0.0.1 上占用的端口主机端口容器内端口用途472708006noVNC 网页界面472717148Guest Server API健康检查走这里472727149QEMU QMP472733389RDPtcp 与 udp472747150Guest Server 更新器端口定义见 src/renderer/lib/constants.ts。对应的修法ss -ltnp | grep -E 47270|47271|47272|47273|47274找到占用进程后结束它。资源门槛是 4GB 内存、2 个 CPU 核心、32GB 可用磁盘用free -h和df -h核对装 Windows 的磁盘不足就清空间或换分区。容器起不来重启、看日志还是重建确认问题出在这一步docker ps -a --filter nameWinBoat看真实状态状态 Exited → 看日志docker logs WinBoat启动报错含 no such file or directory 或 no such device or address → 陈旧容器典型成因是 USB 直通设备被拔掉旧容器还引用着它容器 Running 但 Guest API 一直 Offline → 首次安装还在进行需要几十分钟或 Guest Server 崩溃对应的修法普通起不来docker restart WinBoat再看日志陈旧容器docker rm WinBoat后用原 compose 文件执行docker compose up -d重建。应用内的启动按钮其实会自动识别这类错误并触发重建手动操作只是等价路径健康判定curl -I http://127.0.0.1:47271/health返回 200 即 Guest Server 在线看到 WinBoat Guest API - Online 与 Container - Running 同时出现链路就算全通了。 分档解决方案从快速恢复到彻底重置同一故障按代价从小到大处理先用第一档不行再升级。第一档2 分钟内先试在 WinBoat 界面停止再启动一次容器运行curl -I http://127.0.0.1:47271/health确认是否 200打开~/.local/share/winboat-app/install.log读最后十几行第二档深度修复10–30 分钟删除并重新生成 compose 文件链路第 2 步释放被占端口补齐缺失依赖KVM、docker 组、FreeRDP 3.x删除容器后按原 compose 重建绕开陈旧状态第三档最后手段——重置重装WinBoat 内置重置流程停止容器 → 删除容器 → 删除存储文件夹 → 清空~/.local/share/winboat-app。之后重新走一遍安装生成 compose → 写入 OEM 资产 → 启动容器 → 监控预安装 → 等 Guest API 健康检查通过。会重新装 Windows数据先备份。防再犯自查清单5 件事做完不回头☑ Docker 守护进程已设为开机自启不要用 Docker Desktop☑ 用户在 docker 组里加组后重新登录过☑ 没有第三方程序长期占用 127.0.0.1 的 47270–47274☑ 安装磁盘剩余空间不低于 32GB☑ 运行中不拔直通 USB真要拔之后用重建容器而不是硬启动☑ WinBoat 与 Guest Server 版本保持同步应用上线时会自动比对并推送更新仍卡住时先导出 install.log 和 container.log 里的完整报错再去项目仓库开 Issue 或到官方社区提问。附上日志比口头描述定位快得多。【免费下载链接】winboatRun Windows apps on Linux with ✨ seamless integration项目地址: https://gitcode.com/GitHub_Trending/wi/winboat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考