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/VALIDATION.md

428 lines
42 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 本版验证记录
## 2026-10-09:真实宿主探针兼容修复
- AlmaLinux 10 现场证明配置的 endpoint 唯一属于 `br0`,firewalld 使用
nft backend 且 `br0` 的持久 NetworkManager profile 存在;误报来自探针调用了不受
支持的 detail 字段 `GENERAL.FILENAME`。readiness、Fabric/VPC apply/remove/observe
与开机恢复现统一读取有界的 `UUID,FILENAME` 列表,按 UUID 精确唯一匹配,并继续要求
endpoint profile 位于 `/etc/NetworkManager/system-connections`、非符号链接、root 所有且
模式为 `0600`。
- 运行中 VM 的 `vnet1`、`vnet3`、`vnet10` 等 tap 可能对应 NetworkManager 在 `/run`
下生成的临时 profile。它们会逐接口标为不可持久验证,但只要不是 endpoint,就不会再
连带阻断 `br0`;若 endpoint 自身只有临时、重复或不可验证 profile,仍然 fail-closed。
- Debian 13 现场的 iproute2 6.15 在 WireGuard 模块未加载时会让
`ip -j -d link show type wireguard` 返回成功且包含逐 link 的 `{}` 占位。解析器只在
模块状态精确为 `not_loaded` 时允许 WireGuard typed 段中的精确空对象;模块已加载、
其他 link/address/bridge 段或任意非空畸形记录继续拒绝。页面同时区分 `ip` 命令与发行版
包名:Debian 安装包为 `iproute2`,AlmaLinux/RHEL 安装包为 `iproute`。
- `ip`、`nft` 与 `modinfo` 均改为执行能力探针实际发现的绝对路径,覆盖 `/usr/sbin`、
`/usr/bin`、`/sbin` 和 `/bin`,避免非 merged-/usr 布局出现“已发现但执行阶段假缺失”。
- 直接相关三组 Engine 回归为 **295 passed**;Python `compileall`、生成 shell 的 POSIX
语法、管理员 Fabric Node 行为、JavaScript 语法、PHP 静态合同和 `git diff --check`
通过。完整 Engine 回归为 **1312 passed、10 skipped、5 failed、80 subtests passed**;
5 个失败仍是既有 cloud-template spec、reinstall cleanup envelope 与 3 个公网池 fixture,
不涉及本次探针代码。
- 上述现场输出是修复输入,不代表新版本已经在宿主机验收。部署本提交后仍须重新点击
“检测宿主机”,确认两个旧阻断消失;随后执行地区自动配置、WireGuard 握手、跨宿主流量、
firewalld/NetworkManager reload 与重启恢复验收,才能认定生产组网完成。
## 2026-10-08:公网优先 underlay 与 firewalld+nft 兼容
- Fabric/VPC 现在只接受两个互斥模式:native nftables 要求
`nftables.service` active/enabled 且 firewalld 不存在或 inactive+masked;
firewalld 模式要求 active/enabled、nft backend、`NftablesTableOwner=yes`,native
nftables unit 则只能不存在或 inactive+disabled/masked。能力探针不会查询 inactive
firewalld 的 D-Bus API,避免为了检测而把仅 disabled 的服务重新激活。
- firewalld 继续管理 endpoint 所在 zone 及精确 UDP rich rule;平台受管 Fabric/VPC
table 仍由 nft 原子加载并用 owner/revision/digest/完整语义快照回读。公网物理接口永不
trusted,只有已验证 profile/fragment 的 overlay/VPC 接口在 ACL 完整回读后临时进入
runtime trusted。失败、回滚和开机恢复均先隔离而不拆除 bridge/tap 拓扑。
- firewalld 事务会先安装带随机 token 的独立 emergency nft guard,并把 token 写入
root-only owner intent;删除前必须再次证明 token、完整 table 形状和 stateless snapshot
均未变化。仅没有 VPC state、manifest 或未完成 journal 的空宿主,才允许在失败的
firewalld 前置尝试纠正为 native 后接管并清理这份 guard;已有 VPC 时必须保留 guard 并
报告维护迁移,不会以 owner comment 数量代替三族 ACL 的完整语义证明。缺少 owner intent
的同名外部 table 始终不触碰。nft journal 区分 mutation/install/refresh 的提交阶段,
崩溃恢复不能把“命令已返回”误当成持久规则已完成回读。
- underlay 普通路由和显式 `from endpoint` 路由必须选择同一接口及配置的源地址;多地址
同接口不能再靠 `dev` 相同误通过。fresh readiness 还拒绝 endpoint 落入实际全局租户
VPC CIDR 池;Engine 在 Fabric 变更与 VPC apply 两端拒绝 endpoint 与既有 VPC CIDR
重叠,避免目的策略路由把 WireGuard 外层 UDP 重新导向租户表。
- Fabric apply/reconcile 与 VPC apply/delete/reconcile/lifecycle reconcile/observe 现在由
`EngineApplication` 显式注入同一个 lazy catalog mutation lock,锁序固定为每资源锁、
catalog 锁、排序后的 VM 锁。VPC 从读取 Fabric gate 到完整远端 mutation 和根/子记录
提交都保持共享锁;Fabric reconcile 先在锁内持久化关闭 gate,SSH 只读观测期间释放,
发布前重新取锁并复核资源互斥。并发回归覆盖 Fabric-first、VPC-first、删除、普通收敛、
lifecycle 收敛和外部观测发布,阻止旧 active gate 或变化后的 endpoint/CIDR 被继续使用。
该保证以部署的单 Uvicorn worker 为边界;多 worker 必须先增加跨进程 durable
reservation/CAS,不能依靠 asyncio 锁。
- VPC 准入会扫描全部持久化 `fabric_desired` endpoint,不仅检查当前 VPC 固定的
Fabric;每条记录都必须能重建计划且已存 `plan_digest` 与重建 digest 一致,
损坏或 stale 记录 fail-closed。根删除不能改变已有 region/Fabric identity/revision/CIDR;
无历史记录但需清理宿主的删除目标同样先执行全局 endpoint/digest 准入。取消回归证明
caller cancellation 不会让 catalog 锁越过尚未返回的 `asyncio.to_thread` mutation
提前释放;引擎在持锁期间 drain 底层任务、完成 desired state/receipt 提交后才传播
`CancelledError`。
- 每个 VPC 数据面计划携带权威 `fabric_plan_digest`;apply、remove 与 observe 均重建并
严格校验 Fabric nft grammar、owner/digest、精确 tenant set 和完整最终 snapshot。
因此即使 VPC 自身三张表看似正确,Fabric revision 漂移或租户集合不一致也不能发布
active。
- repair timer 不会 restart 主 service:主 service failed 时,它只排队一次主 service
和此前确因 dependency 失败的 libvirt 单元;主 service active 且精确核验到 firewalld
runtime trusted 漂移时,reconcile service 直接执行同一份带 flock 的完整 ACL-first
helper,不重启主 Fabric unit 或 libvirt。健康状态不会进入 helper。
NetworkManager 的合法无持久 keyfile/运行期 profile 只把对应接口标成不可验证,不再
连坐无关 endpoint;被选中的 endpoint 接口仍必须具有持久、root-only 的可验证 profile。
- 首次 apply 只有在事务目录持久写入 `committed` 后才释放 Fabric flock,并同步启动独立
reconcile dispatcher;主 oneshot 已 active 时直接执行同一份完整 helper,inactive/failed
时则等待 systemd start 完成。apply 随后重新取得 flock,复核当前 CONF digest、防火墙模式、
Fabric/VPC nft、WireGuard、主 service/timer active,以及 emergency owner 和 inet+bridge
两张 guard table 均已消失,才返回成功。`RemainAfterExit=yes` 为首启后的 repair timer 提供
稳定 active 语义;提交后的旧进程无权删除共享 journal,dispatcher 失败时由 timer/helper
或下一次持锁 apply 消费。boot quarantine 使用有界、逐步校验的 bridge 端口快照并在每次
`link down` 后明确回读无 `UP`,命令失败、畸形/重复/超量输出、端口变化或
NetworkManager 重新拉起接口均 fail-closed。
- Python 3.12 全量 Engine 回归为 **1302 passed、10 skipped、5 failed、80 subtests
passed**。5 个失败仍是本轮前已存在的 cloud-template spec snapshot、reinstall cleanup
detail envelope 和 3 个公网池 fixture;Fabric、VPC、firewalld、endpoint 与 repair 新增
用例全部通过;Fabric 单文件最终为 **148 passed**,聚焦组合为 **650 passed、2 个上述
已知失败、5 subtests passed**。PHP/WASM 下 14 个相关管理/资源/资产合同与流程测试、
VPC 创建和 CIDR
allocator 回归、Fabric Node 行为测试、两份 JavaScript 语法检查及 `git diff --check`
通过。
- 这些结果没有替代真实宿主机验收。AlmaLinux 10、Debian 13、firewalld/nftables reload、
NetworkManager/ifupdown 重启、libvirt socket activation、宿主重启、跨宿主 WireGuard
握手、MTU、SELinux、外部 NAT/安全组和允许/拒绝流量仍须按验收矩阵执行。
- nft CLI 不提供跨进程 CAS。本轮以完整 stateless snapshot、`nft -c` 后的最后
precommit 回读、原子 batch 和提交后回读关闭已知检查窗口;同机 root/CAP_NET_ADMIN
或其他 out-of-band nft 管理器仍须遵守维护互斥,不在事务中并发替换同名 table。
## 2026-10-08:Fabric underlay 地址与 SSH 管理地址解耦
- Engine 宿主机配置增加可选 `fabric_endpoint_ip`;空值仅在 SSH `host` 为安全的字面
IPv4 时回退,当前公网组网无需重复填写。未来同地区宿主机已有互通内网时,可以逐台填写
本机内网 IPv4,而无需改变 Fabric/VPC overlay 架构。
- endpoint 仍由 Engine HostProfile 单点持久化,面板 `cloud_hosts` 不复制该运行配置。
管理员宿主机表单安全透传可选 IPv4;fresh probe 验证显式地址属于对应宿主机。
- Fabric readiness 只展示生效的 endpoint 和受限来源(专用配置或 SSH IPv4 回退),未知
来源会被折叠,不会增加 SSH 地址、凭据或原始输出字段。每台宿主机仍只公布一个 endpoint,
因此所选公网或内网地址必须能被同地区所有成员直接访问。
- PHP/WASM 下 endpoint、宿主地区、宿主错误、Fabric 静态契约和动态 readiness、公网池、
共享资产/抽屉回归通过;管理员 Fabric Node 行为测试和两份修改 JavaScript 的语法检查
通过。真实公网/内网 endpoint 可达性仍须按宿主机验收矩阵确认。
## 2026-10-08:宿主机显示位置与 Fabric 地区解耦
- 宿主机编辑页把 `CloudHost.region` 明确标为“位置标签(仅展示)”;该字段仍按引擎边界
要求为 1 至 64 字符,但不再代表销售地区、Fabric identity 或 VPC 归属。权威归属由
active/draining 宿主机成员关系沿资源池、线路到 `CloudRegion` 唯一解析。
- Fabric readiness、fresh probe 和 VPC 成员门禁不再比较宿主显示标签或探针回传标签与
`fabric_region`。成员关系缺失、重复、断裂或跨地区仍 fail-closed,Fabric/VPC 固定的
identity、region、revision 回读仍要求精确一致。
- 引擎中存在但没有平台映射的自定义 Fabric 不会被自动认领或改写,继续进入
`migration_required`。没有增加旧配置兼容;仅保留本地区确定性 Fabric 在下发结果未知或
部分成功后的原有“重新核对”恢复路径。
- 静态宿主位置契约覆盖了表单与校验文案,Fabric/VPC 回归覆盖“显示标签不同但权威成员
关系相同”的正常路径,并覆盖实例 pool pin 不一致、多条 live membership、
pool/line/region 断链与跨地区拒绝。本轮 Engine Fabric/VPC/边界回归 `268 passed`,
21 个聚焦 PHP 测试脚本、7 个变更 PHP 文件语法检查和管理员 Fabric Node.js 行为测试
通过。开发环境仍未替代真实多宿主 WireGuard、nftables/firewalld、libvirt 和重启恢复验收。
- 扩大探测仍命中未修改的既有测试问题:`SourceSyntaxTest` 被
`AdminSystemLogsContractTest.php` 的双引号插值语法错误阻断;
`CloudEngineReadinessTest` 保留了已过时的静态次数断言;`CloudProtocolTest` 未导入
`CloudOperationErrorCatalog`。三个文件均未在本轮修改。
## 2026-10-08:raw JSON 部署收口为地区级向导
- 管理员“地区私网”页面改为四阶段内联向导:选择地区、检测宿主机、自动配置、重新
核对;全页仍只有对应后三步的三个操作按钮。浏览器只消费服务端 `workflow` 门禁和
`plan_preview` 只读摘要,不生成、编辑或提交节点/endpoint/raw JSON 计划。
- 公开管理 API 已移除 raw plan apply、按 Fabric ID 直接 reconcile 和地区映射
PUT/PATCH;只保留 Fabric/映射只读回读和三个按地区执行的空 body 动作。PHP 仍在服务端
生成并校验固定 DTO,再调用不对浏览器公开的 Engine 内部 apply/reconcile。
- 服务端按权威库存、映射与引擎回读投影引擎不可用、无宿主机、待检测、阻断、可配置、
待核对、active、需要迁移和需要恢复阶段。只在 fresh probe 完整通过后开放自动配置;
固定 desired state 不一致或缺失时不会在原 revision 下重建。
- “自动配置”仅接受无映射且无 desired state 的全新地区;活动/disabled 映射和未映射的
确定性部分成功只能走“重新核对”。所有 reconcile 都在宿主写入前重新校验平台拓扑、
fresh probe、详情/目录、冲突与精确计划;disabled 映射可在同 identity/region/revision
的 active 回读后安全激活,但每个未删除 VPC 也必须精确固定到同一三元组;旧空 pin 或
任一漂移都会进入迁移门禁,不会在宿主写入后才失败。
- 前端不会把非 `active` 的成功 HTTP 响应显示为配置成功;地区切换、重复点击、引擎不可用、
请求超时、网络中断和 HTTP 5xx 均有独立门禁。写操作结果未知按地区隔离,禁止重放
自动配置,只开放服务端 reconcile 恢复路径;其他地区成功不会解除该保护。
- 列表和地区动作响应不再携带冗余的完整 `fabrics`/`region.fabric` 节点计划;向导只收到
readiness 宿主行、标量回读和有界方案摘要。管理员按 Fabric ID 的显式 GET 详情仍保留
为只读诊断入口。
- PHP 8.5/WASM + SQLite 下 Fabric readiness、Fabric/VPC 控制面、VPC 创建/复用/CIDR/
删除/tombstone、管理员资源调度、路由、模板、资产和防火墙相关回归通过;路由目标为
273 项、Smarty/email 模板 105 个、前端模块 52 个。新增 Node 向导行为测试、JS 语法、
修改 PHP 语法和 `git diff --check` 通过;未改 Engine 的 Fabric/boundary 定向回归为
**210 passed**。
- 扩大检查中的 `SourceSyntaxTest` 仍被既有 `AdminSystemLogsContractTest.php` 双引号插值
语法错误阻断,`CloudEngineReadinessTest` 仍保留与当前源码次数不符的旧静态断言;两处
文件均不在本次 diff。本节所列相关回归全部通过,但没有宣称这两个既有测试已修复。
- 结果未知集合当前属于页面内保护;彻底覆盖刷新或第二管理员需要服务端持久 operation
ID/lease/phase。映射提交前已在长网络操作后重读拓扑,并在事务中锁地区、映射和 live
VPC;跨全部库存写路径的 topology generation/CAS 仍是后续并发强化项。
- 开发环境没有连接真实多宿主 SSH、
WireGuard、nftables/firewalld 或 libvirt,生产部署仍须执行 Fabric 宿主机验收矩阵。
## 2026-10-08:管理员地区宿主机 readiness 与自动组网
- 管理员“地区私网”页面现在以地区为唯一操作入口,正常操作严格只保留“检测宿主机”、
“自动配置地区私网”和“重新核对”三个按钮。页面新增地区 readiness 汇总、逐宿主机
清单与 Fabric 只读回读,不再让浏览器编辑 Fabric ID、overlay、revision、端口、节点
JSON 或地区映射;普通管理员只读,三个动作仍要求具有管理权限的超级管理员与 CSRF。
- 地区必须宿主机集合由 active/draining 资源池成员、非删除实例、非删除 VPC deployment
以及当前/冲突 Fabric 节点合并。缺失宿主机、资源池、线路、地区或 VPC 根,同一宿主机
存在多个 live membership,工作负载归属漂移、未映射自定义/跨地区 Fabric 占用和
重复/不可用 endpoint 均 fail-closed,不会因内连接缩小清单后继续写宿主机。宿主机
显示位置标签不参与地区归属判断。
- “检测宿主机”调用新的只读引擎探针;未知宿主机不会构造运行时或数据目录,每台失败独立
返回白名单状态。一次引擎请求最多 64 台、固定 16 路并发,同一进程不排队执行重叠
探针而返回稳定 409;PHP 可把最多 128 台 readiness 清单拆成两个批次。真正自动配置的
Fabric 仍限制为 2 至 64 台,并在写入前重新探测,不能复用浏览器里的旧检测结果。
- 自动 Fabric ID、地区、CGNAT `/24`、revision、UDP 端口、排序后的节点与 overlay `/32`
全部由服务端确定生成。既有映射要求 desired state 精确一致;映射缺失时只允许恢复形状
完全一致的确定性 partial success,不会用变化后的 inventory 在同 revision 重建。写入后
通过引擎精确回读、平台拓扑复读及数据库映射 CAS 才发布 active/ready,HTTP 超时则要求
使用“重新核对”读取固定 desired state。其他未绑定的自定义 Fabric 保持
`migration_required`,不作为旧配置自动兼容或认领。
- PHP 8.5.10/WASM + SQLite 下 `AdminFabricReadinessWorkflowTest`、
`AdminFabricContractTest`、`DrawerMotionAssetsTest` 及 7 个 VPC 策略/收敛契约测试通过;
275 条路由目标、105 个 Smarty/email 模板、52 个前端模块和 schema 契约通过。
`admin-fabric.js`、`vpc.js`、`drawer-motion.js` Node 语法、修改 PHP 语法、Python
`py_compile` 与 `git diff --check` 通过。Engine Fabric/boundary 定向回归为
**210 passed**。
- Python 3.12.14 全量 Engine 回归为 **1097 passed、10 skipped、5 failed**。5 个失败
与本轮前的基线类别一致,分别属于既有 cloud-template spec snapshot、reinstall cleanup
detail envelope 和 3 个公网池 fixture;本轮 Fabric/readiness 与 Engine boundary 没有
新增失败。
- 当前未连接真实 PHP-FPM、MariaDB、浏览器或 SSH/libvirt 多宿主机。生产验收仍须覆盖
WireGuard 握手、UDP/51820 underlay、MTU、SELinux、受支持的 native nftables 或
firewalld+nft 持久化、网络/防火墙重启修复和跨宿主机租户流量。两种防火墙模式必须
互斥;不受支持或所有权不明确的组合继续 fail-closed,不能直接清空生产防火墙。
反代与 PHP-FPM 请求终止/读超时建议至少 270 秒。
## 2026-10-08:租户单自动子网与创建页简化
- 租户创建页只保留 VPC 名称和地区;CIDR、前缀、唯一子网、成员容量与成员私网 IP
均由平台管理。详情页不再显示子网管理卡片,成员加入也不再选择子网或手填地址;共享
前端资产版本已提升,避免部署后继续使用旧表单缓存。
- 删除租户 `POST/DELETE /vpcs/{vpc_key}/subnets...` 路由、Controller 入口和 Service
mutator。新成员加入意图严格只有 `instance_id` 与 `request_key`,先锁 VPC 根及其全部
子网,确认恰好一个非删除、非清理中的有效子网,再从成员租约与 route `/32` 保留地址
之后自动选择最低可用 IP。仅为滚动升级重放已存在的同 key operation 才读取旧版
`subnet_key/private_ip`;这些字段不能创建新成员,新请求携带时返回 422,且不产生
member、lease、operation 或 revision 副作用。
- 自动子网缺失或正在清理时返回 409;历史数据若存在多个活动子网或无效子网账本则
fail-closed 为 503,不静默选择任一行。数据库表、引擎多子网 DTO 读取能力、根删除和
历史 `subnet_remove` tombstone 收敛逻辑继续保留;本轮没有增加会阻断历史升级的
`UNIQUE(vpc_id)`,也没有自动合并或删除历史数据。
- 成员加入继续把服务端选出的 `subnet_key` 与 `private_ip=null` 写入旧版 request hash,
保持旧自动分配请求可重放。重放检查先于当前子网和实例状态,并从不可变 operation
payload 验证旧自动分配或旧显式 IP hash;因此丢失响应后,即使子网随后进入清理,刷新
到新版页面可用原 `request_key + instance_id` 安全读取结果,未刷新的旧页面也只能在
`subnet_key/private_ip` 与原 hash 精确一致时重放,参数变化返回 409。
- PHP 8.5/WASM + SQLite 下 `CloudVpcCreatePolicyTest`、
`CloudVpcMemberReuseTest`、`CloudPrivateCidrAllocatorTest`、
`CloudVpcRootDeletionTest` 和 `CloudVpcTombstoneConvergenceTest` 通过;源码契约
`CloudVpcControlPlaneContractTest`、`CloudVpcUserPageContractTest`、
`VirtualizationConfigTest`、272 条路由目标、105 个 Smarty/email 模板、52 个前端资产
模块及 schema 契约通过。修改 PHP 语法、`vpc.js` Node 语法和
`git diff --check` 通过。
- SQLite 不实现 MariaDB 的 `SELECT ... FOR UPDATE` 竞争语义,当前也未连接真实
MariaDB、PHP-FPM、浏览器或宿主机。上线前先只读审计所有非删除 VPC;下列查询必须
没有结果,再在隔离 MariaDB 中并发加入同一 VPC、并发重放同一 key,并确认只有一个
member、lease 和 operation:
```sql
SELECT v.id, v.vpc_key,
SUM(CASE WHEN s.state IN ('applying', 'active', 'degraded', 'uncertain')
THEN 1 ELSE 0 END) AS live_subnets,
SUM(CASE WHEN s.state = 'deleting' THEN 1 ELSE 0 END) AS deleting_subnets
FROM cloud_vpcs AS v
LEFT JOIN cloud_vpc_subnets AS s
ON s.vpc_id = v.id AND s.state <> 'deleted'
WHERE v.state <> 'deleted'
GROUP BY v.id, v.vpc_key
HAVING live_subnets <> 1 OR deleting_subnets <> 0;
```
## 2026-10-08:租户 VPC 创建策略、账户配额与幂等加固
- 租户创建 API 现在只接收 `name`、`region_id` 和 `request_key`;CIDR、前缀、首个
子网、成员容量和 Fabric 身份全部改为平台策略。新 VPC 固定自动分配独立 `/24`,首个
子网覆盖该 `/24`,成员上限为 200;历史大 VPC 的 4096 协议/观测上界不变。
- 默认每账户最多保留 5 个非 `deleted` VPC,可用
`cloud_max_vpcs_per_account` 在 1 至 100 内调整。创建事务先锁账户行,再核对根、配额、
Region/Fabric 和 CIDR 分配;`deleting` 根仍占账户配额,`deleting` 成员仍占成员容量,
只有精确收敛为 `deleted` 才释放。
- 同一创建键的回放先于当前配额、Region/Fabric 状态和分配器策略;请求摘要只包含稳定的
名称与地区。历史创建摘要继续按确定性 root、owner/name/region、operation 和 allocator
链接兼容,但缺 operation、network/subnet 或精确 CIDR claim 闭集时 fail-closed。已删除
root 只返回原 tombstone,不复活 CIDR;released allocation 出现残留 claim 同样拒绝回放。
- CIDR 分配、root、首个 subnet 和 operation 位于同一默认数据库事务。删除了失败后的
二次 `release()` 补偿,避免事务回滚后与同 request key 重试竞态、误释放胜者 CIDR。
租户创建表单同步移除高级网络字段并提升资产版本,旧缓存不会继续提交已禁字段。
- PHP 8.5/WASM + SQLite 下 `CloudVpcCreatePolicyTest`、
`CloudVpcControlPlaneContractTest`、`CloudPrivateCidrAllocatorTest`、
`CloudVpcMemberReuseTest`、`CloudVpcRootDeletionTest`、
`CloudVpcTombstoneConvergenceTest`、`CloudVpcUserPageContractTest` 和
`VirtualizationConfigTest` 通过;覆盖强制 post-allocation 失败零泄漏、满配额回放、历史
hash、平台状态变化、deleted tombstone、live/released claim 损坏和 deleting 容量。
另通过 105 个 Smarty 模板编译、274 条路由目标、52 个前端资产契约、schema 契约、
修改 PHP 语法、`vpc.js` Node 语法和 `git diff --check`。
- SQLite 不实现 MariaDB 的 `SELECT ... FOR UPDATE` 并发语义;上线前仍须在隔离 MariaDB
上并发争抢账户最后一个名额、并发同 key 丢响应重试,并核对最终仅有一条 root、network、
claim 和 create operation。当前未连接真实数据库、PHP-FPM、浏览器或宿主机,也未改变
WireGuard/libvirt/firewalld 数据面。额外全仓 `SourceSyntaxTest` 仍被未修改的
`AdminSystemLogsContractTest.php:108` 既有解析错误阻断,不归因于本轮 VPC 修改。
## 2026-10-08:VPC 来宾网络启动代次门禁
- 私网 MAC、`/32` 地址和唯一的 VPC CIDR scope-link 路由共同生成独立
guest-network generation;成员、自定义 route、ACL/Fabric 等纯宿主变化不改变该
generation。
- 运行中 VM 的新来宾网络不改写 NoCloud seed、inactive XML 或 live device;完全停机
后由 reconcile 写入 seed 与持久 XML,再启动消费。在完成 stop/reconcile/start 且
live metadata 匹配之前,宿主保持
`applying/pending_restart`,PHP 拒绝将缺失 `restart_required=false` 的证据视为
active/usable。
- 相同私网目标重试返回原 seed 字节,不重复轮换 NoCloud `instance-id`;写入
后会在 libvirt define 前重新下载 seed 并核对 MAC/IP/routes;缺少安全 boot 网络策略
的旧 seed 明确要求迁移,不通过新 instance-id 重放 credentials。
- current generation 还要通过 QGA 地址、link 与 route 的精确回读;保留地址/路由但
`NO-CARRIER`/`linkdown` 的接口不能通过。显式 link-down suspension 单独由 XML/config
证明隔离,恢复 link-up 后才重新要求 QGA usable 证据。
- `evidence_version=2` 使历史 XML-only succeeded 证据失效;宿主 config proof、每成员
guest readiness 与 VPC 聚合健康分别收敛,tombstone 不再被无关成员的 QGA 状态阻塞。
- 本地验证:Python compileall 通过;cloud-init、VPC 数据面、libvirt、协调器及删除回执
的定向回归 **394 passed**。完整 engine 回归为 **1071 passed、10 skipped、8
failed**;8 个失败已在本轮修改前的 `6dc0d21` 干净快照复现,属于既有云模板 spec、
重装错误 envelope、Python 3.9 upload timeout/event-loop 与退役宿主盘点式公网池 fixture。
- 隔离 PHP 8.5.10/WASM 下 5 个 VPC 契约/收敛测试全部通过,10 个修改 PHP 文件语法、
`vpc.js` Node 语法和 `git diff --check` 通过。当前宿主没有原生 PHP CLI;真实
libvirt/cloud-init 验收仍需在测试 VM 内核对地址、唯一 VPC CIDR scope-link 路由与跨
VM 连通性。宿主策略路由、代理 ARP 和 WireGuard AllowedIPs 仍必须保持精确 `/32`。
## 2026-10-08:根 VPC 可恢复删除状态机
- 租户 API 新增根 VPC 删除:精确名称确认后,PHP 在事务中把根和子资源固定为
`deleting`,签署空 desired target、待清宿主机闭集及 `retiring_members` 身份清单。
普通变更不能覆盖该 revision;失败或响应丢失只能用原 operation/revision/digest
显式核对。
- 引擎在任何 SSH/libvirt 变更前持久化删除 marker,逐成员核对并移除持久化
`private0`、私网 metadata 与 cloud-init seed,再清理宿主机 VPC 数据面。部分宿主机
已确认时,重试只联系尚无精确不存在性证明的宿主机;完整 receipt 必须先持久化,
随后才能清理引擎 desired 记录。终态 receipt 只保留重放所需的操作身份、摘要、
宿主机闭集和时间戳,不永久保存成员 UUID、私网 IP 或 MAC;旧格式会自动压缩。
- PHP finalizer 严格核对 payload、receipt、历史/待清宿主机集合和子账本,然后验证
CIDR interval 与全部 /24 claim,最后用 revision CAS 释放地址。live allocation 的
幂等重放也会重新证明 claim 闭集;畸形 VPC 核心/子表、残留 claim 或未完成根删除
均会阻止账户删除。只有完成删除的子账本会被清理,以释放全局 member 唯一键;根、
宿主机和 operation 保留为审计 tombstone。
- 前端只有详情接口明确返回 `state=deleted` 才结束删除提示;分页列表缺失或 404 不会被
当作成功。`deleting` 期间锁定所有普通编辑,仅保留“核对 / 重试”。
- 直接相关 Python 模块回归:**429 passed、56 subtests passed**;覆盖 VPC 协调器、
数据面脚本、内部 API 和 libvirt 持久 XML/metadata/seed 清理。完整 engine 回归为
**1007 passed、10 skipped、80 subtests passed、5 failed**;5 个失败在未修改的
`7f9fb9c` 干净快照逐项复现,分别属于既有云模板 spec、重装错误结构和公网 IP 池
fixture,不是本次删除状态机引入。
- 隔离 PHP 8.5/WASM 下 `CloudVpcRootDeletionTest`、
`CloudPrivateCidrAllocatorTest`、`CloudVpcControlPlaneContractTest`、
`CloudVpcUserPageContractTest`、`ManualAccountDeletionSqliteTest` 和
`ManualAccountDeletionTest` 全部通过;本轮 11 个 PHP 文件语法、274 条路由目标、
`vpc.js` Node 语法、Python `compileall` 与 `git diff --check` 通过。
- 当前没有连接真实 MariaDB、SSH/libvirt、nft、NetworkManager 或 ifupdown 宿主机。
生产验收必须覆盖多宿主机部分失败/重启续跑、HTTP 回执丢失、真实 seed 重写和数据面
移除回读。含私网成员的根删除要求相关 VM 已停机;managed-save 或原生快照存在时会
保留 tombstone 并拒绝继续,处理阻断后再显式 reconcile。
## 2026-10-07:在线更新后部署页 SQL 回归修复
- 在线更新到 `521d40a` 后,`/user/cloud/deploy` 在读取销售目录时会因 `cloud_hosts` 不存在 `host` 列而返回 500;同一错误也影响管理员资源汇总。根因已在 `e7230ff` 修复,应用查询现在只使用面板资源策略、reservation 和已物化的公网 IP ledger。
- 管理 IPv4、网关和 DNS 必须在地址池 `reserved_ips` 中显式保留;代码不再从宿主机模型读取 SSH/管理地址,也不通过宿主机盘点补全地址。
- saleCatalog SQLite/WASM 首屏 smoke 通过;部署 SSR、资源调度、IP ledger、宿主机网络池/调度、模板编译、虚拟化资产和 Node JS 语法检查通过。完整财务流程继续执行到既有 reconciliation 场景后失败,不能把该失败归因于本次缺失列修复。
- 代码修复提交为 `e7230ff`,随后补充部署 smoke 与验证记录文档;提交链已推送到远端 `venix`。真实 PHP-FPM、MariaDB、浏览器和宿主机仍需部署验收;上线后应同时检查 `/user/cloud/deploy`、`/api/v1/catalog` 和 PHP-FPM 错误日志。
## 2026-10-07:移除账户实例数量上限
- 删除账户实例数量配置、购买事务中的账户级 409 检查,以及金融测试中依赖该限制的场景;账户实例数量现在只受销售库存、宿主机面板容量、reservation 和具体公网 IP 账本约束。
- 全仓精确搜索未发现该配置键或账户上限错误文案的 CSS、JS、SQL 残留;`cloud_host_capacity_policies.max_instances` 保留为单宿主机调度容量,分页大小和快照/防火墙等其他实例上限也未误删。
- 账户上限相关的财务流程已越过,完整金融测试仍在既有 reconciliation fixture 处失败;具体契约、模板、JS 语法和 `git diff --check` 通过。真实 PHP-FPM、MariaDB 和并发购买仍需部署环境验收。
## 2026-10-07:面板资源账本取代宿主机盘点
- 调度、创建放置和网络选项现在只读取面板配置的容量策略、活动资源池、reservation 账本和 `cloud_public_ips`;不再要求容量快照、盘点新鲜度、宿主机 `host/network-options` 或 VM discovery 结果。
- 创建和换 IP 的引擎路径只读取面板传入的具体地址池参数与持久 claim,并用原子 claim 防并发重复;不会为每个请求枚举宿主机全部虚拟机。
- 宿主机保存/连接测试只验证 SSH、存储池和网络资源,不调用 `list_vms()`;用户 VM 列表和指定 UUID 的状态读取仍保留为用户操作及结果核对路径,不参与容量或 IP 调度。
- 用户列表、实时状态和生命周期状态同步只向引擎发送面板已知的 UUID(每批最多 100 个);旧的无参数全量状态接口仅为未接入面板的私有兼容 UI 保留。
- 引擎本机兼容 UI 仍保留全量 `/api/v1/vms`、无参数 `/api/v1/vm-states` 和资源目录接口;它们不进入 PHP 调度链,部署只允许 `127.0.0.1:8000`,不能作为公网管理入口。`inventory-panel` 是旧 UI 的通用卡片类,不代表已保留宿主机容量盘点功能。
- 旧 `cloud_instances.spec_json` 的可验证资源与公网地址会在地址池物化时迁移到面板账本;缺失、损坏或重复数据会阻止该宿主机调度。管理宿主机 IPv4 需在 `reserved_ips` 中显式保留。
- 私有引擎仍负责最终宿主机操作和具体 IP claim。网络超时或响应不确定时保留 `operation_id` 与 reservation,先核对再决定补偿;同一 client token 重试不得重复创建。
- 最终隔离回归:`engine.tests.test_libvirt_service` **183 passed、10 skipped**;`test_app.py` 与 `test_engine_boundary.py` **205 passed、4 failed**。4 个失败均为既有的云模板平台策略断言和 Python 3.9 上传超时/事件循环兼容问题,不涉及面板调度、IP 账本或盘点删除路径。
- PHP/WASM 契约测试通过:`CloudInstanceReadPerformanceTest`、`CloudInstancePageSsrContractTest`、`AdminHostNetworkPoolsContractTest`、`AdminResourceSchedulingContractTest`、`CloudNetworkIpLedgerContractTest`、`AdminHostSchedulingContractTest`、`CloudMultiHostSchemaDefinitionTest`、`VirtualizationAssetsTest`。
- `python -m compileall` 与 `git diff --check` 已通过。当前 macOS 工作区没有 PHP CLI、Composer 依赖、真实 MariaDB、systemd journal 或 libvirt 宿主机;PHP 契约测试使用隔离 WASM 运行时,真实引擎/数据库验收仍需在部署环境复跑。
## 2026-10-06:系统日志异步读取与详情
- 系统日志首屏改为只渲染页面框架,列表 API 增加浏览器截止时间、显式停止读取、旧响应隔离和 `journalctl` 子进程的有界回收;分页游标使用 `--cursor` + `--reverse`,按 systemd 的实际 seek 语义从边界向更早记录读取,并防御性移除意外返回的边界记录。
- 新增管理员只读详情接口,按列表携带的 UTC 微秒时间戳和服务窗口重新读取单条记录,再校验 journal cursor;返回受限的完整诊断字段和完整消息。日志轮转、字段上限和敏感字段省略均有明确状态。
- 使用工作区捆绑 Node 运行并通过 `AdminSystemLogsBehaviorTest.mjs`、`AdminOperationsCancelBehaviorTest.mjs`、日志页 JavaScript 语法检查和 `git diff --check`。
- 当前 macOS 工作区没有 PHP CLI、Composer 依赖或 systemd journal,因此 PHP 契约测试、真实 PHP-FPM 子进程超时回收和远程宿主机日志读取仍需在部署环境复跑。
## 2026-10-06:修复系统日志详情抽屉不可见
- 现场复现确认:日志行的鼠标点击和键盘事件已经执行,详情请求也可发出;页面没有视觉反馈是因为日志页直接调用 `showModal()`,绕过了共享抽屉的 `is-drawer-visible` 动画类,抽屉因此保持在屏幕右侧的初始变换位置。
- 日志页现在统一使用 `VenixDrawerMotion` 打开和关闭详情,缺少共享脚本时仍有可见的降级路径,同时锁定页面滚动、恢复触发行焦点,并拦截原生 `cancel` 事件以完成动画关闭。
- 详情对话框位于日志 `<main>` 外,详情消息和字段样式已改为直接以 `#system-logs-detail` 作用域,避免样式选择器永远不匹配。
- `AdminSystemLogsBehaviorTest.mjs` 现通过嵌套消息元素模拟真实冒泡点击,并验证鼠标、Enter、空格、共享 motion、可见类和滚动锁;资产版本更新为 `2026100602` 以避免部署端继续使用旧脚本。
## 2026-10-04:盘点只读并发与删除驱动清理(历史记录,盘点方案已退役)
- `host/capacity`、`host/network-options` 与诊断查询已从引擎全局写锁、在线更新修复及 ISO/云镜像惰性清理中拆出;删除后的宿主缓存回收只由持久 tombstone 监督器重试。诊断专项回归:**33 passed**,覆盖慢盘、取消/晚完成、满接纳窗口终态、淘汰失败上界、异常引用释放及 daemon writer 退出边界。
- Python 3.12 全量隔离回归:**762 passed、10 skipped、68 subtests passed、1 failed**。唯一失败仍为 `test_app.py::test_native_public_pool_blocks_silent_default_network_change` 的既有 409“公网地址池目录存储不可用”;该失败在本轮修改前已有独立复现记录。
- 本轮没有修改 PHP 或前端源码;当前工作区没有 PHP/Node 可执行文件,因此未重复运行上一节的 PHP/WASM 与页面行为测试。
- 未连接真实 MariaDB、systemd 或 SSH/libvirt 宿主机。该轮并发盘点验证属于历史实现;当前上线验收应改为并发创建、IP reservation、相同 client token 重试及 `operation_id` 对账,并验证显式删除模板后的离线宿主重试与代际保护。
## 2026-10-04:宿主机盘点诊断(历史记录,相关页面和服务已删除)
本轮只增加过渡期诊断历史、管理员页面和跨 PHP/引擎阶段证据;每请求 8 秒预算、容量/IP 提交代际和调度判定不变。该页面和服务不再属于当前部署路径,以下结果仅用于解释迁移前的基线。
- Python 3.12 全量隔离回归:**747 passed、10 skipped、68 subtests passed、1 failed**。新增诊断用例覆盖签名/权限、锁等待、存储失败降级、嵌套阶段、取消请求与 worker 晚完成、重启和保留上限。
- 唯一 Python 失败为 `test_app.py::test_native_public_pool_blocks_silent_default_network_change`:测试创建公网池返回 409“公网地址池目录存储不可用”,预期 200。在修改前的 `fad3b4e` 独立源码快照中复现同一失败;未在本轮扩大范围修改。
- 隔离 PHP 8.5.10/WASM、精确 `composer.lock` 依赖与 SQLite 测试曾覆盖盘点客户端、诊断、同步服务和关系边界;这些盘点专项名称和结果仅保留作迁移前记录,对应页面、同步服务和诊断服务当前已删除,不再列入本版执行集。
- 扩展 PHP 检查另发现两项既有失败,均在 `fad3b4e` 快照复现:`CloudProtocolTest.php:85` 的源码断言插值 `$actor`;`CloudAdminOperationsServiceTest.php:245` 的查询字段断言与原服务选择 `payload_cipher` 不一致。本轮未修改这两个测试或其既有服务。
- 过渡期盘点页面行为测试、相关 PHP 语法、两份 JS 语法及 `git diff --check` 曾通过。该页面和测试已删除;当前前端验收应覆盖宿主机调度抽屉、面板容量计算、IP 账本筛选和操作核对。
- 未连接真实 MariaDB 或远程宿主机,没有验证生产 PHP-FPM/systemd、cURL 传输、SSH/libvirt 延迟或诊断持久化的实际 I/O 开销;不能据此声称用户当前 `unavailable` 的根因已确定。真实环境启用后,应依据新增记录验证失败层和最后确认阶段。
## 2026-09-27:集成基线
2026-09-27,集成代码的隔离验证,不代表生产验收。
- 当前 macOS 工作区 Python 3.12 回归:515 passed、10 skipped、55 subtests passed。覆盖原虚拟化逻辑及私有 API、签名/重放、多宿主机归属、持久幂等、一次性 VNC、退出后断权、带宽 XML、救援上传摘要,以及到期断网/恢复、同实例变更串行、多网卡 live+config 断网/恢复、退出救援保持计费断网、流量累计检查点和破坏性操作结果核对。生产仍按部署文档使用 Python 3.12 或更新的受支持版本复测。
- 隔离 PHP 8.5.10 验证源码语法、Smarty 模板、路由目标、精确金额/HMAC、SQLite 购买开通/退款/超时核对、宿主机面板容量/IP 账本、租户隔离、Cookie/Redis 会话撤销及内省、统一用户资源和 noVNC 模块;账户固定实例数量上限已删除。本次账期与生命周期用例应覆盖提前续费、精确扣款幂等、RX+TX 额度、断网不关机、下期恢复、到期仅断网、3 天宽限期内续费恢复,以及宽限期结束后的实例与受管磁盘删除;当前 macOS 工作区没有 PHP 可执行文件时,需在下方 PHP 8.5 环境命令中复跑。
- Chrome 使用模拟 API 检查套餐购买、VM 详情/指标/凭据、公钥、重装/救援、后台宿主机/镜像操作与 CSRF;用户账户及登录等页面进行桌面/手机布局检查。不连接真实数据库或宿主机。
- PHP 隔离环境不提供 sodium:`CloudSecretsTest` 明确跳过,原 Paytaro/易支付密钥加密测试因同一缺失无法运行;财务/会话测试的加密存储仅用明确标注的测试替身,不作为实际加密验证。生产必须安装 sodium,没有弱加密回退。
- Python 的跳过项需要真实 libvirt/网络环境。没有验证真实 MariaDB 并发、AlmaLinux systemd、宿主机 VM 操作、SMTP、支付和大文件上传。
## 在具备依赖的环境复测
不要使用生产数据库/宿主机运行额外真实集成测试;以下默认单元/隔离测试:
```bash
cd /home/virt-cloud/web
for test_file in tests/*Test.php; do php "$test_file" || exit $?; done
cd /home/virt-cloud/engine
.venv/bin/python -m pip install -r requirements-dev.txt
PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m pytest -q -p no:cacheprovider
```
PHP 测试需 Composer 开发可用依赖和测试所用 PDO SQLite。测试中的模拟凭据、地址与密钥不是部署配置。
上线前按 [部署说明](DEPLOYMENT.md) 完成测试用户的实际购买、首次 SSH 登录、重装、救援、VNC 撤销、故障清理退款与无人登录时持续采样。另须使用短测试账期实际验证:到期只断网、宽限期续费恢复网络、宽限期结束后 VM 定义/系统盘/cloud-init 盘均被删除,以及删除失败或响应丢失时不会错误标记成功。共享公网网桥的 IP/MAC 防欺骗及宿主容量调度尚未提供,不能只凭单元测试开放不受信任客户的资源销售。