# VPC v2 简化架构与迁移边界 状态:v2 目标架构仍是设计提案;2026-10-15 已完成一轮 v1 过渡硬化,尚未实现 Host Agent、mTLS、v2 schema 或执行后端迁移。 验证状态:本轮专项回归通过,但全量引擎仍有 28 项本轮未解决失败;具体测试名和 部署边界见 `docs/VALIDATION.md` 的 2026-10-15 记录。该快照已按收口决定停止继续 修改,不能作为生产已修复或可部署的验收结论。 审查基线:`venix` `86fa8f60865b37fa0f45cf620eedd453dcaa0494`。 适用范围:同地区、跨宿主机的 WireGuard + L3 私网。 ## 2026-10-15:v1 过渡硬化已经实现 本轮没有把现有 Python/SSH 执行器伪装成 v2,也没有增加第二个宿主写入者。它先把 最常导致成员加入、退出和根删除卡住的 v1 边界收紧,使当前生产链路可以安全运行到 真正的 Agent 迁移: - 新的成员加入、退出和含成员的根删除只接受所有受影响实例的最新持久化关机证据; VPC 不再自动关机、自动开机。旧 power workflow 仅用于核对历史操作,不创建新的 电源写入。 - PHP 在写入成员账本前完成停机预检;Engine 在任何宿主写入前再次锁定并核对本轮 revision 涉及的完整 VM 集合。一个实例重新运行会阻止整轮写入,而不是留下半数 宿主已更新、半数未更新的目标。 - 新 desired root、host 和成员目标在第一次远端写入前持久化。重启后的核对读取同一 operation/revision/digest,不依赖请求进程内状态。 - 宿主 apply/remove 只有在唯一、完整、严格匹配的 receipt 解析成功后才算已确认。 写入响应丢失、回执畸形或解析异常会保留 durable claim;后续只读核对不能重放写入。 - 一次 revision 的 VM/storage/root claim family 作为整体恢复。恢复先固定 family 大小和摘要,对每个成员及宿主执行只读证明,再用数据库 CAS 原子关闭;恢复过程中 发现新 desired bytes 时拒绝覆盖。 - 退出和根删除要求 persistent XML、cloud-init seed、bridge、route/rule、三类 nft 表、NetworkManager profile 或 ifupdown fragment、共享 Fabric state 和 WireGuard peer closure 的不存在性证明。NetworkManager 二进制缺失或 daemon 查询失败属于 未确认,不能被计数管道误判为 profile 数量为零。 - 旧记录缺少 `pending_member_mutations` 时仅在可证明的范围内迁移;空列表原样保留, 不完整记录重建完整成员 fence,畸形或歧义记录进入 `vpc_record_corrupt`,不会猜测。 - 宿主配置完成与来宾 QGA 健康继续分开。停机实例可以完成持久配置回读;开机后的 地址、路由和 link 状态作为运行健康继续核验,不把已经确认的宿主写入重新派发。 这些改动是 v1 到 v2 的安全桥梁。下文的单一 Host Agent、完整 host manifest、 executor epoch 和精简 schema 仍需按迁移门槛单独实现;当前部署仍保持单 Engine worker 和 Python/SSH 单写入者。 ## 结论 VPC v2 不再扩展当前 v1 状态机。目标只有一条路线:保留 PHP 业务控制面和 WireGuard + L3 数据面,把宿主机写入收敛到每台宿主机上的固定版本 Agent;租户 VPC 只提供自动 `/24`、隐式单子网、每实例一个 `/32`、同 VPC 默认互通和跨 VPC 默认隔离。 这是一项迁移设计,不表示 Go Agent、v2 schema、v2 API 或迁移工具已经存在。 生产环境在完成本文各阶段门槛前仍运行 v1。迁移过程中,一个宿主机只能有一个 写入后端;不能让 Python/SSH 与 Agent 同时修改相同的 libvirt、seed、WireGuard、 route 或 nftables 资源。 ## 为什么停止继续修补 v1 审查基线中,仅以下三个引擎文件已有 23,179 行: - `engine/virsh_panel/fabric.py` - `engine/virsh_panel/vpc.py` - `engine/virsh_panel/vpc_dataplane.py` PHP 的 `CloudVpc*` 核心文件合计 7,841 行;相关 Engine/PHP 测试约 39,542 行。 从 `887072ac61` 到审查基线共有 86 个提交、277 个文件变化和 113,920 行新增。 这些数字只用于说明当前维护面,不作为按行删除代码的目标。 复杂度主要来自多套正确性机制互相组合: - PHP 同时维护 VPC、子网、私网 IP、成员、route、ACL、宿主部署和 operation, 各层又有 desired/observed revision、digest、状态和 tombstone。 - Fabric、VPC、实例电源和来宾 QGA 各有独立状态,随后通过专用 worker、lease、 自动关机/开机工作流和周期 reconcile 互相推进。 - 每次成员变更既要处理宿主 bridge、route、WireGuard AllowedIPs、nftables、 proxy ARP、邻居、seed、persistent/live XML,又要适配 NetworkManager 与 ifupdown 的持久化和恢复差异。 - operation 的宿主配置完成、HTTP 回执、实例电源状态和来宾网络可用是四种事实, 当前页面和 worker 仍需要大量分支才能把它们收敛。 `docs/VALIDATION.md` 在 2026-10-14 的连续现场记录进一步显示,合法的多 VPC state 曾因重复 Fabric peer、route 校验范围、bridge 恢复顺序、helper 契约版本和旧 coordination claim 分别失败。同一数据面连续修复仍会产生新的状态组合,说明问题 已经超出单个条件判断或单次回读修复的范围。 ## v2 保留的保证 简化不能以放弃以下保证为代价: 1. PHP 仍是账户、授权、VPC/IPAM、实例归属和 operation 的业务事实源。 2. VPC 仍限制为同地区、全局不重叠的 RFC1918 `/24`;一个实例最多加入一个 VPC,每个成员只有一个唯一 `/32` 地址。 3. 每个写请求都有稳定 `operation_id`、幂等键、目标 generation 和摘要。响应丢失 时只查询同一 operation,不能用新 ID 猜测性重放。 4. 跨 VPC 默认拒绝;同 VPC 默认互通。宿主继续执行源 MAC/IP 反欺骗、IPv6 和 未登记目标隔离,公网 `public0/br0` 不被私网操作改写。 5. Agent 只管理带明确 owner 的 `wg-fabric0`、VPC bridge、route 和 nftables 对象。未知同名资源或外部漂移必须停止写入,不能自动接管或清空。 6. 成员加入必须精确回读 persistent XML、私网 MAC/bridge、宿主 route、 WireGuard AllowedIPs 和 nftables;HTTP 2xx 本身不代表配置成功。 7. 成员退出和 VPC 删除必须先取得所有受影响宿主的不存在性证明,再释放私网 IP 或 CIDR。超时和未知结果保留占用。 8. Fabric 是地区基础设施。宿主未完成 enrollment、握手、路由和重启恢复验收时, 不能承载新的租户私网。 9. 生产环境始终只有一个宿主写入者。切换后端本身也必须有持久 fence 和审计记录。 ## v2 删除或延期的机制 以下机制不进入 v2 首版: | 机制 | v2 处理 | | --- | --- | | 用户自定义 subnet CRUD | 删除;一个 VPC 只有一个与根 CIDR 相同的隐式子网 | | 用户自定义 route | 延期;首版只生成成员 `/32` 路由 | | 用户自定义 ACL | 延期;固定为同 VPC 双向允许、跨 VPC 默认拒绝 | | 自动关机、配置、自动开机 | 删除;加入和退出前要求实例已经完全关机 | | `CloudVpcPowerWorkflow` 多阶段 JSON | 删除;电源操作与 VPC operation 完全分离 | | QGA 作为 operation 成功门槛 | 删除;QGA 仅更新独立的 guest health | | `waiting_observed` 周期重试 | 删除;宿主结果在有界期限内进入成功、失败或 uncertain | | 每个子资源的 revision/digest/tombstone | 删除;根 generation、成员/IP tombstone 和 operation receipt 足够 | | 每个 VPC state 复制全 Fabric peer union | 删除;每台宿主只保存一份完整 host manifest | | 租户请求动态升级 Fabric/helper | 删除;Fabric/Agent 升级是管理员维护操作 | | NetworkManager/ifupdown 在线接管与 shadow 恢复 | 删除;Agent 只操作预先声明的自有对象 | | 多 Engine writer 或自动接管其他 writer | 延期;先保持单 writer,再单独设计分布式 fencing | 旧的自定义 route、ACL 或多子网不能通过兼容分支永久带入 v2。迁移审计发现这些 对象时,该 VPC 保持 v1 只读;管理员先将其收敛为 v2 固定能力,随后再迁移。 ## 单一路线目标架构 ```text 浏览器 -> PHP HTTPS/API - 账户、授权、IPAM - VPC/member desired state - operation 与 per-host receipt - 持久 worker -> mTLS -> Host Agent (AlmaLinux) -> mTLS -> Host Agent (Debian) Host Agent - 本机 durable operation receipt - 本机完整 desired manifest - libvirt persistent XML / private0 - wg-fabric0、精确 route/AllowedIPs - 单一 Agent-owned nftables table - 原子 apply、精确 observe、开机恢复 ``` 浏览器不直接访问 Agent,也不生成宿主命令。PHP worker 发送的是有界、带版本的 typed manifest,不发送 shell、raw nft 或任意 libvirt XML。Agent 根据固定产品合同 生成本机配置。 Fabric 在宿主 enrollment 或维护窗口中建立。每台宿主只有一个 `wg-fabric0`,peer、 endpoint、overlay `/32` 和密钥不随租户 VPC 操作变化。租户成员变更只更新完整 host manifest 中的 VPC bridge、成员 `/32`、peer tenant AllowedIPs 和固定隔离规则。 每份 host manifest 包含该宿主的全部有效 VPC,而不是一组互相聚合的 per-VPC state 文件。manifest 以单调 generation 和 digest 标识;Agent 只接受更高 generation,或 相同 generation、相同 digest 的幂等查询。相同 generation、不同 digest 必须拒绝。 ### 成员加入 1. PHP 确认实例完全关机,并锁定 VPC、实例和私网地址账本。 2. PHP 分配 `/32`,写入成员 desired state 和唯一 operation。 3. PHP worker 为所有受影响宿主生成完整 manifest,并使用同一 operation ID 派发。 4. Agent 原子应用并回读自己的 manifest,持久保存回执。 5. 所有受影响宿主 exact 后,operation 进入 `succeeded`,成员进入 `configured`。 6. 用户使用独立电源操作启动实例。QGA 可更新 `guest_state`,但不能把已经确认的 宿主配置重新变成“待回读”。 ### 成员退出 1. PHP 确认实例完全关机,成员进入单一 `removing` tombstone。 2. Agent 从受影响宿主的完整 manifest 移除成员,并移除 persistent `private0`。 3. 全部宿主证明 XML、route、AllowedIPs 和 nft 集合中均不存在该成员后,PHP 才把 私网 IP 标为可复用。 4. 任一宿主不可达或回执未知时,operation 为 `uncertain`,成员/IP 保持占用;不创建 第二个退出 operation。 ### 状态边界 v2 operation 只使用五种状态: - `queued` - `applying` - `succeeded` - `failed` - `uncertain` 成员把宿主配置和来宾健康分开: - `host_state`: `pending | configured | removing | uncertain | error` - `guest_state`: `unknown | stopped | online | mismatch` `guest_state` 是健康信息,不参与 IP 释放、隔离和 operation 成功判断。VPC 聚合页面 分别展示配置状态与来宾状态,不能再用一个“待回读”同时表示宿主未配置、实例未启动、 QGA 不可用和 HTTP 回执未知。 ## Host executor 单写边界 只把 VPC 网络交给 Agent、同时让 Python 继续直接修改同一宿主的 domain XML 或 seed, 会产生两个写入者,不能接受。v2 必须按宿主迁移完整 executor 边界。 建议为宿主增加: - `executor_backend`: `python_ssh | agent_v1` - `executor_epoch`: 单调 fencing generation - Agent identity 和证书指纹 当宿主为 `python_ssh` 时,Agent 只能 observe,不能 apply。当宿主切换为 `agent_v1` 后,所有可能修改 libvirt、domain XML、cloud-init seed、磁盘、快照、实例电源和本地 网络的操作都必须经 Agent。Python 可以在迁移期作为协议代理或只读兼容层,但不能绕过 Agent 直接写宿主。 executor 切换必须满足: 1. 该宿主没有 queued/running/uncertain 的 VM、VPC、删除、重装、快照或更新操作。 2. Python 协调锁和远端 systemd operation 均已取得终态证据。 3. Agent observe 与 PHP 实例/网络账本一致。 4. 持久写入新的 `executor_epoch`,旧 backend 收到旧 epoch 后拒绝写入。 5. 完成一次创建、开关机、重装、删除和 VPC 加入/退出的 canary 验收后,才开放该 宿主的新任务。 切换完成后不自动回退为 `python_ssh`。需要回退时先冻结宿主、证明 Agent 没有在途 写入,再以新的 epoch 执行独立迁移。 ## 立即止血 在 v2 可用前,先阻止 v1 继续产生新的状态组合: 1. 关闭新建 VPC、成员加入、成员退出、route/ACL 变更和 VPC 删除入口;保留现有 私网流量、只读页面和管理员证据读取。 2. VPC worker 停止领取新的 mutation,只允许对已经存在的 operation 做同 ID 只读 核对。不能批量点击“重新核对”制造并发任务。 3. 对当前三个“待回读” VPC 分别保存 operation ID、revision/digest、成员、宿主集合、 Engine receipt、远端 operation 和当前 XML/route/WG/nft 证据。 4. persistent XML 与宿主网络已经 exact、只是 QGA/guest 未确认时,归类为“宿主已配置, 来宾未知”,不再自动关机或开机。 5. 现场漂移或写入结果未知时进入维护队列,仍以原 operation ID 核对;不释放 IP、 不清理 claim、不新建 operation。 止血开关必须独立于普通维护页,部署更新不能顺带解除。恢复 v1 写入口不是 v2 迁移的 前置步骤。 ## v1 未决 operation 处理 迁移工具对每个旧 operation 只允许以下分类: | v1 证据 | 处理 | | --- | --- | | 已有 `succeeded`、`failed` 或 `superseded` 终态 | 原样保留,作为审计历史 | | `queued` 且 Engine、宿主 spool、systemd unit 都证明从未派发 | 以明确 `not_dispatched` 原因终结,不执行宿主写入 | | `running`、`waiting_observed`、`paused` 或 `uncertain`,可能已经派发 | 只按原 ID 读取 Engine/宿主结果;禁止创建 v2 替代写操作 | | 宿主配置 exact,仅缺 QGA 或 guest 启动证据 | 旧操作不伪装为 v1 成功;由 migration operation 接管当前配置,旧操作记录迁移关联并终结为 superseded | | 宿主不存在目标配置,且确证原操作未写入 | 终结旧操作后才允许进入 v2 migration | | 回执、现场或资源归属无法证明 | 将 VPC 标记为 `migration_blocked`,人工处理;不猜测成功或失败 | 旧 power workflow 不在迁移中自动恢复开机。迁移前记录当前真实电源状态;迁移只在实例 已经关机时修改网络,完成后由用户或独立电源任务决定是否启动。`original_running`、 `resume_cancelled` 和旧 child operation 只保留审计,不转换成 v2 自动动作。 七个无 operation、无资源的历史 uncertain claim 也不能因时间旧或资源列表为空而批量 删除。它们不直接转成 v2 operation;只有现有协调层能证明其未派发或已终结时才关闭。 ## 数据库只增不删迁移 首轮 schema 只增加字段和表,不删除、重命名或复用 v1 字段: ### 新增宿主字段 - `cloud_hosts.executor_backend` - `cloud_hosts.executor_epoch` - Agent identity、证书指纹和最后一次健康回读时间 ### 新增 VPC/成员字段 - `cloud_vpcs.backend_version` - `cloud_vpcs.migration_state` - `cloud_vpcs.migrated_at` - `cloud_vpc_members.desired_state` - `cloud_vpc_members.host_state` - `cloud_vpc_members.guest_state` ### 新增 operation 证据 - `cloud_vpc_operations.schema_version` - `cloud_vpc_operations.superseded_by_operation_id` - 新表 `cloud_vpc_operation_hosts`,保存 operation、host、executor epoch、manifest generation/digest、状态和有界 receipt 以下 v1 表在迁移期间继续保留,但对 `backend_version=2` 的 VPC 只读: - `cloud_vpc_subnets` - `cloud_vpc_routes` - `cloud_vpc_acl_rules` - `cloud_vpc_host_deployments` - `cloud_vpc_operations.power_workflow_json` - `cloud_vpc_operations.power_instance_id` `cloud_private_networks`、`cloud_private_cidr_claims`、`cloud_vpcs`、 `cloud_vpc_private_ips`、`cloud_vpc_members` 和 `cloud_vpc_operations` 继续承担地址与 审计保证,不在迁移中移除。 迁移完成后的表清理属于单独设计和单独发布。只有所有 VPC 均为 v2、所有 v1 operation 终态、所有 tombstone 收敛、备份和回滚保留期结束后,才能提出 drop migration。本文 不授权执行任何 drop。 ## 每个 VPC 的迁移资格 自动迁移前必须同时满足: 1. 根 CIDR 为受支持的 RFC1918 `/24`,CIDR claim 唯一且完整。 2. 恰好一个活动子网,且它与根 CIDR 相同。 3. ACL 只有平台默认的同 VPC ingress/egress 允许规则。 4. 没有用户自定义 route。 5. 每个成员恰好关联一个私网 IP lease,VM、host、MAC、IP 均唯一。 6. 没有 `deleting` 子资源、未完成 tombstone 或无法解释的 host deployment。 7. 没有 queued/running/waiting/paused/uncertain 的 v1 operation。 8. PHP desired、Engine desired 和所有宿主实际状态能够生成相同的 v2 manifest。 任一条件失败时保持 v1 只读并输出具体阻断原因,不自动删除数据来满足资格。 ## 分阶段实施与门槛 ### 阶段 0:冻结和现场分类 - 部署 v1 mutation kill switch。 - 固定并核对当前未决 operation。 - 导出数据库与各宿主受管网络/operation 清单。 门槛:没有新的 v1 mutation;所有现有 operation 都有唯一分类和负责人。 ### 阶段 1:只增 schema 和 Agent observe - 应用新增 schema,旧代码仍能运行。 - 部署 Agent,但 `executor_backend=python_ssh` 时只能 observe。 - Agent 生成 host manifest 和 drift 报告,不执行写入。 门槛:AlmaLinux 与 Debian 的 observe 结果均与当前 XML、route、WG 和 nft 现场一致; Agent 重启不改变任何宿主状态。 ### 阶段 2:完整宿主 executor canary - 选择隔离测试宿主,清空在途任务并提升 `executor_epoch`。 - 把该宿主全部写操作切换为 `agent_v1`。 - 执行 VM 创建、开关机、重装、救援、快照、删除和 VPC 全生命周期。 门槛:同一宿主不存在第二个 writer;响应丢失、Agent 重启和面板重启均通过原 operation 收敛;公网功能无回归。 ### 阶段 3:新建 v2 VPC canary - 仅向 canary 账户开放 v2 创建和 stopped-VM 加入。 - 使用至少一台 AlmaLinux 和一台 Debian 宿主完成跨宿主测试。 - 使用一台 QGA 正常 VM 和一台 QGA disabled/unavailable VM。 门槛:两台 VM 的宿主配置 operation 都终结;QGA 不可用的 VM 显示 `configured + guest unknown`,不能停在“待回读”。 ### 阶段 4:迁移现有 VPC - 对通过资格扫描的 VPC 生成 migration operation 和完整 per-host manifest。 - 所有成员停机后写入目标 seed/XML,Agent 应用并精确回读。 - 在同一数据库事务中把 VPC `backend_version` 切换为 2,并记录旧 operation 关联。 门槛:切换前可无写入回退;切换后只有 Agent writer。任一宿主失败时不翻转版本,保留 地址与旧数据。 ### 阶段 5:关闭 v1 写路径 - 全部 VPC 迁移后永久关闭 v1 worker、自动电源工作流、旧 Fabric/VPC mutation API。 - Python v1 VPC reconciler 仅保留有界审计读取,随后独立删除代码。 门槛:数据库中没有 v1 活动 VPC、非终态 operation、未收敛 tombstone 或 v1 executor 宿主。代码删除和数据库 drop 不与该阶段合并。 ## 回滚边界 - `backend_version` 翻转前,Agent 只 observe 或执行可证明的 canary;可以撤回 Agent 代码而不改写业务账本。 - host executor 或 VPC 翻转后,不能直接部署旧代码并恢复 Python/SSH 写入。旧 writer 不认识新的 epoch、manifest 和 operation receipt,自动回退可能覆盖已应用状态。 - 翻转后的故障采用 forward-fix:冻结该宿主/VPC,读取同一 operation,修复 Agent 或 manifest,再以相同 generation/digest 收敛。 - 代码回滚包必须认识 v2 schema 和 kill switch,即使它暂时不开放新操作,也不能把 v2 行当成 v1 行处理。 ## AlmaLinux 与 Debian 真实验收 以下项目必须在真实宿主执行;模拟测试、Shell 语法和 HTTP 成功不能替代: ### 宿主前置和 Fabric - AlmaLinux 与 Debian 使用相同 Agent 协议和 manifest 语义;发行版差异只留在 Agent 的本地适配层,不改变成功条件。 - 预检 kernel WireGuard、nftables、libvirt、SELinux/AppArmor、时间同步、MTU、UDP underlay 和证书权限。 - Agent enrollment、证书轮换、升级、重启和宿主 reboot 后,`wg-fabric0`、peer、 endpoint、overlay route 和 owner 证据完全恢复。 - 私网操作前后,公网 bridge、默认路由、管理 SSH 和已有 VM 公网连通保持不变。 ### 成员配置和流量 - 停机实例加入后,persistent XML、private0 MAC/bridge、seed、宿主 `/32` route、 WG AllowedIPs 和 nft 集合精确一致。 - 启动与 VPC 配置是两个 operation;启动失败不能回滚已确认的宿主网络。 - QGA enabled、disabled、unavailable 三种镜像都能终结配置 operation,只有 guest health 不同。 - 同机和跨机分别验证双向 ICMP、TCP 和 UDP;验证跨 VPC 拒绝、伪造 MAC/IP 拒绝、 IPv6/广播/多播边界和访问宿主服务边界。 - 至少创建三个 VPC,并依次向每个 VPC 添加新实例,不能出现共享 state 污染或全部 进入同一个“待回读”状态。 ### 故障与恢复 - 丢失 apply HTTP 回包后只查询原 operation;Agent 不能重复执行同一 generation。 - 在 manifest 落盘前、宿主写入中、写入后回执前分别中断 Agent,确认结果只会收敛为 succeeded、failed 或 uncertain,不出现第二个 writer。 - 面板、worker、Agent 和宿主分别重启后,原 operation 与本地 receipt 能重新关联。 - 一台宿主离线时,新成员不宣称 configured;已有成员流量和其他 VPC 不被无关重写。 - detach 只在全部宿主 absence proof 后释放 IP;中途失败时原 IP 仍不可分配。 - Agent 遇到未知 bridge、route、WG peer 或 nft owner 时停止写入并给出有界错误, 不执行自动清理。 ### 完整生命周期 executor canary 还必须验证创建、删除、重装、救援、快照、开关机、配额断网和到期清理。 这些路径可能修改 XML、seed、磁盘或网络;缺少任一项就不能证明 host executor 已经安全 从 Python/SSH 切换到 Agent。 ## 发布完成标准 只有同时满足以下条件,才能宣布 v2 可替代 v1: - 当前三个待回读 VPC 已按原 operation 分类并安全终结或明确阻断。 - AlmaLinux 与 Debian 的 canary host 已完成 executor 全生命周期验收。 - 三个独立 VPC 连续添加实例成功,QGA 不可用不会阻塞宿主配置终态。 - 跨宿主允许流量、跨 VPC 拒绝、反欺骗、公网无回归和宿主 reboot 均有实机证据。 - 响应丢失、服务重启和部分宿主失败均只使用原 operation 收敛。 - 所有生产 VPC 已标明 v1 或 v2,且每个宿主只有一个 executor writer。 - v1 写入口已关闭,但 v1 数据尚未删除,可继续审计和恢复。 在这些门槛完成前,本文只能作为实施边界,不能作为“Go Agent 已上线”或“VPC 已完成 重构”的证明。