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

24 KiB

Virt Cloud 集成架构

更新:2026-10-07。描述当前实现边界;真实部署仍需测试环境联调。

请求链路

浏览器
  ├─ 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 地址池。

当前网络模型有意保持一条权威路径:每台宿主机只有一个 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 文件。 探测只识别现状,不在租户请求中安装包、加载 模块或修改规则。缺少能力时旧公网 VM 路径仍可保存宿主机,但 VPC 控制器 必须要求 vpc_ready=true,否则拒绝创建或变更私网。

云初始化和 libvirt XML 使用显式角色:公网网卡是 public0,私网网卡是 private0。公网静态 IPv4 保留唯一默认路由;私网只接受 RFC1918 /32, 关闭 DHCP/RA 且不带 gateway、DNS 或路由。旧的单网卡域可按兼容规则视为 公网,带多网卡但没有角色别名的域一律停止安全策略操作。面板的 clean-traffic/vc-fw-* nwfilter 只能绑定 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/firewalld 共存和跨宿主机连通性仍须 在验收环境验证。

当前阶段已增加引擎全局 Fabric 控制面:管理员可以只读查看状态,只有超级管理员 可以下发或核对配置。它只接受同地区 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,并要求 Debian 的 /etc/nftables.conf 或 AlmaLinux 的 /etc/sysconfig/nftables.conf 存在受管 include。 规则带 plan digest,启动 helper 会校验归属、结构、revision 和 include;规则被防火墙 重载清掉后,nftables 的持久配置负责重建,repair timer 负责短暂故障后的回读和修复。 启用或可能在重启时接管的 firewalld 与 native nftables 会被能力探测判为冲突;当前 Fabric 不把 raw nft 规则混入 firewalld direct/permanent 后端,也不会覆盖未知规则。 underlay UDP 端口的公网防火墙、NAT、MTU、SELinux/firewalld、管理器重载后的实际 连通性,以及 AlmaLinux 10 NetworkManager、Debian 13 ifupdown 在真实重启后的恢复, 仍属于真实宿主机验收项。Fabric 只使用独立的 wg-fabric0;管理器适配不得修改 br0、默认路由或宿主机管理接口。 真实验收步骤见 Fabric 宿主机验收矩阵。

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 不在引擎注册表中时门禁保持关闭。

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 不会每 30 秒重复请求;后续 数据面上线后必须由显式 reconcile 重新推进,不能把 waiting 当成 active。

VPC 私网数据面现在由引擎的独立 reconciler 执行。每台参与宿主机使用带 owner 标记的独立私网 bridge/tap,VM XML 使用不绑定 nwfilter 的 private0 和私网 /32 参数;公网 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 多网卡配置和 link-scope /32 路由。 宿主机 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。

当前已完成脚本/解析器和引擎集成的静态验证;真实 AlmaLinux 10 NetworkManager、 Debian 13 ifupdown、nft 语法、重启、防火墙重载、跨宿主机握手和故障回滚仍需按 VPC 私网数据面宿主机验收矩阵 执行。删除成员仍 保留 PHP tombstone,直到对应 VM private0 移除和宿主机资源回读完成。单台 VM 首版只允许加入一个 VPC,与当前单一私网角色和防止跨租户混网的边界一致。

本阶段没有 VPC 根删除接口。CIDR reservation 在租户私网数据面、引擎删除 tombstone 和宿主机回读闭环之前不会释放;这会保留地址以避免未知状态下复用, 不能把 allocator 的 active 误认为已经可以回收。后续删除流程必须先阻断新成员 变更、确认所有成员/路由/ACL 已收敛,再以独立 revision 和 CAS 释放 reservation。 删除中的宿主机、私网 NIC、地址、子网或成员 tombstone 仍会关闭 usable;这些 对象没有专门的删除回读证据时,不能在只剩其余宿主机 active 时提前放行。Route/ACL tombstone 属于已纳入每台宿主机精确路由、nft 和 revision/digest 回读的对象,只有所有 仍存活的宿主机逐一匹配后才会收敛为 deleted。空 VPC 也不会进入 active,必须先有 至少一个成员宿主机通过 Fabric 门禁。

VM 删除与 VPC 成员是两个独立状态机:仍有成员(包括 deleting tombstone)时, 手动删除和到期永久删除都会 fail-closed;到期实例进入 delete_failed/purge_failed, 等待管理员先完成成员及其引用 route 的 VPC 清理和后续数据面回读。删除 worker 不会在 引擎已返回成功后把 tombstone 伪造为 deleted。账户删除同样拒绝遗留 VPC 或私网 CIDR reservation,避免独立 VPC worker 继续消费孤儿租户计划。

AlmaLinux 10 与 Debian 13 的 WireGuard/NetworkManager/ifupdown 能力、真实宿主机 路由、SELinux/firewalld、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,历史清理见 PRUNING_REPORT.md。