实现首版 Gitea microVM runner

README.md

@@ -1,3 +1,39 @@
-# gitea-microvm-runner
+# Gitea microVM runner
 
-按需启动 Cloud Hypervisor microVM 的 Gitea Actions runner autoscaler
+为 Gitea Actions 按需启动 Cloud Hypervisor microVM。适合 kind、嵌套容器和其他不应
+在常驻 Kubernetes runner 中执行的 CI 工作负载。
+
+组件：
+
+- `controller`：接收 Gitea `workflow_job` webhook，将指定 label 的 queued job
+  发布到 NATS JetStream。
+- `worker`：在虚拟化宿主机领取任务，限制本机并发，并启动一次性 microVM。
+- `microvm-runner-launch`：为每个任务创建 COW disk、NoCloud seed 和 TAP，运行
+  Cloud Hypervisor，退出后完整清理。
+- `guest-runner`：在 guest 中领取一次性 runner registration token，注册 ephemeral
+  runner，执行一个 job 后关机。
+
+消息流使用一个 `WorkQueuePolicy` stream。相同 runner label 的所有 worker 共享同一
+durable consumer；扩容只需要增加 worker 或提高单机 capacity。
+
+## 开发
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[test]'
+pytest
+```
+
+## 安全边界
+
+- NATS 密码、webhook secret 和 Gitea registration token 只从文件读取。
+- registration token 不写入 seed image；worker 通过单次 nonce endpoint 交给 guest。
+- guest runner 使用 `--ephemeral`，每台 VM 只执行一个 job。
+- launcher 只接受 UUID instance ID 和 URL-safe nonce，所有临时文件都位于独立目录。
+- base image 不得包含 runner identity、registration token、SSH 密码或 host key。
+
+homelab 的 Kubernetes、OpenBao、LXC、bridge 和容量配置保留在
+`panxiao81/homelab-infra`。
+
+按需启动 Cloud Hypervisor microVM 的 Gitea Actions runner autoscaler