@ -2,22 +2,30 @@
## 范围
生命周期进程现在 会分批巡检启用的宿主机。每台宿主机的一次完整观测同时读取:
生命周期进程会分批巡检启用的宿主机。每台宿主机的一次完整观测同时读取:
- `GET /internal/v1/hosts/{id}/host/capacity`
- `GET /internal/v1/hosts/{id}/host/network-options`
两个响应均通过严格校验并在同一数据库事务提交后,才算一次成功。巡检不修改管理员资源页面、商品目录或订单调度策略。
两个响应均通过严格校验并在同一数据库事务提交后,才算一次成功。网络响应可以包含同一宿主机的多个公网 IPv4 池;每个池都必须绑定宿主机当前的 `default_network` ,且所有池归属该宿主机当前唯一权威资源池对应的线路。 巡检不修改管理员资源页面、商品目录或订单调度策略。
## 成功写入
- `cloud_host_capacity_snapshots` 更新 CPU、内存、存储原始字节数、实例数和公网 IP 聚合计数。
- `cloud_host_capacity_snapshots` 更新 CPU、内存、存储原始字节数、实例数和所有公网池的聚合计数。
- `cloud_host_network_attachments` 按网络选择器保存线路接入身份,`cloud_public_ip_pools` 按稳定 `pool_key` 保存 CIDR、网关、DNS、客户机前缀、保留地址、状态和 revision; `cloud_public_ips.public_ip_pool_id` 把具体地址绑定到所属池。
- `sync_state` 写为 `fresh` , `observed_at` 使用已校验的引擎观测时间,`last_attempt_at` 使用 PHP 本地时间。
- 引擎返回的具体 `available_ips` 新建或恢复为 `available` ;上次仍为 `available` 、但本次已不在列表中的地址改为 `disabled` 。
- 引擎返回的每池 `available_ips` 新建或恢复为 `available` ;上次仍为 `available` 、但本次已不在对应池 列表中的地址改为 `disabled` 。`draining` 或 `disabled` 池不会产生新的可分配地址。
- PHP 本地已有占用或不确定状态优先于引擎的建议列表。`held`、`reserved`、`assigned`、`changing`、`uncertain` 以及其他非空闲状态都不会被巡检覆盖;带 `reservation_id` 、`instance_id` 或 `operation_id` 的行也不会被恢复为空闲。
- `cloud_hosts.health_state` 写为 `healthy` ,清除固定错误码,并且只有此时更新 `last_seen_at` 。
公网池未配置也是有效观测:容量响应必须同时报告 `configured=false` 和零计数,网络响应必须是严格的 `not_configured` 空结构;已有本地占用记录仍保留,仅旧 `available` 会变为 `disabled` 。
公网池未配置也是有效观测:容量响应必须同时报告 `configured=false` 和零计数,网络响应必须是严格的 `not_configured` 空结构;已有本地占用记录仍保留,仅旧 `available` 会变为 `disabled` 。完整的地址池模型见 [单宿主机多公网 IPv4 地址池 ](MULTI_PUBLIC_IPV4_POOLS.md )。
## 地址池状态与 revision
- `active` :允许在盘点完成后向新任务分配地址;`draining` 和 `disabled` 均停止新分配,但不会抹掉现有实例、任务或账本身份。
- 管理员每次有效修改递增该池的 `desired_revision` ,引擎观测写入 `observed_revision` 。写请求成功后仍为 `pending` ;只有完整盘点观察到相同或更新 revision, 池及其网络接入才可进入 `fresh` 。
- 调度器只选择 `active + fresh` 、`observed_revision >= desired_revision` 的网络接入、地址池和 `available` 地址。旧观测、失败观测或尚未核对的配置一律 fail closed, 不按“最后看见的空闲 IP”继续销售。
- 更新接口使用 `expected_revision` 做比较并交换;管理员页面持有的旧版本不能静默覆盖另一个管理员刚保存的配置。
## 失败语义
@ -36,19 +44,20 @@
## 并发与锁顺序
成功同步按 `cloud_hosts` → `cloud_host_capacity_snapshots` → 当前宿主机 `cloud_public_ips` 加锁。调度器同样先锁 `cloud_hosts` ,再锁 `cloud_host_capacity_policies` → snapshot → IP; 以宿主机行为共同入口, 避免与管理员策略修改形成 反向等待。同步不会锁定其他宿主机的 IP 行;跨宿主地址冲突先只读检查,最终仍由全局唯一地址索引阻止竞态插入。
成功同步以 `cloud_hosts` 为宿主机级哨兵,之后依次锁定 `cloud_host_capacity_snapshots` → 资源池成员关系 → `cloud_host_network_attachments` → `cloud_public_ip_pools` → 当前宿主机 `cloud_public_ips` ,同组内按主键顺序。调度与管理员配置也先锁宿主机行,再按各自所需的相同相对顺序锁资源策略、快照、网络身份和具体 IP, 避免 反向等待。同步不会锁定其他宿主机的 IP 行;跨宿主地址冲突先只读检查,最终仍由全局唯一地址索引阻止竞态插入。
## 生命周期与身份
- daemon 单轮最多检查 10 台启用宿主机,只选择到期宿主机;默认同一宿主机至少间隔 30 秒,可用 `cloud_host_inventory_interval_seconds` 配置为 30~ 300 秒。到期队列优先选择从未检查或 `health_checked_at` 最旧的宿主机,避免固定低 ID 饥饿,并控制顺序引擎请求对生命周期主循环的占用。
- 管理员精确刷新单台宿主机时调用 `CloudHostInventorySyncService::syncOne($hostId)` ;它跳过到期窗口,但复用完全相同的 daemon actor、双响应校验、事务和失败标记, 不另开宽松路径。
- 管理员保存公网池后不会在写请求内把账本伪装为已同步:配置先保持 `pending` ,随后可由上述 daemon 自动盘点,或由“资源调度 → 手动同步”立即触发同一条 `syncOne` 路径。手动同步失败也不会回退或清空最后一次有效容量。
- heartbeat 新增阶段 `host_inventory_sync` ,对外错误仅为 `host_inventory_sync_failed` 或 `host_inventory_sync_unconfigured` 。
- `CloudDaemonActor` 统一解析已启用的配置超级管理员;宿主库存同步和实例运行状态同步不再各自复制 daemon 权限逻辑。
## 验证资产与边界
- `CloudHostInventorySyncServiceTest.php` : SQLite + Guzzle mock 行为测试, 覆盖双端点成功、容量字节精度、IP 状态保留/禁用/恢复、共享 daemon actor、到期过滤、单宿主机精确刷新、无效响应保留最后快照、临时失败状态与原始错误不落库。
- `CloudHostInventorySyncServiceTest.php` : SQLite + Guzzle mock 行为测试,覆盖双端点成功、多池身份与 revision、 容量字节精度、IP 状态保留/禁用/恢复、共享 daemon actor、到期过滤、单宿主机精确刷新、无效响应保留最后快照、临时失败状态与原始错误不落库。
- `CloudHostInventorySyncContractTest.php` : 无需数据库和引擎的静态边界测试, 覆盖生命周期接线、heartbeat、共享 actor、失败不清空和固定诊断码。
- 当前开发机没有 PHP CLI, 无法在此环境执行上述 PHP 测试或 `php -l` ;部署/CI 的 PHP 8.5 环境仍须实际运行两个测试,并建议连同 `CloudRuntimeHeartbeatTest.php` 回归 。
- 部署/CI 的 PHP 8.5 环境必须实际运行上述测试,并连同 `CloudRuntimeHeartbeatTest.php` 、公网池与调度合同测试回归;静态合同通过不替代真实 MariaDB 与宿主网络验收 。
上线前必须先运行 `php xcat cloudInit` 创建新增表/列,再重启 lifecycle 进程。真实引擎联调还应验证一个已配置地址池和一个未配置地址池 ;测试发布不代表生产宿主机已验收。
上线前必须先运行 `php xcat cloudInit` 创建新增表/列,再重启引擎与 lifecycle 进程。真实引擎联调至少应验证同一宿主机的两个不重叠地址池、一个 `draining` 池、一个未配置地址池,以及 revision 冲突和盘点失败 ;测试发布不代表生产宿主机已验收。当前仍是每台宿主机一个 `default_network` 和一条权威线路,真正的单宿主机多线路属于后续阶段。