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

571 lines
54 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`、多资源键严格串行、不相交资源并行、重 I/O 容量限制、派发前锁等待超时、派发后超时仍保留租约、派发前/后故障注入、inflight 与 recovery 索引重启恢复、长期待核对记录不被压缩、超过 16 MiB 的永久 journal 重启、nonce 到期索引清理、operation tombstone 保留、五类 expected-state/transition marker 只读核对、换网 source 反例、libvirt typed error、UEFI XML、启动脚本一次性 runner 和反向控制台。libvirt 定向测试还必须覆盖 event loop 早于连接、每个 generation 注册与逆序释放 lifecycle/`JOB_COMPLETED`/close callback、回调非阻塞合并、注册期间断线、旧 generation 延迟回调、新旧 session 租约切换、退避重连与关停,以及启动/重连 recovery 扫描不会重放 mutation。`JOB_COMPLETED` 只能提前唤醒 `GetJobStats`,没有事件时仍须靠轮询确认终态。不带 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 不丢失;Agent 启动扫描 recovery 索引并核对所有未完成 operation。
5. 同一 `operation_id` + 相同摘要:返回既有结果;同一标识 + 不同摘要:409 拒绝。
6. 同一 VM 或共享卷、过滤器、目录资源的并发变更:严格串行;不相交资源可在容量上限内并行。锁或重 I/O 槽等待超时必须保持 `not_dispatched`,派发后 HTTP 超时必须继续持有全部租约直到真实调用返回。
7. 在授权的非生产环境分别中断并重启实际使用的 libvirt daemon 与 Agent:close callback 只唤醒后台重连,重连后重新注册全部事件并扫描 Journal;旧连接的迟到事件不能影响新连接,扫描不得重放原 mutation。
运行中状态不能证明关机/重启未发生;持久域消失不能在未核对磁盘清单时自动视为完整删除。任何未知删除都不得释放 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:
event/reconnect unit tests:
authorized libvirt daemon restart test:
Agent restart recovery scan 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 个无连字符字符;正式上线后仍需在目标宿主机做一次受控创建和重装验收
```
### 2026-10-17 宿主机存储注册与重复逻辑精简
```text
source: 本记录所在 go 分支提交,基于 913f0fa;macOS arm64,Go 1.27.1、libvirt 12.8.0、PHP 8.5.11、Node 24.19.0
scope: 五类存储目录注册;合并存储探测、Agent 就绪失效和抽屉公共逻辑;正常能力探测的池查找由 21 次降至 6 次;相对精简前源码与测试净减少 51 行(不含本记录)
Go: Agent 与 Gateway 的 go mod verify、gofmt 检查、go vet、go test、go test -race 通过;Agent 同时通过默认、libvirt、libvirt+libvirt_dlopen 三套构建,均为 8 个测试包通过、1 个命令包无测试;Gateway 为 4 个测试包通过、2 个命令包无测试
PHP: tests/*Test.php 共 123/123 通过,无跳过;app/config/public/tests 下 401 个 PHP 文件语法检查通过;存储 GET/PUT 的 6 种权限拒绝与就绪撤销行为验证通过
Node and contracts: 4/4 个 mjs 测试、admin.js 语法、部署 JSON 和 git diff --check 通过;12 组抽屉新旧行为、1787 组路径校验新旧结果一致
temporary Go validation: overlay 测试及 race 通过,验证同阶段读取次数、变更后重新读取和 8 个错误分类;保留原有仓库安全测试,临时 fake/overlay 不提交
known limits: 未进行真实宿主机注册、重启或部署;保留 uncertain 重试误判 failed 和仅检查运行中存储池 XML 两个已知问题;PHP 既有警告及 macOS 重复链接库警告不影响测试退出状态
```
### 2026-10-17 宿主机存储注册 Linux AMD64 构建验收
```text
source commit: 7ef64578924549b9c5d10402eb74e1790f8f2ddb
Go / Zig version: Go 1.27.1 / Zig 0.17.0;构建主机为 macOS arm64
Agent build: CGO_ENABLED=1 GOOS=linux GOARCH=amd64;tags=libvirt,libvirt_dlopen;Zig target=x86_64-linux-gnu.2.14;trimpath;ldflags='-s -w -linkmode external -extldflags=-s'
Gateway / Updater build: CGO_ENABLED=0 GOOS=linux GOARCH=amd64;trimpath;ldflags='-s -w';静态链接
validation: 本轮两个模块 go mod verify、三个程序交叉编译、ELF 架构/依赖及构建元数据核验通过;源码未改变,全量测试结果沿用上方同一源码提交的测试记录
Agent artifact: release/virt-agent-linux-amd64 (10362576 bytes)
Agent SHA-256: 04626e2565c4b79452770e86797e37247bcabd4a99cfdb2924181501fcf0e36d
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64 (7803040 bytes)
Gateway SHA-256: 14ea31f7d48c9072840b280b8332b809265806b17c6bd61361d818b07fc88d5e
Updater artifact: release/virt-cloud-update-linux-amd64 (7127200 bytes)
Updater SHA-256: 3d4cb40b9648328ec68c2465873eb6b8998ca885ffbe7d5ed8b1ba04f6db0e09
artifact inspection: 三个产物均为 stripped ELF 64-bit x86-64、GOAMD64=v1、revision=7ef64578924549b9c5d10402eb74e1790f8f2ddb、vcs.modified=false;Agent 最高 GLIBC 符号版本 2.14,动态依赖 libc/libresolv/libpthread/libdl,运行时仍需 libvirt.so.0;Gateway/Updater 无动态依赖
build path / key marker scan: 三个产物未发现本机用户路径、临时构建路径或私钥标记;全部先在临时目录构建和验证,再更新 release
live deployment: 未执行;本轮未在 Linux 宿主机运行产物、替换线上程序或重启服务;两个已知存储问题保持不变
```
### 2026-10-17 宿主机网络接入统一由面板配置
```text
source: 本记录所在 go 分支提交,基于 1f19d42;Go 1.27.1、libvirt 12.8.0、PHP 8.5.11、Node 24.19.0
behavior: 面板选择现有 Linux 网桥或 libvirt network,新建默认 bridge:br0;Agent 配置删除 network_selectors,不再维护别名映射;签名请求使用 bridge:<name>/network:<name>
safety: 两端严格校验名称和长度;Agent 验证真实 UP bridge 或 active libvirt network,capabilities 排序去重且最多 64 项,创建/换网时再次验证;保持原 HMAC、权限、事务锁、占用池和 operation 对账边界
readiness: 网络修改撤销旧 revision 的就绪结果;旧 alias 即使留有 healthy 记录也不能通过客户端、调度、换网、控制台和就绪/健康投影;已下发请求及 journal 不重写
Go: Agent/Gateway go mod verify、gofmt 通过;Agent 默认、libvirt、libvirt+libvirt_dlopen 三套 vet/test/race 全通过,每套测试为 8 个测试包和 1 个无测试命令包;Gateway vet/test/race 通过,4 个测试包和 2 个无测试命令包
PHP: 124/124 个 tests/*Test.php 通过,无跳过;app/config/public/tests 的 403 个 PHP 文件 lint 通过;包含旧 healthy 拒绝、两类网络保存及就绪撤销、用户网络注入拒绝、签名任务来自面板接入配置的回归
Node: 5/5 个 mjs 测试及 admin.js 语法检查通过;新增宿主机网络表单默认值、提交、旧值提示、长度、只读权限和摘要行为测试
cross-language validation: 2064 组网络选择器在 Go/PHP/JavaScript 中与严格协议规则全部一致,覆盖控制字符、路径、Unicode、长度边界和旧别名
other validation: 部署示例 JSON、git diff --check 通过;macOS libvirt 重复链接库 warning 及 PHP 既有警告不影响退出状态
upgrade: 删除旧 Agent 配置的整个 network_selectors 字段;核实真实网络后在面板重新保存并测试;有占用的旧别名地址池须受控迁移,不能自动猜测 public=bridge:br0 或重放不确定操作
live deployment: 未修改真实宿主机网卡、路由、VM 或生产数据库;两个已知存储问题保持原样
```
### 2026-10-17 面板网络接入 Linux AMD64 构建验收
```text
source commit: 8e977b487f11c6a0338a498956ddf152c26bb810
toolchain: Go 1.27.1 / Zig 0.17.0,macOS arm64 交叉编译 linux/amd64,GOAMD64=v1
Agent build: CGO_ENABLED=1,tags=libvirt,libvirt_dlopen,Zig target=x86_64-linux-gnu.2.14,trimpath,ldflags='-s -w -linkmode external -extldflags=-s'
Gateway / Updater build: CGO_ENABLED=0,trimpath,ldflags='-s -w',静态链接;同步本次源码提交标识
Agent artifact: release/virt-agent-linux-amd64 (10365456 bytes)
Agent SHA-256: 751e11ac6b63c6dbbcf0eeca2bde473b3f68999910424c28aa276942294575e4
Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64 (7803040 bytes)
Gateway SHA-256: b5cec2f29a5886693b1eb68990bdcb1df0922231029fdd4d16e43bf2db2cf959
Updater artifact: release/virt-cloud-update-linux-amd64 (7127200 bytes)
Updater SHA-256: 8d6045a0a813c395e8393182bd7394232f5b0145956ba4f6849c377cf49be01c
artifact inspection: 三个产物均为 stripped ELF 64-bit x86-64,revision=8e977b487f11c6a0338a498956ddf152c26bb810、vcs.modified=false;Agent 最高 GLIBC 符号版本 2.14,动态依赖 libc/libresolv/libpthread/libdl,运行时仍需 libvirt.so.0;Gateway/Updater 无动态依赖
build path / key marker scan: 三个产物未发现本机用户路径、临时构建路径或私钥标记;临时目录中完成全部构建和验证后再更新 release
live deployment: 未执行;源码测试见上方同一源码版本记录;产物尚未在真实 Linux 宿主机运行
```
### 2026-10-18 第一阶段资源准入锁及 Linux AMD64 构建验收
```text
source commit: cad916e3978d712d1b75f979b50b0684b02d7e18
behavior: 删除宿主机级 domainMutationMu、storageConfigMu 和 catalogImportMu;按 domain、volume、nwfilter、catalog、storage-config 及网络身份资源键排序取得租约,不相交资源可并行;重 I/O 容量默认 4、允许 2~4
dispatch boundary: 资源租约、重 I/O 槽和通用执行槽全部在 markDispatching 前取得;等待失败持久记录为 operation_not_dispatched 并允许同 operation_id/同指纹重新准入;派发后 HTTP 超时转为 uncertain,全部租约保留到真实调用返回
Go validation: Agent go mod verify 通过;默认与 libvirt+libvirt_dlopen 两套 go vet、go test、go test -race 全量通过;operation/api/hypervisor 关键并发测试连续 5 次通过;macOS 链接仅有重复 -ldl warning
PHP validation: Agent 协议、模板/救援/用户 ISO 导入收敛、公平调度及财务任务共 8 个定向测试通过;PHP 8.5.11 原生语法检查 407 个文件通过
Agent build: Go 1.27.1 / Zig 0.17.0;CGO_ENABLED=1、GOOS=linux、GOARCH=amd64、tags=libvirt,libvirt_dlopen、target=x86_64-linux-gnu.2.14、trimpath、外部链接器剥离调试符号
Agent artifact: release/virt-agent-linux-amd64 (10415792 bytes)
Agent SHA-256: a6672656730189ef663e23cf4c64617425ff173c0e80102ee24434728defcc36
artifact inspection: stripped ELF 64-bit x86-64、GOAMD64=v1、revision=cad916e3978d712d1b75f979b50b0684b02d7e18、vcs.modified=false;运行时通过 dlopen 需要目标宿主机提供 libvirt.so.0
known limits: 同一模板的创建仍因模板目录资源使用独占租约而串行;换网的持久 IP 唯一性仍由面板/IPAM 保证;升级前旧 journal 记录在对账时使用兼容主资源键
live deployment: 未执行;未替换线上 Agent、重启服务、修改宿主机配置、创建或变更真实 VM
```
### 2026-10-18 libvirt 官方超时、取消与非阻塞存储流
```text
source: 本记录所在 go 分支源码提交,基于 7f528e4;Go 1.27.1、libvirt 12.8.0,macOS arm64
guest agent: filesystem-consistent 在线快照在 freeze 前设置 AgentSetResponseTimeout;默认 15 秒、允许 5~120 秒;本地客户端或守护进程低于 libvirt 5.10.0、或驱动明确返回 unsupported 时降级 crash-consistent,版本查询/RPC 失败不伪装成降级
snapshot cancellation: 继续使用 BackupBegin + GetJobStats;context 超时后仅在当前 active job 明确为 BACKUP 时调用一次 AbortJob,再等待最多 30 秒确认 COMPLETED/FAILED/CANCELLED;无终态保持 uncertain;全仓没有其他生产 AbortJob 调用
storage streams: 三个 NewStream 调用均使用 VIR_STREAM_NONBLOCK;默认 event loop 在连接前注册 heartbeat 并持续运行;Send/Recv 的 -2 通过事件 callback、context 和 StreamAbort 收敛;成功路径 remove callback -> Finish -> Free,异常路径 remove callback -> Abort -> Free,无法安全移除 callback 或 Abort 失败时保留 stream 并标记 uncertain
context and rollback: upload/download、模板/救援/用户 ISO、seed、rescue 和 reconcile 路径均传播 context;覆盖旧 seed 的回滚使用 WithoutCancel 加独立 30 秒上限
validation: Agent go mod verify、go mod tidy -diff、git diff --check、JSON 解析和 gofmt 检查通过;默认、libvirt、libvirt+libvirt_dlopen 三套 vet/test 通过;默认与 libvirt+libvirt_dlopen 全量 race 通过;快照定向测试连续 20 次、stream 定向 race 连续 10 次通过;macOS 链接器仅报告重复 -ldl/-lvirt warning
known limits: libvirt-go v1.12007.0 的 stream callback ID 无 free hook;实现使用无闭包包级 callback,不会永久持有请求 context/buffer/stream,但每个实际遇到 -2 的 stream 仍会留下一个很小的 callback map 条目;仍需在目标 Debian/libvirt 宿主机执行真实 QGA freeze/thaw、强制 stream would-block/cancel 和 backup 超时验收
live deployment: 未执行;未替换线上 Agent、重启服务、修改宿主机配置或操作真实 VM
```
### 2026-10-18 libvirt 第二阶段 Linux AMD64 构建验收
```text
source commit: 118a5957a854114521e9d762d10faa3272f072f0
toolchain: Go 1.27.1 / Zig 0.17.0;macOS arm64 交叉编译 linux/amd64,GOAMD64=v1
Agent build: CGO_ENABLED=1;tags=libvirt,libvirt_dlopen;Zig target=x86_64-linux-gnu.2.14;trimpath;ldflags='-s -w -linkmode external -extldflags=-s'
Agent artifact: release/virt-agent-linux-amd64 (10450192 bytes)
Agent SHA-256: 82a914a0072a9269fdf47fc1ea21a09dbccc65fb188ea062e33ff13419c97ba9
artifact inspection: stripped ELF 64-bit x86-64;revision=118a5957a854114521e9d762d10faa3272f072f0;vcs.modified=false;最高 GLIBC 符号版本 2.14;动态依赖 libc/libresolv/libpthread/libdl,运行时通过 dlopen 需要 libvirt.so.0
build path / key marker scan: 未发现本机用户路径、临时构建目录、私钥标记或项目 Git 远端;产物先在临时目录构建和验证,再更新 release
live deployment: 未执行;产物尚未在真实 Linux 宿主机运行,未替换线上 Agent 或重启服务
```
### 2026-10-18 libvirt 连接、事件与 Journal 恢复
```text
source: 本记录所在 go 分支源码提交,基于 a73c269;Go 1.27.1、libvirt 12.8.0,macOS arm64
connection generations: 默认 event loop 在首次连接前注册并持续运行;每个 qemu:///system 连接代注册 connection close、全域 lifecycle 和 JOB_COMPLETED;断线后后台退避重连并重新注册;新代完整发布后接收新调用,旧代等全部在途调用真实返回后再逆序注销 callback 和关闭
event semantics: callback 仅做代际校验和有界合并唤醒;JOB_COMPLETED 只促使快照等待器重新读取 GetJobStats,500ms 轮询保留;connection close 同时唤醒 stream/job waiter;事件、completed job stats 和临时连接状态均不作为操作结果证据
recovery: Journal schema v2 自动事务升级到 v3,新增 recovery 索引;启动、成功重连、lifecycle/JOB_COMPLETED/close 事件及 5 分钟周期兜底均扫描可核对 operation;每项默认 30 秒,串行取得原资源租约,只读核对或继续同 operation_id 的幂等 cleanup tail,绝不重放原 mutation;未解决记录继续保留索引及证据,不受 90 天详情压缩影响
dispatch result: 无可用 session 且 backend 明确未调用时返回确定的 libvirt_unavailable;真实调用后遇到 RPC、INVALID_CONN 或 NO_CONNECT 时 mutation 保持 uncertain 并触发重连
validation: Agent go mod verify、go mod tidy -diff、gofmt 和 git diff --check 通过;默认、libvirt、libvirt+libvirt_dlopen 三套 go test 通过;默认与 libvirt+libvirt_dlopen 全量 race 通过;默认与 libvirt+libvirt_dlopen vet 通过;operation/hypervisor 定向测试覆盖 v2→v3 迁移、恢复索引、关停、事件合并、每项超时、连接代切换、迟到 callback、注册清理顺序、JOB_COMPLETED 非证据语义和 AbortJob 终态确认;macOS 链接器仅报告重复 -ldl/-lvirt warning
upgrade: 这是 Agent 本地 journal 的自动升级,不需要修改面板数据库;首次打开 v2 journal 会扫描一次现有 operation 回填 recovery 索引,后续启动只读取 inflight/recovery 索引
known limits: 尚未在真实 Debian/libvirt 宿主机执行 virtqemud/libvirtd 重启、Agent 重启和 callback 重注册验收;libvirt-go v1.12007.0 的 stream callback free-hook 限制仍与第二阶段记录相同
live deployment: 未执行;未替换线上 Agent、重启服务、修改宿主机配置或操作真实 VM
```
### 2026-10-18 libvirt 第三阶段 Linux AMD64 构建验收
```text
source commit: 1bfc8b7513a87aa135cb2a05e6fd552b4705d247
toolchain: Go 1.27.1 / Zig 0.17.0;macOS arm64 交叉编译 linux/amd64,GOAMD64=v1
Agent build: CGO_ENABLED=1;tags=libvirt,libvirt_dlopen;Zig target=x86_64-linux-gnu.2.14;trimpath;ldflags='-s -w -linkmode external -extldflags=-s'
Agent artifact: release/virt-agent-linux-amd64 (10603632 bytes)
Agent SHA-256: f9c116c367b542daef3da6ee08e30d77b833e3a22c7eba829c1f17ab47b38050
artifact inspection: stripped ELF 64-bit x86-64;revision=1bfc8b7513a87aa135cb2a05e6fd552b4705d247;vcs.modified=false;最高 GLIBC 符号版本 2.14;动态依赖 libc/libresolv/libpthread/libdl,运行时通过 dlopen 需要 libvirt.so.0
build path / key marker scan: 未发现本机用户路径、临时构建目录、私钥标记或项目 Git 远端;仅包含预期的配置字段名称;产物先在临时目录构建和验证,再更新 release
validation: 源码测试见上方同一源码提交记录;复制到 release 后 SHA-256 与临时产物一致
live deployment: 未执行;产物尚未在真实 Linux 宿主机运行,未替换线上 Agent、重启 Agent 或重启 libvirt daemon
```
### 2026-10-18 管理员操作四语义与只读核对
```text
source: 本记录所在 go 分支源码提交,基于 4aba92a;Go 1.27.1、libvirt-go 1.12007.0、PHP 8.5.11
behavior: 管理员任务页拆分为立即核对、停止自动核对、请求中止 libvirt 作业、清理已确认残留;立即核对不进入 Journal mutation/reconcile;停止自动核对只在面板数据库阻止后续领取;中止和清理只能由最近一次状态绑定核对结果开放,二者互斥,页面最多显示三个动作按钮
abort safety: 当前只允许中止与 create-snapshot operation、确定性 managed snapshot volume 及单盘 vda push-backup XML 精确匹配的 BACKUP;AbortJob 发出后忽略 HTTP 取消并在独立 30 秒窗口继续等待 COMPLETED/FAILED/CANCELLED,仍无终态则保持 uncertain;block job 只阻止清理,当前不提供 block abort
cleanup safety: plan_id 绑定 Domain live/persistent XML、精确卷集合及卷 XML、filter XML、NVRAM、流量状态和磁盘切换元数据等私有证据;Journal 资源准入后重新核对计划,并在 delete/snapshot/disk-transition 的 mutation 尾段再次拒绝任意活动 domain job、block job 或不可读状态;共享引用和证据变化均失败关闭
privacy and authorization: 四类动作均要求超级管理员;Agent 恢复错误不附 Journal record;PHP 只按稳定错误码生成固定中文提示;网页不展示路径、XML、原始异常、result、cause_code、密钥或 libvirt 自由文本
Go validation: go mod verify、go mod tidy -diff、gofmt、git diff --check 通过;默认、libvirt、libvirt+libvirt_dlopen 三套 test/vet 通过;默认与 libvirt+libvirt_dlopen 全量 race 通过;核对/job/plan/API 脱敏定向测试各连续 20 次通过;macOS 链接器仅报告重复 -lvirt/-ldl warning
PHP validation: 125/125 个 tests/*Test.php 通过;测试套件自带的 PHP 8.5.11 原生源码语法检查为 409 个文件,另对 app/config/public/tests 的 405 个 PHP 文件逐一 lint 通过;既有第三方 deprecated/warning 不影响退出状态
Node validation: 5/5 个 mjs 行为测试及 admin-operations.js 语法检查通过;覆盖最多三个按钮、互斥能力、二次确认、CSRF、未知步骤拒绝和敏感字段不渲染
upgrade: 无面板数据库迁移;复用 cloud_jobs 的 cancelled 状态表示已停止自动核对,不自动改写历史 cancelled 记录;部署需同步 PHP、静态资源及新 Agent
known limits: 尚未在真实 Debian/libvirt 宿主机验证 GetBlockJobInfo 无任务返回、真实 push backup 中止和外部工具并发启动 job;完整卷 XML 与 NVRAM 状态绑定可能使运行中虚机的计划更易过期,管理员需重新立即核对,过期只拒绝清理
live deployment: 未执行;未替换线上 Agent、重启服务、修改宿主机配置、操作真实 VM 或修改生产数据库
```
### 2026-10-18 管理员恢复第四阶段 Linux AMD64 构建验收
```text
source commit: e11a380e8f92fb6e5b6f28f9146c070d47854bbb
toolchain: Go 1.27.1 / Zig 0.17.0;macOS arm64 交叉编译 linux/amd64,GOAMD64=v1
Agent build: CGO_ENABLED=1;tags=libvirt,libvirt_dlopen;Zig target=x86_64-linux-gnu.2.14;trimpath;ldflags='-s -w -linkmode external -extldflags=-s'
Agent artifact: release/virt-agent-linux-amd64 (10708112 bytes)
Agent SHA-256: ce05840349e1ce1652001b60c3e6d6d0eaf6a553cf79b9e5ba758d4afa640f53
artifact inspection: stripped ELF 64-bit x86-64;revision=e11a380e8f92fb6e5b6f28f9146c070d47854bbb;vcs.modified=false;最高 GLIBC 符号版本 2.14;动态依赖 libc/libresolv/libpthread/libdl,运行时通过 dlopen 需要 libvirt.so.0
build path / key marker scan: 未发现本机用户路径、临时构建目录、私钥标记或项目 Git 远端;临时目录产物与 release 文件逐字节一致
validation: 源码测试见上方同一源码提交记录;构建后再次核对 file、go version -m、ELF dynamic section、GLIBC version references、SHA-256 和敏感字符串
live deployment: 未执行;产物尚未在真实 Linux/libvirt 宿主机运行,未替换线上 Agent 或重启服务
```
### 2026-10-18 VM 删除分阶段恢复与 Linux AMD64 构建验收
```text
source commit: 2d0305d5dd82b904581f6c66393cc53e0381d9b6
delete stages: 普通删除只执行 graceful_shutdown;确认等待结束仍活动才返回 force_required;force_delete 使用独立 operation ID 和 ack_data_loss=true;inactive 后才进入 cleanup;自动核对永不把 graceful 或 uncertain force 升级为 Destroy
delete evidence: 删除前失败关闭地核对 managed-save、原生 snapshot/checkpoint、外部 snapshot/revertDisks/snapshotDeleteInProgress、实际 NVRAM、卷与过滤器的当前及历史引用;首次删除与 reconcile 共用 Domain、卷、Seed、过滤器、NVRAM 和流量状态的最终 absence 检查
recovery bounds: Agent 自动核对默认最多 24 次或 6 小时,面板最多 12 次或 6 小时;到限进入 needs_attention 并退出普通 worker,但 resource blocker 继续阻止同 VM、卷、过滤器和目录资源的冲突操作
crash recovery: ShutdownFlags 派发边界崩溃后,fresh admission-bound inspection 将仍活动的旧 graceful operation 结案为 graceful_shutdown_unconfirmed,只允许新 operation 重新正常关机;已授权 force 的结果丢失且 Domain 仍活动时,只能由超级管理员 token 二次核对确认旧 force 失败,随后再次 ack_data_loss 并创建新的 force operation;dispatching 和晚到结果不能被旧 token 覆盖
administrator semantics: 立即核对保持只读;停止自动核对不表示底层调用停止;AbortJob 只用于匹配的在线 push backup;清理残留需要 token/plan 二次确认;网页仅显示白名单错误码的固定中文提示和 operation ID
Go validation: go mod verify、go mod tidy -diff、gofmt、git diff --check 通过;默认、libvirt、libvirt+libvirt_dlopen 三套 go test -count=1 ./... 与 go vet ./... 通过;libvirt+libvirt_dlopen 的 hypervisor/operation/api race 通过;macOS 链接器仅报告重复 libvirt/dl 库 warning
PHP validation: tests/*Test.php 125/125 通过;app/config/public/tests 下 405 个 PHP 文件逐一 php -l 通过;覆盖正常关机崩溃重试、强制删除二次授权、账本保留、管理员 token 核对、needs_attention 与错误白名单
Node validation: 5/5 个 mjs 行为测试通过;public/resources 下 89 个 JavaScript 文件 node --check 通过
review: 两轮独立终审均未发现剩余 HIGH/MEDIUM;已知低风险为 CloudWorkerService 终态事务与部分管理员事务的 job/instance 行锁顺序不同,极端同任务并发可能触发数据库可重试死锁,但事务回滚、租约和 blocker 会保留一致状态,不会重复 Destroy 或释放账本
upgrade: 无面板数据库迁移;Agent bbolt journal 从 schema v2/v3 自动事务升级到 v4 并回填 recovery/resource-blocker 索引;部署需同步面板 PHP、静态资源与本次 Agent
toolchain: Go 1.27.1 / Zig 0.17.0;macOS arm64 交叉编译 linux/amd64,GOAMD64=v1;CGO_ENABLED=1;tags=libvirt,libvirt_dlopen;target=x86_64-linux-gnu.2.14;trimpath;ldflags='-s -w -linkmode external -extldflags=-s'
Agent artifact: release/virt-agent-linux-amd64 (10885744 bytes)
Agent SHA-256: 816fc90ca85bb2efef0bcabcab1049fc3160175b771a26fe5c7f93c67d186636
artifact inspection: stripped ELF 64-bit x86-64;revision=2d0305d5dd82b904581f6c66393cc53e0381d9b6;vcs.modified=false;最高 GLIBC 符号版本 2.14;动态依赖 libc/libresolv/libpthread/libdl,运行时通过 dlopen 需要 libvirt.so.0
build path / key marker scan: 未发现本机用户路径、临时构建目录、私钥标记或项目 Git 远端;临时目录产物与 release 文件逐字节一致
live deployment: 未执行;未替换线上 Agent、重启服务、修改宿主机配置、操作真实 VM 或修改生产数据库
```