feat: add VPC network preaccess contracts

venix
admin 1 month ago
parent 887072ac61
commit 4046a895ea

@ -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 可能已部分提交,仅回退源码不足以解除维护锁。

@ -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():

@ -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(
"<interface><alias name='public0'/><mac address='52:54:00:12:34:56'/>"
"<source bridge='br0'/></interface>"
)
private = ET.fromstring(
"<interface><alias name='private0'/><mac address='52:54:00:12:34:57'/>"
"<source bridge='vpc0'/></interface>"
)
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(
"<interface><alias name='private0'/><mac address='52:54:00:12:34:57'/>"
"<source network='private-net'/></interface>"
)
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"

@ -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(
"<interface><alias name='public0'/><source bridge='br0'/></interface>"
)
private = ET.fromstring(
"<interface><source bridge='vpc0'/><alias name='private0'/></interface>"
)
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(
"<interface><source bridge='vpc0'/><filterref filter='clean-traffic'/></interface>"
)
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(
"<interface><alias name='public0'/><source bridge='br0'/></interface>"
)
unknown = ET.fromstring("<interface><source bridge='vpc0'/></interface>")
with pytest.raises(ValueError, match="声明"):
select_public_interface([public, unknown])
def test_explicit_public_private_pair_selects_public_interface():
public = ET.fromstring("<interface><alias name='public0'/></interface>")
private = ET.fromstring("<interface><alias name='private0'/></interface>")
assert select_public_interface([private, public]) is public
def test_legacy_single_public_nic_can_still_be_updated():
legacy = ET.fromstring("<interface><source bridge='br0'/></interface>")
assert interface_role(legacy) == "unknown"
assert interface_role(legacy, legacy_public=True) == "public"
assert_public_interface(legacy, legacy_public=True)
generated = ET.fromstring(
"<interface><alias name='net0'/><source bridge='br0'/></interface>"
)
assert interface_role(generated) == "unknown"
assert select_public_interface([generated]) is generated
assert_public_interface(generated, legacy_public=True)
renamed = ET.fromstring(
"<interface><alias name='operator0'/><source bridge='br0'/></interface>"
)
with pytest.raises(ValueError):
select_public_interface([renamed])
def test_private_selection_requires_one_explicit_private_role():
private = ET.fromstring(
"<interface><alias name='private0'/><source bridge='vpc0'/></interface>"
)
public = ET.fromstring(
"<interface><alias name='public0'/><source bridge='br0'/></interface>"
)
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(
"<interface><alias name='private0'/></interface>")])
@pytest.mark.parametrize("alias", ["net0", "ua-net-0"])
def test_libvirt_generated_single_nic_alias_is_legacy_public(alias):
legacy = ET.fromstring(
f"<interface><alias name='{alias}'/><source bridge='br0'/></interface>"
)
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(
"<interface><alias name='public0'/><source bridge='br0'/></interface>"
)
legacy = ET.fromstring(
"<interface><alias name='net1'/><source bridge='vpc0'/></interface>"
)
with pytest.raises(ValueError, match="声明"):
select_public_interface([public, legacy])

@ -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)

@ -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:

@ -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

@ -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):

@ -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"))

@ -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.

@ -0,0 +1,19 @@
<?php
namespace App\Models;
/** Immutable-ish operator configuration for the global private CIDR pool. */
final class CloudPrivateCidrAllocatorConfig extends Model
{
protected $connection = 'default';
protected $table = 'cloud_private_cidr_allocator_configs';
protected $casts = [
'id' => 'int',
'quantum_prefix_length' => 'int',
'min_prefix_length' => 'int',
'max_prefix_length' => 'int',
'revision' => 'int',
'updated_at' => 'int',
];
}

@ -0,0 +1,15 @@
<?php
namespace App\Models;
/** One /24 quantum claimed by a live private network allocation. */
final class CloudPrivateCidrClaim extends Model
{
protected $connection = 'default';
protected $table = 'cloud_private_cidr_claims';
protected $casts = [
'id' => 'int',
'created_at' => 'int',
];
}

@ -0,0 +1,23 @@
<?php
namespace App\Models;
/** One globally allocated, tenant-owned VPC network CIDR. */
final class CloudPrivateNetwork extends Model
{
protected $connection = 'default';
protected $table = 'cloud_private_networks';
protected $casts = [
'id' => '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',
];
}

