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/docs/DEPLOYMENT.md

462 lines
57 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.

# 全新安装与启动
本版本只支持全新安装:不导入旧数据库,不读取旧引擎密文、配置或宿主机凭据,也不提供兼容回退。示例使用 AlmaLinux、项目目录 `/home/virt-cloud`、PHP-FPM 用户 `apache`;请按实际发行版调整包名和服务名。
面板服务器运行 PHP、数据库客户端、workers 和 Go Agent Gateway。每台 KVM 宿主机单独运行 Go `virt-agent`,Agent 只连接该机的 `qemu:///system`,并主动连接面板 WSS;不经 SSH 管理另一台宿主机。PeerMigration V3 使用一个 Agent 端口在宿主机之间直接传输只读磁盘分块:Agent 自动生成 TLS 1.3 身份、发现本机可达地址并管理暂存目录,不开放 libvirt TCP。
## 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/libvirt` CGo binding;AlmaLinux 常用构建依赖为 `gcc pkgconf-pkg-config libvirt-devel`。
不要为 Agent 开启未认证的 libvirt TCP。Agent 应通过本机 UNIX socket 使用 `qemu:///system`。
## 2. 安装面板
```bash
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 配置:
```bash
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 都能读取:
```bash
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. 创建全新数据库
只对两个空数据库执行以下命令。不要把这一步当作旧库升级工具;检测到旧云表时应停止、另建空库并人工保留只读备份。
```bash
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` 只包含应有的超级管理员。
已经运行当前 `go` 分支全新 schema 的测试环境,在发布账户资料功能前需先备份业务库并增加 `user` 表字段:
```bash
mariadb -h DB_HOST -P DB_PORT -u DB_USER -p BUSINESS_DB < /home/virt-cloud/web/sql/user_profile.sql
```
该增量文件只为当前分支的测试环境补充姓、名、手机号和地址字段,不读取或迁移已退役系统的数据。注册流程不采集这些资料;新用户和已有用户均可登录后在“账户设置 → 账户信息”中补充。
已经运行当前 `go` 分支 schema 的环境,在启用后台法律页面编辑前还需导入全局法律内容表:
```bash
mariadb -h DB_HOST -P DB_PORT -u DB_USER -p BUSINESS_DB < /home/virt-cloud/web/sql/legal_documents.sql
```
服务条款和隐私政策按语言维护草稿与不可变发布版本,但不按域名拆分;所有配置域名读取同一份已发布内容,页面中的 `{{site_name}}` 会在展示时替换为当前站点名称。未导入增量表时公开页面使用内置安全文本,后台会明确提示先执行该 SQL,且不会把草稿误当作已发布内容。
已经运行当前 `go` 分支 schema 的测试环境,在发布 Telegram 工单直接回复前,必须先导入持久消息映射表:
```bash
mariadb -h DB_HOST -P DB_PORT -u DB_USER -p BUSINESS_DB < /home/virt-cloud/web/sql/ticket_telegram_replies.sql
```
顺序必须是“先备份并建表,再更新 PHP 代码,最后重载 PHP-FPM”。该表只保存工单通知与 Telegram 消息 ID 的映射,不回填历史通知;只有更新后新发送且成功记录的通知可以在 Telegram 中直接回复。发送超时会保留 `unknown` 栅栏并禁止自动重发;管理员应改用面板处理该条工单。
若实例是在缺少 PHP 模板展示快照的早期 Go Agent 版本中创建,更新面板代码后先执行只读检查,再显式应用元数据修复:
```bash
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 密钥。丢失该密钥不能通过导入旧引擎密钥或降级格式恢复。
### 对象存储应用
后台 `/admin/object-storage` 同时最多启用两套相互独立的 S3 兼容对象存储后端,适用于 AWS S3、MinIO 及实现 AWS Signature Version 4 的兼容服务。为替换故障提供商,可以额外登记处于 draft、draining、read_only 或 disabled 的后端;历史行会继续保存精确对象身份,但不会扩大“最多两个参与新写入”的边界。后端、制品、副本、操作和发布账本保存在业务库的 `cloud_storage_*` 表;不能再用旧 `configurations` 单应用记录替代当前结构。Endpoint 必须是带有效证书的 HTTPS origin;MinIO 通常选择路径寻址,AWS S3 通常选择虚拟主机寻址。每套后端必须分别验证当前配置版本后才能参与写入;模板和救援镜像要求两个不同故障域的副本,普通云备份先完成主副本后异步复制。第二后端恢复或替代后端启用后,副本 Worker 会从现有精确副本生成持久复制意图;draining/disabled 后端不计入目标覆盖,因此可以在维护下线前先补齐到替代后端。页面默认展示真实副本覆盖、复制积压、就绪条件和脱敏连接详情;只有超级管理员可修改连接。对象清理异常位于独立工作区,未知删除只显示系统核对进度,只有进入人工核对状态才提供受控恢复入口。
Access Key ID 与 Secret Access Key 只在超级管理员提交时进入 PHP,使用 `cloud_data_key` 的独立用途密钥密封后保存,读取页面不会回显。修改任一后端配置或停用后端都会清除该后端的就绪标记;必须重新执行连接验证。连接验证只发送签名的 `HeadBucket` 请求,需要目标 Bucket 的 `s3:ListBucket` 权限,不上传、覆盖或删除对象。副本 Worker 为崩溃恢复执行精确对象键的 multipart 列表查询,因此每套后端还必须授予 Bucket 级 `s3:ListBucketMultipartUploads`。运行账户需要在各自配置前缀下授予 multipart 创建、分片上传、完成与中止,以及 `GetObject`、`HeadObject` 和 `DeleteObject`;开启 Bucket 版本控制时还必须授予 `s3:GetObjectVersion` 与 `s3:DeleteObjectVersion`,让读取与删除准确绑定 `versionId`。管理员虚拟机管理的完整系统盘备份和用户自动备份使用同一制品账本;云镜像与救援镜像在达到冻结的副本覆盖数前不得下发到宿主机。维护迁移使用宿主机间 PeerMigration V3 直传,不创建对象存储迁移对象。当前不包含增量链和管理员手工备份的自动保留策略,具体安全边界见 `docs/PORTABLE_VM_BACKUPS.md`。
生产 Bucket 必须把生命周期规则作为控制面之外的最后兜底:建议在 1 天后终止未完成 multipart upload;开启版本控制时,按业务保留要求清理 `vm-backups/` 与 `cloud-templates/` 的非当前版本和过期删除标记。生命周期不得提前删除仍由面板备份、云镜像目录或未完成导入意图引用的当前版本。管理员本地上传云镜像时,浏览器直接向对象存储执行分片 `PUT`,Bucket CORS 必须只允许面板 HTTPS origin,允许 `PUT`,并在 `ExposeHeaders` 中公开 `ETag`;不要使用 `*` origin 搭配管理站点。面板保存每个已确认分片,刷新后重新选择同一文件会跳过这些分片;取消或 24 小时过期后,普通 worker 会中止仍可确认的 multipart。若创建 multipart 的响应在 upload ID 返回前丢失,面板只能放弃该上传记录,因此上述生命周期规则是清除提供商残留分片的必需兜底。官方地址导入先持久化同一导入意图和唯一对象键,再由 PHP 有界下载、校验并发布;正常结束立即删除本地临时文件,进程硬中止遗留的同前缀普通文件由 worker 在 24 小时后逐个回收。PUT 结果不明时只允许用同一对象键执行 HEAD 核对,不能新建导入或盲目重写。
面板会保存 HEAD 返回的 ETag 与 `version_id`,删除时精确定位该版本;删除结果不明时先进行间隔稳定 HEAD,只有对象身份完全一致才创建新的删除代次,每个自动周期最多三次。达到上限的对象进入后台人工核对,不再自动删除;对象存储页面的“重新核对”只恢复稳定 HEAD 证据流程,不会重放原 DELETE。云镜像的人工重试同样只恢复对象存储核对,不会再次删除宿主机副本。
生产环境应为面板创建独立服务账户,把权限限制到配置的 Bucket 和业务前缀。数据库备份必须与原始 `cloud_data_key` 一起保管,重新生成主密钥无法恢复各后端密封凭据,也无法继续读取、复制或精确清理账本引用的对象。
## 4. 构建并安装宿主机 Agent
在与目标宿主机 ABI 相同的 Linux 环境构建,不要把 macOS CGo 产物复制到 Linux:
```bash
cd /home/virt-cloud/agent
go mod download
go mod verify
go test ./...
go test -tags libvirt ./...
install -d -o root -g root -m 0700 /home/agent /var/lib/virt-agent
go build -tags libvirt -trimpath -o /home/agent/virt-agent ./cmd/virt-agent
chown root:root /home/agent/virt-agent
chmod 0755 /home/agent/virt-agent
install -o root -g root -m 0600 \
/home/virt-cloud/deploy/virt-cloud-agent.json.example /home/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` | 网页可下发存储目录的宿主机绝对路径允许列表;每个目录必须是允许根目录的真实子目录,不能是根目录本身、符号链接或其他角色目录的父/子目录 |
| `peer_migration_port` | PeerMigration V3 数据面端口,默认 `9443`,允许 `1`~`65535`;Agent 自动监听全部地址、发现本机 IP、生成并锁定 TLS 身份,并把暂存目录放在第一个 `storage_path_roots` 下 |
| `firmware_loader` | 从本机 `domcapabilities` 选定的非 Secure-Boot EFI pflash loader 绝对路径 |
| `firmware_nvram_template` | 与 loader 匹配的可写 VARS 模板绝对路径 |
| `nvram_directory` | 受管每 VM NVRAM 文件目录的绝对路径 |
`storage_path_roots` 和固件字段都是必填项。`peer_migration_port` 可以省略并使用默认值 `9443`;新增宿主机只需保证同资源池宿主机之间可访问该 TCP 端口。Agent 自动把服务监听在全部本机地址,发布本机非 loopback 单播 IP,目标先尝试同网段地址再回退公网地址;因此新增物理内网后无需修改面板或 Agent endpoint。TLS 私钥和证书由 Agent 在 `journal_path + ".peer-v3"` 下以 `0600` 自动生成并持久化,目标严格锁定源证书 SHA-256;每次迁移仍使用独立一次性票据。暂存目录自动使用第一个 `storage_path_roots` 下的 `.peer-migration-staging`。旧的六个 PeerMigration V2 字段已删除,继续保留会因严格 JSON 解析而拒绝启动。Agent 配置文件不再填写 libvirt pool 名或网络映射;必须删除旧的 `managed_storage_pool`、`template_storage_pool`、`seed_storage_pool` 和整个 `network_selectors` 字段,否则严格配置解析会按未知字段拒绝启动。复制样例后,必须用目标宿主机实际允许的存储根目录和 `virsh domcapabilities` 支持的 loader/VARS 组合替换示例值。不得把 `/` 加入允许列表。仓库样例 unit 不启用 `ProtectHome` 或 `ProtectSystem`;如果运维自行增加 systemd 文件系统隔离,必须同时保证 `/home/agent`、`journal_path`、第一个 `storage_path_roots` 和 `nvram_directory` 可写并完成真实迁移验收。存储配置使用独立的短边界:面板 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 可用前,宿主机不会进入调度。
公网网络接入在宿主机的“网络接入”中按资源池线路独立配置,可使用 `bridge:br0`、其他 Linux 网桥或 `network:default` 这样的 libvirt network。名称以字母或数字开头,后续只能包含字母、数字、点、下划线和短横线,bridge 名称为 1~15 字符,libvirt network 名称为 1~64 字符。宿主机上的公网网桥或 libvirt network 必须由运维预先准备。Agent 只发现、验证和使用现有公网网络,不创建公网网桥、不启动 libvirt network,也不修改公网地址、上游网关或挂载。`cloud_hosts.default_network` 仅保留为兼容展示值,不参与 Agent 就绪、调度、恢复、迁移或换 IP 决策;真正的运行时权威是资源池线路、当前 Agent 代次已验证的网络接入,以及绑定该接入的公网地址池。VPC 使用下述独立的 Agent 受管 bridge 和 L3 路由,不改变这一公网边界。
当前完整 schema 版本为 `go-agent-wss-v38-backup-publication-preparation`。每个资源预留的当前公网权威只来自 `cloud_resource_reservation_ips.active_claim = 1` 的一组 IPv4+IPv6 精确声明;两族允许具有各自的 generation 和 operation ID,但必须绑定同一资源预留和网络接入,并各自与具体 IP、地址池、宿主机、实例状态双向一致。`cloud_resource_reservations` 中旧的单地址列只保留审计形态,不参与当前地址读取、释放或管理员投影。释放时历史声明保留并把 `active_claim` 置空,具体 IP 同时清空 claim、operation、reservation 和 instance 归属。普通换 IP、独立恢复和维护迁移分别只允许 transition ledger、restore attempt 与 migration source debt 所有的完整双栈流程;旧 `CloudPlacementService` 单地址恢复、旧换 IP writer,以及缺少或损坏冻结身份的任务仍会在派发 CAS 前拒绝,不能绕过新账本。
Agent 的 capabilities 响应仍使用 `network_selectors` 字段,但它是自动发现的当前可用 `bridge:<名称>` / `network:<名称>` 列表,排序去重且最多 64 项,不再来自配置文件。Linux 网桥必须有 sysfs bridge 目录且接口为 UP;libvirt network 必须处于 active 状态。完整 Agent 测试保存当前代次的候选列表,但不要求某个宿主机全局默认值必须存在。管理员只能从该代次已测试列表创建网络接入,并必须对每个接入执行精确验证;创建、恢复、迁移、重装和换 IP 会在锁内再次核对本次资源池线路、接入、公网池与 Agent 代次。修改兼容 `default_network` 不会撤销 Agent 就绪结果,修改或失效真实网络接入则由接入自身的验证状态阻止运行时使用。
公网 IPv6 防伪还依赖宿主机启动门禁。Agent 每次成功重算公网 TAP 身份时,会先把完整、排序后的 v1 投影原子写入 `journal_path + ".public-guard-v1.json"`,完成文件 `fsync`、`rename` 和目录 `fsync` 后才允许替换 `bridge virt_cloud_public_guard` nftables 表。该文件必须是 root 所有的普通 `0600` 文件,父目录必须由 root 所有且不可被 group/other 写入;版本、严格 JSON、SHA-256、规范化 MAC、全局 IPv6 和 MAC 派生 link-local IPv6 任一不一致都会拒绝读取。它与 `journal_path + ".public-guard.lock"`、实时 Agent 变更和启动预检共用同一把跨进程 `flock`,不得手工编辑、复制半成品或用空文件代替。明确的零实例投影也是一份带摘要的合法 JSON;文件缺失或损坏绝不会被解释成“当前没有实例”。该状态文件必须与 Journal 一起纳入宿主机状态备份。
仓库分别提供 `deploy/libvirtd.service.d/10-virt-cloud-public-guard.conf` 和 `deploy/virtqemud.service.d/10-virt-cloud-public-guard.conf`。只安装当前宿主机实际使用的 daemon drop-in;其 `ExecStartPre=+...` 显式要求 systemd 即使原发行版 unit 配置了降权,也以完整宿主机权限运行预检。预检在打开 Journal、libvirt 或 HTTP 之前执行 `/home/agent/virt-agent -config /home/agent/config.json -public-guard-preflight`,从上述严格缓存恢复并精确回读 nftables。预检失败返回非零,libvirt daemon 因而不会启动,持久 VM 的 autostart 也不会越过防伪表。drop-in 同时声明在已进入同一启动事务的 `firewalld.service`/`nftables.service` 完成后执行,避免开机后防火墙服务再覆盖刚恢复的表;运行期间的 reload 或误删由 Agent watcher 在同一 flock 下核对和修复。
首次部署不能先安装 drop-in 再期待缺失状态自动降级。应先在现有 libvirt 正常运行时启动新版 Agent,让它从受管 domain 生成并验证第一份缓存;确认文件存在、权限与 owner 正确且 Agent capability 正常后,再安装对应 drop-in 并重启实际 daemon 做验收:
```bash
# 以下二选一,只为本机实际使用的 daemon 安装对应目录和文件。
install -d -o root -g root -m 0755 /etc/systemd/system/libvirtd.service.d
install -o root -g root -m 0644 \
/home/virt-cloud/deploy/libvirtd.service.d/10-virt-cloud-public-guard.conf \
/etc/systemd/system/libvirtd.service.d/10-virt-cloud-public-guard.conf
# 模块化 libvirt 主机改用 virtqemud.service.d 中的同名文件。
systemctl daemon-reload
systemctl restart libvirtd.service
systemctl status libvirtd.service virt-cloud-agent.service --no-pager
journalctl -u libvirtd.service -u virt-cloud-agent.service -n 100 --no-pager
```
验收必须覆盖合法缓存、缺失缓存、摘要损坏、软链、非 `0600`、非 root owner、额外/缺失/篡改 nft 规则和并发 Agent transition。除合法缓存外,所有缓存异常都必须使 daemon 启动失败;并发预检必须等待同一 transition lease,不能观察或发布中间投影。不要通过删除 `ExecStartPre`、创建空缓存或关闭 VM autostart 后跳过验收来恢复服务。
`capabilities.vpc_l3` version 3 报告 VPC L3 前置条件、VM 网卡能力和候选传输地址,不替代面板配置。Agent 从处于 UP 状态的接口中筛选 RFC1918 IPv4 地址,排序去重并限制为最多 64 项;每项包含 CIDR、接口、MTU 和是否为 Linux bridge。`ipv4_forwarding` 只反映当前 `/proc/sys/net/ipv4/ip_forward`,Agent 不会为能力探测修改 sysctl。管理员必须在计算节点页面明确选择一个候选地址;只有 IPv4 forwarding 已启用、候选地址存在,并且宿主机提供 root 所有、不可由 group/other 写入的 `ip` 与 `nft` 可执行文件时,`apply_supported` 和 `vm_port_supported` 才为 true。firewalld 正在运行时,能力探测还会在 5 秒上限内只读核验 daemon 状态、runtime/permanent 保留对象及其接口归属是否与 Agent 持久化的完整 VPC projection 一致;探测不会安装规则或 reload,任何查询错误、外部占用或孤立接口都会让 `apply_supported` 为 false,并由 `vpc_l3_apply` 返回精确原因。首次真实 VPC mutation 才会创建并回读确认专用 zone/policy。面板会同时检查 `vpc_l3_apply` 与 `vpc_vm_port`,低于 version 3 的 Agent 不会被误认为当前 VPC 功能已就绪。version 3 还把可选 VPC 逻辑端口纳入 PeerMigration 接收合同,使维护迁移能在目标路由先就绪后保留同一私网 IP/MAC。
VPC V1 使用同地区直接 L3 underlay,不创建隧道、不做 NAT,也不延伸二层广播。所选宿主机 underlay 地址必须处于同一个可直达前缀;每个 VPC 在参与宿主机上使用由 VPC key 派生的专属 Linux bridge,bridge 地址为该 VPC gateway,并启用 proxy ARP。本机 VM 地址保留在 bridge,远端 VM 地址使用 protocol 186 的精确 `/32` 路由指向远端宿主机 underlay 地址。`inet virt_cloud_vpc` nftables 表只允许已声明本机/远端端口之间经所选 underlay 转发,并拒绝 VPC bridge 访问宿主机或其他出口;公网网卡和原有防火墙不归该表管理。宿主机启用 firewalld 时,Agent 会在精确 nftables 表安装成功后再幂等维护 `virt-vpc-guest`、`virt-vpc-transit` 两个专用 zone,以及 `virt-vpc-out`、`virt-vpc-in` 两条固定转发 policy;policy 使用 `ACCEPT` target 允许这两个精确 zone 之间的全部 IP 协议,不创建用户 ACL 或宽泛 rich rule。永久定义先在无新增接口归属的状态下落盘;仅当运行时对象首次缺失或不完整时,Agent 才先解除全部受管接口、执行一次标准 reload、重新安装精确 nftables 表,最后恢复 runtime/permanent 接口归属。后续增删 VPC 只做增量同步,也不会把接口加入 `trusted`。guest zone 只为同机 VPC 成员启用 intra-zone forwarding,transit zone 不启用;两条 policy 只允许这两类接口之间转发,宿主机 INPUT 仍由 firewalld 原有规则保护。已有同名对象、目标接口已属于其他 zone,或专用对象中存在非 Agent 规则时,Agent 会拒绝覆盖并保持 fail-closed。路由状态文件 `journal_path + ".vpc-l3-v1.json"` 与 Journal、`.traffic.json` 一样必须纳入宿主机状态备份,不能手工编辑。父 Agent 每次启动或 libvirt 重连时会从这一已提交快照幂等恢复 bridge、路由、nftables 表与 firewalld 接口归属;隔离 mutation worker 不会执行额外的启动恢复。VM 挂载私网网卡前必须先应用包含该精确 IP/MAC 的 host projection;卸载时顺序相反,先冷重启移除网卡,再从 projection 删除端口。来宾使用静态 `/32` 和到 VPC CIDR 的 on-link route,私网流量不进入公网流量计费。启用 VPC 前必须在至少两台同地区宿主机上实测 underlay 双向直达、MTU、`net.ipv4.ip_forward=1`、nftables 事务、firewalld 开启状态下的同机与跨宿主机互通、宿主机重启恢复、运行/关机实例挂载与卸载、重装保留私网以及跨宿主机 VM 私网连通。
VPC 生命周期保持一条明确边界:连接和断开私网都需要实例正常关机后冷启动;重装保留当前逻辑端口;恢复原实例的系统盘备份保留恢复时实例的当前网络意图;独立备份恢复和云快照新建实例不继承源实例 VPC。维护迁移会先把同一端口路由到目标宿主机,再允许目标 Agent 接收并挂载该端口;成功切换后才从源宿主机撤销路由。失败回滚会先恢复源端路由,任何派发后未知结果都会保留端口和实例执行栅栏,不会更换 IP、自动重放或释放资源。实例到期、流量额度耗尽或管理员限制网络时会同时断开公网和私网链路;续费或解除限制后同时恢复。公网流量采样只读取受管公网网卡,VPC 流量不计入公网流量额度。用户防火墙继续只管理公网接口,VPC 东西向隔离由 Agent 的 VPC 路由投影和 nftables 规则负责。当前版本不提供 VPC ACL:同一用户加入同一 VPC 的实例默认允许全部 IP 协议双向互通;未加入该 VPC 的接口、伪造源地址、跨 VPC 和宿主机 INPUT 不会因这项默认互通而放行。
启用顺序不能颠倒:先在同地区每台计算节点确认既有私网 underlay 双向可达、MTU 一致并启用 IPv4 forwarding;部署支持 VPC capability version 3 的 Agent;在后台计算节点页选择并验证该节点的私网传输地址;创建地区 RFC1918 地址池;保持用户功能开关关闭,先用测试 VPC 和至少两台测试实例完成连接、冷启动、跨宿主机通信、断网/恢复、重装、备份恢复、维护迁移、回滚和宿主机重启恢复验收;最后才打开用户功能开关。停用地址池只阻止新建 VPC,关闭用户功能开关只阻止新的用户操作,都不会删除现有网络或端口。当前 schema 是 clean-break VPC L3 v3,不提供旧 VPC 数据或旧 Agent 状态升级路径。
本版本只面向全新部署,不读取旧 `public` alias、旧网络映射或旧就绪记录。部署时必须直接填写真实的 `bridge:<name>` 或 `network:<name>`;不要复制旧 Agent 配置,也不要把旧数据库导入当前 schema。
Agent 的 systemd 样例与当前宿主机部署保持一致:以 root 运行 `/home/agent/virt-agent -config /home/agent/config.json`,不设置 `ProtectSystem`、`ProtectHome`、`ReadWritePaths` 或 `StateDirectory`。这是因为 Agent 除了写入 `journal_path`,还需要在第一个 `storage_path_roots` 中维护 PeerMigration 暂存文件,并可能清理 `nvram_directory` 中由面板管理的 UUID 专属 VARS 文件。配置文件仍应保持 root 所有和 `0600` 权限,运行目录不应存放其他可执行或可写入的非 Agent 内容。若运维自行增加 systemd 沙箱,必须精确放行上述实际目录,并分别完成 Agent 启动、迁移接收、失败清理和 NVRAM 删除验收。
`journal_path` 是当前版本专用的 bbolt 数据库,不是可编辑 JSON;同目录的 `.traffic.json` 是流量状态,两者都要纳入一致性备份。Agent Journal 会拒绝旧 schema,不执行升级或回填;全新安装必须使用空状态目录。流量状态是唯一例外:新版 Agent 会在文件锁内把 v1 `.traffic.json` 一次性迁移为 v2,保留每台实例的初始化位、最后原始计数、单调累计流量和最后观测时间,只丢弃已由面板日志库接管的宿主机本地每日桶;其他未知版本仍拒绝启动。Journal 在变更跨越派发边界前写入 operation tombstone,随后只允许这一次 worker 执行。Agent 重启若发现已启动但没有完整回执的 operation,会直接写入终态失败和执行栅栏,不会重新调用 libvirt。operation ID、指纹、资源、动作和终态永久保留用于防重放;完成回执在收到精确 ACK 前按固定低频间隔持续重发,不会重新执行 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 不启动已退役的通用管理 API 监听,但仍会自动启动仅供宿主机间迁移使用的 `peer_migration_port` TLS 数据面。
安装并启动 service:
```bash
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
```
这是首次缓存引导步骤:确认 `journal_path + ".public-guard-v1.json"` 已由新版 Agent 生成并通过权限、摘要和 nft 回读核验后,必须继续按前述说明安装本机实际 libvirt daemon 的 public-guard drop-in,再执行 daemon 重启验收。后续更新二进制时保留该缓存和 drop-in,不能重新初始化为空。
在面板 `/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:
```bash
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/
cp /home/virt-cloud/deploy/virt-cloud-vpc-worker@.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-recovery-worker.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-notification-worker.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-storage-replica-worker.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-storage-publication-worker.service /etc/systemd/system/
cp /home/virt-cloud/deploy/virt-cloud-storage-health-worker.service /etc/systemd/system/
cd /home/virt-cloud/agent
go build -trimpath -o /home/virt-cloud/bin/virt-cloud-storage-replicator \
./cmd/virt-cloud-storage-replicator
chown root:root /home/virt-cloud/bin/virt-cloud-storage-replicator
chmod 0755 /home/virt-cloud/bin/virt-cloud-storage-replicator
systemctl daemon-reload
systemctl enable --now virt-cloud-worker.service \
virt-cloud-recovery-worker.service virt-cloud-notification-worker.service \
virt-cloud-storage-replica-worker.service \
virt-cloud-storage-publication-worker.service \
virt-cloud-storage-health-worker.service \
virt-cloud-lifecycle.service \
virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service \
virt-cloud-vpc-worker@{1..8}.service
```
普通 worker 负责购买、创建、重装、实例升级、实例可用时间补偿、邮件和最终删除;补偿每轮最多推进一个 PHP 本地账本明细,不联系 Agent。至少两个策略 worker 处理到期断网、网络恢复与删除前策略;lifecycle 生成续费账单并推进账期、流量、宽限和删除状态。VPC 批量加入/移出没有实例数量上限:面板会在一个数据库事务中释放同一批次的全部 VM 子任务,实际同一时刻运行多少台由 `virt-cloud-vpc-worker@N.service` 的实例数和各宿主机 Agent 的安全 admission 决定,超出 worker 并发度的任务仍已持久接收并等待空闲进程,不依赖浏览器。上例启用 8 个专用 worker;可按面板 CPU、数据库连接和宿主机冷启动能力增减实例数,而不是在页面设置固定的“最多 4 台”。未安装专用 unit 时普通 worker 仍会安全消费这些任务,但吞吐量较低。
`virt-cloud-notification-worker.service` 消费管理员维护通知和实例补偿结果通知;两个通道每轮各最多领取一封,任一通道异常不阻塞另一通道,也不占用虚拟机任务 worker。投递使用 300 秒租约;邮件传输一旦开始后返回失败、异常或租约过期都记为“效果未知”,不会自动重发。该服务是两类通知的必需组件;只更新 PHP 而不安装并启动该 unit 时,通知会安全保留在待发送状态。
`virt-cloud-storage-replica-worker.service` 独立流式复制已冻结的对象存储制品,不占用虚拟机任务 worker。PHP 只通过标准输入把短期、限方法的 capability 交给 helper;命令行、环境、数据库和日志都不保存 capability 或对象存储凭据。复制租约覆盖 helper 的完整六小时硬截止;进程中断、回执损坏或完成结果不确定时只对固定目标对象执行 HEAD 与精确对象键的 Multipart 列表查询,不自动重放复制或 Abort。只有连续两次确认目标对象和对应 Multipart 会话都不存在后,才会重排同一复制意图;唯一且时间窗口匹配的未持久化会话可被原操作接管。同一对象键出现多个会话、记录会话与远端不匹配或会话无法归属原操作时,连续两次稳定证据会使原操作进入“副本人工核对”;管理员在提供商侧清理多余会话后只能重开该原操作的只读核对,本次点击不会由面板 Abort 或直接新建上传;只有两次确认无远端效果后才会沿用原操作安全重试。该 worker 独立写入 `storage_replica` 运行心跳;后台运行状态出现警告时应同时核对副本修复、复制操作和该 unit 的 journal,不能仅凭 systemd 的 `active` 判断复制正常。
`virt-cloud-storage-publication-worker.service` 是单实例、本地数据库型业务发布 worker:每轮最多处理一个已经达到双副本保护的 `ready_to_finalize` 模板或救援 ISO 发布,不执行 PUT、COPY、HEAD、DELETE、Abort 或 Agent 请求。模板必须由它创建幂等的宿主机分发任务,救援 ISO 必须由它进入验证阶段;只更新 PHP 而未安装或启动该 unit 时,这两类制品会安全停在 `ready_to_finalize`,不会绕过保护直接发布。普通云备份仍由原同步流程最终化,不进入该 worker。它独立写入 `storage_publication` 运行心跳,并在后台运行状态中单独显示。由拆分前版本升级时,复制新 unit 后应同时重启 `virt-cloud-storage-publication-worker.service` 与 `virt-cloud-storage-replica-worker.service`,避免旧副本 worker 进程继续加载包含业务发布消费的旧代码。
`virt-cloud-storage-health-worker.service` 与副本复制 worker 彻底隔离:它每次只领取一个到期后端,在数据库事务外执行最长 15 秒的 `HeadBucket`,并且只能按领取时冻结的配置版本结算。成功只恢复健康证据,不会把人工设置的 `read_only`、`draining` 或 `disabled` 改回 `active`;失败使正在 `active` 的后端转为 `read_only`、按 60 秒到 1 小时退避,新写入随即停止选择它。这个 worker 不执行 PUT、COPY、DELETE 或 Abort,也不把凭据写入心跳、日志或命令行。
实例补偿的批次、明细和收件人账本已包含在当前 v38 完整 schema 中。`php xcat cloudInit` 只能为全新空数据库创建和验证当前全部结构,不能冒充既有数据库的增量升级。既有安装发布前必须备份数据库,使用经过审核的一次性迁移落地完整 v38 结构并核对 schema 指纹;升级成功后删除迁移脚本。然后按本节重启普通、通知及对象存储 workers。补偿本身不调用 Agent/Gateway,因此仅补偿功能不要求更新或重新编译宿主机 Agent 和面板 Gateway。完整语义见 [`SERVICE_COMPENSATION.md`](SERVICE_COMPENSATION.md)。
共享流量池必须严格按 `disabled -> shadow -> enforced` 上线,并在强制执行前通过全部账本、采样和网络策略门禁。现有数据库不能使用 `php xcat cloudInit` 冒充增量升级,旧服务周期也不能通过 SQL 回填到流量池;完整步骤、验收项和故障处置见 [`TRAFFIC_POOL_ROLLOUT.md`](TRAFFIC_POOL_ROLLOUT.md)。
`virt-cloud-recovery-worker.service` 是必需的独立 operation 恢复进程,覆盖策略表中的实例电源、重装/救援、公网 IP、实例设置、实例升级、快照、防火墙、删除、生命周期网络、模板与 ISO Agent 叶子任务。它只做 operation-bound inspection/栅栏审计、持久晚到回执的 PHP 收敛或聚合父任务的本地汇总,不投递邮件,也绝不重放原 mutation。离线、身份冲突或账本异常按固定低频间隔持续核对,没有次数或总时长上限。它与普通队列隔离,避免某个离线 Agent 的核对占住正常 worker。
恢复进程也覆盖已派发开通任务的失败收尾:完整缺失证据回执可直接完成本地退款和资源释放;回执不足时,只读检查原 operation,确认实例及托管资源均不存在后才收尾。升级此能力需同时更新面板代码与宿主机 Agent,并重启已有 worker/recovery worker 使其加载新代码;无需数据库迁移或新增 service。旧 Agent 拒绝开通自动检查时会保留订单占用并低频重试,不会绕过授权退款。已有失败且效果未知的开通订单会被后台领取,不必重发开通请求。
在面板机器构建并安装 Agent Gateway:
```bash
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.v3`,不提供 v1/v2 兼容或降级。每次发布必须先准备同一提交的 PHP 面板源码、Agent 和 Gateway 二进制,再在同一发布窗口更新三端并重启两个 Go 服务。混用新旧 Agent/Gateway 必须在 WSS 握手阶段失败;新 PHP 也会拒绝缺少 v3 操作身份的旧完成回执,不允许出现“健康检查成功但丢弃完成回执”。
启动前先编辑 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 字节,保留它会使服务拒绝启动。然后才启动:
```bash
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。首次内省必须原子消费面板票据:
```json
{"ticket":"<browser-ticket>","consume":true}
```
PHP 只返回下列字段;`agent_id` 对应已连接的数字 Agent 身份,过期时间为 UTC RFC3339:
```json
{
"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 执行一次清理。本节只用于卸载遗留文件;当前版本不构建、安装或调用该组件。
```bash
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 路径应按发行版调整:
```nginx
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`。
```nginx
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 镜像源及对象存储。维护迁移还要求同一资源池的宿主机之间双向放行 `peer_migration_port`(默认 `9443/TCP`),不应向无关公网来源开放该端口。
控制台上线前必须验收:一次性票据只能消费一次、过期拒绝、登出/撤销后断开、跨用户/跨 VM 拒绝、Origin 校验、上游 Agent 断线及时关闭、浏览器不能注入 endpoint。Agent 未声明 console capability 时,PHP 必须显示不可用,不能回退旧实现。
## 7. 管理页面配置顺序
1. 在 `/admin/agents` 为每台宿主机保存独立密钥,在 Agent 配置中写入面板 HTTPS 地址、对应数字 ID 和同一密钥;出站连接测试通过但先保持调度 disabled。
2. 创建宿主机业务记录、地区、资源池成员关系、容量和安全余量。面板策略、reservation 与具体 IP 账本是调度事实源。
3. 配置预先存在的 bridge,并在同一已验证网络接入下分别配置至少一个 active IPv4 地址池和一个 active IPv6 地址池;显式保留宿主机管理地址、网关和其他不可售地址。Agent 不通过扫描推测可售地址。
4. 导入云镜像和救援 ISO。官方地址只接受可公开解析的 HTTPS 直链,PHP 会校验初始地址及全部跳转;来源的发行方可信度由管理员确认。浏览器本地云镜像必须是独立、未加密、无 backing/data file 的 QCOW2,并通过受控 multipart 直接写入对象存储,不经过 PHP 请求正文;救援镜像只支持官方 HTTPS 地址。两类内容达到两个不同故障域的不可变副本覆盖后,Agent 只接收其中一个精确对象版本的短期只读地址、大小和摘要,并拒绝短读、多余字节、长度、摘要或格式不一致。
5. 为每个云镜像按需设置首次安装启动脚本。脚本最大 32 KiB UTF-8、拒绝 NUL;保存后修订递增,新创建任务快照当前版本。不要在脚本中写长期密钥。
6. 在 `/admin/config` 的“云实例计费”中用“数值+分钟/小时/天”设置新建实例账单支付期限;面板保存时统一换算为整数分钟。该值只作用于保存后新生成的开通账单,既有账单保持原截止时间。
7. 如需使用可移植备份,在 `/admin/object-storage` 分别登记并验证两套位于不同故障域的 S3 兼容后端。普通备份在一个主副本就绪后可用并异步补齐第二副本;云镜像和救援 ISO 必须等两个故障域均有就绪副本后才能发布。验证本身只检查 Bucket 可达性和 `s3:ListBucket` 权限,两个运行账户都必须具备各自业务前缀的 multipart 上传、读取、HEAD 和删除权限。
8. 创建销售套餐和库存,再启用宿主机/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 重放和错误遮罩。
- 创建、启动、软/硬关机、软/硬重启、删除、重装、救援、快照、网络、防火墙、指标和控制台。
- 新建 VM 的 Domain XML 必须在专属 nwfilter 引用中写入唯一的 `IP`、`IPV6` 与 `IPV6_LINK_LOCAL` 参数,分别绑定已分配公网 IPv4、全局 IPv6 和由 MAC 派生的 link-local IPv6;旧地址及其他伪造源地址均不能发出流量。还必须验证 firewalld/nftables reload 或受管表被误删后,Agent 会从持久投影自动恢复同一绑定。
- 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。不能回收时,新冲突请求必须立即被执行栅栏拒绝。
- 重复、乱序和晚到完成回执不能改变终态或触发 mutation;允许类型的精确同源回执最多幂等收敛 PHP 副作用账本与 effect fence。回执在精确 ACK 前按固定低频间隔持续投递,旧 attempts/expires 不得使其永久退出 outbox。
- 并发购买不超卖 CPU/内存/磁盘/IP;同一 VM 变更串行。
- 分别把新建实例账单支付期限设为“1 小时”和“1 天”,确认新账单截止时间为 1 小时和 1 天且旧账单不变;续费账单无论何时生成,其支付截止都必须等于对应实例到期时间加三天。
- RX+TX 额度用尽只断网;下一账期恢复;最终到期只断网;三天宽限结束后删除定义与面板受管磁盘。
- MariaDB、Redis、SMTP、支付回调、大文件上传和 PHP-FPM 重启。
验证命令和记录格式见 [VALIDATION.md](VALIDATION.md)。禁止在生产宿主机做破坏性验收;未授权主机只允许读 capabilities、版本、域/网络/池清单等只读信息。
## 9. 排错
```bash
journalctl -u virt-cloud-agent.service -n 200 --no-pager
journalctl -u virt-cloud-worker.service -u virt-cloud-recovery-worker.service \
-u virt-cloud-storage-replica-worker.service \
-u virt-cloud-storage-publication-worker.service \
-u virt-cloud-storage-health-worker.service \
-u virt-cloud-lifecycle.service \
-u 'virt-cloud-policy-worker@*' -u 'virt-cloud-vpc-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、账单和安全栅栏。独立 recovery worker 会持续执行只读核对并仅凭 operation-bound 证据收敛;不要重放旧任务、直接改库释放、自动退款或再次毁盘。异常时先修复页面所示的网络、身份、密文或账本根因,后续轮次会继续核对,只有审计的 effect resolution 提交后才解除栅栏。