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

51 lines
4.9 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
PHP 8.5 网站与私有 Python/libvirt 引擎集成的虚拟机销售面板。使用 `venix` 分支;`main` 的原 virsh-panel 不受影响。
## 本版功能
- PHP 统一注册、邮箱登录、账户、充值、支付、SMTP、工单;注册后无需创建审核。注册验证、密码重置、自动续费账单和实例开通成功通知均使用统一的用户面板邮件主题。
- 用户购买套餐开通 VM,余额扣款、库存扣减、确认创建失败退款;可手动续费,续费从已购期限末尾顺延。
- 套餐绑定宿主机,提供 CPU、内存、磁盘、网络带宽、账期天数和每期流量额度,用户不能随意修改套餐资源。
- 下载 RX 与上传 TX 按字节累加计费;当期额度用尽只断开 VM 网卡,不关机,下一已付费账期开始自动归零当期用量并恢复网络;无后续账期的最终到期才停机。
- 管理员管理多宿主机、全局云镜像目录和独立救援 ISO;云镜像既可从受信任的官方 HTTPS 地址下载,也可由管理员在浏览器上传不超过 4 GiB 的独立 QCOW2。支持 AlmaLinux 8/9/10、Debian 11/12/13、CentOS Stream 9/10 和 Ubuntu 20.04/22.04/24.04/25.04/25.10/26.04。用户切换地区时云镜像选择保持不变,首次部署由引擎按需同步到目标宿主机并缓存复用。
- 用户仅操作自己的 VM:控制台、开关机、软/硬重启、重装、救援、删除、初始 root 密码查看/复制。
- CPU、内存、磁盘 I/O、网络带宽图表;后台持续采集,写入日志库,最长保留 30 天。
- 全部用户页及登录页使用原虚拟机面板风格;管理员后台保留 venix 样式。
- 宿主机凭据及任务密码等敏感数据加密保存;内部请求签名,控制台使用短时一次性凭据。
- 超级管理员在线检查并更新固定 Gitea 私有仓库的 `venix` 分支;访问令牌由私有引擎加密保存且永不回显,更新由独立 root one-shot 服务执行。在线通道只快进代码并重启既有服务;不运行 Composer/pip、不准备依赖暂存区、不改写 systemd unit。目标版本修改 `engine/requirements.txt`、`web/composer.json`、`web/composer.lock` 或 `deploy/**` 时必须改用 SSH 升级;代码或数据库状态无法确认的失败会保留维护锁,其中数据库迁移中断不能仅靠回退源码解除,必须通过 SSH 人工完成并验证恢复。
## 目录与部署
```text
virt-cloud/
web/ PHP 网站、页面、SQL、测试
engine/ 私有 FastAPI/libvirt 引擎及测试
deploy/ 引擎、业务 worker、策略 worker 与按需更新 worker 的 systemd 配置
runtime/ 私有配置、密钥、引擎数据(安装生成,不入 Git)
docs/ 架构、部署、原清理记录
```
网站文档根目录必须是 `web/public`。引擎仅监听 `127.0.0.1:8000`;不能把整个网站反代到引擎,只有 `/engine-console` 的 WebSocket 转发给引擎。
云镜像的远程下载入口只接受官方镜像站的 HTTPS 文件地址,不接受下载介绍页;引擎只跟随由官方入口返回且通过公网地址安全校验的跳转链。AlmaLinux、Debian 和 CentOS Stream 使用 `.qcow2`;Ubuntu 官方云镜像文件名为 `.img`,但下载内容必须是 qcow2。支持的文件地址形式例如:
```text
https://repo.almalinux.org/almalinux/8/cloud/x86_64/images/AlmaLinux-8-GenericCloud-latest.x86_64.qcow2
https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2
https://cloud.centos.org/centos/9-stream/x86_64/images/CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2
https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64.img
```
自制或修复后的镜像使用管理员页面“从本机上传 QCOW2”。上传时必须选择与镜像内容一致的系统及版本;引擎会计算 SHA-256,并拒绝 raw/ISO、加密镜像、外部 data file、backing file、无法通过 QCOW2 结构检查的文件及超过 4 GiB 的文件。浏览器上传还需要按部署说明配置 PHP、Web 服务器和反代的请求体上限与超时。
全新安装见 [部署说明](docs/DEPLOYMENT.md),职责边界见 [集成架构](docs/INTEGRATION_PLAN.md)。配置使用 `web/config/config.php`,兼容旧文件名 `.config.php`;两者存在时前者优先。本版不导入原 Python 面板数据。
## 验证范围
已进行隔离 PHP 8.5 语法、模板、协议、SQLite 订单状态机和 Python 引擎测试。没有使用真实 MariaDB、SSH/KVM、付款或邮件通道完成生产联调。首次部署请先在测试宿主机验收,再开放销售。
超时后状态不明的任务保持 `uncertain`,不会直接退款或再次毁盘/创建。管理员需核对宿主机与任务状态,不能靠重复购买处理。这不是自动故障迁移、资源超售防护或高可用平台。
原清理边界见 [清理报告](docs/PRUNING_REPORT.md)。原 `/html` 与 `/virsh-panel` 项目未在本轮修改。