22 KiB
VPC 私网数据面宿主机验收矩阵
代码侧已经验证计划解析、稳定私网 MAC、cloud-init 多网卡、生成脚本的 POSIX
语法和 typed readback contract。当前开发环境没有 ip、wg、nft、nmcli、
ifquery 或 libvirt daemon,因此下面的宿主机步骤不能在本机冒充通过。
应用前证据
在每台同地区宿主机保存 Fabric active 的新鲜回读,并确认:
wg-fabric0由 Fabric owner marker 所有,Fabric 锁可用,IPv4 forwarding 已启用; readiness 分别显示rp_filter的all/default、实际 endpoint 接口和wg-fabric0raw/effective 值,并按max(all, interface)核对有效值。Alma/RHEL 的default=1与公网 endpoint 接口 strict1是可保留的正常策略,不能据此 阻断 VPC,也不能要求面板改写全局或公网接口;平台拥有的wg-fabric0必须在 承载流量前持久化并回读 raw/effective2。尚未创建时应明确显示待自动配置, 动态vnet*/tap 不参与该门禁;- AlmaLinux 10 只有 NetworkManager/nmcli 处于 active/enabled,Debian 13 只有
ifupdown 的
ifup、ifdown、ifquery和/etc/network/interfaces(含已加载 的interfaces.d)作为网络管理来源; - 防火墙精确处于 Fabric 已确认的
native_nftables模式;nft命令可用、规则集可读,持久主配置只有一个受管 include, firewalld 不存在或 inactive+masked,且没有遗留inet firewalldtable。任何旧firewalld_nftdesired/manifest/journal 都必须阻断普通 reconcile,不得自动迁移; stocknftables.service状态只作诊断,不参与 readiness; - NetworkManager profile 不 autoconnect、不写 zone;ifupdown fragment 不含
auto。wg-fabric0和 VPC bridge 只在受管 nft ACL 精确回读后激活,不依赖任何 firewalld zone/trusted 状态; - Fabric 公网或内网 endpoint 均不位于全局租户 VPC CIDR 池,且当前 VPC CIDR 不包含
任一 Fabric endpoint;否则目的策略路由会吸走 WireGuard underlay,必须在 apply 前阻断;
/etc/virt-cloud、/run/virt-cloud、/etc/nftables.d和sysctl.d不是符号链; br0、管理接口、默认路由和未知 nft 规则的快照已经保存。
旧 helper 和邻居状态的升级顺序
新增 local_neighbor|IPv4|MAC 前,所有相关宿主机上的
/usr/local/libexec/virt-cloud-wg-fabric 必须已包含
# vpc-local-neighbor-contract-v1。旧 helper 会拒绝新状态记录;仅升级面板代码
不足以完成宿主机迁移。Fabric observer 会把缺少该标记的同摘要 helper 判为需要
修复,但旧 state 未记录邻居、运行时却存在普通邻居时,完整 reconcile 仍可能因
无法证明这些绑定而停止恢复。因此不能把普通公开 reconcile 当作所有旧环境的
自动迁移入口,更不能通过忽略未知 MAC 或删除邻居绕过检查。
已有旧 state 的环境采用受控两阶段升级:
- 暂停面板 VPC worker、引擎后台协调和相关 Fabric timer,确认在途任务已结束。 有未确认操作、事务目录或持久锁时,先保留并核对原操作证据,不直接清理。
- 固定当前 Fabric desired 摘要、宿主机标识与 SSH 指纹,保存旧 helper 的 SHA256、 owner/权限及相关配置快照。从已审阅版本按同一计划生成对应宿主机的新 helper。
- 在维护互斥和 Fabric 锁内,确认旧 helper 为 root 所有的普通文件、权限
0700, owner、计划摘要和旧 SHA256 均精确匹配,且不存在活动网络事务。备份旧文件, 验证新文件语法、契约标记及审阅时的新 SHA256,再仅原子替换 helper。此阶段 不执行组网、不改 unit、drop-in、libvirt 启动项或启动依赖,也不生成新密钥。 - 所有相关宿主机的 helper 更新并回读后,恢复原 Fabric timer、引擎与 VPC worker。
Fabric readiness 要求 timer 为 active;持续暂停 timer 会关闭 VPC 的 Fabric gate,
因而不能等待新 state 出现后才启动它。引擎自身会周期核对已生效 VPC,
不需要为迁移重新保存相同 ACL 或手工修改数据库任务。通过原 VPC 操作推进当前
desired revision/digest。由正常应用事务写入邻居绑定、恢复运行时
PERMANENT项并 完整回读;未知绑定仍须停止处理。不得手写 state 或数据库成功状态代替迁移。 - 新 state 和运行时证据一致后,确认原有 worker/timer 调度持续正常,检查多个 后台周期中的桥、tap、路由和邻居稳定性,再执行同机、跨机流量验收。 helper 发布成功本身不代表 VPC 或来宾网络已经可用。
成员接入和回读
对一个跨两台宿主机的 VPC,至少放置两个成员和一个 ACL,逐台检查:
镜像前置契约:安装并启用 qemu-guest-agent,domain 存在 agent channel,
guest-info 中 guest-exec 与 guest-exec-status 均为 enabled;镜像必须提供
/usr/bin/timeout、/usr/bin/head、/bin/sh 和 /usr/sbin/ip。不要假定发行版默认允许 guest-exec:Alma/RHEL
系列镜像或加固策略可能在 QGA blocklist 中禁用它,必须逐镜像实际核对。任何一项缺失
都应得到 vpc_private_guest_probe_unsupported(或 unavailable),成员不得 usable。
-
运行中 VM 首次加入,或其 MAC、私网 IP、VPC CIDR 变化时,引擎不得改写 NoCloud seed、 inactive XML,也不得对 live domain 执行私网网卡热插/热更新;旧配置必须原样保留。 VM 完全停机后由下一次 reconcile 写入 seed 与 inactive XML,再执行完整 start。 在完成该 stop/reconcile/start 流程前,宿主状态必须是
applying、回读为pending_restart、错误码为vpc_private_guest_restart_required,且 VPCusable=false。普通 guest soft reboot 不能替代 libvirt stop/start。如果随后撤销尚未实际接入的成员,运行中 VM 只在 live/inactive XML 均无私网网卡 和 metadata、唯一受管 seed 也无私网配置,且重复只读核验一致时允许确认已不存在。 仍有真实私网配置、未知 CD-ROM/seed 或未核销的 QGA launch/PID 账本时继续要求 停机;不得把 HTTP 取消、网卡缺失或本地线程结束当成来宾进程已退出。
用户页应显示完整操作顺序:停机、对原 VPC 操作执行“核对/重试”、再启动并核对 来宾网络。创建、加入和移除的明确失败均可在前提修复后显式核对,必须保持原 operation/revision/digest,不能重建任务掩盖未知结果。删除前后核对 member 与 IP 账本,缺少真实清理证明时仍保留占用。成员有 queued/running/uncertain 实例任务 时,普通 VPC 修改应拒绝并回滚,先核对原任务;不自动终结旧电源任务。
-
生成的 bridge 名称、owner/state/proxy 文件均为 root-only,bridge/tap 没有 地址、网关或 DNS;
private0产品角色对应的 libvirt alias 是ua-private0,其 bridge、稳定 MAC、/32和持久/实时 XML 都一致,私网接口 不绑定公网clean-trafficnwfilter。 -
QGA 回读必须找到唯一的 guest 接口名与 MAC,精确 IPv4 地址只有目标
/32;固定 sysfs 探测必须同时确认接口 flags 含IFF_UP、operstate=up、carrier=1。 接口 down 后即使地址和路由仍保留也必须返回vpc_private_guest_link_mismatch,不能通过 usable 门禁。显式 network suspend 则以 persistent/live XML 都为 down 证明隔离,并保持成员 non-usable。 -
宿主机上的每个成员
/32和每条自定义/32route 都带 panel route protocol、正确 device/table、via和 metric;不存在 VPC CIDR、默认路由或宽前缀的替代项。 来宾 main table 的目标 route 必须只有一条 exact scope-link VPC CIDR,不能含 gateway、 nexthop、linkdown、dead或unresolvedflags;成员或自定义 route 变化不得改变 兄弟 VM 的 guest generation。历史逐成员/32seed 只能在完全停机后迁移。 -
wg show wg-fabric0 allowed-ips的每个 peer 与完整期望集合一致:overlay/32加精确 tenant/service/32,没有0.0.0.0/0、宽前缀或其他 VPC 的未授权地址。 -
nft inet/bridge/arp 三张表的 owner marker、chain priority、ACL comments、 anti-spoof、IPv6/广播/未知目的 drop 和精确 proxy-ARP set 均能被 observe 回读。 bridge 上通用
proxy_arp=0、同桥下一跳所需的proxy_arp_pvlan=1、rp_filter=2,代理项集合与 route destination 集合 完全相同;其他地址的 ARP reply 必须被过滤。 observe 还必须以计划携带的fabric_plan_digest重建并核验 Fabric table grammar、 owner/digest、精确 tenant set 和完整 stateless snapshot;Fabric revision 或任一租户 AllowedIPs 漂移时,即使本 VPC 三张表未变也不得报告 active。 每个本机成员还必须存在精确的private_ip → private_mac普通 IPv4 邻居项, 状态为PERMANENT;它与 proxy ARP 项是两类独立证据。绑定写入受管 state 的local_neighbor记录,并在网桥 down/up、回滚和 Fabric 恢复后重新回读。 缺失、错误 MAC、未解析或动态邻居状态不能替代这项证明。旧 state 可读取以便 迁移,但必须经当前计划应用并验证后才能重新报告可用。 -
从同机和跨机成员分别验证允许的 TCP/UDP/ICMP 流量、ACL deny、伪造源 MAC/IP、 IPv6、广播/多播和访问宿主机自身地址。验证结果同时记录 guest route、宿主机 route、WireGuard handshake 和 nft counter,不能只看页面的
active。
管理器和重启矩阵
已有运行中成员时,重复 apply/reconcile 必须保留 bridge 的 ifindex、完整 tap 集合和
NetworkManager 原连接 UUID。隔离前先记录路由、proxy ARP 和 sysctl;不能通过
nmcli device set ... managed no、停用连接或再次 connection up 隔离活动网桥,
因为 NetworkManager 的清理会解除 libvirt 创建的 tap 从属关系。已有端口的 NM 网桥
只在身份和活动连接均可证明时使用 link down/up;任何拓扑漂移均保留事务并拒绝继续。
空桥或冷启动仍按后述管理器流程恢复。验收重复核对与失败回滚时,必须比较操作前后
的 tap master、桥 ifindex、连接 UUID、路由和 proxy 项,不能只检查接口 UP。
成功应用凭据只用于减少相同计划的重复写入。它在当前引擎进程内有界保存,绑定 宿主机 SSH 配置代次、目标与指纹、完整应用脚本摘要和成功事务中取得的三张 nft 表摘要。后续每次尝试复用都必须重新读取宿主机配置、持久文件、Fabric/WireGuard、 路由、规则、proxy ARP、普通永久邻居及完整 nft 摘要;全部一致才跳过再次应用和 bridge down/up。SSH 超时、非零退出或无效凭据等已传播的读取异常会丢弃凭据并返回 失败,不在该次请求中改写网络;回读不匹配、进程重启、缓存淘汰或计划/代码/SSH 代次变化则需要重新完成受保护的应用。部分旧观测分支仍将子命令失败汇总为 不匹配,不能把这项优化描述为能够区分所有底层读取故障与真实配置漂移。
该凭据不是 active、usable 或来宾核验结果;复用路径仍返回 applying/pending,
后续 XML、seed、QGA 链路、地址和路由核验照常执行。验收既要证明多个协调周期不再
无故扰动健康网桥,也要证明邻居或 nft 漂移会触发安全修复、读取超时不会派发写入,
且停机或 QGA 不可用的成员不会因已有应用凭据被标记为可用。
AlmaLinux 10:执行 nmcli connection reload、systemctl restart NetworkManager、
panel-owned Fabric service/timer 修复测试和宿主机重启。不要用 stock
nftables.service 的 start/reload/stop 作为验收步骤。每一步都要确认 private bridge
没有靠 autoconnect 抢先启动,helper 先恢复并回读 nft inet/bridge/arp ACL,再按 UUID
激活 profile;过程不应出现 firewalld zone/trusted 依赖;随后
route/rule、proxy ARP、WireGuard peer、
ua-private0 XML 和默认公网路径恢复,NetworkManager 没有接管 br0 或管理接口。
Debian 13:执行 ifquery <private-bridge>、systemctl restart networking、
panel-owned Fabric service/timer 修复测试和宿主机重启。不要启动或重载 stock
nftables.service。确认不含 auto 的 interfaces.d
fragment 不能让 bridge 绕过 helper 抢先启动,ACL 精确回读后才执行
ifup --force,且不应出现 firewalld zone/trusted 依赖;随后 route/rule、
proxy ARP、WireGuard
peer 和 ua-private0 XML 恢复。严禁用 ifdown 操作 br0 或管理接口。
两种发行版都要分别测试 libvirt service、socket activation 和 VM autostart。组网前后
比较 libvirtd.service、virtqemud.service、virtproxyd.service、
libvirt-guests.service 及 sockets 的 unit、drop-in、启动状态和依赖:平台不得添加
Fabric 依赖、改变 enable/mask 状态或启动/重启这些服务。Fabric 故障不得阻断原有
libvirt 控制面和无私网 VM。私网隔离由受管 nft ACL、bridge quarantine 和
ACL-first helper 承担;带私网 VM 在 bridge 尚未恢复时的启动失败应按该 VM 核验,
不能用修改整个 libvirt 的依赖解决。
路由验收同时使用裸 IPv4 与 /32 两种 host-route 输出,以及按 dev 过滤后省略
设备字段的输出;只有带设备过滤的查询可补回该设备,无过滤列表不得猜测设备。
错误设备、重复路由、特殊路由类型、宽前缀、多路径和未知/重复 flags 都不能通过回读。
停止最后一个成员后,明确受管的私网 bridge 可以因没有运行中的 tap 而出现单个
linkdown;路由身份仍须完全匹配,回读保留 routes[].flags=["linkdown"],只证明
配置存在,不证明网络可用。WireGuard 路由及 guest 路由仍不接受 linkdown。
验收需覆盖停机首次加入、启动、停止最后成员、停机重试修改和再次启动;停止时允许
配置核验通过,但 host 和对应成员不能借陈旧 QGA 成功状态变成 active/usable,启动后
必须同时取得无链路异常的路由和新的 guest 证据。
实际执行生成的 observe 路由片段,不能仅用 sh -n 检查嵌入的 AWK。
宿主路由归属查询使用 ip -N 的数字协议、scope 和 table,避免协议 186 被输出为
bgp 或本地自定义名称而误拒自己的路由;QGA 固定 dev 查询也须覆盖 JSON 省略设备
字段的实际输出。依据 iproute2 路由输出实现
和 数字协议名称实现,仅归一化
查询本身已经确定的身份,不能从无过滤输出猜测设备或路由归属。
故障回滚
在隔离环境中分别让 ip link、ip route、ip rule、ip neigh、wg set、
nft -c、nft -f、NetworkManager/ifup、sysctl 或 libvirt define/seed 上传在
每个阶段失败。预期结果是:
- apply、实例接入和停机 libvirt 变更失败时,原 panel-owned bridge、route/rule、 peer AllowedIPs、nft 表/include、proxy 项、sysctl、XML 和 seed 按快照恢复;
- apply/remove/rollback/journal 恢复必须以单次 nft batch 建立或恢复受管 table;只有 marker/digest 精确回读后才能重新激活接口,不能用分离的 table delete/load 暴露无 ACL 窗口;
- boot 对 panel-owned bridge 执行 hard quarantine 时,必须在 down 前后严格核对有界端口
快照并回读确认
UPflag 消失;bridge 命令/解析失败、端口变化或 NetworkManager 竞态 重新拉起接口都必须停止恢复且不得继续改写 nft,不能靠停用 profile 拆除 tap; - 删除/撤销路径使用阶段 journal 和 fail-closed 收敛:未提交的 journal 在回读前
返回
uncertain/manual_reconcile并保留现场,不重复执行破坏性删除;只有已经 提交且能证明面板资源全部不存在的 journal 才会被清理。因此删除路径的“回滚” 是可审计的停机与人工核对边界,不是假设资源可以自动恢复; - 事务开始前或最后 precommit 回读已存在的外部 bridge/profile、未知 route、未知 ARP proxy 项和未知 nft 规则不被删除;同机 root/CAP_NET_ADMIN 与 out-of-band nft 管理器 必须遵守维护互斥,因为 nft CLI 不提供跨进程 compare-and-swap;
- 恢复本身失败或响应丢失时返回
uncertain/degraded,保留事务目录供下一次 readback,绝不返回成功; - 重试只依据新的完整宿主机回读,不对不确定的 libvirt 或网络变更盲目反向执行。
跨宿主机最后还要单独验证 underlay 公网防火墙、NAT、MTU、SELinux 和 UDP 监听。
Fabric/VPC 的 panel-owned nft 表不负责放行 underlay UDP;运维必须在宿主
持久 native nftables 规则或上游云安全组/防火墙中,以精确 peer 源地址、
本机 endpoint /32、UDP 和 Fabric 监听端口放行。还需单独核对外部 DNAT,
并用双向握手和实际流量验收;接口 active 或 unit green 不能证明端到端可达。
成员已获得地址但不能通信
VPC ACL 默认拒绝,未配置允许规则时,同机和跨机成员都不会自动放行 ICMP。
先从成员 VM 发起有限次数的测试,核对 VPC default-deny 计数;宿主机自身对租户
地址发起的 ping 还可能被 host-isolation 规则拒绝,不能用它替代 VM 间验收。
需要互通时,通过原 VPC ACL 接口保存明确的源、目标、方向和协议规则,并核对
双向请求与回复。不要临时插入无归属 nft accept 规则或停用防火墙来宣告恢复。
ACL 已允许仍不通时,同时抓取 WireGuard 和私网 tap 上的 ICMP/ARP。无 IPv4 地址的
私网桥可能选择宿主机公网地址作为 ARP 请求源;来宾启用严格 rp_filter 时,该源
的反向路由经公网接口,ARP 请求可能被丢弃。此时转发规则命中 accept 也不能证明
下一跳已解析。修复使用计划绑定的本机成员永久邻居,不改来宾全局或私网接口的
反向路径校验。仅手工运行 ip neigh replace ... nud permanent 不构成持久修复:
网桥被置为 DOWN 后内核会删除这些项,应用与恢复流程必须重新建立并验证。
验收应覆盖多个后台协调周期,并比较同机与跨机 TCP、UDP、ICMP,不能只记录一次 ping。
“地址可见”和“来宾核验成功”也不同。当前 QGA 核验同时要求私网 MAC、链路状态、
/32 地址和精确 scope-link 路由。启用 guest-exec/guest-exec-status 后,SELinux
仍可能拒绝代理执行 /usr/sbin/ip;命令管道末尾的 head 成功会使 exitcode 为 0,
但 stderr 中仍有拒绝信息,必须保持未核验。应检查该次 AVC 和程序标签,不能只凭
exitcode 标记成功,也不能默认关闭 SELinux 或让整个 QGA 不受限制。来宾执行权限
和 VPC ACL 是两个独立检查项;改变其访问范围前应由运维明确批准。
若 AVC 已证实代理域为 virt_qemu_ga_t、/usr/sbin/ip 的标签为
ifconfig_exec_t,可以在获准的来宾中安装只针对这两个类型的本地 SELinux 模块,
允许文件 getattr open read map execute execute_no_trans。安装前保存模块列表与
原代理配置;安装后必须保持 getenforce=Enforcing、
virt_qemu_ga_run_unconfined=off,再从宿主实际调用 QGA 固定路由探针,检查退出码、
标准错误和完整路由内容。该类型许可不能限制命令参数,不应当作任意镜像通用策略
或自动下发给未经批准的来宾;标签不同的发行版须重新依据 AVC 判断。
发布和规模边界
- 先应用包含 VPC evidence version 字段的数据库 schema,再发布 PHP/worker,最后发布
engine。历史或混合版本 receipt 没有
evidence_version=2时必须重新 reconcile,不能 继承旧 active/usable。 - 用 1、32、256 个成员和至少两台宿主分别压测正常、QGA command disabled、QGA
timeout 三种场景。引擎的协作式探测预算到期后必须停止提交新 QGA/SSH 探测,并取消
未开始任务;它不是对已经开始的 libvirt 打开、XML、seed 或 define 操作的强制 HTTP
截止。PHP HTTP timeout 必须大于该探测预算,operation lease 还要留出明确余量;超时只返回
vpc_private_guest_probe_deadline_exceeded并继续幂等 reconcile,不能 lease steal、 重复派发或遗留不断增长的 guest process/线程/SSH 连接。 - 宿主 libvirt 必须为 upstream 4.2.0+,或由发行版明确回补 CVE-2018-1064 的 QGA 单响应
10 MiB 读取上限;Python 只解析
不超过 192 KiB 的响应,且默认最多并行 4 个来宾探测。
agentSetResponseTimeout恢复 默认值失败时必须返回 uncertain,不能在 domain-wide timeout 仍被修改时发布 confirmed。 - 另用单宿主 4096 成员验证周期 reconcile:生命周期目标必须优先;进入 QGA 并发探测前 的逐 VM seed/libvirt 核对仍是已知串行边界,应记录首个目标完成时间和全量收敛时间, 不能仅以请求超时作为容量结论。
- 同一 VPC 放置 A、B 两个成员:A QGA exact、B stopped/unsupported 时,配置 operation 应完成,A 的实例私网可用、B 单独显示未就绪,聚合健康可 degraded;随后只恢复 B 的 agent/启动状态,不做新 mutation,周期 reconcile 必须最终将 B 和聚合健康推进为 active。