28 KiB
全新安装与启动
本版本只支持全新安装:不导入旧数据库,不读取旧引擎密文、配置或宿主机凭据,也不提供兼容回退。示例使用 AlmaLinux、项目目录 /home/virt-cloud、PHP-FPM 用户 apache;请按实际发行版调整包名和服务名。
面板服务器运行 PHP、数据库客户端、workers 和 Go Agent Gateway。每台 KVM 宿主机单独运行 Go virt-agent,Agent 只连接该机的 qemu:///system,并主动连接面板 WSS;不经 SSH 管理另一台宿主机。
1. 依赖
面板服务器:
- PHP 8.5 CLI/FPM、PDO MySQL、sodium、mbstring、curl、XML/DOM、OpenSSL、session,Composer 2。
- MariaDB:一个业务库和一个日志库;初始化账户需要建表权限。当前 SQL 以 MariaDB 为目标,不承诺兼容 Oracle MySQL。
- Redis 或兼容 Valkey,用于会话、验证码与限流。
- Go 1.24 或更新版本,用于构建本机 Agent Gateway。
- Nginx/Apache 与有效 HTTPS 证书。
每台虚拟化宿主机:
- Go 1.24 或更新版本、C 编译工具、
pkg-config、libvirt 客户端/开发头文件。 - 已配置的 KVM/QEMU、libvirt、网桥、存储池、UEFI 固件和
qemu-img。 - Agent 使用官方
libvirt.org/go/libvirtCGo binding;AlmaLinux 常用构建依赖为gcc pkgconf-pkg-config libvirt-devel。
不要为 Agent 开启未认证的 libvirt TCP。Agent 应通过本机 UNIX socket 使用 qemu:///system。
2. 安装面板
git clone --branch go --single-branch https://g.luoli.live/root/virt.git /home/virt-cloud
cd /home/virt-cloud/web
composer install --no-dev --prefer-dist --optimize-autoloader
网站文档根目录必须指向 /home/virt-cloud/web/public,不能指向仓库根目录。复制并编辑 PHP 配置:
cd /home/virt-cloud/web
install -o apache -g apache -m 0600 config/.config.php.example config/config.php
至少设置业务库、日志库、Redis、站点 HTTPS、Cookie、SMTP、支付以及 cloud_data_key_file。cloud_data_key 必须是 base64 编码的 32 字节独立随机密钥,PHP 使用版本化、用途/AAD 隔离的 XChaCha20-Poly1305 格式密封每台 Agent 的 HMAC 密钥、任务载荷和凭据;不能使用网站通用 key 代替,也不接受旧密文格式。
默认样例读取 /home/virt-cloud/runtime/php/data.key。在全新部署中生成一次,并确保 PHP-FPM 与 workers 都能读取:
install -d -o apache -g apache /home/virt-cloud/runtime/php
install -o apache -g apache -m 0600 /dev/null /home/virt-cloud/runtime/php/data.key
openssl rand -base64 32 > /home/virt-cloud/runtime/php/data.key
上述 owner/mode 只是使文件可读并收紧操作系统访问的部署建议;PHP 不审计它们,也不会因为可读密钥文件使用其他 mode 而拒绝启动。
3. 创建全新数据库
只对两个空数据库执行以下命令。不要把这一步当作旧库升级工具;检测到旧云表时应停止、另建空库并人工保留只读备份。
mariadb -h DB_HOST -P DB_PORT -u DB_USER -p BUSINESS_DB < /home/virt-cloud/web/sql/ss.sql
mariadb -h LOG_DB_HOST -P LOG_DB_PORT -u LOG_DB_USER -p LOG_DB < /home/virt-cloud/web/sql/user_log.sql
cd /home/virt-cloud/web
php xcat cloudInit
php xcat createAdmin
cloudInit 创建 PHP 拥有的云业务、Agent 注册、镜像、任务、账期、指标和流量结构;它不生成 cloud_data_key、不连接宿主机、不导入或转换任何旧记录。createAdmin 后核对 super_admin 只包含应有的超级管理员。
若实例是在缺少 PHP 模板展示快照的早期 Go Agent 版本中创建,更新面板代码后先执行只读检查,再显式应用元数据修复:
cd /home/virt-cloud/web
php xcat cloudRepairInstanceMetadata
php xcat cloudRepairInstanceMetadata --apply
命令默认只报告 would_repair,不会写数据库。--apply 只处理未删除且已成功创建的实例,并要求实例、订单、用户、宿主机和模板 ID 全部相互匹配;已有字段冲突、损坏 JSON、非云镜像或不可信模板元数据都会跳过,不能用该命令覆盖人工数据。修复优先使用付款时冻结在订单中的系统名称;仅对旧订单缺少完整展示快照时,才回退读取当前有效模板。可用 --limit=N 限制单次扫描数量;结果为 has_more: true 时,把返回的 next_after_id 传给下一次 --after-id=N,逐批完成检查或修复。
配置、密钥和数据库备份不得提交 Git。备份数据库时必须同步备份 runtime/php/data.key;仅有 SQL 无法解密 Agent 密钥。丢失该密钥不能通过导入旧引擎密钥或降级格式恢复。
4. 构建并安装宿主机 Agent
在与目标宿主机 ABI 相同的 Linux 环境构建,不要把 macOS CGo 产物复制到 Linux:
cd /home/virt-cloud/agent
go mod download
go mod verify
go test ./...
go test -tags libvirt ./...
go build -tags libvirt -trimpath -o /usr/local/sbin/virt-agent ./cmd/virt-agent
install -d /etc/virt-agent /var/lib/virt-agent
install -o root -g root -m 0600 \
/home/virt-cloud/deploy/virt-cloud-agent.json.example /etc/virt-agent/config.json
为每台宿主机生成不同的至少 32 字节随机密钥,并把相同值分别写入该机 Agent 配置和面板 /admin/agents 对应记录。agent_id 就是面板宿主机记录的正整数 ID,panel_url 是面板对 Agent 可达的 HTTPS origin。示例文件只有占位符,绝不能直接启动或提交真实密钥。保存启用配置后,先启动 Agent 建立出站会话,再到宿主机页注册五类存储目录,最后回到 /admin/agents 执行“测试连接”;存储尚未注册时能力测试会明确失败。面板仅在当前 revision 已通过健康与必要能力检查时才允许调度、业务 Agent 请求和控制台票据发放。密钥或启用状态修改会清除就绪标记。
Agent 配置字段:
| 字段 | 说明 |
|---|---|
panel_url |
面板 HTTPS origin,例如 https://panel.example.com;Agent 由此派生 wss://.../agent/connect 和 /agent/console |
agent_id |
面板对应宿主机的正整数 ID |
agent_secret |
该宿主机独立连接/HMAC 密钥,32~256 个非空格可打印 ASCII 字符 |
journal_path |
bbolt 事务型持久库,保存 operation_id、结果、expected-state 与 nonce 到期索引;systemd 样例下使用 /var/lib/virt-agent/operations.db |
libvirt_uri |
必须为 qemu:///system |
max_body_bytes |
请求体上限,默认 1 MiB,允许 1 KiB~1 MiB;云镜像正文不经过控制通道 |
clock_skew_seconds |
签名时间窗,默认 300 秒 |
nonce_ttl_seconds |
nonce 保留时间,默认 600 秒且不得小于 2 × clock_skew_seconds,以覆盖未来时间戳请求的完整有效窗 |
operation_timeout_seconds |
Agent API 内层操作等待上限,默认且最大为 840 秒;Agent WSS 控制层自动保留到 855 秒,外层 Gateway 固定 870 秒、PHP Worker 900 秒、任务租约 930 秒,逐层留出回执和持久化时间;超时不等于底层调用已取消 |
guest_agent_timeout_seconds |
在线快照执行 QEMU Guest Agent 文件系统冻结/解冻时的响应上限,默认 15 秒,允许 5~120 秒;它不限制后续 push backup 的执行时间 |
heavy_io_concurrency |
每台宿主机同时执行重 I/O 操作的容量上限,默认 4,允许 2~4;容量槽在操作进入派发状态前取得 |
storage_path_roots |
网页可下发存储目录的宿主机绝对路径允许列表;每个目录必须是允许根目录的真实子目录,不能是根目录本身、符号链接或其他角色目录的父/子目录 |
firmware_loader |
从本机 domcapabilities 选定的非 Secure-Boot EFI pflash loader 绝对路径 |
firmware_nvram_template |
与 loader 匹配的可写 VARS 模板绝对路径 |
nvram_directory |
受管每 VM NVRAM 文件目录的绝对路径 |
storage_path_roots 和固件字段都是必填项。Agent 配置文件不再填写 libvirt pool 名或网络映射;必须删除旧的 managed_storage_pool、template_storage_pool、seed_storage_pool 和整个 network_selectors 字段,否则严格配置解析会按未知字段拒绝启动。复制样例后,必须用目标宿主机实际允许的存储根目录和 virsh domcapabilities 支持的 loader/VARS 组合替换示例值。不得把 / 加入允许列表,也不要在样例 systemd 单元启用 ProtectHome=true 时使用 /home 下的目录。存储配置使用独立的短边界:面板 60 秒内必须派发,Agent helper 最多运行 120 秒,面板在派发后最多等待回执 180 秒。这些边界不会被通用 operation_timeout_seconds 放宽。
先在宿主机创建五个互相独立的真实目录,并为 libvirt/QEMU 配置正确的属主、权限、挂载和剩余空间;Agent 不会创建目录、挂载文件系统或删除其中的数据。保存并启用 Agent 连接后,在后台“虚拟机管理 -> 宿主机 -> 存储目录”填写系统盘与快照、云系统模板、cloud-init Seed、用户 ISO、救援 ISO 五类目录。Agent 校验目录是 storage_path_roots 的真实子目录后,分别注册固定名称的 persistent dir pool:virt-cloud-managed、virt-cloud-templates、virt-cloud-seeds、virt-cloud-user-isos、virt-cloud-rescue-isos,并启动、刷新和启用 autostart。若固定名称已被其他目录占用,Agent 会拒绝注册;不会扫描、复用或迁移其他 pool。
libvirt 的持久 pool 定义就是 Agent 后续使用的映射,不另写存储状态文件。系统盘与快照、模板、Seed、用户 ISO 和救援 ISO 后续只使用各自固定 pool。当前实现不兼容旧存储布局,也不提供自动迁移或回退读取;已有数据必须在启用本功能前另行完成受控迁移。首次成功应用后网页不允许更换路径。若任务以失败终态结束,旧 CloudJob 和 operation ID 保留为审计记录且绝不重放;管理员可修正尚未定义角色的目录,或按已经定义的同一路径显式提交一个新 CloudJob 和新 operation ID。固定存储池配置失败不会在 Agent Journal 中保留跨任务 storage-config 资源栅栏;Agent 启动时也会清理由旧版本生成的该类派生索引,但不会改写原 operation 或完成回执。配置过程是单调的:已经定义的固定 pool 即使后续步骤失败也不会被回滚、destroy 或 undefine,避免旧超时 helper 晚到后破坏新任务结果。新任务只会幂等地核验并补全同路径固定 pool;既不更换已有 pool 的路径,也不迁移或删除数据。宿主机同时还使用 journal_path + ".storage-config.lock" 的非阻塞进程锁;旧 helper 尚未退出时新任务立即以 storage_configuration_busy 失败,不等待、不自动重试,也不留下永久栅栏。注册成功后回到 /admin/agents 重新执行连接测试;storage_configuration capability 可用前,宿主机不会进入调度。
网络接入统一在宿主机页面填写“接入类型”和“网桥 / 网络名称”,新建默认 Linux 网桥 br0。面板保存为 bridge:br0 或 network:default 这样的 default_network;名称以字母或数字开头,后续只能包含字母、数字、点、下划线和短横线,bridge 名称为 1~15 字符,libvirt network 名称为 1~64 字符。宿主机上的网桥或 libvirt network 必须由运维预先准备。Agent 只选择、验证和使用现有网络,不创建网桥、不启动 libvirt network,也不修改宿主机系统网卡、路由或挂载。
Agent 的 capabilities 响应仍使用 network_selectors 字段,但它是自动发现的当前可用 bridge:<名称> / network:<名称> 列表,排序去重且最多 64 项,不再来自配置文件。Linux 网桥必须有 sysfs bridge 目录且接口为 UP;libvirt network 必须处于 active 状态。面板要求 default_network 精确匹配列表中的一项;每次创建或换网也会单独重验本次选中的网络。修改面板网络接入后,旧就绪结果立即失效,必须回到“Agent API”重新测试。
本版本只面向全新部署,不读取旧 public alias、旧网络映射或旧就绪记录。部署时必须直接填写真实的 bridge:<name> 或 network:<name>;不要复制旧 Agent 配置,也不要把旧数据库导入当前 schema。
Agent 的 systemd 单元保持 ProtectSystem=strict。journal_path 必须位于已授权的 /var/lib/virt-agent;若确需另一个状态目录,应由运维通过 systemd drop-in 精确增加对应 ReadWritePaths。存储池内容仍只由独立的 libvirt/QEMU 服务通过 qemu:///system 管理,不能把受管存储池目录授权给 Agent。删除回查需要清理域定义消失后残留的 UUID 专属 VARS 文件,因此样例 unit 仅额外授权标准 /var/lib/libvirt/qemu/nvram;若 nvram_directory 使用其他路径,必须在 drop-in 中用该实际目录替换,并保持授权范围只覆盖 NVRAM 目录。capabilities 只确认该目录存在,不冒充对 systemd mount namespace 写权限的验证;正式上线仍须用授权的创建/删除验收确认权限。
journal_path 是当前版本专用的 bbolt 数据库,不是可编辑 JSON;同目录的 .traffic.json 是流量状态,两者都要纳入一致性备份。Agent 会拒绝旧 schema,不执行升级或回填;全新安装必须使用空状态目录。Journal 在变更跨越派发边界前写入 operation tombstone,随后只允许这一次 worker 执行。Agent 重启若发现已启动但没有完整回执的 operation,会直接写入终态失败和执行栅栏,不会重新调用 libvirt。operation ID、指纹、资源、动作和终态永久保留用于防重放;完成回执的网络重发有固定次数和绝对截止时间,不会重新执行 mutation。
每个变更由独立 helper 进程打开自己的 libvirt 连接。父 Agent 到达绝对截止后终止整个 helper 进程组并执行有界 Wait;正常确认 helper 已退出后释放运行时 admission。若回收仍无法确认,Journal 会把任务终态化并释放进程内 admission:虚拟机和磁盘等破坏性操作继续由持久执行栅栏拒绝同资源的新 mutation;固定存储配置则由 helper 持有的宿主机非阻塞文件锁拒绝并发,旧进程真实退出时由内核自动释放。两类任务都不会长期保持运行中,固定存储任务也不会因旧失败留下永久栅栏。
配置必须存在、可读、是单个严格 JSON 对象并通过内容校验。Agent 不会检查文件 owner、group 或 mode,也不会因 0600、0640、0644 等可读权限差异拒绝启动;文档中的收紧权限只是运维建议。操作系统本身无权读取、JSON 损坏、字段未知或配置值无效仍会明确启动失败;这些是可用性/内容错误,不是权限位审计。旧的 listen_address、shared_secret、tls_cert_file 和 tls_key_file 会作为未知字段被拒绝;Agent 不启动入站监听。
安装并启动 service:
cp /home/virt-cloud/deploy/virt-cloud-agent.service /etc/systemd/system/virt-cloud-agent.service
systemctl daemon-reload
systemctl enable --now virt-cloud-agent.service
systemctl status virt-cloud-agent.service --no-pager
journalctl -u virt-cloud-agent.service -n 100 --no-pager
在面板 /admin/agents 为相同宿主机 ID 保存对应密钥并启动 Agent。先保持宿主机调度状态为 disabled;到宿主机页选择实际网络接入并应用存储目录,再回到 /admin/agents 执行连接测试。健康、存储和所选网络等必要 capabilities 全部通过后,才能启用资源调度和销售。如果二进制未带 libvirt build tag,Agent 会以 libvirt_adapter_not_built 明确失败,不会退化成外部命令或远程连接。
5. 面板 workers 与 Agent Gateway
PHP workers 不依赖本机虚拟化服务;它们先持久化任务,再通过本机 Agent Gateway 将请求发给任务绑定的 Agent:
cp /home/virt-cloud/deploy/virt-cloud-worker.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-lifecycle.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-policy-worker@.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now virt-cloud-worker.service virt-cloud-lifecycle.service \
virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service
普通 worker 负责购买、创建、重装、邮件和最终删除;至少两个策略 worker 处理到期断网、网络恢复与删除前策略;lifecycle 生成续费账单并推进账期、流量、宽限和删除状态。不要因某个 Agent 离线而停止其他宿主机的任务处理。
在面板机器构建并安装 Agent Gateway:
install -d /home/virt-cloud/bin
cd /home/virt-cloud/gateway
go mod download
go mod verify
go test ./...
go build -trimpath -o /home/virt-cloud/bin/virt-cloud-agent-gateway ./cmd/virt-cloud-agent-gateway
install -o apache -g apache -m 0600 \
/home/virt-cloud/deploy/virt-cloud-agent-gateway.json.example /home/virt-cloud/runtime/agent-gateway.json
cp /home/virt-cloud/deploy/virt-cloud-agent-gateway.service /etc/systemd/system/
Agent 与 Gateway 控制子协议固定为 virt-agent-control.v2,不提供 v1 兼容或降级。每次发布必须先准备同一提交构建的 Agent 和 Gateway 二进制,再在同一发布窗口替换并重启两端。混用新旧二进制必须在 WSS 握手阶段失败,不允许出现“健康检查成功但丢弃完成回执”。
启动前先编辑 Gateway runtime JSON,把 REPLACE_ME 占位符换成安全随机密钥,并在 PHP config.php 中配置完全一致的 cloud_agent_gateway_secret;cloud_agent_gateway_url 必须严格为 http://127.0.0.1:8001/internal/agent/request。占位符短于 32 字节,保留它会使服务拒绝启动。然后才启动:
systemctl daemon-reload
systemctl enable --now virt-cloud-agent-gateway.service
面板 Agent Gateway 只监听 127.0.0.1:8001。runtime/agent-gateway.json 的 panel_shared_secret 必须与 PHP cloud_agent_gateway_secret 一致;panel_introspection_url 和 panel_agent_auth_url 必须分别是字面 loopback IP 上的 /api/internal/cloud/session-introspection 与 /api/internal/cloud/agent-auth。Gateway 在 Agent WSS 握手以及每次普通请求或控制台打开前请 PHP 重新核验当前连接保存的 Agent 凭据;核验失败会撤销该连接。
agent_request_timeout_seconds 必须为 870。完整截止时间顺序是 Agent API 840 秒、Agent WSS 控制层 855 秒、Gateway 870 秒、PHP 900 秒,普通 worker 的 930 秒租约再包住 PHP 请求。不要把各层设置成相同值,否则外层可能先超时并丢失 Agent 已生成的结构化回执。
Gateway 用 X-Virt-* HMAC 以 actor {"service":"agent-gateway"} 调用 PHP。首次内省必须原子消费面板票据:
{"ticket":"<browser-ticket>","consume":true}
PHP 只返回下列字段;agent_id 对应已连接的数字 Agent 身份,过期时间为 UTC RFC3339:
{
"active": true,
"connection_id": "<opaque-connection-id>",
"agent_id": "42",
"agent_ticket": "<one-use-agent-ticket>",
"agent_expires_at": "2026-10-15T12:00:00Z"
}
Gateway 向对应 Agent 的控制长连接发送 console_open,Agent 消费票据并主动建立 /agent/console 反向 WSS。Gateway 每 15 秒发送 {"ticket":"<browser-ticket>","connection_id":"<opaque-connection-id>","consume":false}。会话、用户、VM 所有权和服务均仍有效时 PHP 必须严格只返回 {"active":true}。任何拒绝、超时或 active:false 都必须断开两端。
Agent Gateway 的配置加载不把 owner/group/mode 当成启动条件;只要实际 service 用户能读取并且 JSON/字段有效,不会因权限位不符合某个预设值而拒绝启动。建议使用最小读取范围,绝不要 chmod 777。
从旧版本撤除在线更新组件
如果旧版本已经安装过在线更新服务,请通过 SSH 在面板机确认以下路径确实属于该旧组件后,以 root 执行一次清理。本节只用于卸载遗留文件;当前版本不构建、安装或调用该组件。
systemctl disable --now virt-cloud-update.service || true
rm -f /etc/systemd/system/virt-cloud-update.service
rm -f /home/virt-cloud/bin/virt-cloud-update
rm -f /home/virt-cloud/runtime/update.json
rm -rf /home/virt-cloud/runtime/update
rm -f /run/virt-cloud/update.sock
systemctl daemon-reload
同时从 PHP 私有配置中删除旧的 cloud_update_helper_secret。不要删除 Agent Gateway 的二进制、配置、密钥或 systemd unit。
6. Web 与 WebSocket
所有普通页面和 JSON API 交给 PHP。将控制台以及 Agent 主动连接的 WebSocket 路径反代到本机 Go Gateway:
Gateway 配置样例使用 http://127.0.0.1/... 回调 PHP,因此必须另有一个明确绑定字面 loopback 的 HTTP vhost,把且只把两个固定回调路径交给同一 PHP front controller。该 vhost 不得执行 HTTP 到 HTTPS 跳转、域名规范化或代理到公开站点;否则 Gateway 会因禁止重定向而拒绝回调。下面的 PHP-FPM socket 路径应按发行版调整:
server {
listen 127.0.0.1:80;
server_name 127.0.0.1;
root /home/virt-cloud/web/public;
location ~ ^/api/internal/cloud/(?:session-introspection|agent-auth)$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root/index.php;
fastcgi_param SCRIPT_NAME /index.php;
fastcgi_pass unix:/run/php-fpm/www.sock;
}
location / {
return 404;
}
}
公开 HTTPS vhost 必须为上述两个 PHP 内部路径配置精确 return 404,不能让普通 PHP catch-all 暴露它们。启动 Gateway 前,应从面板本机分别向两个 loopback URL 发送未签名 POST,确认请求直达 PHP 并被 HMAC 校验拒绝,而不是得到 301、302 或 PHP 路由 404。
map $http_upgrade $cloud_connection_upgrade {
default upgrade;
'' close;
}
location = /engine-console {
proxy_pass http://127.0.0.1:8001/engine-console;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $cloud_connection_upgrade;
# Preserve a non-default public port because Origin validation compares
# the complete authority, not only the hostname.
proxy_set_header Host $http_host;
proxy_set_header Origin $http_origin;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
}
# These PHP callbacks and the Gateway dispatch endpoint are local-only.
location = /api/internal/cloud/session-introspection { return 404; }
location = /api/internal/cloud/agent-auth { return 404; }
location = /internal/agent/request { return 404; }
location = /agent/connect {
proxy_pass http://127.0.0.1:8001/agent/connect;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $cloud_connection_upgrade;
proxy_set_header Sec-WebSocket-Protocol $http_sec_websocket_protocol;
proxy_set_header X-Virt-Agent-ID $http_x_virt_agent_id;
proxy_set_header Authorization $http_authorization;
proxy_read_timeout 3600s;
}
location = /agent/console {
proxy_pass http://127.0.0.1:8001/agent/console;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $cloud_connection_upgrade;
proxy_set_header Sec-WebSocket-Protocol $http_sec_websocket_protocol;
proxy_set_header X-Virt-Agent-ID $http_x_virt_agent_id;
proxy_read_timeout 3600s;
}
不要公开 PHP 内省/认证接口、/internal/agent/request、Gateway 的本机端口或 libvirt。Agent 宿主机无需开放管理端口;出站网络只需能访问面板 HTTPS/WSS 和经校验的 HTTPS 镜像源。
控制台上线前必须验收:一次性票据只能消费一次、过期拒绝、登出/撤销后断开、跨用户/跨 VM 拒绝、Origin 校验、上游 Agent 断线及时关闭、浏览器不能注入 endpoint。Agent 未声明 console capability 时,PHP 必须显示不可用,不能回退旧实现。
7. 管理页面配置顺序
- 在
/admin/agents为每台宿主机保存独立密钥,在 Agent 配置中写入面板 HTTPS 地址、对应数字 ID 和同一密钥;出站连接测试通过但先保持调度 disabled。 - 创建宿主机业务记录、地区、资源池成员关系、容量和安全余量。面板策略、reservation 与具体 IP 账本是调度事实源。
- 配置预先存在的 bridge 和一个或多个公网 IPv4 CIDR;显式保留宿主机管理 IP。Agent 不通过扫描推测可售地址。
- 导入云镜像和救援 ISO。远程下载只接受可公开解析的 HTTPS 直链,Agent 会校验初始地址与全部跳转;来源的发行方可信度由管理员确认。本地上传必须是独立、未加密、无 backing/data file 的 QCOW2。
- 为每个云镜像按需设置首次安装启动脚本。脚本最大 32 KiB UTF-8、拒绝 NUL;保存后修订递增,新创建任务快照当前版本。不要在脚本中写长期密钥。
- 创建销售套餐和库存,再启用宿主机/Agent 调度。用户支付成功后只应创建一个 VM。
部署人员根据宿主机 domain capabilities 选择 Q35 UEFI loader/NVRAM 并写入该机 Agent 配置,Agent 用这组本地固定值生成明确关闭 Secure Boot 的 XML。首次启动脚本由 cloud-init 一次性 runner 执行;VM 创建成功不等待脚本完成,脚本失败或中断不自动重放。
8. 上线验收
在非生产宿主机完成以下测试后才开放销售:
- 通过 WSS 转发
/v1/health、/v1/capabilities的双层 HMAC、时间窗、nonce 重放和错误遮罩。 - 创建、启动、软/硬关机、软/硬重启、删除、重装、救援、快照、网络、防火墙、指标和控制台。
- Q35 UEFI 启动且 Secure Boot 关闭;不同宿主机固件路径通过 capabilities 选择。
- 云镜像启动脚本只执行一次,并覆盖成功、非零退出、重启及 Agent 断线。
- 并发提交相同幂等键只能得到同一个任务;同一任务的宿主机 mutation 调用计数只能是 0 或 1。
- 分别注入派发前拒绝、派发后断线、helper 超时、Agent 重启、Gateway 重启、PHP worker 重启和完成回执丢失;所有任务都必须在固定截止内进入
succeeded或failed,不能重新派发。 - 在明确授权的非生产宿主机重启实际启用的
virtqemud或libvirtd,确认 Agent 能恢复连接并重新注册 lifecycle、JOB_COMPLETED和 close callback,但不会扫描或执行历史 mutation。重启 Agent 后,已启动而未留下完整回执的 operation 必须终态失败并保留 durable fence。 - 杀死超时 helper 后确认整个进程组已回收;只有
Wait成功才释放资源 admission。不能回收时,新冲突请求必须立即被执行栅栏拒绝。 - 重复、乱序和晚到完成回执只产生幂等 ACK,不能改变终态;回执发送超过固定次数或绝对截止后必须停止。
- 并发购买不超卖 CPU/内存/磁盘/IP;同一 VM 变更串行。
- RX+TX 额度用尽只断网;下一账期恢复;最终到期只断网;三天宽限结束后删除定义与面板受管磁盘。
- MariaDB、Redis、SMTP、支付回调、大文件上传和 PHP-FPM 重启。
验证命令和记录格式见 VALIDATION.md。禁止在生产宿主机做破坏性验收;未授权主机只允许读 capabilities、版本、域/网络/池清单等只读信息。
9. 排错
journalctl -u virt-cloud-agent.service -n 200 --no-pager
journalctl -u virt-cloud-worker.service -u virt-cloud-lifecycle.service \
-u 'virt-cloud-policy-worker@*' -n 200 --no-pager
journalctl -u virt-cloud-agent-gateway.service -n 200 --no-pager
先区分 PHP 任务尚未派发、Gateway 未运行、Agent 出站 WSS 认证/网络失败、已派发但回执丢失、libvirt 明确失败和业务库提交失败。权限位与所有者不是应用层合规检查项;遇到启动错误应读取具体的“不可读、JSON 无效或字段无效”诊断,而不是盲目放宽权限。
任何破坏性任务在派发后超时都会立即显示终态失败,同时保留原 operation_id、reservation、IP、账单和安全栅栏。可以进行独立只读检查,但不要重放旧任务、直接改库释放、自动退款或再次毁盘;人工收敛后只能通过审计的 effect resolution 解除栅栏。