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

6.1 KiB

Virt Cloud 集成架构

更新:2026-09-27。替代此前“尚未集成”的计划,描述本版实现边界;真实部署仍需测试环境联调。

请求链路

浏览器
  ├─ 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 是唯一账户入口,所有用户页面使用原虚拟化面板 CSS;后台保留 venix。没有第二套 Python 注册、SMTP、数据库设置或审核流程。

数据职责

数据 权威写入方 存储
用户、钱包、套餐、原财务/工单 PHP 原业务库表
宿主机索引、订单、实例、账期、续费、公钥、会话、任务 PHP cloud_hosts/orders/instances/service_periods/renewals/ssh_keys/sessions/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,不共用一个可切换的全局“当前宿主机”。模板、IP 地址池、网关、DNS、虚拟机网卡前缀、磁盘/ISO/救援目录均按宿主机设置。地址池与网卡前缀分开:供应商地址池可以为 /28,虚拟机网卡可以为 /24,不能因此把售卖范围扩大为 /24。

PHP 不直接解密 Python 记录或执行任意 virsh 命令。主库与日志库可同实例或分别配置地址/端口。敏感业务数据加密;部署数据库连接配置仍是权限受限配置文件,不代表配置文件本身加密。

购买状态机

  1. 用户选择启用套餐、已有系统来源、公钥/强 root 密码,提交幂等键。
  2. PHP 事务锁定用户钱包与套餐,校验余额、库存、宿主机与实例配额,保存不可由浏览器改写的规格快照,扣款并保存加密任务。
  3. 独立 cloudWorker 获取租约,携带唯一 operation_id 请求引擎。只有经过签名的开通上下文可以创建 VM,用户不能免费创建。
  4. 成功关联实例和凭据;确认创建失败且无残留时只退款、恢复库存一次。
  5. 超时、引擎中断或残留无法确认时保持待核对,只查询原操作,不重复创建或盲目退款。

金额通过精确小数与整数最小单位换算处理,不用浮点完成扣款比较。套餐带宽转换成 libvirt 网卡双向 KiB/s 限制。开通和每次手动续费都生成一个独立预付费周期;提前续费只排在已购周期末尾,不会提前刷新当期流量。每期额度为下载 RX + 上传 TX;用尽只持久断开网卡,VM 不关机;下一已付费周期开始时以新的累计基线归零当期用量并自动恢复网卡。只有无后续周期的最终到期才禁用自启并停机;到期后续费恢复服务和自启,但不会擅自开启用户已关机的 VM。

单台实例默认最多排队 24 个未来账期,可通过 cloud_max_renewal_periods_ahead 调整(服务端限制为 1–120)。这个上限在实例行锁内校验,避免免费套餐或自动化重复请求无限写入续费与账期记录。

本轮不含自动扣费、套餐升级、按日比例退款或自动删除到期 VM。流量依赖约 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/反代超时与大小限制。

尚未实现宿主容量调度、分布式资源预留、IP/MAC 防伪、套餐磁盘 IOPS、备份、热迁移或 HA。线程中断进入待核对,并非完整步骤恢复;后续应增加运维对账与独立执行器。

上线前必须验收真实 MariaDB 并发、两库权限、宿主机固件/网桥/SELinux、cloud-init 与 SSH、浏览器 WSS、会话撤销、失败清理/退款。SMTP 沿用 venix,TLS 证书校验已恢复,自签邮件证书需修复信任链。

全新安装见 DEPLOYMENT.md,历史清理见 PRUNING_REPORT.md。