diff --git a/docs/GO_AGENT_PHP_LEGACY_CALLS.md b/docs/GO_AGENT_PHP_LEGACY_CALLS.md new file mode 100644 index 00000000..3ee574f9 --- /dev/null +++ b/docs/GO_AGENT_PHP_LEGACY_CALLS.md @@ -0,0 +1,223 @@ +# PHP 到 Go Agent 切换审计:旧 Engine、CloudJob 与宿主 SSH + +**审计日期:** 2026-10-16 +**分支:** `go-agent` +**范围:** `web/app`、`web/config`、云面板相关浏览器脚本/模板,以及当前 Go Agent v1 契约。 +**方法:** 只读检索 `CloudEngineClient`、`CloudJobService`、`CloudJob`、`/internal/v1`、宿主 SSH 凭据字段和用户 SSH 公钥字段,再对照 `docs/GO_AGENT_API_V1.md`、`docs/GO_AGENT_OPERATION_MATRIX.md` 与当前 PHP Agent gateway。 + +## 结论先行 + +当前不能删除全部 Python Engine、`CloudEngineClient`、`CloudJobService` 或宿主 SSH +配置。当前真正已经切到 Go Agent 的范围很窄: + +- 电源操作 `start`、`shutdown`、`reboot`、`poweroff`(Agent `domain_power`); +- 显式 `live=1` 的单/批量运行状态观察(Agent `domain_observe`,批量实际是有界的多次单 UUID 请求); +- 运行时状态同步、Agent readiness/注册表健康检查; +- UUID Agent operation 的状态/历史投影; +- 面板数据库内的元数据、账单、资源调度,以及用户 SSH **公钥**管理。 + +创建、重装、救援、删除清理、快照、防火墙、网络策略、镜像/ISO artifact、指标/流量、 +控制台票据、宿主机注册,以及旧任务 worker 仍依赖旧 Engine/`CloudJob`。Go Agent +虽然已有窄范围 `domain_delete` 主机操作,但 PHP 尚未开放该 kind,而且它只做 +libvirt `undefine`,不包含面板磁盘、seed、计费、IP 和 tombstone 清理;不能直接替代 +面板删除流程。 + +因此本文件把调用点分为: + +1. **A:可立即使用/已切换**:没有旧 Engine/SSH 运行时依赖,或已有明确的 Agent 边界; +2. **B:需要 Go Agent 新 API 或 PHP 适配器**:在对应 API、幂等、回读和清理证据完成前不得删除旧路径; +3. **C:保留用户 SSH 公钥**:这是来宾初始化输入,不是宿主机 SSH 运维凭据,不能误删。 + +“可立即使用”只表示代码路径的边界已满足,不等于真实宿主机、libvirt、来宾或跨宿主网络 +已经验收。Agent 操作的 HTTP 超时仍必须按 `operation_id` 核对,不能盲目重放破坏性动作。 + +## A. 可立即使用或已经切换的路径 + +| 路径 | 当前证据 | 边界/注意事项 | +| --- | --- | --- | +| `web/app/Controllers/CloudApiController.php:1180-1275` `actions()` | 通过 `CloudAgentActionService` → `CloudAgentVmGateway`;`PANEL_POWER_ACTION_TO_AGENT` 明确映射四种电源动作 | `reset` 未实现;成功必须有 Agent envelope 与宿主回读。没有 Python/SSH fallback。 | +| `CloudApiController.php:833-880` `vmStatuses()` | `live=1` 调用 `CloudAgentObservationService::observeMany()`,目标先由面板实例/权限确定 | v1 没有 batch endpoint,实际为每个已授权 UUID 一次 `domain_observe`;需设置数量/超时上限。默认 `live=0` 仍是缓存。 | +| `CloudApiController.php:883-910` `vmStatus()`;`CloudInstanceRuntimeSyncService.php:8-15,39-187` | 详情页显式 live 刷新和后台 runtime sync 使用 Agent 观察并以 revision/CAS 写回 | Agent 不可用只标记 unavailable,不得伪造 stopped;这不是全量 guest 健康证明。 | +| `CloudApiController.php:812-825` `vmMetadataRows()`;`CloudInstancePageService` | 元数据只读面板数据库;没有旧 Engine fallback | 可作为新 schema 的 panel-owned projection,宿主动态状态另走 Agent。 | +| `CloudApiController.php:427-447`;`CloudAgentOperationStatusService.php:8-15` | UUID 使用 `cloud_agent_operations`;Agent result 经过固定 DTO allow-list | 同一 URL 的纯数字 id 仍读取 `CloudJob`,这是明确的过渡边界,不是已完成删除。 | +| `CloudAgentReadiness.php:5-59`、`CloudRuntimeHealthService.php:21-72`、`Command/CloudWorker.php`、`Command/CloudLifecycle.php` | worker/lifecycle 的默认 readiness 是 Agent 注册表/liveness;无 Python/SSH fallback | “Agent liveness”不等于 libvirt 域或网络可用;写操作仍需 Agent 自身 readiness/readback。 | +| `CloudDeploymentPageService.php:134-144`、`CloudApiController.php:1443-1475` | 用户 SSH 公钥 CRUD、指纹和归属完全由 PHP/数据库处理 | 见 C 节;公钥本身必须保留,私钥不能进入此路径。 | +| `CloudAdminController.php:55-62`(无 id 的 `GET /admin/hosts`)、调度/资源目录、账单/订单查询 | 这些特定读取/账务路径只读 PHP-owned 表 | 同一 controller 的宿主详情、测试、保存和模板操作仍是 B 类,不能按整个 controller 删除。 | + +## B. 需要 Go Agent 新 API 或 PHP 适配器的调用点 + +优先级说明: + +- **P0(阻止 Python/旧 worker 删除)**:面板仍可触发真实宿主变更,或会产生破坏性/计费后果; +- **P1(阻止完整功能切换)**:读路径、artifact、监控或后台管理仍依赖旧 Engine; +- **P2(控制平面收尾)**:更新代理、session introspection、旧配置清理等,不一定是宿主 VM API,但会阻止彻底删除旧 Engine。 + +### B1. P0:VM 生命周期、任务执行和生命周期策略 + +| 旧调用点 | 当前行为 | 必须新增/完成的替代 | 删除门槛 | +| --- | --- | --- | --- | +| `CloudJobService::enqueue()`(`web/app/Services/Cloud/CloudJobService.php:15-263`) | 在 `cloud_jobs` 写入加密 payload;`create`、`reinstall`、`rescue`、`delete`、`network_change`、`instance_settings` 等都共用旧任务格式 | 为每种 panel kind 定义 typed Agent operation、operation identity、desired projection、CAS/租约和结果投影;物理操作不得再把任意 method/resource 转发给 Engine | 所有写路由都只产生 `cloud_agent_operations` 或明确的 PHP 业务事件;不存在隐式旧队列 fallback;旧 numeric job 已完成终态核对 | +| `CloudWorkerService.php:30-39,89-169,208-315,470-927` | 轮询/租约 `CloudJob`,调用 `/internal/v1/operations` 或 `host()`,并在同一事务更新账单、IP、快照/防火墙状态 | 新 PHP Agent worker/dispatcher:按 typed kind 调 Agent,未知 transport 结果只 reconcile,不重放 destructive action;保留账务事务边界 | Agent operation journal、重启恢复、lease fencing、uncertain reconcile、退款/清理证据均通过真实宿主测试 | +| `CloudApiController.php:1290-1318` `reinstall()` | `CloudJobService::enqueue(..., 'reinstall', ..., '/reinstall', ...)`;包含镜像、公钥、root 密码 | `vm_reinstall`/artifact/seed/卷替换 typed API,定义旧卷清理清单、启动回读、凭据提交边界 | 新定义、磁盘/seed 身份、QGA/电源状态、失败清理和旧卷无残留均可读证 | +| `CloudApiController.php:1326-1383` `settings()`;`CloudAdminInstanceController.php:294-365` | 主机名、密码、公钥设置仍排入旧 `instance_settings` job | Guest settings API(hostname/password/public-key)和明确重启/readback;密码不得写入通用 Agent journal | Agent 支持同一公钥语义、秘密只进受控 secret 途径、重启后 guest/QGA 回读通过 | +| `CloudApiController.php:1386-1412` `rescue()` | GET 状态直接 `CloudEngineClient::host()`;进入/退出/force-start 排入旧 rescue job | rescue enter/status/exit/force-start typed API、救援 artifact、原 XML/网络策略恢复和电源回读 | 进入/退出幂等、未知结果 reconcile、网络与原域定义恢复证据齐全 | +| `CloudApiController.php:1423-1440` `delete()`;`CloudJobService.php:274-319` `enqueueExpiryDelete()` | 用户删除和到期销毁分别进入旧 delete/expiry_delete;payload 还携带删除磁盘语义 | Go `domain_delete` 仅是第一步;还需 storage/seed/network cleanup manifest、PHP CAS/tombstone、IP/账务收尾 | 先确认域 inactive/absence,再逐项清理并回读;任何未知结果都不能重放 `undefine` 或删除卷 | +| `CloudLifecycleService.php:265-285,347-384`、`CloudRenewalService.php:50-163` | 到期/流量策略依赖 `CloudJob` 状态和旧 `service_suspend`/`network_suspend`/resume 任务 | Agent target-state service/network operation(新网络架构),并将 billing desired state 与 Agent observed state 分开 | 跨重启/并发/CAS 验收;网络策略只在宿主 readback 后转为 active/blocked | +| `CloudAdminInstanceController.php:193,263-364` | 管理员公网换 IP、实例网络和设置仍进入 `CloudJobService` | 新网络/地址池 typed API;保留 PHP 公网账本,但由 Agent 应用受控 host dataplane 变更 | 目标 revision、地址池/实例绑定、宿主实际规则和失败回滚均可核对 | + +### B2. P1:旧 Engine 读写、artifact 和运维能力 + +| 旧调用点 | 当前行为 | 替代 API/适配边界 | +| --- | --- | --- | +| `CloudApiController.php:615-657` `vmListContexts()`、`675-689` `vmData()` | 对每个实例调用 `GET /vms/{uuid}`;这是用户 VM 列表/详情仍保留的旧 Engine 读 | 可先用已有 `domain_observe` 做有界 per-UUID 迁移,但应补 batch observation 或严格限流;静态面板元数据继续 DB-owned,不能把宿主 raw JSON 合并到 DTO。 | +| `CloudApiController.php:1124-1158` `metrics()`/`dailyTraffic()` | 读取旧 Engine 的 `/metrics` 与 `/traffic/daily` | Agent telemetry API 或 PHP 日志库的明确数据契约;必须定义时间窗口、采样、权限和 host-unavailable 语义。 | +| `CloudApiController.php:1169-1177` `consoleTicket()` | 旧 Engine 生成 console ticket | Agent 短期票据/WSS API;票据需绑定 agent/domain/actor、TTL、撤销和浏览器代理边界。 | +| `CloudApiController.php:1497-1505`、`CloudAdminController.php:315-334` | rescue 模板目录/导入仍按宿主调用旧 Engine | Agent artifact/catalog API;只返回公共 DTO,不暴露宿主路径。 | +| `CloudApiController.php:1518-1592` | user ISO import/list/status/delete 仍使用 `/internal/v1/user-isos*` | Agent artifact 下载/校验/删除 API,或明确由 PHP artifact worker 承担;必须有 sha256、owner、取消和孤儿清理。 | +| `CloudAdminController.php:201-312,337-386,390-492` | 云镜像模板目录、导入、删除、救援 ISO 上传、QCOW2 上传都调用旧 Engine;`CloudTemplateDeletionService` 还维护旧 job/generation gate | 新 artifact upload/import/replication API,面板只保存公共摘要和 `artifact_id`;上传完成、宿主复制、删除和失败清理都要有 durable operation。 | +| `CloudDeploymentPageService.php:176-191` | `freshTemplateCatalog()` 请求 `/internal/v1/vm-templates`,SSR 首次刷新依赖旧 Engine | 改为面板 catalog + Agent artifact replication read;缓存失效不能回到 Python。 | +| `CloudAdminHostNetworkService.php:30-32,80-125` | 公网地址池 desired revision 由 PHP 校验后调用 `host/network-pools/*` | 按新的数据面设计提供 Agent network apply/readback;当前 Go Agent 明确没有 WG/L3/network operation,不能假装已切换。 | + +### B3. P1:宿主注册、扫描、测试和保存 + +| 旧调用点 | 当前行为 | 替代边界 | +| --- | --- | --- | +| `CloudAdminController.php:47-52`;`routes_cloud.php:63`;`web/public/cloud/admin.js:364-368` | `/admin/hosts/scan` 接收 host/port,扫描 SSH host key/fingerprint | 改为 Go Agent enrollment/bootstrap(一次性 token 或受控证书签发)和 `GET /v1/health`/`capabilities`;不再扫描或信任 SSH 登录。 | +| `CloudAdminController.php:55-150`;`routes_cloud.php:118-120` | 宿主详情、保存、测试仍使用 `CloudEngineClient::host()`;保存时接受私钥并依赖 Engine 加密 | PHP 只登记 `cloud_agents` 的 `agent_id`、endpoint、协议版本、证书指纹和能力摘要;mTLS/HMAC 文件由 root-only secret provider 管理,Agent 不接受 SSH 私钥。 | +| `CloudAdminController.php:153-159` | `/admin/hosts/{id}/test` 调旧 `host/test` | 新 `agent/test` + capabilities probe;结果需去敏化并区分 liveness/readiness/host capability。 | +| `CloudAgentHostClientResolver.php`(当前 Agent 边界) | 已明确只读 `cloud_agents` + root-only secret,拒绝旧 `CloudHost`/SSH | 这是新注册表入口;在所有写路由接入前,不能删除旧宿主保存流程。 | + +### B4. P2:非 VM 操作但阻止彻底删除旧 Engine + +| 旧调用点 | 当前行为 | 替代/处理 | +| --- | --- | --- | +| `CloudInternalController.php:11-35`、`routes_cloud.php:4` | 使用 `CloudEngineClient::canonical()` 与 `engine_hmac_key` 做 session introspection 签名 | 改成 PHP 自己的 session introspection 签名/内部中间件,或在明确不再有 Engine 调用者后删除该路由;不能让 Agent 复用 Engine secret。 | +| `AdminUpdateController.php:10-141`、`routes_cloud.php:131-134` | 管理后台 update settings/check/apply/job 代理 `/internal/v1/update/*`;这不是 VM Agent API | 迁移到 PHP 的签名发布/更新服务或单独 updater control plane。它不应被塞进宿主 Agent;完成前 `CloudEngineClient` 仍有非 VM 调用。 | +| `CloudSetup::exportEngineConfig()` `web/app/Command/CloudSetup.php:168-193` | 生成 `engine.hmac`、`engine.json`、旧 data dir 和 `php_introspection_url` | 新 Agent bootstrap/secret 文件导出替代;删除前须确认所有部署 unit、配置、脚本和运行时目录均不再读取这些文件。 | +| `CloudEngineClient.php:7-346` | 旧 base URL、`/internal/v1` allow-list、Engine HMAC、SSH 私钥错误码和上传/host helper 的唯一实现 | 所有调用者迁移并通过静态检查后才可删除类、配置键和旧服务;不能仅因 UI 不再显示某按钮而删除。 | + +### B5. `CloudEngineClient` 直接引用的完整清单 + +下面是本次静态检索到的全部生产 PHP 直接引用(`CloudAgentClient` 中仅有“与旧类 +分离”的文档注释,不算运行时调用): + +```text +AdminUpdateController.php:5,22-25,77-141 + 旧更新代理;属于 P2,不是宿主 VM Agent operation。 + +CloudAdminController.php:9,52,59,65,99-136,158, + 229-262,334,380-381,478-483 + 宿主扫描/保存/测试、云/救援模板和上传;属于 P0/P1 宿主 enrollment + 与 artifact 迁移面。 + +CloudApiController.php:25,168,640-647,685-686,1134-1135, + 1153-1155,1175-1176,1393-1394,1497-1498,1522-1538, + 1557-1558,1588-1589 + VM 列表/详情、指标/流量、console、rescue、模板和 user ISO;属于 P0/P1。 + `safeUserIsoMessage()`(168)只是旧错误 DTO helper,迁移 ISO 后可提取为 + PHP allow-list helper,不应被误认为 Agent transport。 + +CloudInternalController.php:5,23,35 + 旧 Engine HMAC canonical/session introspection;属于 P2。 + +CloudAdminHostNetworkService.php:30-32,106-112 + 旧公网地址池 host API;属于 P0 网络数据面迁移。 + +CloudDeploymentPageService.php:179-183 + 旧全局镜像目录刷新;属于 P1 artifact/catalog 迁移。 + +CloudWorkerService.php:30-39,216-219,258-260,270-272,287-315 + 旧 operation 查询、策略 reconcile 和任意 host resource dispatch;属于 P0。 + +CloudEngineClient.php:7-346 + 旧 transport/allow-list/HMAC/SSH 错误码本体;所有外部引用归零后才能删除。 +``` + +对应的直接 `CloudJobService` 调用点也必须逐一清零或改为新 operation: + +```text +CloudApiController.php:33,446,1307-1308,1375-1376,1411-1412,1438-1439 +CloudAdminInstanceController.php:16,263-264,364-365 +CloudAdminInstanceService.php:337-343 # 历史标签/动作投影 +CloudAdminOperationsService.php:372 # 历史动作投影 +CloudLifecycleService.php:278 # 到期删除 enqueue +CloudJobService.php:13-419 # queue、expiry queue、DTO/query 本体 +CloudAgentOperationStatusService.php:13 # 仅注释/迁移边界,不是运行时调用 +``` + +## C. 必须保留的用户 SSH 公钥能力 + +以下是用户向**来宾虚拟机**注入公钥的业务能力,不是面板连接宿主机的 SSH。它应迁移到 +新的 typed Agent guest-settings/create/reinstall payload,但不能删除: + +| 位置 | 语义 | +| --- | --- | +| `routes_cloud.php:61-62`、`CloudApiController.php:1443-1475`、`CloudSSHKey.php`/`CloudSSHKeys.php` | 用户公钥 CRUD、指纹去重、owner 归属;必须继续只接受单行 OpenSSH **公钥**,拒绝私钥。 | +| `CloudOrderService.php:23,92-94` | 新购单通过 `guest_ssh_key_id` 解析为 `guest_ssh_public_key`;Agent create API 应接收已验证的公钥或 artifact identity。 | +| `CloudApiController.php:1296-1308` | 重装通过 `ssh_key_id` 解析公钥;新 reinstall API 需保留同样的 owner 检查和一次性凭据边界。 | +| `CloudApiController.php:1332-1372` | 实例设置的 `ssh_key_id` 解析为 `ssh_public_key`;新 settings API 需在重启/readback 后确认 guest 生效。 | +| `CloudAdminInstanceController.php:294-365` | 管理员设置可直接提交已解析的 `ssh_public_key`;新 API 仍需验证格式、权限和审计。 | +| `CloudJobService.php:38-59` | 旧任务对 `ssh_public_key` 做格式化;迁移到 typed API 前不能简单删除字段,否则会丢失来宾登录能力。 | + +必须同时满足: + +- Agent/新 schema 不保存宿主 SSH 私钥、私钥口令或用户私钥; +- 公钥只在必要的 guest seed/settings operation 中出现,日志、错误 DTO、通用 journal 和浏览器响应均做 allow-list; +- “删除 SSH”仅表示删除用户保存的公钥记录或撤销 guest 注入,不得误删宿主 Agent 的 mTLS/HMAC 资料。 + +## `CloudJob` 的迁移边界 + +`CloudJob` 不能按“旧代码”一次性删除,因为它同时承担三种不同责任: + +1. **物理执行队列(必须迁移)**:`CloudJobService::enqueue()`、`CloudWorkerService::tick()` 以及 + `CloudLifecycleService::enqueueExpiryDelete()`。这些记录携带旧 Engine method/resource,必须改成 + typed Agent operation 或明确的 PHP 业务 outbox。 +2. **业务关联与账务投影(可暂时保留)**:`CloudOrderService`、`CloudInvoiceService`、 + `CloudRenewalService`、`CloudAdminBillingService`、`CloudAdminOverviewService` 查询 job + 是否已创建/完成。迁移期间可以由 Agent operation projection 提供同形 DTO,但不能让这些查询 + 继续暗示旧 Engine 已成功。 +3. **历史展示/兼容 URL(最后删除)**:`CloudApiController::job()` 对数字 id 的分支、 + `CloudAdminOperationsService`/`CloudAdminInstanceService` 的历史列表。UUID Agent URL 已可用; + 数字 id 只有在旧任务全部进入终态、导出审计并关闭回滚窗口后才可移除。 + +直接引用清单(静态检索结果): + +```text +CloudJobService enqueue/display/action: + CloudApiController.php, CloudAdminInstanceController.php, + CloudAdminInstanceService.php, CloudAdminOperationsService.php, + CloudLifecycleService.php, CloudJobService.php + +CloudJob model readers/writers: + CloudAdminBillingService.php, CloudAdminInstanceService.php, + CloudAdminOperationsService.php, CloudAdminOverviewService.php, + CloudApiController.php, CloudAdminInstanceController.php, + CloudFirewallService.php, CloudInvoiceService.php, CloudLifecycleService.php, + CloudOrderService.php, CloudRenewalService.php, CloudSnapshotService.php, + CloudTemplateDeletionService.php, CloudWorkerService.php +``` + +`CloudSecrets` 的 payload 加密也不能与“新数据库不加密”混为一谈:新 Agent schema 的 +desired/observed/journal JSON 可以按新契约保存非秘密状态,但密码、token、mTLS/HMAC 私密材料 +仍须走 root-only/secret provider。删除旧 payload 加密前,必须先完成凭据脱敏、旧行终态封存和 +新 secret 生命周期设计,不能做全局替换。 + +## 删除 Python/宿主 SSH 的统一门槛 + +只有以下条件全部满足,才允许在独立、可回滚的提交中删除 `CloudEngineClient`、旧 Python +服务和宿主 SSH 运行时配置: + +1. **路由覆盖**:每个仍暴露的 VM/admin 路由都有对应 typed Agent operation 或明确的 PHP-only 说明;`rg` 不再发现 `/internal/v1`、`CloudEngineClient` 实例化或 `CloudJobService::enqueue()` 物理写入。 +2. **Agent 协议**:创建/重装/救援/删除清理/快照/防火墙/网络/console/artifact/metrics/traffic 均有版本化 API、白名单 payload、幂等键、operation journal 和 reconcile;unsupported kind 必须 fail-closed。 +3. **删除语义**:域、卷、seed、IP、firewall、账务和 panel tombstone 的 commit boundary/cleanup manifest/真实宿主 readback 全部可证明;Go `domain_delete` 的 `undefine` 单独成功不能当作整机删除成功。 +4. **数据库边界**:全新 Agent schema 已初始化并通过 CAS/租约/并发/重启恢复验收;旧 `cloud_jobs`、旧 operation id 不自动伪装成 Agent 状态。 +5. **宿主接入**:每个宿主有唯一 `cloud_agents` 注册、mTLS 证书指纹和 root-only secret 文件;面板不再接收、保存、转发 SSH 私钥,Agent 不再连接面板数据库。 +6. **安全清理**:`cloud_engine_url`、`engine_hmac_key/file`、`engine.json`、旧 data dir、旧 systemd unit、日志/定时任务和部署脚本都完成引用审计;旧 secret 先轮换/吊销再删除。 +7. **真实验收**:Go/PHP/浏览器合同测试通过,并在 103 宿主机及代表性宿主进行只读能力、VM 生命周期、失败/超时/恢复和回滚演练;不以静态测试或 HTTP 2xx 代替宿主 readback。 +8. **授权与回滚**:保留旧提交/发布物和操作审计,得到单独的删除授权;未知 destructive operation 不得靠重试“碰运气”。 + +## 验证限制 + +本次是静态审计,没有启动 PHP 应用、MariaDB、libvirt 或远程宿主;当前工作树没有可用的 +PHP/Composer 运行时,因此不能把本文件当作 PHP 全量测试通过证明。`go test` 只覆盖 Go +Agent 代码本身,不能证明 PHP 路由已切换或真实宿主行为。