# 单宿主机多公网 IPv4 地址池 ## 当前范围 一台独占宿主机可以配置最多 32 个互不重叠的实际公网 IPv4 CIDR。每个 CIDR 独立保存网关、1~4 个 DNS、客户机前缀、保留地址和运行状态;CIDR 与客户机前缀范围为 `/24`~`/30`,客户机前缀不能比地址池前缀更长。 当前阶段是一条手工准备好的 bridge、一个资源池成员关系和多个公网池。多线路、VLAN、路由表及实例迁移需要另行设计。 ## 权威数据与状态 | 对象 | 作用 | | --- | --- | | `cloud_host_network_attachments` | 面板保存宿主机、线路和 `default_network` 的接入身份 | | `cloud_public_ip_pools` | 面板保存池配置、期望/已应用版本和应用状态 | | `cloud_public_ips` | 面板唯一的具体 IP 账本,保存可用、预留、分配和不确定状态 | | 私有引擎公网池目录 | 只保存面板下发的运行配置,并在创建/换 IP 时做最终参数校验 | 面板是调度、容量、reservation 和 IP 可售状态的唯一事实源。引擎不再向面板提供宿主机容量或 IP 盘点结果;宿主机连接仅用于配置网络、执行 VM 操作和对当前操作做最终校验。IP 分配使用面板账本与引擎原子 claim,不在每次创建时枚举宿主机全部虚拟机。 从旧版本升级时,先备份业务库并停止销售,再运行 `php xcat cloudInit`。旧实例若没有 reservation,首次物化地址池会从 `cloud_instances.spec_json` 迁入仍有效的公网地址和资源规格;无法解析、重复或缺少资源字段的记录会进入未知/不确定状态并 fail-closed。管理宿主机的 IPv4 必须显式加入 `reserved_ips`,引擎不会通过扫描自动发现并保留它。面板账本之外手工创建的客户地址不会被系统发现,独占宿主机和预配置 bridge 是当前版本前提。 地址池状态: - `active`:允许从面板 IP 账本分配新地址。 - `draining`:停止新分配,保留现有实例和任务。 - `disabled`:停止新分配,不自动释放已有占用。 应用状态:`pending` 表示已经写入面板、等待引擎确认,`applied` 表示响应与版本匹配且面板已物化 IP 账本,`failed` 表示引擎明确拒绝,`uncertain` 表示网络或业务库无法确认结果,`never` 表示尚未提交。调度器不依赖宿主机扫描或新鲜度标记。 ## 配置与幂等顺序 1. 更新代码和依赖后,在停写维护窗口运行 `php xcat cloudInit`,再重启引擎、worker 与 lifecycle。 2. 添加宿主机并验证 SSH 指纹,设置地区、目录和唯一 `default_network`;桥接网络由管理员预先在宿主机准备好。 3. 在“资源调度”中加入资源池,填写 CPU、内存、磁盘、安全余量和最大实例数。面板用这些策略减去 reservation/IP 账本计算剩余资源。 4. 在“公网地址池”逐个添加实际 CIDR。创建使用稳定 `request_key`,它确定性映射到池标识;更新使用页面读取的 `expected_revision`,旧表单不能覆盖新版本。 5. 面板在事务中保存配置并生成版本,然后向私有引擎提交同版本。签名响应匹配后标记 `applied`,自动物化 CIDR 中未保留的具体 IP;响应超时则标记 `uncertain`。 6. 超时后必须使用原 `request_key` 和原版本重试。引擎对同池同版本返回幂等结果,面板只把同一条记录恢复为 `applied`,不会创建第二个池或第二批 IP。 7. 用测试实例验证创建、重装、换 IP、任务失败恢复、相同 client token 重试和两个 CIDR 的实际公网连通性。 旧 `legacy-default` 只读展示,不自动迁移;检测到旧池时先停止销售、备份并按新版结构重建。 ## 失败、恢复与回滚边界 - 引擎明确拒绝时池进入 `failed`;修正输入并基于最新版本重新提交。 - 网络超时、5xx、响应不一致或业务库无法确认时进入 `uncertain`。按原 `request_key`、版本和日志中的 `operation_id` 对账,禁止换新标识盲目重复创建。 - 池中存在实例、预留、换 IP 或不确定任务时,不允许修改 CIDR、网关、DNS、客户机前缀、保留地址或网络接入;只能修改名称与运行状态。 - 停止新销售时改为 `draining` 或 `disabled`,待面板账本中的占用清空后再做前向清理;不要直接删库或复用地址。 - 代码回退不等于数据回退:数据库版本、面板账本和引擎运行配置可能已经前进。回滚前备份业务库及引擎密钥/记录;优先用前向修复恢复同一版本的幂等状态。