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

485 lines
44 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.

# Virt Cloud 集成架构
更新:2026-10-07。描述当前实现边界;真实部署仍需测试环境联调。
## 请求链路
```text
浏览器
├─ HTTPS 页面/API → PHP:账户、授权、CSRF、套餐、钱包、订单
│ └─ HMAC 内部 API → Python → SSH/libvirt → 宿主机
└─ WSS /engine-console ──────────────────→ Python → SSH 隧道 → VM VNC
PHP cloudWorker → 持久任务 → Python operation_id → 实例关联/核对/退款
Python 后台采集 → 日志库指标/持久流量基线 → 图表与字节计量
PHP cloudLifecycle → 续费账单/独立账期/流量限额 → 到期断网、恢复或宽限期后永久删除
PHP cloudWorker → 隔离投递账单提醒和实例开通成功邮件 → SMTP 异常不阻塞开通事务及到期策略
```
PHP 是唯一账户入口,所有用户页面使用原虚拟化面板 CSS;后台保留 venix。没有第二套 Python 注册、SMTP、数据库设置或审核流程。
## 数据职责
| 数据 | 权威写入方 | 存储 |
| --- | --- | --- |
| 用户、钱包、套餐、原财务/工单 | PHP | 原业务库表 |
| 宿主机索引、资源池成员关系、网络接入、公网池/IP 账本、订单、实例、账单、支付映射、账期、续费、公钥、会话、任务 | PHP | `cloud_hosts/cloud_host_resource_pool_memberships/cloud_host_network_attachments/cloud_public_ip_pools/cloud_public_ips/cloud_orders/cloud_instances/cloud_invoices/cloud_invoice_payments/cloud_service_periods/cloud_renewals/cloud_ssh_keys/cloud_sessions/cloud_jobs` |
| 宿主机凭据、VM 元数据、镜像、操作进度 | Python | 主库 `engine_records`,敏感记录加密 |
| 引擎签名防重放 | Python | 主库 `engine_request_nonces` |
| 四项性能指标样本 | Python | 日志库 `engine_vm_metric_samples`,保留 30 天 |
| VM RX/TX 持久累计与网卡基线 | Python | 日志库 `engine_vm_traffic_totals`,不随 30 天图表样本清理 |
多个宿主机使用稳定 `host_id`,不共用一个可切换的全局“当前宿主机”。模板、磁盘/ISO/救援目录和默认网络均按宿主机设置;单台宿主机可在同一个 `default_network` 下保存多个互不重叠的公网 IPv4 CIDR。每个池有稳定 `pool_key`、独立网关/DNS/客户机前缀/保留地址/运行状态,以及 PHP 期望和已应用 revision。地址池与网卡前缀分开:供应商地址池可以为 /28,虚拟机网卡可以为 /24,不能因此把售卖范围扩大为 /24。面板由容量策略、reservation 和具体 IP 账本计算剩余资源;引擎只应用网络配置并在创建/换 IP 时做当前操作的最终校验。具体上线顺序见 [单宿主机多公网 IPv4 地址池](MULTI_PUBLIC_IPV4_POOLS.md)。
当前网络模型有意保持一条权威路径:每台宿主机只有一个 `default_network`,并通过唯一有效的资源池成员关系归属一条线路;多个公网 CIDR 共享该网络接入。线路管理和数据表为未来扩展保留,但“同一宿主机同时销售多条线路”尚未开放。该阶段必须增加多个资源池成员/网络接入选择、bridge/VLAN/路由表验证、逐线路容量以及实例跨接入迁移策略,不能仅给现有公网池补一个线路下拉框。
### VPC 接入前置契约
VPC 的第一版地址池由 PHP 从全局、可配置的 RFC1918 地址池分配(默认
`10.0.0.0/8`)。分配记录保留
`state/revision` 生命周期和释放历史;并发请求不使用新的全局应用锁,而是在一个
事务中抢占候选 CIDR 包含的 `/24` quantum 行。每个 quantum 的唯一键是跨
worker 的冲突点,冲突后重新读取账本并重试;因此不同候选块可以并发,重叠
候选不能同时提交。实例地址继续使用精确 `/32`,不把公网地址池或 `br0`
复用为私网地址池。
宿主机测试会通过固定、只读的 SSH 探测返回能力快照:系统发行版/版本、
`ip`/`wg`/`nft` 工具路径、WireGuard 内核模块、bridge、网络管理器、IPv4
转发、`rp_filter` 和防火墙规则所有者。AlmaLinux 10 只接受 `dnf`、
NetworkManager 和 `nmcli`,且 NetworkManager 必须处于运行和开机启用状态;
Debian 13 只接受 `apt`、经典 ifupdown/ifupdown2 共有的
`ifup`/`ifdown`/`ifquery` 命令(配置来源为 `/etc/network/interfaces` 或
`interfaces.d`)。systemd-networkd 会被识别但当前策略明确拒绝,
NetworkManager、systemd-networkd、ifupdown 同时运行、开机启用或持有配置时
一律标为冲突并拒绝私网变更;持有配置包括 NetworkManager keyfile、
systemd-networkd 的 `.network/.netdev` 文件以及 ifupdown 的 interfaces 文件。
防火墙只接受 `native_nftables` 所有权:`nft` 命令必须可用且规则集可读,
firewalld unit 必须不存在或 inactive+masked,且实时规则中不得存在
`inet firewalld` table。stock `nftables.service` 的运行、启用和 load 状态只作
诊断,不作为 nft 能力门禁;平台受管 service/helper 直接加载并回读自己的表。
仅 disabled 的 firewalld 仍可能被 D-Bus 激活,不能归入 native 模式。任何旧
`firewalld_nft` desired state、manifest、journal、zone/rich-rule 所有权或其他
管理器冲突都 fail-closed;普通
apply/reconcile 不做静默映射或自动接管。探测只识别现状,不在租户请求中安装包、加载
模块或修改规则。缺少能力时旧公网 VM 路径仍可保存宿主机,但 VPC 控制器
必须要求 `vpc_ready=true`,否则拒绝创建或变更私网。
`rp_filter` 必须按 Linux 的有效值语义判断:具体接口的有效值为
`max(conf/all, conf/<interface>)`,不能逐项把 raw `1` 一律判为失败。Alma/RHEL
的 `default=1` 以及公网 underlay(例如 `br0`)保持 strict 是正常且受保留的
发行版/运维策略,平台不得为了 VPC 改写全局 `all/default` 或公网、管理接口。
管理员 readiness 同时回显 `all/default`、endpoint 实际接口和 `wg-fabric0`
的 raw/effective 值;动态 `vnet*`/tap 不是 Fabric 路由门禁。平台只管理自己
拥有的 `wg-fabric0` 与 VPC bridge,并在接口承载私网流量前将其逐接口
`rp_filter` 持久化、设置并回读为 `2`;尚未创建的 `wg-fabric0` 显示为待自动
配置,不能伪装成已经检测成功,也不能因此要求管理员先手工放宽公网接口。
云初始化使用 `public0`/`private0` 作为 Netplan 配置键和产品角色;libvirt XML
使用符合设备契约的 `ua-public0`/`ua-private0` 用户 alias,两者不得混用。公网
静态 IPv4 保留唯一默认路由;`private0` 地址只接受 RFC1918 `/32`,另且仅下发一条
当前 VPC CIDR 的 scope-link 路由,关闭 DHCP/RA 且不带 gateway、DNS 或默认路由。
旧的单网卡域可按兼容规则视为公网;历史
`netN`/`ua-net-N` 公网 alias 只有在其他网卡全部明确为私网时才可用于运行态
迁移,其他无角色多网卡域一律停止安全策略操作。面板的
`clean-traffic`/`vc-fw-*` nwfilter 只能绑定 `public0` 产品角色(libvirt alias
为 `ua-public0`);私网 ACL 属于独立的 WireGuard/L3 nftables 上下文,不能把
公网过滤器复制到私网网卡。
宿主机数据面预留独立的 `wg-fabric0`。首次探测到一个没有面板所有权标记的同名
接口时必须停止私网接入;后续 reconciler 只有在固定的
`/etc/virt-cloud/wg-fabric0.owner` 标记为 `virt-cloud-wg-fabric-v1` 后才可认领
已有接口,避免重启后的能力刷新把面板自己创建的链路误判为外部冲突。它只承载宿主机间的加密传输;公网
`br0` 仍是外部接入,私网桥/tap、精确路由、AllowedIPs 和租户 ACL 由后续
VPC reconciler 单独管理。私网 libvirt 网卡在该阶段只接受已核验的独立
bridge/tap/device 来源,不接受无法确认底层桥接的 `network=` 间接来源;公网
nwfilter 与私网 ACL 永远是两套策略上下文。WireGuard 能力探测通过不改变系统的命令完成,
真正的 AlmaLinux/Debian 部署、SELinux/native nftables 持久化和跨宿主机连通性仍须
在验收环境验证。
当前阶段已增加引擎全局 Fabric 控制面。管理员页面按地区展示宿主机 readiness,正常
操作只保留“检测宿主机”“自动配置地区私网”“重新核对”三个按钮;浏览器不再编辑
Fabric ID、overlay、revision、端口、节点 JSON 或地区映射。普通管理员可以只读查看,
只有具有管理权限的超级管理员可以触发这三个动作。检测使用独立的只读宿主能力探针,
只返回白名单能力与字面 IPv4 endpoint;单批最多 64 台、引擎固定 16 路并发,同一引擎
不排队执行重叠检测。地区 readiness 清单最多检测 128 台(包含历史/orphan Fabric 节点),
而可自动配置的目标仍严格限制为 2 至 64 台。
`CloudHost.region` / `HostProfile.region` 是管理员可读的宿主机位置标签,只用于展示,
不是销售地区、Fabric identity 或 VPC 归属键。宿主机的权威地区唯一来自
`cloud_host_resource_pool_memberships -> cloud_resource_pools -> cloud_network_lines -> cloud_regions`
关系;新 Fabric 使用所选 `CloudRegion.code` 生成地区身份。位置标签可以与该 code/name
不同,不会因此阻断 readiness 或 VPC 成员接入,但成员关系断裂、重复或跨地区仍须
fail-closed。
宿主机运行配置另有可选的 `HostProfile.fabric_endpoint_ip`,专门表示 WireGuard
underlay 的 IPv4,不复用 VM 公网网桥语义,也不在面板 `cloud_hosts` 中保存第二份副本。
留空时 Engine 只会在 SSH `host` 本身是安全的字面 IPv4 时将其作为当前公网默认值;SSH
域名不会被隐式解析为 Fabric 身份。显式填写时可以使用公网或同地区内网 IPv4,但 fresh
probe 必须证明该地址确实属于对应宿主机,且地区内每个成员都必须能访问其他成员公布的
单一 endpoint。探针只向管理员 readiness 投影最终生效的 `endpoint_ip` 与受限来源
`configured` / `ssh_host_ipv4`,不会附带 SSH 地址、凭据或原始命令输出。
endpoint 不得落入当前全局租户 VPC CIDR 池;fresh readiness 会把这种地址标为阻断,
Engine 还会在 Fabric 变更和 VPC 应用两个方向对既有 CIDR 做纵深校验。这样后续内网
underlay 必须使用独立地址规划,不会被租户目的策略路由重新导向 VPC table。
管理员入口现在是服务端驱动的地区级向导:选择地区后,PHP 依据平台库存、固定映射和
引擎回读投影 `needs_probe`、`ready_to_apply`、`needs_reconcile`、`active`、阻断、迁移或
恢复阶段,并只返回有界的只读方案摘要。浏览器不能自行拼装节点、endpoint 或 raw plan,
也不能越过当前阶段启用按钮。公开的 raw plan apply、按任意 Fabric ID 直接 reconcile,
以及地区映射 PUT/PATCH 写入口已经移除;Fabric 详情和地区映射只保留管理员只读回读,
真正下发仍由地区动作在服务端生成固定 DTO 后调用受 HMAC/loopback 保护的 Engine 内部
接口。写请求返回 200 但权威阶段未到 `active` 时页面不会报告成功;请求超时或连接中断
以及 HTTP 5xx 都按结果未知处理,按地区禁止重复 apply,只允许通过“重新核对”收敛固定
desired state;其他地区的成功响应不会解除该保护。
“自动配置”只创建不存在映射且引擎也没有 desired state 的全新地区 Fabric。只要固定
desired state 已存在(活动映射、历史 disabled 映射或首次下发的部分成功),后续宿主机
写入都只能走“重新核对”:服务端重新校验地区、2 至 64 台规范宿主机、平台归属、fresh
capability probe、Fabric 详情/目录、冲突与精确计划,disabled 映射只有在同 identity、
region、revision 的 active 回读,且地区内每个未删除 VPC 都固定到相同三元组后,才能以
CAS 激活;VPC pin 漂移或映射缺失会直接进入显式迁移阶段。每个写动作都会自行重跑这些门禁,
因此显式“检测”是管理员预览步骤而不是可复用的旧快照。Engine 回读后的映射发布还会
再次复读平台拓扑,并在事务中锁定地区和映射;完整的多表 topology generation/CAS 仍是
后续并发强化边界。
浏览器内的“结果未知”只用于当前页面的交互防护,不作为执行账本、不会触发写操作重放。Engine 在接纳 apply/reconcile 时先持久化
32 位小写十六进制 `operation_id`,以 `202 Accepted` 立即返回;根记录只投影
`apply|reconcile` 与 `queued|running|succeeded|failed|uncertain|interrupted`,节点只投影
`identity|observe|apply`、固定 checkpoint 和固定 reason。同一轮所有宿主机共用同一
operation ID,页面仅轮询 Fabric GET 回读,不会因超时、刷新或第二管理员而重放 POST。
Engine 将每台宿主机的精确 apply 脚本、manifest 和状态以 root-only 文件写入
`/run/virt-cloud/fabric-operations/<operation_id>/`,然后通过
`virt-cloud-fabric-apply-<operation_id>.service` transient systemd oneshot 异步执行。
systemd 以绝对路径 `/bin/sh` 解释 runner,runner/update/apply 的内部状态更新也不直接执行
`/run` 文件,从而兼容宿主把 `/run` 挂载为 `noexec`;oneshot 用 `TimeoutStartSec` 约束完整
任务,不使用对 `Type=oneshot` 无效的 `RuntimeMaxSec`。
SSH 只负责精确 ID 的 dispatch/status 协议;任务 stdout/stderr 不返回面板,journal 只记录
operation ID、固定 state、checkpoint 和 reason。运行时间有上限,中断保留事务日志和当前现场
并禁止自动重放;远端 operation 目录有严格 owner/mode/hash 校验和有界终态清理,不删除
queued/running 或无法证明归属的对象。
Engine 重启或 dispatch 回包丢失时,页面 GET 与周期 reconcile 只使用原 operation ID
读取宿主状态并做精确 observe,绝不发起宿主写。只有管理员显式“重新核对”可以在严格证据下
继续同一个 ID:若不可变 operation 目录已发布、status 仍为 queued 且 systemd unit 的
`LoadState` 被证明为 `not-found`(任何 loaded unit 都不重启),可启动该目录中原 runner;
若部分宿主已经接纳任务,则必须先证明这些宿主
精确收敛,再对具有持久化“从未 dispatch”证据的其余宿主继续一次同 ID 下发。已接纳宿主绝不
重派,恢复过程绝不生成新 ID。旧 ID 仍无法终结时,新 apply 必须拒绝。只有所有宿主的计划
digest/revision/owner 精确回读且传输核验通过,才可设置 `next_stage_allowed=true`。
唯一升级例外是 immutable 脚本 hash 已变化、旧 status 精确证明从未启动,且 unit 为
`not-found/inactive` 或精确 `exit-code/exited/203` 的 legacy queued task:显式“重新核对”只把
旧 task 原子关闭为失败,不运行或覆盖旧脚本;下一次显式“重新核对”才创建新 ID。宿主 journal
恢复过程只公开固定的文件、nft、运行态和收尾子检查点,诊断写入不得改变 fail-closed 行为。
Engine 端仍以确定性 Fabric ID、revision
与 plan digest 拒绝不同计划覆盖,并让 Fabric apply/reconcile 与 VPC
apply/delete/reconcile/lifecycle reconcile/observe 共用一个进程内 catalog 准入锁。锁序固定为
“每资源锁 → catalog 锁 → 排序后的 VM 锁”;所有会读取 Fabric gate 后接触宿主私网数据面
或发布 active 的 VPC 路径都把 gate 读取、远端 mutation 和根/子记录提交放在同一临界区,
因而 endpoint 变更和 VPC CIDR/宿主收敛不能同时越过旧 gate。Fabric reconcile 先在该锁内
持久化关闭 gate,SSH 只读观测期间释放,发布前重新取锁并复核资源互斥。部署必须保持
单个 Engine Uvicorn worker;多 worker 或多实例必须先实现跨进程 durable reservation/CAS,
不能把当前 asyncio 锁解释为数据库事务。VPC apply 会扫描全部持久化
`fabric_desired` endpoint(不仅是它固定的 Fabric),重建每份计划并校验已存
`plan_digest`;损坏或 stale 记录一律 fail-closed,防止跨 Fabric 的 endpoint/CIDR 冲突。
面板侧协调协程被取消时只停止状态轮询;已被宿主 systemd 接纳的 mutation 继续由原
operation ID 所有。下次 Engine 启动先持久化关闭 Fabric gate,再做只读状态/精确回读;
一次暂时 404 或 SSH 断线不能证明原 apply 未执行。
readiness 的平台宿主机闭集由 active/draining 资源池成员、非删除实例宿主机、非删除
VPC deployment 宿主机与引擎 Fabric 漂移节点合并而成。断裂的成员关系、资源池/线路、
实例或 VPC 归属一律 fail-closed;任何未映射且不是本地区确定性 identity 的自定义
Fabric、不同地区 Fabric 对 required host 的占用、重复 endpoint 或 fresh probe 失败都会
在写宿主机之前阻断。未绑定的自定义 Fabric 即使节点看似一致也不会被自动认领、改名或
改写,而是保持 `migration_required`;向导只保留本地区确定性 identity 下发结果未知或
部分成功时原有的“重新核对”恢复路径,不提供旧自定义配置兼容。
自动配置的 Fabric identity、CGNAT `/24` overlay、revision、端口与排序后的节点由 PHP
确定生成;既有 desired state 只允许精确 reconcile,不会以当前可变 inventory 在同一
revision 下重建。映射写入同时使用拓扑复读与事务 CAS 防止并发管理员覆盖。
引擎只接受同地区
Full Mesh 计划,在每台参与宿主机独立创建并持久化 `wg-fabric0`、主机本地密钥、
peer、精确的宿主 overlay `/32` 路由,并通过专用 systemd helper 在宿主机重启后
恢复。私钥只存在宿主机的 root-only 文件中;引擎加密记录和 HTTP 响应只保存/返回
公钥、期望 revision 与回读结果。每次下发后都要重新读取接口、监听端口、peer、
route、owner marker 和 systemd 状态;旧的面板管理 peer/route 才允许被删除,未知
条目会保留并使节点进入 `degraded`。
Fabric 的状态分为 `applying`、`active`、`degraded`、`uncertain`。参与节点任一
失败不会回滚已经成功的节点;只有所有节点的精确配置回读为 `active` 且最近一次
宿主间握手核验通过时,统一记录才会返回 `next_stage_allowed=true`。引擎重启会把
中断的 `applying` 标为 `uncertain`,只读回读后再收敛;不会盲目重放破坏性命令。
该控制面仍不创建租户私网桥、libvirt 私网网卡或用户 VPC API。为避免 Fabric
接口在尚未接入租户 ACL 前被当作转发平面,宿主机 helper 会安装并维护一个带
`virt-cloud-wg-fabric-v1` 标记的最小 `inet virt_cloud_wg_fabric` forward
隔离规则,对 `wg-fabric0` 的跨接口转发默认丢弃;这不是租户 ACL,也不替代
后续 VPC 的 input/output 策略。未知 nftables 规则不会被覆盖,规则不符合归属
标记时节点保持非 active。Fabric 输入/输出只放行用于宿主间健康核验的 IPv4
ICMP,其余来自或发往 `wg-fabric0` 的主机服务流量丢弃;systemd repair timer
会在重启或暂时失败后重试。
`br0` 公网桥和现有 libvirt VM 路径不被 Fabric helper 修改。每次下发前仍必须
重新核对宿主机能力快照和 revision。
当前阶段没有 Fabric 删除/撤销 API;成员变更必须由后续迁移流程以新 revision
显式处理。Fabric 下发现在会在每台宿主机操作前重新执行固定能力探测,并在远端
`/run/virt-cloud/wg-fabric0.lock` 内串行化 identity、apply、observe 和管理器 hook。
apply 会先保存 panel-owned 配置、WireGuard peer/地址/路由、systemd 单元和 nft
状态;任一后续步骤失败会恢复该宿主机原状态,回滚自身失败时只保留
`uncertain/degraded`,不会返回 active。跨宿主机仍不自动回退已经健康的节点。
目标 peer 的 `/32` 会与所有路由表的宽前缀、blackhole、unreachable 和其他设备逐一
检查,默认路由不被当作 Fabric overlay 路由;重叠或无法核验时 fail-closed。
nftables 规则保存为 root-only 的
`/etc/nftables.d/virt-cloud-wg-fabric.nft`。native 模式要求 Debian 的
`/etc/nftables.conf` 或 AlmaLinux 的 `/etc/sysconfig/nftables.conf` 存在唯一受管
include。规则均带 owner 和 digest;helper 校验归属、结构、revision 和完整 include
集合。发现旧 firewalld manifest、journal、zone/rich-rule 所有权或 `inet firewalld`
table 时保留现场并拒绝普通 apply/reconcile,不会继续写规则。
underlay 只允许本机真实 endpoint:普通路由及显式 `from endpoint` 路由都必须
返回唯一且相同的地址归属接口,并选择该 endpoint 作为源地址。
panel-owned Fabric nft table 不放行 underlay UDP;管理员必须在宿主持久 native nftables
规则或上游云安全组/防火墙中,以最窄可证明的 peer 源地址、本机 endpoint
`/32`、UDP 和固定监听端口显式放行。外部 DNAT 也由运维管理;本地接口 active
或 unit green 不能代替双向 WireGuard 握手和实际流量验收。
NetworkManager profile 不写 zone、禁止 autoconnect,ifupdown fragment 不写 `auto`。
helper 必须先在单次原子 nft transaction 恢复并回读 Fabric 隔离和全部 VPC
inet/bridge/arp ACL,再激活接口,不查询、设置或要求任何 firewalld
zone/trusted 状态。panel-owned systemd
gate 同时约束已安装的 libvirt/
virtqemud/virtproxyd service 与 socket,避免 socket activation 或 VM autostart 在 ACL
恢复前开放私网。公网/内网 endpoint 实际可达、NAT、MTU、SELinux、native nftables/
NetworkManager/ifupdown 重启以及宿主机重启后的恢复仍属于真实宿主机验收项。Fabric
只使用独立的 `wg-fabric0`;管理器适配不得修改 `br0`、默认路由或宿主机管理接口。
repair timer 在主 Fabric service 明确 failed 时只重新排队该主 service,并只附带此前
确因 dependency 失败的 libvirt 单元;若主 service 为 active 且核验到受管 nft table
或接口漂移,则 reconcile service 直接执行同一份带 flock 的完整
ACL-first helper,不 restart 主 Fabric unit 或 libvirt。两条分支都保证完整 helper 每轮
最多执行一次,健康状态不触发修复。
受管 nft 事务使用完整 stateless snapshot、阶段 journal、`nft -c` 预检、最后一次
precommit 回读和单次原子 `nft -f` batch 保护现有数据面;任何所有权、snapshot
或回读不完整都保留现场并 fail-closed。旧 emergency owner/table 以及
firewalld owner/manifest/journal 都只是遗留检测证据,不是当前事务机制;它们
只能在事先备份且已停止租户流量的维护窗口由运维显式清理;当前 reconcile
不改写这些持久状态。
nft journal 明确记录 mutation/install/refresh 阶段,崩溃点恢复会重新核验 live table,而
不是根据上一条命令返回值推断提交完成。
boot helper 在降低每个 panel-owned VPC bridge 前后使用有界且严格解析的端口快照,拒绝
bridge 命令失败、畸形/重复/超量输出或端口集合变化,并在 `ip link set down` 后回读确认
`UP` flag 已消失。这样 NetworkManager 竞态不能越过 hard quarantine,同时不需要停用
bridge profile 或拆除正在运行 VM 的 tap。首次 apply 在 durable transaction commit 后释放
flock,再同步启动独立 reconcile dispatcher;dispatcher 等待 `RemainAfterExit` oneshot,
或在主 unit 已 active 时直接执行同一份完整 helper。apply 重新持锁并确认不存在旧
emergency owner/table,且主 service/timer active 及当前 digest/ACL/WireGuard 均匹配后才返回成功;提交态
旧进程不删除共享 journal,使 repair timer 在首次重启前也有可恢复、可核验的状态。
受管 nft 事务以完整 stateless snapshot、`nft -c` 后的最后 precommit 回读、单次原子
batch 和提交后回读保护进入事务前已存在的外部对象。nft CLI 不提供跨进程 CAS;同机
root/CAP_NET_ADMIN 与 out-of-band nft 管理器属于受信运维边界,必须遵守维护互斥,当前
设计不声称抵抗其在最后回读与提交之间进行的恶意或不协调并发替换。
真实验收步骤见 [Fabric 宿主机验收矩阵](FABRIC_HOST_ACCEPTANCE.md)。
### VPC 控制面(当前实现阶段)
VPC 控制面已经与公网 `network_change` 和 `cloud_jobs` 分开。PHP 的
`cloud_vpcs`、`cloud_vpc_subnets`、`cloud_vpc_private_ips`、`cloud_vpc_members`、`cloud_vpc_routes`、
`cloud_vpc_acl_rules`、`cloud_vpc_host_deployments` 和
`cloud_vpc_operations` 是租户意图、IP 分配、成员关系、Typed route/ACL、
宿主机部署门禁及持久操作的唯一业务模型。每个 VPC 根行是事务锁边界;修改
先锁 VPC,再按稳定顺序锁子资源和宿主机部署行,不在数据库事务中持有 SSH/HTTP
锁。私网地址有独立的 `/32` 租约行和 `CloudVpcPrivateIp` 模型;成员只保存对该
租约的引用和兼容性镜像。地址分配先锁 VPC 的全部租约行,数据库唯一键是最后的
并发冲突边界;删除/不确定状态的地址保留 tombstone,直到未来数据面回读确认,
不能被新成员复用。每次变更递增 `desired_revision`,以规范化 JSON 计算
`desired_digest`,操作行使用独立幂等键、租约和状态。
地区与引擎 Fabric 的关系由平台表 `cloud_region_fabrics` 明确保存
`fabric_id`、引擎使用的 `fabric_region` 和 `fabric_revision`,不会从可变的
数字地区 ID 推导,也不会由租户选择。管理员把映射置为 `active` 前,PHP 会通过
受信的超级管理员内部请求读取引擎 Fabric,并要求三项身份、revision、`active`
状态及 `next_stage_allowed=true` 全部精确匹配;引擎不可达或信息不一致时映射不
会写入。`disabled` 可用于提前录入部署配置,但会阻断 VPC 创建。映射变化在该地区
仍有未删除 VPC 时被拒绝。Fabric 参与宿主机使用现有引擎稳定 ID(当前 PHP 实例
`host_id` 以字符串发送),ID 不在引擎注册表中时门禁保持关闭。
宿主机记录中的 `region` 位置标签不参与这项映射,也不要求与 `fabric_region` 相等。
PHP 只向引擎发送固定 DTO:VPC/地区/Fabric revision、子网、实例 UUID、宿主机
稳定 ID、精确 `/32` 私网地址、Typed route 和 ACL。它不会发送 shell、libvirt XML、
公钥私钥、网卡命令或 raw nft 规则。引擎只在 Fabric 同地区、同 revision 且
`next_stage_allowed=true` 时打开下一阶段门禁;它会保存独立的 desired/observed
记录和每个 VPC 的锁。引擎重启会关闭门禁但保留最后观测证据,重新回读后才能恢复。
PHP 只有在所有参与宿主机的观测 revision/digest 完全匹配时才把 VPC 标为
`active/applied/usable`;CIDR allocator 的 `active` 只代表地址已保留,不能代表
私网已经连通。
`cloud_vpc_operations` 由独立的 `virt-cloud-vpc-worker.service` 消费;它使用
自己的租约、重试和引擎调用,不由现有 `cloudWorker` 的公网/VM 任务队列代领。
如果该服务未安装,API 仍会安全地保留 `queued` 状态,显式
`POST /api/v1/vpcs/{vpc_key}/reconcile` 可用于人工核对,但不能把 queued 当作
已经下发。引擎只证明 Fabric 已就绪、而本阶段没有私网数据面回读时,操作会进入
`waiting_observed`、根同步状态为 `waiting`;专用 worker 会周期性执行幂等
reconcile,也可由显式 reconcile 立即推进。重试必须保持 seed、XML 和宿主数据面
幂等,不能把 waiting 当成 active。
VPC 私网数据面现在由引擎的独立 reconciler 执行。每台参与宿主机使用带 owner
标记的独立私网 bridge/tap,VM XML 使用不绑定 nwfilter 的 `ua-private0` alias
和私网 `/32` 参数,对外仍投影为 `private0` 产品角色;公网 `br0`、公网默认
路由和公网 nwfilter 不会被复用。宿主机策略表
只安装成员/服务精确 `/32` 路由(自机走私网 bridge,跨机走 `wg-fabric0`),并
为每个 WireGuard peer 合并精确 tenant `AllowedIPs`。每个 VPC 还有独立的 inet、
bridge 和 ARP nft 表:ACL 按 priority 处理,bridge 入口校验 MAC/IP/ARP,IPv6、
广播、多播和未知目的地址默认隔离;代理 ARP 仅允许面板登记的精确 `/32`。
云初始化 seed 同步写入 `public0`/`private0` 多网卡配置和唯一的 scope-link VPC CIDR
路由。NoCloud 只在 boot 事件重新消费该网络配置:运行中的 VM 首次接入或其 MAC、私网
IP、VPC CIDR
变化时,引擎不会改写 seed、持久 XML 或 live 网卡,而是保持旧配置并返回待重启;VM
完全停机后,下一次 reconcile 才原子写入 seed 和持久 XML,随后一次完整 start 才消费
新网络配置。独立的 guest-network generation 只覆盖 MAC、私网 `/32` 地址和 VPC 前缀;
成员、自定义 route、ACL 等宿主侧变化不改变 generation,避免一次成员变更要求所有运行中
成员重启。只有完整 stop/reconcile/start 后 live domain metadata 带有目标
generation,成员才能通过 active/usable 门禁;
缺失或旧 generation 会保持 `waiting_observed` 并返回
`vpc_private_guest_restart_required`。相同目标的重试不再轮换 NoCloud `instance-id`,
避免重放用户、密码和 sshd 等 per-instance 模块;缺少当前 `boot-v1` 网络更新策略的
旧 seed 以 `vpc_seed_network_policy_migration_required` 失败关闭,必须重装或执行明确的
离线迁移,不能通过轮换 instance-id 静默升级。
live generation 一致仍不等于来宾网络可用。每个运行成员还必须通过 QEMU Guest Agent
回读:`guest-info` 明确启用 `guest-exec`/`guest-exec-status`;链路探测固定使用
`/usr/bin/timeout` 与 `/usr/bin/head` 读取 sysfs,路由探测只允许固定的
`/bin/sh -c 'exec /usr/sbin/ip -j -4 route show table main dev "$1" | /usr/bin/head -c 131073'`
脚本,唯一可变参数是已校验的 guest 接口名。回读必须确认唯一接口的 MAC、精确 IPv4
`/32`、admin/carrier/oper link-up,以及 main table 中恰好一条当前 VPC CIDR 的
scope-link 路由,且没有 gateway、nexthop、`linkdown`、`dead` 或 `unresolved`。
agent/channel/service、命令 allowlist 或固定二进制缺失时分别返回
unsupported/unavailable/uncertain/deadline evidence,成员保持不可用。该 QGA 证据是
租户可控来宾的 readiness 信号,不是 VPC 隔离的安全边界;隔离仍由宿主 bridge、route、
WireGuard 和 nft 回读证明。显式 network suspend 是例外:精确 persistent/live XML 的
`link state='down'` 与宿主配置可以证明隔离已生效,但该成员绝不能因此被标为 usable。
宿主配置提交和成员运行态分开收敛:当前 revision/digest 的 bridge、路由、ACL、seed
与 inactive/live XML 配置证据可完成控制面操作和 tombstone 回收;每个成员的
active/usable 则只由自己的 current-generation QGA 证据推进。一台关机、待重启或
agent 不可用的 VM 不得抹掉同 VPC 其他已验证成员的可用状态,但 VPC 聚合健康仍可显示
degraded,周期 reconcile 会继续推进尚未就绪的成员。
历史 seed 中逐成员 `/32` route 只用于旧 generation;运行中成员保持
`vpc_private_guest_restart_required`,完全停机后的 reconcile 才迁移为单条 VPC CIDR。
4096 成员上限保护记录和回读大小,但普通周期 reconcile 在进入并发 QGA 阶段前仍会按宿主
顺序执行每台 VM 的 seed/libvirt 核对;生命周期目标会优先,整宿主满规模延迟仍需真实压测,
不能把单次 HTTP 预算当作全量收敛时限。
本契约使用 `evidence_version=2`。滚动发布顺序必须是:先应用数据库 schema,再部署能
持久化/校验 v2 的 PHP 与 worker,最后部署 engine;混合版本及历史缺失版本证据一律
fail closed,不能回退接受仅有 XML 的旧 succeeded receipt。
宿主机 apply 在 Fabric 锁和 VPC 锁内执行,持久文件、NetworkManager/ifupdown
配置、路由、策略规则、WireGuard、nft、代理 ARP 和 sysctl 都有实际回读;apply、
实例接入和停机 libvirt 路径中途失败会按 ownership marker 恢复,响应不确定时保持
`uncertain`,不猜测性反向操作。删除/撤销路径另外保留阶段 journal 并 fail-closed:
未提交事务只进入 `uncertain/manual_reconcile`,不会重复执行破坏性删除,只有已提交
且完成资源不存在性证明后才清理 journal。PHP
只在每台宿主机的 XML、路由、ACL、反欺骗、代理 ARP、rp_filter 和完整 peer
AllowedIPs 证据都匹配当前 revision/digest 后才把 VPC 标为 `active`。
VPC apply/remove/rollback/启动恢复以单次 nft batch 建立或恢复受管 table;
只有全部 ACL marker/digest 精确回读后才能重新激活 bridge。NetworkManager 或
ifupdown 重启不会依赖 profile 自动连接来绕过
该顺序;libvirt daemon service 受 Fabric gate 约束,socket activation 触发的仍是
同一个受门禁的 daemon。socket 保留默认早期启动顺序,避免与网络依赖形成循环。
当前已完成脚本/解析器和引擎集成的静态验证;真实 AlmaLinux 10 NetworkManager、
Debian 13 ifupdown、nft 语法、重启、防火墙重载、跨宿主机握手和故障回滚仍需按
[VPC 私网数据面宿主机验收矩阵](VPC_DATAPLANE_ACCEPTANCE.md) 执行。删除成员仍
保留 PHP tombstone,直到对应 VM `private0` 移除和宿主机资源回读完成。单台 VM
首版只允许加入一个 VPC,与当前单一私网角色和防止跨租户混网的边界一致。
VPC 根删除使用独立的 `DELETE /api/v1/vpcs/{vpc_key}` 状态机。PHP 先在 VPC 行锁内
阻断全部新变更,把根和仍存活的子资源推进到 `deleting`,再建立不可被新操作替换的
`vpc_delete` revision。删除目标除空的子网、成员、route 和 ACL 集合外,还包含摘要
覆盖的 `retiring_members` 闭集(member ID、实例 UUID、宿主机、私网 IP 和 MAC);
该清单覆盖“宿主机/libvirt 已变更、但旧 apply 尚未写回引擎持久记录”的中断窗口。
引擎先持久化删除 marker,再逐成员移除并回读持久化 `private0` XML 与 cloud-init seed,
逐宿主机移除 bridge、route、WireGuard tenant AllowedIPs、nft 和 sysctl 状态。只有所有
成员与宿主机都得到精确不存在性证明后,引擎才先写 durable receipt、再清理 desired
记录;丢失 HTTP 响应时只能用原 operation/revision/digest 重取同一回执。终态回执只
保留操作身份、摘要、宿主机闭集和完成时间,不永久保留成员 UUID、私网 IP 或 MAC;
旧格式回执在首次读取或引擎恢复时会压缩为同一最小 tombstone。
PHP 只接受与当前删除操作和摘要一致、且覆盖删除 payload 全部待清宿主机的回执;回执
不得包含 PHP 从未部署过的宿主机,已由历史精确证明为不存在的宿主机则允许重复出现或
省略。PHP 在同一数据库事务中核对 CIDR interval 与全部 /24 claim 后,以 revision CAS
释放 reservation;随后才把
根置为 `deleted` 并清除已完成的子资源账本。任何宿主机、成员 XML、回执、CIDR 或 claim
证据缺失都会保留删除 tombstone,不会提前复用地址。运行中的 VM、managed-save 或原生
快照会让 private0 移除 fail-closed,处理对应实例状态后通过显式 reconcile 重试原删除
操作。根处于 `deleting` 时,VM 生命周期回读只能补充证据,不能越过根 finalizer 单独
终结成员账本。删除完成后该根不再阻止 Fabric identity/revision 变更;账户删除只会清除
`deleted` 根及已 `released` 且无残留 claim 的网络历史。
普通成员/route/ACL 删除仍使用各自 tombstone。删除中的宿主机、私网 NIC、地址、子网或
成员会关闭 `usable`。成员/IP 只有在其 owner host 提供当前精确 active 回读(同宿主仍有
成员)或精确 removal 回读后,且全部当前 live host 的 route、WireGuard、proxy 与 nft
集合都匹配时才释放;每台宿主机的 removal proof 单调持久化,部分失败重试不要求已清理
宿主机再次在线。Route/ACL tombstone 使用同一全宿主精确门禁。子网本身没有宿主对象,
无引用时可在全宿主精确门禁后释放;完全没有参与宿主机时,也可由明确的 no-members
terminal gate 完成子网控制面删除。空 VPC 的控制面操作可以完成,但根保持
`degraded`/不可用,必须先有至少一个成员宿主机通过 Fabric 门禁才会进入 `active`。
VM 删除与 VPC 成员是两个独立状态机:仍有成员(包括 `deleting` tombstone)时,
手动删除和到期永久删除都会 fail-closed;到期实例进入 `delete_failed/purge_failed`,
等待管理员先完成成员及其引用 route 的 VPC 清理和后续数据面回读。删除 worker 不会在
引擎已返回成功后把 tombstone 伪造为 `deleted`。账户删除同样拒绝活动或删除未完成的
VPC,以及未释放或仍有 claim 的私网 reservation,避免独立 VPC worker 继续消费孤儿
租户计划。
AlmaLinux 10 与 Debian 13 的 WireGuard/NetworkManager/ifupdown 能力、真实宿主机
路由、SELinux/native nftables 持久化、MTU 和跨机房连通性尚未在本地环境宣称通过;必须完成
上述 Fabric 与 VPC 宿主机验收矩阵后,才能把环境状态推进为可上线。
PHP 不直接解密 Python 记录或执行任意 virsh 命令。主库与日志库可同实例或分别配置地址/端口。敏感业务数据加密;部署数据库连接配置仍是权限受限配置文件,不代表配置文件本身加密。
在线更新同样遵守这条边界:PHP 仅做超级管理员授权、CSRF 和固定路径代理;Gitea 令牌由私有引擎写入加密 `engine_records`,Git 快进、幂等升级及现有服务重启只由按需启动的 root `virt-cloud-update.service` 执行。仓库和 `venix` 分支均不可由浏览器修改,更新仅允许干净工作树上的 fast-forward。在线流程不运行 Composer/pip、不建立依赖暂存区、不改写 systemd unit;目标提交一旦修改 `engine/requirements.txt`、`web/composer.json`、`web/composer.lock` 或 `deploy/**`,必须在停服与切换前拒绝并改走 SSH 升级。工作器以持久检查点区分“代码已切换但数据库未确认”、“数据库正在迁移”与“数据库已就绪”;不安全的中断进入 `blocked` 并保留维护锁,不会在兼容性未知时自动启动服务。特别是进入 `schema_migrating` 后,MariaDB DDL 可能已部分提交,仅回退源码不足以解除维护锁。
## 购买状态机
1. 用户选择启用套餐、已有系统来源、公钥/强 root 密码,提交幂等键。
2. PHP 事务校验销售库存、宿主机面板容量与公网 IP 账本,保存不可由浏览器改写的规格快照和加密创建载荷,预留有限库存并生成开通账单;此时不扣钱、不创建引擎任务。账户不设固定实例数量上限。
3. 余额或在线支付结清账单后,同一事务才扣减钱包并创建唯一队列任务。未支付开通账单 30 分钟后失效,释放库存并清除其加密凭据载荷;晚到的在线付款只保留为账户余额。
4. 独立 `cloudWorker` 获取租约,携带唯一 `operation_id` 请求引擎。只有已支付且经过签名的开通上下文可以创建 VM。
5. 成功关联实例和凭据;确认创建失败且无残留时只退款、恢复库存一次。超时、引擎中断或残留无法确认时保持待核对,只查询原操作,不重复创建或盲目退款。
金额通过精确小数与整数最小单位换算处理,不用浮点完成扣款比较。套餐带宽转换成 libvirt 网卡双向 KiB/s 限制。到期前 7 天幂等生成一张续费账单和可重试邮件任务;账单可由余额结清,也可绑定现有在线支付订单。网关回调先入账余额并在同一事务结清账单,净余额为零;账单已结清或失效时晚到款保留为余额,不能重复续期或丢失。每次结清账单都生成一个独立预付费周期,提前支付只排在已购周期末尾,不会提前刷新当期流量。每期额度为下载 RX + 上传 TX;用尽只持久断开网卡,VM 不关机;下一已付费周期开始时以新的累计基线归零当期用量并自动恢复网卡。
未支付账单不会延长到期时间。实例到期时只停用网络,不改变用户原来的开关机状态;在随后 3 天宽限期内结清账单会建立新账期并自动恢复网络,也不会擅自开启用户已经关机的 VM。到期满 3 天仍未支付,账单失效,系统先安全收敛虚拟机电源状态,再永久删除实例定义和面板管理的系统盘;此后支付渠道的晚到款只进入账户余额,不能恢复已经删除的实例或磁盘。数据库继续保留订单、账单和支付审计记录,“永久删除”指宿主机上的实例及其受管磁盘数据。
单台实例默认最多排队 24 个未来账期,可通过 `cloud_max_renewal_periods_ahead` 调整(服务端限制为 1–120)。这个上限在实例行锁内校验,避免免费套餐或自动化重复请求无限写入续费与账期记录。
本轮不含免确认自动扣费、套餐升级、账单自动退款或按日比例退款。已生效服务账单不得通过支付渠道自动退款;需要人工审核并进行补偿记账。流量依赖约 60 秒的宿主机采样,因此限额可能有一个采样间隔的少量超额;日志库不可读时采取 fail-open,不会因未知流量误停租户。
## 安全与控制台
- 用户 ID、角色、VM 归属由 PHP 确定,不能相信浏览器身份字段;引擎再次检查归属。
- 管理员与 `super_admin` 白名单权限分开;跨用户只读不自动获得跨用户写权限。
- 云 API 写操作校验 CSRF;未登录/无权限返回 JSON,不重定向 HTML。
- HMAC 覆盖方法、完整路径/查询、请求体摘要、时间戳、nonce、身份。防重放存储是共享的持久数据库/Redis。
- PHP 签名密钥与任务加密密钥独立生成;任务使用 sodium secretbox 随机 nonce,引擎有独立 master.key。备份时保存密钥,不能删除后期待解密数据。
- root 公钥和密码可以同时设置,未填密码时生成强密码;root 密码策略独立于网站 bcrypt 的 72 字节限制。
VNC 凭据 60 秒有效、单次、绑定用户/VM/会话,通过 WebSocket 子协议传递而非 URL。连接期间持续校验 PHP 会话,退出或停权会阻止继续访问。线上使用 HTTPS/WSS。
## 原虚拟化功能与限制
保留云镜像/ISO 创建、UEFI/ACPI、host-passthrough、virtio 队列随 vCPU、开机自启、首次安装重启停止并弹出 ISO、磁盘删除、重装网络保留、救援挂载/卸载、SSH 隧道 VNC。救援正常关机失败不会自动断电,用户可确认硬重启,主动退出救援前 ISO 保持挂载。
重装、救援、手动删除和到期自动清理使用持久操作编号,进程中断不盲目重复破坏性步骤。自动清理只有在实例定义和受管磁盘的删除结果得到确认后,才把业务库实例标记为已删除;宿主机或磁盘异常会保留失败状态供管理员处理,不会伪装成成功。救援 ISO 为管理员授权原始流上传及摘要校验;线上需配置 FPM/反代超时与大小限制。
已实现按资源池的面板容量策略、CPU/内存/磁盘 reservation 和具体 IP 账本调度,多公网池配置使用稳定请求标识与 revision 幂等写入;不再周期盘点宿主机容量或 IP。用户列表、状态同步和生命周期观察只向引擎发送面板已知的 UUID,宿主机保存/测试也不枚举全部域。尚未实现同一宿主机多线路选择、IP/MAC 防伪的完整租户策略、套餐磁盘 IOPS、备份、热迁移或 HA。线程中断进入待核对,并非完整步骤恢复;后续应增加基于 `operation_id` 的运维对账与独立执行器。
上线前必须验收真实 MariaDB 并发、两库权限、宿主机固件/网桥/SELinux、cloud-init 与 SSH、浏览器 WSS、会话撤销、失败清理/退款。SMTP 沿用 venix,TLS 证书校验已恢复,自签邮件证书需修复信任链。
全新安装见 [DEPLOYMENT.md](DEPLOYMENT.md),历史清理见 [PRUNING_REPORT.md](PRUNING_REPORT.md)。