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

49 lines
4.6 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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