@ -0,0 +1,511 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudPrivateCidrAllocatorConfig;
use App\Models\CloudPrivateCidrClaim;
use App\Models\CloudPrivateNetwork;
/**
* Concurrent allocator for the first VPC private-address release.
*
* The address space is global rather than host- or region-scoped. Allocation
* uses /24 quantum claims: every candidate claims each /24 it contains under
* one database transaction, and the unique block key is the conflict point.
* Independent candidates therefore proceed concurrently without a process or
* global mutex. A larger VPC CIDR simply claims more adjacent quantum rows.
*/
final class CloudPrivateCidrAllocator
{
public const CONFIG_ID = 1;
public const DEFAULT_POOL_CIDR = '10.0.0.0/8';
public const DEFAULT_MIN_PREFIX_LENGTH = 16;
public const DEFAULT_MAX_PREFIX_LENGTH = 24;
public const QUANTUM_PREFIX_LENGTH = 24;
private const MAX_ALLOCATION_RETRIES = 8;
private const LIVE_STATES = ['active', 'applying', 'degraded', 'uncertain'];
private const STATES = ['active', 'applying', 'degraded', 'uncertain', 'released'];
/**
* Allocate one globally unique private network.
*
* `$allocationKey` is the caller's durable idempotency key. A retry with
* the same key returns the original row only when all immutable request
* fields match. The optional request CIDR is canonicalised before the
* claim; omitted requests use first-fit aligned blocks.
*/
public static function allocate(string $allocationKey, int $userId, int $regionId,
?string $requestedCidr = null, int $prefixLength = self::DEFAULT_MAX_PREFIX_LENGTH,
?string $vpcKey = null): CloudPrivateNetwork
{
self::assertKey($allocationKey, 'CIDR 分配请求');
if ($userId < 1 || $regionId < 1) {
throw new CloudError('私网分配的用户或地区无效', 422);
}
$providedVpcKey = $vpcKey;
$vpcKey ??= substr(hash('sha256', 'virt-cloud-vpc:' . $allocationKey), 0, 32);
self::assertKey($vpcKey, 'VPC');
$requested = $requestedCidr === null
? null : self::normalizeCidr($requestedCidr, $prefixLength);
$connection = (new CloudPrivateNetwork())->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);
}
}

@ -0,0 +1,8 @@
<?php
namespace App\Services\Cloud;
/** Internal retry signal for a /24 claim lost to another allocator worker. */
final class CloudPrivateCidrClaimConflict extends \RuntimeException
{
}

