@ -109,10 +109,12 @@ 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 -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 /etc/virt-agent/config.json
/home/virt-cloud/deploy/virt-cloud-agent.json.example /hom e/agent/config.json
```
为每台宿主机生成不同的至少 32 字节随机密钥,并把相同值分别写入该机 Agent 配置和面板 `/admin/agents` 对应记录。`agent_id` 就是面板宿主机记录的正整数 ID, `panel_url` 是面板对 Agent 可达的 HTTPS origin。示例文件只有占位符, 绝不能直接启动或提交真实密钥。保存启用配置后, 先启动 Agent 建立出站会话,再到宿主机页注册五类存储目录,最后回到 `/admin/agents` 执行“测试连接”;存储尚未注册时能力测试会明确失败。面板仅在当前 `revision` 已通过健康与必要能力检查时才允许调度、业务 Agent 请求和控制台票据发放。密钥或启用状态修改会清除就绪标记。
@ -138,7 +140,7 @@ Agent 配置字段:
| `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 组合替换示例值。不得把 `/` 加入允许列表,也不要在样例 systemd 单元启用 `ProtectHome=true` 时使用 `/home` 下的目录 。存储配置使用独立的短边界:面板 60 秒内必须派发, Agent helper 最多运行 120 秒,面板在派发后最多等待回执 180 秒。这些边界不会被通用 `operation_timeout_seconds` 放宽。
`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。
@ -150,13 +152,13 @@ Agent 的 capabilities 响应仍使用 `network_selectors` 字段,但它是自
本版本只面向全新部署,不读取旧 `public` alias、旧网络映射或旧就绪记录。部署时必须直接填写真实的 `bridge:<name>` 或 `network:<name>` ;不要复制旧 Agent 配置,也不要把旧数据库导入当前 schema。
Agent 的 systemd 单元保持 `ProtectSystem=strict` 。`journal_path` 必须位于已授权的 `/var/lib/virt-agent` ;若确需另一个状态目录,应由运维通过 systemd drop-in 精确增加对应 `ReadWritePaths` 。存储池内容仍只由独立的 libvirt/QEMU 服务通过 `qemu:///system` 管理,不能把受管存储池目录授权给 Agent。删除回查需要清理域定义消失后残留的 UUID 专属 VARS 文件,因此样例 unit 仅额外授权标准 `/var/lib/libvirt/qemu/nvram` ;若 `nvram_directory` 使用其他路径,必须在 drop-in 中用该实际目录替换,并保持授权范围只覆盖 NVRAM 目录。capabilities 只确认该目录存在,不冒充对 systemd mount namespace 写权限的验证;正式上线仍须用授权的创建/删除验收确认权限 。
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 会拒绝旧 schema, 不执行升级或回填; 全新安装必须使用空状态目录。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 不启动入站监听 。
配置必须存在、可读、是单个严格 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:
@ -327,7 +329,7 @@ location = /agent/console {
}
```
不要公开 PHP 内省/认证接口、`/internal/agent/request`、Gateway 的本机端口或 libvirt。Agent 宿主机无需开放管理端口;出站网络只需能访问面板 HTTPS/WSS 和经校验的 HTTPS 镜像源 。
不要公开 PHP 内省/认证接口、`/internal/agent/request`、Gateway 的本机端口或 libvirt。Agent 宿主机无需开放通用管理端口;出站网络需要访问面板 HTTPS/WSS、经校验的 HTTPS 镜像源及对象存储。维护迁移还要求同一资源池的宿主机之间双向放行 `peer_migration_port` (默认 `9443/TCP` ),不应向无关公网来源开放该端口 。
控制台上线前必须验收:一次性票据只能消费一次、过期拒绝、登出/撤销后断开、跨用户/跨 VM 拒绝、Origin 校验、上游 Agent 断线及时关闭、浏览器不能注入 endpoint。Agent 未声明 console capability 时, PHP 必须显示不可用,不能回退旧实现。