You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/GO_AGENT_MIGRATION.md

7.9 KiB

Go 宿主机 Agent 重构契约

状态:go-agent 分支第一阶段设计与骨架,尚未接管生产宿主机。

全新系统边界

Go Agent 和配套面板 API 是全新系统,不承担旧 Python Engine 或旧数据库的 兼容责任。不会读取旧 engine_records 密文、旧 operation、旧 XML/seed 恢复记录,也不会在启动时执行隐式解密迁移。新数据库从零初始化,使用独立 schema 和版本;本分支不提供旧数据库兼容层,也不把旧字段映射成 Agent 的可信 状态。若业务确实需要保留账户/订单等资料,必须另行设计、人工审核的一次性 业务导入流程,该流程不属于 Agent 启动路径。没有完成新系统验收前,旧 Python 服务仍作为独立回滚面保留,但两者不共享写入表。

目标

  • PHP 面板继续拥有账户、订单、账期、IP 账本、租户授权和管理员页面。
  • 每台宿主机运行一个 Go Agent;面板只通过 Agent API 调用 libvirt、存储、固件、cloud-init seed、快照、救援和网络状态操作。
  • 新架构不再依赖 SSH 到宿主机,也不在 Agent 中实现 PHP 的用户/计费授权。
  • UEFI 继续使用 efi + q35,所有新建或重写的域显式关闭 Secure Boot。
  • 云镜像首次启动脚本只在创建云镜像实例时封存进 NoCloud seed,并使用来宾内一次性 marker 防重复执行。
  • 旧 Python Engine 在 Go Agent 完成替换、双侧验收和回滚窗口关闭前保留,不先删除。

明文数据库边界(新 schema)

“不再加密数据库内容”适用于新 schema 中的业务状态、可审计 desired/observed JSON 和 operation 记录;新 schema 不包含旧的 *_cipher 兼容列,也不在 Agent 中实现旧密文解密。以下内容仍不写入明文数据库:

  • Agent mTLS 私钥、注册 token、面板签名密钥;
  • 管理员密码、用户 bearer token、SSH 私钥、VM root 密码、SMTP/支付/Telegram 凭据;
  • 云镜像启动脚本中的平台密钥或其他租户凭据。

这些值使用 systemd credentials、root-only 文件或受控 secret provider;数据库只保存 secret_ref/指纹。密码仍只保存不可逆 hash,token 只保存指纹。数据库明文不等于删除 HMAC、CAS、唯一约束或 operation idempotency。

Agent 请求签名密钥的文件协议固定为 canonical standard base64(解码后恰好 32 个 raw bytes,允许文件末尾换行)。Go auth.FromFile 负责严格解码;PHP 面板侧 CloudAgentFileSecretResolver 负责读取每个 agent_id 的 .hmac/.ca.pem/.crt/.key 四文件,执行同样的 HMAC 解码并把 raw key 与 TLS 文件路径交给 CloudAgentClient;宿主 侧 VIRT_CLOUD_AGENT_HMAC_KEY_FILE 则只由 Go Agent 本地 verifier 读取。测试或内存调用 可以使用明确标注的 raw-key constructor,但不得把配置文件中的 base64 文本直接用于 HMAC。

Agent 传输和启动语义

  • Agent 默认只监听 loopback;远程监听必须启用双向 TLS,并校验面板 CA、Agent 身份和请求有效期。
  • PHP CloudAgentClient 只接受 HTTPS endpoint;默认 loopback HTTP 仅用于本机开发/健康 检查,不能直接填入生产面板配置。生产面板应使用 Agent 的 mTLS 地址(或受控的 本机 TLS 终结层),避免把 PHP 客户端降级成明文。
  • 每个写请求携带 request_id/operation_id、body digest、时间戳、nonce 和注册的 agent_id;agent_id 参与 HMAC canonical 文本并必须等于当前宿主身份。重复请求返回 同一 durable operation,不重放不确定的破坏性动作。
  • 配置文件、目录 mode 或 owner 检查不再阻止进程启动;启动时记录 warning 并将 readiness 标为 degraded。缺少监听地址、证书、Agent 身份或操作日志等必需运行时能力时,进程仍可提供健康/诊断接口;除认证后只读的 domain_preflight 外,写操作仍拒绝。domain_preflight 也必须通过 TLS/HMAC、Agent 身份和 durable journal gate。
  • 这不等于删除 OS 安全边界:mTLS 私钥、操作日志、libvirt socket 和运行目录仍必须防 symlink、路径穿越和非授权替换。
  • PHP web/bootstrap.php 只选择并加载面板配置,不执行配置 mode/owner 预检,也不读取 Python engine.json;因此面板 liveness 不依赖旧 Engine 配置文件的权限。操作系统本身 仍须允许 PHP-FPM 读取实际配置,否则 PHP 无法解释该文件,这是文件访问失败而不是应用 层权限审核。旧 Python private_config() 的 0600/owner 检查在回滚面暂时保留,不能把 它的宽松读取能力误认为 Go Agent 已验收;切换完成后随 Python Engine 一并删除。

