troubleshooting

Ludus 故障排除

使用此技能快速诊断用户报告的问题、对错误进行分类，并提供有针对性的修复步骤。

诊断工作流

1. 收集背景信息和完整的错误输出。
2. 检查范围部署状态和近期错误。
3. 查看部署日志，了解故障详情。
4. 使用已知错误目录确定故障类别。
5. 检查当前范围配置是否存在错误配置。
6. 提供包含具体步骤的针对性修复方案。
7. 明确验证步骤，以确认问题已解决。

关键诊断信息

进行诊断时，按以下顺序收集信息：

• 范围状态 — 部署正在运行、已失败还是已完成？
• 部署错误 — 最近一次部署的错误输出。
• 部署日志 — 完整日志流，用于追踪故障背景。
• 模板状态 — 所需模板是否已构建并可用？
• 范围配置 — YAML 是否符合用户的预期？
• 测试模式状态 — 测试模式是否已启用，网络规则是否生效？

常见问题模式

• 网络问题通常与 dnsmasq 或 NAT 网桥状态有关。
• Ansible 故障通常涉及 WinRM（Windows）或 SSH 连通性（Linux）。
• 域加入失败通常与 DNS 顺序或时序有关。
• 模板故障通常与 ISO 下载或磁盘空间有关。

参考资料

• 已知错误、根本原因和修复流程请参阅 references/common-errors.md。
• 客户端和 CLI 故障排除详情请参阅 https://docs.ludus.cloud/docs/troubleshooting/client。
• 网络和连接问题请参阅 https://docs.ludus.cloud/docs/troubleshooting/network/ 和 https://docs.ludus.cloud/docs/troubleshooting/wireguard/。
• 如需卸载 Ludus，请引导用户查阅官方指南 https://docs.ludus.cloud/docs/troubleshooting/uninstall，不要自行执行相关步骤。