diff --git a/docs/INTEGRATION_PLAN.md b/docs/INTEGRATION_PLAN.md
index 6d697de4..2777859d 100644
--- a/docs/INTEGRATION_PLAN.md
+++ b/docs/INTEGRATION_PLAN.md
@@ -33,6 +33,46 @@ PHP 是唯一账户入口,所有用户页面使用原虚拟化面板 CSS;后
当前网络模型有意保持一条权威路径:每台宿主机只有一个 `default_network`,并通过唯一有效的资源池成员关系归属一条线路;多个公网 CIDR 共享该网络接入。线路管理和数据表为未来扩展保留,但“同一宿主机同时销售多条线路”尚未开放。该阶段必须增加多个资源池成员/网络接入选择、bridge/VLAN/路由表验证、逐线路容量以及实例跨接入迁移策略,不能仅给现有公网池补一个线路下拉框。
+### VPC 接入前置契约
+
+VPC 的第一版地址池由 PHP 从全局、可配置的 RFC1918 地址池分配(默认
+`10.0.0.0/8`)。分配记录保留
+`state/revision` 生命周期和释放历史;并发请求不使用新的全局应用锁,而是在一个
+事务中抢占候选 CIDR 包含的 `/24` quantum 行。每个 quantum 的唯一键是跨
+worker 的冲突点,冲突后重新读取账本并重试;因此不同候选块可以并发,重叠
+候选不能同时提交。实例地址继续使用精确 `/32`,不把公网地址池或 `br0`
+复用为私网地址池。
+
+宿主机测试会通过固定、只读的 SSH 探测返回能力快照:系统发行版/版本、
+`ip`/`wg`/`nft` 工具路径、WireGuard 内核模块、bridge、网络管理器、IPv4
+转发、`rp_filter` 和防火墙规则所有者。AlmaLinux 10 预期走 `dnf` 与
+NetworkManager,Debian 13 预期走 `apt` 与 systemd-networkd;探测只识别
+现状,不在租户请求中安装包、加载模块或修改规则。缺少能力时旧公网 VM
+路径仍可保存宿主机,但 VPC 控制器必须要求 `vpc_ready=true`,否则拒绝
+创建或变更私网。
+
+云初始化和 libvirt XML 使用显式角色:公网网卡是 `public0`,私网网卡是
+`private0`。公网静态 IPv4 保留唯一默认路由;私网只接受 RFC1918 `/32`,
+关闭 DHCP/RA 且不带 gateway、DNS 或路由。旧的单网卡域可按兼容规则视为
+公网,带多网卡但没有角色别名的域一律停止安全策略操作。面板的
+`clean-traffic`/`vc-fw-*` nwfilter 只能绑定 `public0`;私网 ACL 属于后续
+独立的 WireGuard/L3 nftables 上下文,不能把公网过滤器复制到私网网卡。
+
+宿主机数据面预留独立的 `wg-fabric0`。首次探测到一个没有面板所有权标记的同名
+接口时必须停止私网接入;后续 reconciler 只有在固定的
+`/etc/virt-cloud/wg-fabric0.owner` 标记为 `virt-cloud-wg-fabric-v1` 后才可认领
+已有接口,避免重启后的能力刷新把面板自己创建的链路误判为外部冲突。它只承载宿主机间的加密传输;公网
+`br0` 仍是外部接入,私网桥/tap、精确路由、AllowedIPs 和租户 ACL 由后续
+VPC reconciler 单独管理。私网 libvirt 网卡在该阶段只接受已核验的独立
+bridge/tap/device 来源,不接受无法确认底层桥接的 `network=` 间接来源;公网
+nwfilter 与私网 ACL 永远是两套策略上下文。WireGuard 能力探测通过不改变系统的命令完成,
+真正的 AlmaLinux/Debian 部署、SELinux/firewalld 共存和跨宿主机连通性仍须
+在验收环境验证。
+
+本阶段只落地 PHP 的地址分配账本、引擎的只读能力快照和公私网契约,尚未接入
+用户 VPC API,也不会因为 `vpc_ready=true` 自动创建 WireGuard、路由或 nftables
+规则;后续控制面必须在每次下发前重新核对能力和资源版本。
+
PHP 不直接解密 Python 记录或执行任意 virsh 命令。主库与日志库可同实例或分别配置地址/端口。敏感业务数据加密;部署数据库连接配置仍是权限受限配置文件,不代表配置文件本身加密。
在线更新同样遵守这条边界:PHP 仅做超级管理员授权、CSRF 和固定路径代理;Gitea 令牌由私有引擎写入加密 `engine_records`,Git 快进、幂等升级及现有服务重启只由按需启动的 root `virt-cloud-update.service` 执行。仓库和 `venix` 分支均不可由浏览器修改,更新仅允许干净工作树上的 fast-forward。在线流程不运行 Composer/pip、不建立依赖暂存区、不改写 systemd unit;目标提交一旦修改 `engine/requirements.txt`、`web/composer.json`、`web/composer.lock` 或 `deploy/**`,必须在停服与切换前拒绝并改走 SSH 升级。工作器以持久检查点区分“代码已切换但数据库未确认”、“数据库正在迁移”与“数据库已就绪”;不安全的中断进入 `blocked` 并保留维护锁,不会在兼容性未知时自动启动服务。特别是进入 `schema_migrating` 后,MariaDB DDL 可能已部分提交,仅回退源码不足以解除维护锁。
diff --git a/engine/tests/test_cloud_init.py b/engine/tests/test_cloud_init.py
index a961aaa5..b06d0ba1 100644
--- a/engine/tests/test_cloud_init.py
+++ b/engine/tests/test_cloud_init.py
@@ -15,7 +15,8 @@ from virsh_panel.cloud_init import (
generate_root_password,
hash_root_password,
read_seed_network, replace_seed_network, replace_seed_settings,
- validate_cloud_network, validate_guest_hostname,
+ validate_cloud_network, validate_guest_hostname, validate_private_network,
+ _parse_network_config,
)
@@ -191,6 +192,86 @@ def test_public_network_rejects_bad_dns_and_ssh_key(dns, key):
validate_cloud_network("8.8.8.18/24", "8.8.8.1", dns, key)
+def test_private_network_is_an_explicit_static_role_without_a_default_route():
+ assert validate_private_network("10.24.3.7/32") == {
+ "private_ip_cidr": "10.24.3.7/32",
+ }
+ config = {
+ "version": 2,
+ "ethernets": {
+ "public0": {
+ "match": {"macaddress": "52:54:00:12:34:56"},
+ "dhcp4": False,
+ "dhcp6": False,
+ "addresses": ["8.8.8.18/28"],
+ "routes": [{"to": "0.0.0.0/0", "via": "8.8.8.17"}],
+ "nameservers": {"addresses": ["1.1.1.1"]},
+ },
+ "private0": {
+ "match": {"macaddress": "52:54:00:12:34:57"},
+ "dhcp4": False,
+ "dhcp6": False,
+ "accept-ra": False,
+ "addresses": ["10.24.3.7/32"],
+ },
+ },
+ }
+ parsed = _parse_network_config(config)
+ assert parsed["roles"] == ["public0", "private0"]
+ assert parsed["private_ip_cidr"] == "10.24.3.7/32"
+ with pytest.raises(ValueError, match="无默认路由"):
+ _parse_network_config({
+ **config,
+ "ethernets": {
+ **config["ethernets"],
+ "private0": {
+ **config["ethernets"]["private0"],
+ "routes": [{"to": "0.0.0.0/0", "via": "10.24.3.1"}],
+ },
+ },
+ })
+
+
+@pytest.mark.parametrize("value", [
+ "10.24.3.7/31", "127.0.0.1/32", "169.254.1.1/32",
+ "192.0.2.1/32", "2001:db8::1/128",
+])
+def test_private_network_rejects_non_rfc1918_guest_endpoints(value):
+ with pytest.raises(ValueError):
+ validate_private_network(value)
+
+
+@pytest.mark.skipif(importlib.util.find_spec("pycdlib") is None,
+ reason="pycdlib is not installed")
+def test_seed_iso_can_add_private_role_without_public_route_or_dns():
+ validated = validate_cloud_network(
+ "8.8.8.18/28", "8.8.8.17", ["1.1.1.1"], PUBLIC_KEY,
+ )
+ seed = build_seed_iso(
+ str(uuid.uuid4()), "multi-nic-vm", "52:54:00:12:34:56", validated,
+ private_mac="52:54:00:12:34:57",
+ private_network={"private_ip_cidr": "10.24.3.7/32"},
+ )
+ network = _network_data(seed)
+ assert set(network["ethernets"]) == {"public0", "private0"}
+ assert network["ethernets"]["private0"] == {
+ "match": {"macaddress": "52:54:00:12:34:57"},
+ "dhcp4": False,
+ "dhcp6": False,
+ "accept-ra": False,
+ "addresses": ["10.24.3.7/32"],
+ }
+ assert read_seed_network(seed) == {
+ "public_ip_cidr": "8.8.8.18/28",
+ "gateway": "8.8.8.17",
+ "dns_servers": ["1.1.1.1"],
+ "mac": "52:54:00:12:34:56",
+ "private_ip_cidr": "10.24.3.7/32",
+ "private_mac": "52:54:00:12:34:57",
+ "roles": ["public0", "private0"],
+ }
+
+
@pytest.mark.skipif(importlib.util.find_spec("pycdlib") is None,
reason="pycdlib is not installed")
def test_seed_iso_has_nocloud_files_and_mac_specific_static_network():
diff --git a/engine/tests/test_libvirt_service.py b/engine/tests/test_libvirt_service.py
index 4cc95341..1cf429f4 100644
--- a/engine/tests/test_libvirt_service.py
+++ b/engine/tests/test_libvirt_service.py
@@ -843,6 +843,32 @@ class VMServiceTests(unittest.TestCase):
"52:54:00:12:34:56", "8.8.8.18/24")
self.assertIsNotNone(ET.fromstring(cloud_xml).find("./devices/interface/bandwidth"))
+ def test_private_seed_role_requires_explicit_separate_source(self):
+ public = ET.fromstring(
+ ""
+ ""
+ )
+ private = ET.fromstring(
+ ""
+ ""
+ )
+ network = {"private_ip_cidr": "10.24.3.7/32",
+ "private_mac": "52:54:00:12:34:57"}
+ self.assertEqual(
+ self.service_module.VMService._assert_seed_private_network_matches_interfaces(
+ [public, private], network, public_bridge="br0", public_network="default",
+ ),
+ network,
+ )
+ indirect = ET.fromstring(
+ ""
+ ""
+ )
+ with self.assertRaises(self.service_module.VMError):
+ self.service_module.VMService._assert_seed_private_network_matches_interfaces(
+ [public, indirect], network, public_bridge="br0", public_network="default",
+ )
+
def test_bridge_cloud_xml_binds_platform_wrapper_to_public_ip(self):
service = self.cloud_service()
vm_id = "00000000-0000-4000-8000-000000000001"
diff --git a/engine/tests/test_network_roles.py b/engine/tests/test_network_roles.py
new file mode 100644
index 00000000..4948eb1a
--- /dev/null
+++ b/engine/tests/test_network_roles.py
@@ -0,0 +1,110 @@
+"""Network-role and public-filter boundary contracts."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+
+import pytest
+
+from virsh_panel.network_roles import (
+ assert_public_interface,
+ interface_role,
+ private_interface_has_public_filter,
+ select_private_interface,
+ select_public_interface,
+)
+
+
+def test_explicit_roles_do_not_depend_on_xml_order():
+ public = ET.fromstring(
+ ""
+ )
+ private = ET.fromstring(
+ ""
+ )
+ assert interface_role(public) == "public"
+ assert interface_role(private) == "private"
+ assert_public_interface(public)
+ with pytest.raises(ValueError):
+ assert_public_interface(private)
+
+
+def test_unlabelled_multi_nic_is_ambiguous_and_private_filter_is_rejected():
+ unlabelled = ET.fromstring(
+ ""
+ )
+ assert interface_role(unlabelled) == "unknown"
+ assert private_interface_has_public_filter(unlabelled)
+ with pytest.raises(ValueError):
+ assert_public_interface(unlabelled)
+
+
+def test_explicit_public_with_unlabelled_second_nic_fails_closed():
+ public = ET.fromstring(
+ ""
+ )
+ unknown = ET.fromstring("")
+ with pytest.raises(ValueError, match="声明"):
+ select_public_interface([public, unknown])
+
+
+def test_explicit_public_private_pair_selects_public_interface():
+ public = ET.fromstring("")
+ private = ET.fromstring("")
+ assert select_public_interface([private, public]) is public
+
+
+def test_legacy_single_public_nic_can_still_be_updated():
+ legacy = ET.fromstring("")
+ assert interface_role(legacy) == "unknown"
+ assert interface_role(legacy, legacy_public=True) == "public"
+ assert_public_interface(legacy, legacy_public=True)
+
+ generated = ET.fromstring(
+ ""
+ )
+ assert interface_role(generated) == "unknown"
+ assert select_public_interface([generated]) is generated
+ assert_public_interface(generated, legacy_public=True)
+
+ renamed = ET.fromstring(
+ ""
+ )
+ with pytest.raises(ValueError):
+ select_public_interface([renamed])
+
+
+def test_private_selection_requires_one_explicit_private_role():
+ private = ET.fromstring(
+ ""
+ )
+ public = ET.fromstring(
+ ""
+ )
+ assert select_private_interface([public, private]) is private
+ assert select_private_interface([public]) is None
+ with pytest.raises(ValueError):
+ select_private_interface([private, ET.fromstring(
+ "")])
+
+
+@pytest.mark.parametrize("alias", ["net0", "ua-net-0"])
+def test_libvirt_generated_single_nic_alias_is_legacy_public(alias):
+ legacy = ET.fromstring(
+ f""
+ )
+ assert interface_role(legacy) == "unknown"
+ assert interface_role(legacy, legacy_public=True) == "public"
+ assert select_public_interface([legacy]) is legacy
+ assert_public_interface(legacy, legacy_public=True)
+
+
+def test_generated_alias_is_not_guessed_in_a_multi_nic_domain():
+ public = ET.fromstring(
+ ""
+ )
+ legacy = ET.fromstring(
+ ""
+ )
+ with pytest.raises(ValueError, match="声明"):
+ select_public_interface([public, legacy])
diff --git a/engine/tests/test_remote_host.py b/engine/tests/test_remote_host.py
index f6070e42..588a0077 100644
--- a/engine/tests/test_remote_host.py
+++ b/engine/tests/test_remote_host.py
@@ -17,9 +17,15 @@ from urllib.parse import parse_qs, urlsplit
import pytest
from virsh_panel.remote_host import (
+ HOST_CAPABILITY_SCHEMA_VERSION,
+ WG_FABRIC_INTERFACE,
+ WG_FABRIC_OWNERSHIP_MARKER,
+ _CAPABILITY_MARKER,
+ _CAPABILITY_PROBE_COMMAND,
HostProfile,
RemoteHostError,
RemoteHostManager,
+ parse_host_capabilities,
)
from virsh_panel.ssh_agent import SSHAgentError
@@ -37,6 +43,63 @@ def host_key(seed: bytes) -> str:
PRIVATE_KEY = "-----BEGIN OPENSSH PRIVATE KEY-----\nZmFrZQ==\n-----END OPENSSH PRIVATE KEY-----\n"
+CAPABILITY_OUTPUT = f"""{_CAPABILITY_MARKER}
+__VCAP_OS_BEGIN__
+ID=almalinux
+NAME="AlmaLinux"
+VERSION_ID="10.0"
+__VCAP_OS_END__
+__VCAP_KERNEL_BEGIN__
+6.12.0-alma
+__VCAP_KERNEL_END__
+__VCAP_TOOL__wg=/usr/bin/wg
+__VCAP_TOOL__wg_quick=/usr/bin/wg-quick
+__VCAP_TOOL__ip=/usr/sbin/ip
+__VCAP_TOOL__nft=/usr/sbin/nft
+__VCAP_TOOL__nmcli=/usr/bin/nmcli
+__VCAP_TOOL__networkctl=
+__VCAP_TOOL__systemctl=/usr/bin/systemctl
+__VCAP_TOOL__modinfo=/usr/sbin/modinfo
+__VCAP_TOOL__dnf=/usr/bin/dnf
+__VCAP_TOOL__apt_get=
+__VCAP_MODULE__wireguard=loaded
+__VCAP_MODULE_FILE_BEGIN__
+
+__VCAP_MODULE_FILE_END__
+__VCAP_FABRIC_OWNER_BEGIN__
+__VCAP_FABRIC_OWNER_END__
+__VCAP_SYSCTL__ip_forward=1
+__VCAP_SYSCTL__rp_filter=2
+__VCAP_SYSCTL__rp_filter_default=2
+__VCAP_RPF__br0=2
+__VCAP_SERVICE__network_manager=active
+__VCAP_SERVICE__networkd=inactive
+__VCAP_SERVICE__firewall=inactive
+__VCAP_SERVICE__nftables=active
+__VCAP_IP_BEGIN__links
+[{{"ifname":"br0"}}]
+__VCAP_IP_END__links=0
+__VCAP_IP_BEGIN__bridges
+[{{"ifname":"br0"}}]
+__VCAP_IP_END__bridges=0
+__VCAP_IP_BEGIN__wireguard
+[]
+__VCAP_IP_END__wireguard=0
+__VCAP_NFT_BEGIN__
+[{{"family":"inet","name":"filter"}}]
+__VCAP_NFT_END__0
+__VCAP_END__
+"""
+
+
+def test_capability_probe_command_is_parseable_by_posix_sh():
+ result = subprocess.run(
+ ["/bin/sh", "-n", "-c", _CAPABILITY_PROBE_COMMAND],
+ capture_output=True, text=True, check=False,
+ )
+ assert result.returncode == 0, result.stderr
+
+
class Runner:
def __init__(self) -> None:
self.key = host_key(b"a")
@@ -57,6 +120,8 @@ class Runner:
return subprocess.CompletedProcess(argv, 255, "", "passphrase required")
return subprocess.CompletedProcess(argv, 0, f"{self.public_key_type} fake-public-key\n", "")
if argv[0] == "ssh":
+ if _CAPABILITY_MARKER in argv[-1]:
+ return subprocess.CompletedProcess(argv, 0, CAPABILITY_OUTPUT, "")
return subprocess.CompletedProcess(argv, self.ssh_exit, "", "permission denied")
raise AssertionError(argv)
@@ -387,7 +452,18 @@ def test_stage_test_commit_writes_private_pinned_ssh_config(tmp_path):
wrapper = stage.path / "ssh-wrapper"
assert stat.S_IMODE(wrapper.stat().st_mode) == 0o700
assert parse_qs(urlsplit(stage.libvirt_uri).query)["command"] == [str(wrapper)]
- assert manager.test(stage) == {"ok": True, "ssh": "connected", "libvirt": "available"}
+ tested = manager.test(stage)
+ assert tested["ok"] is True
+ assert tested["ssh"] == "connected"
+ assert tested["libvirt"] == "available"
+ assert tested["capabilities"]["schema_version"] == HOST_CAPABILITY_SCHEMA_VERSION
+ assert tested["capabilities"]["vpc_ready"] is True
+ assert tested["capabilities"]["os"]["package_tool"] == "dnf"
+ assert tested["capabilities"]["os"]["package_tool_available"] is True
+ assert tested["capabilities"]["wireguard"]["deployment_mode"] == "direct_ip_wg"
+ assert tested["capabilities"]["network"]["rp_filter_default"] == 2
+ assert tested["capabilities"]["network"]["rp_filter_interfaces"]["br0"] == 2
+ assert tested["capabilities"]["network_roles"]["private"]["host_interface"] == WG_FABRIC_INTERFACE
assert runner.commands[-1][0:4] == ["ssh", "-F", stage.ssh_config_file, "-T"]
current = manager.commit(stage)
assert current["host"] == "host.example"
@@ -407,6 +483,144 @@ def test_stage_test_commit_writes_private_pinned_ssh_config(tmp_path):
assert stat.S_IMODE(manager.ssh_user_config_path.parent.stat().st_mode) == 0o700
+def test_capability_snapshot_is_persisted_only_after_commit(tmp_path):
+ runner = Runner()
+ manager = make_manager(tmp_path, runner)
+ scanned = manager.scan("host.example", 2222)
+ staged = manager.stage(make_profile(scanned), scanned["fingerprint"])
+ tested = manager.test(staged)
+ assert tested["capabilities"]["os"]["id"] == "almalinux"
+ profile_before = json.loads((staged.path / "profile.json").read_text())
+ assert "capabilities" not in profile_before
+ current = manager.commit(staged)
+ assert current["capabilities"]["vpc_ready"] is True
+ profile_after = json.loads((staged.path / "profile.json").read_text())
+ assert profile_after["capabilities"]["wireguard"]["interface"] == WG_FABRIC_INTERFACE
+
+
+def test_capability_probe_rejects_missing_private_plane_evidence():
+ output = CAPABILITY_OUTPUT.replace(
+ "__VCAP_TOOL__wg=/usr/bin/wg", "__VCAP_TOOL__wg=",
+ ).replace(
+ "__VCAP_SERVICE__nftables=active", "__VCAP_SERVICE__nftables=inactive",
+ ).replace(
+ "__VCAP_SYSCTL__ip_forward=1", "__VCAP_SYSCTL__ip_forward=0",
+ )
+ capabilities = parse_host_capabilities(output, public_network="bridge:br0")
+ assert capabilities["probe_valid"] is True
+ assert capabilities["private_ready"] is False
+ assert capabilities["vpc_ready"] is False
+ assert "wireguard_tool_missing" in capabilities["reasons"]
+ assert "firewall_owner_not_nftables" in capabilities["reasons"]
+ assert "ipv4_forwarding_disabled_or_unknown" in capabilities["reasons"]
+ assert capabilities["network_roles"]["private"]["separate_from_public"] is True
+
+
+def test_capability_probe_rejects_preexisting_fabric_interface():
+ output = CAPABILITY_OUTPUT.replace(
+ '[{"ifname":"br0"}]',
+ '[{"ifname":"br0"},{"ifname":"wg-fabric0"}]',
+ 1,
+ ).replace(
+ "__VCAP_IP_BEGIN__wireguard\n[]",
+ '__VCAP_IP_BEGIN__wireguard\n[{"ifname":"wg-fabric0"}]',
+ )
+ capabilities = parse_host_capabilities(output, public_network="bridge:br0")
+ assert capabilities["vpc_ready"] is False
+ assert "wireguard_fabric_interface_conflict" in capabilities["reasons"]
+
+
+def test_capability_probe_rejects_reserved_name_used_by_non_wireguard_link():
+ output = CAPABILITY_OUTPUT.replace(
+ '[{"ifname":"br0"}]',
+ '[{"ifname":"br0"},{"ifname":"wg-fabric0"}]',
+ 1,
+ )
+ capabilities = parse_host_capabilities(output, public_network="bridge:br0")
+ assert capabilities["vpc_ready"] is False
+ assert capabilities["wireguard"]["interface_name_reserved"] is True
+ assert capabilities["wireguard"]["interface_is_wireguard"] is False
+ assert "wireguard_fabric_interface_conflict" in capabilities["reasons"]
+
+
+def test_capability_probe_accepts_panel_owned_fabric_interface():
+ output = CAPABILITY_OUTPUT.replace(
+ '[{"ifname":"br0"}]',
+ '[{"ifname":"br0"},{"ifname":"wg-fabric0"}]',
+ 1,
+ ).replace(
+ "__VCAP_IP_BEGIN__wireguard\n[]",
+ '__VCAP_IP_BEGIN__wireguard\n[{"ifname":"wg-fabric0"}]',
+ ).replace(
+ "__VCAP_FABRIC_OWNER_BEGIN__\n__VCAP_FABRIC_OWNER_END__",
+ "__VCAP_FABRIC_OWNER_BEGIN__\n"
+ + WG_FABRIC_OWNERSHIP_MARKER
+ + "\n__VCAP_FABRIC_OWNER_END__",
+ )
+ capabilities = parse_host_capabilities(output, public_network="bridge:br0")
+ assert capabilities["vpc_ready"] is True
+ assert capabilities["wireguard"]["owned_by_panel"] is True
+
+
+def test_capability_probe_requires_selected_bridge_rp_filter_evidence():
+ capabilities = parse_host_capabilities(
+ CAPABILITY_OUTPUT.replace("__VCAP_RPF__br0=2", ""),
+ public_network="bridge:br0",
+ )
+ assert capabilities["network_roles"]["public"]["verified"] is True
+ assert capabilities["private_ready"] is False
+ assert "rp_filter_not_compatible" in capabilities["reasons"]
+
+
+def test_capability_probe_fails_closed_when_protocol_section_is_missing():
+ capabilities = parse_host_capabilities(
+ CAPABILITY_OUTPUT.replace("__VCAP_NFT_BEGIN__\n", ""),
+ public_network="bridge:br0",
+ )
+ assert capabilities["probe_valid"] is False
+ assert capabilities["vpc_ready"] is False
+ assert "capability_probe_invalid" in capabilities["reasons"]
+
+
+def test_capability_probe_fails_closed_on_malformed_ip_json():
+ capabilities = parse_host_capabilities(
+ CAPABILITY_OUTPUT.replace(
+ '[{"ifname":"br0"}]', '[{"ifname":42}]', 1,
+ ),
+ public_network="default",
+ )
+ assert capabilities["network"]["ip_probe_valid"] is False
+ assert capabilities["vpc_ready"] is False
+ assert "iproute2_probe_failed" in capabilities["reasons"]
+
+
+def test_capability_probe_supports_debian_networkd_contract():
+ output = CAPABILITY_OUTPUT.replace("ID=almalinux", "ID=debian").replace(
+ 'NAME="AlmaLinux"', 'NAME="Debian GNU/Linux"',
+ ).replace('VERSION_ID="10.0"', 'VERSION_ID="13"').replace(
+ "__VCAP_TOOL__nmcli=/usr/bin/nmcli", "__VCAP_TOOL__nmcli=",
+ ).replace(
+ "__VCAP_TOOL__apt_get=", "__VCAP_TOOL__apt_get=/usr/bin/apt-get",
+ ).replace(
+ "__VCAP_TOOL__networkctl=", "__VCAP_TOOL__networkctl=/usr/bin/networkctl",
+ ).replace(
+ "__VCAP_SERVICE__network_manager=active", "__VCAP_SERVICE__network_manager=inactive",
+ ).replace(
+ "__VCAP_SERVICE__networkd=inactive", "__VCAP_SERVICE__networkd=active",
+ )
+ capabilities = parse_host_capabilities(output)
+ assert capabilities["os"]["id"] == "debian"
+ assert capabilities["os"]["name"] == "Debian GNU/Linux"
+ assert capabilities["os"]["version_id"] == "13"
+ assert capabilities["os"]["family"] == "debian"
+ assert capabilities["os"]["package_manager"] == "apt"
+ assert capabilities["os"]["package_tool"] == "apt_get"
+ assert capabilities["os"]["package_tool_available"] is True
+ assert capabilities["os"]["supported"] is True
+ assert capabilities["network"]["network_manager"] == "systemd_networkd"
+ assert capabilities["vpc_ready"] is True
+
+
def test_rejects_unconfirmed_or_changed_host_key(tmp_path):
runner = Runner()
manager = make_manager(tmp_path, runner)
diff --git a/engine/virsh_panel/app.py b/engine/virsh_panel/app.py
index 58d780e9..b5fd5bec 100644
--- a/engine/virsh_panel/app.py
+++ b/engine/virsh_panel/app.py
@@ -520,7 +520,7 @@ def _public_host(profile: dict | None) -> dict:
"iso_pool", "default_network", "private_key_configured",
"private_key_encrypted", "key_locked", "private_key_passphrase_saved",
)
- return {
+ result = {
"configured": True,
**{key: profile[key] for key in keys if key in profile},
"rescue_iso_pool": profile.get("rescue_iso_pool", ""),
@@ -531,6 +531,15 @@ def _public_host(profile: dict | None) -> dict:
"public_reserved_ips": profile.get("public_reserved_ips", []),
"public_vm_prefix": profile.get("public_vm_prefix"),
}
+ # Capability snapshots are read-only evidence from the pinned host test.
+ # Keep the private key and raw probe output out of the public response;
+ # the normalized contract is what a future VPC controller checks before
+ # attempting WireGuard/nftables changes. Omit the field for old fake or
+ # legacy profiles so the compatibility response remains unchanged until a
+ # host has actually been tested with the new probe.
+ if "capabilities" in profile:
+ result["capabilities"] = profile["capabilities"]
+ return result
def _peer(request: Request) -> str:
diff --git a/engine/virsh_panel/cloud_init.py b/engine/virsh_panel/cloud_init.py
index c6e23dc4..37a5f641 100644
--- a/engine/virsh_panel/cloud_init.py
+++ b/engine/virsh_panel/cloud_init.py
@@ -18,6 +18,11 @@ import uuid
from io import BytesIO
from typing import Any
+from virsh_panel.network_roles import (
+ PRIVATE_INTERFACE_ALIAS,
+ PUBLIC_INTERFACE_ALIAS,
+)
+
_VM_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,62}\Z")
# Linux host names are case-insensitive DNS labels. Keep the panel contract
@@ -280,6 +285,140 @@ def validate_cloud_network(
return result
+def validate_private_network(private_ip_cidr: Any) -> dict[str, str]:
+ """Validate one L3 VPC guest address.
+
+ VPC members are routed as host/guest ``/32`` endpoints. They do not get
+ a default route or a provider gateway from this function; those routes are
+ owned by the host dataplane and are added only after the VPC ACL/readback
+ barrier succeeds.
+ """
+ if (not isinstance(private_ip_cidr, str)
+ or not private_ip_cidr
+ or private_ip_cidr != private_ip_cidr.strip()):
+ raise ValueError("私网 IP 必须采用 IPv4 地址/32 格式")
+ try:
+ interface = ipaddress.ip_interface(private_ip_cidr)
+ except ValueError as exc:
+ raise ValueError("私网 IP/CIDR 格式无效") from exc
+ if not isinstance(interface, ipaddress.IPv4Interface):
+ raise ValueError("私网一期仅支持 IPv4")
+ if interface.network.prefixlen != 32:
+ raise ValueError("私网实例地址必须使用 /32")
+ address = interface.ip
+ # ``is_private`` also includes loopback/link-local ranges, which are not
+ # valid tenant addresses. Explicitly keep the product contract to RFC1918
+ # space so a host-local or metadata address cannot be routed as a member.
+ rfc1918 = (
+ ipaddress.IPv4Network("10.0.0.0/8"),
+ ipaddress.IPv4Network("172.16.0.0/12"),
+ ipaddress.IPv4Network("192.168.0.0/16"),
+ )
+ if (not any(address in network for network in rfc1918)
+ or address.is_loopback or address.is_link_local
+ or address.is_reserved or address.is_multicast):
+ raise ValueError("私网 IP 必须是 RFC1918 IPv4 地址")
+ return {"private_ip_cidr": str(interface)}
+
+
+def _validate_network_mac(value: Any, label: str) -> str:
+ if not isinstance(value, str) or not _MAC.fullmatch(value):
+ raise ValueError(f"{label} MAC 地址无效")
+ normalized = value.lower()
+ octets = [int(part, 16) for part in normalized.split(":")]
+ if octets[0] & 1 or not any(octets):
+ raise ValueError(f"{label} MAC 地址不能是组播或全零地址")
+ return normalized
+
+
+def _parse_network_config(config: Any) -> dict[str, Any]:
+ """Parse role-aware Netplan v2 data without accepting implicit bridges."""
+ if not isinstance(config, dict) or config.get("version") != 2:
+ raise ValueError("原 cloud-init 网络配置格式无效")
+ if (set(config) - {"version", "ethernets", "renderer"}
+ or ("renderer" in config and config["renderer"] != "networkd")):
+ raise ValueError("原 cloud-init 网络配置字段不受支持")
+ ethernets = config.get("ethernets")
+ if (not isinstance(ethernets, dict)
+ or not ethernets
+ or any(key not in {PUBLIC_INTERFACE_ALIAS, PRIVATE_INTERFACE_ALIAS}
+ for key in ethernets)):
+ raise ValueError("原 cloud-init 网卡角色格式无效")
+ if PUBLIC_INTERFACE_ALIAS not in ethernets:
+ raise ValueError("原 cloud-init 网络配置缺少 public0")
+
+ public = ethernets[PUBLIC_INTERFACE_ALIAS]
+ if not isinstance(public, dict):
+ raise ValueError("原 cloud-init 公网网卡配置无效")
+ if set(public) - {
+ "match", "dhcp4", "dhcp6", "addresses", "routes",
+ "nameservers", "accept-ra",
+ }:
+ raise ValueError("原 cloud-init 公网网卡字段不受支持")
+ match = public.get("match")
+ public_mac = match.get("macaddress") if isinstance(match, dict) else None
+ if (public.get("dhcp4") is not False
+ or public.get("dhcp6") is not False
+ or ("accept-ra" in public and public.get("accept-ra") is not False)
+ or not isinstance(public.get("addresses"), list)
+ or len(public["addresses"]) != 1
+ or not isinstance(public.get("routes"), list)
+ or len(public["routes"]) != 1
+ or not isinstance(public.get("nameservers"), dict)
+ or not isinstance(match, dict)
+ or set(match) != {"macaddress"}):
+ raise ValueError("原 cloud-init 公网网卡配置无效")
+ route = public["routes"][0]
+ if (not isinstance(route, dict) or route.get("to") != "0.0.0.0/0"
+ or set(route) != {"to", "via"}
+ or not isinstance(route.get("via"), str)):
+ raise ValueError("原 cloud-init 公网默认路由无效")
+ dns = public["nameservers"].get("addresses")
+ if (set(public["nameservers"]) != {"addresses"}
+ or not isinstance(dns, list)):
+ raise ValueError("原 cloud-init 公网 DNS 配置无效")
+ public_network = validate_cloud_network(
+ public["addresses"][0], route["via"], dns, require_auth=False,
+ )
+ public_mac = _validate_network_mac(public_mac, "公网")
+ result: dict[str, Any] = {
+ **public_network,
+ "mac": public_mac,
+ "roles": [PUBLIC_INTERFACE_ALIAS],
+ }
+
+ private = ethernets.get(PRIVATE_INTERFACE_ALIAS)
+ if private is not None:
+ if not isinstance(private, dict):
+ raise ValueError("原 cloud-init 私网网卡配置无效")
+ if set(private) - {
+ "match", "dhcp4", "dhcp6", "accept-ra", "addresses", "routes",
+ }:
+ raise ValueError("原 cloud-init 私网网卡字段不受支持")
+ private_match = private.get("match")
+ private_mac = (private_match.get("macaddress")
+ if isinstance(private_match, dict) else None)
+ if (private.get("dhcp4") is not False
+ or private.get("dhcp6") is not False
+ or private.get("accept-ra") is not False
+ or not isinstance(private.get("addresses"), list)
+ or len(private["addresses"]) != 1
+ or "routes" in private
+ or not isinstance(private_match, dict)
+ or set(private_match) != {"macaddress"}):
+ raise ValueError("原 cloud-init 私网网卡必须是无默认路由的静态 /32")
+ private_mac = _validate_network_mac(private_mac, "私网")
+ private_network = validate_private_network(private["addresses"][0])
+ if private_mac == public_mac:
+ raise ValueError("公网和私网网卡不能使用同一个 MAC")
+ result.update({
+ **private_network,
+ "private_mac": private_mac,
+ "roles": [PUBLIC_INTERFACE_ALIAS, PRIVATE_INTERFACE_ALIAS],
+ })
+ return result
+
+
def build_seed_iso(
vm_uuid: str,
name: str,
@@ -287,6 +426,8 @@ def build_seed_iso(
validated_network: dict[str, Any],
*,
debian12_network_fix: bool = False,
+ private_mac: str | None = None,
+ private_network: dict[str, Any] | None = None,
) -> bytes:
"""Build a CIDATA ISO with user-data, meta-data, and network-config."""
try:
@@ -403,6 +544,23 @@ def build_seed_iso(
},
},
}
+ if (private_mac is None) != (private_network is None):
+ raise ValueError("私网网卡必须同时提供 MAC 和地址")
+ if private_mac is not None and private_network is not None:
+ normalized_private_mac = _validate_network_mac(private_mac, "私网")
+ private = validate_private_network(
+ private_network.get("private_ip_cidr")
+ if isinstance(private_network, dict) else None
+ )
+ if normalized_private_mac == normalized_mac:
+ raise ValueError("公网和私网网卡不能使用同一个 MAC")
+ network_config["ethernets"][PRIVATE_INTERFACE_ALIAS] = {
+ "match": {"macaddress": normalized_private_mac},
+ "dhcp4": False,
+ "dhcp6": False,
+ "accept-ra": False,
+ "addresses": [private["private_ip_cidr"]],
+ }
if debian12_network_fix:
# dhcp6=false does not disable DHCPv6 started in response to a router
# advertisement. This product currently provisions IPv4 only, so
@@ -592,23 +750,9 @@ def replace_seed_network(
meta_data = _prepare_seed_metadata(
files["meta-data"], rotate=needs_generation)
config = json.loads(files["network-config"])
- if (config.get("version") != 2
- or not isinstance(config.get("ethernets"), dict)
- or set(config["ethernets"]) != {"public0"}):
- raise ValueError
- public = config["ethernets"]["public0"]
- match = public.get("match")
- mac = match.get("macaddress") if isinstance(match, dict) else None
- if (public.get("dhcp4") is not False or public.get("dhcp6") is not False
- or not isinstance(mac, str) or not _MAC.fullmatch(mac)
- or not isinstance(public.get("addresses"), list)
- or len(public["addresses"]) != 1
- or not isinstance(public.get("routes"), list)
- or len(public["routes"]) != 1):
- raise ValueError
+ _parse_network_config(config)
+ public = config["ethernets"][PUBLIC_INTERFACE_ALIAS]
route = public["routes"][0]
- if route.get("to") != "0.0.0.0/0":
- raise ValueError
# Validate only fields that are changing. No credential is accepted
# by this operation; only the network-on-boot policy is merged into
# the panel-generated user-data above.
@@ -946,28 +1090,19 @@ def read_seed_network(seed: bytes) -> dict[str, Any]:
iso.close()
try:
- if config["version"] != 2:
- raise ValueError
- ethernets = config["ethernets"]
- if not isinstance(ethernets, dict) or set(ethernets) != {"public0"}:
- raise ValueError
- public = ethernets["public0"]
- if public["dhcp4"] is not False or public["dhcp6"] is not False:
- raise ValueError
- addresses = public["addresses"]
- routes = public["routes"]
- dns = public["nameservers"]["addresses"]
- mac = public["match"]["macaddress"]
- if (not isinstance(addresses, list) or len(addresses) != 1
- or not isinstance(routes, list) or len(routes) != 1
- or routes[0]["to"] != "0.0.0.0/0"
- or not isinstance(mac, str) or not _MAC.fullmatch(mac)):
- raise ValueError
- return {
- "public_ip_cidr": addresses[0],
- "gateway": routes[0]["via"],
- "dns_servers": dns,
- "mac": mac.lower(),
+ parsed = _parse_network_config(config)
+ result = {
+ "public_ip_cidr": parsed["public_ip_cidr"],
+ "gateway": parsed["gateway"],
+ "dns_servers": parsed["dns_servers"],
+ "mac": parsed["mac"],
}
+ if PRIVATE_INTERFACE_ALIAS in parsed["roles"]:
+ result.update({
+ "private_ip_cidr": parsed["private_ip_cidr"],
+ "private_mac": parsed["private_mac"],
+ "roles": list(parsed["roles"]),
+ })
+ return result
except (KeyError, TypeError, ValueError) as exc:
raise ValueError("原 cloud-init 网络配置格式无效") from exc
diff --git a/engine/virsh_panel/libvirt_service.py b/engine/virsh_panel/libvirt_service.py
index 510215c3..eb5807bb 100644
--- a/engine/virsh_panel/libvirt_service.py
+++ b/engine/virsh_panel/libvirt_service.py
@@ -30,9 +30,17 @@ from virsh_panel.cloud_init import (
_validate_guest_auth, _validate_ssh_public_key,
build_seed_iso, default_guest_hostname, read_seed_network,
replace_seed_network, replace_seed_settings, validate_cloud_network,
+ validate_private_network,
validate_guest_hostname,
)
from virsh_panel.metrics import RawVMStats
+from virsh_panel.network_roles import (
+ PUBLIC_INTERFACE_ALIAS,
+ assert_public_interface,
+ interface_role,
+ select_private_interface,
+ select_public_interface,
+)
from virsh_panel.platform_network_policy import (
MAX_PLATFORM_POLICY_SNAPSHOT_BYTES,
PLATFORM_DEFAULT_NETWORK_POLICY,
@@ -623,6 +631,11 @@ class VMService:
def _attach_public_filter(interface: ET.Element, public_ip_cidr: str,
filter_name: str) -> None:
"""Bind one validated filter to a panel-managed public interface."""
+ try:
+ assert_public_interface(interface, legacy_public=True)
+ except ValueError as exc:
+ raise VMError(str(exc), 409,
+ error_code="firewall_capability_missing") from exc
public_ip = public_ip_cidr.split("/", 1)[0]
filterref = ET.SubElement(interface, "filterref", filter=filter_name)
ET.SubElement(filterref, "parameter", name="IP", value=public_ip)
@@ -773,6 +786,11 @@ class VMService:
public_ip_cidr: str,
vm_uuid: str | None = None) -> None:
"""Update the IP parameter on either baseline or managed firewall."""
+ try:
+ assert_public_interface(interface, legacy_public=True)
+ except ValueError as exc:
+ raise VMError(str(exc), 409,
+ error_code="firewall_capability_missing") from exc
public_ip = public_ip_cidr.split("/", 1)[0]
expected_firewall = (firewall_filter_name(vm_uuid)
if vm_uuid is not None else None)
@@ -1686,6 +1704,10 @@ class VMService:
else:
interface = ET.SubElement(devices, "interface", type="bridge")
ET.SubElement(interface, "source", bridge=self.bridge_name)
+ # Give the provider-facing NIC an explicit role. Older domains with
+ # no alias remain readable, but new multi-NIC definitions must never
+ # rely on XML order when selecting a firewall target.
+ ET.SubElement(interface, "alias", name=PUBLIC_INTERFACE_ALIAS)
ET.SubElement(interface, "model", type="virtio")
# RHEL 10 recommends one virtio-net queue per vCPU, up to 16.
ET.SubElement(interface, "driver", queues=str(min(spec["vcpu"], 16)))
@@ -2857,6 +2879,75 @@ class VMService:
and template_volume_name.startswith(DEBIAN_12_TEMPLATE_VOLUME_PREFIX)
)
+ @staticmethod
+ def _assert_seed_private_network_matches_interfaces(
+ interfaces: list[ET.Element], network: dict[str, Any],
+ *, public_bridge: str | None = None, public_network: str | None = None,
+ ) -> dict[str, str] | None:
+ """Require the seed's private role to match the domain's private NIC.
+
+ A seed can be replaced independently of the domain XML. Keeping the
+ two role declarations in lockstep prevents a reinstall or a network
+ update from silently leaving an attached private NIC without an
+ address, or assigning a private address to an unrelated NIC.
+ """
+ private_ip = network.get("private_ip_cidr")
+ private_mac = network.get("private_mac")
+ has_seed_private = private_ip is not None or private_mac is not None
+ if has_seed_private and (
+ not isinstance(private_ip, str)
+ or not isinstance(private_mac, str)
+ or not private_ip
+ or not private_mac
+ ):
+ raise VMError("cloud-init 私网网卡字段不完整,已停止网络操作", 409)
+
+ try:
+ private_interface = select_private_interface(interfaces)
+ except ValueError as exc:
+ raise VMError("虚拟机网卡角色无效,已停止网络操作", 409) from exc
+ if (private_interface is not None) != has_seed_private:
+ raise VMError("虚拟机私网网卡与 cloud-init 私网配置不一致", 409)
+ if private_interface is None:
+ return None
+
+ mac_node = private_interface.find("mac")
+ xml_mac = (mac_node.get("address", "").lower()
+ if mac_node is not None else "")
+ if not xml_mac or xml_mac != private_mac.lower():
+ raise VMError("虚拟机 private0 MAC 与 cloud-init 私网配置不一致", 409)
+ if private_interface.findall("filterref"):
+ raise VMError("私网网卡不能绑定 libvirt 公网过滤器", 409)
+ source = private_interface.find("source")
+ if source is None or not any(
+ source.get(key) for key in ("bridge", "network", "dev", "name")
+ ):
+ raise VMError("私网网卡缺少独立的数据面来源", 409)
+ # A libvirt ``network=`` source hides its backing bridge behind a
+ # separately managed network definition. Until the VPC reconciler
+ # verifies that resource, accepting it would make a private NIC able
+ # to land on the public bridge by indirection. The preaccess contract
+ # therefore permits only an explicitly named bridge/tap/device.
+ if source.get("network"):
+ raise VMError("私网网卡必须使用已核验的独立 bridge/tap/device", 409)
+ if (public_bridge is not None and source is not None
+ and source.get("bridge") == public_bridge):
+ raise VMError("私网网卡不能复用公网网桥", 409)
+ if (public_bridge is not None
+ and source.get("dev") == public_bridge):
+ raise VMError("私网网卡不能复用公网网桥", 409)
+ if (public_network is not None and source is not None
+ and source.get("name") == public_network):
+ raise VMError("私网网卡不能复用公网 libvirt 网络", 409)
+ try:
+ validate_private_network(private_ip)
+ except ValueError as exc:
+ raise VMError("cloud-init 私网地址无效,已停止网络操作", 409) from exc
+ return {
+ "private_ip_cidr": private_ip,
+ "private_mac": private_mac.lower(),
+ }
+
@staticmethod
def _mac_for_new_vm(conn: Any) -> str:
used = {
@@ -3145,9 +3236,12 @@ class VMService:
disks = original_root.findall("./devices/disk[@device='disk']")
cdroms = original_root.findall("./devices/disk[@device='cdrom']")
interfaces = original_root.findall("./devices/interface")
- if len(disks) != 1 or len(cdroms) != 1 or len(interfaces) != 1:
+ if len(disks) != 1 or len(cdroms) != 1:
raise VMError("虚拟机磁盘或网卡配置已变化,不能安全自动重装", 409)
- interface = interfaces[0]
+ try:
+ interface = select_public_interface(interfaces)
+ except ValueError as exc:
+ raise VMError("虚拟机公网或私网网卡角色已变化,不能安全自动重装", 409) from exc
source = interface.find("source")
mac_node = interface.find("mac")
if (interface.get("type") != "bridge" or source is None
@@ -3167,6 +3261,9 @@ class VMService:
)
except (ImportError, ValueError) as exc:
raise VMError("无法校验原 cloud-init 网络配置,已停止重装", 409) from exc
+ private_network = self._assert_seed_private_network_matches_interfaces(
+ interfaces, original_network, public_bridge=self.bridge_name,
+ public_network=self.network)
if (original_network["mac"] != mac
or network["public_ip_cidr"] != managed.get("public-ip-cidr")):
raise VMError("原配置盘的公网 IP 或 MAC 与虚拟机不一致,已停止重装", 409)
@@ -3205,7 +3302,14 @@ class VMService:
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,重装已停止",
)
- inactive_interface = inactive_root.find("./devices/interface")
+ try:
+ inactive_interface = select_public_interface(
+ inactive_root.findall("./devices/interface"))
+ except ValueError as exc:
+ raise VMError("关机后虚拟机网卡角色已变化,重装已停止", 409) from exc
+ self._assert_seed_private_network_matches_interfaces(
+ inactive_root.findall("./devices/interface"), original_network,
+ public_bridge=self.bridge_name, public_network=self.network)
inactive_mac = (inactive_interface.find("mac") if inactive_interface is not None
else None)
inactive_source = (inactive_interface.find("source")
@@ -3233,6 +3337,10 @@ class VMService:
seed_uuid, display_name, mac, network,
debian12_network_fix=self._cloud_seed_needs_debian12_network_fix(
template_volume_name),
+ private_mac=(private_network["private_mac"]
+ if private_network is not None else None),
+ private_network=(private_network
+ if private_network is not None else None),
)
except ImportError as exc:
raise VMError("面板缺少 pycdlib,需安装 requirements.txt 中的依赖", 503) from exc
@@ -3478,9 +3586,10 @@ class VMService:
and old_pool_key != source_public_pool_key):
raise VMError("虚拟机原公网地址池已变化,已停止网络修改", 409)
interfaces = original_root.findall("./devices/interface")
- if len(interfaces) != 1:
- raise VMError("虚拟机必须只有一个公网网卡,已停止网络修改", 409)
- interface = interfaces[0]
+ try:
+ interface = select_public_interface(interfaces)
+ except ValueError as exc:
+ raise VMError("虚拟机公网或私网网卡角色不明确,已停止网络修改", 409) from exc
source = interface.find("source")
mac_node = interface.find("mac")
if (interface.get("type") != "bridge" or source is None
@@ -3510,6 +3619,9 @@ class VMService:
if (original_network["mac"] != mac
or original_network["public_ip_cidr"] != old_ip):
raise VMError("原配置盘的公网 IP 或 MAC 与虚拟机不一致,已停止网络修改", 409)
+ self._assert_seed_private_network_matches_interfaces(
+ interfaces, original_network, public_bridge=self.bridge_name,
+ public_network=self.network)
try:
original_validated = validate_cloud_network(
original_network["public_ip_cidr"],
@@ -3563,7 +3675,14 @@ class VMService:
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,网络修改已停止",
)
- inactive_interface = inactive_root.find("./devices/interface")
+ try:
+ inactive_interface = select_public_interface(
+ inactive_root.findall("./devices/interface"))
+ except ValueError as exc:
+ raise VMError("关机后虚拟机网卡角色已变化,网络修改已停止", 409) from exc
+ self._assert_seed_private_network_matches_interfaces(
+ inactive_root.findall("./devices/interface"), original_network,
+ public_bridge=self.bridge_name, public_network=self.network)
inactive_mac = (inactive_interface.find("mac")
if inactive_interface is not None else None)
inactive_source = (inactive_interface.find("source")
@@ -3582,8 +3701,12 @@ class VMService:
new_root = ET.fromstring(old_xml)
new_managed = new_root.find(f"./metadata/{{{PANEL_NS}}}managed")
- new_interface = new_root.find("./devices/interface")
- if new_managed is None or new_interface is None:
+ try:
+ new_interface = select_public_interface(
+ new_root.findall("./devices/interface"))
+ except ValueError as exc:
+ raise VMError("虚拟机配置网卡角色已变化,网络修改已停止", 409) from exc
+ if new_managed is None:
raise VMError("虚拟机配置已变化,网络修改已停止", 409)
new_managed.set("public-ip-cidr", validated["public_ip_cidr"])
new_managed.set("public-pool-key", public_pool_key)
@@ -3741,9 +3864,10 @@ class VMService:
or not managed.get("public-ip-cidr")):
raise VMError("只有面板创建的公网云镜像虚拟机支持修改设置", 409)
interfaces = original_root.findall("./devices/interface")
- if len(interfaces) != 1:
- raise VMError("虚拟机网卡配置已变化,已停止修改设置", 409)
- interface = interfaces[0]
+ try:
+ interface = select_public_interface(interfaces)
+ except ValueError as exc:
+ raise VMError("虚拟机公网或私网网卡角色不明确,已停止修改设置", 409) from exc
mac_node = interface.find("mac")
if mac_node is None or not mac_node.get("address"):
raise VMError("虚拟机 MAC 配置已变化,已停止修改设置", 409)
@@ -3759,6 +3883,9 @@ class VMService:
if (original_network["mac"] != mac
or original_network["public_ip_cidr"] != managed.get("public-ip-cidr")):
raise VMError("原配置盘的公网 IP 或 MAC 与虚拟机不一致,已停止修改设置", 409)
+ self._assert_seed_private_network_matches_interfaces(
+ interfaces, original_network, public_bridge=self.bridge_name,
+ public_network=self.network)
try:
replacement_seed = replace_seed_settings(
original_seed,
@@ -3814,6 +3941,14 @@ class VMService:
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,设置修改已停止",
)
+ try:
+ select_public_interface(
+ inactive_root.findall("./devices/interface"))
+ except ValueError as exc:
+ raise VMError("关机后虚拟机网卡角色已变化,设置修改已停止", 409) from exc
+ self._assert_seed_private_network_matches_interfaces(
+ inactive_root.findall("./devices/interface"), original_network,
+ public_bridge=self.bridge_name, public_network=self.network)
if (inactive_managed is None
or inactive_managed.get("seed-volume") != old_seed.name()
or inactive_managed.get("public-ip-cidr") != managed.get("public-ip-cidr")):
@@ -4313,10 +4448,49 @@ class VMService:
raise VMError("只有面板创建的公网云镜像虚拟机支持防火墙", 409,
error_code="firewall_capability_missing")
interfaces = root.findall("./devices/interface")
- if len(interfaces) != 1:
- raise VMError("防火墙一期要求虚拟机只有一张公网网卡", 409,
- error_code="firewall_capability_missing")
- interface = interfaces[0]
+ try:
+ interface = select_public_interface(interfaces)
+ except ValueError as exc:
+ raise VMError("虚拟机网卡角色无效,已停止防火墙操作", 409,
+ error_code="firewall_capability_missing") from exc
+ try:
+ for item in interfaces:
+ if item is interface:
+ continue
+ role = interface_role(item)
+ # An unaliased second NIC is not safe to classify during the
+ # migration window. Even when it currently has no filter,
+ # allowing a public policy operation would leave its security
+ # role implicit and could bind a future ACL to the wrong NIC.
+ if role == "unknown":
+ raise VMError("多网卡虚拟机必须为每张网卡声明 public0/private0 角色", 409,
+ error_code="firewall_capability_missing")
+ if role == "private" and item.findall("filterref"):
+ raise VMError("私网网卡不能绑定公网过滤器", 409,
+ error_code="firewall_drift_detected")
+ if role == "private":
+ source = item.find("source")
+ if source is None or not any(
+ source.get(key)
+ for key in ("bridge", "network", "dev", "name")
+ ):
+ raise VMError("私网网卡缺少独立的数据面来源", 409,
+ error_code="firewall_drift_detected")
+ if source.get("network"):
+ raise VMError(
+ "私网网卡必须使用已核验的独立 bridge/tap/device", 409,
+ error_code="firewall_drift_detected")
+ if ((self.bridge_name is not None
+ and source.get("bridge") == self.bridge_name)
+ or (self.bridge_name is not None
+ and source.get("dev") == self.bridge_name)
+ or (self.network is not None
+ and source.get("name") == self.network)):
+ raise VMError("私网网卡不能复用公网网络", 409,
+ error_code="firewall_drift_detected")
+ except ValueError as exc:
+ raise VMError("虚拟机网卡角色无效,已停止防火墙操作", 409,
+ error_code="firewall_capability_missing") from exc
source = interface.find("source")
if (self.bridge_name is None or interface.get("type") != "bridge"
or source is None or source.get("bridge") != self.bridge_name):
diff --git a/engine/virsh_panel/network_roles.py b/engine/virsh_panel/network_roles.py
new file mode 100644
index 00000000..82a37961
--- /dev/null
+++ b/engine/virsh_panel/network_roles.py
@@ -0,0 +1,148 @@
+"""Stable guest network-role helpers shared by cloud-init and libvirt.
+
+The public interface is the only interface that may carry the panel's
+provider-facing anti-spoofing/nwfilter policy. A future VPC interface is a
+separate L3 dataplane and must never be inferred from the public bridge.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from typing import Any
+
+
+PUBLIC_INTERFACE_ALIAS = "public0"
+PRIVATE_INTERFACE_ALIAS = "private0"
+SUPPORTED_INTERFACE_ALIASES = frozenset({
+ PUBLIC_INTERFACE_ALIAS,
+ PRIVATE_INTERFACE_ALIAS,
+})
+_ALIAS_RE = re.compile(r"[a-z][a-z0-9-]{0,15}\Z")
+# libvirt adds a generated interface alias when an older domain definition did
+# not provide one. Those aliases identify the first/only legacy NIC, but they
+# do not constitute an explicit private role. Keep the compatibility scope
+# narrow so an arbitrary operator alias is never silently treated as public.
+_LEGACY_PUBLIC_ALIAS_RE = re.compile(r"(?:net|ua-net-)[0-9]+\Z")
+
+
+def _is_legacy_public_alias(alias: str | None) -> bool:
+ return alias is not None and _LEGACY_PUBLIC_ALIAS_RE.fullmatch(alias) is not None
+
+
+def interface_alias(interface: ET.Element) -> str | None:
+ """Return a validated libvirt interface alias, if one is present."""
+ alias = interface.find("alias")
+ value = alias.get("name") if alias is not None else None
+ if value is None:
+ return None
+ if not isinstance(value, str) or not _ALIAS_RE.fullmatch(value):
+ raise ValueError("虚拟机网卡别名无效")
+ return value
+
+
+def interface_role(interface: ET.Element, *, legacy_public: bool = False) -> str:
+ """Classify one interface without guessing a role for a multi-NIC VM.
+
+ A legacy single-NIC domain with no alias, or with libvirt's generated
+ ``net0``/``ua-net-0`` alias, is treated as public for backwards
+ compatibility when ``legacy_public`` is requested. An unaliased or
+ generated interface in a multi-NIC domain is intentionally ``unknown``
+ and must be rejected by callers that apply a security policy.
+ """
+ alias = interface_alias(interface)
+ if alias == PUBLIC_INTERFACE_ALIAS:
+ return "public"
+ if alias == PRIVATE_INTERFACE_ALIAS:
+ return "private"
+ if alias is not None:
+ if legacy_public and _is_legacy_public_alias(alias):
+ return "public"
+ return "unknown"
+ if legacy_public and alias is None:
+ return "public"
+ return "unknown"
+
+
+def role_for_cloud_key(key: Any) -> str:
+ """Map a cloud-init ethernet key to a product network role."""
+ if key == PUBLIC_INTERFACE_ALIAS:
+ return "public"
+ if key == PRIVATE_INTERFACE_ALIAS:
+ return "private"
+ raise ValueError("cloud-init 网卡角色不受支持")
+
+
+def select_public_interface(
+ interfaces: list[ET.Element] | tuple[ET.Element, ...],
+ *,
+ allow_legacy_single: bool = True,
+) -> ET.Element:
+ """Select the provider-facing NIC and validate every other NIC's role.
+
+ New definitions must label every interface. The sole exception is an
+ old one-NIC domain without an alias, which is still safely identifiable as
+ the public NIC. Once a second NIC exists, an unlabelled or unknown alias
+ is rejected rather than being treated as private by accident.
+ """
+ values = list(interfaces)
+ if not values:
+ raise ValueError("虚拟机缺少网卡")
+ candidates = [
+ item for item in values
+ if interface_role(item, legacy_public=False) == "public"
+ ]
+ if not candidates and allow_legacy_single and len(values) == 1:
+ if interface_role(values[0], legacy_public=True) == "public":
+ candidates = [values[0]]
+ if len(candidates) != 1:
+ raise ValueError("虚拟机公网网卡角色不明确")
+ selected = candidates[0]
+ private_count = 0
+ for item in values:
+ if item is selected:
+ continue
+ role = interface_role(item)
+ if role == "private":
+ private_count += 1
+ elif role == "unknown":
+ raise ValueError("多网卡虚拟机必须声明每张网卡的角色")
+ if private_count > 1:
+ raise ValueError("虚拟机不能包含多张 private0 网卡")
+ return selected
+
+
+def select_private_interface(
+ interfaces: list[ET.Element] | tuple[ET.Element, ...],
+) -> ET.Element | None:
+ """Return the single explicit private NIC, if a domain has one."""
+ candidates = [
+ item for item in interfaces
+ if interface_role(item, legacy_public=False) == "private"
+ ]
+ if len(candidates) > 1:
+ raise ValueError("虚拟机不能包含多张 private0 网卡")
+ return candidates[0] if candidates else None
+
+
+def assert_public_interface(interface: ET.Element, *, legacy_public: bool = False) -> None:
+ """Reject attaching public policy to a private or ambiguous interface."""
+ role = interface_role(interface, legacy_public=legacy_public)
+ if role != "public":
+ raise ValueError("公网过滤器只能绑定 public0 网卡")
+
+
+def private_interface_has_public_filter(interface: ET.Element) -> bool:
+ """Return whether a non-public role carries a public filter reference.
+
+ An explicitly private NIC is the normal case. Treating an unknown alias
+ as unsafe here also matters during migration: a future or externally
+ edited NIC must never become an unreviewed place to attach a provider
+ anti-spoofing policy.
+ """
+ role = interface_role(interface)
+ # The private dataplane is governed by its own nftables context. Any
+ # libvirt nwfilter on a non-public NIC is therefore outside this contract;
+ # accepting an arbitrary filter would make it impossible to prove that a
+ # provider anti-spoofing policy was not copied to the private interface.
+ return role != "public" and bool(interface.findall("filterref"))
diff --git a/engine/virsh_panel/remote_host.py b/engine/virsh_panel/remote_host.py
index 8e351bc9..a59c21ef 100644
--- a/engine/virsh_panel/remote_host.py
+++ b/engine/virsh_panel/remote_host.py
@@ -37,9 +37,162 @@ _KEY_HEADER = re.compile(r"-----BEGIN (?:OPENSSH |RSA |EC |DSA )?PRIVATE KEY----
_GEN_NAME = re.compile(r"gen-[0-9a-f]{32}\Z")
_POOL_PATH = re.compile(r"/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*\Z")
_BRIDGE_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,14}\Z")
+_IFACE_NAME = re.compile(r"[A-Za-z0-9_.:-]{1,15}\Z")
PUBLIC_POOL_KEY = re.compile(r"[0-9a-f]{32}\Z")
PUBLIC_POOL_STATES = frozenset({"active", "draining", "disabled"})
MAX_PUBLIC_NETWORK_POOLS = 32
+HOST_CAPABILITY_SCHEMA_VERSION = 1
+WG_FABRIC_INTERFACE = "wg-fabric0"
+WG_FABRIC_OWNERSHIP_MARKER = "virt-cloud-wg-fabric-v1"
+_MAX_CAPABILITY_OUTPUT = 262144
+_CAPABILITY_MARKER = "__VIRT_CLOUD_HOST_CAPABILITIES_V1__"
+
+# Keep this command literal and independent of every value supplied by an
+# administrator. The remote shell is used only to run this fixed probe; no
+# selector, path, peer, or other request data is interpolated into it. The
+# probe is deliberately read-only: it never installs packages, loads modules,
+# changes links, or rewrites a firewall. AlmaLinux and Debian place the
+# utilities in slightly different directories, so each known path is checked
+# explicitly instead of using PATH or ``command -v``.
+_CAPABILITY_PROBE_COMMAND = r'''/bin/sh -c '
+set +e
+printf "%s\n" "__VIRT_CLOUD_HOST_CAPABILITIES_V1__"
+printf "%s\n" "__VCAP_OS_BEGIN__"
+/usr/bin/cat /etc/os-release 2>/dev/null || /bin/cat /etc/os-release 2>/dev/null
+printf "%s\n" "__VCAP_OS_END__"
+printf "%s\n" "__VCAP_KERNEL_BEGIN__"
+/usr/bin/uname -r 2>/dev/null || /bin/uname -r 2>/dev/null
+printf "%s\n" "__VCAP_KERNEL_END__"
+
+probe_binary() {
+ name="$1"
+ shift
+ for path in "$@"; do
+ if test -x "$path"; then
+ printf "__VCAP_TOOL__%s=%s\n" "$name" "$path"
+ return 0
+ fi
+ done
+ printf "__VCAP_TOOL__%s=\n" "$name"
+ return 1
+}
+probe_binary wg /usr/bin/wg /usr/sbin/wg /bin/wg /sbin/wg
+probe_binary wg_quick /usr/bin/wg-quick /usr/sbin/wg-quick /bin/wg-quick /sbin/wg-quick
+probe_binary ip /usr/sbin/ip /usr/bin/ip /sbin/ip /bin/ip
+probe_binary nft /usr/sbin/nft /usr/bin/nft /sbin/nft /bin/nft
+probe_binary nmcli /usr/bin/nmcli /usr/sbin/nmcli /bin/nmcli /sbin/nmcli
+probe_binary networkctl /usr/bin/networkctl /usr/sbin/networkctl /bin/networkctl /sbin/networkctl
+probe_binary systemctl /usr/bin/systemctl /usr/sbin/systemctl /bin/systemctl /sbin/systemctl
+probe_binary modinfo /usr/sbin/modinfo /usr/bin/modinfo /sbin/modinfo /bin/modinfo
+probe_binary dnf /usr/bin/dnf /usr/sbin/dnf /bin/dnf /sbin/dnf /usr/bin/dnf5 /usr/sbin/dnf5
+probe_binary apt_get /usr/bin/apt-get /usr/sbin/apt-get /bin/apt-get /sbin/apt-get
+
+if test -e /sys/module/wireguard; then
+ printf "%s\n" "__VCAP_MODULE__wireguard=loaded"
+else
+ printf "%s\n" "__VCAP_MODULE__wireguard=not_loaded"
+fi
+printf "%s\n" "__VCAP_MODULE_FILE_BEGIN__"
+if test -x /usr/sbin/modinfo; then
+ /usr/sbin/modinfo -F filename wireguard 2>/dev/null
+elif test -x /usr/bin/modinfo; then
+ /usr/bin/modinfo -F filename wireguard 2>/dev/null
+else
+ printf "%s\n" ""
+fi
+printf "%s\n" "__VCAP_MODULE_FILE_END__"
+printf "%s\n" "__VCAP_FABRIC_OWNER_BEGIN__"
+if test -f /etc/virt-cloud/wg-fabric0.owner; then
+ /usr/bin/cat /etc/virt-cloud/wg-fabric0.owner 2>/dev/null || /bin/cat /etc/virt-cloud/wg-fabric0.owner 2>/dev/null
+fi
+printf "%s\n" "__VCAP_FABRIC_OWNER_END__"
+
+probe_sysctl() {
+ name="$1"
+ key="$2"
+ value=""
+ if test -x /usr/sbin/sysctl; then
+ value=$(/usr/sbin/sysctl -n "$key" 2>/dev/null)
+ elif test -x /usr/bin/sysctl; then
+ value=$(/usr/bin/sysctl -n "$key" 2>/dev/null)
+ fi
+ printf "__VCAP_SYSCTL__%s=%s\n" "$name" "$value"
+}
+probe_sysctl ip_forward net.ipv4.ip_forward
+probe_sysctl rp_filter net.ipv4.conf.all.rp_filter
+probe_sysctl rp_filter_default net.ipv4.conf.default.rp_filter
+# Linux computes the effective reverse-path policy from the global value and
+# the interface value (and uses ``default`` for interfaces created later).
+# Read every bounded interface file so a strict policy on br0 or a previously
+# created fabric link cannot be hidden by a permissive ``all`` value.
+for rp_file in /proc/sys/net/ipv4/conf/*/rp_filter; do
+ test -f "$rp_file" || continue
+ rp_iface=${rp_file%/rp_filter}
+ rp_iface=${rp_iface##*/}
+ case "$rp_iface" in
+ ""|*[!A-Za-z0-9_.:-]*) continue ;;
+ esac
+ if test -x /usr/bin/cat; then
+ rp_value=$(/usr/bin/cat "$rp_file" 2>/dev/null)
+ else
+ rp_value=$(/bin/cat "$rp_file" 2>/dev/null)
+ fi
+ printf "__VCAP_RPF__%s=%s\n" "$rp_iface" "$rp_value"
+done
+
+probe_service() {
+ name="$1"
+ service="$2"
+ status="unknown"
+ if test -x /usr/bin/systemctl; then
+ status=$(/usr/bin/systemctl is-active "$service" 2>/dev/null)
+ elif test -x /bin/systemctl; then
+ status=$(/bin/systemctl is-active "$service" 2>/dev/null)
+ fi
+ case "$status" in
+ active|inactive|failed|activating|deactivating) ;;
+ *) status="unknown" ;;
+ esac
+ printf "__VCAP_SERVICE__%s=%s\n" "$name" "$status"
+}
+probe_service network_manager NetworkManager
+probe_service networkd systemd-networkd
+probe_service firewall firewalld
+probe_service nftables nftables
+
+probe_ip_json() {
+ name="$1"
+ shift
+ printf "__VCAP_IP_BEGIN__%s\n" "$name"
+ status=127
+ if test -x /usr/sbin/ip; then
+ /usr/sbin/ip "$@" 2>/dev/null
+ status=$?
+ elif test -x /usr/bin/ip; then
+ /usr/bin/ip "$@" 2>/dev/null
+ status=$?
+ fi
+ printf "__VCAP_IP_END__%s=%s\n" "$name" "$status"
+}
+probe_ip_json links -j -d link show
+# Keep bridge discovery compatible with the iproute2 versions shipped by the
+# two supported distributions; ``-d`` is unnecessary for this selector and is
+# rejected by some older builds.
+probe_ip_json bridges -j link show type bridge
+probe_ip_json wireguard -j -d link show type wireguard
+
+printf "%s\n" "__VCAP_NFT_BEGIN__"
+status=127
+if test -x /usr/sbin/nft; then
+ /usr/sbin/nft -j list tables 2>/dev/null
+ status=$?
+elif test -x /usr/bin/nft; then
+ /usr/bin/nft -j list tables 2>/dev/null
+ status=$?
+fi
+printf "__VCAP_NFT_END__%s\n" "$status"
+printf "%s\n" "__VCAP_END__"
+' '''
_RUNNER = Callable[..., subprocess.CompletedProcess[str]]
LOG = logging.getLogger(__name__)
@@ -526,6 +679,444 @@ def _quoted_path(path: Path) -> str:
return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+def _capability_section(output: str, begin: str, end: str) -> str | None:
+ """Return one bounded probe section, or ``None`` for malformed output."""
+ start = output.find(begin)
+ if start < 0:
+ return None
+ start += len(begin)
+ finish = output.find(end, start)
+ if finish < 0 or finish - start > _MAX_CAPABILITY_OUTPUT:
+ return None
+ return output[start:finish]
+
+
+def _capability_lines(output: str, prefix: str) -> dict[str, str]:
+ values: dict[str, str] = {}
+ for line in output.splitlines():
+ if not line.startswith(prefix):
+ continue
+ key, separator, value = line[len(prefix):].partition("=")
+ if (separator and re.fullmatch(r"[a-z_]{1,32}", key)
+ and len(value) <= 512):
+ values[key] = value
+ return values
+
+
+def _capability_named_lines(output: str, prefix: str) -> dict[str, str]:
+ """Parse bounded interface-name keyed probe lines."""
+ values: dict[str, str] = {}
+ for line in output.splitlines():
+ if not line.startswith(prefix):
+ continue
+ key, separator, value = line[len(prefix):].partition("=")
+ if (separator and re.fullmatch(r"[A-Za-z0-9_.:-]{1,15}", key)
+ and re.fullmatch(r"[0-9]+", value.strip())):
+ values[key] = value.strip()
+ return values
+
+
+def _parse_os_release(section: str | None) -> dict[str, str]:
+ if section is None:
+ return {}
+ values: dict[str, str] = {}
+ for line in section.splitlines()[:128]:
+ key, separator, value = line.partition("=")
+ if (not separator or not re.fullmatch(r"[A-Z0-9_]{1,64}", key)
+ or len(value) > 512):
+ continue
+ value = value.strip()
+ if len(value) >= 2 and value[0] == value[-1] == '"':
+ value = value[1:-1].replace('\\"', '"').replace("\\\\", "\\")
+ elif len(value) >= 2 and value[0] == value[-1] == "'":
+ value = value[1:-1]
+ if "\x00" not in value and "\r" not in value and "\n" not in value:
+ values[key] = value
+ return values
+
+
+def _parse_json_interfaces(section: str | None, status: str | None) -> list[str]:
+ if section is None or status != "0":
+ return []
+ try:
+ values = json.loads(section.strip())
+ except (TypeError, ValueError):
+ return []
+ if not isinstance(values, list) or len(values) > 4096:
+ return []
+ names: list[str] = []
+ for item in values:
+ if not isinstance(item, dict):
+ continue
+ name = item.get("ifname")
+ if isinstance(name, str) and _IFACE_NAME.fullmatch(name):
+ names.append(name)
+ return sorted(set(names))
+
+
+def _valid_json_interfaces(section: str | None, status: str | None) -> bool:
+ """Return whether an iproute2 JSON section is complete and well formed."""
+ if section is None or status != "0":
+ return False
+ try:
+ values = json.loads(section.strip())
+ except (TypeError, ValueError):
+ return False
+ if not isinstance(values, list) or len(values) > 4096:
+ return False
+ for item in values:
+ if (not isinstance(item, dict)
+ or not isinstance(item.get("ifname"), str)
+ or _IFACE_NAME.fullmatch(item["ifname"]) is None):
+ return False
+ return True
+
+
+def _parse_integer(value: str | None) -> int | None:
+ if value is None or not re.fullmatch(r"[0-9]+", value.strip()):
+ return None
+ try:
+ return int(value.strip(), 10)
+ except ValueError:
+ return None
+
+
+def _parse_nft_tables(section: str | None, status: str | None) -> bool:
+ """Confirm that the read-only nft probe returned valid JSON."""
+ if section is None or status != "0":
+ return False
+ try:
+ payload = json.loads(section.strip())
+ except (TypeError, ValueError):
+ return False
+ # ``nft -j list tables`` returns an object in newer nft versions and a
+ # list in a few vendor builds. Both are evidence that the command ran;
+ # arbitrary text is not.
+ return isinstance(payload, (dict, list)) and len(section) <= _MAX_CAPABILITY_OUTPUT
+
+
+def parse_host_capabilities(
+ output: str,
+ *,
+ public_network: str = "default",
+) -> dict[str, Any]:
+ """Parse the fixed remote probe into a fail-closed capability snapshot.
+
+ The returned object is a data contract for the future VPC/Fabric
+ reconciler. It is intentionally useful even when a command is missing:
+ ``vpc_ready`` remains false and ``reasons`` names the missing evidence.
+ No raw command output is returned to callers.
+ """
+ if not isinstance(output, str) or len(output) > _MAX_CAPABILITY_OUTPUT:
+ output = ""
+ required_sections = (
+ _CAPABILITY_MARKER,
+ "__VCAP_OS_BEGIN__\n", "__VCAP_OS_END__",
+ "__VCAP_KERNEL_BEGIN__\n", "__VCAP_KERNEL_END__",
+ "__VCAP_MODULE_FILE_BEGIN__\n", "__VCAP_MODULE_FILE_END__",
+ "__VCAP_FABRIC_OWNER_BEGIN__\n", "__VCAP_FABRIC_OWNER_END__",
+ "__VCAP_IP_BEGIN__links\n", "__VCAP_IP_END__links=",
+ "__VCAP_IP_BEGIN__bridges\n", "__VCAP_IP_END__bridges=",
+ "__VCAP_IP_BEGIN__wireguard\n", "__VCAP_IP_END__wireguard=",
+ "__VCAP_NFT_BEGIN__\n", "__VCAP_NFT_END__",
+ "__VCAP_END__",
+ )
+ protocol_ok = all(section in output for section in required_sections)
+ os_values = _parse_os_release(
+ _capability_section(output, "__VCAP_OS_BEGIN__\n", "__VCAP_OS_END__"))
+ kernel_section = _capability_section(
+ output, "__VCAP_KERNEL_BEGIN__\n", "__VCAP_KERNEL_END__")
+ kernel = "" if kernel_section is None else kernel_section.strip()
+ tools = _capability_lines(output, "__VCAP_TOOL__")
+ modules = _capability_lines(output, "__VCAP_MODULE__")
+ sysctls = _capability_lines(output, "__VCAP_SYSCTL__")
+ services = _capability_lines(output, "__VCAP_SERVICE__")
+ rp_filter_interfaces = {
+ name: parsed for name, raw in _capability_named_lines(
+ output, "__VCAP_RPF__").items()
+ if (parsed := _parse_integer(raw)) is not None
+ }
+ ip_statuses: dict[str, str] = {}
+ ip_sections: dict[str, str | None] = {}
+ for name in ("links", "bridges", "wireguard"):
+ begin = f"__VCAP_IP_BEGIN__{name}\n"
+ section_start = output.find(begin)
+ if section_start < 0:
+ ip_sections[name] = None
+ continue
+ section_start += len(begin)
+ end_prefix = f"__VCAP_IP_END__{name}="
+ end_start = output.find(end_prefix, section_start)
+ if end_start < 0 or end_start - section_start > _MAX_CAPABILITY_OUTPUT:
+ ip_sections[name] = None
+ continue
+ ip_sections[name] = output[section_start:end_start]
+ status_line = output[end_start:].splitlines()[0]
+ ip_statuses[name] = status_line[len(end_prefix):].strip()
+ nft_start = output.find("__VCAP_NFT_BEGIN__\n")
+ nft_end = output.find("__VCAP_NFT_END__", nft_start + 1)
+ nft_section: str | None = None
+ nft_status: str | None = None
+ if nft_start >= 0 and nft_end >= 0:
+ nft_start += len("__VCAP_NFT_BEGIN__\n")
+ if nft_end - nft_start <= _MAX_CAPABILITY_OUTPUT:
+ nft_section = output[nft_start:nft_end]
+ nft_status = output[nft_end + len("__VCAP_NFT_END__"):].splitlines()[0].strip()
+
+ bridge_names = _parse_json_interfaces(
+ ip_sections.get("bridges"), ip_statuses.get("bridges"))
+ wireguard_names = _parse_json_interfaces(
+ ip_sections.get("wireguard"), ip_statuses.get("wireguard"))
+ all_interfaces = _parse_json_interfaces(
+ ip_sections.get("links"), ip_statuses.get("links"))
+ ip_probe_valid = all(
+ _valid_json_interfaces(ip_sections.get(name), ip_statuses.get(name))
+ for name in ("links", "bridges", "wireguard")
+ )
+ tool_paths = {
+ name: value for name, value in tools.items()
+ if value and re.fullmatch(r"/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*", value)
+ }
+ tool_state = {
+ name: {"available": name in tool_paths, "path": tool_paths.get(name)}
+ for name in (
+ "wg", "wg_quick", "ip", "nft", "nmcli", "networkctl",
+ "systemctl", "modinfo", "dnf", "apt_get",
+ )
+ }
+ os_id = os_values.get("ID", "").lower()
+ version_id = os_values.get("VERSION_ID", "")
+ if os_id in {"almalinux", "rhel", "rocky", "centos"}:
+ family = "rhel"
+ package_manager = "dnf"
+ elif os_id in {"debian", "ubuntu"}:
+ family = "debian"
+ package_manager = "apt"
+ else:
+ family = "unknown"
+ package_manager = None
+ os_supported = family in {"rhel", "debian"}
+ package_tool = "dnf" if family == "rhel" else "apt_get" if family == "debian" else None
+ package_tool_ready = bool(package_tool and tool_state[package_tool]["available"])
+
+ network_managers = {
+ "networkmanager": services.get("network_manager") == "active",
+ "systemd_networkd": services.get("networkd") == "active",
+ }
+ active_network_managers = [name for name, active in network_managers.items() if active]
+ if len(active_network_managers) == 1:
+ network_manager = active_network_managers[0]
+ elif len(active_network_managers) > 1:
+ network_manager = "conflict"
+ else:
+ network_manager = "unknown"
+
+ firewall_managers = {
+ "firewalld": services.get("firewall") == "active",
+ "nftables": services.get("nftables") == "active",
+ }
+ active_firewall_managers = [name for name, active in firewall_managers.items() if active]
+ if len(active_firewall_managers) == 1:
+ firewall_manager = active_firewall_managers[0]
+ elif len(active_firewall_managers) > 1:
+ firewall_manager = "conflict"
+ elif services.get("firewall") == "unknown" and services.get("nftables") == "unknown":
+ firewall_manager = "unknown"
+ else:
+ firewall_manager = "unmanaged"
+
+ ip_forward = _parse_integer(sysctls.get("ip_forward"))
+ rp_filter = _parse_integer(sysctls.get("rp_filter"))
+ rp_filter_default = _parse_integer(sysctls.get("rp_filter_default"))
+ module_loaded = modules.get("wireguard") == "loaded"
+ owner_section = _capability_section(
+ output, "__VCAP_FABRIC_OWNER_BEGIN__\n",
+ "__VCAP_FABRIC_OWNER_END__")
+ fabric_owner_marker = "" if owner_section is None else owner_section.strip()
+ fabric_owned = fabric_owner_marker == WG_FABRIC_OWNERSHIP_MARKER
+ module_file = None
+ module_section = _capability_section(
+ output, "__VCAP_MODULE_FILE_BEGIN__\n", "__VCAP_MODULE_FILE_END__")
+ if module_section:
+ module_lines = module_section.strip().splitlines()
+ if module_lines:
+ candidate = module_lines[0]
+ if re.fullmatch(r"/[A-Za-z0-9_.+@:-]+(?:/[A-Za-z0-9_.+@:-]+)*", candidate):
+ module_file = candidate
+ wireguard_kernel_ready = module_loaded or module_file is not None
+ wireguard_ready = bool(tool_state["wg"]["available"] and wireguard_kernel_ready)
+ # The reserved name must be free for the panel's own WireGuard device.
+ # A pre-existing link with the same name is a conflict even when it is
+ # not itself a WireGuard link (for example, an operator-created dummy or
+ # bridge). An ownership marker alone cannot convert the wrong link type
+ # into a safe fabric interface.
+ fabric_interface_present = WG_FABRIC_INTERFACE in all_interfaces
+ fabric_interface_is_wireguard = WG_FABRIC_INTERFACE in wireguard_names
+ nft_readable = _parse_nft_tables(nft_section, nft_status)
+ # This is only a capability result: a later reconciler still has to create
+ # and own a dedicated private ACL table, then read it back before marking
+ # a VPC revision active. An unknown or unmanaged firewall is rejected so
+ # that the private policy cannot silently drift into a different owner.
+ nft_ready = bool(tool_state["nft"]["available"] and nft_readable
+ and firewall_manager == "nftables")
+ forwarding_ready = ip_forward == 1
+ selector = public_network if isinstance(public_network, str) else ""
+ if selector.startswith("bridge:"):
+ bridge = selector.removeprefix("bridge:")
+ public_selector_kind = "bridge"
+ public_verified = bridge in bridge_names
+ public_reason = None if public_verified else "public_bridge_missing"
+ elif selector and _DNS_LABEL.fullmatch(selector):
+ bridge = None
+ public_selector_kind = "libvirt_network"
+ # The libvirt resource check remains authoritative for named virtual
+ # networks. This probe records the role without guessing its bridge.
+ public_verified = True
+ public_reason = None
+ else:
+ bridge = None
+ public_selector_kind = "invalid"
+ public_verified = False
+ public_reason = "public_network_selector_invalid"
+
+ rp_filter_ready = rp_filter in {0, 2} and rp_filter_default in {0, 2}
+ # A bridge selector names the public L3 interface and therefore requires
+ # direct evidence for that interface as well. The fabric interface is
+ # checked whenever it already exists; a newly-created one inherits the
+ # validated default value. Strict mode (1) is rejected because it can
+ # discard asymmetric routed WireGuard traffic.
+ relevant_rp_values: list[int] = []
+ if bridge is not None:
+ bridge_rp = rp_filter_interfaces.get(bridge)
+ if bridge_rp is None:
+ rp_filter_ready = False
+ else:
+ relevant_rp_values.append(bridge_rp)
+ if WG_FABRIC_INTERFACE in rp_filter_interfaces:
+ relevant_rp_values.append(rp_filter_interfaces[WG_FABRIC_INTERFACE])
+ if any(value not in {0, 2} for value in relevant_rp_values):
+ rp_filter_ready = False
+
+ reasons: list[str] = []
+ if not protocol_ok:
+ reasons.append("capability_probe_invalid")
+ if not os_supported:
+ reasons.append("unsupported_host_os")
+ if not tool_state["wg"]["available"]:
+ reasons.append("wireguard_tool_missing")
+ elif not wireguard_kernel_ready:
+ reasons.append("wireguard_kernel_unavailable")
+ if fabric_interface_present and (
+ not fabric_owned or not fabric_interface_is_wireguard):
+ # The first deployment owns this name exclusively. A pre-existing
+ # interface may belong to an operator or another tenant; without an
+ # ownership marker it is unsafe to overwrite keys, peers, or routes.
+ reasons.append("wireguard_fabric_interface_conflict")
+ if not tool_state["ip"]["available"]:
+ reasons.append("iproute2_missing")
+ elif not ip_probe_valid:
+ reasons.append("iproute2_probe_failed")
+ if not tool_state["nft"]["available"]:
+ reasons.append("nftables_tool_missing")
+ elif not nft_readable:
+ reasons.append("nftables_probe_failed")
+ if firewall_manager != "nftables":
+ reasons.append("firewall_owner_not_nftables")
+ if not forwarding_ready:
+ reasons.append("ipv4_forwarding_disabled_or_unknown")
+ if not rp_filter_ready:
+ reasons.append("rp_filter_not_compatible")
+ if network_manager == "conflict":
+ reasons.append("network_manager_conflict")
+ elif network_manager == "unknown":
+ reasons.append("network_manager_unknown")
+ if public_reason:
+ reasons.append(public_reason)
+ reasons = sorted(set(reasons))
+ private_ready = not any(reason in reasons for reason in (
+ "capability_probe_invalid", "unsupported_host_os", "wireguard_tool_missing",
+ "wireguard_kernel_unavailable", "iproute2_missing", "nftables_tool_missing",
+ "nftables_probe_failed", "firewall_owner_not_nftables",
+ "iproute2_probe_failed",
+ "ipv4_forwarding_disabled_or_unknown", "rp_filter_not_compatible",
+ "network_manager_conflict", "wireguard_fabric_interface_conflict",
+ "network_manager_unknown",
+ ))
+ vpc_ready = private_ready and public_verified
+
+ return {
+ "schema_version": HOST_CAPABILITY_SCHEMA_VERSION,
+ "probe_protocol": _CAPABILITY_MARKER,
+ "probe_valid": protocol_ok,
+ "os": {
+ "id": os_id,
+ "name": os_values.get("NAME", ""),
+ "version_id": version_id,
+ "family": family,
+ "package_manager": package_manager,
+ "supported": os_supported,
+ "package_tool": package_tool,
+ "package_tool_available": package_tool_ready,
+ },
+ "kernel": kernel,
+ "tools": tool_state,
+ "network": {
+ "network_manager": network_manager,
+ "firewall_manager": firewall_manager,
+ "ip_probe_valid": ip_probe_valid,
+ "bridges": bridge_names,
+ "interfaces": all_interfaces,
+ "wireguard_interfaces": wireguard_names,
+ "ip_forward": ip_forward,
+ "rp_filter": rp_filter,
+ "rp_filter_default": rp_filter_default,
+ "rp_filter_interfaces": rp_filter_interfaces,
+ },
+ "wireguard": {
+ "interface": WG_FABRIC_INTERFACE,
+ "tool_available": bool(tool_state["wg"]["available"]),
+ "kernel_module_loaded": module_loaded,
+ "kernel_module_file": module_file,
+ "ready": wireguard_ready,
+ "interface_present": WG_FABRIC_INTERFACE in wireguard_names,
+ "interface_name_reserved": fabric_interface_present,
+ "interface_is_wireguard": fabric_interface_is_wireguard,
+ "ownership_marker": fabric_owner_marker or None,
+ "owned_by_panel": fabric_owned,
+ # The reconciler deliberately uses direct `ip` + `wg` commands
+ # behind the private SSH boundary. wg-quick is only evidence for
+ # an optional operator persistence path, never a prerequisite.
+ "deployment_mode": "direct_ip_wg",
+ "wg_quick_available": bool(tool_state["wg_quick"]["available"]),
+ },
+ "nftables": {
+ "tool_available": bool(tool_state["nft"]["available"]),
+ "ruleset_readable": nft_readable,
+ "owner": firewall_manager,
+ "ready": nft_ready,
+ },
+ "network_roles": {
+ "public": {
+ "guest_alias": "public0",
+ "selector": selector,
+ "selector_kind": public_selector_kind,
+ "bridge": bridge,
+ "verified": public_verified,
+ },
+ "private": {
+ "guest_alias": "private0",
+ "kind": "l3_wireguard",
+ "host_interface": WG_FABRIC_INTERFACE,
+ "separate_from_public": True,
+ "verified": private_ready,
+ },
+ },
+ "private_ready": private_ready,
+ "vpc_ready": vpc_ready,
+ "reasons": reasons,
+ }
+
+
class RemoteHostManager:
"""Prepare, test, and atomically select a root-key SSH generation."""
@@ -792,7 +1383,15 @@ class RemoteHostManager:
raise
def test(self, staged: StagedHost) -> dict[str, Any]:
- """Check the staged key, pinned host key, SSH, and remote libvirt."""
+ """Check SSH/libvirt and return a read-only host capability snapshot.
+
+ Capability gaps deliberately do not reject saving an existing public
+ host yet: the public VM path has a separate compatibility boundary.
+ VPC/Fabric callers must require ``capabilities.vpc_ready`` and treat a
+ false value as unsupported. This keeps the probe useful during the
+ staged rollout while preventing a future private-network operation
+ from guessing when bridge, WireGuard, or firewall evidence is absent.
+ """
self._check_staged(staged)
result = self._exec(
[
@@ -814,8 +1413,31 @@ class RemoteHostManager:
"SSH 或宿主机 libvirt 连接失败;请检查 root 密钥、端口、主机指纹和 virsh 服务",
status=502,
)
+ probe = self._exec(
+ [
+ self.ssh_binary,
+ "-F",
+ staged.ssh_config_file,
+ "-T",
+ "-o",
+ "ConnectTimeout=10",
+ SSH_ALIAS,
+ _CAPABILITY_PROBE_COMMAND,
+ ],
+ timeout=22,
+ )
+ capabilities = parse_host_capabilities(
+ probe.stdout if probe.returncode == 0 else "",
+ public_network=staged.metadata.get("default_network", ""),
+ )
+ staged.metadata["capabilities"] = capabilities
staged.tested = True
- return {"ok": True, "ssh": "connected", "libvirt": "available"}
+ return {
+ "ok": True,
+ "ssh": "connected",
+ "libvirt": "available",
+ "capabilities": capabilities,
+ }
def _check_staged(self, staged: StagedHost) -> None:
if not isinstance(staged, StagedHost) or staged.path.parent != self.data_dir / "generations":
@@ -850,12 +1472,37 @@ class RemoteHostManager:
else:
user_config.symlink_to(destination)
+ @staticmethod
+ def _replace_profile_metadata(staged: StagedHost) -> None:
+ """Atomically persist probe metadata without following a symlink."""
+ profile_path = staged.path / "profile.json"
+ try:
+ info = profile_path.lstat()
+ except OSError as exc:
+ raise RemoteHostError("暂存宿主机配置损坏", status=500) from exc
+ if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
+ raise RemoteHostError("暂存宿主机配置权限无效", status=500)
+ temporary = staged.path / (".profile-" + secrets.token_hex(8))
+ try:
+ _write_private(
+ temporary,
+ json.dumps(staged.metadata, ensure_ascii=False).encode("utf-8"),
+ )
+ os.replace(temporary, profile_path)
+ finally:
+ temporary.unlink(missing_ok=True)
+
def commit(self, staged: StagedHost) -> dict[str, Any]:
"""Activate a previously tested generation with one atomic symlink swap."""
with self._lock:
self._check_staged(staged)
if not staged.tested:
raise RemoteHostError("保存前必须先测试宿主机连接", status=409)
+ # Persist only the normalized capability contract. Older staged
+ # generations may have no snapshot and remain valid for the
+ # public path.
+ if "capabilities" in staged.metadata:
+ self._replace_profile_metadata(staged)
self._ensure_user_ssh_config()
previous = self._current_generation()
link = self.data_dir / (".current-" + secrets.token_hex(8))
@@ -1025,7 +1672,11 @@ class RemoteHostManager:
)
except RemoteHostError as exc:
raise RemoteHostError("已保存的宿主机配置损坏", status=500) from exc
- return {
+ has_capabilities = "capabilities" in metadata
+ capabilities = metadata.get("capabilities")
+ if has_capabilities and not isinstance(capabilities, dict):
+ raise RemoteHostError("已保存的宿主机能力快照损坏", status=500)
+ result = {
**{field: metadata[field] for field in fields},
"rescue_iso_pool": rescue_iso_pool,
"region": region,
@@ -1039,6 +1690,9 @@ class RemoteHostManager:
"ssh_config_file": str(generation / "config"),
"ssh_known_hosts_file": str(generation / "known_hosts"),
}
+ if has_capabilities:
+ result["capabilities"] = capabilities
+ return result
# A clearer name for callers that prefer "store" terminology.
diff --git a/web/app/Models/CloudPrivateCidrAllocatorConfig.php b/web/app/Models/CloudPrivateCidrAllocatorConfig.php
new file mode 100644
index 00000000..0463decb
--- /dev/null
+++ b/web/app/Models/CloudPrivateCidrAllocatorConfig.php
@@ -0,0 +1,19 @@
+ 'int',
+ 'quantum_prefix_length' => 'int',
+ 'min_prefix_length' => 'int',
+ 'max_prefix_length' => 'int',
+ 'revision' => 'int',
+ 'updated_at' => 'int',
+ ];
+}
diff --git a/web/app/Models/CloudPrivateCidrClaim.php b/web/app/Models/CloudPrivateCidrClaim.php
new file mode 100644
index 00000000..585f72ba
--- /dev/null
+++ b/web/app/Models/CloudPrivateCidrClaim.php
@@ -0,0 +1,15 @@
+ 'int',
+ 'created_at' => 'int',
+ ];
+}
diff --git a/web/app/Models/CloudPrivateNetwork.php b/web/app/Models/CloudPrivateNetwork.php
new file mode 100644
index 00000000..b1290b2e
--- /dev/null
+++ b/web/app/Models/CloudPrivateNetwork.php
@@ -0,0 +1,23 @@
+ 'int',
+ 'user_id' => 'int',
+ 'region_id' => 'int',
+ 'network_address' => 'int',
+ 'broadcast_address' => 'int',
+ 'prefix_length' => 'int',
+ 'revision' => 'int',
+ 'created_at' => 'int',
+ 'updated_at' => 'int',
+ 'released_at' => 'int',
+ ];
+}
diff --git a/web/app/Services/Cloud/CloudPrivateCidrAllocator.php b/web/app/Services/Cloud/CloudPrivateCidrAllocator.php
new file mode 100644
index 00000000..dd6c4b2c
--- /dev/null
+++ b/web/app/Services/Cloud/CloudPrivateCidrAllocator.php
@@ -0,0 +1,511 @@
+getConnection();
+
+ for ($attempt = 0; $attempt < self::MAX_ALLOCATION_RETRIES; $attempt++) {
+ try {
+ return $connection->transaction(function () use (
+ $allocationKey, $userId, $regionId, $requestedCidr,
+ $requested, $prefixLength, $vpcKey, $providedVpcKey
+ ): CloudPrivateNetwork {
+ $config = CloudPrivateCidrAllocatorConfig::where(
+ 'id', self::CONFIG_ID
+ )->first();
+ if ($config === null) {
+ throw new CloudError('私网 CIDR 分配器尚未初始化', 503);
+ }
+ $pool = self::poolConfig($config);
+ self::assertPrefixAllowed($prefixLength, $pool);
+
+ $existing = CloudPrivateNetwork::where(
+ 'allocation_key', $allocationKey
+ )->lockForUpdate()->first();
+ if ($existing !== null) {
+ self::assertIdempotent(
+ $existing,
+ $providedVpcKey === null
+ ? (string) $existing->vpc_key : $vpcKey,
+ $userId, $regionId, $requestedCidr, $prefixLength,
+ );
+ return $existing;
+ }
+ $sameVpc = CloudPrivateNetwork::where('vpc_key', $vpcKey)
+ ->lockForUpdate()->first();
+ if ($sameVpc !== null) {
+ throw new CloudError('该 VPC 已存在私网 CIDR 分配', 409);
+ }
+
+ if ($requested !== null
+ && !self::within(
+ $requested['network'], $requested['broadcast'], $pool
+ )) {
+ throw new CloudError('请求的私网 CIDR 不在全局地址池内', 409);
+ }
+ $occupied = self::occupied($pool);
+ $candidate = $requested ?? self::firstFree(
+ $occupied, $pool, $prefixLength
+ );
+ if ($candidate === null) {
+ throw new CloudError('全局私网 CIDR 地址池已耗尽', 409);
+ }
+ foreach ($occupied as $row) {
+ if (self::overlaps(
+ $candidate['network'], $candidate['broadcast'], $row
+ )) {
+ throw new CloudError('请求的私网 CIDR 与现有 VPC 重叠', 409);
+ }
+ }
+
+ self::claimCandidate($candidate, $allocationKey);
+ $now = time();
+ $network = new CloudPrivateNetwork();
+ $network->vpc_key = $vpcKey;
+ $network->allocation_key = $allocationKey;
+ $network->user_id = $userId;
+ $network->region_id = $regionId;
+ $network->cidr = $candidate['cidr'];
+ $network->requested_cidr = $requested === null
+ ? null : $requested['cidr'];
+ $network->active_cidr = $candidate['cidr'];
+ $network->network_address = $candidate['network'];
+ $network->broadcast_address = $candidate['broadcast'];
+ $network->prefix_length = $candidate['prefix'];
+ $network->state = 'active';
+ $network->revision = 1;
+ $network->created_at = $now;
+ $network->updated_at = $now;
+ $network->released_at = null;
+ $network->save();
+ return $network;
+ });
+ } catch (\Throwable $error) {
+ // A unique claim/network key can be lost to a concurrent
+ // worker. A fresh transaction observes its committed row and
+ // either returns an idempotent result or chooses the next
+ // free candidate. Explicit requests eventually become a
+ // normal 409 once the winner is visible.
+ if (!self::isDuplicateKey($error)
+ && !self::isTransientConflict($error)
+ && !($error instanceof CloudPrivateCidrClaimConflict)) {
+ throw $error;
+ }
+ if ($attempt + 1 >= self::MAX_ALLOCATION_RETRIES) {
+ throw new CloudError(
+ $requested === null
+ ? '私网 CIDR 并发分配冲突,请稍后重试'
+ : '请求的私网 CIDR 已被其他 VPC 占用',
+ 409,
+ );
+ }
+ }
+ }
+
+ throw new CloudError('私网 CIDR 分配未完成,请稍后重试', 409);
+ }
+
+ /** Compare-and-swap a network lifecycle state under its own row lock. */
+ public static function compareAndSwapState(string $allocationKey,
+ int $expectedRevision, string $from, string $to): CloudPrivateNetwork
+ {
+ self::assertKey($allocationKey, 'CIDR 分配请求');
+ if ($expectedRevision < 1 || !in_array($from, self::LIVE_STATES, true)
+ || !in_array($to, self::STATES, true)) {
+ throw new CloudError('私网 CIDR 状态变更参数无效', 422);
+ }
+ return self::transition($allocationKey, $expectedRevision, $from, $to);
+ }
+
+ /** Release any live allocation with an explicit revision check. */
+ public static function release(string $allocationKey, int $expectedRevision): CloudPrivateNetwork
+ {
+ self::assertKey($allocationKey, 'CIDR 分配请求');
+ if ($expectedRevision < 1) {
+ throw new CloudError('私网 CIDR 状态变更参数无效', 422);
+ }
+ $connection = (new CloudPrivateNetwork())->getConnection();
+ return $connection->transaction(function () use (
+ $allocationKey, $expectedRevision
+ ): CloudPrivateNetwork {
+ $network = CloudPrivateNetwork::where('allocation_key', $allocationKey)
+ ->lockForUpdate()->first();
+ if ($network === null) {
+ throw new CloudError('私网 CIDR 分配记录不存在', 404);
+ }
+ if (!in_array((string) $network->state, self::LIVE_STATES, true)
+ || (int) $network->revision !== $expectedRevision) {
+ throw new CloudError('私网 CIDR 状态已被其他操作更新,请重新读取', 409);
+ }
+ self::deleteClaims($allocationKey);
+ return self::markReleased($network, $expectedRevision);
+ });
+ }
+
+ /** Return a canonical RFC1918 IPv4 network description without the DB. */
+ public static function normalize(string $cidr, ?int $expectedPrefix = null): array
+ {
+ $normalized = self::normalizeCidr($cidr, $expectedPrefix);
+ if (!self::isRfc1918($normalized['network'], $normalized['broadcast'])) {
+ throw new CloudError('私网 CIDR 必须使用 RFC1918 地址', 422);
+ }
+ return $normalized;
+ }
+
+ private static function transition(string $allocationKey, int $expectedRevision,
+ string $from, string $to): CloudPrivateNetwork
+ {
+ $connection = (new CloudPrivateNetwork())->getConnection();
+ return $connection->transaction(function () use (
+ $allocationKey, $expectedRevision, $from, $to
+ ): CloudPrivateNetwork {
+ $network = CloudPrivateNetwork::where('allocation_key', $allocationKey)
+ ->lockForUpdate()->first();
+ if ($network === null) {
+ throw new CloudError('私网 CIDR 分配记录不存在', 404);
+ }
+ if ((int) $network->revision !== $expectedRevision
+ || (string) $network->state !== $from) {
+ throw new CloudError('私网 CIDR 状态已被其他操作更新,请重新读取', 409);
+ }
+ if ($to === 'released') {
+ self::deleteClaims($allocationKey);
+ return self::markReleased($network, $expectedRevision);
+ }
+ if ($network->active_cidr === null) {
+ throw new CloudError('已释放的私网 CIDR 不允许恢复', 409);
+ }
+ $network->state = $to;
+ $network->revision = $expectedRevision + 1;
+ $network->updated_at = time();
+ $network->save();
+ return $network;
+ });
+ }
+
+ private static function markReleased(CloudPrivateNetwork $network,
+ int $expectedRevision): CloudPrivateNetwork
+ {
+ $network->state = 'released';
+ $network->revision = $expectedRevision + 1;
+ $network->active_cidr = null;
+ $network->released_at = time();
+ $network->updated_at = (int) $network->released_at;
+ $network->save();
+ return $network;
+ }
+
+ private static function deleteClaims(string $allocationKey): void
+ {
+ CloudPrivateCidrClaim::where('allocation_key', $allocationKey)->delete();
+ }
+
+ /** @param array{network:int,broadcast:int,cidr:string,prefix:int} $candidate */
+ private static function claimCandidate(array $candidate, string $allocationKey): void
+ {
+ $blockSize = self::blockSize(self::QUANTUM_PREFIX_LENGTH);
+ $count = 1 << (self::QUANTUM_PREFIX_LENGTH - $candidate['prefix']);
+ for ($index = 0; $index < $count; $index++) {
+ $block = self::description(
+ $candidate['network'] + ($index * $blockSize),
+ self::QUANTUM_PREFIX_LENGTH,
+ );
+ $claim = new CloudPrivateCidrClaim();
+ $claim->block_cidr = $block['cidr'];
+ $claim->allocation_key = $allocationKey;
+ $claim->created_at = time();
+ try {
+ $claim->save();
+ } catch (\Throwable $error) {
+ if (self::isDuplicateKey($error)) {
+ throw new CloudPrivateCidrClaimConflict($error->getMessage(), 0, $error);
+ }
+ throw $error;
+ }
+ }
+ }
+
+ /** @return array{pool:string,pool_network:int,pool_broadcast:int,min_prefix:int,max_prefix:int,quantum_prefix:int} */
+ private static function poolConfig(CloudPrivateCidrAllocatorConfig $config): array
+ {
+ $pool = self::normalizeCidr((string) $config->pool_cidr);
+ $min = (int) $config->min_prefix_length;
+ $max = (int) $config->max_prefix_length;
+ $quantum = (int) $config->quantum_prefix_length;
+ if ($quantum !== self::QUANTUM_PREFIX_LENGTH
+ || $min < $pool['prefix'] || $min > $max || $max > $quantum
+ || $pool['prefix'] > $quantum) {
+ throw new CloudError('私网 CIDR 分配器配置无效', 503);
+ }
+ $poolNetwork = self::ipv4ToInt($pool['network_address']);
+ $poolBroadcast = self::ipv4ToInt($pool['broadcast_address']);
+ if (!self::isRfc1918($poolNetwork, $poolBroadcast)) {
+ throw new CloudError('私网 CIDR 分配器必须使用 RFC1918 地址池', 503);
+ }
+ return [
+ 'pool' => $pool['cidr'],
+ 'pool_network' => $poolNetwork,
+ 'pool_broadcast' => $poolBroadcast,
+ 'min_prefix' => $min,
+ 'max_prefix' => $max,
+ 'quantum_prefix' => $quantum,
+ ];
+ }
+
+ /** @param array{min_prefix:int,max_prefix:int} $pool */
+ private static function assertPrefixAllowed(int $prefix, array $pool): void
+ {
+ if ($prefix < $pool['min_prefix'] || $prefix > $pool['max_prefix']
+ || $prefix > self::QUANTUM_PREFIX_LENGTH) {
+ throw new CloudError('私网 CIDR 前缀不在分配器允许范围内', 422);
+ }
+ }
+
+ /** @param array{pool_network:int,pool_broadcast:int,min_prefix:int,max_prefix:int} $pool */
+ private static function occupied(array $pool): array
+ {
+ $rows = CloudPrivateNetwork::orderBy('network_address')->orderBy('id')
+ ->get()->all();
+ $occupied = [];
+ foreach ($rows as $row) {
+ $state = (string) $row->state;
+ if ($state === 'released') {
+ if ($row->active_cidr !== null) {
+ throw new CloudError('已释放私网 CIDR 账本不一致,已停止分配', 503);
+ }
+ continue;
+ }
+ if (!in_array($state, self::LIVE_STATES, true)) {
+ throw new CloudError('未知私网 CIDR 状态,已停止分配', 503);
+ }
+ $network = (int) $row->network_address;
+ $broadcast = (int) $row->broadcast_address;
+ $prefix = (int) $row->prefix_length;
+ $expected = self::description($network, $prefix);
+ if ($network < $pool['pool_network']
+ || $broadcast > $pool['pool_broadcast']
+ || $network > $broadcast
+ || $prefix < $pool['min_prefix']
+ || $prefix > $pool['max_prefix']
+ || (string) ($row->active_cidr ?? '') !== (string) $row->cidr
+ || (string) $row->cidr !== $expected['cidr']
+ || $broadcast !== $expected['broadcast']) {
+ throw new CloudError('现有私网 CIDR 账本不一致,已停止分配', 503);
+ }
+ $occupied[] = $row;
+ }
+ return $occupied;
+ }
+
+ /** @param array{pool_network:int,pool_broadcast:int} $pool */
+ private static function firstFree(array $occupied, array $pool, int $prefix): ?array
+ {
+ $blockSize = self::blockSize($prefix);
+ $candidate = $pool['pool_network'];
+ foreach ($occupied as $row) {
+ $start = (int) $row->network_address;
+ $end = (int) $row->broadcast_address;
+ if ($end < $candidate) {
+ continue;
+ }
+ if ($start > $candidate && $candidate + $blockSize - 1 < $start) {
+ break;
+ }
+ $next = $end + 1;
+ $offset = $next - $pool['pool_network'];
+ $alignedBlocks = intdiv($offset + $blockSize - 1, $blockSize);
+ $candidate = $pool['pool_network'] + ($alignedBlocks * $blockSize);
+ }
+ if ($candidate < $pool['pool_network']
+ || $candidate + $blockSize - 1 > $pool['pool_broadcast']) {
+ return null;
+ }
+ return self::description($candidate, $prefix);
+ }
+
+ /** @return array{cidr:string,network:int,broadcast:int,prefix:int,network_address:string,broadcast_address:string} */
+ private static function normalizeCidr(string $cidr, ?int $expectedPrefix = null): array
+ {
+ if (PHP_INT_SIZE < 8) {
+ throw new CloudError('当前 PHP 平台不支持安全的 IPv4 CIDR 分配', 503);
+ }
+ $parts = explode('/', trim($cidr), 2);
+ if (count($parts) !== 2 || filter_var($parts[0], FILTER_VALIDATE_IP,
+ FILTER_FLAG_IPV4) === false || preg_match(
+ '/^(?:[0-9]|[12][0-9]|3[0-2])$/D', $parts[1]
+ ) !== 1) {
+ throw new CloudError('私网 CIDR 格式无效', 422);
+ }
+ $prefix = (int) $parts[1];
+ if ($expectedPrefix !== null && $prefix !== $expectedPrefix) {
+ throw new CloudError('私网 CIDR 前缀与请求不一致', 422);
+ }
+ $address = self::ipv4ToInt($parts[0]);
+ $blockSize = self::blockSize($prefix);
+ $network = intdiv($address, $blockSize) * $blockSize;
+ $broadcast = $network + $blockSize - 1;
+ return self::description($network, $prefix, $broadcast);
+ }
+
+ private static function description(int $network, int $prefix,
+ ?int $broadcast = null): array
+ {
+ $broadcast ??= $network + self::blockSize($prefix) - 1;
+ return [
+ 'cidr' => self::intToIpv4($network) . '/' . $prefix,
+ 'network' => $network,
+ 'broadcast' => $broadcast,
+ 'prefix' => $prefix,
+ 'network_address' => self::intToIpv4($network),
+ 'broadcast_address' => self::intToIpv4($broadcast),
+ ];
+ }
+
+ /** @param array{network:int,broadcast:int} $candidate */
+ private static function within(int $network, int $broadcast, array $pool): bool
+ {
+ return $network >= $pool['pool_network']
+ && $broadcast <= $pool['pool_broadcast'];
+ }
+
+ /** @param object{network_address:int,broadcast_address:int} $row */
+ private static function overlaps(int $network, int $broadcast, $row): bool
+ {
+ return $network <= (int) $row->broadcast_address
+ && $broadcast >= (int) $row->network_address;
+ }
+
+ private static function blockSize(int $prefix): int
+ {
+ if ($prefix < 0 || $prefix > 30) {
+ throw new CloudError('私网 CIDR 前缀无效', 422);
+ }
+ return 1 << (32 - $prefix);
+ }
+
+ private static function ipv4ToInt(string $value): int
+ {
+ $packed = inet_pton($value);
+ if ($packed === false || strlen($packed) !== 4) {
+ throw new CloudError('私网 CIDR 地址无效', 422);
+ }
+ $parts = unpack('Nnumber', $packed);
+ if (!is_array($parts) || !isset($parts['number'])) {
+ throw new CloudError('私网 CIDR 地址无效', 422);
+ }
+ return (int) sprintf('%u', $parts['number']);
+ }
+
+ private static function intToIpv4(int $value): string
+ {
+ if ($value < 0 || $value > 4294967295) {
+ throw new CloudError('私网 CIDR 地址超出 IPv4 范围', 422);
+ }
+ $packed = pack('N', $value);
+ $result = inet_ntop($packed);
+ if ($result === false) {
+ throw new CloudError('私网 CIDR 地址无效', 422);
+ }
+ return $result;
+ }
+
+ private static function isRfc1918(int $network, int $broadcast): bool
+ {
+ foreach ([
+ [self::ipv4ToInt('10.0.0.0'), self::ipv4ToInt('10.255.255.255')],
+ [self::ipv4ToInt('172.16.0.0'), self::ipv4ToInt('172.31.255.255')],
+ [self::ipv4ToInt('192.168.0.0'), self::ipv4ToInt('192.168.255.255')],
+ ] as [$start, $end]) {
+ if ($network >= $start && $broadcast <= $end) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ private static function assertKey(string $value, string $label): void
+ {
+ if (preg_match('/^[a-f0-9]{32}$/D', $value) !== 1) {
+ throw new CloudError($label . '标识无效', 422);
+ }
+ }
+
+ private static function assertIdempotent(CloudPrivateNetwork $existing,
+ string $vpcKey, int $userId, int $regionId,
+ ?string $requestedCidr, int $prefixLength): void
+ {
+ $requested = $requestedCidr === null ? null
+ : self::normalizeCidr($requestedCidr, $prefixLength)['cidr'];
+ if ((string) $existing->vpc_key !== $vpcKey
+ || (int) $existing->user_id !== $userId
+ || (int) $existing->region_id !== $regionId
+ || (int) $existing->prefix_length !== $prefixLength
+ || (string) ($existing->requested_cidr ?? '')
+ !== (string) ($requested ?? '')) {
+ throw new CloudError('CIDR 分配请求标识已用于另一组参数', 409);
+ }
+ }
+
+ private static function isDuplicateKey(\Throwable $error): bool
+ {
+ $info = isset($error->errorInfo) ? $error->errorInfo : null;
+ return is_array($info) && (($info[0] ?? null) === '23000'
+ || (int) ($info[1] ?? 0) === 1062)
+ || str_contains(strtolower($error->getMessage()), 'duplicate');
+ }
+
+ private static function isTransientConflict(\Throwable $error): bool
+ {
+ $info = isset($error->errorInfo) ? $error->errorInfo : null;
+ $sqlState = is_array($info) ? (string) ($info[0] ?? '') : '';
+ $driverCode = is_array($info) ? (int) ($info[1] ?? 0) : 0;
+ return $sqlState === '40001' || in_array($driverCode, [1205, 1213], true);
+ }
+}
diff --git a/web/app/Services/Cloud/CloudPrivateCidrClaimConflict.php b/web/app/Services/Cloud/CloudPrivateCidrClaimConflict.php
new file mode 100644
index 00000000..56bd69f5
--- /dev/null
+++ b/web/app/Services/Cloud/CloudPrivateCidrClaimConflict.php
@@ -0,0 +1,8 @@
+transaction(')
+ && str_contains($serviceSource, 'self::LIVE_STATES')
+ && str_contains($serviceSource, '未知私网 CIDR 状态')
+ && str_contains($serviceSource, 'compareAndSwapState')
+ && str_contains($serviceSource, 'active_cidr')
+ && str_contains($serviceSource, 'isTransientConflict')
+ && !str_contains($serviceSource, 'CloudPrivateCidrAllocatorLock')
+ && !str_contains($serviceSource, "CloudPrivateCidrAllocatorConfig::where(\n 'id', self::CONFIG_ID\n )->lockForUpdate()"),
+ 'CIDR allocation no longer uses a database transaction, overlap ledger and CAS.');
+$assert(is_string($modelSource)
+ && str_contains($modelSource, "protected \$table = 'cloud_private_networks';")
+ && is_string($configModelSource)
+ && str_contains($configModelSource,
+ "protected \$table = 'cloud_private_cidr_allocator_configs';")
+ && is_string($claimModelSource)
+ && str_contains($claimModelSource,
+ "protected \$table = 'cloud_private_cidr_claims';"),
+ 'Private CIDR Eloquent boundaries are missing.');
+
+if (!is_file($root . '/vendor/autoload.php')) {
+ echo "Cloud private CIDR schema and source contracts passed (runtime skipped).\n";
+ return;
+}
+require $root . '/vendor/autoload.php';
+
+$capsule = new Capsule();
+$capsule->addConnection(['driver' => 'sqlite', 'database' => ':memory:'], 'default');
+$capsule->setAsGlobal();
+$capsule->bootEloquent();
+$schema = $capsule->schema('default');
+$schema->create('cloud_private_cidr_allocator_configs', static function (Blueprint $table): void {
+ $table->unsignedTinyInteger('id')->primary();
+ $table->string('pool_cidr', 18);
+ $table->unsignedTinyInteger('quantum_prefix_length');
+ $table->unsignedTinyInteger('min_prefix_length');
+ $table->unsignedTinyInteger('max_prefix_length');
+ $table->unsignedBigInteger('revision');
+ $table->unsignedBigInteger('updated_at');
+});
+$schema->create('cloud_private_cidr_claims', static function (Blueprint $table): void {
+ $table->increments('id');
+ $table->string('block_cidr', 18)->unique();
+ $table->string('allocation_key', 32);
+ $table->unsignedBigInteger('created_at');
+ $table->index(['allocation_key', 'block_cidr']);
+});
+$schema->create('cloud_private_networks', static function (Blueprint $table): void {
+ $table->increments('id');
+ $table->string('vpc_key', 32)->unique();
+ $table->string('allocation_key', 32)->unique();
+ $table->unsignedInteger('user_id');
+ $table->unsignedInteger('region_id');
+ $table->string('cidr', 18);
+ $table->string('requested_cidr', 18)->nullable();
+ $table->string('active_cidr', 18)->nullable()->unique();
+ $table->unsignedBigInteger('network_address');
+ $table->unsignedBigInteger('broadcast_address');
+ $table->unsignedTinyInteger('prefix_length');
+ $table->string('state', 16);
+ $table->unsignedBigInteger('revision');
+ $table->unsignedBigInteger('created_at');
+ $table->unsignedBigInteger('updated_at');
+ $table->unsignedBigInteger('released_at')->nullable();
+});
+$config = new CloudPrivateCidrAllocatorConfig();
+$config->id = 1;
+$config->pool_cidr = '10.0.0.0/8';
+$config->quantum_prefix_length = 24;
+$config->min_prefix_length = 16;
+$config->max_prefix_length = 24;
+$config->revision = 1;
+$config->updated_at = time();
+$config->save();
+
+$key = str_repeat('a', 32);
+$vpc = str_repeat('b', 32);
+$first = CloudPrivateCidrAllocator::allocate($key, 7, 1, null, 24, $vpc);
+$assert($first->cidr === '10.0.0.0/24'
+ && $first->active_cidr === $first->cidr, 'First global CIDR was not canonical.');
+$assert(CloudPrivateCidrClaim::where('allocation_key', $key)->count() === 1,
+ 'The active network did not claim its /24 quantum.');
+$second = CloudPrivateCidrAllocator::allocate(str_repeat('c', 32), 8, 2,
+ null, 24, str_repeat('d', 32));
+$assert($second->cidr === '10.0.1.0/24',
+ 'Automatic CIDR allocation did not advance to the next aligned block.');
+$retry = CloudPrivateCidrAllocator::allocate($key, 7, 1, null, 24, $vpc);
+$assert((int) $retry->id === (int) $first->id,
+ 'A repeated allocation key created a second private network.');
+
+$expectConflict = static function (callable $operation, string $message) use ($assert): void {
+ try {
+ $operation();
+ } catch (CloudError $error) {
+ $assert($error->httpStatus === 409, $message . ' returned the wrong status.');
+ return;
+ }
+ throw new RuntimeException($message);
+};
+$expectConflict(static fn () => CloudPrivateCidrAllocator::allocate(
+ str_repeat('e', 32), 9, 3, '10.0.0.1/24', 24, str_repeat('f', 32)
+), 'Overlapping CIDR was accepted.');
+$expectConflict(static fn () => CloudPrivateCidrAllocator::allocate(
+ $key, 99, 1, null, 24, $vpc
+), 'Allocation-key parameter drift was accepted.');
+
+$released = CloudPrivateCidrAllocator::release($key, 1);
+$assert($released->state === 'released' && $released->active_cidr === null
+ && (int) $released->revision === 2,
+ 'Release did not clear the active claim and advance its revision.');
+$assert(CloudPrivateCidrClaim::where('allocation_key', $key)->count() === 0,
+ 'Release did not remove the reusable quantum claim.');
+$reused = CloudPrivateCidrAllocator::allocate(str_repeat('1', 32), 10, 1,
+ '10.0.0.0/24', 24, str_repeat('2', 32));
+$assert($reused->cidr === '10.0.0.0/24',
+ 'A released CIDR was not safely reusable under quantum claims.');
+$expectConflict(static fn () => CloudPrivateCidrAllocator::release($key, 1),
+ 'A stale revision released a CIDR a second time.');
+
+$normalized = CloudPrivateCidrAllocator::normalize('10.2.3.4/16', 16);
+$assert($normalized['cidr'] === '10.2.0.0/16'
+ && $normalized['broadcast_address'] === '10.2.255.255',
+ 'CIDR canonicalisation or broadcast calculation is incorrect.');
+
+echo "Cloud private CIDR allocation schema, overlap, idempotency, release and CAS tests passed.\n";