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_API_V1.md

15 KiB

Go Agent API v1(全新协议)

这是新的 PHP 面板到宿主机 Go Agent 的 v1 绿地协议(当前实现边界)。它不兼容 Python Engine 内部 API,也不读取旧数据库;任何旧 operation 需要由人工定义的业务导入 重新生成新的 operation_id,不能把旧状态伪装成 Agent 已执行。

连接与身份

  • Agent 默认监听 127.0.0.1,用于本机开发和健康检查。
  • 远程监听必须使用双向 TLS 1.3。面板证书由部署 CA 签发,Agent 只接受该 CA 并将客户端证书指纹绑定到 cloud_agents.client_certificate_fingerprint;轮换期 使用 cloud_agent_client_certificates 的受控重叠记录。
  • Agent 不连接面板数据库,不持有 PHP 数据库密码,也不接受 SSH 私钥。
  • VIRT_CLOUD_AGENT_HMAC_KEY_FILE 是宿主 Agent 本机的 verifier 文件;它只供 Go Agent 读取,不能把这个路径或宿主文件直接配置到 PHP。文件内容是 canonical standard base64 文本,解码后必须恰好 32 个 raw bytes;文件末尾可有一个换行。Go FromFile 会拒绝 symlink、非 regular file、group/other 权限、原始字节、嵌入空白、非 canonical padding 和其他长度;权限错误只让 Agent 保持 degraded,不会放行写请求。密钥路径的祖先目录也 会逐级检查;仅内核 sticky 保护的标准共享临时根(例如 /tmp)可作为测试边界,生产 secret/journal 应放在单 Agent 独占的私有目录。
  • PHP 面板使用独立的 root-only secret provider。默认目录为 /run/virt-cloud/agents/,每个已登记 agent_id 必须有四个文件: <agent_id>.hmac(同样的 canonical base64 HMAC key)、<agent_id>.ca.pem、 <agent_id>.crt、<agent_id>.key。PHP CloudAgentFileSecretResolver 每次请求都会 校验这些文件及其祖先目录的 regular/non-symlink、owner 和权限边界,并只把解码后的 32-byte key 与文件路径交给 CloudAgentClient;这些文件不存入数据库,也不由 CloudSecrets/旧 cloud_engine_hmac_file 解析。面板端的四文件必须通过受控部署流程 写入,不能把宿主机的 request.hmac 路径当作面板 secret directory。
  • GET /v1/health 是 liveness;配置 mode/owner 宽松时仍返回 200,但 readiness=degraded。除只读 domain_preflight 外,写操作在宿主 readiness 降级时返回 503;preflight 仍必须通过认证传输、Agent 身份和 durable journal gate,不能借此绕过 TLS/HMAC 或匿名放行。

请求信封

写请求必须携带并在 Agent 端校验:

字段 约束
operation_id UUID;一次业务操作的稳定标识
idempotency_key 面板生成;同一 Agent 下不可复用到不同 body
request_hash 原始 JSON body 的 SHA-256
timestamp 与 Agent 时钟偏差不超过部署窗口
nonce 在 Agent journal 中一次性消费,防重放
X-Cloud-Agent-ID 必须等于当前 Agent 的注册身份,并参与 HMAC canonical 文本;防止同一 transport secret 被发往错误宿主
client certificate 绑定已注册 Agent 调用方/面板传输身份;X-Cloud-Actor 当前只作签名审计元数据,业务权限仍由 PHP 发起前校验

面板生成新操作时可以只提交 idempotency_key,由 PHP 按该键稳定生成 operation_id。如果调用方显式提交 operation_id,必须同时提交同一次请求的 idempotency_key(请求头和请求体若同时出现也必须一致);operation UUID 本身 不携带原始幂等键,面板不会从 UUID 派生或猜测幂等键。仅有 operation_id 的 重试在进入 Agent 或 journal 之前以 422 拒绝,避免把未知重试变成第二个操作。

