Multipass错误代码大全：常见问题快速解决方案
项目地址: https://gitcode.com/gh_mirrors/mu/multipass 概述
Multipass是一款轻量级虚拟机编排工具，用于快速创建和管理Ubuntu实例。在使用过程中，用户可能会遇到各种错误代码和异常情况。本文汇总了Multipass常见错误场景及解决方案，帮助用户快速定位并解决问题。官方故障排除文档：docs/how-to-guides/troubleshoot/index.md
启动与初始化错误
镜像下载验证失败
错误场景：multipass launch命令失败，提示"Downloaded image hash does not match"。
解决方案：执行multipass find --force-update强制更新镜像缓存，或删除网络缓存目录后重启服务：
# Linux
sudo snap stop multipass
sudo rm -rf /var/snap/multipass/common/cache/multipassd/network-cache/
sudo snap start multipass
# macOS
sudo launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist
sudo rm -rf /System/Volumes/Data/private/var/root/Library/Caches/multipassd/network-cache
sudo launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist
相关文档：docs/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md
实例启动超时
错误场景：启动实例时卡在"Waiting for initialisation to complete"。
解决方案：
- 延长超时时间：
multipass launch --timeout 1000 - 检查cloud-init日志：
multipass shell <实例名> -- tail -f /var/log/cloud-init.log - 验证SSH连接：确保实例已获取IP且SSH服务正常运行
网络连接错误
IP地址获取失败
错误场景：Unable to determine IP address错误。
解决方案：
- 检查防火墙设置，确保允许bootpd服务：
# macOS特有
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd
- 检查DHCP流量：
# Linux
sudo tcpdump -i mpqemubr0 udp port 67 and 68
# macOS
sudo tcpdump -i bridge100 udp port 67 and 68
相关文档：docs/how-to-guides/troubleshoot/troubleshoot-networking.md
DNS解析失败
错误场景：实例内无法解析域名，但可ping通IP。
解决方案：
- 手动配置DNS：
echo "nameserver 1.1.1.1" | multipass exec <实例名> -- sudo tee -a /etc/resolv.conf - 检查主机端口占用：
# 确保只有mDNSResponder监听53端口
sudo lsof -iTCP:53 -iUDP:53 -n -P
存储与文件系统错误
镜像文件损坏
错误场景：实例启动失败，控制台显示文件系统错误。
解决方案：
- 使用qemu-img检查镜像：
# macOS示例路径
/Library/Application\ Support/com.canonical.multipass/bin/qemu-img check -r /var/root/Library/Application\ Support/multipassd/qemu/vault/instances/<实例名>/ubuntu-22.04-server-cloudimg-arm64.img
- 运行fsck修复文件系统：
# 通过GRUB进入恢复模式后执行
fsck -f /dev/sda1
相关文档：docs/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md
高级故障排除
查看详细日志
操作步骤：
# Linux
journalctl --unit snap.multipass.multipassd.service -f
# macOS
tail -f /Library/Logs/Multipass/multipassd.log
# Windows
Get-Content "C:\ProgramData\Multipass\Logs\multipassd.log" -Wait
恢复实例数据
当实例无法启动时，可通过以下步骤挂载镜像恢复数据：
-
定位实例镜像：
- Linux:
/root/.local/share/multipassd/vault/instances/<实例名>/ - macOS:
/var/root/Library/Application Support/multipassd/qemu/vault/instances/<实例名>/ - Windows:
C:\ProgramData\Multipass\data\vault\instances\<实例名>\
- Linux:
-
使用qemu-nbd挂载镜像：
sudo modprobe nbd
sudo qemu-nbd --connect=/dev/nbd0 <镜像路径>
sudo mount /dev/nbd0p1 /mnt
错误代码速查表
| 错误场景 | 可能原因 | 解决方案 |
|---|---|---|
| 镜像哈希不匹配 | 缓存损坏 | multipass find --force-update |
| IP获取失败 | DHCP服务异常 | 检查bootpd和防火墙设置 |
| SSH连接拒绝 | 密钥或用户配置错误 | 验证cloud-init用户配置 |
| 启动超时 | cloud-init未完成 | 延长超时或检查cloud-init日志 |
项目仓库地址：https://gitcode.com/gh_mirrors/mu/multipass
官方文档：docs/index.md
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