分层

  1. transport/auth:mTLS、请求签名、重放窗口、请求体上限、脱敏日志。
  2. host capability:libvirt/QEMU/存储/UEFI/QGA/快照能力探测;只读 test 和 readiness。
  3. domain/desired state:UUID、managed XML metadata、UUID 资源命名、UEFI/no-Secure-Boot、网络/防火墙/电源目标。
  4. operation journal:本地明文但原子持久化的 operation、commit boundary、cleanup manifest、uncertain/reconcile。
  5. artifact/seed:云镜像副本、用户 ISO、救援 ISO、NoCloud seed 和一次性启动脚本快照。
  6. HTTP API:保持 PHP 现有业务语义,Agent 不接收 PHP 的原始用户权限并自行放大; mTLS + HMAC 是当前 host-wide transport authority,X-Cloud-Actor 只作为签名审计 元数据,最终租户/管理员授权仍由 PHP 完成。按操作粒度的 capability token 绑定属于后续协议版本,不在当前 v1 中假装已经实现。

当前 API 迁移原则

  • PHP 的用户路由和管理员页面先不改;CloudEngineClient 增加 Agent transport adapter,逐个替换内部调用。
  • Agent API 以显式 VM UUID 和 operation_id 为主,不提供租户侧全宿主 inventory。
  • uncertain、cleanup_pending、快照证据、救援原 XML、删除 manifest、firewall revision/digest 和网络收敛均为当前正确性边界,不得在迁移中删除。
  • 旧 SSH host scan/unlock/test/save 在 Agent enrollment、capability probe、证书轮换和 PHP 页面切换完成前保留;切换后才删除 SSH 字段和 Python SSH 代码。

具体能力和删除门槛见 GO_AGENT_OPERATION_MATRIX.md。 矩阵中的“未实现”能力不得通过旧 Python 或 SSH 隐式回退伪装成 Agent 成功。

分阶段门槛

  1. 建立 Agent v1 健康、能力和 operation API;本地 fake backend 全量测试。
  2. 增加 cloud_agents/cloud_agent_operations 与 fresh schema generation;明文 desired/observed JSON 迁移,保留 CAS、唯一键、租约和审计字段。cloud_agent_operations.version 是独立的单调 CAS token,不能用秒级 updated_at 代替。
  3. PHP 以 shadow/read-only 方式调用 Agent,比较 Python 与 Agent 的状态和 XML/资源证据。
  4. 逐项切换创建、读取、电源、网络、设置、快照、防火墙、救援、重装和删除;每项通过真实宿主机验收后再关闭 Python 路由。
  5. 103 宿主机只做只读能力、域 XML、存储和 Agent API 验证;任何 bridge、地址、路由、nftables、firewalld、WireGuard 或网络 manager 写操作均禁止,除非另行明确授权。
  6. 所有 PHP/Agent/Go 测试、go test -race ./...、静态安全扫描和真实宿主机验收通过后,才在独立提交中删除 Python Engine、SSH 配置和旧 schema 迁移路径。

当前 PHP shadow 仅实现 registry health 的显式注入服务,见 GO_AGENT_PHP_SHADOW.md;它尚未接入旧管理员路由, 不会替换 Python readiness,也不能作为删除 Python/SSH 的证据。

回滚边界

go-agent 分支不向 dev 推送。每个切换阶段独立提交,保留 Python fallback 和旧服务单元直到下一阶段验收完成;任何未知 destructive result 以 operation id 重新核对,不自动重放。