docs: align agent deployment contract

go
codex 4 weeks ago
parent f8464313b7
commit fd28f475f1

@ -4,10 +4,10 @@ Virt Cloud 是 PHP 8.5 面板与宿主机 Go Agent 组成的虚拟机销售平
## 架构与功能
- PHP 负责账户、授权、余额、支付、订单、账期、资源账本、Agent 注册和持久任务协调。管理员在 `/admin/agents` 为每台宿主机配置独立 Agent 密钥;宿主机不再向面板暴露管理端口。
- PHP 负责账户、授权、余额、支付、订单、账期、资源账本、Agent 注册和持久任务协调。管理员在 `/admin/agents` 为每台宿主机配置独立 Agent 密钥;宿主机不向面板暴露 SSH、libvirt 或通用 Agent 管理端口。
- PHP 使用 `cloud_data_key` 的用途隔离密钥密封 Agent 密钥、任务载荷和凭据;只接受当前版本密文,不导入或尝试解密旧格式。
- 每台虚拟化宿主机运行 `virt-agent`,只连接本机 `qemu:///system`,执行 libvirt、存储、网络、快照、救援、指标和控制台后端操作。面板不保存 SSH/libvirt 登录凭据,也不直接执行宿主机命令。
- Agent 以 `panel_url + agent_id + agent_secret` 主动建立 WSS 长连接。PHP 先持久化任务并立即向浏览器返回 `202 Accepted`,再通过面板本机 Go Agent Gateway 派发一次带 SHA-256、时间戳、nonce、操作者上下文和 HMAC-SHA256 签名的请求。断线、超时或重启都不会重新派发 mutation。
- Agent 以 `panel_url + agent_id + agent_secret` 主动建立 WSS 控制长连接。PHP 先持久化任务并立即向浏览器返回 `202 Accepted`,再通过面板本机 Go Agent Gateway 派发一次带 SHA-256、时间戳、nonce、操作者上下文和 HMAC-SHA256 签名的请求。断线、超时或重启都不会重新派发 mutation。维护迁移的数据不经过面板:同资源池宿主机的 Agent 在 `peer_migration_port`(默认 `9443/TCP`)之间使用 TLS 1.3、一次性票据和源证书 SHA-256 锁定进行目标拉取;该端口只提供路径隔离的 PeerMigration V3 清单和工件 Range 读取,不暴露 libvirt 或通用管理 API。
- 所有虚拟机使用宿主机能力支持的 Q35 UEFI,并明确关闭 Secure Boot。不要硬编码某个发行版的 OVMF 路径。
- 每个云镜像可配置仅首次安装执行的启动脚本。创建任务会快照脚本版本;脚本成功、失败或中断后都不会自动重放,租户不能读取或覆盖脚本正文。
- 用户购买套餐开通一台 VM;每次购买或续费生成独立预付费账期及流量额度。新建实例账单的支付期限由后台按分钟配置,只影响之后生成的开通账单;续费账单的支付截止固定为其对应实例到期时间加三天,不会因账单延迟生成而顺延。额度用尽只断网、不关机;下一已付费账期恢复网络。最终到期只断网;未支付续费账单进入三天宽限期,之后永久删除 VM 定义和面板管理的磁盘。

@ -7,7 +7,7 @@ import (
"testing"
)
func TestAgentSystemdSandboxOnlyGrantsStateAndManagedNVRAMWrites(t *testing.T) {
func TestAgentSystemdUnitMatchesHostDeployment(t *testing.T) {
servicePath := filepath.Join("..", "..", "deploy", "virt-cloud-agent.service")
contents, err := os.ReadFile(servicePath)
if err != nil {
@ -15,18 +15,25 @@ func TestAgentSystemdSandboxOnlyGrantsStateAndManagedNVRAMWrites(t *testing.T) {
}
service := string(contents)
for _, required := range []string{
"ProtectSystem=strict",
"StateDirectory=virt-agent",
"ReadWritePaths=/var/lib/virt-agent -/var/lib/libvirt/qemu/nvram",
"If nvram_directory is configured elsewhere, replace this path in a drop-in.",
"Type=simple",
"User=root",
"Group=root",
"ExecStart=/home/agent/virt-agent -config /home/agent/config.json",
"Restart=on-failure",
"RestartSec=5",
"LimitCORE=0",
"TimeoutStopSec=30",
} {
if !strings.Contains(service, required) {
t.Fatalf("agent service is missing %q", required)
}
}
for _, forbidden := range []string{"ReadWritePaths=/var/lib/libvirt", "ReadWritePaths=/srv", "ProtectSystem=false"} {
for _, forbidden := range []string{
"ProtectSystem=", "ProtectHome=", "ReadWritePaths=",
"StateDirectory=", "NoNewPrivileges=", "PrivateTmp=", "UMask=",
} {
if strings.Contains(service, forbidden) {
t.Fatalf("agent service broadens its write namespace with %q", forbidden)
t.Fatalf("agent service contains retired sandbox setting %q", forbidden)
}
}
}

@ -7,24 +7,9 @@ Wants=network-online.target
Type=simple
User=root
Group=root
ExecStart=/usr/local/sbin/virt-agent -config /etc/virt-agent/config.json
ExecStart=/home/agent/virt-agent -config /home/agent/config.json
Restart=on-failure
RestartSec=5
UMask=0077
# UMask/StateDirectoryMode only harden newly created files; the binary does
# not audit the owner, group, or mode of its readable JSON configuration.
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
StateDirectory=virt-agent
StateDirectoryMode=0700
# The Agent normally writes only its Bolt journal and traffic state. The
# standard libvirt NVRAM directory is also writable so reconciliation can
# remove a UUID-owned VARS file left after a domain definition disappeared.
# The leading '-' keeps the unit portable when this distro path is absent.
# If nvram_directory is configured elsewhere, replace this path in a drop-in.
ReadWritePaths=/var/lib/virt-agent -/var/lib/libvirt/qemu/nvram
LimitCORE=0
TimeoutStopSec=30

@ -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 /home/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 必须显示不可用,不能回退旧实现。

Loading…
Cancel
Save