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.
 
 
 
codex c980b4da73 feat(i18n): add administrator copy workspace 2 weeks ago
agent feat(storage): add resilient replica worker 2 weeks ago
config fix: align platform policy with dual stack 2 weeks ago
deploy feat(storage): split publication outbox worker 2 weeks ago
docs feat(i18n): define user copy manifest contract 2 weeks ago
gateway fix(cloud): repair portable backup preflight 3 weeks ago
release build(release): refresh linux amd64 binaries 3 weeks ago
tools feat(cloud): add portable VM backups 3 weeks ago
web feat(i18n): add administrator copy workspace 2 weeks ago
.gitignore feat: replace Python engine with Go host agents 1 month ago
AGENTS.md docs(traffic): add rollout and recovery runbook 2 weeks ago
README.md docs: document service compensation workflow 2 weeks ago

README.md

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。完整边界见 实例可用时间补偿。
  • 用户页面及登录页保持原虚拟机面板样式,管理员页面保留 venix 主题。普通用户不获得宿主机管理、Agent 设置或退役节点管理入口。
  • 任务只有执行中、成功和失败三种公开状态,终态只有 succeeded 或 failed;所有任务都有绝对截止时间。派发后超时或断线直接终态失败,并标记“效果可能已发生、不可重放原 operation ID”;任务不会停在“待核对”,也不会自动重试、退款或再次删除磁盘。实例设置可以用精确晚到回执,或 Agent 对同一 operation 的只读双标记证据,收敛 PHP 凭据/主机名账本与内部 effect fence;原任务仍保持失败,原宿主机 mutation 永不重放。不能可靠受 Go context 中止的 libvirt mutation 在独立子进程中执行,截止后由父 Agent 回收整个进程组。固定存储池配置是非破坏性的幂等例外:失败任务仍终止且不重放,但不保留跨任务资源栅栏;已定义的固定 pool 不做失败回滚,管理员可显式提交新任务核验或补全同路径固定池,绝不改绑、迁移或删除数据。

目录

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 和超过限制的文件。镜像来源的发行方可信度由管理员负责确认。

安装与验证

这是全新数据库版本。只能向空的业务库和日志库安装,旧表、旧密文、旧宿主机凭据及旧任务不能迁移或复用。完整步骤见 部署说明,职责与协议见 集成架构,单次派发和回执不变量见 单次派发任务架构,补偿账本见 实例可用时间补偿,验证门槛见 验证说明。

开放销售前必须在非生产宿主机完成 MariaDB 并发、Agent WSS/HMAC、UEFI、cloud-init 启动脚本、VM 生命周期、反向控制台、指标、流量、HTTPS 镜像/救援、付款和故障核对验收。单元测试通过不代表生产环境已验收。