@ -197,6 +197,64 @@ CREATE TABLE IF NOT EXISTS cloud_public_ip_pools (
KEY cloud_public_ip_pool_sync (host_id, sync_state, updated_at, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- Private VPC CIDRs are allocated from one configured global RFC1918 pool
-- (10.0.0.0/8 by default). Allocation uses /24 quantum claims rather than
-- a process-local or global application mutex: the unique block_cidr key is
-- the cross-worker serialization point. A /16 therefore claims 256 rows in
-- one transaction, while independent blocks can be allocated concurrently.
CREATE TABLE IF NOT EXISTS cloud_private_cidr_allocator_configs (
id TINYINT UNSIGNED NOT NULL PRIMARY KEY,
pool_cidr VARCHAR(18) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
quantum_prefix_length TINYINT UNSIGNED NOT NULL DEFAULT 24,
min_prefix_length TINYINT UNSIGNED NOT NULL DEFAULT 16,
max_prefix_length TINYINT UNSIGNED NOT NULL DEFAULT 24,
revision BIGINT UNSIGNED NOT NULL DEFAULT 1,
updated_at BIGINT UNSIGNED NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
INSERT IGNORE INTO cloud_private_cidr_allocator_configs
(id, pool_cidr, quantum_prefix_length, min_prefix_length, max_prefix_length,
revision, updated_at)
VALUES (1, '10.0.0.0/8', 24, 16, 24, 1, UNIX_TIMESTAMP());
CREATE TABLE IF NOT EXISTS cloud_private_cidr_claims (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
block_cidr VARCHAR(18) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
allocation_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
created_at BIGINT UNSIGNED NOT NULL,
UNIQUE KEY cloud_private_cidr_claim_block (block_cidr),
KEY cloud_private_cidr_claim_allocation (allocation_key, block_cidr)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- One row is one VPC network allocation. `network_address` and
-- `broadcast_address` make overlap checks explicit and indexable; the
-- canonical `active_cidr` unique key is an additional database guard for
-- exact duplicate claims. Interval overlap is serialized by the unique
-- quantum claims above because MariaDB has no exclusion constraint for
-- arbitrary ranges.
CREATE TABLE IF NOT EXISTS cloud_private_networks (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
vpc_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
allocation_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
user_id BIGINT UNSIGNED NOT NULL,
region_id BIGINT UNSIGNED NOT NULL,
cidr VARCHAR(18) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
requested_cidr VARCHAR(18) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL,
active_cidr VARCHAR(18) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL,
network_address BIGINT UNSIGNED NOT NULL,
broadcast_address BIGINT UNSIGNED NOT NULL,
prefix_length TINYINT UNSIGNED NOT NULL,
state VARCHAR(16) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'active',
revision BIGINT UNSIGNED NOT NULL DEFAULT 1,
created_at BIGINT UNSIGNED NOT NULL,
updated_at BIGINT UNSIGNED NOT NULL,
released_at BIGINT UNSIGNED DEFAULT NULL,
UNIQUE KEY cloud_private_network_vpc_key (vpc_key),
UNIQUE KEY cloud_private_network_allocation_key (allocation_key),
UNIQUE KEY cloud_private_network_active_cidr (active_cidr),
KEY cloud_private_network_overlap (state, network_address, broadcast_address, id),
KEY cloud_private_network_region (region_id, state, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- Operator limits and safety reserves are authoritative scheduling policy.
-- Zero configured capacity keeps a new host unschedulable until explicitly
-- configured; it never means unlimited capacity.

@ -0,0 +1,173 @@
<?php
use App\Models\CloudPrivateCidrAllocatorConfig;
use App\Models\CloudPrivateCidrClaim;
use App\Models\CloudPrivateNetwork;
use App\Services\Cloud\CloudError;
use App\Services\Cloud\CloudPrivateCidrAllocator;
use Illuminate\Database\Capsule\Manager as Capsule;
use Illuminate\Database\Schema\Blueprint;
// The contract portion is intentionally useful even on a checkout without a
// PHP runtime. The SQLite section below exercises canonicalisation,
// idempotency, overlap rejection, release/reuse and revision CAS when the
// project's normal PHP dependencies are available.
$root = dirname(__DIR__);
$schemaSource = file_get_contents($root . '/sql/cloud.sql');
$serviceSource = file_get_contents($root
. '/app/Services/Cloud/CloudPrivateCidrAllocator.php');
$modelSource = file_get_contents($root . '/app/Models/CloudPrivateNetwork.php');
$configModelSource = file_get_contents($root
. '/app/Models/CloudPrivateCidrAllocatorConfig.php');
$claimModelSource = file_get_contents($root
. '/app/Models/CloudPrivateCidrClaim.php');
$assert = static function ($condition, string $message): void {
if (!$condition) {
throw new RuntimeException($message);
}
};
$assert(is_string($schemaSource)
&& str_contains($schemaSource,
'CREATE TABLE IF NOT EXISTS cloud_private_cidr_allocator_configs (')
&& str_contains($schemaSource,
'CREATE TABLE IF NOT EXISTS cloud_private_cidr_claims (')
&& str_contains($schemaSource,
'CREATE TABLE IF NOT EXISTS cloud_private_networks (')
&& str_contains($schemaSource,
'UNIQUE KEY cloud_private_network_active_cidr (active_cidr)')
&& str_contains($schemaSource,
'UNIQUE KEY cloud_private_cidr_claim_block (block_cidr)')
&& str_contains($schemaSource, 'requested_cidr VARCHAR(18)')
&& str_contains($schemaSource,
'KEY cloud_private_network_overlap (state, network_address, broadcast_address, id)')
&& str_contains($schemaSource,
"VALUES (1, '10.0.0.0/8', 24, 16, 24, 1, UNIX_TIMESTAMP())"),
'Global private CIDR schema lost its quantum claim, interval index or seed.');
$assert(is_string($serviceSource)
&& str_contains($serviceSource, 'claimCandidate')
&& str_contains($serviceSource, 'CloudPrivateCidrClaimConflict')
&& str_contains($serviceSource, '->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";
Loading…
Cancel
Save