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/MULTI_PUBLIC_IPV4_POOLS.md

4.6 KiB

单宿主机多公网 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,待面板账本中的占用清空后再做前向清理;不要直接删库或复用地址。
  • 代码回退不等于数据回退:数据库版本、面板账本和引擎运行配置可能已经前进。回滚前备份业务库及引擎密钥/记录;优先用前向修复恢复同一版本的幂等状态。