响应必须包含 operation 状态。网络超时不是失败证明;面板应以 GET /v1/operations/{operation_id} 和专用 reconcile 端点核对,而不是自动 重放 delete/reinstall/power 等破坏性操作。

HMAC canonical 文本在绑定 Agent 时为 METHOD、URI、body SHA-256、timestamp、nonce、agent_id、actor 七行;未绑定的本地单元测试形式保留六行。协议测试向量(仅测试材料,不得用于生产):文件内容 MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY= 解码为 0123456789abcdef0123456789abcdef;对 POST /v1/operations、body {"ok":true}、timestamp 1700000000、nonce 0123456789abcdef、actor panel-agent 的签名为 cdaa0263ea55989caf519362660358ea67d78002ff428490d39734f0c7a1cb37;若 agent_id=host-103 纳入第六行,签名为 727720b3ed11cc15b2664cdb8c4bc1c2f7befa9742666815137cb281d873b41c。

v1 端点

方法 路径 说明
GET /v1/health liveness/readiness、非敏感 warning
GET /v1/capabilities EFI/q35、非 Secure Boot、QGA、快照等能力
POST /v1/agent/test 只读能力探测,不改网络/域/存储
POST /v1/operations 幂等 operation 入口;当前实现覆盖 capability_probe、domain_preflight、只读 domain_create_plan/domain_create_validate、域 XML 只读、电源、domain_observe 和 seed_prepare;原始 domain_define 已明确禁用
GET /v1/operations/{id} 读取 durable operation
POST /v1/operations/{id}/reconcile 未知结果的类型化核对,不自动重放;当前对 domain_power 只读 domstate,reboot 永不由单次 running 回读确认,shutdown 必须读到 terminal shutoff

当前 Go 实现已经覆盖 capability probe、只读 domain_preflight、只读 domain_create_plan/domain_create_validate、单域 XML 读取、组合 XML/电源状态的 domain_observe、电源动作、 只读电源/preflight reconcile,以及 seed_prepare 的 NoCloud artifact 发布。仍未 开放的完整创建/重装、网络/服务收敛、快照、防火墙、救援、删除、控制台票据 和存储 artifact 会继续以显式 UUID 和白名单 payload 增加;在对应宿主机 readback、清理清单和 commit boundary 完成前,Agent 会返回“未实现”,而不会 把旧 Python operation 转发或重放。

原始 domain_define operation 已从 HTTP 白名单移除。旧 backend 仍保留内部 define 实现供隔离测试/后续重构使用,但 Agent 不再接受任意 XML,也不会把仅按 UUID 的读回误报为 desired XML 已落地。面板若要求创建域,应等待带 ownership marker、卷/seed identity、原子 define 和精确 read-back 的 typed executor。

当前 host-bound XML 还会拒绝通用 <interface>、远程/块设备磁盘、NVRAM、emulator、 memory-backed file 和文件/套接字型外设。它们必须先进入有 owner、allowlist、TOCTOU 和读回证据的 typed Agent operation;因此这一版不能把任意网络或宿主路径拼进 domain XML,网络/完整挂载 executor 仍属于后续阶段。

未来 typed define 对 <disk type="file"><source file="…"/></disk> 仍必须在 host-bound 阶段执行存储路径 allowlist:每个路径必须是现有 regular file、不能是 symlink 或 路径别名,并且必须位于 Agent 配置的 VIRT_CLOUD_AGENT_STORAGE_ROOTS 之一。 空 allowlist 不表示允许任意路径,而是对 file-backed 磁盘 fail-closed;存储根的 创建、owner 和挂载生命周期由宿主部署负责。该检查不能替代后续的全祖先 owner/TOCTOU 验收,所以在对应门槛完成前不要把 domain define 当作生产存储编排。定义前可证明的 路径策略拒绝会记录为 definitive failure;定义后读回发现路径漂移仍保留操作证据, 不会把不受控 XML 报告为成功。

