diff --git a/docs/GO_AGENT_PYTHON_DELETION_PLAN.md b/docs/GO_AGENT_PYTHON_DELETION_PLAN.md new file mode 100644 index 00000000..3d30340a --- /dev/null +++ b/docs/GO_AGENT_PYTHON_DELETION_PLAN.md @@ -0,0 +1,166 @@ +# Go Agent 接管与 Python 删除计划 + +状态:`go-agent` 分支的迁移清单。本文是删除前的静态契约和验收门槛,不表示 +Python 已经可以删除,也不表示当前 Agent 已经覆盖生产能力。 + +## 删除范围和保留边界 + +当前仓库有 54 个已跟踪 Python 文件:26 个 Engine 运行时文件、27 个 Engine +测试文件和 1 个前端手工 fixture。只有在 PHP 路由全部切换到 Go Agent、真实 +宿主回读和回滚窗口验收完成后,才删除下面列出的 Engine 源码和测试。删除提交 +应单独完成,便于回滚;不要把行为迁移、数据库重写和大规模删除混在一个提交。 + +本计划不删除下列未跟踪文件,也不把它们纳入提交: + +- `deploy/test_host_cleanup_flow.py` +- `deploy/test_host_cleanup_network.py` +- `deploy/test_host_cleanup_vm.py` +- `deploy/virt-cloud-host-cleanup.sh` +- `docs/HOST_CLEANUP.md` + +`engine/.venv`、`__pycache__`、`.pytest_cache` 等安装依赖和缓存不属于版本化 +源码。它们不能提交,也不能用宽泛的递归删除命令清理;环境清理应另开维护任务, +给出精确路径和可恢复方案。 + +## 已跟踪 Python 文件分类 + +### Engine 入口、配置、鉴权、状态和持久化(14) + +| 文件 | Go Agent/PHP 替代边界 | +| --- | --- | +| `engine/virsh_panel/__init__.py` | 删除前确认无部署脚本导入;由 Go `cmd/` 入口替代 | +| `engine/virsh_panel/app.py` | HTTP 入口和路由由 Go Agent API 替代 | +| `engine/virsh_panel/internal.py` | PHP→Agent 的内部操作协议和 Go API 替代 | +| `engine/virsh_panel/engine_context.py` | Go Agent 请求上下文、宿主身份和 operation journal 替代 | +| `engine/virsh_panel/panel_state.py` | PHP fresh schema 的 desired/observed 状态替代 | +| `engine/virsh_panel/config.py` | Go Agent 配置;密钥仅 root-only 文件/credentials | +| `engine/virsh_panel/auth.py` | Agent mTLS/HMAC/key 文件协议替代 | +| `engine/virsh_panel/engine_security.py` | Go 安全边界、路径和日志脱敏替代 | +| `engine/virsh_panel/database.py` | PHP fresh schema 与 Go 本地 operation journal 替代 | +| `engine/virsh_panel/database_bootstrap.py` | `web/sql/cloud_agent_v1.sql` 和 Agent 初始化替代 | +| `engine/virsh_panel/update_worker.py` | PHP worker + Agent operation/reconcile 替代 | +| `engine/virsh_panel/updater.py` | Agent 发布和 systemd 更新流程替代 | +| `engine/virsh_panel/users.py` | PHP 用户、授权、订单逻辑替代 | +| `engine/virsh_panel/smtp_service.py` | PHP 通知服务替代;确认无宿主动作依赖 | + +### libvirt、宿主和 SSH 运行时(5) + +| 文件 | Go Agent/PHP 替代边界 | +| --- | --- | +| `engine/virsh_panel/libvirt_service.py` | Go typed libvirt executor;操作必须有 read-back/commit boundary | +| `engine/virsh_panel/remote_host.py` | Agent enrollment、mTLS endpoint、capability probe 替代 | +| `engine/virsh_panel/platform_network_policy.py` | Go Agent 宿主能力和新网络 typed executor 替代 | +| `engine/virsh_panel/ssh_agent.py` | 删除 SSH 运行时;密钥通信改为 Agent key + mTLS | +| `engine/virsh_panel/ssh_keys.py` | 删除宿主 SSH 凭据存取;用户 VM 公钥仍由 PHP 业务保留 | + +### VM、镜像、seed、控制台和救援(6) + +| 文件 | Go Agent/PHP 替代边界 | +| --- | --- | +| `engine/virsh_panel/cloud_init.py` | Go seed artifact;启动脚本含一次性 guest marker | +| `engine/virsh_panel/cloud_template_runtime.py` | PHP 模板业务 + Go image/seed executor | +| `engine/virsh_panel/cloud_templates.py` | PHP 模板目录业务;宿主执行部分移入 Agent | +| `engine/virsh_panel/rescue_templates.py` | Go rescue typed operation,包含电源、卷和回读 | +| `engine/virsh_panel/user_isos.py` | PHP 元数据 + Go artifact/storage 操作 | +| `engine/virsh_panel/console.py` | Go 短期 console ticket;PHP 只授权和返回前端票据 | + +### 指标和剩余 Engine 业务(1) + +| 文件 | Go Agent/PHP 替代边界 | +| --- | --- | +| `engine/virsh_panel/metrics.py` | Agent metrics/readback,PHP 负责展示和账期聚合 | + +### Python 测试(27) + +`engine/tests/` 下的 27 个 `test_*.py` 覆盖上述 Python 实现。迁移期间应把 +有业务意义的断言转为 Go unit/integration tests 或 PHP contract tests,再删除 +测试文件;测试文件本身不是替代实现的证据。文件清单为: + +```text +test_app.py test_auth_sessions.py +test_cloud_init.py test_cloud_template_runtime.py +test_cloud_templates.py test_config.py +test_console.py test_database.py +test_database_bootstrap.py test_database_http.py +test_engine_boundary.py test_frontend_page_layout.py +test_libvirt_service.py test_metrics.py +test_panel_state.py test_public_ip_pool.py +test_registration_http.py test_remote_host.py +test_rescue_templates.py test_smtp_service.py +test_ssh_agent.py test_ssh_keys.py +test_template_frontend.py test_update_worker.py +test_updater.py test_user_isos.py +test_users.py +``` + +`web/tests/manual/admin_sidebar_fixture.py` 是单独的手工 fixture;只有确认 +浏览器/布局测试没有读取它后才删除。 + +## PHP 调用点和接管顺序 + +旧调用点必须逐个切换到 `CloudAgentHostClientResolver`、`CloudAgentHandle`、 +`CloudAgentClient` 和 `CloudAgentOperationRepository`。页面、路由和外部 JSON +语义保持不变,宿主执行不再从 PHP 发 SSH 或访问 Python Engine。 + +| PHP 区域 | 迁移要求 | +| --- | --- | +| `CloudApiController`、`CloudPageController` | 保持用户页面和响应 DTO;VM 读写统一使用 Agent typed operation | +| `CloudAdminController`、`CloudAdminInstanceController`、`CloudAdminRuntimeController` | 管理页面保留;宿主扫描/测试/保存改为 enrollment、health、capability probe | +| `CloudAdminHostNetworkService` | IP 账本仍由 PHP;网络实际变更由 Agent `domain_network`,必须有 revision/read-back | +| `CloudAdminOperationsService`、`CloudLifecycleService` | PHP 负责授权、CAS、租约和展示;Agent 负责执行与 reconcile | +| `CloudWorkerService`、`CloudJobService`、`CloudRuntimeHeartbeat` | 消除 Engine readiness/SSH 分支;轮询 Agent operation ID,未知结果只读核对 | +| `CloudEngineClient`、`CloudEngineReadiness`、`CloudRuntimeHealthService` | 所有生产调用迁移后删除;不得保留隐式 Python/SSH fallback | +| `CloudInstanceRuntimeSyncService`、`CloudPanelUsageService`、`CloudTrafficService` | 改读 Agent 受限状态/指标;数据库写入由 PHP 完成 | +| `CloudOrderService`、`CloudSSHKeys`、用户/管理员授权服务 | 业务和用户 SSH 公钥仍属于 PHP;不能与宿主 SSH 凭据混淆 | +| `CloudSecrets`、`CloudAgentSecretResolver` | Agent key/mTLS 私钥只读 root-only 文件或 systemd credentials;DB 只存 ref/指纹 | + +删除 Python 前,`rg` 必须确认生产 PHP、命令、systemd 和 deploy 文件不再引用 +`CloudEngineClient`、`cloud_engine_url`、`engine_hmac_key`、`ssh_agent`、 +`qemu+ssh` 或 Python service。文档中的历史说明可以保留在迁移记录,但不能再 +成为运行时配置或部署步骤。 + +## 15 个 Agent operation kind 映射 + +以下是 PHP 对外能力对应的 typed Agent kind。当前 Go 首版已实现的 kind 用“已实现” +标记;`domain_preflight`、`domain_create_plan`、`domain_create_validate` 是创建 +流程的内部阶段,最终由 `domain_create` 统一承载,不向旧 Python API 做兼容映射。 + +| # | 新 Agent kind | 覆盖的旧能力/页面动作 | 当前状态 | +| ---: | --- | --- | --- | +| 1 | `capability_probe` | 宿主扫描、EFI/Q35、存储/QGA 能力 | 已实现首版 | +| 2 | `domain_read` | VM 详情、运行状态、XML 摘要 | 已实现首版 | +| 3 | `domain_create` | 创建、镜像/磁盘绑定、seed、define | 由三阶段协议组成,完整执行未实现 | +| 4 | `domain_power` | 启动、关机、强制关机、重启、暂停/恢复 | 已实现首版 | +| 5 | `domain_network` | 网卡挂载、私网/公网状态、服务暂停恢复 | 未实现 | +| 6 | `domain_settings` | CPU、内存、磁盘和设备设置 | 未实现 | +| 7 | `domain_reinstall` | 重装、旧卷/新卷切换、seed 重建 | 未实现 | +| 8 | `domain_delete` | 删除域、卷和失败清理 | 未实现 | +| 9 | `seed_prepare` | NoCloud seed、云镜像首次启动脚本 | 已实现 artifact 首版 | +| 10 | `snapshot_create` | 快照创建和冻结/解冻 | 未实现 | +| 11 | `snapshot_restore` | 快照恢复及电源/卷回读 | 未实现 | +| 12 | `snapshot_delete` | 快照删除及清理 | 未实现 | +| 13 | `firewall_apply` | 防火墙规则、revision/digest、回读 | 未实现 | +| 14 | `rescue` | 进入/退出救援、救援盘和恢复 | 未实现 | +| 15 | `console_ticket` | 控制台短期票据和 WebSocket 绑定 | 未实现 | + +每个 kind 都必须带 `operation_id`、幂等键、目标身份、期望状态摘要和 Agent +身份。破坏性动作只有在宿主 read-back 和 commit boundary 证据齐全时才返回 +成功;传输中断或清理未完成时返回 `uncertain`,PHP 以 operation ID reconcile, +不得盲目重放。 + +## 删除前验收门槛和回滚 + +删除提交前必须留下可审阅的证据: + +1. 15 个 kind 中所有仍暴露的页面能力均有 Go 实现、契约测试和真实宿主回读; +2. PHP 所有写路由和后台 worker 仅调用 Agent,静态扫描找不到 Python/SSH fallback; +3. 新数据库从零初始化,明文业务状态、CAS/租约、审计和 operation journal 通过并发测试; +4. create/reinstall/delete/snapshot/firewall/rescue/network 的 commit boundary、清理清单、未知结果 reconcile 已演练; +5. UEFI + q35 且 Secure Boot 关闭,云镜像启动脚本和一次性 marker 在来宾中验证; +6. Go `go test -race ./...`、`go vet ./...`、安全/依赖扫描通过;PHP 语法、Composer、MariaDB 和浏览器验收在具备运行环境时完成; +7. 103 宿主机仅做 Agent/API、能力、域 XML、存储的只读或测试域验收,禁止修改 bridge、路由、地址、nftables、firewalld、WireGuard 或 NetworkManager; +8. 保留删除前提交、发布物和回滚步骤;回滚只恢复面板/Agent 版本,不恢复旧数据库兼容层或重放未知破坏性操作。 + +任一门槛未满足时,只能继续迁移或修复 Agent/PHP 契约,不能删除 Python。删除 +动作应作为独立提交并在发布记录中列出精确路径,避免误删未跟踪 cleanup 文件、 +依赖环境或缓存。