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

5.9 KiB

Go Agent 面板 operation CAS 边界

状态:go-agent 分支的 greenfield 面板状态机基础层。该组件尚未接入旧 PHP 用户/管理员路由,也不调用宿主机、SSH、Python Engine 或旧数据库。

责任边界

CloudAgentOperationRepository 是新表 cloud_agent_operations 的唯一写入 入口。它只负责以下面板侧事实:

  • 以 operation_id + agent_id + idempotency_key + request_hash 保留一次新的 typed operation;相同身份可安全重放读取,不同请求会返回冲突;
  • 用 version、lease_owner、lease_expires_at 和 attempt_count 做跨 PHP worker 的 CAS/租约 fencing;
  • 保存有限的 desired/result JSON、状态、错误码和 commit boundary;不会保存 Agent 错误详情、原始 XML、网络/启动脚本、宿主路径、URL、命令或凭据;
  • 在网络结果未知时把状态保留为 uncertain,只允许显式 reconcile claim, 不把原 destructive request 自动重放成新的 dispatch;
  • 返回不携带 lease owner 的公开记录。CloudAgentOperationClaim 只在当前 PHP 进程内使用,显式禁止队列序列化。

Agent HTTP 必须在事务外执行。正确顺序是:

reserve
  -> claim(dispatch)
  -> [HTTP Agent 请求;不持有数据库事务]
  -> renew(长操作仍在执行且租约尚未过期时)
  -> setCommitBoundary(如有宿主 read-back 证据)
  -> finalize(succeeded|failed;省略 boundary 时保留当前证据)
  -> 或 markUncertain / claim(reconcile)

状态转移

当前状态 允许动作 结果
pending claim(dispatch) running,版本与尝试次数递增
running 且租约有效 同一 claim 的 boundary/finalize CAS 成功才可写入
running 且租约过期 任意新 claim 先提交 uncertain + lease_expired,然后要求只读核对
uncertain claim(reconcile) 继续 uncertain,不得变成 dispatch
running/uncertain finalize succeeded、failed 或再次 uncertain
终态 任意 claim/finalize 拒绝,不能覆盖既有证据

过期 fencing 在同一数据库事务中写入,但异常在事务提交后才抛出;这样不会因 “通知调用方必须核对”而把 fencing 回滚成陈旧的 running。所有更新都要求 operation_id + version + status + lease_owner,终态还要求 lease 仍未过期, 因此迟到的 worker 不能覆盖新的核对结果。

renew() 也必须带同一个 fencing token,并且只接受仍未过期的租约。它只延长 租约并递增版本,不会把 uncertain 变回 running;续租失败时应立即停止等待 原请求并转入只读核对。租约过期 fencing 只会把尚未证明的 not_started boundary 变为 unknown,已经由宿主 read-back 证明的 boundary 必须保留,供 reconcile 决定清理或继续观察。

数据和错误边界

  • desired/result 只接受受限 JSON;根 desired 必须是非空对象,result 必须是非空 对象或 null(不接受 JSON list/空对象),嵌套深度和字节数有上限,字段名拒绝 控制字符、路径/XML/网络/启动脚本/凭据等敏感形态。非凭据摘要 字段(例如 xml_hash、plan_hash)可保留,但不代表原文已经进入数据库; password_hash、secret_hash、token_hash 等凭据摘要也拒绝进入 operation result,避免把认证材料的衍生物误当作普通资源身份。
  • error_code 是稳定的小写机器码;人类错误详情不进入 journal。数据库异常 对外统一映射为安全的 storage_unavailable,不泄露 SQL/连接细节。
  • CloudAgentOperationException 使用独立的 errorCode 属性,不重声明 PHP 内置 Exception::$code;HTTP 状态仅由 API adapter 映射,不能作为业务错误码。
  • 新 schema 的 version 是独立 CAS token(marker v2),不能用秒级 updated_at 代替;数据库仍是新库初始化,不执行旧表迁移、解密或回填。
  • finalize()/markUncertain() 未显式给出 boundary 时保留当前已证明值;只有 uncertain 且仍为 not_started 的记录会被标为 unknown。它们不会把 seed_published、readback_confirmed 等证据回退掉。
  • succeeded 终态必须带非 not_started/unknown 的宿主 commit boundary;没有 read-back 证据的请求只能停在 failed 或 uncertain。
  • reserve() 接收的 request_hash 是调用方已经从 canonical request body 计算出的值,不是授权或 hash 生成器;在接入 gateway 前必须先做 typed normalizer、校验 target/instance_uuid 与 desired 的一致性,并绑定 actor、 host/enrollment generation,再调用 reserve。不能让 HTTP 参数直接透传成 trusted replay。

接入前必须完成的工作

这层完成后仍不能宣布生产切换。接 gateway 时必须再完成:

  1. 将 agent_id 与不可变的宿主/enrollment generation 绑定,防止重新注册后 旧 operation 被路由到错误宿主;当前 repository 只接受 registry 已验证的 agent_id,不会自行推断 host 归属。
  2. 由唯一 gateway 在事务外构造 mTLS/HMAC client,校验完整响应 envelope,再 调用 setCommitBoundary/finalize;不能把任意 HTTP JSON 直接写进 result。
  3. 为不同 operation kind 定义 commit boundary 的合法顺序、清理清单和只读 reconcile;当前 repository 只提供 CAS,不替业务宣称宿主动作已完成。
  4. 在 CI/部署环境执行 PHP 8.5、Eloquent、真实 MariaDB 并发测试。当前开发 shell 没有 PHP/Composer,因此本轮只能提供源码契约检查;Go race/vet 不能替代 PHP/数据库/真实宿主验收。

旧 CloudJob、Python Engine、SSH 和现有业务路由仍保留为独立回滚面,直到 每个 typed Agent operation 完成 shadow、103 宿主只读验证、真实 read-back 和 回滚窗口验收后,才允许另一个独立提交删除它们。