每个 destructive operation 都必须定义 commit boundary、清理清单和 readback 证据;未知结果只能通过该 operation 类型的只读 reconcile 核对。

domain_create_plan(只读首版)

domain_create_plan 是完整创建流程前的绿地 intent/能力边界,不是 VM 创建成功 证明。它复用 domain_preflight 的严格 EFI、x86_64、q35、pflash、readonly 和 Secure Boot disabled 校验,并额外接受以下 typed 区块:

{
  "domain": {
    "uuid": "00000000-0000-4000-8000-000000000001",
    "firmware": "efi",
    "architecture": "x86_64",
    "machine": "q35",
    "os_type": "hvm",
    "loader": {"type":"pflash", "readonly":true, "secure_boot":false}
  },
  "seed": {
    "artifact_id": "00000000-0000-4000-8000-000000000002",
    "instance_id": "instance-1",
    "hostname": "vm-1",
    "network_config": "{\"version\":2,\"ethernets\":{}}",
    "startup_script": "#!/bin/sh\necho first boot\n"
  },
  "image": {"id":"image-1", "sha256":"<64 lowercase hex>"}
}

network_config 和 startup_script 只在本次请求内用于确定性渲染。响应和 durable operation journal 只保留 pre-host XML 的 xml_hash(规范化 XML 原文仅在 Agent 进程内供后续 host-bound 阶段使用)、三份固定 NoCloud 文件的字节数/SHA-256、 first_boot_present/first_boot_digest、镜像摘要和 plan_hash; 不会保存脚本、网络原文、镜像 URL 或宿主机路径。为避免通用明文 journal 的敏感键 规则误把摘要替换成字符串,manifest 使用 agent 内部的 user/meta/network 摘要字段, 不代表 payload 文件内容。

该操作只调用一次只读 capability 观察,成功边界为 domain_create_plan_confirmed。它不会调用 WriteSeedDirectory、存储池/卷、 DefineDomain、任何电源动作或网络配置。HTTP 丢失、宿主 capability 不可用时, operation 保持 uncertain;reconcile 只重新观察 capability 并核对同一个 plan_hash,不会重放创建步骤。loader_pending=true 仍表示真实 loader 路径必须在 后续 host-bound define 阶段由新鲜 domcapabilities 选择。计划通过不证明镜像含 cloud-init,也不证明磁盘、seed attach 或来宾脚本已经执行。

domain_create_validate(已发布 seed 的只读核验)

domain_create_validate 只接受与 domain_create_plan 输出形状相同的脱敏 JournalPayload(不是带有 seed.network_config 或 seed.startup_script 的原始创建 请求)。调用方应先用 seed_prepare 发布同一 artifact_id;Agent 不追踪两个 operation 的来源链路,只依据 journal identity 和宿主 artifact 回读做核验。Agent 会从配置的 artifact 根目录按 UUID 定位固定 NoCloud 目录,校验目录权限、manifest 和三份文件的 SHA-256,再重新渲染 pre-host XML 并核对 plan_hash。请求/journal/result 均不保存 脚本、网络原文或宿主路径,未知字段会在入 journal 前拒绝。

核验通过后只执行一次只读 domcapabilities/能力观察,结果同时返回 commit_boundary=seed_verified 的核验结果(包括 first_boot_present/摘要)和能力摘要,operation commit boundary 为 domain_create_validate_confirmed。该操作永远不会写 seed、分配存储、define 域、 执行电源动作或修改网络;loader_pending=true 仍表示真实 loader 路径必须在后续 host-bound define 阶段从新鲜能力中选择。seed 缺失、manifest 不匹配或策略/hash 不一致 是 definitive failure;artifact/能力传输不可用保持 uncertain,可在同一 operation ID 上 reconcile。reconcile 先重新验证 seed,再只读观察能力,绝不重放 define/写入。

domain_preflight(只读首版)

