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/VALIDATION.md

380 lines
29 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.

# PHP/Go Agent 验证门槛
本文件定义 `go` 分支的交付门槛。历史旧引擎测试结果不代表本实现通过;每次发布必须记录实际提交、环境、命令、通过/失败/跳过数量和未完成的真实环境验收。
## 1. 静态与单元测试
Go Agent 与本机 helper:
```bash
cd /home/virt-cloud/agent
test -z "$(gofmt -l .)"
go mod verify
go vet ./...
go test ./...
go vet -tags libvirt ./...
go test -tags libvirt ./...
go test -race -tags libvirt ./...
cd /home/virt-cloud/gateway
test -z "$(gofmt -l .)"
go mod verify
go vet ./...
go test ./...
go test -race ./...
```
Go 测试至少覆盖:配置内容校验但不检查 owner/mode、HTTPS `panel_url`、数字 Agent ID、旧 listener/TLS 字段被拒绝、WSS 子协议与认证、严格控制帧、HMAC 正文摘要、完整时间窗(含未来偏差与到期边界)、nonce 防重放、不同请求复用 `operation_id`、按 VM 串行、派发前/后故障注入、仅按 inflight 索引重启恢复、超过 16 MiB 的长期 journal 重启、nonce 到期索引清理、operation tombstone 保留、五类 expected-state/transition marker 只读核对、换网 source 反例、libvirt typed error、UEFI XML、启动脚本一次性 runner 和反向控制台。不带 tag 的 portable 测试只能验证缺失 adapter 时的明确失败;生产交付必须通过 `-tags libvirt` 的编译和测试。PHP 契约测试还必须证明 PHP→Gateway 只使用字面 loopback 固定路径,不再存储或请求宿主机 endpoint。
PHP:
```bash
cd /home/virt-cloud/web
find app config public tests -name '*.php' -print0 | xargs -0 -n1 php -l
for test_file in tests/*Test.php; do php "$test_file" || exit $?; done
```
PHP 测试至少覆盖:Agent Gateway loopback 约束、Gateway 外层 HMAC、每宿主机内层密钥加密与签名 golden vector、Agent 握手认证、管理员权限、普通用户路由隔离、模板脚本读取/写入权限、32 KiB/UTF-8/NUL 边界、revision/generation、持久任务快照、账单与资源 reservation、`uncertain` 不自动重放/退款。
浏览器脚本与部署文件:
```bash
cd /home/virt-cloud
for test_file in web/tests/*.mjs; do node "$test_file" || exit $?; done
jq empty deploy/*.json.example
git diff --check
```
在 systemd Linux 测试机另运行:
```bash
systemd-analyze verify /home/virt-cloud/deploy/*.service
```
最终仓库不得再跟踪 Python 源码、依赖清单或旧引擎 service:
```bash
cd /home/virt-cloud
test -z "$(git ls-files '*.py' '*.pyi' '*requirements*.txt' 'pyproject.toml')"
test ! -e deploy/virt-cloud-engine.service
test ! -e deploy/virt-cloud-console-relay.service
test ! -e deploy/virt-cloud-console-relay.json.example
test ! -e gateway/cmd/virt-cloud-console-relay
! rg -n 'virt-cloud-engine\.service|/home/virt-cloud/engine|CLOUD_ENGINE_CONFIG' \
deploy README.md docs --glob '!VALIDATION.md'
! rg -n 'virt-cloud-console-relay|cloud_console_relay_secret|agent_websocket_url' \
deploy gateway web/app web/config README.md docs --glob '!VALIDATION.md'
```
上述 `requirements*.txt` 只是对已退役文件类型的残留检查,不是当前部署依赖;产品运行路径中不存在 Python 或 pip 安装步骤。
## 2. API 契约
使用 PHP 客户端与 Go 服务共享的固定向量校验以下字节级契约:
- method 必须转大写;path 与原始 query 不重排。
- body SHA-256 和 HMAC 为小写十六进制。
- actor JSON 为 URL-safe base64 且无填充。
- canonical 值为 method、target、digest、timestamp、nonce、actor 六行,以 `\n` 连接且末尾无额外换行。
- 缺少任一签名头、摘要不符、过期/未来时间、nonce 重放、actor 字段未知或签名错误全部拒绝。
- 认证错误不回显密钥、canonical 内容、内部路径或 libvirt 原始敏感信息。
每个 Agent 的 `/v1/health` 和 `/v1/capabilities` 都要从面板 `/admin/agents` 经当前已认证 WSS 会话测试;一个宿主机失败不得污染另一个宿主机的配置或状态。
## 3. 操作与故障注入
所有变更使用非生产测试 VM。为创建、关机、重启、强制断电、删除、重装、快照、救援、换 IP、断网/恢复分别覆盖:
1. Agent 收到请求前失败:PHP 可按同一标识安全重试。
2. Agent 持久写入派发边界后、调用 libvirt 前失败:恢复后仍使用原 `operation_id`,不得新建操作。
3. libvirt 调用已返回但响应丢失:任务进入 `uncertain`,通过 UUID 和本地操作日志核对。
4. Agent 或面板 worker 重启:操作日志、PHP 租约和 reservation 不丢失。
5. 同一 `operation_id` + 相同摘要:返回既有结果;同一标识 + 不同摘要:409 拒绝。
6. 同一 VM 并发变更:严格串行;不同 VM 可在资源上限内并行。
运行中状态不能证明关机/重启未发生;持久域消失不能在未核对磁盘清单时自动视为完整删除。任何未知删除都不得释放 IP、库存或退款。
## 4. libvirt 与宿主机
先做只读能力检查:
```bash
virsh -c qemu:///system version
virsh -c qemu:///system capabilities >/dev/null
virsh -c qemu:///system domcapabilities >/dev/null
virsh -c qemu:///system list --all
virsh -c qemu:///system net-list --all
virsh -c qemu:///system pool-list --all
```
只读检查不得安装软件、修改服务、网络、存储池、域 XML 或主机配置。只有明确授权的非生产宿主机才可运行变更测试。
生成的 XML 应使用宿主机的 `virt-xml-validate` 验证。至少检查:Q35、EFI loader/NVRAM 来自 domain capabilities、Secure Boot 明确关闭、MAC/网桥/带宽正确、磁盘与 cloud-init seed 路径位于受管目录、用户输入经过 XML 转义。
## 5. 镜像与首次启动脚本
- 远程导入验证 HTTPS、DNS 解析后的公网地址、每次跳转、超时、大小和 SHA-256;拒绝内网/环回/链路本地/元数据地址。
- 本地上传验证独立 QCOW2;拒绝 raw、ISO、加密、backing file、外部 data file、截断和超限文件。
- 每个镜像分别测试无脚本、空脚本、最大脚本、CRLF、非 UTF-8、NUL 和修订并发。
- 新 VM 第一次启动只运行一次。退出 0、非零、执行中重启、Agent 重启和控制面断线后均不能自动重放。
- 重装、救援、用户 ISO、普通重启、改密码、改主机名、改网络不得意外触发该首次安装脚本。
## 6. 业务与 UI 回归
管理员页面保持 venix,用户/登录页保持原虚拟机面板样式。逐项验收:
- 注册、登录、密码重置、充值、支付、公告、工单、管理员账户。
- `/admin/agents` 新增/修改密钥/禁用/出站连接测试;普通用户不可见且 API 返回拒绝。
- 地区、资源池、套餐、库存、多公网池、镜像、救援 ISO、系统日志和异常任务。
- 购买只扣款一次并只创建一台 VM;明确创建失败才退款,未知结果不退款。
- 控制台短票据一次消费、到期、登出撤销、跨用户拒绝和上游断线。
- CPU、内存、磁盘 I/O、网络图表持续采样;无人登录时仍采集。
- RX+TX 用尽只断网;下一账期恢复;最终到期只断网;三天宽限内续费恢复,宽限后删除定义与面板受管磁盘。
用桌面和手机宽度检查页面,确认后端切换没有改变用户可见信息架构,也没有向普通用户暴露宿主机或 Agent 管理入口。
## 7. 更新与恢复
在测试副本验证固定 `go` 分支 fast-forward、脏工作树拒绝、签名 API、令牌不回显、依赖变更人工门槛、service 停启顺序、`cloudInit` 失败、PHP-FPM 启动失败和健康检查失败。进入 `cloudInit` 后中断必须保留维护锁;不得因回退 Git 提交自动判定数据库安全。本项是对当前全新 schema 初始化/重放的保守处理,不是旧库兼容迁移。
## 8. 发布记录
发布提交前把实际结果追加到本节;未执行项写“未执行”及原因,不能写成通过。
```text
commit:
Go version / libvirt version / PHP version / MariaDB version:
go vet:
go test:
go test -race:
PHP tests:
Node tests:
systemd-analyze:
read-only host capability check:
authorized host mutation test:
browser/payment/SMTP test:
known skips or risks:
```
### 2026-10-15 `go` 分支提交前验收
```text
commit: 本记录所在 go 分支提交(基线 887072a)
Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / libvirt 12.8.0 / PHP 8.5.11 / MariaDB 未在本机运行
go vet: Agent 默认、libvirt+dlopen、libvirt 静态 tag 与 Gateway 均通过
go test: Agent 默认、libvirt+dlopen、libvirt 静态 tag 与 Gateway 均通过;go mod verify 与 tidy -diff 通过
go test -race: Agent 默认、libvirt+dlopen、libvirt 静态 tag 与 Gateway 均通过
PHP tests: 383 个 PHP 文件 lint 通过,113 个测试文件通过
Node tests: 93 个 JavaScript 文件语法检查通过,4 个行为测试通过;3 个部署 JSON 示例有效
systemd-analyze: 未执行;验收机为 macOS,不提供 systemd-analyze
read-only host capability check: 已对指定 103 宿主机只读检查;AlmaLinux 10.2、libvirt 11.10、qemu:///system、Q35 EFI 与 secureBoot yes/no 能力可用
authorized host mutation test: 未执行;用户明确禁止修改指定宿主机的任何配置
browser/payment/SMTP test: 自动化 PHP/Node 契约测试通过;真实支付、SMTP 和浏览器人工验收未执行
known skips or risks: 生产 Linux 上的 systemd-analyze、MariaDB 全新建库、真实 libvirt 破坏性生命周期与外部服务联调仍须在获授权测试环境验收;macOS 静态 libvirt 链接仅有重复库警告
```
### 2026-10-16 出站 WSS Agent Gateway 提交前验收
```text
commit: 本记录所在 go 分支提交(基线 97a17ed)
Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / libvirt 12.8.0 / PHP 8.5.11 / MariaDB 未在本机运行
go vet: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过
go test: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过;go mod verify 与 tidy -diff 通过;反向控制台目标测试分别连续运行 50 次和 30 次通过
go test -race: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过
Linux AMD64 build: linux/amd64 CGo + libvirt_dlopen 交叉编译通过;提交后按实际提交 SHA 重建发布包
PHP tests: SourceSyntax 检查 391 个 PHP 文件通过,115 个测试文件通过;现有测试依赖仅输出已知弃用/警告信息,退出码为 0
Node tests: 93 个 JavaScript 文件语法检查通过,4 个行为测试通过;3 个部署 JSON 示例有效
systemd-analyze: 未执行;验收机为 macOS,不提供 systemd-analyze
read-only host capability check: 本轮未完成;当前 Mac 的 SSH 别名 103 解析为 0.0.0.103,网络不可达
authorized host mutation test: 未执行;用户明确禁止修改指定宿主机的任何配置
browser/payment/SMTP test: 自动化 PHP/Node 契约测试通过;真实支付、SMTP 和浏览器人工验收未执行
known skips or risks: 生产 Linux 上的 systemd-analyze、MariaDB 全新建库、真实 libvirt 生命周期与外部服务联调仍须在获授权测试环境验收;macOS libvirt 链接测试仅有重复库警告
```
### 2026-10-16 创建/回执一致性加固提交前验收
```text
commit: 本记录所在 go 分支提交(基线 177fa24)
Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / 本机动态链接测试沿用已安装 libvirt / PHP 8.5.11 / MariaDB 未在本机运行
go vet: Agent 默认及 libvirt+dlopen、Gateway 均通过
go test: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过;两个 Go 模块的 mod verify 与 tidy -diff 均通过
go test -race: Agent libvirt+dlopen 与 Gateway 均通过
Linux AMD64 build: 提交后按实际提交源码交叉编译 Agent(CGo + libvirt_dlopen)和静态 Gateway 直运行二进制
PHP tests: 389 个 PHP 文件 lint 通过,116 个测试文件通过;仅输出既有 TicketAttachmentService warning 与 Predis deprecation,退出码为 0
Node tests: 89 个 JavaScript 文件语法检查通过,4 个行为测试通过;部署 JSON 示例有效
systemd-analyze: 待在 Linux 面板/宿主机部署时执行
read-only host capability check: 待对指定 103 宿主机部署前复核
authorized host mutation test: 待部署后在用户指定的测试环境按 operation_id 串行验收
browser/payment/SMTP test: 自动化 PHP/Node 契约测试通过;真实创建付款需在最终提交动作前取得用户即时确认
known skips or risks: libvirt 调用已执行但结果不可证明时会安全保留 uncertain,必须复用原 operation_id 核对,禁止自动重放;macOS libvirt 链接仅有重复库警告
```
### 2026-10-16 持久化目录任务收敛验收
```text
commit: 本记录所在 go 分支提交(基线 e7fa625)
Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / 本机动态链接测试沿用已安装 libvirt / PHP 8.5.11 / MariaDB 未在本机运行
go vet: Agent 默认及 libvirt tag、Gateway 均通过
go test: Agent 默认及 libvirt tag、Gateway 均通过;两个 Go 模块的 mod verify 均通过
go test -race: Agent libvirt tag 与 Gateway 均通过;Gateway race 测试获准绑定本机临时回环端口
Linux AMD64 build: 本提交未修改 Go 源码,继续使用 e7fa625 对应的已验证 Agent 与 Gateway 二进制
PHP tests: 392 个 PHP 文件逐文件 lint 通过,119 个测试文件通过;SourceSyntax 独立检查 396 个文件通过;仅输出既有测试 warning 与第三方依赖 deprecation,退出码为 0
Node tests: 89 个 JavaScript 文件语法检查通过,4 个行为测试通过;部署 JSON 示例有效
systemd-analyze: 本提交未修改 service 文件,未重复执行
read-only host capability check: HKG-A 出站 WSS 已稳定连接;Agent 报告 14 项必要能力、UEFI 可用且 Secure Boot 关闭
authorized host mutation test: HTTPS Debian 13 云镜像导入在 Agent 端确定成功,436207616 字节,SHA-256 为 1010eb3215be632548cfb6793b53bd8243064d8820b5106f2becfcd179099b2f;本提交新增后台同 operation_id 收敛,禁止重放原始导入 POST
browser/payment/SMTP test: 管理端网络选择器已由错误的 bridge:br0 修正为 Agent 声明的 public;旧创建任务已按原 operation_id 核对并明确失败退款;新的真实 10 USD 创建提交仍等待用户即时确认
known skips or risks: worker 每 tick 最多处理一个普通任务和一个目录核对;真实创建、重装、快照恢复和删除属于外部或破坏性操作,必须在动作前取得确认后再完成联调
```
### 2026-10-16 Linux AMD64 直运行二进制发布验收
```text
source commit: fbe8498deb9405a9e13396212eab43d1e490a8f3(Agent/Gateway Go 源码与 e7fa625 一致)
Go version: Go 1.27.1
Agent build: linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen、trimpath、vcs.modified=false
Agent artifact: release/virt-agent-linux-amd64
Agent SHA-256: ea70ee891a2b85793407a1d7a66679bc8d9822117daeb8e9a6b87da4e5570046
Gateway build: linux/amd64、CGO_ENABLED=0、静态链接、trimpath、vcs.modified=false
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64
Gateway SHA-256: e612c35eabae27d5afc483b9430404f9f9d73f92529dcd583ea1ba8ff17628e9
go mod verify: Agent 与 Gateway 均通过
go vet / go test: Agent 默认及 libvirt+libvirt_dlopen 均通过;Gateway 均通过
go test -race: Gateway 通过;Agent 沿用同一 source commit 的前置 race 验收
artifact inspection: 两个文件均为 ELF 64-bit x86-64,未嵌入本机路径或部署端点
known skips or risks: Agent 使用 libvirt_dlopen,宿主机运行时仍必须提供 libvirt.so.0;新产物未在本轮重复执行真实 VM 破坏性生命周期操作
```
### 2026-10-16 创建失败根因保留与阶段诊断验收
```text
commit: 本记录所在 go 分支源码提交(基线 93781a2)
Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / 本机 libvirt 12.8.0 / PHP 8.5.11 / MariaDB 未在本机运行
go vet: Agent 默认及 libvirt+libvirt_dlopen 均通过
go test: Agent 默认及 libvirt+libvirt_dlopen、Gateway 均通过;Gateway Agent 包连续 20 次通过;Agent go mod verify 通过
go test -race: Agent libvirt+libvirt_dlopen 与 Gateway 均通过
PHP tests: 119 个测试文件通过,app/config/public 下 272 个 PHP 文件逐文件 lint 通过;SourceSyntax 独立通过;仅输出既有测试 warning 与第三方依赖 deprecation,退出码为 0
Node tests: 4 个行为测试及 admin-operations.js 语法检查通过
libvirt XML: 当前 create 请求形态生成的 q35/UEFI、Secure Boot 关闭、br0 bridge 域 XML 通过 virt-xml-validate domain schema
read-only host capability check: 面板快照确认 Agent、public->br0、/29 地址池及模板副本均就绪;本轮桌面 SSH 自动化两次超时,未取得宿主机原始 libvirt 日志
authorized host mutation test: 未重新提交真实付费创建;现有失败任务已完成退款且受管工件确认不存在
known skips or risks: 旧 Agent 将最初错误覆盖为 creation_absent,历史任务无法恢复唯一根因;部署本提交后,新失败会保留首个 Agent cause_code 并区分模板、克隆、seed、NWFilter、domain define/autostart/start 阶段;卷缺失退款证据要求 dir pool 的刷新清单与目标文件 ENOENT 同时成立,其他池型保守保持 uncertain;随后须用一次受控创建完成宿主机实测
```
### 2026-10-16 创建诊断 Linux AMD64 二进制发布验收
```text
source commit: 59dff015355b93800d024e097dfc949584165536
Go version: Go 1.27.1
Agent build: linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen、trimpath、vcs.modified=false;外部链接器剥离调试符号并移除本机构建路径
Agent artifact: release/virt-agent-linux-amd64
Agent SHA-256: 3ba35c544f563354fbeab2f0f99e02acb0be917a45b16e58a7e4fdc1fbe0666f
Gateway build: linux/amd64、CGO_ENABLED=0、静态链接、trimpath、vcs.modified=false;运行时代码未改变,仅同步本次源码提交标识
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64
Gateway SHA-256: f59a96840b735c1560260830681b038a41e692c8623db3b820b9177b34f23361
go vet / go test: Agent libvirt+libvirt_dlopen 的 hypervisor、operation、api 通过;Gateway 全量及 race 通过
PHP tests: CloudAdminOperationsService、CloudAgentProtocol、CloudFinancialWorkflow、CloudOperationErrorCatalog、CloudProtocol 通过
artifact inspection: 两个文件均为 ELF 64-bit x86-64,未嵌入本机路径或部署端点;Agent 最低检测到 GLIBC_2.14,运行时需要 libvirt.so.0
known skips or risks: 二进制需部署到面板与宿主机后,再以一次受控创建取得新的 cause_code 并完成真实 libvirt 生命周期验收
```
### 2026-10-16 手工 UEFI 固件模式修复验收
```text
commit: 本记录所在 go 分支源码提交(基线 6461eb3)
Go version / libvirt version: Go 1.27.1 / 本机 libvirt 12.8.0
go vet: Agent 默认构建通过
go test: Agent 默认及 libvirt+libvirt_dlopen 全量通过;hypervisor 定向回归通过
go test -race: Agent libvirt+libvirt_dlopen 全量通过
go mod verify / tidy -diff: 均通过且无变更
Linux AMD64 build: Zig 交叉编译预检通过;linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen,最低 GLIBC 符号版本 2.14
read-only host diagnosis: 103 宿主机 libvirt 日志对失败创建明确报告 `cannot use feature-based firmware autoselection when firmware autoselection is disabled`
XML contract: 手工 loader/NVRAM 模式不再生成仅适用于 `os firmware='efi'` 自动选择的 firmware feature;测试精确锁定配置 loader、readonly=yes、pflash、secure=no、NVRAM template/path、SMM=off
authorized host mutation test: 未重放旧 operation_id,未重新提交付费创建,未注册测试域
known skips or risks: schema 校验不能捕获本次 libvirt 语义互斥;发布后二进制仍须先在 103 执行只读 domxml-to-native,再由用户即时确认一次受控付费创建
```
### 2026-10-16 手工 UEFI 修复 Linux AMD64 二进制发布验收
```text
source commit: e155ccfc3b09a2cd5e7ef523f82b5adefdaf8fc3
Go version: Go 1.27.1
Agent build: linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen、trimpath、vcs.modified=false;外部链接器剥离调试符号
Agent artifact: release/virt-agent-linux-amd64
Agent SHA-256: 5470337d9dda62b2c985eb32153bdcd705af62f8dd6a402532d945ef53dcfa3f
Gateway build: 本次未修改 Gateway 运行时代码,不重编译、不要求替换面板 Gateway
artifact inspection: ELF 64-bit x86-64 直运行文件,最低 GLIBC 符号版本 2.14,运行时需要 libvirt.so.0;未嵌入本机路径或部署端点
known skips or risks: 产物部署并重启 Agent 后仍须完成 103 宿主机只读 libvirt 语义验证;真实付费创建须在提交动作前取得用户即时确认
```
### 2026-10-16 实例模板元数据修复及 Linux AMD64 发布验收
```text
source commit: a25aa0fe5510afef47753245ea7cd3111c9b7f88
Go version / PHP version: Go 1.27.1 / PHP 8.5.11
functional fix: 创建与重装任务把 PHP 拥有的模板名称和登录名保存在 Agent 请求体之外;Agent 成功后实例标记 managed;历史修复默认 dry-run、只填缺失字段、支持 after-id 游标并优先使用付款订单不可变快照
go vet / go test: Agent 默认及 libvirt+libvirt_dlopen、Gateway 均通过;两个 Go 模块 go mod verify 通过
go test -race: Agent 默认及 libvirt+libvirt_dlopen、Gateway 均通过;macOS libvirt 链接仅有重复 -ldl 警告
PHP tests: web/tests 下 120 个测试文件全部通过;web/app、web/config、web/tests 共 394 个 PHP 文件 lint 通过;git diff --check 通过
Agent build: linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen、trimpath、外部链接器剥离调试符号、vcs.modified=false;Zig 0.13.0 目标 x86_64-linux-gnu.2.14
Agent artifact: release/virt-agent-linux-amd64
Agent SHA-256: 459db694d92b9c2039415e535019a49519d58c894db07b6cd7ce4ddb987074cd
Gateway build: linux/amd64、CGO_ENABLED=0、静态链接、trimpath、vcs.modified=false;运行时代码未改变,本次重编译用于同步源码提交标识
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64
Gateway SHA-256: 4ab467716095e850793600c9d91adab52d91d7622461c9fc4ecb6ad69b151f66
artifact inspection: 两个文件均为 ELF 64-bit x86-64 且已剥离;Agent 最高 GLIBC 符号版本 2.14,动态依赖为 libc/libpthread/libdl/libresolv,运行时通过 dlopen 需要 libvirt.so.0;未嵌入本机路径、面板或宿主机地址
read-only server check: 面板机为 AlmaLinux 10.2 x86_64 且具备 GCC/libvirt-devel,但未安装 Go;宿主机为 Debian 13 x86_64 且无构建工具,因此发布物使用低 glibc 交叉工具链生成
live deployment / repair: 未执行;本轮没有替换线上二进制、重启服务或修改生产数据库,部署面板后应先运行 cloudRepairInstanceMetadata dry-run,再显式 --apply
known skips or risks: 线上现有受影响实例在部署和执行受保护修复命令前仍保持旧元数据;真实新建、重装及设置操作需在部署后的受控实例完成最终联调
```
### 2026-10-16 快照 Guest Agent 自动降级及三产物 Linux AMD64 发布验收
```text
source commit: 312e6a9c0f9e6bd8e05782f0b4c34a3423e05de8
Go / Zig version: Go 1.27.1 / Zig 0.17.0
functional fix: filesystem 快照遇到 Guest Agent 不可用时自动降级为 crash-consistent 快照;其他冻结失败仍保持失败,不放宽为无条件降级
Agent build command: CGO_ENABLED=1 GOOS=linux GOARCH=amd64 CC='/private/tmp/virt-zig-0.17.0-aarch64-macos/zig cc -target x86_64-linux-gnu.2.14' CXX='/private/tmp/virt-zig-0.17.0-aarch64-macos/zig c++ -target x86_64-linux-gnu.2.14' go build -tags='libvirt libvirt_dlopen' -trimpath -ldflags='-s -w -linkmode external -extldflags=-s' -o /tmp/virt-amd64-release.1AUgDR/virt-agent-linux-amd64 ./cmd/virt-agent
Gateway build command: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/virt-amd64-release.1AUgDR/virt-cloud-agent-gateway-linux-amd64 ./cmd/virt-cloud-agent-gateway
Updater build command: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/virt-amd64-release.1AUgDR/virt-cloud-update-linux-amd64 ./cmd/virt-cloud-update
go mod verify / go vet: Agent 与 Gateway 两模块均通过;Agent 同时验证默认与 libvirt+libvirt_dlopen tags
go test: Agent 默认与 libvirt+libvirt_dlopen 全量通过;Gateway 全量通过
go test -race: Agent 默认与 libvirt+libvirt_dlopen 全量通过;Gateway 全量通过;macOS libvirt 链接仅有重复 -ldl warning;Gateway httptest 需要 loopback 端口,在允许本地监听的环境重跑通过
Agent artifact: release/virt-agent-linux-amd64 (10290256 bytes)
Agent SHA-256: b90472505295f1e4f6cecb102ac1cb5dd884c2e264b316b0084f3348dd4006a4
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64 (7803040 bytes)
Gateway SHA-256: aac959b2ed2edcfef3057a06093415bf365e37dcbce179414a8292aa8a396fe0
Updater artifact: release/virt-cloud-update-linux-amd64 (7127200 bytes)
Updater SHA-256: c1479d744241f937fde7b929d59f3b8f543f04e90df6c1d198ceb594d82c9eca
artifact inspection: 三个文件均为已剔除调试符号的 ELF 64-bit x86-64,trimpath 且 vcs.modified=false;Agent 最高 GLIBC 符号版本为 2.14,动态依赖为 libc/libdl/libpthread/libresolv,运行时通过 dlopen 需要 libvirt.so.0;Gateway 与 Updater 均为静态链接
sensitive string scan: 三个产物未发现本机路径、面板/宿主机地址、私钥标记或配置密钥值
live deployment: 尚未部署;本轮未替换面板或宿主机二进制,未重启服务,未重放历史快照 operation_id,也未执行真实 VM 快照变更
known skips or risks: 部署 Agent 后应在受控实例分别验证 Guest Agent 已连接时的 filesystem-consistent 路径和未连接时的 crash-consistent 降级路径;Updater 为首次纳入 release 的独立 AMD64 产物,仍需按部署文档安装配置、systemd unit 并完成 Unix socket 健康检查
```
### 2026-10-16 libvirt 内部名称隔离及三产物 Linux AMD64 发布验收
```text
source commit: ef87b456b660cfe13495edbc0dd2ba33508374b5
Go / Zig / PHP version: Go 1.27.1 / Zig 0.17.0 / PHP 8.5.11
functional fix: 新建 VM 的 libvirt domain name 由已验签 user_id 与最终 UUID 派生为 <user_id>:vm-<前 12 位小写无连字符 UUID>;面板显示名、首次 Guest 配置名与重装名称继续使用原请求 name;新域把显示名保存在 display-name metadata,旧域缺失时只读回退原 domain name
Agent build command: ZIG_GLOBAL_CACHE_DIR=/tmp/virt-zig-global-cache-domain-name ZIG_LOCAL_CACHE_DIR=/tmp/virt-zig-local-cache-domain-name CGO_ENABLED=1 GOOS=linux GOARCH=amd64 CC='/private/tmp/virt-zig-0.17.0-aarch64-macos/zig cc -target x86_64-linux-gnu.2.14' CXX='/private/tmp/virt-zig-0.17.0-aarch64-macos/zig c++ -target x86_64-linux-gnu.2.14' go build -tags='libvirt libvirt_dlopen' -trimpath -ldflags='-s -w -linkmode external -extldflags=-s' -o <temporary>/virt-agent-linux-amd64 ./cmd/virt-agent
Gateway build command: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o <temporary>/virt-cloud-agent-gateway-linux-amd64 ./cmd/virt-cloud-agent-gateway
Updater build command: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o <temporary>/virt-cloud-update-linux-amd64 ./cmd/virt-cloud-update
go mod verify / tidy -diff: Agent 与 Gateway 两模块均通过
go vet / go test / go test -race: Agent 默认与 libvirt+libvirt_dlopen 两套均通过;Gateway 全量普通与 race 均通过;macOS libvirt 链接仅有重复 -ldl warning;Gateway httptest 在允许回环监听后通过
PHP tests: web/tests 下 120 个自动测试全部通过;398 个 Git 版本化 PHP 文件 lint 通过
Node tests: 4 个行为测试通过;public/resources 下 89 个 JavaScript 文件语法检查通过
libvirt XML: 3:vm-834728973274 通过本机 libvirt 12.8.0 的 virt-xml-validate domain schema;Domain XML、metadata round-trip、旧域回退与重装显示名回归通过
Agent artifact: release/virt-agent-linux-amd64 (10294704 bytes)
Agent SHA-256: 43c49acc60962d0e38516f394820d79d45945c06031a54a09e992bb9c5ed118f
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64 (7803040 bytes)
Gateway SHA-256: 57c5c8a139aae36028c2eab6117617422c4c5eefa270d4b0891fe42458d52f1b
Updater artifact: release/virt-cloud-update-linux-amd64 (7127200 bytes)
Updater SHA-256: 9e30701585685eb0ec65e177a8b66b613bc24045107231a3b3d86c2f9a7fcde8
artifact inspection: 三个文件均为 stripped ELF 64-bit x86-64,trimpath、revision=ef87b456b660cfe13495edbc0dd2ba33508374b5 且 vcs.modified=false;Agent 最高 GLIBC 符号版本为 2.14,动态依赖为 libc/libdl/libpthread/libresolv,运行时通过 dlopen 需要 libvirt.so.0;Gateway 与 Updater 均为静态链接
sensitive string scan: 未发现本机路径、临时构建目录、私钥标记或已知线上主机地址;Updater 按设计包含独立项目 Git 远端用于 go 分支在线更新
live deployment: 尚未部署;本轮未替换面板或宿主机二进制、未重启服务、未新建或修改真实 VM
known skips or risks: 前 12 个 UUID 十六进制字符只有 48 bit,已经消除相同网站显示名导致的 libvirt 冲突,但同一用户的 UUID 前缀仍存在理论上的极低碰撞概率;若要求继承完整 UUID 唯一性,需改用全部 32 个无连字符字符;正式上线后仍需在目标宿主机做一次受控创建和重装验收
```