add revm dockerd docker api proxy doc

Signed-off-by: ihexon <14349453+ihexon@users.noreply.github.com>

Author: ihexon

content/posts/revm-shutdown-design/index.md

@@ -0,0 +1,352 @@
+---
+title: "如何设计虚拟机的关机流程"
+summary: "从 revm 的一次关机流程重构出发，讨论虚拟机运行时里 graceful shutdown、force shutdown、等待语义和宿主侧服务生命周期应该如何拆分。"
+description: "从 revm 的一次关机流程重构出发，讨论虚拟机运行时里 graceful shutdown、force shutdown、等待语义和宿主侧服务生命周期应该如何拆分。"
+date: 2026-05-16
+draft: false
+categories:
+  - "virtualization"
+tags:
+  - "design"
+  - "virtualization"
+  - "revm"
+---
+
+虚拟机的关机流程很容易被写成一团：收到用户中断，发一个信号，关几个服务，杀掉虚拟机，然后退出。
+
+这看起来能工作，但一旦运行时变复杂，就会暴露出许多问题：日志丢失、磁盘没来得及 sync、guest-agent 没跑完整、宿主侧代理提前退出、第二次 Ctrl-C 也不能立刻结束。
+
+这次 revm 的关机流程重构，本质上不是修一个 Go 代码问题，而是重新思考一个虚拟机运行时应该如何表达“关机”。
+
+<!--more-->
+
+## 关机不是一个动作
+
+很多 bug 都来自一个错误抽象：把“关机”当成一个动作。
+
+实际上，对于一个虚拟机运行时来说，关机至少包含三种完全不同的语义。
+
+第一种是 **请求 guest 自己关机**。
+
+这是一种 polite request。host 告诉 guest：“请你开始收尾。” guest-agent 可能会 flush 日志、停止服务、sync filesystem，最后 reboot 或 poweroff。
+
+第二种是 **等待 guest 退出**。
+
+这是 host 侧的等待行为。host 不一定在做什么，只是在等 VMM、hypervisor、子进程或者某个阻塞调用返回。
+
+第三种是 **放弃等待并强制收尾**。
+
+这意味着 host 已经不再相信 guest 能及时退出，或者用户已经不想等了。此时运行时要中断等待、停止宿主侧代理、释放 socket、关闭转发器，必要时 kill 子进程。
+
+这三件事如果混成一个 cancel 或一个 signal，流程就会变得很脆。
+
+## 第一次 Ctrl-C 应该是什么
+
+对于交互式命令，Ctrl-C 往往有两种语义。
+
+第一次 Ctrl-C 通常应该是：
+
+> 我想结束它，请正常退出。
+
+第二次 Ctrl-C 才是：
+
+> 我不想等了，立刻停。
+
+这个习惯很重要。它给运行时提供了一个自然的两阶段退出协议。
+
+对于虚拟机来说，第一次 Ctrl-C 不应该直接解释成“host 不再等待 VM”。它更适合解释成：
+
+```text
+request guest shutdown
+```
+
+也就是通知 guest-agent 进入关机路径。guest 内部应该有机会执行：
+
+```text
+stop services
+flush logs
+sync filesystem
+reboot / poweroff
+```
+
+host 此时仍然应该继续等待 VM 自己退出。
+
+如果第一次 Ctrl-C 直接打断 host 的等待路径，那么 guest-agent 可能还没来得及跑完整，宿主侧就已经开始 teardown。用户看到的现象通常是日志顺序混乱、shutdown 日志缺失，或者某些资源像是被硬切掉。
+
+## 第二次 Ctrl-C 应该是什么
+
+第二次 Ctrl-C 的语义应该非常明确：
+
+```text
+force shutdown
+```
+
+它不再是一个 polite request，而是 host 侧的决策：
+
+```text
+stop waiting for guest
+tear down host services
+return to user as soon as possible
+```
+
+这里的重点是“stop waiting”，而不是“再请求一次 guest 关机”。
+
+如果 guest 能正常关，第一次 Ctrl-C 已经足够。如果第二次 Ctrl-C 发生了，说明用户已经表达了不愿意继续等待。此时运行时应该把控制权还给用户。
+
+## 等待本身也需要被设计
+
+虚拟机运行时里经常有一个阻塞点：
+
+```text
+start VM and wait until it exits
+```
+
+这个阻塞点可能来自不同实现：
+
+- 当前进程内的 VMM 调用
+- libkrun / qemu / firecracker 之类的 backend
+- 一个子进程
+- 一个 RPC session
+- 一个管理 socket
+
+不管实现细节是什么，host 都需要表达一个问题：
+
+> 我还要不要继续等这个 VM 自己退出？
+
+这和“请求 guest 关机”不是同一个问题。
+
+请求 guest 关机是发给 guest 的消息；停止等待是 host 自己的控制流。
+
+所以设计上最好给“等待 VM 退出”一个独立的 abort signal。它可以是 context，可以是 channel，可以是 eventfd，也可以是 supervisor 内部的状态转换。具体机制不重要，重要的是语义：
+
+```text
+abort VM wait != request guest shutdown
+```
+
+这个区分能避免许多隐性 bug。
+
+## 宿主侧服务也有自己的生命周期
+
+一个现代虚拟机运行时通常不只是启动 VM。它还会启动一堆 host-side services：
+
+- 网络栈
+- 端口转发
+- 管理 API
+- ignition / metadata server
+- SSH proxy
+- container API proxy
+- 日志转发
+- 文件系统共享
+
+这些服务依附于 VM，但不等同于 VM。
+
+它们的生命周期应该是：
+
+```text
+VM 还在运行 -> host services 应该活着
+VM 已经退出 -> host services 应该收掉
+强制退出 -> host services 应该尽快收掉
+host service 自己失败 -> VM run 应该进入失败/强制收尾路径
+```
+
+这意味着 host services 也需要一个独立的生命周期控制。
+
+如果把 host services 的生命周期和 VM wait 混成一个信号，第一次 Ctrl-C 时就很容易出现错误：guest 还没关完，metadata server 或网络代理先被停掉了。
+
+对于某些 guest 关机路径来说，这些服务甚至可能仍然是必要的。例如 guest-agent 需要通过 virtio port、vsock、网络或管理通道完成最后一次通信。host 提前 teardown 会破坏 graceful shutdown 本身。
+
+## 一个更稳的状态机
+
+我更倾向于把虚拟机运行时的退出流程设计成下面这个状态机：
+
+```text
+running
+  |
+  | first interrupt
+  v
+shutdown requested
+  |
+  | guest exits
+  v
+finished
+
+shutdown requested
+  |
+  | second interrupt / timeout / parent disappeared
+  v
+forcing
+  |
+  | host resources released
+  v
+finished
+```
+
+这里有几个关键点。
+
+`running -> shutdown requested` 是 graceful path。它应该通知 guest，而不是中断 host 的等待。
+
+`shutdown requested -> finished` 是 guest 自己退出。此时 host 停止附属服务并返回。
+
+`shutdown requested -> forcing` 是放弃等待。它可以由第二次 Ctrl-C 触发，也可以由超时、父进程退出、后台 supervisor 取消任务触发。
+
+`forcing -> finished` 是 host 侧强制收尾。它的目标不是优雅，而是 bounded cleanup。
+
+## 超时是否必要
+
+两次 Ctrl-C 之外，很多运行时还会加一个 timeout。
+
+例如：
+
+```text
+first Ctrl-C
+  -> request guest shutdown
+  -> wait up to 30 seconds
+  -> force shutdown
+```
+
+这是否应该做，取决于产品语义。
+
+对于交互式 CLI，我更喜欢不默认加很短的超时，而是提示用户：
+
+```text
+waiting for guest shutdown; press Ctrl-C again to force
+```
+
+原因是用户就在终端前，可以自己决定要不要等。
+
+对于 daemon、CI、系统服务，timeout 更有必要。因为没有人在旁边按第二次 Ctrl-C，运行时必须保证最终能回收资源。
+
+所以 timeout 不是关机设计的核心，而是策略层。核心仍然是区分：
+
+```text
+request graceful shutdown
+abort waiting
+cleanup host resources
+```
+
+## 父进程消失时不必装作 graceful
+
+还有一种特殊情况：launcher 或 parent process 消失了。
+
+这和用户第一次 Ctrl-C 不一样。
+
+第一次 Ctrl-C 时，用户还在，运行时还被某个前台交互流程拥有。此时等待 guest 优雅退出是合理的。
+
+但如果 parent process 已经消失，运行时通常应该尽快 force shutdown。因为 owning process 已经没了，继续长时间等待会让后台资源悬挂。
+
+所以 parent exit 更像：
+
+```text
+force shutdown
+```
+
+而不是：
+
+```text
+request guest graceful shutdown and wait forever
+```
+
+这是一个 ownership 问题，不是 guest 是否支持 graceful shutdown 的问题。
+
+## 不要让机制吞掉语义
+
+这次重构里最容易误导人的地方是 `context`。
+
+在 Go 里，`context.Context` 是一个很方便的取消机制。但机制本身不携带业务语义。你把它叫 `ctx`，它就什么都能表示：
+
+- 用户取消
+- VM wait abort
+- host services teardown
+- request guest shutdown
+- parent process exit
+- backend failure
+
+一旦这些语义都塞进同一个 `ctx`，代码就很难回答一个问题：
+
+> cancel 这个 ctx 到底是在请求 guest 关机，还是在放弃等待 guest？
+
+这个问题不只存在于 Go。
+
+换成其他语言也是一样。一个 channel、一个 promise cancellation、一个 cancellation token、一个 eventfd、一个 unix signal，如果名字和状态机不清楚，都可能变成“万能退出按钮”。
+
+万能退出按钮的坏处是：它太容易工作了，直到你需要 graceful shutdown。
+
+## 可迁移的设计原则
+
+我从这次重构里总结出的原则是：
+
+### 1. 把 request 和 abort 分开
+
+请求 guest 关机是 request。
+
+停止 host 等待是 abort。
+
+它们可以先后发生，但不应该是同一个动作。
+
+### 2. 把 VM 生命周期和 host services 生命周期分开
+
+VM 退出后，host services 应该停止。
+
+但请求 VM 退出时，host services 不一定应该马上停止。
+
+### 3. 第二次中断必须有明确语义
+
+第一次中断 request graceful shutdown。
+
+第二次中断 force shutdown。
+
+不要让第二次中断只是重复发送同一个 shutdown signal。
+
+### 4. force path 必须能尽快返回
+
+force shutdown 的价值在于 bounded behavior。
+
+如果 force path 仍然可能无限等待，那它就不是 force。
+
+### 5. parent exit 是 ownership 结束
+
+父进程消失通常应该触发 force cleanup。
+
+这条路径不应该和用户第一次 Ctrl-C 使用同一套 graceful wait 语义。
+
+### 6. 命名要暴露状态机
+
+好的名字应该让读者看到控制流：
+
+```text
+requestGuestShutdown
+abortVMWait
+stopHostServices
+forceVMRun
+finishVMRun
+```
+
+坏的名字会隐藏设计：
+
+```text
+ctx
+stop
+shutdown
+cancel
+done
+```
+
+这些词不是不能用，而是不能在复杂生命周期里单独使用。
+
+## 小结
+
+虚拟机的关机流程不是“收到信号然后退出”这么简单。
+
+更稳的设计是把它拆成三层：
+
+```text
+guest graceful shutdown request
+host-side VM wait control
+host services lifecycle
+```
+
+第一次 Ctrl-C 只进入第一层。第二次 Ctrl-C 才进入后两层。
+
+这样设计后，guest 有机会完整执行自己的 shutdown path，host 又保留了强制退出的能力。无论底层是 libkrun、qemu、firecracker，还是一个自研 VMM 子进程，这个设计都可以迁移。
+
+真正重要的不是用了哪种语言、哪个 context、哪个 channel，而是状态机本身足够诚实：它清楚地区分了“请你关机”和“我不等了”。