POST /v1/operations 的 kind=domain_preflight 只接受以下严格 typed payload;未知字段(包括 XML、磁盘、卷、网卡、网络配置和 loader 文件路径)会被拒绝:

{
  "uuid": "00000000-0000-4000-8000-000000000001",
  "firmware": "efi",
  "architecture": "x86_64",
  "machine": "q35",
  "os_type": "hvm",
  "loader": {"type": "pflash", "readonly": true, "secure_boot": false}
}

预检执行阶段只读取宿主 capability,不先依赖通用 host readiness probe;这使得 宿主 probe 过期或失败时仍能取得新的能力事实。它不调用 define/power,也不分配 磁盘或修改网络。成功结果包含宿主能力摘要、pre-host XML 的 xml_hash 和 loader_pending=true;规范化 XML 原文不会进入 operation journal/API JSON,loader 的绝对路径必须在后续 host-bound define 阶段从 新鲜 domcapabilities 选择,预检不会猜测或接受调用方路径。失败使用稳定码: domain_preflight_invalid_uuid、domain_preflight_*_rejected、 domain_preflight_host_policy_rejected、domain_preflight_host_unavailable 或 domain_preflight_canceled。host unavailable 会以 uncertain 写入 operation journal,并可在 readiness 仍降级时通过同一 operation ID 的 reconcile 再次只读 核对;host policy rejection 是 definitive failed。预检通过不等于 VM 已创建。

固件与启动脚本不变量

所有新建、重装、救援 define 前统一规范化为:

<os firmware="efi">
  <type arch="x86_64" machine="q35">hvm</type>
  <firmware><feature name="secure-boot" enabled="no"/></firmware>
</os>

宿主机不具备非 Secure-Boot EFI descriptor 时拒绝操作,不能降级到 BIOS 或 i440fx。云镜像首次启动脚本最多 32 KiB,拒绝 NUL/非法 UTF-8,CRLF 归一化 为 LF,只在 create 时封存到 CIDATA NoCloud seed;脚本在 guest 内用原子 started marker 防止失败或中断后的自动重跑。

宿主机侧 seed artifact 先以目录形式落盘;internal/seedmedia 目前只做 immutable 身份核验并明确返回“不可 attach”的目录状态,再由后续受控存储层决定是否制作 CIDATA ISO。Go Agent 不调用 mkisofs/genisoimage,也不把请求中的文件名 拼入 shell/argv;agent/internal/startup.WriteSeedDirectory 只写固定的 user-data、meta-data、network-config 和 manifest.json。目录权限为 0700,文件权限为 0600,manifest 记录每个 NoCloud 文件的字节数和 SHA-256。写入在同级临时目录完成并 fsync 后发布;artifact_id 是 immutable 身份:相同 manifest 的重试直接复用,内容不同或已有非 Agent 目录时返回冲突, 不执行旧目录替换,也不会出现 target→backup 的空窗。路径或 symlink 不通过 校验时保持原目录不变。 启动脚本由 guest 内固定的 /bin/sh 执行,契约是 POSIX shell,不依赖 Bash。

seed_prepare 的 payload 只接受 artifact_id(UUID)、instance_id、 hostname、可选 JSON network_config 和可选 startup_script。Agent 返回 artifact ID 与 manifest,不返回宿主机绝对路径;PHP 负责把该 artifact 与新 schema 中的实例/镜像 desired state 关联。旧 seed、旧 operation 或旧数据库 字段不会被自动识别。

能力响应中的 startup_script/startup_script_agent 和 nocloud_seed_artifact 表示 Agent 已实现 NoCloud seed 与一次性脚本 artifact 发布;startup_script_host(以及 cloud_init)仍是宿主或来宾镜像事实,不能 仅凭 Agent 能发布 seed 就推断镜像一定安装了 cloud-init。seed_prepare 成功只 证明 immutable artifact 已发布,不证明来宾已经执行脚本。