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

78 lines
10 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/路由表验证、逐线路容量以及实例跨接入迁移策略,不能仅给现有公网池补一个线路下拉框。
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)。