1. 为什么值得花时间搞懂 QMP很多人用 QEMU 的方式就是敲一行命令把虚拟机拉起来然后就不管了。机器能跑就行至于运行过程中想临时改个配置、热插拔一块盘、查一下当前块设备的 IO 状态第一反应往往是关机改参数重启。这种玩法在实验环境里没问题但一旦涉及长时间运行的服务、需要在线迁移的场景或者要写自动化脚本批量管理几十台虚拟机靠命令行参数那一套就彻底不够用了。QMP全称 QEMU Machine Protocol就是为解决这类问题而生的。它是 QEMU 对外暴露的一套基于 JSON 的控制接口跑在一个独立的 socket 通道上你可以把它理解成 QEMU 的遥控器。通过它你能在虚拟机运行期间查询状态、修改配置、触发事件、执行热插拔甚至配合 QAPI 做类型安全的自动化编排。关键词里的 QMP、QEMU、Machine Protocol、JSON、QAPI 这几个词基本就勾勒出了它的全貌一套用 JSON 承载的、由 QAPI 定义 schema 的机器管理协议。这篇文章适合三类人看。第一类是刚接触 QEMU、只会用命令行启动虚拟机的朋友想往自动化方向走一步第二类是做虚拟化平台或云管系统的开发者需要把 QEMU 纳入自己的调度体系第三类是做嵌入式模拟、需要在运行时动态调整设备状态的工程师。不管你属于哪一类读完应该都能自己动手把 QMP 通道跑起来并且知道遇到问题该往哪个方向排查。我自己的经验是QMP 这东西入门门槛不高但坑都藏在细节里。比如握手顺序搞错、socket 权限没配对、事件监听没开导致状态不同步这些在文档里往往一笔带过实际踩上去却能耗掉半天。所以下面我会把原理讲清楚的同时重点把那些文档不写但实际会撞上的地方拎出来说。2. QMP 的通信骨架从 socket 到 JSON 消息2.1 一条命令的完整生命周期QMP 的通信模型其实很朴素客户端连上 QEMU 监听的 socket双方用一行一个 JSON 对象的方式对话。注意这里的关键词是一行一个也就是每条消息必须以换行符结尾解析器是按行读的。这一点看起来不起眼但如果你自己写客户端忘了在 JSON 后面补\nQEMU 那边就会一直等表现为命令发出去了但没反应非常容易误判成协议问题。一条命令从发出到拿到结果大致经历这么几个阶段。客户端先发一个 JSON 对象里面至少要有execute字段值是命令名比如query-status。如果这条命令需要参数就再加一个arguments字段值是个对象。QEMU 收到后执行然后回一条 JSON成功的话带return字段失败的话带error字段。整个过程是同步的你发一条它回一条不会串。这里有个容易混淆的点QMP 里有两类消息一类是命令响应一类是事件。命令响应是你主动问、它才答事件是它主动推给你的比如虚拟机状态变化、块设备出错。事件消息里带event字段没有return也没有error。很多新手写客户端时只处理了return结果事件来了解析不了程序直接崩这是很典型的坑。2.2 握手阶段为什么不能跳连接建立之后QEMU 不会立刻接受你的业务命令而是先进入一个协商阶段。它会先发一条greeting消息过来里面包含 QMP 的版本信息、支持的命令能力等。你收到 greeting 之后必须发一条qmp_capabilities命令过去表示我准备好用这套能力了。只有这条命令成功返回后续的业务命令才会被接受。为什么要有这一步因为 QMP 协议是演进的不同版本的 QEMU 支持的命令集不一样。greeting 里的信息让客户端能提前知道自己面对的是哪个版本、有哪些能力可用从而决定后续怎么发命令。qmp_capabilities则是一个显式的确认握手避免客户端在还没搞清楚对方能力的情况下乱发命令。我见过不少人图省事连上 socket 直接发query-status结果收到一个错误说命令不被允许。原因就是跳过了握手。所以记住这个顺序连上 → 收 greeting → 发qmp_capabilities→ 收它的 return → 之后才能发业务命令。2.3 JSON 消息的字段约定QMP 的 JSON 消息结构是有固定约定的理解这几个字段能帮你少走很多弯路。字段出现场景含义execute客户端发命令命令名称如query-statusarguments客户端发命令命令参数对象可选id客户端发命令请求标识响应会原样带回用于匹配return服务端回响应命令执行成功的结果error服务端回响应命令执行失败的错误信息event服务端推事件事件名称如RESETdata服务端推事件事件附带的数据id这个字段值得单独说。QMP 本身是同步的理论上你发一条等一条就行不需要 id 来匹配。但如果你用了异步的客户端框架或者想批量发命令再统一收结果id就派上用场了。响应里会把你的id原样带回来你就能知道这条响应对应的是哪条请求。建议养成习惯发命令时都带上id哪怕当前用不上将来扩展时省事。3. 把 QMP 通道真正跑起来3.1 启动参数怎么配要让 QEMU 暴露 QMP启动时得加参数。最基础的写法是这样qemu-system-x86_64 \ -qmp tcp:127.0.0.1:4444,server,nowait \ -m 2048 \ -hda disk.img这里-qmp后面跟的是通道描述。tcp:127.0.0.1:4444表示监听本地 4444 端口server表示 QEMU 作为服务端等待连接nowait表示不等客户端连上就继续启动虚拟机。如果不加nowaitQEMU 会卡在那里等第一个客户端连接这在自动化场景里通常不是你想要的。除了 TCP更常用的是 Unix domain socketqemu-system-x86_64 \ -qmp unix:/tmp/qmp.sock,server,nowait \ -m 2048 \ -hda disk.imgUnix socket 的好处是不占端口、权限控制更细、本机通信效率也高。做本机自动化管理时我基本都用 Unix socket。注意路径要放在有写权限的目录否则 QEMU 启动时会报错。还有一种写法是把 QMP 和监控终端合在一起用-monitor配合-qmp不过现在更推荐直接用 QMPHMP人机接口那套文本命令正在逐步被 QMP 取代。3.2 用 socat 或 nc 手动对话通道建好之后最直接的验证方式是用socat或nc手动连上去看看。以 Unix socket 为例socat - UNIX-CONNECT:/tmp/qmp.sock连上之后你会立刻收到 greeting类似这样{QMP: {version: {qemu: {micro: 0, minor: 2, major: 8}, package: }, capabilities: [oob]}}看到这个就说明通道通了。接着输入握手命令{execute: qmp_capabilities}回车后应该收到{return: {}}到这一步你就可以发业务命令了。比如查状态{execute: query-status}返回大概是{return: {status: running, running: true}}用nc的话如果是 Unix socket得用nc -U /tmp/qmp.sock。TCP 的话直接nc 127.0.0.1 4444。手动对话的价值在于当你写的客户端出问题时可以用它来确认到底是 QEMU 那边的问题还是客户端的问题快速定位故障边界。3.3 用 Python 写一个最小可用客户端手动对话只能验证真正做自动化还得写代码。下面是一个最小可用的 Python 客户端用标准库就能跑不依赖第三方包import socket import json class QMPClient: def __init__(self, path): self.sock socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) self.sock.connect(path) self.buf b # 收 greeting self._recv_message() # 握手 self.execute(qmp_capabilities) def _recv_message(self): while b\n not in self.buf: chunk self.sock.recv(4096) if not chunk: raise ConnectionError(QMP connection closed) self.buf chunk line, self.buf self.buf.split(b\n, 1) return json.loads(line.decode(utf-8)) def execute(self, cmd, argsNone): msg {execute: cmd} if args is not None: msg[arguments] args self.sock.sendall((json.dumps(msg) \n).encode(utf-8)) while True: resp self._recv_message() if event in resp: # 事件先放一边继续等命令响应 continue return resp def close(self): self.sock.close()用起来很简单c QMPClient(/tmp/qmp.sock) print(c.execute(query-status)) print(c.execute(query-block)) c.close()这段代码里有几个细节值得说。第一_recv_message用了缓冲区因为 TCP 或 Unix socket 是流式的一次recv不一定能拿到完整的一行必须自己攒。第二execute里遇到事件消息会跳过继续等因为事件可能在任何时候插进来不能把它当成命令响应。第三握手放在构造函数里保证对象一创建就是可用状态。提示如果你的场景里事件很重要别像上面这样直接丢弃应该单独开一个线程或协程专门收消息把事件和响应分流处理。否则事件一多命令响应可能被淹没。4. 常用命令与事件日常管理真正用得上的那些4.1 查询类命令先看清楚再动手QMP 里查询类命令是最安全的不会改变虚拟机状态适合用来做状态采集和监控。几个高频的query-status查虚拟机运行状态返回 running、paused、shutdown 等。query-block查块设备信息包括每块盘的插入状态、读写统计、后端文件路径。query-cpus-fast查 CPU 信息比老的query-cpus更快不触发停机。query-memory-size-summary查内存总量和已用情况。query-pci查 PCI 设备树排查设备直通问题时很有用。query-version查 QEMU 版本。这些命令返回的 JSON 结构在 QAPI schema 里都有定义字段含义明确。实际做监控时我一般会定期拉query-block和query-cpus-fast前者看 IO 是否异常后者看 CPU 占用。注意query-block返回的统计是累计值要算速率得自己两次采样做差。4.2 变更类命令热插拔与在线调整变更类命令会实际改动虚拟机用之前一定要想清楚。常见的几类块设备热插拔用blockdev-add加设备、device_add挂到总线上移除时反过来device_del再blockdev-del。这里顺序不能错先加后端再加前端先删前端再删后端反了会报设备忙。网卡热插拔类似netdev_add加后端device_add挂 virtio-net-pci 之类的前端。CPU 热插拔用device_add加qemu64-x86_64-cpu之类的对象但要注意 guest 操作系统得支持 CPU 热插拔否则加了也认不出来。内存调整相对麻烦需要 guest 配合通常走balloon设备通过balloon命令调整目标值实际生效取决于 guest 里的驱动。我踩过的一个坑是热插拔块设备时device_add的id和blockdev-add的node-name要对应上写错了会报找不到后端。而且这两个 id 在整个 QEMU 实例里必须唯一重复了也会失败。建议命名时带上用途和时间戳比如disk-data-20260101避免冲突。4.3 事件机制别让状态悄悄变化事件是 QMP 里最容易被忽视、但实际很重要的部分。虚拟机状态变化、块设备 IO 错误、电源事件、迁移进度都会以事件形式推过来。常见事件有事件名触发时机RESET虚拟机复位SHUTDOWN虚拟机关机POWERDOWN收到电源关闭请求STOP虚拟机暂停RESUME虚拟机恢复BLOCK_IO_ERROR块设备 IO 出错DEVICE_DELETED设备删除完成MIGRATION迁移状态变化事件机制的价值在于你不用轮询就能知道状态变了。比如做高可用时监听SHUTDOWN事件就能第一时间感知虚拟机挂了比定时query-status及时得多。但要注意事件是异步的处理逻辑不能太重否则会阻塞消息接收。我的做法是收到事件后只做入队真正的处理放到另一个线程。还有一个细节有些事件带data字段里面是事件相关的具体信息比如BLOCK_IO_ERROR会告诉你是哪块设备、什么错误。解析时别只看事件名data里的内容往往才是关键。5. QAPIQMP 背后的类型系统5.1 QAPI 到底解决了什么问题QMP 用 JSON 传消息JSON 本身是弱类型的一个字段是字符串还是数字光看消息看不出来。如果只靠约定客户端和服务端很容易对不上。QAPI 就是来解决这个问题的它用一套 schema 语言把每个命令的参数、返回值、每个事件的字段都定义清楚然后自动生成 C 代码和文档。对使用者的意义在于QAPI schema 就是 QMP 的权威接口文档。你想知道某个命令要什么参数、返回什么结构查 schema 比查任何二手资料都准。QEMU 源码树里的qapi/目录下就是这些 schema 文件按模块分比如block.json、migration.json、net.json。5.2 从 schema 读懂一个命令拿query-status举例schema 里大概是这么定义的{ command: query-status, returns: StatusInfo, allow-preconfig: true } { struct: StatusInfo, data: { running: bool, status: RunState } }这告诉我们query-status没有参数返回一个StatusInfo结构里面有两个字段running是布尔status是RunState枚举。再去找RunState的定义就能知道它有哪些取值。这种层层引用的方式让整个接口体系非常清晰。实际开发时我建议把用到的 schema 片段摘出来放在手边写代码时对照着看比反复试错快得多。尤其是参数名QMP 对参数名是大小写敏感的写错一个字母就报错。5.3 类型安全带来的实际好处QAPI 的类型系统不只是文档它还体现在运行时。当你发一个参数类型不对的命令QEMU 会明确告诉你哪个字段期望什么类型而不是默默接受然后行为诡异。这种即时反馈在调试时非常省事。另外QAPI 支持可选字段和联合类型这让协议在演进时能保持兼容。新版本加字段老客户端不认识就忽略不会崩。理解这一点你就明白为什么 QMP 能长期稳定地扩展而不破坏已有客户端。6. 实战中那些文档不写的坑6.1 握手顺序错导致的假死最常见的坑就是跳过qmp_capabilities。表现是连上之后发任何命令都没反应或者收到一个CommandNotFound之类的错误。排查方法很简单用 socat 手动连一次看 greeting 有没有正常收到握手有没有成功。如果手动能通那就是客户端代码的问题如果手动也不通那就是 QEMU 启动参数或 socket 权限的问题。还有一种变体是客户端把 greeting 当成命令响应处理了导致后续消息错位。记住 greeting 是服务端主动发的第一条消息格式是{QMP: {...}}没有return也没有error要单独识别。6.2 消息边界处理不当前面提过QMP 是按行解析的。客户端发消息时忘了加换行QEMU 就一直等客户端收消息时没按行切分就可能把两条消息粘在一起解析失败。这个坑在消息量大、事件频繁时特别容易触发。我的建议是无论发还是收都严格按一行一个 JSON来处理。发送时统一在末尾补\n接收时用缓冲区攒到\n再切。别图省事用recv一次就当一条消息流式协议没这个保证。6.3 事件与响应混在一起如果客户端只用一个循环收消息事件和响应会混在一起。处理不当的话你可能把事件当成命令响应返回给上层导致逻辑错乱。正确做法是收到消息先判断类型有event字段的是事件有return或error的是响应。两者分流处理。更稳妥的方案是双通道一个线程专门收消息收到后按类型分发到不同队列业务代码从响应队列取结果事件处理从事件队列取。这样职责清晰也不容易漏事件。6.4 权限与路径问题用 Unix socket 时socket 文件的权限决定了谁能连。如果 QEMU 以某个用户身份运行socket 文件属主就是那个用户其他用户连不上。做多用户环境时要么调整 socket 文件权限要么把管理进程和 QEMU 跑在同一用户下。TCP 的话要注意监听地址。绑127.0.0.1只能本机连绑0.0.0.0则所有网卡都能连后者在安全上要谨慎最好配合防火墙规则限制来源。6.5 命令执行失败的错误解读QMP 返回的错误信息里有个class字段表示错误类别比如GenericError、CommandNotFound、DeviceNotFound。不同类别对应不同的问题方向。CommandNotFound通常是命令名拼错或当前版本不支持DeviceNotFound是设备 id 写错GenericError则要看desc字段的具体描述。排查时先看class定位大类再看desc看细节。养成这个习惯能省下大量瞎猜的时间。7. 把 QMP 用进自动化体系的思路7.1 封装成可复用的客户端库裸写 socket 代码只适合验证真正做项目应该封装一层。封装时至少要考虑连接管理断线重连、消息收发缓冲与分行、握手自动化、事件回调注册、命令超时。把这些做进去上层业务代码就只需要调方法不用关心协议细节。我自己的封装里事件用回调注册的方式暴露业务方注册感兴趣的事件名和对应处理函数客户端收到事件后查表分发。命令则提供同步和异步两种接口同步的用于简单场景异步的用于需要并发发多条命令的场景。7.2 与监控系统对接QMP 的查询命令天然适合做监控数据源。定期拉query-block、query-cpus-fast、query-memory-size-summary把结果转成监控系统能吃的格式推过去。事件则用来做告警比如BLOCK_IO_ERROR直接触发告警SHUTDOWN触发状态变更通知。这里要注意采样频率。太频繁会给 QEMU 增加负担太稀疏又抓不到瞬时问题。我的经验是状态类查询 10 到 30 秒一次比较合适事件则是实时的不用轮询。7.3 编排场景下的注意事项做批量编排时QMP 客户端要能同时管理多个 QEMU 实例。每个实例一个连接命令要能路由到正确的实例。事件处理也要带上实例标识否则收到一个SHUTDOWN你不知道是哪台机器挂了。另外编排操作往往有依赖顺序比如先加后端再加前端。这种顺序不能靠并发去赌必须串行执行并检查每步的返回。QMP 是同步协议天然适合这种串行编排别为了快而乱序发命令。8. 几个容易被问到的细节关于 QMP 和 HMP 的关系简单说 HMP 是给人用的文本命令接口QMP 是给程序用的 JSON 接口。HMP 的很多命令在 QMP 里都有对应但 QMP 更规范、更适合自动化。新项目直接用 QMP 就行。关于 QMP 能不能远程用技术上可以绑到非本地地址即可但安全上要慎重。QMP 权限很大能改虚拟机配置、能读写块设备暴露到不可信网络风险很高。真要用至少加访问控制。关于版本兼容QMP 的设计是向后兼容的新版本一般不会删老命令但可能标记为废弃。客户端做版本探测时可以读 greeting 里的版本号也可以直接试命令收到CommandNotFound就说明不支持。关于性能QMP 本身开销很小瓶颈通常在客户端实现。如果发现命令响应慢先查客户端是不是单线程阻塞了再看 QEMU 那边是不是在忙。query-cpus-fast这类命令设计出来就是为了不阻塞虚拟机优先用它而不是老的query-cpus。我在实际项目里用 QMP 做了两年多的虚拟机管理最大的体会是协议本身不复杂难的是把边界情况处理干净。握手、分行、事件分流、错误分类这几件事做扎实了后面基本不会出大问题。反过来任何一处偷懒都会在某个深夜以奇怪的方式暴露出来。所以如果你打算把 QMP 用进生产系统建议先把上面这些坑逐个验证一遍再往上搭业务逻辑。