23 KiB
全新安装与启动
本版本只支持全新安装:不导入旧数据库,不读取旧引擎密文、配置或宿主机凭据,也不提供兼容回退。示例使用 AlmaLinux、项目目录 /home/virt-cloud、PHP-FPM 用户 apache;请按实际发行版调整包名和服务名。
面板服务器运行 PHP、数据库客户端、workers、更新 helper 和 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 或更新版本,用于构建本机更新 helper 与 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 只包含应有的超级管理员。
配置、密钥和数据库备份不得提交 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 建立出站会话,再在管理页执行“测试连接”。面板仅在当前 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 秒,逐层留出回执和持久化时间;超时不等于底层调用已取消 |
managed_storage_pool |
Agent 创建和删除 VM 系统盘的受管 libvirt 存储池名 |
template_storage_pool |
已校验云镜像模板所在的 libvirt 存储池名 |
seed_storage_pool |
Agent 生成 cloud-init seed 卷的 libvirt 存储池名 |
firmware_loader |
从本机 domcapabilities 选定的非 Secure-Boot EFI pflash loader 绝对路径 |
firmware_nvram_template |
与 loader 匹配的可写 VARS 模板绝对路径 |
nvram_directory |
受管每 VM NVRAM 文件目录的绝对路径 |
network_selectors |
PHP 只能引用的本机网络映射;每项 type 只能是 bridge 或 network,source 是预先存在的 bridge/libvirt network 名 |
上表的存储、固件和网络字段都是必填项。复制样例后,必须用目标宿主机实际的存储池、virsh domcapabilities 支持的 loader/VARS 组合和已准备的网络替换示例值。不得选用 *.secboot.fd;域 XML 必须保持 Q35 UEFI 且明确关闭 Secure Boot。network_selectors 最多配置 64 项;key 是面板数据库中宿主机网络接入的稳定选择器,新安装面板默认使用 public,实际 br0 只出现在 Agent 的 source 映射中,PHP 不能直传任意网桥名。能力探测要求至少一个 selector 可用,不会因为未启用的可选 selector 降级全部网络能力;Agent 只在 capabilities 中按字节序上报当前可用的 key,面板要求 default_network 精确匹配其中一项。修改 default_network 会立即撤销旧的 Agent 就绪结果,必须重新执行连接测试;每次创建或换网仍会单独确认本次选中的 bridge/libvirt network 处于活动状态。
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。nonce 通过独立到期索引清理,不会重写 operation 历史;到期时刻本身仍视为占用,只清理严格早于当前时刻的 nonce。独立 inflight 索引使启动只恢复 reserved/dispatching,不会扫描永久历史。终态结果详情保留 90 天后压缩,释放的 bbolt 页面会被后续写入复用,但 operation_id、请求指纹、资源、动作和终态会永久保留为防重放 tombstone。禁止以“清理历史”为由删除这些 tombstone。当前为全新 Go Agent 格式,不导入旧 Python 数据或早期 JSON 原型 journal。
配置必须存在、可读、是单个严格 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;健康和 capabilities 通过后,再配置资源池、网络和销售状态。如果二进制未带 libvirt build tag,Agent 会以 libvirt_adapter_not_built 明确失败,不会退化成外部命令或远程连接。
5. 面板 workers、更新 helper 与 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 离线而停止其他宿主机的任务处理。
在线更新由本机 root Go helper 提供固定 Unix socket API,不通过 Agent 执行。在面板机器构建并安装更新 helper 和 Agent Gateway:
install -d /home/virt-cloud/bin /home/virt-cloud/runtime/update
cd /home/virt-cloud/gateway
go mod download
go mod verify
go test ./...
go build -trimpath -o /home/virt-cloud/bin/virt-cloud-update ./cmd/virt-cloud-update
go build -trimpath -o /home/virt-cloud/bin/virt-cloud-agent-gateway ./cmd/virt-cloud-agent-gateway
install -o root -g root -m 0600 \
/home/virt-cloud/deploy/virt-cloud-update.json.example /home/virt-cloud/runtime/update.json
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-update.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-agent-gateway.service /etc/systemd/system/
启动前先编辑两个 runtime JSON,把所有 REPLACE_ME 占位符换成不同的安全随机密钥,并在 PHP config.php 中配置完全一致的 cloud_update_helper_secret 和 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-update.service virt-cloud-agent-gateway.service
virt-cloud-update 常驻并仅监听 /run/virt-cloud/update.sock,PHP 使用固定的 settings/check/apply/jobs API。配置字段为:
| 字段 | 约束 |
|---|---|
socket_path |
必须为 /run/virt-cloud/update.sock |
repository_dir |
必须是干净绝对路径,部署样例为 /home/virt-cloud |
remote_url |
必须为 https://g.luoli.live/root/virt.git |
branch |
必须为 go |
state_path |
必须精确为 <repository_dir>/runtime/update/state.json |
service_secret |
至少 32 字节,必须与 PHP cloud_update_helper_secret 一致 |
php_command |
PHP CLI 的干净绝对路径 |
php_fpm_unit |
需停止并首先恢复的 PHP-FPM systemd unit |
service_units |
1–32 个已加载且正在运行的应用 unit;不能包含 PHP-FPM 自身或 virt-cloud-update.service |
仓库访问令牌经 API 保存到 helper 状态,不写配置样例、URL、进程参数或日志。helper 只允许固定远端、固定 go 分支和干净工作树 fast-forward;cloudInit 结果不确定时保留维护锁,必须 SSH 人工核对。如果未部署某个可选应用 unit,启动 update helper 前必须把它从 service_units 样例中删除;不得为绕过预检而填写虚假 unit。
面板 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 都必须断开两端。
这两个 helper 的配置加载都不把 owner/group/mode 当成启动条件;只要实际 service 用户能读取并且 JSON/字段有效,不会因权限位不符合某个预设值而拒绝启动。建议使用最小读取范围,绝不要 chmod 777。
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、helper Unix socket、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 断线。
- 同一
operation_id重试不重复创建/删除;派发后丢失响应进入uncertain并可核对。 - 并发购买不超卖 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-update.service -u virt-cloud-agent-gateway.service \
-n 200 --no-pager
先区分 PHP 任务尚未派发、Gateway 未运行、Agent 出站 WSS 认证/网络失败、已派发但响应丢失、libvirt 明确失败和业务库提交失败。权限位与所有者不是应用层合规检查项;遇到启动错误应读取具体的“不可读、JSON 无效或字段无效”诊断,而不是盲目放宽权限。
任何破坏性任务在派发后超时,都保留原 operation_id、reservation、IP 和账单状态进行核对。不要换新标识重试、直接改库释放、自动退款或再次毁盘。