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

41 lines
7.0 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
Virt Cloud 是 PHP 8.5 面板与宿主机 Go Agent 组成的虚拟机销售平台。独立开发线固定为 `go`;不导入旧数据库,不保留旧 Python 引擎或兼容 API。
## 架构与功能
- PHP 负责账户、授权、余额、支付、订单、账期、资源账本、Agent 注册和持久任务协调。管理员在 `/admin/agents` 为每台宿主机配置独立 Agent 密钥;宿主机不向面板暴露 SSH、libvirt 或通用 Agent 管理端口。
- PHP 使用 `cloud_data_key` 的用途隔离密钥密封 Agent 密钥、任务载荷和凭据;只接受当前版本密文,不导入或尝试解密旧格式。
- 每台虚拟化宿主机运行 `virt-agent`,只连接本机 `qemu:///system`,执行 libvirt、存储、网络、快照、救援、指标和控制台后端操作。面板不保存 SSH/libvirt 登录凭据,也不直接执行宿主机命令。
- Agent 以 `panel_url + agent_id + agent_secret` 主动建立 WSS 控制长连接。PHP 先持久化任务并立即向浏览器返回 `202 Accepted`,再通过面板本机 Go Agent Gateway 派发一次带 SHA-256、时间戳、nonce、操作者上下文和 HMAC-SHA256 签名的请求。断线、超时或重启都不会重新派发 mutation。维护迁移的数据不经过面板:同资源池宿主机的 Agent 在 `peer_migration_port`(默认 `9443/TCP`)之间使用 TLS 1.3、一次性票据和源证书 SHA-256 锁定进行目标拉取;该端口只提供路径隔离的 PeerMigration V3 清单和工件 Range 读取,不暴露 libvirt 或通用管理 API。
- 同地区 VPC 使用宿主机既有私网作为 direct L3 underlay。PHP 负责地区 CIDR 池、VPC/IPAM、逻辑端口、宿主机完整路由投影和迁移编排;Agent 只按签名期望状态管理专属 bridge、精确 `/32` 路由、nftables 隔离规则以及一张可选 VM 私网网卡。VPC 不提供跨地区互联、NAT 或二层广播,也不改变由资源池线路、已验证宿主机网络接入和公网地址池共同确定的公网网络、公网防火墙及公网流量计费边界。
- 所有虚拟机使用宿主机能力支持的 Q35 UEFI,并明确关闭 Secure Boot。不要硬编码某个发行版的 OVMF 路径。
- 每个云镜像版本拥有对象存储中的不可变主副本,并按地区/宿主机维护派生副本;可配置仅首次安装执行的启动脚本。创建任务会快照镜像代次和脚本版本;脚本成功、失败或中断后都不会自动重放,租户不能读取或覆盖脚本正文。原始远程 URL 和旧的面板暂存下载路径不会写入模板目录,也不存在绕过主副本直接分发给 Agent 的兼容入口。删除先确认全部宿主机副本已清理,再删除主副本的精确对象版本;对象删除结果不明确时只做 HEAD 核对,不盲目重放 DELETE。
- 用户购买套餐开通一台 VM;每次购买或续费生成独立预付费账期及流量额度。新建实例账单的支付期限由后台按分钟配置,只影响之后生成的开通账单;续费账单的支付截止固定为其对应实例到期时间加三天,不会因账单延迟生成而顺延。额度用尽只断网、不关机;下一已付费账期恢复网络。最终到期只断网;未支付续费账单进入三天宽限期,之后永久删除 VM 定义和面板管理的磁盘。
- 管理员可以按单实例、计算节点或公网地址池创建可审计的可用时间补偿。补偿只延长当前尾服务周期以及已有流量/备份权益的结束窗口,不改变余额、流量字节或套餐,也不生成账单;执行和通知不联系宿主机 Agent。完整边界见 [实例可用时间补偿](docs/SERVICE_COMPENSATION.md)。
- 用户页面及登录页保持原虚拟机面板样式,管理员页面保留 venix 主题。普通用户不获得宿主机管理、Agent 设置或退役节点管理入口。
- 任务只有执行中、成功和失败三种公开状态,终态只有 `succeeded` 或 `failed`;所有任务都有绝对截止时间。派发后超时或断线直接终态失败,并标记“效果可能已发生、不可重放原 operation ID”;任务不会停在“待核对”,也不会自动重试、退款或再次删除磁盘。实例设置可以用精确晚到回执,或 Agent 对同一 operation 的只读双标记证据,收敛 PHP 凭据/主机名账本与内部 effect fence;原任务仍保持失败,原宿主机 mutation 永不重放。不能可靠受 Go context 中止的 libvirt mutation 在独立子进程中执行,截止后由父 Agent 回收整个进程组。固定存储池配置是非破坏性的幂等例外:失败任务仍终止且不重放,但不保留跨任务资源栅栏;已定义的固定 pool 不做失败回滚,管理员可显式提交新任务核验或补全同路径固定池,绝不改绑、迁移或删除数据。
## 目录
```text
virt-cloud/
agent/ 宿主机 Go Agent 与测试
web/ PHP 面板、页面、全新 SQL schema 与测试
deploy/ Agent、PHP workers 和 Agent Gateway 的部署样例
runtime/ 安装时生成的私有状态与密钥,不入 Git
docs/ 架构、部署、运维和验证说明
```
HTTP 文档根目录必须是 `web/public/`。普通页面和 API 全部由 PHP 提供。面板侧 `virt-cloud-agent-gateway` 同时承载 Agent 主动控制通道和反向控制台:浏览器只提交 PHP 签发的一次性票据;Gateway 仅在已连接会话的内存中暂存该 Agent 握手密钥,用于每次普通请求或控制台打开前向 PHP 复核,绝不持久化。未部署并验收 Gateway 时必须将 Agent 操作和控制台标记为不可用,不能回退到旧引擎。
Agent 和 Agent Gateway 只校验配置文件是否可读、JSON 与字段内容是否有效;它们不审计 owner、group 或 mode,不会因为可读文件是 `0600`、`0640` 或 `0644` 而拒绝启动。最小权限仍是运维加固建议,不是应用启动的权限位合规检查。
云镜像只接受经过校验的独立 QCOW2 内容;远程导入只允许可公开解析的 HTTPS 直链,并对初始地址及全部跳转执行 SSRF、大小与摘要校验,自制镜像通过管理员上传入口导入。拒绝 raw/ISO、加密镜像、外部 data file、backing file 和超过限制的文件。镜像来源的发行方可信度由管理员负责确认。
## 安装与验证
这是全新数据库版本。只能向空的业务库和日志库安装,旧表、旧密文、旧宿主机凭据及旧任务不能迁移或复用。完整步骤见 [部署说明](docs/DEPLOYMENT.md),职责与协议见 [集成架构](docs/INTEGRATION_PLAN.md),单次派发和回执不变量见 [单次派发任务架构](docs/TASK_EXECUTION.md),补偿账本见 [实例可用时间补偿](docs/SERVICE_COMPENSATION.md),验证门槛见 [验证说明](docs/VALIDATION.md)。
开放销售前必须在非生产宿主机完成 MariaDB 并发、Agent WSS/HMAC、UEFI、cloud-init 启动脚本、VM 生命周期、反向控制台、指标、流量、HTTPS 镜像/救援、付款和故障核对验收。单元测试通过不代表生产环境已验收。