# 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` 必须有四个文件: `.hmac`(同样的 canonical base64 HMAC key)、`.ca.pem`、 `.crt`、`.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 还会拒绝通用 ``、远程/块设备磁盘、NVRAM、emulator、 memory-backed file 和文件/套接字型外设。它们必须先进入有 owner、allowlist、TOCTOU 和读回证据的 typed Agent operation;因此这一版不能把任意网络或宿主路径拼进 domain XML,网络/完整挂载 executor 仍属于后续阶段。 未来 typed define 对 `` 仍必须在 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 区块: ```json { "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 文件路径)会被拒绝: ```json { "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 前统一规范化为: ```xml hvm ``` 宿主机不具备非 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 已发布,不证明来宾已经执行脚本。