"""Small, synchronous libvirt service for one remote QEMU host.
The URI normally has the form ``qemu+ssh://user@host/system``. The web
process must already have a non-interactive, trusted way to authenticate to
that host; libvirt-python does not turn an interactive SSH prompt into an API.
"""
from __future__ import annotations
import hashlib
import hmac
import ipaddress
import json
import logging
import posixpath
import re
import secrets
import threading
import time
import uuid as uuidlib
import xml.etree.ElementTree as ET
from contextlib import contextmanager
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Callable, Iterator
import libvirt
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_guest_hostname,
)
from virsh_panel.metrics import RawVMStats
from virsh_panel.platform_network_policy import (
MAX_PLATFORM_POLICY_SNAPSHOT_BYTES,
PLATFORM_DEFAULT_NETWORK_POLICY,
default_platform_policy_snapshot,
normalize_platform_policy_snapshot,
)
from virsh_panel.user_isos import (
MAX_USER_ISO_BYTES, MAX_USER_ISOS, MAX_USER_ISO_TOTAL_BYTES,
USER_ISO_ID_RE, USER_ISO_VOLUME_RE, verify_user_iso,
)
LOG = logging.getLogger(__name__)
GIB = 1024**3
PANEL_NS = "urn:virsh-panel:1"
CLEAN_TRAFFIC_FILTER = "clean-traffic"
FIREWALL_FILTER_PREFIX = "vc-fw-"
FIREWALL_FILTER_COMPILER_VERSION = 4
SUPPORTED_FIREWALL_FILTER_COMPILER_VERSIONS = frozenset({1, 2, 3, 4})
MAX_FIREWALL_RULES = 50
NAME_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,62}\Z")
INTERNAL_RESOURCE_PREFIX_LENGTHS = (16, 20, 24, 28, 32)
BRIDGE_NAME_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,14}\Z")
PUBLIC_POOL_KEY_RE = re.compile(r"[0-9a-f]{32}\Z")
SNAPSHOT_KEY_RE = re.compile(r"[0-9a-f]{32}\Z")
TEMPLATE_VOLUME_STEM = (
r"panel-template-(?:alma(?:8|9|10)|debian(?:11|12|13)|"
r"ubuntu(?:2004|2204|2404|2504|2510|2604)|"
r"centosstream(?:9|10))-"
r"[0-9a-f]{8}-[0-9a-f]{16}"
)
TEMPLATE_SOURCE_VOLUME_RE = re.compile(TEMPLATE_VOLUME_STEM + r"\.qcow2\Z")
TEMPLATE_VOLUME_RE = re.compile(
TEMPLATE_VOLUME_STEM + r"(?:-[0-9a-f]{16})?\.qcow2\Z")
DEBIAN_12_TEMPLATE_VOLUME_PREFIX = "panel-template-debian12-"
RESCUE_VOLUME_RE = re.compile(r"panel-rescue-[0-9a-f]{32}\.iso\Z")
# Reinstall rotates this UUID, so the seed identity is not derived from the VM
# UUID. Cleanup checkpoints must validate the managed seed shape instead.
SEED_VOLUME_RE = re.compile(
r"panel-seed-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-"
r"[0-9a-f]{4}-[0-9a-f]{12}\.iso\Z"
)
_CREATE_LOCK = threading.RLock()
REINSTALL_SHUTDOWN_TIMEOUT = 120
REINSTALL_SHUTDOWN_POLL_INTERVAL = 1
# These codes cross the private engine boundary. A replacement domain has
# already been started when they are emitted, so callers must preserve the
# new credential while keeping the operation out of the successful state.
REINSTALL_CLEANUP_PENDING_ERROR_CODE = "reinstall_cleanup_pending"
REINSTALL_RESULT_UNCERTAIN_ERROR_CODE = "reinstall_result_uncertain"
NETWORK_CHANGE_SHUTDOWN_TIMEOUT = 120
NETWORK_CHANGE_SHUTDOWN_POLL_INTERVAL = 1
SERVICE_SUSPEND_SHUTDOWN_TIMEOUT = 30
SERVICE_SUSPEND_SHUTDOWN_POLL_INTERVAL = 0.5
# libvirt's power APIs acknowledge a request before the guest necessarily
# reaches its final state. Keep the wait bounded so a guest that ignores an
# ACPI request becomes an explicit uncertain operation instead of a false
# success. The internal operation record can perform a later read-only
# reconciliation after a transport timeout.
POWER_ACTION_TIMEOUT = 60
POWER_ACTION_POLL_INTERVAL = 0.5
POWER_ACTION_RESULT_UNCERTAIN_ERROR_CODE = "power_action_result_uncertain"
SNAPSHOT_JOB_POLL_INTERVAL = 0.5
SNAPSHOT_JOB_TIMEOUT = 4 * 60 * 60
SNAPSHOT_ABORT_TIMEOUT = 30
SNAPSHOT_RESTORE_SHUTDOWN_TIMEOUT = 120
SNAPSHOT_RESTORE_SHUTDOWN_POLL_INTERVAL = 1
MIN_RESCUE_ISO_BYTES = 1024 * 1024
MAX_RESCUE_ISO_BYTES = 8 * GIB
STATES = {
0: "nostate",
1: "running",
2: "blocked",
3: "paused",
4: "shutdown",
5: "shutoff",
6: "crashed",
7: "pmsuspended",
}
class VMError(Exception):
"""An error safe to report to the authenticated panel user."""
def __init__(self, message: str, status: int = 400, *,
error_code: str = "") -> None:
super().__init__(message)
self.status = status
self.status_code = status
self.error_code = error_code
class VMSnapshotUncertainError(VMError):
"""The snapshot operation crossed a destructive/ambiguous boundary."""
def __init__(self, message: str) -> None:
super().__init__(message, 503, error_code="snapshot_result_uncertain")
def _platform_policy_from_domain_xml(
root: ET.Element, *, require_explicit: bool = False,
) -> dict[str, Any]:
"""Read one immutable per-VM snapshot; missing means legacy baseline."""
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
if managed is None:
raise VMError(
"虚拟机缺少面板网络策略元数据", 409,
error_code="firewall_drift_detected",
)
nodes = managed.findall(f"{{{PANEL_NS}}}platform-policy")
if not nodes:
if require_explicit:
raise VMError(
"虚拟机缺少显式平台网络策略元数据", 409,
error_code="firewall_drift_detected",
)
return default_platform_policy_snapshot()
if len(nodes) != 1 or set(nodes[0].attrib) != {"version", "digest"}:
raise VMError(
"虚拟机平台网络策略元数据已损坏", 409,
error_code="firewall_drift_detected",
)
node = nodes[0]
raw = node.text or ""
if (node.get("version") != "1"
or len(raw.encode("utf-8")) > MAX_PLATFORM_POLICY_SNAPSHOT_BYTES):
raise VMError(
"虚拟机平台网络策略元数据已损坏", 409,
error_code="firewall_drift_detected",
)
try:
decoded = json.loads(raw)
snapshot = normalize_platform_policy_snapshot(decoded)
except (TypeError, ValueError, UnicodeError, json.JSONDecodeError) as exc:
raise VMError(
"虚拟机平台网络策略元数据已损坏", 409,
error_code="firewall_drift_detected",
) from exc
if not hmac.compare_digest(node.get("digest") or "", snapshot["digest"]):
raise VMError(
"虚拟机平台网络策略摘要已漂移", 409,
error_code="firewall_drift_detected",
)
return snapshot
def _platform_policy_state_from_domain_xml(
root: ET.Element,
) -> tuple[dict[str, Any] | None, bool]:
"""Return policy evidence for managed domains; unmanaged domains opt out."""
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
if managed is None:
return None, False
explicit = bool(
managed.findall(f"{{{PANEL_NS}}}platform-policy"))
return (
_platform_policy_from_domain_xml(
root, require_explicit=explicit),
explicit,
)
def _require_same_platform_policy_state(
root: ET.Element,
expected: dict[str, Any] | None,
*,
require_explicit: bool,
message: str,
) -> None:
"""Reject a managed policy change between two already-read definitions."""
observed, observed_explicit = _platform_policy_state_from_domain_xml(root)
if expected is None:
if observed is None:
return
elif (observed is not None
and observed_explicit == require_explicit
and isinstance(observed.get("digest"), str)
and hmac.compare_digest(
observed["digest"], expected["digest"])
and observed == expected):
return
raise VMError(
message, 409,
error_code="firewall_drift_detected",
)
def _verify_platform_policy_in_domain(
domain: Any, expected: dict[str, Any], *, require_explicit: bool,
) -> dict[str, Any]:
"""Prove a defineXML call retained the intended inactive metadata."""
try:
root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
observed = _platform_policy_from_domain_xml(
root, require_explicit=require_explicit)
except Exception as exc:
raise VMError(
"虚拟机平台网络策略写入结果无法确认", 502,
error_code="firewall_result_uncertain",
) from exc
if (not isinstance(observed.get("digest"), str)
or not hmac.compare_digest(
observed["digest"], expected["digest"])
or observed != expected):
raise VMError(
"虚拟机平台网络策略写入结果无法确认", 502,
error_code="firewall_result_uncertain",
)
return observed
def _store_platform_policy_in_domain_xml(
managed: ET.Element, snapshot: Any,
) -> dict[str, Any]:
"""Persist one canonical snapshot as namespaced, libvirt-retained text."""
try:
normalized = normalize_platform_policy_snapshot(snapshot)
except ValueError as exc:
raise VMError(
"平台网络策略快照无效", 422,
error_code="firewall_rule_invalid",
) from exc
for old in managed.findall(f"{{{PANEL_NS}}}platform-policy"):
managed.remove(old)
node = ET.SubElement(
managed, f"{{{PANEL_NS}}}platform-policy",
version="1", digest=normalized["digest"],
)
node.text = json.dumps(
normalized, ensure_ascii=False, separators=(",", ":"),
)
return normalized
def firewall_filter_name(vm_uuid: str) -> str:
"""Return the stable, host-local nwfilter name for one VM UUID."""
try:
canonical = str(uuidlib.UUID(vm_uuid))
except (TypeError, ValueError, AttributeError) as exc:
raise VMError("虚拟机 UUID 无效", 400) from exc
digest = hashlib.sha256(canonical.encode("ascii")).hexdigest()[:32]
return FIREWALL_FILTER_PREFIX + digest
def normalize_firewall_rules(rules: Any) -> list[dict[str, Any]]:
"""Validate the typed IPv4 ingress allowlist accepted by the engine."""
if not isinstance(rules, list) or len(rules) > MAX_FIREWALL_RULES:
raise VMError("防火墙规则数量无效", 422,
error_code="firewall_rule_invalid")
normalized: list[dict[str, Any]] = []
allowed = {"protocol", "source_cidr", "port_from", "port_to", "description"}
for item in rules:
if not isinstance(item, dict) or set(item) - allowed:
raise VMError("防火墙规则格式无效", 422,
error_code="firewall_rule_invalid")
protocol = item.get("protocol")
if protocol not in {"tcp", "udp", "icmp"}:
raise VMError("防火墙协议无效", 422,
error_code="firewall_rule_invalid")
raw_source = item.get("source_cidr")
try:
source = ipaddress.ip_network(raw_source, strict=False)
except (TypeError, ValueError) as exc:
raise VMError("防火墙来源必须是 IPv4 CIDR", 422,
error_code="firewall_rule_invalid") from exc
if source.version != 4:
raise VMError("防火墙一期仅支持 IPv4", 422,
error_code="firewall_rule_invalid")
if raw_source != str(source):
raise VMError("防火墙来源必须使用规范 IPv4 CIDR", 422,
error_code="firewall_rule_invalid")
port_from = item.get("port_from")
port_to = item.get("port_to")
if protocol in {"tcp", "udp"}:
if (isinstance(port_from, bool) or not isinstance(port_from, int)
or isinstance(port_to, bool) or not isinstance(port_to, int)
or not 1 <= port_from <= port_to <= 65535):
raise VMError("防火墙 TCP/UDP 端口范围无效", 422,
error_code="firewall_rule_invalid")
elif port_from is not None or port_to is not None:
raise VMError("ICMP 规则不能包含端口", 422,
error_code="firewall_rule_invalid")
description = item.get("description", "")
if (not isinstance(description, str) or len(description) > 120
or description != description.strip()
or any(ord(char) < 32 or ord(char) == 127
for char in description)):
raise VMError("防火墙规则说明无效", 422,
error_code="firewall_rule_invalid")
normalized.append({
"protocol": protocol,
"source_cidr": str(source),
"port_from": port_from if protocol != "icmp" else None,
"port_to": port_to if protocol != "icmp" else None,
"description": description,
})
return sorted(normalized, key=lambda rule: (
rule["protocol"].encode("utf-8"),
rule["source_cidr"].encode("ascii"),
rule["port_from"] if rule["port_from"] is not None else -1,
rule["port_to"] if rule["port_to"] is not None else -1,
rule["description"].encode("utf-8"),
))
def _canonical_xml_node(node: ET.Element) -> Any:
"""Make libvirt-added formatting and UUIDs irrelevant to evidence."""
children = [child for child in node if child.tag != "uuid"]
return [
node.tag,
sorted(node.attrib.items()),
(node.text or "").strip(),
[_canonical_xml_node(child) for child in children],
]
def firewall_xml_digest(xml: str) -> str:
try:
root = ET.fromstring(xml)
except (TypeError, ET.ParseError) as exc:
raise VMError("宿主机返回的防火墙 XML 无效", 502,
error_code="firewall_drift_detected") from exc
canonical = json.dumps(
_canonical_xml_node(root), ensure_ascii=True,
separators=(",", ":"), sort_keys=False,
).encode("ascii")
return hashlib.sha256(canonical).hexdigest()
def firewall_policy_digest(enabled: bool, rules: Any) -> str:
"""Cross-language v1 digest of the normalized control-plane policy."""
normalized = normalize_firewall_rules(rules)
document = {
"version": 1,
"enabled": enabled,
"rules": [{
"protocol": rule["protocol"],
"source_cidr": rule["source_cidr"],
"port_from": rule["port_from"],
"port_to": rule["port_to"],
"description": rule["description"],
} for rule in normalized],
}
encoded = json.dumps(
document, ensure_ascii=False, separators=(",", ":"),
).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def build_firewall_filter_xml(
vm_uuid: str, enabled: bool, rules: Any, *,
compiler_version: int = FIREWALL_FILTER_COMPILER_VERSION,
platform_policy_snapshot: Any = None,
) -> tuple[str, list[dict[str, Any]], str, str]:
"""Compile a bounded typed policy; callers can never supply raw XML."""
if (isinstance(compiler_version, bool)
or compiler_version not in SUPPORTED_FIREWALL_FILTER_COMPILER_VERSIONS):
raise ValueError("unsupported firewall filter compiler version")
if not isinstance(enabled, bool):
raise VMError("防火墙启用状态无效", 422,
error_code="firewall_rule_invalid")
normalized = normalize_firewall_rules(rules)
root = ET.Element("filter", name=firewall_filter_name(vm_uuid), chain="root")
# The interface's IP parameter instantiates the complete referenced filter
# tree in libvirt, so clean-traffic receives the same value transitively.
ET.SubElement(root, "filterref", filter=CLEAN_TRAFFIC_FILTER)
if compiler_version >= 3:
# Platform rules are compiled independently from the tenant allowlist.
# They therefore remain active when the tenant firewall is disabled
# and can never be overridden by a later user accept rule. Keep every
# direction explicit: the filter is attached only to the managed
# public interface, so these are public ingress/egress restrictions.
priority = 10
direction_names = {"ingress": "in", "egress": "out"}
if compiler_version >= 4:
try:
platform_rules = normalize_platform_policy_snapshot(
platform_policy_snapshot
if platform_policy_snapshot is not None
else default_platform_policy_snapshot()
)["rules"]
except ValueError as exc:
raise VMError(
"平台网络策略快照无效", 422,
error_code="firewall_rule_invalid",
) from exc
else:
platform_rules = [{
"protocols": platform_rule.protocols,
"port_from": platform_rule.port_from,
"port_to": platform_rule.port_to,
"directions": platform_rule.directions,
} for platform_rule in PLATFORM_DEFAULT_NETWORK_POLICY.rules]
for platform_rule in platform_rules:
for direction in platform_rule["directions"]:
for protocol in platform_rule["protocols"]:
rule = ET.SubElement(
root, "rule", action="drop",
direction=direction_names[direction],
priority=str(priority),
)
ET.SubElement(
rule, protocol,
dstportstart=str(platform_rule["port_from"]),
dstportend=str(platform_rule["port_to"]),
state="NONE",
)
priority += 1
if priority > 80:
raise VMError(
"平台网络策略超过过滤器优先级预算", 422,
error_code="firewall_rule_invalid",
)
# The product does not provision guest IPv6. Enforce that boundary in
# this wrapper as well as in an enabled tenant firewall, otherwise the
# IPv4 platform deny list could be bypassed if a bridge later starts
# forwarding router advertisements or routed IPv6 traffic.
ipv6_drop = ET.SubElement(
root, "rule", action="drop", direction="inout", priority="80")
ET.SubElement(ipv6_drop, "all-ipv6")
if compiler_version >= 2:
# The tenant-configurable policy restricts only ingress. After any v3
# platform drops, an explicit NONE state permits all other IPv4
# egress. It keeps libvirt on its direction-aware rule path without a
# conntrack predicate: FI/HI allow packets sent by the guest, while no
# unconditional FO rule is generated for traffic entering the guest.
outbound = ET.SubElement(
root, "rule", action="accept", direction="out", priority="90")
ET.SubElement(outbound, "all", state="NONE")
# Keep already-established flows usable while the allowlist changes.
established = ET.SubElement(
root, "rule", action="accept", direction="in", priority="100")
ET.SubElement(established, "all", state="ESTABLISHED,RELATED")
for offset, item in enumerate(normalized):
rule = ET.SubElement(
root, "rule", action="accept", direction="in",
priority=str(200 + offset),
)
network = ipaddress.ip_network(item["source_cidr"], strict=True)
attributes = {
"srcipaddr": str(network.network_address),
"srcipmask": str(network.prefixlen),
"state": "NEW",
}
if item["protocol"] in {"tcp", "udp"}:
attributes.update(
dstportstart=str(item["port_from"]),
dstportend=str(item["port_to"]),
)
ET.SubElement(rule, item["protocol"], **attributes)
if enabled:
# The product is IPv4-only. all/all-ipv6 are iptables/ip6tables
# protocols, so these rules do not consume ARP/RARP before the
# referenced clean-traffic tree can handle them. Do not use the
# ebtables-level ip/ipv6 elements here: ebtables runs first and would
# drop packets before the typed tcp/udp/icmp accepts are evaluated.
if compiler_version < 3:
ipv6_drop = ET.SubElement(
root, "rule", action="drop", direction="inout",
priority="400")
ET.SubElement(ipv6_drop, "all-ipv6")
ipv4_drop = ET.SubElement(
root, "rule", action="drop", direction="in", priority="400")
# NONE is also required here. A bare is expanded by libvirt to
# FI, FO and HI and therefore drops guest egress despite direction=in.
ET.SubElement(
ipv4_drop, "all",
**({"state": "NONE"} if compiler_version >= 2 else {}),
)
xml = ET.tostring(root, encoding="unicode")
return (
xml,
normalized,
firewall_policy_digest(enabled, normalized),
firewall_xml_digest(xml),
)
def snapshot_volume_name(vm_uuid: str, snapshot_key: str) -> str:
"""Return a bounded, host-local name derived only from validated IDs."""
try:
compact = uuidlib.UUID(vm_uuid).hex
except (TypeError, ValueError, AttributeError) as exc:
raise VMError("虚拟机 UUID 无效", 400) from exc
if not isinstance(snapshot_key, str) or not SNAPSHOT_KEY_RE.fullmatch(snapshot_key):
raise VMError("快照标识无效", 422)
# Keep the complete PHP-issued snapshot key while deriving the bounded VM
# component from the complete UUID. Truncating the UUID itself would make
# two otherwise unrelated VMs with the same prefix share a volume name.
vm_digest = hashlib.sha256(compact.encode("ascii")).hexdigest()[:16]
return f"panel-snap-{vm_digest}-{snapshot_key}.qcow2"
def snapshot_restore_volume_name(vm_uuid: str, operation_id: str) -> str:
"""Return an idempotent replacement-disk name without exposing the op ID."""
try:
compact = uuidlib.UUID(vm_uuid).hex
except (TypeError, ValueError, AttributeError) as exc:
raise VMError("虚拟机 UUID 无效", 400) from exc
if (not isinstance(operation_id, str)
or not re.fullmatch(r"[A-Za-z0-9_-]{8,80}", operation_id)):
raise VMError("快照恢复操作编号无效", 422)
# Operation IDs can be up to 80 characters while libvirt volume names
# must remain within the panel's 63-character safe stem. Hash the complete
# UUID and complete operation ID together; never truncate either input.
digest = hashlib.sha256(
compact.encode("ascii") + b"\0" + operation_id.encode("ascii")
).hexdigest()[:48]
return f"panel-restore-{digest}.qcow2"
class VMService:
"""Operate on one host through libvirt's native API, never a shell."""
def __init__(self, uri: str, storage_pool: str, iso_pool: str, network: str,
rescue_iso_pool: str = "") -> None:
if not all(isinstance(value, str) and value for value in
(uri, storage_pool, iso_pool, network)):
raise ValueError("libvirt URI, storage pools, and network are required")
if not isinstance(rescue_iso_pool, str):
raise ValueError("rescue ISO pool must be a string")
self.uri = uri
self.storage_pool = storage_pool
self.iso_pool = iso_pool
self.rescue_iso_pool = rescue_iso_pool
self.network = network
self.bridge_name = None
if network.startswith("bridge:"):
self.bridge_name = network.removeprefix("bridge:")
if not BRIDGE_NAME_RE.fullmatch(self.bridge_name):
raise ValueError("bridge network must name a host interface of at most 15 characters")
@contextmanager
def _connect(self) -> Iterator[Any]:
try:
conn = libvirt.open(self.uri)
if conn is None:
raise VMError("无法连接虚拟化宿主机", 502)
except libvirt.libvirtError as exc:
LOG.warning("libvirt connection failed: %s", exc)
raise VMError("无法连接虚拟化宿主机", 502) from exc
try:
yield conn
except libvirt.libvirtError as exc:
LOG.warning("libvirt operation failed: %s", exc)
raise VMError("宿主机操作失败,请查看面板服务日志", 502) from exc
finally:
try:
conn.close()
except libvirt.libvirtError:
LOG.exception("Could not close libvirt connection")
@staticmethod
def _uuid(value: str) -> str:
try:
return str(uuidlib.UUID(value))
except (TypeError, ValueError, AttributeError) as exc:
raise VMError("虚拟机 UUID 无效", 400) from exc
def _domain(self, conn: Any, value: str) -> Any:
vm_uuid = self._uuid(value)
try:
return conn.lookupByUUIDString(vm_uuid)
except libvirt.libvirtError as exc:
raise VMError("虚拟机不存在", 404) from exc
@staticmethod
def _require_clean_traffic_filter(conn: Any) -> None:
"""Fail before allocating storage when the host cannot filter guests."""
lookup = getattr(conn, "nwfilterLookupByName", None)
if lookup is None:
raise VMError("宿主机 libvirt 不支持 clean-traffic 网络过滤器", 502)
try:
filter_object = lookup(CLEAN_TRAFFIC_FILTER)
except libvirt.libvirtError as exc:
LOG.warning("Host is missing libvirt network filter %s: %s",
CLEAN_TRAFFIC_FILTER, exc)
raise VMError(
"宿主机缺少 clean-traffic 网络过滤器,实例创建已停止", 502,
) from exc
if filter_object is None:
raise VMError(
"宿主机缺少 clean-traffic 网络过滤器,实例创建已停止", 502,
)
@staticmethod
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."""
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)
@staticmethod
def _attach_clean_traffic_filter(interface: ET.Element,
public_ip_cidr: str) -> None:
"""Bind the anti-spoofing filter to a panel-managed public interface."""
VMService._attach_public_filter(
interface, public_ip_cidr, CLEAN_TRAFFIC_FILTER)
def _ensure_default_firewall_filter(
self, conn: Any, vm_uuid: str, platform_policy_snapshot: Any,
) -> tuple[str, str, bool]:
"""Define the immutable platform wrapper before a new guest can boot.
The boolean reports whether this call definitely created the filter.
An exact pre-existing filter is safe to reuse, but is never claimed as
ours for rollback cleanup.
"""
expected_xml, _rules, _policy_digest, expected_digest = (
build_firewall_filter_xml(
vm_uuid, False, [],
platform_policy_snapshot=platform_policy_snapshot,
))
expected_name = firewall_filter_name(vm_uuid)
existing = self._lookup_filter(conn, expected_name)
if existing is not None:
if (not callable(getattr(existing, "XMLDesc", None))
or not hmac.compare_digest(
firewall_xml_digest(existing.XMLDesc(0)),
expected_digest,
)):
raise VMError(
"同名虚拟机防火墙过滤器与平台默认策略不一致",
409,
error_code="firewall_drift_detected",
)
return expected_xml, expected_digest, False
define_filter = getattr(conn, "nwfilterDefineXML", None)
if not callable(define_filter):
raise VMError(
"宿主机 libvirt 不支持定义网络过滤器", 502,
error_code="firewall_capability_missing",
)
try:
defined = define_filter(expected_xml)
except libvirt.libvirtError as exc:
# The transport can fail after libvirt committed. Reuse exact
# evidence, but do not claim ownership for rollback cleanup.
try:
observed = self._lookup_filter(conn, expected_name)
except Exception as observation_error:
raise VMError(
"平台默认网络策略定义结果无法确认且回滚不完整",
502,
error_code="firewall_result_uncertain",
) from observation_error
if (observed is not None
and callable(getattr(observed, "XMLDesc", None))
and hmac.compare_digest(
firewall_xml_digest(observed.XMLDesc(0)),
expected_digest,
)):
return expected_xml, expected_digest, False
if observed is not None:
raise VMError(
"平台默认网络策略定义结果无法确认且回滚不完整",
502,
error_code="firewall_result_uncertain",
) from exc
raise VMError(
"宿主机未能定义平台默认网络策略", 502,
error_code="firewall_apply_failed",
) from exc
if defined is None:
raise VMError(
"宿主机未能定义平台默认网络策略", 502,
error_code="firewall_apply_failed",
)
try:
observed = self._lookup_filter(conn, expected_name)
verified = bool(
observed is not None
and callable(getattr(observed, "XMLDesc", None))
and hmac.compare_digest(
firewall_xml_digest(observed.XMLDesc(0)),
expected_digest,
)
)
except Exception:
verified = False
if not verified:
# The definition may already have committed. Remove only exact,
# unreferenced evidence. If that cannot be proven, surface an
# incomplete rollback so the control plane retains the operation
# context for operator reconciliation instead of treating this as
# an ordinary clean failure.
if not self._remove_created_firewall_filter(
conn, vm_uuid, expected_digest):
raise VMError(
"平台默认网络策略定义结果无法确认且回滚不完整",
502,
error_code="firewall_result_uncertain",
)
raise VMError(
"平台默认网络策略定义结果无法确认", 502,
error_code="firewall_result_uncertain",
)
return expected_xml, expected_digest, True
def _remove_created_firewall_filter(
self, conn: Any, vm_uuid: str, expected_digest: str,
) -> bool:
"""Remove only this create attempt's exact, unreferenced wrapper."""
filter_name = firewall_filter_name(vm_uuid)
try:
for domain in conn.listAllDomains(0):
roots = [ET.fromstring(domain.XMLDesc(0))]
if domain.isPersistent():
roots.append(ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)))
if any(
ref.get("filter") == filter_name
for root in roots
for ref in root.findall("./devices/interface/filterref")
):
return False
filter_object = self._lookup_filter(conn, filter_name)
if filter_object is None:
return True
if (not callable(getattr(filter_object, "XMLDesc", None))
or not hmac.compare_digest(
firewall_xml_digest(filter_object.XMLDesc(0)),
expected_digest,
)):
return False
filter_object.undefine()
return self._lookup_filter(conn, filter_name) is None
except Exception:
LOG.exception(
"Could not remove default firewall filter for %s", vm_uuid)
return False
@staticmethod
def _update_public_filter_ip(interface: ET.Element,
public_ip_cidr: str,
vm_uuid: str | None = None) -> None:
"""Update the IP parameter on either baseline or managed firewall."""
public_ip = public_ip_cidr.split("/", 1)[0]
expected_firewall = (firewall_filter_name(vm_uuid)
if vm_uuid is not None else None)
refs = [node for node in interface.findall("filterref")
if (node.get("filter") == CLEAN_TRAFFIC_FILTER
or (expected_firewall is not None
and node.get("filter") == expected_firewall))]
if len(refs) > 1:
raise VMError("虚拟机存在重复的公网过滤器,已停止网络修改", 409)
if not refs:
managed_refs = [node for node in interface.findall("filterref")
if (node.get("filter") or "").startswith(
FIREWALL_FILTER_PREFIX)]
if managed_refs:
raise VMError("虚拟机防火墙身份不匹配,已停止网络修改", 409)
VMService._attach_clean_traffic_filter(interface, public_ip_cidr)
return
parameters = refs[0].findall("parameter")
if len(parameters) > 1:
raise VMError("虚拟机的 clean-traffic 参数重复,已停止网络修改", 409)
parameter = parameters[0] if parameters else ET.SubElement(
refs[0], "parameter", name="IP", value=public_ip)
if parameter.get("name") != "IP":
raise VMError("虚拟机的 clean-traffic 参数无效,已停止网络修改", 409)
parameter.set("value", public_ip)
# Compatibility for callers/tests written before per-VM firewall wrappers.
_update_clean_traffic_filter = _update_public_filter_ip
@staticmethod
def _pool_path(reference: str) -> str | None:
if not reference.startswith("/"):
return None
if ("\x00" in reference or reference.startswith("//")
or any(part in (".", "..") for part in reference.split("/"))):
raise VMError("存储池目录必须是不含 . 或 .. 的绝对路径")
path = posixpath.normpath(reference)
if path == "/":
raise VMError("不能将宿主机根目录用作存储池")
return path
@staticmethod
def _file_pool_path(pool: Any) -> str | None:
"""Compare paths for file-backed pools, including fs/netfs aliases."""
try:
root = ET.fromstring(pool.XMLDesc(0))
except ET.ParseError as exc:
raise VMError("宿主机返回的存储池配置 XML 无效", 502) from exc
if root.get("type") not in {"dir", "fs", "netfs"}:
return None
path = root.findtext("./target/path")
return posixpath.normpath(path) if path and path.startswith("/") else None
@staticmethod
def _directory_pool_path(pool: Any) -> str | None:
try:
root = ET.fromstring(pool.XMLDesc(0))
except ET.ParseError as exc:
raise VMError("宿主机返回的存储池配置 XML 无效", 502) from exc
if root.get("type") != "dir":
return None
path = root.findtext("./target/path")
return posixpath.normpath(path) if path and path.startswith("/") else None
def _lookup_pool(self, conn: Any, reference: str) -> Any | None:
path = self._pool_path(reference)
if path is None:
try:
return conn.storagePoolLookupByName(reference)
except libvirt.libvirtError as exc:
LOG.info("Storage pool %s is not defined: %s", reference, exc)
return None
matches = [pool for pool in conn.listAllStoragePools(0)
if self._file_pool_path(pool) == path]
if len(matches) > 1:
raise VMError(f"目录 {path} 对应多个 libvirt 存储池,请在宿主机处理重复配置", 409)
return matches[0] if matches else None
def _active_pool(self, conn: Any, reference: str) -> Any:
pool = self._lookup_pool(conn, reference)
if pool is None:
if self._pool_path(reference) is not None:
raise VMError(f"目录 {reference} 尚未配置为 libvirt 存储池,请先保存宿主机设置", 409)
raise VMError(f"存储池 {reference} 不存在", 404)
if not pool.isActive():
raise VMError(f"存储池 {pool.name()} 未启动", 409)
return pool
@classmethod
def _same_pool_location(cls, first: Any, second: Any) -> bool:
if first.name() == second.name():
return True
first_path = cls._file_pool_path(first)
second_path = cls._file_pool_path(second)
return first_path is not None and first_path == second_path
def _active_rescue_pool(self, conn: Any) -> Any:
if not self.rescue_iso_pool:
raise VMError("请先在宿主机设置中配置救援 ISO 目录", 409)
pool = self._active_pool(conn, self.rescue_iso_pool)
normal_pool = self._lookup_pool(conn, self.iso_pool)
if normal_pool is not None and self._same_pool_location(pool, normal_pool):
raise VMError("救援 ISO 目录不能与安装 ISO 目录相同", 409)
return pool
@staticmethod
def _user_id(value: Any) -> int:
if isinstance(value, bool) or not isinstance(value, int) or value < 1:
raise VMError("用户身份无效", 403)
return value
@staticmethod
def _user_iso_pool_name(path: str) -> str:
return "panel-user-iso-" + hashlib.sha256(path.encode("utf-8")).hexdigest()[:40]
def _active_user_iso_pool(self, conn: Any, user_id: int, *,
create: bool = True) -> Any | None:
"""Return the persistent dir pool rooted at ISO_ROOT/.
The caller supplies only the authenticated numeric owner. Neither an
HTTP body nor catalog record can influence the directory path.
"""
user_id = self._user_id(user_id)
root_pool = self._active_pool(conn, self.iso_pool)
root_path = self._directory_pool_path(root_pool)
if root_path is None or root_path == "/":
raise VMError("用户 ISO 需要配置为目录类型的 ISO 存储池", 409)
user_path = posixpath.join(root_path, str(user_id))
if posixpath.dirname(user_path) != root_path:
raise VMError("用户 ISO 目录无效", 409)
generated_name = self._user_iso_pool_name(user_path)
try:
named_pool = conn.storagePoolLookupByName(generated_name)
except libvirt.libvirtError:
named_pool = None
if named_pool is not None and self._directory_pool_path(named_pool) != user_path:
raise VMError("用户 ISO 存储池名称已被其他目录占用", 409)
matches = [pool for pool in conn.listAllStoragePools(0)
if self._directory_pool_path(pool) == user_path]
if len(matches) > 1:
raise VMError("用户 ISO 目录对应多个 libvirt 存储池", 409)
if named_pool is not None and matches and matches[0].name() != named_pool.name():
raise VMError("用户 ISO 目录的 libvirt 存储池配置冲突", 409)
pool = named_pool or (matches[0] if matches else None)
created = False
if pool is None:
if not create:
return None
try:
pool = conn.storagePoolDefineXML(
self._directory_pool_xml(generated_name, user_path), 0)
except libvirt.libvirtError as exc:
raise VMError("无法创建用户 ISO 目录存储池", 502) from exc
if pool is None:
raise VMError("无法创建用户 ISO 目录存储池", 502)
created = True
if not pool.isPersistent():
if created:
self._rollback_new_pool(pool)
raise VMError("用户 ISO 目录必须使用持久化 libvirt 存储池", 409)
if not pool.isActive():
build_error = None
if created:
try:
# A dir-pool build creates exactly the numeric child
# directory. It never creates or changes the configured
# root pool itself.
pool.build(0)
except libvirt.libvirtError as exc:
# The directory may already exist after a previous pool
# definition was lost. Starting the pool is the safe,
# non-destructive way to distinguish that case.
build_error = exc
try:
pool.create(0)
except libvirt.libvirtError as exc:
if created:
self._rollback_new_pool(pool)
LOG.warning("Could not activate user ISO directory %s: build=%s start=%s",
user_path, build_error, exc)
raise VMError("无法创建或访问用户 ISO 专用目录", 409) from exc
self._refresh_directory_pool(pool)
return pool
@classmethod
def _refresh_directory_pool(cls, pool: Any) -> None:
# ISO files and disk images may be placed into these directories
# outside libvirt. Refresh before looking up names or checking for
# collisions so libvirt's cached volume list is not stale.
if cls._directory_pool_path(pool) is not None:
pool.refresh(0)
@staticmethod
def _directory_pool_xml(name: str, path: str) -> str:
root = ET.Element("pool", type="dir")
ET.SubElement(root, "name").text = name
target = ET.SubElement(root, "target")
ET.SubElement(target, "path").text = path
return ET.tostring(root, encoding="unicode")
@staticmethod
def _rollback_new_pool(pool: Any) -> bool:
"""Remove only a definition created by this ensure call, not its files."""
restored = True
try:
if pool.isActive():
pool.destroy()
except libvirt.libvirtError:
LOG.exception("Could not stop newly defined pool %s during rollback", pool.name())
restored = False
try:
pool.undefine()
except libvirt.libvirtError:
LOG.exception("Could not undefine newly defined pool %s during rollback", pool.name())
restored = False
return restored
def _ensure_pool(self, conn: Any, reference: str, created_pools: list[Any]) -> Any:
path = self._pool_path(reference)
pool = self._lookup_pool(conn, reference)
if pool is None:
if path is None:
raise VMError(f"存储池 {reference} 不存在;请填写已存在的池名或宿主机绝对目录", 404)
# A path is a host directory, never an XML pool name. A stable
# name keeps domain XML valid across panel and libvirt restarts.
name = "panel-dir-" + hashlib.sha256(path.encode("utf-8")).hexdigest()[:48]
try:
collision = conn.storagePoolLookupByName(name)
except libvirt.libvirtError:
collision = None
if collision is not None:
raise VMError(f"自动生成的存储池名称 {name} 已被其他目录占用", 409)
try:
pool = conn.storagePoolDefineXML(self._directory_pool_xml(name, path), 0)
except libvirt.libvirtError as exc:
LOG.warning("Could not define directory pool %s for %s: %s", name, path, exc)
raise VMError(f"无法为目录 {path} 定义 libvirt 存储池", 502) from exc
if pool is None:
raise VMError(f"无法为目录 {path} 定义 libvirt 存储池", 502)
created_pools.append(pool)
if not pool.isPersistent():
raise VMError(f"存储池 {pool.name()} 是临时池,无法在宿主机重启后自动启动", 409)
try:
if not pool.isActive():
pool.create(0)
except libvirt.libvirtError as exc:
LOG.warning("Could not start directory pool %s: %s", pool.name(), exc)
if path is not None:
raise VMError(f"目录 {path} 不存在或 libvirt 无权访问;请检查宿主机目录和 SELinux 权限", 409) from exc
raise VMError(f"存储池 {reference} 无法启动", 409) from exc
if not pool.autostart():
try:
pool.setAutostart(1)
except libvirt.libvirtError as exc:
LOG.warning("Could not enable autostart for pool %s: %s", pool.name(), exc)
raise VMError(f"无法设置存储池 {pool.name()} 随宿主机启动", 502) from exc
return pool
def ensure_storage_pools(self) -> dict[str, str]:
"""Explicitly define/start configured directory pools; never build paths."""
with self._connect() as conn:
created_pools: list[Any] = []
try:
disk_pool = self._ensure_pool(conn, self.storage_pool, created_pools)
iso_pool = self._ensure_pool(conn, self.iso_pool, created_pools)
pools = {"storage_pool": disk_pool.name(), "iso_pool": iso_pool.name()}
if self.rescue_iso_pool:
rescue_pool = self._ensure_pool(
conn, self.rescue_iso_pool, created_pools)
if self._same_pool_location(iso_pool, rescue_pool):
raise VMError("救援 ISO 目录不能与安装 ISO 目录相同", 409)
pools["rescue_iso_pool"] = rescue_pool.name()
return pools
except Exception as exc:
rolled_back = True
for pool in reversed(created_pools):
if not self._rollback_new_pool(pool):
rolled_back = False
if not rolled_back:
raise VMError("存储池配置失败且新建存储池回滚失败;请检查宿主机", 502) from exc
raise
@staticmethod
def _vm_xml(domain: Any) -> ET.Element:
try:
return ET.fromstring(domain.XMLDesc(0))
except ET.ParseError as exc:
raise VMError("宿主机返回的虚拟机配置 XML 无效", 502) from exc
@staticmethod
def _display_name(domain: Any, managed: ET.Element | None) -> str:
"""Return the customer label without exposing host resource names.
Older panel domains did not persist a separate label, so their
libvirt name remains the compatibility fallback.
"""
display_name = managed.get("display-name") if managed is not None else None
if isinstance(display_name, str) and NAME_RE.fullmatch(display_name):
return display_name
return domain.name()
@staticmethod
def _internal_resource_names(vm_uuid: str) -> tuple[str, ...]:
compact = uuidlib.UUID(vm_uuid).hex
return tuple(
f"vc-{compact[:length]}" for length in INTERNAL_RESOURCE_PREFIX_LENGTHS
)
@classmethod
def _select_internal_resource_name(
cls,
vm_uuid: str,
domains: list[Any],
volume_names: set[str],
) -> str:
"""Choose a short UUID-derived domain/disk stem without overwriting.
Sixteen hexadecimal digits are ample for routine host maintenance.
If an existing domain or volume has that prefix, progressively reveal
more of the UUID instead of falling back to a user-controlled name.
"""
domain_names = {domain.name() for domain in domains}
for candidate in cls._internal_resource_names(vm_uuid):
if candidate not in domain_names and f"{candidate}.qcow2" not in volume_names:
return candidate
raise VMError("虚拟机内部资源标识已被占用,请重试", 409)
@staticmethod
def _disk_rows(root: ET.Element) -> list[dict[str, Any]]:
rows: list[dict[str, Any]] = []
for disk in root.findall("./devices/disk"):
if disk.get("device") != "disk":
continue
source = disk.find("source")
target = disk.find("target")
driver = disk.find("driver")
source_name = ""
if source is not None:
source_name = (source.get("volume") or source.get("file")
or source.get("dev") or "")
rows.append({
"device": disk.get("device", "disk"),
"source": source_name,
"target": target.get("dev", "") if target is not None else "",
"format": driver.get("type", "") if driver is not None else "",
})
return rows
@staticmethod
def _vnc_port(root: ET.Element) -> int | None:
for graphics in root.findall("./devices/graphics"):
if graphics.get("type") == "vnc":
# The relay always connects to the hypervisor's IPv4 loopback.
# Do not advertise a console that listens on another address.
listeners = [graphics.get("listen")]
listeners.extend(node.get("address") for node in graphics.findall("listen"))
if not listeners or any(address not in (None, "127.0.0.1") for address in listeners):
return None
if all(address is None for address in listeners):
return None
try:
port = int(graphics.get("port", "-1"))
except ValueError:
return None
return port if 1 <= port <= 65535 else None
return None
def _vm_dict(self, domain: Any) -> dict[str, Any]:
info = domain.info()
root = self._vm_xml(domain)
disks = self._disk_rows(root)
for disk in disks:
identifier = disk["target"] or disk["source"]
if not identifier:
continue
try:
capacity, _allocation, _physical = domain.blockInfo(identifier, 0)
except libvirt.libvirtError:
# The domain remains manageable when an external storage
# backend cannot report its capacity (for example, RBD).
continue
if isinstance(capacity, int) and capacity > 0:
disk["capacity_gib"] = round(capacity / GIB, 2)
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
rescue = root.find(f"./metadata/{{{PANEL_NS}}}rescue")
rescue_staged = False
inactive_rescue = None
if domain.isPersistent():
try:
inactive_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
except ET.ParseError as exc:
raise VMError("宿主机返回的虚拟机持久配置 XML 无效", 502) from exc
inactive_rescue = inactive_root.find(f"./metadata/{{{PANEL_NS}}}rescue")
# Defining the next boot does not replace the live QEMU process.
# A stopped VM with a rescue definition is staged until first boot.
rescue_staged = inactive_rescue is not None and (
not domain.isActive() or rescue is None)
os_source = managed.get("os-source") if managed is not None else None
if os_source not in {"cloud_template", "iso"}:
os_source = "unknown"
try:
autostart = bool(domain.autostart())
except libvirt.libvirtError:
autostart = False
return {
"uuid": domain.UUIDString(),
"name": self._display_name(domain, managed),
"state": STATES.get(info[0], "unknown"),
"vcpu": info[3],
"memory_mib": info[1] // 1024,
"disks": disks,
"autostart": autostart,
"managed": managed is not None,
"public_ip_cidr": managed.get("public-ip-cidr") if managed is not None else None,
"public_pool_key": managed.get("public-pool-key") if managed is not None else None,
"created_at": managed.get("created-at") if managed is not None else None,
"credential_generation": managed.get("seed-volume") if os_source == "cloud_template" else None,
"os_name": managed.get("os-name") if os_source == "cloud_template" else None,
"hostname": managed.get("guest-hostname") if os_source == "cloud_template" else None,
"os_source": os_source,
"install_iso": managed.get("install-iso") if os_source == "iso" else None,
"rescue_mode": rescue is not None,
"rescue_staged": rescue_staged,
"rescue_volume_name": (
rescue.get("volume") if rescue is not None else
inactive_rescue.get("volume") if inactive_rescue is not None else None),
"console_port": self._vnc_port(root),
}
@staticmethod
def _domain_disappeared(exc: BaseException) -> bool:
"""Return whether libvirt says the domain vanished during a read.
``listAllDomains`` returns handles, not a snapshot of each domain's
state. A concurrent undefine can therefore make a later ``info`` or
``XMLDesc`` call fail with ``VIR_ERR_NO_DOMAIN``. Only that specific
race is safe to ignore; all other libvirt errors must still fail the
inventory request.
"""
get_error_code = getattr(exc, "get_error_code", None)
no_domain_code = getattr(libvirt, "VIR_ERR_NO_DOMAIN", None)
if callable(get_error_code) and no_domain_code is not None:
try:
if get_error_code() == no_domain_code:
return True
except Exception: # pragma: no cover - defensive for adapters
pass
# Keep a narrow fallback for libvirt adapters that do not expose the
# enum constant. Do not classify unrelated "not found" errors (for
# example an nwfilter or storage pool) as a vanished domain.
message = str(exc).casefold()
return bool(
re.search(r"\bno (?:matching )?domain\b", message)
or re.search(r"\bdomain .*\bnot found\b", message)
or re.search(r"\bdomain .*\bno longer exists\b", message)
or "未找到域" in message
or "没有匹配" in message and "域" in message
or "域" in message and "不存在" in message
)
@staticmethod
def _enable_vm_autostart(domain: Any) -> None:
"""Require host-boot autostart on a new persistent VM definition."""
try:
domain.setAutostart(1)
except libvirt.libvirtError as exc:
LOG.warning("Could not enable VM autostart: %s", exc)
raise VMError("无法设置新虚拟机随宿主机开机自启", 502) from exc
def list_vms(self) -> list[dict[str, Any]]:
with self._connect() as conn:
domains = conn.listAllDomains(0)
rows: list[dict[str, Any]] = []
for domain in domains:
try:
rows.append(self._vm_dict(domain))
except libvirt.libvirtError as exc:
if not self._domain_disappeared(exc):
raise
LOG.info("Skipped domain that disappeared while listing VMs")
return sorted(rows, key=lambda row: row["name"].casefold())
@staticmethod
def _vm_state_dict(domain: Any) -> dict[str, Any]:
"""Return the live power fields without parsing domain XML or disks."""
info = domain.info()
return {
"uuid": domain.UUIDString(),
"name": domain.name(),
"state": STATES.get(info[0], "unknown"),
}
def _vm_metadata_dict(self, domain: Any) -> dict[str, Any]:
"""Return the static fields needed to repair the PHP metadata cache.
Unlike :meth:`_vm_dict`, this deliberately omits live state, console
details, rescue state and credential-generation identifiers. It does
parse the selected domain's XML and inspect its disks, but callers can
select a bounded UUID set instead of loading the complete host
inventory.
"""
info = domain.info()
root = self._vm_xml(domain)
disks = self._disk_rows(root)
for disk in disks:
identifier = disk["target"] or disk["source"]
if not identifier:
continue
try:
capacity, _allocation, _physical = domain.blockInfo(identifier, 0)
except libvirt.libvirtError:
continue
if isinstance(capacity, int) and capacity > 0:
disk["capacity_gib"] = round(capacity / GIB, 2)
safe_disks = [
{"capacity_gib": disk.get("capacity_gib")}
for disk in disks
]
known_capacities = [
disk["capacity_gib"] for disk in safe_disks
if isinstance(disk.get("capacity_gib"), (int, float))
and not isinstance(disk.get("capacity_gib"), bool)
and disk["capacity_gib"] > 0
]
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
os_source = managed.get("os-source") if managed is not None else None
if os_source not in {"cloud_template", "iso"}:
os_source = "unknown"
try:
autostart = bool(domain.autostart())
except libvirt.libvirtError:
autostart = False
return {
"uuid": domain.UUIDString(),
"name": self._display_name(domain, managed),
"vcpu": info[3],
"memory_mib": info[1] // 1024,
# Storage paths and volume names are host-internal details. The
# PHP boundary only needs capacities for the instance summary.
"disks": safe_disks,
"disk_gib": round(sum(known_capacities), 2) if known_capacities else None,
"autostart": autostart,
"managed": managed is not None,
"public_ip_cidr": (
managed.get("public-ip-cidr") if managed is not None else None
),
"public_pool_key": (
managed.get("public-pool-key") if managed is not None else None
),
"created_at": managed.get("created-at") if managed is not None else None,
"os_name": (
managed.get("os-name")
if managed is not None and os_source == "cloud_template" else None
),
"hostname": (
managed.get("guest-hostname")
if managed is not None and os_source == "cloud_template" else None
),
"os_source": os_source,
"install_iso": (
managed.get("install-iso")
if managed is not None and os_source == "iso" else None
),
"login_name": "root" if os_source == "cloud_template" else None,
}
def list_vm_states(self, vm_ids: list[str] | None = None) -> list[dict[str, Any]]:
"""Fetch power state for explicit UUIDs, or every domain for legacy UI."""
if vm_ids is not None:
if not isinstance(vm_ids, list) or not 1 <= len(vm_ids) <= 100:
raise VMError("虚拟机状态查询数量必须为 1 到 100", 400)
canonical_ids: list[str] = []
seen: set[str] = set()
for value in vm_ids:
canonical = self._uuid(value)
if canonical not in seen:
canonical_ids.append(canonical)
seen.add(canonical)
with self._connect() as conn:
rows: list[dict[str, Any]] = []
for vm_id in canonical_ids:
try:
rows.append(self._vm_state_dict(
conn.lookupByUUIDString(vm_id)
))
except libvirt.libvirtError:
continue
return rows
with self._connect() as conn:
rows: list[dict[str, Any]] = []
for domain in conn.listAllDomains(0):
try:
rows.append(self._vm_state_dict(domain))
except libvirt.libvirtError:
# A domain can disappear between listAllDomains() and
# info(). Preserve the rest of the VM state list.
continue
return sorted(rows, key=lambda row: row["name"].casefold())
def list_vm_metadata(self, vm_ids: list[str]) -> list[dict[str, Any]]:
"""Fetch static metadata for at most 100 explicitly selected domains."""
if not isinstance(vm_ids, list) or not 1 <= len(vm_ids) <= 100:
raise VMError("虚拟机元数据查询数量必须为 1 到 100", 400)
canonical_ids: list[str] = []
seen: set[str] = set()
for value in vm_ids:
canonical = self._uuid(value)
if canonical not in seen:
canonical_ids.append(canonical)
seen.add(canonical)
with self._connect() as conn:
rows: list[dict[str, Any]] = []
for vm_id in canonical_ids:
try:
# Resolve only the domains requested by the visible page.
# This avoids enumerating every guest on a large host.
domain = conn.lookupByUUIDString(vm_id)
rows.append(self._vm_metadata_dict(domain))
except (libvirt.libvirtError, VMError):
# Ownership is resolved by the API before this host query.
# A database row can nevertheless become stale after an
# operator deletes the domain directly, or disappear while
# its XML is being read. Do not let that one row prevent the
# rest of this bounded batch from refreshing its metadata.
continue
return rows
def provisioning_absent(
self,
vm_uuid: str,
name: str,
*,
uuid_resources: bool = False,
legacy_name_collision: bool = False,
) -> bool:
"""Only certify refund safety after a fresh host/volume state check.
Any connection failure, external disk collision or partial rollback is
deliberately not evidence that a financial refund is safe.
"""
vm_uuid = self._uuid(vm_uuid)
if not isinstance(name, str) or not NAME_RE.fullmatch(name):
return False
with self._connect() as conn:
domains = conn.listAllDomains(0)
if any(domain.UUIDString() == vm_uuid for domain in domains):
return False
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
volumes = set(pool.listVolumes())
seed_name = f"panel-seed-{vm_uuid}.iso"
if seed_name in volumes:
return False
if (legacy_name_collision and not uuid_resources
and any(domain.name() == name for domain in domains)):
# Legacy creates rejected a duplicate libvirt name before
# allocating either disk. Therefore a same-name domain with
# another UUID (and its same-name disk) predates this failed
# operation and must not keep a deterministic 409 uncertain
# forever. The operation UUID and seed were checked above.
return True
disk_names = (
{f"{candidate}.qcow2" for candidate in self._internal_resource_names(vm_uuid)}
if uuid_resources else {f"{name}.qcow2"}
)
return not disk_names.intersection(volumes)
def get_vm(self, uuid: str) -> dict[str, Any]:
with self._connect() as conn:
return self._vm_dict(self._domain(conn, uuid))
def get_vm_state(self, uuid: str) -> dict[str, Any]:
"""Fetch one domain's power state without loading its XML metadata."""
with self._connect() as conn:
return self._vm_state_dict(self._domain(conn, uuid))
def metric_counters(self) -> list[RawVMStats]:
"""Fetch running-domain counters in one libvirt API round trip.
getAllDomainStats(stats, flags) returns ``(domain, dict)`` pairs in
libvirt-python. Network rx/tx fields are from the guest's viewpoint.
Missing per-device values are preserved as missing by the sampler.
"""
groups = (libvirt.VIR_DOMAIN_STATS_CPU_TOTAL | libvirt.VIR_DOMAIN_STATS_BALLOON
| libvirt.VIR_DOMAIN_STATS_BLOCK | libvirt.VIR_DOMAIN_STATS_INTERFACE)
running = libvirt.VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING
with self._connect() as conn:
rows: list[RawVMStats] = []
for domain, values in conn.getAllDomainStats(groups, running):
# A guest can stop or be undefined after bulk stats are read.
# Do not lose all other guests' samples for that transient race.
try:
info = domain.info()
generation = domain.ID()
vm_id = domain.UUIDString()
except libvirt.libvirtError:
continue
if info[0] != 1 or generation < 0:
continue
# ``net.N.name`` is normally the host tap device (vnet0,
# vnet1, ...), which can change every time QEMU starts. Add
# the guest NIC MAC as a stable billing identity so a reboot
# cannot make the first interval on the renamed tap free.
values = dict(values)
try:
root = ET.fromstring(domain.XMLDesc(0))
by_target: dict[str, str] = {}
for interface in root.findall("./devices/interface"):
target = interface.find("target")
mac = interface.find("mac")
target_name = target.get("dev") if target is not None else None
address = mac.get("address") if mac is not None else None
if (isinstance(target_name, str) and target_name
and isinstance(address, str)
and re.fullmatch(r"[0-9A-Fa-f]{2}(?::[0-9A-Fa-f]{2}){5}",
address)):
by_target[target_name] = "mac:" + address.lower()
count = values.get("net.count")
if isinstance(count, int) and not isinstance(count, bool):
for number in range(min(max(0, count), 1024)):
name = values.get(f"net.{number}.name")
identity = by_target.get(name) if isinstance(name, str) else None
if identity is not None:
values[f"net.{number}.identity"] = identity
except (AttributeError, ET.ParseError, libvirt.libvirtError):
# Metrics remain useful on older/unusual domains whose
# live XML cannot be read; accounting falls back to the
# reported interface name for that sample.
pass
rows.append(RawVMStats(
vm_id=vm_id, generation=generation,
vcpus=info[3], values=values,
))
return rows
def resources(self) -> dict[str, Any]:
with self._connect() as conn:
disk_pool = self._active_pool(conn, self.storage_pool)
iso_pool = self._active_pool(conn, self.iso_pool)
self._refresh_directory_pool(iso_pool)
if self.bridge_name is None:
network = conn.networkLookupByName(self.network)
active_networks = [self.network] if network.isActive() else []
else:
# Linux bridges live outside libvirt's virtual-network API.
# Advertise the configured selector and let domain startup
# report a missing/inactive bridge on the actual host.
active_networks = [self.network]
isos = sorted(name for name in iso_pool.listVolumes()
if name.lower().endswith(".iso")
and not RESCUE_VOLUME_RE.fullmatch(name))
pool_info = disk_pool.info()
return {
"storage_pool": self.storage_pool,
"networks": active_networks,
"isos": isos,
"storage_available_gib": pool_info[3] // GIB,
}
def _validate_common_create(self, spec: dict[str, Any]) -> dict[str, Any]:
if not isinstance(spec, dict):
raise VMError("虚拟机配置无效")
name = spec.get("name")
if not isinstance(name, str) or not NAME_RE.fullmatch(name):
raise VMError("名称只能包含字母、数字、点、下划线或短横线,最长 63 字符")
bounds = {
"vcpu": (1, 64),
"memory_mib": (512, 262144),
"disk_gib": (1, 4096),
}
validated: dict[str, Any] = {"name": name}
for key, (minimum, maximum) in bounds.items():
value = spec.get(key)
if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
raise VMError(f"{key} 必须是 {minimum} 到 {maximum} 的整数")
validated[key] = value
if spec.get("network") != self.network:
raise VMError("只能选择面板配置的虚拟网络或网桥")
bandwidth = spec.get("bandwidth_mbps")
if bandwidth is not None:
if isinstance(bandwidth, bool) or not isinstance(bandwidth, int) or not 1 <= bandwidth <= 100000:
raise VMError("带宽必须是 1 至 100000 Mbps 的整数")
validated["bandwidth_mbps"] = bandwidth
return validated
def _validate_create(self, spec: dict[str, Any]) -> dict[str, Any]:
validated = self._validate_common_create(spec)
iso = spec.get("iso")
if not isinstance(iso, str) or not iso.lower().endswith(".iso"):
raise VMError("请选择 ISO 存储池内的安装镜像")
if RESCUE_VOLUME_RE.fullmatch(iso):
raise VMError("救援镜像不能用作虚拟机安装 ISO", 409)
validated["iso"] = iso
return validated
@staticmethod
def _validated_os_name(value: Any) -> str | None:
if value is None:
return None
if (not isinstance(value, str) or not 1 <= len(value) <= 64
or value != value.strip() or any(ord(char) < 32 for char in value)):
raise VMError("云镜像模板名称无效")
return value
@staticmethod
def _volume_xml(name: str, disk_gib: int) -> str:
return VMService._volume_xml_bytes(name, disk_gib * GIB, "qcow2")
@staticmethod
def _volume_xml_bytes(
name: str, capacity: int, fmt: str, *, allocation: int | None = None,
) -> str:
if (isinstance(capacity, bool) or not isinstance(capacity, int)
or capacity <= 0):
raise ValueError("volume capacity must be a positive integer")
if (allocation is not None
and (isinstance(allocation, bool)
or not isinstance(allocation, int)
or not 0 <= allocation <= capacity)):
raise ValueError("volume allocation must be between zero and capacity")
root = ET.Element("volume")
ET.SubElement(root, "name").text = name
ET.SubElement(root, "capacity", unit="bytes").text = str(capacity)
if allocation is not None:
ET.SubElement(root, "allocation", unit="bytes").text = str(
allocation)
target = ET.SubElement(root, "target")
ET.SubElement(target, "format", type=fmt)
return ET.tostring(root, encoding="unicode")
@classmethod
def _volume_source(cls, pool: Any, volume: Any) -> tuple[str, dict[str, str]]:
"""Use the actual host path for directory-backed storage volumes."""
directory = cls._directory_pool_path(pool)
if directory is None:
return "volume", {"pool": pool.name(), "volume": volume.name()}
path = volume.path()
if (not isinstance(path, str) or not posixpath.isabs(path)
or posixpath.dirname(posixpath.normpath(path)) != directory):
raise VMError("存储卷路径不在面板配置的宿主机目录中", 502)
return "file", {"file": posixpath.normpath(path)}
def _domain_xml(self, spec: dict[str, Any], vm_uuid: str, disk_name: str,
disk_source: tuple[str, dict[str, str]],
iso_source: tuple[str, dict[str, str]], *,
install_phase: bool) -> str:
root = ET.Element("domain", type="kvm")
ET.SubElement(root, "name").text = spec.get("resource_name", spec["name"])
ET.SubElement(root, "uuid").text = vm_uuid
ET.SubElement(root, "memory", unit="MiB").text = str(spec["memory_mib"])
ET.SubElement(root, "vcpu", placement="static").text = str(spec["vcpu"])
os_node = ET.SubElement(root, "os", firmware="efi")
# AlmaLinux 10's x86_64 OVMF descriptors target Q35 machines. An
# unspecified machine can resolve to i440fx and make firmware='efi'
# fail even when virt-install --boot uefi succeeds on the same host.
ET.SubElement(os_node, "type", arch="x86_64", machine="q35").text = "hvm"
if install_phase:
ET.SubElement(os_node, "boot", dev="cdrom")
ET.SubElement(os_node, "boot", dev="hd")
# x86 UEFI firmware requires ACPI; virt-install also enables APIC.
features = ET.SubElement(root, "features")
ET.SubElement(features, "acpi")
ET.SubElement(features, "apic")
ET.SubElement(root, "cpu", mode="host-passthrough")
if install_phase:
# The installer's first reboot shuts the transient guest off.
# The next panel Start uses the persistent, ISO-free definition.
ET.SubElement(root, "on_reboot").text = "destroy"
metadata = ET.SubElement(root, "metadata")
managed = ET.SubElement(metadata, f"{{{PANEL_NS}}}managed", version="2",
**{"disk-volume": disk_name})
managed.set("display-name", spec["name"])
if spec.get("created_at"):
managed.set("created-at", spec["created_at"])
if spec.get("source") == "cloud" or spec.get("os_name") is not None:
# Keep the guest-side hostname visible to the panel without
# reading cloud-init user-data (which contains credentials) on
# every inventory call. Older VMs may not have this marker.
try:
managed.set("guest-hostname", default_guest_hostname(spec["name"], vm_uuid))
except ValueError as exc:
raise VMError("无法生成虚拟机初始主机名", 422) from exc
if "iso" in spec:
# The installation media does not prove which OS was installed.
managed.set("os-source", "iso")
managed.set("install-iso", spec["iso"])
if spec.get("user_iso_id"):
managed.set("install-iso-id", spec["user_iso_id"])
devices = ET.SubElement(root, "devices")
disk = ET.SubElement(devices, "disk", type=disk_source[0], device="disk")
ET.SubElement(disk, "driver", name="qemu", type="qcow2",
cache="none", discard="unmap")
ET.SubElement(disk, "source", **disk_source[1])
ET.SubElement(disk, "target", dev="vda", bus="virtio")
cdrom = ET.SubElement(devices, "disk", type=iso_source[0] if install_phase else "file",
device="cdrom")
ET.SubElement(cdrom, "driver", name="qemu", type="raw")
if install_phase:
ET.SubElement(cdrom, "source", **iso_source[1])
ET.SubElement(cdrom, "target", dev="sda", bus="sata")
ET.SubElement(cdrom, "readonly")
if self.bridge_name is None:
interface = ET.SubElement(devices, "interface", type="network")
ET.SubElement(interface, "source", network=self.network)
else:
interface = ET.SubElement(devices, "interface", type="bridge")
ET.SubElement(interface, "source", bridge=self.bridge_name)
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)))
if spec.get("bandwidth_mbps"):
# libvirt average/peak use KiB/s, while packages use decimal Mbps.
rate = (spec["bandwidth_mbps"] * 1_000_000 + 8191) // 8192
bandwidth = ET.SubElement(interface, "bandwidth")
for direction in ("inbound", "outbound"):
ET.SubElement(bandwidth, direction, average=str(rate), peak=str(rate))
graphics = ET.SubElement(devices, "graphics", type="vnc", port="-1",
autoport="yes", listen="127.0.0.1")
ET.SubElement(graphics, "listen", type="address", address="127.0.0.1")
video = ET.SubElement(devices, "video")
ET.SubElement(video, "model", type="vga")
ET.SubElement(devices, "input", type="tablet", bus="usb")
channel = ET.SubElement(devices, "channel", type="unix")
ET.SubElement(channel, "target", type="virtio", name="org.qemu.guest_agent.0")
memballoon = ET.SubElement(devices, "memballoon", model="virtio",
freePageReporting="on")
ET.SubElement(memballoon, "stats", period="10")
return ET.tostring(root, encoding="unicode")
def _rollback_new_vm(self, conn: Any, vm_uuid: str, resource_name: str,
pool: Any, volume: Any, disk_name: str) -> bool:
"""Delete the new disk only after verifying its VM no longer exists."""
try:
domains = [domain for domain in conn.listAllDomains(0)
if domain.UUIDString() == vm_uuid]
if (len(domains) > 1
or any(domain.name() != resource_name for domain in domains)):
LOG.error("Cannot safely identify new domain %s during rollback", vm_uuid)
return False
for domain in domains:
persistent = bool(domain.isPersistent())
if domain.isActive():
domain.destroy()
if persistent:
self._undefine_domain(domain, remove_nvram=True)
remaining = conn.listAllDomains(0)
if any(domain.UUIDString() == vm_uuid for domain in remaining):
LOG.error("New domain %s still exists after rollback", vm_uuid)
return False
# An external actor could have attached this newly created volume
# while the install was starting. Inspect both running and saved
# definitions before deleting it; uncertainty means retain it.
volume_path = volume.path()
pool_name = pool.name()
if not isinstance(volume_path, str) or not volume_path:
LOG.error("Cannot resolve volume %s path during rollback", disk_name)
return False
for other in remaining:
flags = [0]
if other.isActive() and other.isPersistent():
flags.append(libvirt.VIR_DOMAIN_XML_INACTIVE)
for flag in flags:
root = ET.fromstring(other.XMLDesc(flag))
for source in self._all_disk_sources(root):
if ((source.get("pool") == pool_name
and source.get("volume") == disk_name)
or volume_path in (source.get("file"), source.get("dev"))):
LOG.error("Another domain references volume %s; retaining it", disk_name)
return False
except Exception:
LOG.exception("Could not roll back domain %s; retaining disk %s", vm_uuid, disk_name)
return False
try:
volume.delete(0)
except Exception:
LOG.exception("Could not roll back volume %s", disk_name)
return False
return True
@staticmethod
def _upload_volume(conn: Any, volume: Any, chunks: Iterator[bytes], size: int) -> None:
"""Upload a local image through libvirt's authenticated SSH transport."""
stream = conn.newStream(0)
try:
volume.upload(stream, 0, size, 0)
uploaded = 0
for chunk in chunks:
if not isinstance(chunk, bytes):
raise VMError("镜像上传数据无效", 502)
pending = chunk
while pending:
sent = stream.send(pending)
if not isinstance(sent, int) or sent <= 0:
raise VMError("宿主机镜像上传中断", 502)
uploaded += sent
pending = pending[sent:]
if uploaded != size:
raise VMError("宿主机镜像上传长度不匹配", 502)
stream.finish()
except Exception:
try:
stream.abort()
except Exception:
LOG.exception("Could not abort failed libvirt volume upload")
raise
@staticmethod
def _download_seed_volume(conn: Any, volume: Any) -> bytes:
"""Read only a small CIDATA image through libvirt's SSH transport."""
size = int(volume.info()[1])
if not 0 < size <= 1024 * 1024:
raise VMError("原 cloud-init 配置盘大小无效,无法自动恢复网络", 409)
stream = conn.newStream(0)
try:
volume.download(stream, 0, size, 0)
chunks = []
remaining = size
while remaining:
chunk = stream.recv(min(65536, remaining))
if not isinstance(chunk, bytes) or not chunk:
raise VMError("原 cloud-init 配置盘读取不完整", 502)
chunks.append(chunk)
remaining -= len(chunk)
stream.finish()
return b"".join(chunks)
except Exception:
try:
stream.abort()
except Exception:
LOG.exception("Could not abort failed libvirt volume download")
raise
def import_template(self, image_path: Path, volume_name: str,
virtual_size: int) -> dict[str, Any]:
"""Place a verified qcow2 image in the configured host disk pool."""
if (not isinstance(volume_name, str)
or not TEMPLATE_VOLUME_RE.fullmatch(volume_name)):
raise VMError("模板卷名称无效")
if not isinstance(virtual_size, int) or not GIB <= virtual_size <= 4096 * GIB:
raise VMError("模板虚拟容量无效")
image_path = Path(image_path)
image_size = image_path.stat().st_size
with self._connect() as conn:
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
if volume_name in pool.listVolumes():
raise VMError("同名模板镜像已存在,不会覆盖", 409)
if image_size > pool.info()[3]:
raise VMError("宿主机存储池空间不足,无法导入模板", 409)
volume = pool.createXML(self._volume_xml_bytes(
volume_name, virtual_size, "qcow2"), 0)
if volume is None:
raise VMError("宿主机未能创建模板卷", 502)
try:
def read_chunks() -> Iterator[bytes]:
with image_path.open("rb") as image:
while chunk := image.read(1024 * 1024):
yield chunk
self._upload_volume(conn, volume, read_chunks(), image_size)
self._refresh_directory_pool(pool)
uploaded = pool.storageVolLookupByName(volume_name)
uploaded_xml = ET.fromstring(uploaded.XMLDesc(0))
uploaded_format = uploaded_xml.find("./target/format")
if (uploaded_format is None or uploaded_format.get("type") != "qcow2"
or int(uploaded.info()[1]) != virtual_size):
raise VMError("宿主机模板卷的格式或容量与原镜像不一致", 502)
return {"volume_name": volume_name, "virtual_size": virtual_size,
"image_bytes": image_size}
except Exception as exc:
try:
volume.delete(0)
except Exception:
LOG.exception("Template upload failed and volume %s remains", volume_name)
raise VMError(
f"模板导入失败且宿主机卷 {volume_name} 未能清理,请人工检查", 502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("Template upload failed for %s: %s", volume_name, exc)
raise VMError("模板镜像上传到宿主机失败", 502) from exc
@staticmethod
def _template_replica_identity(pool, volume) -> str:
"""Fingerprint the concrete pool/volume backing a ready marker."""
try:
pool_xml = ET.fromstring(pool.XMLDesc(0))
pool_type = pool_xml.get("type", "")
pool_target = pool_xml.findtext("./target/path", "")
pool_uuid_method = getattr(pool, "UUIDString", None)
pool_uuid = pool_uuid_method() if callable(pool_uuid_method) else ""
volume_key_method = getattr(volume, "key", None)
volume_key = volume_key_method() if callable(volume_key_method) else ""
volume_path = volume.path()
volume_info = volume.info()
capacity = int(volume_info[1])
allocation = int(volume_info[2])
volume_xml = ET.fromstring(volume.XMLDesc(0))
timestamps = volume_xml.find("./target/timestamps")
mtime = (timestamps.findtext("mtime", "").strip()
if timestamps is not None else "")
ctime = (timestamps.findtext("ctime", "").strip()
if timestamps is not None else "")
btime = (timestamps.findtext("btime", "").strip()
if timestamps is not None else "")
timestamp_re = re.compile(r"[0-9]+(?:\.[0-9]{1,9})?\Z")
if (timestamp_re.fullmatch(mtime) is None
or (timestamp_re.fullmatch(ctime) is None
and timestamp_re.fullmatch(btime) is None)
or (ctime and timestamp_re.fullmatch(ctime) is None)
or (btime and timestamp_re.fullmatch(btime) is None)):
raise ValueError("volume generation timestamps unavailable")
except (AttributeError, IndexError, TypeError, ValueError,
ET.ParseError, libvirt.libvirtError) as exc:
raise VMError("无法核对宿主机模板缓存身份", 502) from exc
fields = tuple(str(value) for value in (
"virt-cloud-template-replica-v2", pool.name(), pool_uuid,
pool_type, pool_target, volume.name(), volume_key, volume_path,
str(capacity), str(allocation), btime, ctime, mtime,
))
return hashlib.sha256("\0".join(fields).encode("utf-8")).hexdigest()
def cache_template(self, image_path: Path, volume_name: str,
virtual_size: int, *,
trusted_replica_volume_name: str | None = None,
trusted_replica_identity: str | None = None) -> dict[str, Any]:
"""Idempotently cache one engine-owned cloud image on this host.
``volume_name`` is the fresh generation reserved for an upload. A
prior generation is reusable only when both its name and its durable
identity are supplied and the concrete libvirt volume still matches.
If that proof fails, leave the prior generation untouched and upload
into ``volume_name``. A same-named desired volume has no ready proof
and may be an interrupted stream, so replace it only after proving no
domain references it.
"""
if (not isinstance(volume_name, str)
or not TEMPLATE_VOLUME_RE.fullmatch(volume_name)):
raise VMError("模板卷名称无效")
if not isinstance(virtual_size, int) or not GIB <= virtual_size <= 4096 * GIB:
raise VMError("模板虚拟容量无效")
image_path = Path(image_path)
if image_path.is_symlink() or not image_path.is_file():
raise VMError("云镜像源文件无效")
image_size = image_path.stat().st_size
if image_size <= 0:
raise VMError("云镜像源文件无效")
if ((trusted_replica_volume_name is None)
!= (trusted_replica_identity is None)):
raise VMError("模板缓存身份不完整")
if (trusted_replica_volume_name is not None
and (not isinstance(trusted_replica_volume_name, str)
or not TEMPLATE_VOLUME_RE.fullmatch(
trusted_replica_volume_name))):
raise VMError("模板缓存卷名称无效")
if (trusted_replica_identity is not None
and (not isinstance(trusted_replica_identity, str)
or re.fullmatch(
r"[0-9a-f]{64}", trusted_replica_identity) is None)):
raise VMError("模板缓存身份无效")
if trusted_replica_volume_name == volume_name:
raise VMError("模板缓存的新旧卷名称不能相同")
with _CREATE_LOCK, self._connect() as conn:
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
if (trusted_replica_volume_name is not None
and trusted_replica_volume_name in pool.listVolumes()):
trusted = pool.storageVolLookupByName(trusted_replica_volume_name)
trusted_identity = None
try:
trusted_xml = ET.fromstring(trusted.XMLDesc(0))
trusted_format = trusted_xml.find("./target/format")
trusted_capacity = int(trusted.info()[1])
if (trusted_format is not None
and trusted_format.get("type") == "qcow2"
and trusted_capacity == virtual_size):
trusted_identity = self._template_replica_identity(
pool, trusted)
except (ET.ParseError, TypeError, ValueError, VMError,
libvirt.libvirtError):
LOG.warning(
"Could not prove trusted template replica %s; "
"uploading a fresh generation",
trusted_replica_volume_name,
)
if (trusted_identity is not None
and secrets.compare_digest(
trusted_replica_identity, trusted_identity)):
return {
"volume_name": trusted_replica_volume_name,
"virtual_size": virtual_size,
"image_bytes": image_size,
"already_cached": True,
"replica_identity": trusted_identity,
}
if volume_name in pool.listVolumes():
existing = pool.storageVolLookupByName(volume_name)
try:
existing_path = existing.path()
except (AttributeError, libvirt.libvirtError) as exc:
raise VMError("无法核对宿主机模板卷路径", 502) from exc
if self._other_domain_uses_volume(
conn, "", pool.name(), volume_name, existing_path):
raise VMError(
"宿主机模板缓存未能确认完整且正被虚拟机引用", 409)
existing.delete(0)
self._refresh_directory_pool(pool)
if image_size > pool.info()[3]:
raise VMError("宿主机存储池空间不足,无法缓存模板", 409)
volume = pool.createXML(self._volume_xml_bytes(
volume_name, virtual_size, "qcow2"), 0)
if volume is None:
raise VMError("宿主机未能创建模板缓存卷", 502)
try:
def read_chunks() -> Iterator[bytes]:
with image_path.open("rb") as image:
while chunk := image.read(1024 * 1024):
yield chunk
self._upload_volume(conn, volume, read_chunks(), image_size)
self._refresh_directory_pool(pool)
uploaded = pool.storageVolLookupByName(volume_name)
uploaded_xml = ET.fromstring(uploaded.XMLDesc(0))
uploaded_format = uploaded_xml.find("./target/format")
if (uploaded_format is None
or uploaded_format.get("type") != "qcow2"
or int(uploaded.info()[1]) != virtual_size):
raise VMError("宿主机模板缓存的格式或容量与源镜像不一致", 502)
replica_identity = self._template_replica_identity(pool, uploaded)
return {
"volume_name": volume_name,
"virtual_size": virtual_size,
"image_bytes": image_size,
"already_cached": False,
"replica_identity": replica_identity,
}
except Exception as exc:
try:
volume.delete(0)
except Exception:
LOG.exception(
"Template cache upload failed and volume %s remains",
volume_name,
)
raise VMError(
f"模板缓存失败且宿主机卷 {volume_name} 未能清理,请人工检查",
502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("Template cache upload failed for %s: %s", volume_name, exc)
raise VMError("云镜像缓存到宿主机失败", 502) from exc
def delete_cloud_template_replicas(
self, source_volume_name: str) -> dict[str, Any]:
"""Delete every host-local generation derived from one global image.
A failed identity check can intentionally leave an older generation
beside the current ready replica. Deletion therefore scans the
tightly validated source-name namespace instead of trusting only the
latest marker. All candidates are checked for domain references
before any is removed, so the operation is safe to retry.
"""
if (not isinstance(source_volume_name, str)
or not TEMPLATE_SOURCE_VOLUME_RE.fullmatch(source_volume_name)):
raise VMError("云镜像源卷名称无效")
replica_prefix = source_volume_name.removesuffix(".qcow2") + "-"
replica_re = re.compile(
re.escape(replica_prefix) + r"[0-9a-f]{16}\.qcow2\Z"
)
with _CREATE_LOCK, self._connect() as conn:
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
candidates = sorted(
name for name in pool.listVolumes()
if name == source_volume_name or replica_re.fullmatch(name)
)
if not candidates:
raise VMError(
"云镜像宿主机缓存不存在", 404,
error_code="cloud_template_cache_not_found",
)
volumes = []
for name in candidates:
if not TEMPLATE_VOLUME_RE.fullmatch(name):
raise VMError("云镜像宿主机缓存名称无效", 500)
volume = pool.storageVolLookupByName(name)
try:
path = volume.path()
except (AttributeError, libvirt.libvirtError) as exc:
raise VMError("无法核对宿主机模板卷路径", 502) from exc
if self._other_domain_uses_volume(
conn, "", pool.name(), name, path):
raise VMError("云镜像仍被虚拟机引用,不能删除", 409)
volumes.append((name, volume))
for _name, volume in volumes:
volume.delete(0)
return {
"source_volume_name": source_volume_name,
"deleted": True,
"deleted_volumes": [name for name, _volume in volumes],
}
@staticmethod
def _check_user_iso_volume_name(volume_name: str) -> None:
if not isinstance(volume_name, str) or not USER_ISO_VOLUME_RE.fullmatch(volume_name):
raise VMError("用户 ISO 卷名称无效")
def _user_iso_volume(self, conn: Any, user_id: int,
volume_name: str) -> tuple[Any, Any]:
self._check_user_iso_volume_name(volume_name)
pool = self._active_user_iso_pool(conn, user_id)
self._refresh_directory_pool(pool)
if volume_name not in pool.listVolumes():
raise VMError("用户 ISO 在宿主机上不存在,请重新上传", 404)
volume = pool.storageVolLookupByName(volume_name)
# Also proves the returned host path is an immediate child of the
# authenticated user's numeric directory.
self._volume_source(pool, volume)
try:
root = ET.fromstring(volume.XMLDesc(0))
fmt = root.find("./target/format")
size = int(volume.info()[1])
except (ET.ParseError, TypeError, ValueError) as exc:
raise VMError("用户 ISO 卷信息无效", 502) from exc
if (fmt is None or fmt.get("type") != "raw"
or not 1024 * 1024 <= size <= MAX_USER_ISO_BYTES):
raise VMError("用户 ISO 必须是有效大小的 raw ISO 卷", 409)
return pool, volume
def check_user_iso_storage(self, user_id: int) -> dict[str, int]:
"""Prepare and verify the owner's directory before any remote download."""
user_id = self._user_id(user_id)
try:
with _CREATE_LOCK, self._connect() as conn:
pool = self._active_user_iso_pool(conn, user_id)
try:
available = int(pool.info()[3])
except (IndexError, TypeError, ValueError, libvirt.libvirtError) as exc:
raise VMError("无法核对用户 ISO 存储空间", 502) from exc
if available < 1024 * 1024:
raise VMError("宿主机用户 ISO 存储空间不足", 409)
return {"available_bytes": available}
except VMError as exc:
if str(exc) == "宿主机用户 ISO 存储空间不足":
raise
LOG.warning("User ISO storage preflight failed for owner %s: %s",
user_id, exc)
raise VMError("用户 ISO 存储目录不可用,请联系管理员",
502 if exc.status >= 500 else 409) from exc
def cache_user_iso(self, image_path: Path, user_id: int,
volume_name: str,
active_volume_names: set[str] | None = None,
*, trusted_existing: bool = False) -> dict[str, Any]:
"""Idempotently cache an engine-owned ISO under ISO_ROOT/."""
user_id = self._user_id(user_id)
self._check_user_iso_volume_name(volume_name)
if active_volume_names is not None:
if (not isinstance(active_volume_names, set)
or volume_name not in active_volume_names
or any(not isinstance(name, str)
or not USER_ISO_VOLUME_RE.fullmatch(name)
for name in active_volume_names)):
raise VMError("用户 ISO 缓存清单无效")
image_path = Path(image_path)
if image_path.is_symlink() or not image_path.is_file():
raise VMError("用户 ISO 文件无效")
try:
verify_user_iso(image_path)
except Exception as exc:
raise VMError(str(exc), getattr(exc, "status", 422)) from exc
image_size = image_path.stat().st_size
with _CREATE_LOCK, self._connect() as conn:
pool = self._active_user_iso_pool(conn, user_id)
names = pool.listVolumes()
if active_volume_names is not None:
for name in list(names):
if (not USER_ISO_VOLUME_RE.fullmatch(name)
or name in active_volume_names):
continue
stale = pool.storageVolLookupByName(name)
stale_path = self._volume_source(pool, stale)[1].get("file")
if (stale_path is not None and not self._other_domain_uses_volume(
conn, "", pool.name(), name, stale_path)):
stale.delete(0)
self._refresh_directory_pool(pool)
names = pool.listVolumes()
if volume_name in names:
_existing_pool, existing = self._user_iso_volume(
conn, user_id, volume_name)
existing_size = int(existing.info()[1])
if trusted_existing and existing_size == image_size:
return {
"volume_name": volume_name,
"image_bytes": image_size,
"already_cached": True,
}
existing_path = existing.path()
if self._other_domain_uses_volume(
conn, "", pool.name(), volume_name, existing_path):
raise VMError(
"宿主机的 ISO 缓存未能确认完整且正被虚拟机引用",
409,
)
# A volume without the host-scoped ready marker may be a
# preallocated remainder from an interrupted upload. Never
# accept it merely because its declared size matches.
existing.delete(0)
self._refresh_directory_pool(pool)
names = pool.listVolumes()
sizes = []
for name in names:
try:
sizes.append(int(pool.storageVolLookupByName(name).info()[1]))
except (KeyError, TypeError, ValueError, libvirt.libvirtError) as exc:
raise VMError("无法核对用户 ISO 目录配额", 502) from exc
if len(names) >= MAX_USER_ISOS:
raise VMError("每个宿主机最多保存 5 个用户 ISO", 409)
if sum(sizes) + image_size > MAX_USER_ISO_TOTAL_BYTES:
raise VMError("用户 ISO 目录总容量不能超过 10 GiB", 409)
if image_size > pool.info()[3]:
raise VMError("宿主机用户 ISO 存储空间不足", 409)
volume = pool.createXML(
self._volume_xml_bytes(volume_name, image_size, "raw"), 0)
if volume is None:
raise VMError("宿主机未能创建用户 ISO 卷", 502)
try:
def read_chunks() -> Iterator[bytes]:
with image_path.open("rb") as image:
while chunk := image.read(1024 * 1024):
yield chunk
self._upload_volume(conn, volume, read_chunks(), image_size)
self._user_iso_volume(conn, user_id, volume_name)
return {"volume_name": volume_name, "image_bytes": image_size,
"already_cached": False}
except Exception as exc:
try:
volume.delete(0)
except Exception:
LOG.exception("User ISO upload failed and volume %s remains", volume_name)
raise VMError(
f"用户 ISO 上传失败且宿主机卷 {volume_name} 未能清理,请人工检查",
502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("User ISO upload failed for %s: %s", volume_name, exc)
raise VMError("用户 ISO 上传到宿主机失败", 502) from exc
def import_user_iso(self, image_path: Path, user_id: int,
volume_name: str) -> dict[str, Any]:
"""Compatibility alias for callers predating the global cache."""
return self.cache_user_iso(image_path, user_id, volume_name)
def delete_user_iso(self, user_id: int, volume_name: str) -> dict[str, Any]:
"""Delete only an opaque ISO in this owner's numeric directory."""
user_id = self._user_id(user_id)
self._check_user_iso_volume_name(volume_name)
with _CREATE_LOCK, self._connect() as conn:
pool = self._active_user_iso_pool(conn, user_id, create=False)
if pool is None:
raise VMError(
"用户 ISO 在宿主机上不存在", 404,
error_code="user_iso_volume_not_found",
)
self._refresh_directory_pool(pool)
if volume_name not in pool.listVolumes():
raise VMError(
"用户 ISO 在宿主机上不存在", 404,
error_code="user_iso_volume_not_found",
)
volume = pool.storageVolLookupByName(volume_name)
self._volume_source(pool, volume)
if self._other_domain_uses_volume(
conn, "", pool.name(), volume_name, volume.path()):
raise VMError("用户 ISO 仍被虚拟机安装过程引用,不能删除", 409)
volume.delete(0)
return {"volume_name": volume_name, "deleted": True}
@staticmethod
def _check_rescue_volume_name(volume_name: str) -> None:
if not isinstance(volume_name, str) or not RESCUE_VOLUME_RE.fullmatch(volume_name):
raise VMError("救援镜像卷名称无效")
def _lookup_rescue_volume(self, conn: Any, volume_name: str) -> tuple[Any, Any]:
self._check_rescue_volume_name(volume_name)
pool = self._active_rescue_pool(conn)
self._refresh_directory_pool(pool)
if volume_name not in pool.listVolumes():
raise VMError(
"救援镜像在宿主机上不存在,请重新上传", 404,
error_code="rescue_volume_not_found",
)
volume = pool.storageVolLookupByName(volume_name)
self._volume_source(pool, volume)
return pool, volume
def _rescue_volume(self, conn: Any, volume_name: str) -> tuple[Any, Any]:
pool, volume = self._lookup_rescue_volume(conn, volume_name)
try:
root = ET.fromstring(volume.XMLDesc(0))
fmt = root.find("./target/format")
size = int(volume.info()[1])
except (ET.ParseError, TypeError, ValueError) as exc:
raise VMError("救援镜像卷信息无效", 502) from exc
if (fmt is None or fmt.get("type") != "raw"
or not MIN_RESCUE_ISO_BYTES <= size <= MAX_RESCUE_ISO_BYTES):
raise VMError("救援镜像必须是有效大小的 raw ISO 卷", 409)
return pool, volume
def import_rescue_iso(self, image_path: Path, volume_name: str) -> dict[str, Any]:
"""Upload one administrator-supplied ISO to the dedicated rescue pool."""
self._check_rescue_volume_name(volume_name)
image_path = Path(image_path)
if image_path.is_symlink() or not image_path.is_file():
raise VMError("救援镜像文件无效")
image_size = image_path.stat().st_size
if not MIN_RESCUE_ISO_BYTES <= image_size <= MAX_RESCUE_ISO_BYTES:
raise VMError("救援 ISO 大小必须在 1 MiB 至 8 GiB 之间", 422)
with image_path.open("rb") as image:
image.seek(32769)
if image.read(5) != b"CD001":
raise VMError("上传的文件不是 ISO 9660 镜像", 422)
with self._connect() as conn:
pool = self._active_rescue_pool(conn)
self._refresh_directory_pool(pool)
if volume_name in pool.listVolumes():
raise VMError("同名救援镜像已存在,不会覆盖", 409)
if image_size > pool.info()[3]:
raise VMError("宿主机救援 ISO 存储池空间不足", 409)
volume = pool.createXML(self._volume_xml_bytes(
volume_name, image_size, "raw"), 0)
if volume is None:
raise VMError("宿主机未能创建救援镜像卷", 502)
try:
def read_chunks() -> Iterator[bytes]:
with image_path.open("rb") as image:
while chunk := image.read(1024 * 1024):
yield chunk
self._upload_volume(conn, volume, read_chunks(), image_size)
self._rescue_volume(conn, volume_name)
return {"volume_name": volume_name, "image_bytes": image_size}
except Exception as exc:
try:
volume.delete(0)
except Exception:
LOG.exception("Rescue ISO upload failed and volume %s remains", volume_name)
raise VMError(
f"救援镜像上传失败且宿主机卷 {volume_name} 未能清理,请人工检查", 502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("Rescue ISO upload failed for %s: %s", volume_name, exc)
raise VMError("救援镜像上传到宿主机失败", 502) from exc
def delete_rescue_iso(self, volume_name: str) -> dict[str, Any]:
"""Delete only a panel-named rescue ISO unused by every domain."""
with _CREATE_LOCK, self._connect() as conn:
pool, volume = self._lookup_rescue_volume(conn, volume_name)
if self._other_domain_uses_volume(
conn, "", pool.name(), volume_name, volume.path()):
raise VMError("救援镜像仍被虚拟机引用,不能删除", 409)
volume.delete(0)
return {"volume_name": volume_name, "deleted": True}
@staticmethod
def _rescue_original_hash(original_xml: str) -> str:
if not isinstance(original_xml, str) or not original_xml:
raise VMError("原虚拟机配置备份无效", 409)
return hashlib.sha256(original_xml.encode("utf-8")).hexdigest()
@staticmethod
def _rescue_xml_matches(first: str, second: str) -> bool:
try:
return ET.canonicalize(first) == ET.canonicalize(second)
except ET.ParseError as exc:
raise VMError("虚拟机配置 XML 无效", 502) from exc
@staticmethod
def _rescue_vm_preflight(domain: Any) -> str:
if not domain.isPersistent():
raise VMError("只有持久化虚拟机可以进入救援模式", 409)
if getattr(domain, "hasManagedSaveImage", lambda _flags: 0)(0):
raise VMError("虚拟机存在托管保存状态,请先处理后再救援", 409)
original_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
try:
root = ET.fromstring(original_xml)
except ET.ParseError as exc:
raise VMError("虚拟机配置 XML 无效", 502) from exc
if root.find(f"./metadata/{{{PANEL_NS}}}rescue") is not None:
raise VMError("虚拟机已处于救援模式", 409)
if root.find("./devices/disk[@device='disk']") is None:
raise VMError("虚拟机没有系统磁盘,不能进入救援模式", 409)
return original_xml
@staticmethod
def _rescue_xml(original_xml: str, vm_uuid: str, volume_name: str,
source: tuple[str, dict[str, str]], autostart: bool) -> str:
try:
root = ET.fromstring(original_xml)
except ET.ParseError as exc:
raise VMError("原虚拟机配置备份无效", 409) from exc
if root.findtext("uuid") != vm_uuid:
raise VMError("原虚拟机配置备份与目标虚拟机不匹配", 409)
os_node = root.find("os")
devices = root.find("devices")
if os_node is None or devices is None:
raise VMError("原虚拟机配置缺少启动或设备信息", 409)
disks = [disk for disk in devices.findall("disk")
if disk.get("device") == "disk"]
if not disks:
raise VMError("虚拟机没有系统磁盘,不能进入救援模式", 409)
explicitly_booted = [disk for disk in disks
if (disk.find("boot") is not None
and disk.find("boot").get("order") == "1")]
if len(explicitly_booted) == 1:
primary = explicitly_booted[0]
else:
primary = next((disk for disk in disks
if disk.find("target") is not None
and disk.find("target").get("dev") == "vda"), None)
if primary is None and len(disks) == 1:
primary = disks[0]
if primary is None:
raise VMError("无法确定多磁盘虚拟机的系统盘,请先确认原启动顺序", 409)
# A cloud-init seed ISO often occupies the existing CD-ROM. Booting
# "cdrom" as a class could select the wrong image, so target the new
# device explicitly and keep every original device unchanged in the
# saved XML used on exit.
for boot in list(os_node.findall("boot")):
os_node.remove(boot)
for device in devices:
for boot in list(device.findall("boot")):
device.remove(boot)
ET.SubElement(primary, "boot", order="2")
used_targets = {target.get("dev") for target in devices.findall("./disk/target")}
rescue_target = next((f"sd{chr(code)}" for code in range(ord("a"), ord("z") + 1)
if f"sd{chr(code)}" not in used_targets), None)
if rescue_target is None:
raise VMError("虚拟机没有可用的 SATA 光驱目标位置", 409)
cdrom = ET.SubElement(devices, "disk", type=source[0], device="cdrom")
ET.SubElement(cdrom, "driver", name="qemu", type="raw")
ET.SubElement(cdrom, "source", **source[1])
ET.SubElement(cdrom, "target", dev=rescue_target, bus="sata")
ET.SubElement(cdrom, "readonly")
ET.SubElement(cdrom, "boot", order="1")
metadata = root.find("metadata")
if metadata is None:
metadata = ET.SubElement(root, "metadata")
ET.SubElement(metadata, f"{{{PANEL_NS}}}rescue",
volume=volume_name,
**{"original-sha256": VMService._rescue_original_hash(original_xml),
"original-autostart": "1" if autostart else "0"})
return ET.tostring(root, encoding="unicode")
@staticmethod
def _restore_rescue_autostart(domain: Any, enabled: bool) -> None:
if bool(domain.autostart()) != enabled:
domain.setAutostart(int(enabled))
@staticmethod
def _wait_for_rescue_shutdown(domain: Any, phase: str) -> None:
if not domain.isActive():
return
if phase == "救援启动":
next_step = (
"救援 ISO 已写入下次冷启动配置。请先刷新虚拟机状态;如仍在运行,"
"可在救援页面点击“强制重启进入救援”(强制断电后从救援配置开机),"
"也可以手动“强制断电”后再点“开机”。"
"普通“强制重置”只重置运行中的 QEMU,不会加载新的启动配置;"
"强制断电可能导致未保存数据丢失"
)
else:
next_step = (
"原系统启动配置尚未恢复。请先刷新虚拟机状态;如仍在运行,"
"可通过救援系统的 VNC 控制台手动关机,待显示已关机后重试退出救援"
)
try:
domain.shutdown()
except libvirt.libvirtError as exc:
raise VMError(
f"无法请求虚拟机正常关机,{phase}尚未完成;面板未强制断电。{next_step}",
409,
) from exc
deadline = time.monotonic() + REINSTALL_SHUTDOWN_TIMEOUT
while domain.isActive():
if time.monotonic() >= deadline:
raise VMError(
f"正常关机超时,{phase}尚未完成;虚拟机可能随后自行关机。"
f"面板未强制断电。{next_step}", 409)
time.sleep(REINSTALL_SHUTDOWN_POLL_INTERVAL)
def prepare_rescue_vm(self, vm_id: str, rescue_volume_name: str) -> str:
"""Return inactive XML for durable storage before changing this VM."""
with _CREATE_LOCK, self._connect() as conn:
self._rescue_volume(conn, rescue_volume_name)
return self._rescue_vm_preflight(self._domain(conn, vm_id))
def enter_rescue_vm(self, vm_id: str, rescue_volume_name: str,
original_xml: str, *,
progress: Callable[[str], None] | None = None) -> dict[str, Any]:
"""Stage a durable rescue boot, gracefully stop, then start the ISO."""
def phase(value: str) -> None:
if progress is not None:
progress(value)
with _CREATE_LOCK, self._connect() as conn:
vm_uuid = self._uuid(vm_id)
domain = self._domain(conn, vm_uuid)
current_xml = self._rescue_vm_preflight(domain)
if not self._rescue_xml_matches(current_xml, original_xml):
raise VMError("虚拟机配置已变化,请重新提交救援操作", 409)
original_root = ET.fromstring(original_xml)
platform_policy, platform_policy_was_explicit = (
_platform_policy_state_from_domain_xml(original_root))
pool, volume = self._rescue_volume(conn, rescue_volume_name)
original_autostart = bool(domain.autostart())
rescue_xml = self._rescue_xml(
original_xml, vm_uuid, rescue_volume_name,
self._volume_source(pool, volume), original_autostart)
was_running = bool(domain.isActive())
switched = False
rescue_domain = None
try:
phase("mounting")
rescue_domain = conn.defineXML(rescue_xml)
if rescue_domain is None:
raise VMError("宿主机未能保存救援启动配置", 502)
switched = True
if platform_policy is not None:
_verify_platform_policy_in_domain(
rescue_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(rescue_domain, original_autostart)
staged_xml = rescue_domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
except Exception as exc:
restored = True
if switched:
try:
restored_domain = conn.defineXML(original_xml)
if restored_domain is None:
raise VMError("宿主机未能恢复原虚拟机配置", 502)
if platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(restored_domain, original_autostart)
except Exception:
LOG.exception("Could not restore original VM XML for %s", vm_uuid)
restored = False
if not restored:
raise VMError(
"救援 ISO 预挂载失败且原虚拟机持久配置未能恢复;"
"没有强制断电,请检查宿主机", 502,
) from exc
raise VMError("救援 ISO 预挂载失败,原虚拟机未受影响", 502) from exc
phase("shutting_down")
try:
self._wait_for_rescue_shutdown(domain, "救援启动")
except VMError as exc:
if domain.isActive():
vm = self._vm_dict(domain)
if vm["rescue_mode"] and not vm["rescue_staged"]:
# The guest may have shut down and been cold-started
# by an external actor while the request timed out.
return {"vm": vm, "warning":
"救援配置已运行,但宿主机关机状态返回异常;请通过 VNC 确认已进入救援系统"}
# Never discard the persistent rescue boot here: the user
# can safely decide whether to power-cycle manually.
phase("pending_manual_restart")
return {"vm": vm,
"pending_manual_restart": True,
"warning": str(exc)}
# The guest stopped after the error; continue with a cold
# start from the already-staged rescue definition.
latest_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
if not self._rescue_xml_matches(latest_xml, staged_xml):
raise VMError("关机后救援启动配置已变化,救援已停止;请检查虚拟机状态", 409)
try:
phase("starting")
rescue_domain.create()
except Exception as exc:
if switched and rescue_domain is not None:
try:
if rescue_domain.isActive() and self._vm_dict(rescue_domain)["rescue_mode"]:
phase("completed")
return {"vm": self._vm_dict(rescue_domain),
"warning": "救援系统可能已启动,但宿主机启动返回错误;请检查控制台"}
except Exception:
LOG.exception("Could not inspect rescue VM %s after start error", vm_uuid)
restored = True
restart_domain = domain
if switched:
try:
restored_domain = conn.defineXML(original_xml)
if restored_domain is None:
raise VMError("宿主机未能恢复原虚拟机配置", 502)
if platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(restored_domain, original_autostart)
restart_domain = restored_domain
except Exception:
LOG.exception("Could not restore original VM XML for %s", vm_uuid)
restored = False
if restored and was_running:
try:
restart_domain.create()
except Exception:
LOG.exception("Could not restart original VM %s after rescue failure", vm_uuid)
restored = False
if not restored:
raise VMError(
"救援启动失败且原虚拟机未能完全恢复;没有强制断电,请检查宿主机", 502,
) from exc
raise VMError("救援启动失败,已恢复原虚拟机配置及运行状态", 502) from exc
phase("completed")
return {"vm": self._vm_dict(rescue_domain)}
def force_start_staged_rescue_vm(self, vm_id: str,
original_xml: str) -> dict[str, Any]:
"""Cold power-cycle only a verified, pre-staged rescue VM.
libvirt's reset() acts on the live QEMU process and cannot load a
changed inactive boot definition. destroy()+create() deliberately
stops that process and starts a new one from the persistent XML.
"""
with _CREATE_LOCK, self._connect() as conn:
vm_uuid = self._uuid(vm_id)
domain = self._domain(conn, vm_uuid)
if not domain.isPersistent():
raise VMError("救援虚拟机不是持久化定义,不能强制重启", 409)
try:
original_root = ET.fromstring(original_xml)
except (TypeError, ET.ParseError) as exc:
raise VMError("原虚拟机配置备份无效", 409) from exc
if (original_root.findtext("uuid") != vm_uuid
or original_root.find(f"./metadata/{{{PANEL_NS}}}rescue") is not None):
raise VMError("原虚拟机配置备份与目标虚拟机不匹配", 409)
try:
staged_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
except ET.ParseError as exc:
raise VMError("救援虚拟机持久配置 XML 无效", 502) from exc
marker = staged_root.find(f"./metadata/{{{PANEL_NS}}}rescue")
if (marker is None or marker.get("original-sha256") !=
self._rescue_original_hash(original_xml)
or not RESCUE_VOLUME_RE.fullmatch(marker.get("volume", ""))
or marker.get("original-autostart") not in {"0", "1"}):
raise VMError("救援预挂载记录与原配置备份不匹配,已拒绝强制重启", 409)
if domain.isActive() and self._vm_xml(domain).find(
f"./metadata/{{{PANEL_NS}}}rescue") is not None:
raise VMError("虚拟机已从救援配置运行,无需再次强制重启", 409)
pool, volume = self._rescue_volume(conn, marker.get("volume"))
source_type, source_attrs = self._volume_source(pool, volume)
if not any(
disk.get("type") == source_type
and disk.find("source") is not None
and all(disk.find("source").get(key) == value
for key, value in source_attrs.items())
and disk.find("boot") is not None
and disk.find("boot").get("order") == "1"
for disk in staged_root.findall("./devices/disk[@device='cdrom']")):
raise VMError("救援 ISO 启动设备与预挂载记录不匹配,已拒绝强制重启", 409)
if domain.isActive():
try:
domain.destroy()
except libvirt.libvirtError as exc:
if domain.isActive():
raise VMError("强制断电失败;救援配置已保留,请检查虚拟机状态", 502) from exc
try:
domain.create()
except libvirt.libvirtError as exc:
try:
vm = self._vm_dict(domain)
if (vm["state"] == "running" and vm["rescue_mode"]
and not vm["rescue_staged"]):
return {"vm": vm,
"warning": "救援系统可能已启动,但宿主机返回错误;请检查控制台"}
except Exception:
LOG.exception("Could not inspect staged rescue VM %s after start error", vm_uuid)
raise VMError(
"救援系统强制重启后未能启动;救援 ISO 配置已保留,"
"可重试开机或取消救援。强制断电可能导致未保存数据丢失", 502,
) from exc
vm = self._vm_dict(domain)
if not domain.isActive() or not vm["rescue_mode"] or vm["rescue_staged"]:
raise VMError(
"已尝试强制启动,但救援系统未进入运行状态;"
"救援 ISO 配置已保留,请检查控制台或重试开机", 502,
)
return {"vm": vm}
def exit_rescue_vm(self, vm_id: str, original_xml: str, *,
network_suspended: bool = False,
progress: Callable[[str], None] | None = None) -> dict[str, Any]:
"""Gracefully stop rescue mode, restore original XML, and start OS.
``original_xml`` predates rescue mode and can therefore contain a
stale NIC link state. The billing ledger passes its current target so
quota suspension survives the definition swap atomically; a later
network_resume is the only operation that reconnects the guest.
"""
def phase(value: str) -> None:
if progress is not None:
progress(value)
with _CREATE_LOCK, self._connect() as conn:
vm_uuid = self._uuid(vm_id)
domain = self._domain(conn, vm_uuid)
if not domain.isPersistent():
raise VMError("救援虚拟机不是持久化定义,无法恢复", 409)
try:
original_root = ET.fromstring(original_xml)
except (TypeError, ET.ParseError) as exc:
raise VMError("原虚拟机配置备份无效", 409) from exc
if (original_root.findtext("uuid") != vm_uuid
or original_root.find(f"./metadata/{{{PANEL_NS}}}rescue") is not None):
raise VMError("原虚拟机配置备份与目标虚拟机不匹配", 409)
platform_policy, platform_policy_was_explicit = (
_platform_policy_state_from_domain_xml(original_root))
target_link_state = "down" if network_suspended else "up"
for interface in original_root.findall("./devices/interface"):
link = interface.find("link")
if link is None:
link = ET.SubElement(interface, "link")
link.set("state", target_link_state)
restored_xml = ET.tostring(original_root, encoding="unicode")
rescue_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
try:
rescue_root = ET.fromstring(rescue_xml)
except ET.ParseError as exc:
raise VMError("救援虚拟机配置 XML 无效", 502) from exc
_require_same_platform_policy_state(
rescue_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="救援虚拟机平台网络策略已变化,已停止恢复",
)
marker = rescue_root.find(f"./metadata/{{{PANEL_NS}}}rescue")
if (marker is None or marker.get("original-sha256") !=
self._rescue_original_hash(original_xml)
or not RESCUE_VOLUME_RE.fullmatch(marker.get("volume", ""))
or marker.get("original-autostart") not in {"0", "1"}):
raise VMError("虚拟机救援标记与原配置备份不匹配,已停止恢复", 409)
staged_running = False
if domain.isActive():
live_marker = self._vm_xml(domain).find(
f"./metadata/{{{PANEL_NS}}}rescue")
staged_running = live_marker is None
if (live_marker is not None
and (live_marker.get("original-sha256") !=
marker.get("original-sha256")
or live_marker.get("volume") != marker.get("volume"))):
raise VMError("虚拟机当前并未从已记录的救援配置运行,已停止恢复", 409)
original_autostart = marker.get("original-autostart") == "1"
rescue_autostart = bool(domain.autostart())
if staged_running:
# Rescue was saved for the next cold boot, but the original
# guest is still running. Cancelling the staged boot must not
# shut down or restart that guest.
switched = False
try:
phase("restoring")
normal_domain = conn.defineXML(restored_xml)
if normal_domain is None:
raise VMError("宿主机未能恢复原虚拟机配置", 502)
switched = True
if platform_policy is not None:
_verify_platform_policy_in_domain(
normal_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(normal_domain, original_autostart)
except Exception as exc:
if switched:
try:
rescue_domain = conn.defineXML(rescue_xml)
if rescue_domain is None:
raise VMError("宿主机未能恢复救援启动配置", 502)
if platform_policy is not None:
_verify_platform_policy_in_domain(
rescue_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(
rescue_domain, rescue_autostart)
except Exception:
LOG.exception("Could not restore staged rescue XML for %s", vm_uuid)
raise VMError(
"取消救援预挂载失败,原虚拟机仍在运行,但持久配置状态不确定;"
"请检查宿主机", 502,
) from exc
raise VMError("取消救援预挂载失败,原虚拟机仍在运行", 502) from exc
phase("completed")
return {"vm": self._vm_dict(normal_domain)}
was_running = bool(domain.isActive())
phase("shutting_down")
self._wait_for_rescue_shutdown(domain, "退出救援")
latest_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
if not self._rescue_xml_matches(latest_xml, rescue_xml):
raise VMError("关机后救援配置已变化,退出救援已停止;请检查虚拟机状态", 409)
switched = False
normal_domain = None
try:
phase("starting")
normal_domain = conn.defineXML(restored_xml)
if normal_domain is None:
raise VMError("宿主机未能恢复原虚拟机配置", 502)
switched = True
if platform_policy is not None:
_verify_platform_policy_in_domain(
normal_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(normal_domain, original_autostart)
normal_domain.create()
except Exception as exc:
if switched and normal_domain is not None:
try:
if normal_domain.isActive() and not self._vm_dict(normal_domain)["rescue_mode"]:
phase("completed")
return {"vm": self._vm_dict(normal_domain),
"warning": "原系统可能已启动,但宿主机启动返回错误;请检查控制台"}
except Exception:
LOG.exception("Could not inspect VM %s after rescue exit error", vm_uuid)
restored = True
restart_domain = domain
if switched:
try:
restored_domain = conn.defineXML(rescue_xml)
if restored_domain is None:
raise VMError("宿主机未能恢复救援启动配置", 502)
if platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
self._restore_rescue_autostart(restored_domain, rescue_autostart)
restart_domain = restored_domain
except Exception:
LOG.exception("Could not restore rescue VM XML for %s", vm_uuid)
restored = False
if restored and was_running:
try:
restart_domain.create()
except Exception:
LOG.exception("Could not restart rescue VM %s after exit failure", vm_uuid)
restored = False
if not restored:
raise VMError(
"退出救援失败且救援虚拟机未能完全恢复;没有强制断电,请检查宿主机", 502,
) from exc
raise VMError("退出救援失败,已恢复救援启动配置及运行状态", 502) from exc
phase("completed")
vm = self._vm_dict(normal_domain)
if vm["rescue_mode"]:
raise VMError("原系统已启动但仍显示救援模式,请检查虚拟机配置", 502)
return {"vm": vm}
@staticmethod
def _cloud_seed_needs_debian12_network_fix(template_volume_name: str) -> bool:
"""Return whether the seed needs the Debian 12 cloud-init safeguard."""
return bool(
TEMPLATE_VOLUME_RE.fullmatch(template_volume_name)
and template_volume_name.startswith(DEBIAN_12_TEMPLATE_VOLUME_PREFIX)
)
@staticmethod
def _mac_for_new_vm(conn: Any) -> str:
used = {
(node.get("address") or "").lower()
for domain in conn.listAllDomains(0)
for node in VMService._vm_xml(domain).findall("./devices/interface/mac")
}
for _ in range(32):
mac = "52:54:00:" + ":".join(f"{byte:02x}" for byte in secrets.token_bytes(3))
if mac not in used:
return mac
raise VMError("无法生成不重复的虚拟网卡 MAC", 503)
def _cloud_domain_xml(self, spec: dict[str, Any], vm_uuid: str,
disk_name: str, disk_source: tuple[str, dict[str, str]],
seed_name: str, seed_source: tuple[str, dict[str, str]],
mac: str, public_ip_cidr: str) -> str:
root = ET.fromstring(self._domain_xml(
spec, vm_uuid, disk_name, disk_source, ("file", {}),
install_phase=False))
interface = root.find("./devices/interface")
if interface is None:
raise VMError("无法生成虚拟网卡配置", 500)
interface.insert(0, ET.Element("mac", address=mac))
cdrom = root.find("./devices/disk[@device='cdrom']")
if cdrom is None:
raise VMError("无法生成 cloud-init 配置盘", 500)
cdrom.set("type", seed_source[0])
target = cdrom.find("target")
source = ET.Element("source", **seed_source[1])
if target is not None:
cdrom.insert(list(cdrom).index(target), source)
else:
cdrom.append(source)
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
if managed is None:
raise VMError("无法生成面板元数据", 500)
managed.set("seed-volume", seed_name)
managed.set("public-ip-cidr", public_ip_cidr)
public_pool_key = spec.get("public_pool_key")
if public_pool_key:
managed.set("public-pool-key", public_pool_key)
managed.set("os-source", "cloud_template")
if spec.get("os_name") is not None:
managed.set("os-name", spec["os_name"])
_store_platform_policy_in_domain_xml(
managed, spec.get("platform_network_policy_snapshot")
or default_platform_policy_snapshot())
if self.bridge_name is not None:
self._attach_public_filter(
interface, public_ip_cidr, firewall_filter_name(vm_uuid))
return ET.tostring(root, encoding="unicode")
def create_cloud_vm(self, spec: dict[str, Any], template_volume_name: str) -> dict[str, Any]:
"""Clone a trusted cloud image and supply static public networking."""
validated = self._validate_common_create(spec)
validated["created_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
validated["os_name"] = self._validated_os_name(spec.get("os_name"))
try:
validated["platform_network_policy_snapshot"] = (
normalize_platform_policy_snapshot(
spec.get("platform_network_policy_snapshot")
if "platform_network_policy_snapshot" in spec
else default_platform_policy_snapshot()
))
except ValueError as exc:
raise VMError(
"平台网络策略快照无效", 422,
error_code="firewall_rule_invalid",
) from exc
requested_uuid = spec.get("vm_uuid")
if requested_uuid is not None:
try:
requested_uuid = str(uuidlib.UUID(requested_uuid))
except (TypeError, ValueError, AttributeError) as exc:
raise VMError("虚拟机 UUID 无效") from exc
if self.bridge_name is None:
raise VMError("公网模板创建需要先在宿主机设置 Linux 网桥,例如 bridge:br0", 409)
if not TEMPLATE_VOLUME_RE.fullmatch(template_volume_name):
raise VMError("只能使用面板导入的云镜像模板")
try:
network = validate_cloud_network(
spec.get("public_ip_cidr"), spec.get("gateway"),
spec.get("dns_servers"), spec.get("guest_ssh_public_key", ""),
spec.get("root_password_hash"))
except ValueError as exc:
raise VMError(str(exc)) from exc
public_pool_key = spec.get("public_pool_key")
if (public_pool_key is not None
and public_pool_key != "legacy-default"
and (not isinstance(public_pool_key, str)
or not PUBLIC_POOL_KEY_RE.fullmatch(public_pool_key))):
raise VMError("公网地址池标识无效", 422)
# _validate_common_create intentionally returns a narrow, validated
# create spec. Carry the already-validated pool identity forward to
# the XML builder; dropping it here leaves the guest without
# public-pool-key metadata and makes PHP reject the successful create
# during its reservation reconciliation.
if isinstance(public_pool_key, str) and public_pool_key:
validated["public_pool_key"] = public_pool_key
with _CREATE_LOCK, self._connect() as conn:
self._require_clean_traffic_filter(conn)
domains = conn.listAllDomains(0)
uuid_resource_naming = requested_uuid is not None
vm_uuid = requested_uuid or str(uuidlib.uuid4())
if any(domain.UUIDString() == vm_uuid for domain in domains):
raise VMError("虚拟机 UUID 已存在", 409)
if (not uuid_resource_naming
and any(domain.name() == validated["name"] for domain in domains)):
raise VMError("虚拟机名称已存在", 409)
for domain in domains:
managed = self._vm_xml(domain).find(f"./metadata/{{{PANEL_NS}}}managed")
if managed is not None and managed.get("public-ip-cidr", "").split("/")[0] == \
network["public_ip_cidr"].split("/")[0]:
raise VMError("该公网 IP 已分配给面板中的另一台虚拟机", 409)
if conn.getInfo()[0] != "x86_64":
raise VMError("当前云镜像模板仅支持 x86_64 宿主机", 422)
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
if template_volume_name not in pool.listVolumes():
raise VMError("模板卷在宿主机上不存在,请重新导入", 404)
template = pool.storageVolLookupByName(template_volume_name)
template_xml = ET.fromstring(template.XMLDesc(0))
if template_xml.find("./target/format") is None or \
template_xml.find("./target/format").get("type") != "qcow2":
raise VMError("模板卷不是 qcow2 格式", 409)
template_capacity = int(template.info()[1])
target_capacity = validated["disk_gib"] * GIB
if target_capacity < template_capacity:
raise VMError("虚拟磁盘不能小于云镜像模板的原始容量", 409)
if target_capacity > pool.info()[3]:
raise VMError("存储池剩余空间不足", 409)
volume_names = set(pool.listVolumes())
resource_name = (
self._select_internal_resource_name(vm_uuid, domains, volume_names)
if uuid_resource_naming else validated["name"]
)
validated["resource_name"] = resource_name
disk_name = f"{resource_name}.qcow2"
seed_name = f"panel-seed-{vm_uuid}.iso"
if disk_name in volume_names or seed_name in volume_names:
raise VMError("同名虚拟磁盘或配置盘已存在,不会覆盖", 409)
mac = self._mac_for_new_vm(conn)
try:
seed_data = build_seed_iso(
vm_uuid, validated["name"], mac, network,
debian12_network_fix=self._cloud_seed_needs_debian12_network_fix(
template_volume_name),
)
except ImportError as exc:
raise VMError("面板缺少 pycdlib,需安装 requirements.txt 中的依赖", 503) from exc
created: list[tuple[Any, str]] = []
default_filter_xml = ""
default_filter_digest = ""
created_filter = False
try:
(default_filter_xml, default_filter_digest,
created_filter) = self._ensure_default_firewall_filter(
conn, vm_uuid,
validated["platform_network_policy_snapshot"])
disk = pool.createXMLFrom(self._volume_xml_bytes(
disk_name, template_capacity, "qcow2"), template, 0)
if disk is None:
raise VMError("宿主机未能克隆云镜像模板", 502)
created.append((disk, disk_name))
if target_capacity > template_capacity:
disk.resize(target_capacity, 0)
seed = pool.createXML(self._volume_xml_bytes(
seed_name, len(seed_data), "raw"), 0)
if seed is None:
raise VMError("宿主机未能创建 cloud-init 配置盘", 502)
created.append((seed, seed_name))
self._upload_volume(conn, seed, iter((seed_data,)), len(seed_data))
disk_source = self._volume_source(pool, disk)
seed_source = self._volume_source(pool, seed)
domain_xml = self._cloud_domain_xml(
validated, vm_uuid, disk_name, disk_source,
seed_name, seed_source, mac, network["public_ip_cidr"])
domain = conn.defineXML(domain_xml)
if domain is None:
raise VMError("宿主机未能定义云镜像虚拟机", 502)
_verify_platform_policy_in_domain(
domain, validated["platform_network_policy_snapshot"],
require_explicit=True,
)
self._enable_vm_autostart(domain)
domain.create()
evidence = self._firewall_observation(
conn, domain, default_filter_xml)
expected_platform_policy = (
validated["platform_network_policy_snapshot"])
if (not evidence["matches"]
or evidence["platform_policy_snapshot"]
!= expected_platform_policy
or not hmac.compare_digest(
evidence["platform_policy_digest"],
expected_platform_policy["digest"],
)):
raise VMError(
"实例已启动但平台默认网络策略校验失败", 502,
error_code="firewall_result_uncertain",
)
return self._vm_dict(domain)
except Exception as exc:
clean = True
for volume, volume_name in reversed(created):
if not self._rollback_new_vm(conn, vm_uuid, resource_name,
pool, volume, volume_name):
clean = False
break
if (clean and created_filter
and not self._remove_created_firewall_filter(
conn, vm_uuid, default_filter_digest)):
clean = False
if not clean:
raise VMError(
"云虚拟机创建失败且回滚不完整;已保留相关资源,请检查内部资源 "
f"{resource_name}(显示名 {validated['name']})",
502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("Could not create cloud VM %s: %s", validated["name"], exc)
raise VMError("无法创建云镜像虚拟机,请检查网桥、磁盘权限和宿主机日志", 502) from exc
def reinstall_cloud_vm(
self,
vm_id: str,
template_volume_name: str,
*,
os_name: str | None = None,
ssh_public_key: str = "",
root_password_hash: str | None = None,
progress: Callable[[str], None] | None = None,
) -> dict[str, Any]:
"""Replace one panel cloud VM's disk after a graceful shutdown.
The old disk remains untouched until the replacement domain has
started. Failure before that point restores the old definition and
retains the old disk. A cleanup failure after start is a committed,
uncertain result: some old volumes may already have been removed, so
the replacement credential is returned while callers are instructed
to reconcile cleanup instead of reporting success.
"""
if not TEMPLATE_VOLUME_RE.fullmatch(template_volume_name):
raise VMError("只能使用面板导入的云镜像模板")
os_name = self._validated_os_name(os_name)
if self.bridge_name is None:
raise VMError("公网模板重装需要原 Linux 网桥配置", 409)
def phase(value: str) -> None:
if progress is not None:
try:
progress(value)
except Exception:
# Progress persistence is advisory. A failed callback
# must not convert a replacement that already started
# into a pre-commit reinstall failure.
LOG.exception("Could not persist reinstall phase %s for VM %s",
value, vm_id)
with _CREATE_LOCK, self._connect() as conn:
domain = self._domain(conn, vm_id)
if not domain.isPersistent():
raise VMError("只能重装持久化虚拟机", 409)
if getattr(domain, "hasManagedSaveImage", lambda _flags: 0)(0):
raise VMError("虚拟机存在托管保存状态,请先处理后再重装", 409)
if domain.snapshotNum(0) > 0:
raise VMError("虚拟机存在快照,请先处理后再重装", 409)
original_root = self._vm_xml(domain)
preflight_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
platform_policy, platform_policy_was_explicit = (
_platform_policy_state_from_domain_xml(preflight_root))
_require_same_platform_policy_state(
original_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="虚拟机实时与持久平台网络策略不一致,已停止重装",
)
managed = original_root.find(f"./metadata/{{{PANEL_NS}}}managed")
if (managed is None or managed.get("version") != "2"
or not managed.get("seed-volume")
or not managed.get("public-ip-cidr")):
raise VMError("只有面板创建的公网云镜像虚拟机可以自动重装", 409)
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:
raise VMError("虚拟机磁盘或网卡配置已变化,不能安全自动重装", 409)
interface = interfaces[0]
source = interface.find("source")
mac_node = interface.find("mac")
if (interface.get("type") != "bridge" or source is None
or source.get("bridge") != self.bridge_name
or mac_node is None or not mac_node.get("address")):
raise VMError("虚拟机网桥或 MAC 已变化,不能自动沿用原网络", 409)
mac = mac_node.get("address").lower()
old_disk = self._owned_volume(conn, domain)
old_seed = self._owned_seed_volume(conn, domain)
if old_seed is None:
raise VMError("找不到原 cloud-init 配置盘", 409)
try:
original_network = read_seed_network(self._download_seed_volume(conn, old_seed))
network = validate_cloud_network(
original_network["public_ip_cidr"], original_network["gateway"],
original_network["dns_servers"], ssh_public_key, root_password_hash,
)
except (ImportError, ValueError) as exc:
raise VMError("无法校验原 cloud-init 网络配置,已停止重装", 409) from exc
if (original_network["mac"] != mac
or network["public_ip_cidr"] != managed.get("public-ip-cidr")):
raise VMError("原配置盘的公网 IP 或 MAC 与虚拟机不一致,已停止重装", 409)
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
if template_volume_name not in pool.listVolumes():
raise VMError("模板卷在宿主机上不存在,请重新导入", 404)
template = pool.storageVolLookupByName(template_volume_name)
template_format = ET.fromstring(template.XMLDesc(0)).find("./target/format")
if template_format is None or template_format.get("type") != "qcow2":
raise VMError("模板卷不是 qcow2 格式", 409)
target_capacity = int(old_disk.info()[1])
template_capacity = int(template.info()[1])
if template_capacity > target_capacity:
raise VMError("所选模板容量超过原系统盘,无法保留原磁盘大小", 409)
if target_capacity > pool.info()[3]:
raise VMError("存储池空间不足,无法创建新系统盘", 409)
phase("shutting_down")
if domain.isActive():
domain.shutdown()
deadline = time.monotonic() + REINSTALL_SHUTDOWN_TIMEOUT
while domain.isActive():
if time.monotonic() >= deadline:
raise VMError("正常关机超时,重装已停止;旧系统盘未改变", 409)
time.sleep(REINSTALL_SHUTDOWN_POLL_INTERVAL)
# Inspect the now-inactive definition again, so a concurrent
# external edit cannot quietly alter the storage or network.
old_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
inactive_root = ET.fromstring(old_xml)
inactive_managed = inactive_root.find(f"./metadata/{{{PANEL_NS}}}managed")
_require_same_platform_policy_state(
inactive_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,重装已停止",
)
inactive_interface = inactive_root.find("./devices/interface")
inactive_mac = (inactive_interface.find("mac") if inactive_interface is not None
else None)
inactive_source = (inactive_interface.find("source")
if inactive_interface is not None else None)
if (inactive_managed is None
or inactive_managed.get("disk-volume") != old_disk.name()
or inactive_managed.get("seed-volume") != old_seed.name()
or inactive_managed.get("public-ip-cidr") != network["public_ip_cidr"]
or inactive_mac is None or (inactive_mac.get("address") or "").lower() != mac
or inactive_source is None
or inactive_source.get("bridge") != self.bridge_name):
raise VMError("关机后虚拟机配置已变化,重装已停止", 409)
display_name = self._display_name(domain, inactive_managed)
if self._owned_volume(conn, domain).name() != old_disk.name() or \
self._owned_seed_volume(conn, domain).name() != old_seed.name():
raise VMError("关机后存储卷已变化,重装已停止", 409)
disk_name = f"panel-r-{uuidlib.uuid4().hex}.qcow2"
seed_uuid = str(uuidlib.uuid4())
seed_name = f"panel-seed-{seed_uuid}.iso"
if disk_name in pool.listVolumes() or seed_name in pool.listVolumes():
raise VMError("新系统盘或配置盘名称冲突,已停止重装", 409)
try:
seed_data = build_seed_iso(
seed_uuid, display_name, mac, network,
debian12_network_fix=self._cloud_seed_needs_debian12_network_fix(
template_volume_name),
)
except ImportError as exc:
raise VMError("面板缺少 pycdlib,需安装 requirements.txt 中的依赖", 503) from exc
created: list[Any] = []
switched = False
phase("cloning")
try:
disk = pool.createXMLFrom(self._volume_xml_bytes(
disk_name, template_capacity, "qcow2"), template, 0)
if disk is None:
raise VMError("宿主机未能克隆新系统盘", 502)
created.append(disk)
if target_capacity > template_capacity:
disk.resize(target_capacity, 0)
seed = pool.createXML(self._volume_xml_bytes(
seed_name, len(seed_data), "raw"), 0)
if seed is None:
raise VMError("宿主机未能创建新配置盘", 502)
created.append(seed)
self._upload_volume(conn, seed, iter((seed_data,)), len(seed_data))
new_root = ET.fromstring(old_xml)
for device, volume in (("disk", disk), ("cdrom", seed)):
node = new_root.find(f"./devices/disk[@device='{device}']")
if node is None:
raise VMError("虚拟机磁盘配置已变化,无法切换", 409)
source_type, source_attrs = self._volume_source(pool, volume)
node.set("type", source_type)
old_source = node.find("source")
if old_source is None:
raise VMError("虚拟机磁盘来源已变化,无法切换", 409)
source_index = list(node).index(old_source)
node.remove(old_source)
node.insert(source_index, ET.Element("source", **source_attrs))
new_managed = new_root.find(f"./metadata/{{{PANEL_NS}}}managed")
if new_managed is None:
raise VMError("虚拟机面板元数据已变化,无法切换", 409)
new_managed.set("disk-volume", disk_name)
new_managed.set("seed-volume", seed_name)
# A different reinstall template invalidates the old label.
new_managed.attrib.pop("os-source", None)
new_managed.attrib.pop("os-name", None)
new_managed.attrib.pop("install-iso", None)
new_managed.set("os-source", "cloud_template")
if os_name is not None:
new_managed.set("os-name", os_name)
phase("starting")
new_domain = conn.defineXML(ET.tostring(new_root, encoding="unicode"))
if new_domain is None:
raise VMError("宿主机未能切换虚拟机定义", 502)
switched = True
_verify_platform_policy_in_domain(
new_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
new_domain.create()
except Exception as exc:
if switched:
try:
if new_domain.isActive():
live_managed = self._vm_xml(new_domain).find(
f"./metadata/{{{PANEL_NS}}}managed")
if live_managed is not None and \
live_managed.get("disk-volume") == disk_name:
# A transport error can occur after QEMU has
# actually started. Keep both generations and
# report the new credential instead of
# restoring only the inactive definition.
LOG.error("VM %s may have started on replacement disk after error",
vm_id, exc_info=True)
phase("result_uncertain")
return {
"vm": {"uuid": vm_id,
"name": display_name,
"state": "running"},
"credential_generation": seed_name,
"status": "uncertain",
"error_code": REINSTALL_RESULT_UNCERTAIN_ERROR_CODE,
"error": "重装结果待核对;新系统可能已启动,旧系统盘已保留",
"reinstall_committed": True,
"cleanup_pending": True,
"warning": "新系统可能已启动,但启动返回错误;旧系统盘已保留,"
"请检查虚拟机状态和存储卷后手工清理",
}
except Exception:
LOG.exception("Could not inspect VM %s after start error", vm_id)
restored = True
if switched:
try:
restored_domain = conn.defineXML(old_xml)
if restored_domain is None:
raise VMError("宿主机未能恢复原虚拟机定义", 502)
if platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
except Exception:
LOG.exception("Could not restore original definition for %s", vm_id)
restored = False
if restored:
for volume in reversed(created):
try:
if self._other_domain_uses_volume(
conn, "", pool.name(), volume.name(), volume.path()):
restored = False
continue
volume.delete(0)
except Exception:
LOG.exception("Could not remove replacement volume %s", volume.name())
restored = False
if not restored:
raise VMError(
"重装失败且自动回滚不完整;旧系统盘已保留,请检查虚拟机与新建存储卷",
502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("Could not reinstall VM %s: %s", vm_id, exc)
raise VMError("重装失败,已恢复原虚拟机定义及旧系统盘", 502) from exc
# QEMU started with the new disk. This does not prove the guest
# booted or has working SSH; the operator explicitly selected
# automatic removal of the old disk after this point.
phase("cleaning_up")
warnings = []
cleanup_pending = False
for volume in (old_seed, old_disk):
try:
if self._other_domain_uses_volume(
conn, "", pool.name(), volume.name(), volume.path()):
cleanup_pending = True
warnings.append(f"旧存储卷 {volume.name()} 仍被引用,未删除")
continue
volume.delete(0)
except Exception:
LOG.exception("Reinstalled VM %s, but old volume %s remains", vm_id,
volume.name())
cleanup_pending = True
warnings.append(f"旧存储卷 {volume.name()} 删除失败,请检查宿主机")
try:
vm_state = self._vm_dict(new_domain)
except Exception:
LOG.exception("VM %s started after reinstall, but its details could not be read", vm_id)
vm_state = {"uuid": vm_id, "name": display_name,
"state": "running"}
warnings.append("新系统已启动,但面板未能读取完整虚拟机状态,请检查宿主机")
result: dict[str, Any] = {"vm": vm_state, "credential_generation": seed_name}
if warnings:
result.update({
"status": "uncertain",
"error_code": (
REINSTALL_CLEANUP_PENDING_ERROR_CODE
if cleanup_pending else REINSTALL_RESULT_UNCERTAIN_ERROR_CODE
),
"error": (
"重装已完成,但旧系统盘清理待核对"
if cleanup_pending else "重装结果待核对"
),
"reinstall_committed": True,
"warning": ";".join(warnings),
})
if cleanup_pending:
result["cleanup_pending"] = True
phase("cleanup_pending" if cleanup_pending else "result_uncertain")
return result
phase("completed")
return result
def change_cloud_vm_network(
self,
vm_id: str,
network: dict[str, Any],
*,
confirm_restart: bool = False,
progress: Callable[[str], None] | None = None,
) -> dict[str, Any]:
"""Replace a managed cloud VM's public IPv4 configuration.
The operation rewrites the network-config file in the existing NoCloud
seed, preserves guest credentials/hostname, and makes sure cloud-init
consumes the replacement (legacy seeds get one generation rotation).
A running guest is gracefully stopped and started again;
a stopped guest remains stopped. Any transport error after QEMU has
started is surfaced as a 502 so the durable internal operation becomes
``uncertain`` instead of guessing whether the guest applied the IP.
"""
if confirm_restart is not True:
raise VMError("更换公网 IP 前必须确认会短暂重启虚拟机", 422)
if self.bridge_name is None:
raise VMError("公网云镜像更换 IP 需要原 Linux 网桥配置", 409)
if not isinstance(network, dict):
raise VMError("网络配置无效", 422)
try:
validated = validate_cloud_network(
network.get("public_ip_cidr"), network.get("gateway"),
network.get("dns_servers"), require_auth=False,
)
except (TypeError, ValueError) as exc:
raise VMError(str(exc), 422) from exc
public_pool_key = network.get("public_pool_key")
if (not isinstance(public_pool_key, str)
or not PUBLIC_POOL_KEY_RE.fullmatch(public_pool_key)):
raise VMError("公网地址池标识无效", 422)
source_public_pool_key = network.get("source_public_pool_key")
if (not isinstance(source_public_pool_key, str)
or (source_public_pool_key != "legacy-default"
and not PUBLIC_POOL_KEY_RE.fullmatch(
source_public_pool_key))):
raise VMError("原公网地址池标识无效", 422)
def phase(value: str) -> None:
if progress is not None:
progress(value)
with _CREATE_LOCK, self._connect() as conn:
self._require_clean_traffic_filter(conn)
domain = self._domain(conn, vm_id)
if not domain.isPersistent():
raise VMError("只能修改持久化虚拟机", 409)
if getattr(domain, "hasManagedSaveImage", lambda _flags: 0)(0):
raise VMError("虚拟机存在托管保存状态,请先处理后再修改网络", 409)
if domain.snapshotNum(0) > 0:
raise VMError("虚拟机存在快照,请先处理后再修改网络", 409)
original_root = self._vm_xml(domain)
preflight_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
platform_policy, platform_policy_was_explicit = (
_platform_policy_state_from_domain_xml(preflight_root))
_require_same_platform_policy_state(
original_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="虚拟机实时与持久平台网络策略不一致,已停止网络修改",
)
managed = original_root.find(f"./metadata/{{{PANEL_NS}}}managed")
if (managed is None or managed.get("version") != "2"
or managed.get("os-source") != "cloud_template"
or not managed.get("seed-volume")
or not managed.get("public-ip-cidr")):
raise VMError("只有面板创建的公网云镜像虚拟机支持更换 IP", 409)
old_pool_key = managed.get("public-pool-key")
if (old_pool_key not in (None, "", "legacy-default")
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]
source = interface.find("source")
mac_node = interface.find("mac")
if (interface.get("type") != "bridge" or source is None
or source.get("bridge") != self.bridge_name
or mac_node is None or not mac_node.get("address")):
raise VMError("虚拟机网桥或 MAC 已变化,不能自动修改网络", 409)
mac = mac_node.get("address").lower()
old_ip = managed.get("public-ip-cidr")
if validated["public_ip_cidr"] == old_ip:
return {
"vm": self._vm_dict(domain),
"public_pool_key": public_pool_key,
"public_ip_cidr": old_ip,
"gateway": validated["gateway"],
"dns_servers": list(validated["dns_servers"]),
"network_changed": False,
"was_running": bool(domain.isActive()),
}
old_seed = self._owned_seed_volume(conn, domain)
if old_seed is None:
raise VMError("找不到原 cloud-init 配置盘,已停止网络修改", 409)
original_seed = self._download_seed_volume(conn, old_seed)
try:
original_network = read_seed_network(original_seed)
except (ImportError, ValueError) as exc:
raise VMError("原 cloud-init 配置盘不是面板生成格式,已停止网络修改", 409) from exc
if (original_network["mac"] != mac
or original_network["public_ip_cidr"] != old_ip):
raise VMError("原配置盘的公网 IP 或 MAC 与虚拟机不一致,已停止网络修改", 409)
try:
original_validated = validate_cloud_network(
original_network["public_ip_cidr"],
original_network["gateway"],
original_network["dns_servers"],
require_auth=False,
)
except (TypeError, ValueError) as exc:
raise VMError("原 cloud-init 网关或 DNS 配置无效,已停止网络修改", 409) from exc
# A same-pool request may not silently drift gateway or DNS. A
# cross-CIDR request is allowed only after the API has proven both
# pools use the same network selector, and therefore deliberately
# applies the target pool's complete network tuple.
if (source_public_pool_key == public_pool_key
and (original_validated["gateway"] != validated["gateway"]
or original_validated["dns_servers"]
!= validated["dns_servers"])):
raise VMError(
"宿主机网关或 DNS 已变化,请先同步实例网络配置后再更换 IP", 409,
)
try:
replacement_seed = replace_seed_network(
original_seed, validated["public_ip_cidr"],
validated["gateway"], validated["dns_servers"],
)
except ImportError as exc:
raise VMError("面板缺少 pycdlib,无法修改 cloud-init 配置盘", 503) from exc
except ValueError as exc:
raise VMError("原 cloud-init 网络配置格式无效,已停止网络修改", 409) from exc
phase("shutting_down")
was_running = bool(domain.isActive())
if was_running:
try:
domain.shutdown()
except libvirt.libvirtError as exc:
raise VMError("虚拟机正常关机失败,网络未修改", 409) from exc
deadline = time.monotonic() + NETWORK_CHANGE_SHUTDOWN_TIMEOUT
while domain.isActive():
if time.monotonic() >= deadline:
raise VMError("正常关机超时,网络未修改", 409)
time.sleep(NETWORK_CHANGE_SHUTDOWN_POLL_INTERVAL)
# Re-read inactive XML after shutdown. This protects the seed and
# filter update from a concurrent operator edit.
old_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
inactive_root = ET.fromstring(old_xml)
inactive_managed = inactive_root.find(f"./metadata/{{{PANEL_NS}}}managed")
_require_same_platform_policy_state(
inactive_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,网络修改已停止",
)
inactive_interface = inactive_root.find("./devices/interface")
inactive_mac = (inactive_interface.find("mac")
if inactive_interface is not None else None)
inactive_source = (inactive_interface.find("source")
if inactive_interface is not None else None)
if (inactive_managed is None
or inactive_managed.get("seed-volume") != old_seed.name()
or inactive_managed.get("public-ip-cidr") != old_ip
or inactive_managed.get("public-pool-key") != old_pool_key
or inactive_interface is None
or inactive_mac is None
or (inactive_mac.get("address") or "").lower() != mac
or inactive_interface.get("type") != "bridge"
or inactive_source is None
or inactive_source.get("bridge") != self.bridge_name):
raise VMError("关机后虚拟机配置已变化,网络修改已停止", 409)
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:
raise VMError("虚拟机配置已变化,网络修改已停止", 409)
new_managed.set("public-ip-cidr", validated["public_ip_cidr"])
new_managed.set("public-pool-key", public_pool_key)
self._update_public_filter_ip(
new_interface, validated["public_ip_cidr"], vm_id)
switched = False
try:
phase("updating_network")
# The volume is raw and already bounded at one MiB. Grow it
# only when the replacement image is larger; shrinking raw
# volumes is not portable and is unnecessary for NoCloud.
current_capacity = int(old_seed.info()[1])
if len(replacement_seed) > current_capacity:
old_seed.resize(len(replacement_seed), 0)
self._upload_volume(
conn, old_seed, iter((replacement_seed,)),
len(replacement_seed),
)
new_domain = conn.defineXML(ET.tostring(new_root, encoding="unicode"))
if new_domain is None:
raise VMError("宿主机未能保存新的虚拟机网络配置", 502)
switched = True
_verify_platform_policy_in_domain(
new_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
if was_running:
phase("starting")
try:
new_domain.create()
except libvirt.libvirtError as exc:
if new_domain.isActive():
# The request may have reached QEMU despite a lost
# response. Keep the new definition and let the
# internal operation become uncertain.
raise VMError(
"虚拟机已发送启动指令但结果不确定,请查询任务状态", 502,
) from exc
raise
except Exception as exc:
if switched and was_running and domain.isActive():
raise VMError(
"网络修改结果不确定,请查询任务状态;未释放原公网 IP", 502,
) from exc
restored = True
try:
self._upload_volume(conn, old_seed, iter((original_seed,)),
len(original_seed))
except Exception:
LOG.exception("Could not restore original seed for %s", vm_id)
restored = False
if switched:
try:
restored_domain = conn.defineXML(old_xml)
if restored_domain is None:
restored = False
elif platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
except Exception:
LOG.exception("Could not restore original VM XML for %s", vm_id)
restored = False
if not restored:
raise VMError(
"网络修改失败且自动回滚不完整;原配置仍保留,请检查虚拟机", 502,
) from exc
if isinstance(exc, VMError):
raise
raise VMError("网络修改失败,已恢复原配置", 502) from exc
phase("completed")
result = self._vm_dict(new_domain)
return {
"vm": result,
"public_pool_key": public_pool_key,
"public_ip_cidr": validated["public_ip_cidr"],
"gateway": validated["gateway"],
"dns_servers": list(validated["dns_servers"]),
"network_changed": True,
"was_running": was_running,
}
def change_cloud_vm_settings(
self,
vm_id: str,
*,
hostname: str | None = None,
root_password_hash: str | None = None,
ssh_public_key: str | None = None,
confirm_restart: bool = False,
progress: Callable[[str], None] | None = None,
) -> dict[str, Any]:
"""Update a panel cloud guest's hostname or root authentication.
The guest settings are carried by the existing NoCloud seed. The
operation writes a replacement seed only after validating the managed
VM and then defines the updated metadata before restarting a running
guest. Any deterministic failure restores the original seed and XML;
a transport error after QEMU has started is reported as uncertain and
intentionally keeps the new generation for reconciliation.
The method accepts a *hashed* root password. Plaintext credentials
must be converted by the authenticated API boundary and are never
logged, returned, or persisted by this service.
"""
if hostname is None and root_password_hash is None and ssh_public_key is None:
raise VMError("至少需要修改一项虚拟机设置", 422)
if confirm_restart is not True:
raise VMError("修改实例设置前必须确认会短暂重启虚拟机", 422)
if hostname is not None:
try:
hostname = validate_guest_hostname(hostname)
except ValueError as exc:
raise VMError(str(exc), 422) from exc
if root_password_hash is not None:
try:
_validate_guest_auth("", root_password_hash)
except ValueError as exc:
raise VMError("root 密码哈希格式无效", 422) from exc
if ssh_public_key is not None:
try:
ssh_public_key = _validate_ssh_public_key(ssh_public_key)
except ValueError as exc:
raise VMError(str(exc), 422) from exc
def phase(value: str) -> None:
if progress is not None:
progress(value)
with _CREATE_LOCK, self._connect() as conn:
domain = self._domain(conn, vm_id)
if not domain.isPersistent():
raise VMError("只能修改持久化虚拟机", 409)
if getattr(domain, "hasManagedSaveImage", lambda _flags: 0)(0):
raise VMError("虚拟机存在托管保存状态,请先处理后再修改设置", 409)
if domain.snapshotNum(0) > 0:
raise VMError("虚拟机存在快照,请先处理后再修改设置", 409)
was_running = bool(domain.isActive())
original_root = self._vm_xml(domain)
preflight_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
platform_policy, platform_policy_was_explicit = (
_platform_policy_state_from_domain_xml(preflight_root))
_require_same_platform_policy_state(
original_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="虚拟机实时与持久平台网络策略不一致,已停止修改设置",
)
managed = original_root.find(f"./metadata/{{{PANEL_NS}}}managed")
if (managed is None or managed.get("version") != "2"
or managed.get("os-source") != "cloud_template"
or not managed.get("seed-volume")
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]
mac_node = interface.find("mac")
if mac_node is None or not mac_node.get("address"):
raise VMError("虚拟机 MAC 配置已变化,已停止修改设置", 409)
mac = mac_node.get("address").lower()
old_seed = self._owned_seed_volume(conn, domain)
if old_seed is None:
raise VMError("找不到原 cloud-init 配置盘,已停止修改设置", 409)
original_seed = self._download_seed_volume(conn, old_seed)
try:
original_network = read_seed_network(original_seed)
except (ImportError, ValueError) as exc:
raise VMError("原 cloud-init 配置盘不是面板生成格式,已停止修改设置", 409) from exc
if (original_network["mac"] != mac
or original_network["public_ip_cidr"] != managed.get("public-ip-cidr")):
raise VMError("原配置盘的公网 IP 或 MAC 与虚拟机不一致,已停止修改设置", 409)
try:
replacement_seed = replace_seed_settings(
original_seed,
hostname=hostname,
root_password_hash=root_password_hash,
ssh_public_key=ssh_public_key,
)
except ImportError as exc:
raise VMError("面板缺少 pycdlib,无法修改 cloud-init 配置盘", 503) from exc
except ValueError as exc:
raise VMError("原 cloud-init 配置格式无效,已停止修改设置", 409) from exc
# Everything after a successful shutdown is inside one rollback
# boundary. A validation, upload or define failure must restore
# the original running state; otherwise a failed settings update
# would unexpectedly leave a previously running guest powered off.
old_xml = original_root
new_domain = domain
restored_domain = domain
switched = False
seed_touched = False
start_attempted = False
try:
if was_running:
phase("shutting_down")
try:
domain.shutdown()
except libvirt.libvirtError as exc:
try:
still_active = bool(domain.isActive())
except Exception as state_error:
raise VMError(
"虚拟机关机结果不确定,请查询实例状态;设置未修改", 502,
) from state_error
if still_active:
raise VMError("虚拟机正常关机失败,设置未修改", 409) from exc
raise VMError(
"虚拟机已关机但结果不确定,请查询实例状态;设置未修改", 502,
) from exc
deadline = time.monotonic() + NETWORK_CHANGE_SHUTDOWN_TIMEOUT
while domain.isActive():
if time.monotonic() >= deadline:
raise VMError("正常关机超时,设置未修改", 409)
time.sleep(NETWORK_CHANGE_SHUTDOWN_POLL_INTERVAL)
# Re-read the inactive definition after shutdown. This
# protects the seed attachment from a concurrent operator edit.
old_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
inactive_root = ET.fromstring(old_xml)
inactive_managed = inactive_root.find(f"./metadata/{{{PANEL_NS}}}managed")
_require_same_platform_policy_state(
inactive_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,设置修改已停止",
)
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")):
raise VMError("关机后虚拟机配置已变化,设置修改已停止", 409)
new_root = ET.fromstring(old_xml)
new_managed = new_root.find(f"./metadata/{{{PANEL_NS}}}managed")
if new_managed is None:
raise VMError("虚拟机面板元数据已变化,设置修改已停止", 409)
if hostname is not None:
new_managed.set("guest-hostname", hostname)
phase("updating_settings")
current_capacity = int(old_seed.info()[1])
# Mark the volume before resize/upload. A short write must be
# restored as well; otherwise a partial seed can be booted.
seed_touched = True
if len(replacement_seed) > current_capacity:
old_seed.resize(len(replacement_seed), 0)
self._upload_volume(
conn, old_seed, iter((replacement_seed,)),
len(replacement_seed),
)
if hostname is not None:
new_domain = conn.defineXML(ET.tostring(new_root, encoding="unicode"))
if new_domain is None:
raise VMError("宿主机未能保存新的虚拟机主机名", 502)
switched = True
if platform_policy is not None:
_verify_platform_policy_in_domain(
new_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
if was_running:
phase("starting")
start_attempted = True
try:
new_domain.create()
except libvirt.libvirtError as exc:
try:
active_after_start_error = bool(new_domain.isActive())
except Exception as state_error:
raise VMError(
"虚拟机启动结果不确定,请查询实例状态;新配置已保留", 502,
) from state_error
if active_after_start_error:
# QEMU may have accepted the request despite a
# lost response. Keep the new generation for
# reconciliation instead of overwriting a live VM.
raise VMError(
"虚拟机已发送启动指令但结果不确定,请查询实例状态", 502,
) from exc
raise
except Exception as exc:
if start_attempted:
try:
active_after_failure = bool(new_domain.isActive())
except Exception as state_error:
raise VMError(
"实例设置修改结果不确定,请查询实例状态;新配置已保留", 502,
) from state_error
if active_after_failure:
raise VMError(
"实例设置修改结果不确定,请查询实例状态;新配置已保留", 502,
) from exc
restored = True
if seed_touched:
try:
self._upload_volume(conn, old_seed, iter((original_seed,)),
len(original_seed))
except Exception:
LOG.exception("Could not restore original settings seed for %s", vm_id)
restored = False
if switched:
try:
restored_domain = conn.defineXML(old_xml)
if restored_domain is None:
restored = False
elif platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
except Exception:
LOG.exception("Could not restore original VM XML for %s", vm_id)
restored = False
if restored and was_running:
try:
if not restored_domain.isActive():
restored_domain.create()
if not restored_domain.isActive():
restored = False
except Exception:
LOG.exception("Could not restart original VM after settings rollback: %s", vm_id)
restored = False
if not restored:
raise VMError(
"实例设置修改失败且自动回滚不完整;请检查虚拟机配置", 502,
) from exc
if isinstance(exc, VMError):
raise
LOG.warning("Could not update VM settings %s: %s", vm_id, exc)
raise VMError("实例设置修改失败,已恢复原配置", 502) from exc
phase("completed")
result = self._vm_dict(new_domain)
result_hostname = (
hostname if hostname is not None
else (managed.get("guest-hostname") if managed is not None else None)
)
response: dict[str, Any] = {
"vm": result,
"settings_changed": True,
"was_running": was_running,
}
if result_hostname is not None:
response["hostname"] = result_hostname
return response
@staticmethod
def _requested_create_uuid(spec: dict[str, Any]) -> str | None:
requested_uuid = spec.get("vm_uuid")
if requested_uuid is not None:
try:
requested_uuid = str(uuidlib.UUID(requested_uuid))
except (TypeError, ValueError, AttributeError) as exc:
raise VMError("虚拟机 UUID 无效") from exc
return requested_uuid
def _create_iso_vm(self, conn: Any, validated: dict[str, Any],
requested_uuid: str | None, iso_pool: Any,
iso_volume: Any) -> dict[str, Any]:
domains = conn.listAllDomains(0)
uuid_resource_naming = requested_uuid is not None
vm_uuid = requested_uuid or str(uuidlib.uuid4())
if any(domain.UUIDString() == vm_uuid for domain in domains):
raise VMError("虚拟机 UUID 已存在", 409)
if (not uuid_resource_naming
and any(domain.name() == validated["name"] for domain in domains)):
raise VMError("虚拟机名称已存在", 409)
if conn.getInfo()[0] != "x86_64":
raise VMError("当前创建模板只支持 x86_64 宿主机", 422)
disk_pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(disk_pool)
if validated["disk_gib"] * GIB > disk_pool.info()[3]:
raise VMError("存储池剩余空间不足", 409)
if self.bridge_name is None:
network = conn.networkLookupByName(self.network)
if not network.isActive():
raise VMError("配置的虚拟网络未启动", 409)
volume_names = set(disk_pool.listVolumes())
resource_name = (
self._select_internal_resource_name(vm_uuid, domains, volume_names)
if uuid_resource_naming else validated["name"]
)
validated["resource_name"] = resource_name
disk_name = f"{resource_name}.qcow2"
if disk_name in volume_names:
raise VMError(f"磁盘文件 {disk_name} 已存在,不会覆盖现有数据", 409)
iso_source = self._volume_source(iso_pool, iso_volume)
volume = disk_pool.createXML(self._volume_xml(disk_name, validated["disk_gib"]), 0)
try:
disk_source = self._volume_source(disk_pool, volume)
install_xml = self._domain_xml(
validated, vm_uuid, disk_name, disk_source, iso_source,
install_phase=True)
final_xml = self._domain_xml(
validated, vm_uuid, disk_name, disk_source, iso_source,
install_phase=False)
try:
install_domain = conn.createXML(install_xml, 0)
except libvirt.libvirtError as exc:
LOG.warning("Could not start installation VM %s: %s", validated["name"], exc)
bridge_hint = f"网桥 {self.bridge_name}、" if self.bridge_name else ""
raise VMError(
f"无法启动安装期虚拟机;请检查 {bridge_hint}Q35/UEFI 固件、"
"磁盘和 ISO 访问权限,并查看宿主机 libvirt 日志", 409,
) from exc
if install_domain is None:
raise VMError("宿主机未能启动安装期虚拟机", 502)
# Like virt-install, keep the live installation XML separate from
# the persistent definition used after the first stop.
try:
domain = conn.defineXML(final_xml)
except libvirt.libvirtError as exc:
LOG.warning("Could not persist final VM %s: %s", validated["name"], exc)
raise VMError("安装期虚拟机已启动,但无法保存卸载 ISO 后的配置", 502) from exc
if domain is None:
raise VMError("宿主机未能保存卸载 ISO 后的虚拟机配置", 502)
self._enable_vm_autostart(domain)
return self._vm_dict(domain)
except Exception as exc:
if not self._rollback_new_vm(conn, vm_uuid, resource_name,
disk_pool, volume, disk_name):
raise VMError(
"创建失败且自动回滚不完整;为避免误删运行中磁盘,请检查宿主机中的"
f"内部资源 {resource_name}(显示名 {validated['name']})和磁盘 {disk_name}", 502,
) from exc
raise
def create_vm(self, spec: dict[str, Any]) -> dict[str, Any]:
"""Compatibility path for administrator-managed root-pool ISO names."""
validated = self._validate_create(spec)
validated["created_at"] = datetime.now(timezone.utc).isoformat(
timespec="seconds").replace("+00:00", "Z")
requested_uuid = self._requested_create_uuid(spec)
with _CREATE_LOCK, self._connect() as conn:
iso_pool = self._active_pool(conn, self.iso_pool)
self._refresh_directory_pool(iso_pool)
if validated["iso"] not in iso_pool.listVolumes():
raise VMError("安装镜像不在配置的 ISO 存储池中", 404)
iso_volume = iso_pool.storageVolLookupByName(validated["iso"])
return self._create_iso_vm(
conn, validated, requested_uuid, iso_pool, iso_volume)
def create_user_iso_vm(self, spec: dict[str, Any], user_id: int,
volume_name: str, iso_id: str,
display_name: str) -> dict[str, Any]:
"""Create from a catalog-resolved ISO in the authenticated owner pool."""
user_id = self._user_id(user_id)
self._check_user_iso_volume_name(volume_name)
if (not isinstance(iso_id, str) or not USER_ISO_ID_RE.fullmatch(iso_id)
or volume_name != f"panel-user-iso-{iso_id}.iso"):
raise VMError("用户 ISO 标识与存储卷不匹配", 409)
if (not isinstance(display_name, str) or not 1 <= len(display_name) <= 64
or display_name != display_name.strip()
or any(ord(char) < 32 or ord(char) == 127 for char in display_name)):
raise VMError("用户 ISO 名称无效", 409)
validated = self._validate_common_create(spec)
validated.update(
iso=display_name,
user_iso_id=iso_id,
created_at=datetime.now(timezone.utc).isoformat(
timespec="seconds").replace("+00:00", "Z"),
)
requested_uuid = self._requested_create_uuid(spec)
with _CREATE_LOCK, self._connect() as conn:
iso_pool, iso_volume = self._user_iso_volume(conn, user_id, volume_name)
return self._create_iso_vm(
conn, validated, requested_uuid, iso_pool, iso_volume)
@staticmethod
def _power_action_target_active(domain: Any, action: str) -> bool:
"""Return the final active state expected for one power request.
``reboot`` is the one action whose final state is domain-configured:
an ``on_reboot=destroy`` policy intentionally leaves an ISO/install
domain shut off. If the policy cannot be read, refuse to issue the
edge-triggered request: accepting a running result would otherwise
hide an unknown target policy as a successful reboot.
"""
if action in {"start", "reset"}:
return True
if action in {"shutdown", "poweroff"}:
return False
if action == "reboot":
try:
root = ET.fromstring(domain.XMLDesc(0))
except (libvirt.libvirtError, ET.ParseError, TypeError, ValueError) as exc:
raise VMError(
"无法确认重启后的目标状态,请查询实例状态后重试",
502,
error_code=POWER_ACTION_RESULT_UNCERTAIN_ERROR_CODE,
) from exc
return root.findtext("on_reboot") != "destroy"
raise VMError("不支持的虚拟机操作")
@classmethod
def _wait_for_power_action(
cls, domain: Any, *, action: str, target_active: bool,
timeout: float | None = None,
poll_interval: float | None = None,
) -> None:
"""Wait for and verify the bounded postcondition of a power action.
A successful libvirt call only means that the request was accepted.
Read ``info()[0]`` as well as ``isActive()`` so paused/blocked/crashed
domains cannot be mistaken for a running target. Reboot/reset cannot
prove that a complete guest reboot cycle occurred, but they can still
refuse a response that leaves the domain in a non-running state.
"""
timeout = POWER_ACTION_TIMEOUT if timeout is None else timeout
poll_interval = (
POWER_ACTION_POLL_INTERVAL
if poll_interval is None else poll_interval
)
deadline = time.monotonic() + max(0, timeout)
while True:
try:
active = bool(domain.isActive())
state = STATES.get(domain.info()[0], "unknown")
except (libvirt.libvirtError, IndexError, TypeError, ValueError) as exc:
raise VMError(
"虚拟机电源操作结果无法确认,请查询实例状态;请勿重复提交",
502, error_code=POWER_ACTION_RESULT_UNCERTAIN_ERROR_CODE,
) from exc
reached = (active and state == "running") if target_active else (
not active and state == "shutoff")
if reached:
return
if time.monotonic() >= deadline:
target = "运行" if target_active else "关机"
raise VMError(
f"虚拟机电源操作后未确认{target}状态,请查询实例状态;请勿重复提交",
502, error_code=POWER_ACTION_RESULT_UNCERTAIN_ERROR_CODE,
)
if poll_interval > 0:
time.sleep(poll_interval)
def action(self, uuid: str, action: str) -> dict[str, Any]:
methods = {
"start": "create",
"shutdown": "shutdown",
"reboot": "reboot",
"poweroff": "destroy",
"reset": "reset",
}
if action not in methods:
raise VMError("不支持的虚拟机操作")
with self._connect() as conn:
domain = self._domain(conn, uuid)
active = bool(domain.isActive())
if action == "start" and active:
raise VMError("虚拟机已经在运行", 409)
if action != "start" and not active:
raise VMError("虚拟机未运行", 409)
target_active = self._power_action_target_active(domain, action)
try:
if action == "reset":
domain.reset(0)
else:
getattr(domain, methods[action])()
except libvirt.libvirtError as exc:
# A lost libvirt response can still mean that the request
# committed. Verify the target before deciding whether to
# expose an uncertain result; never issue the action again.
# reset, and a normal reboot, deliberately keep the domain
# running. A running read after an exception is therefore
# indistinguishable from a command that never committed.
if action == "reset" or (action == "reboot" and target_active):
self._wait_for_power_action(
domain, action=action, target_active=target_active)
raise VMError(
"虚拟机电源操作结果无法确认,请查询实例状态;请勿重复提交",
502,
error_code=POWER_ACTION_RESULT_UNCERTAIN_ERROR_CODE,
) from exc
self._wait_for_power_action(
domain, action=action, target_active=target_active)
else:
self._wait_for_power_action(
domain, action=action, target_active=target_active)
return self._vm_dict(domain)
def service_suspend(self, uuid: str) -> dict[str, Any]:
"""Converge a persistent VM to the administratively stopped state.
Autostart is disabled before requesting guest shutdown so a host reboot
cannot undo a service-expiry suspension. The operation is safe to
repeat after a lost response: an already stopped VM is still verified
and returned without issuing another shutdown.
"""
with self._connect() as conn:
domain = self._domain(conn, uuid)
if domain.isActive():
self._assert_no_active_snapshot_backup(domain)
if not domain.isPersistent():
raise VMError("只能暂停持久化虚拟机", 409)
was_running = bool(domain.isActive())
if bool(domain.autostart()):
domain.setAutostart(0)
if domain.isActive():
try:
domain.shutdown()
except libvirt.libvirtError as exc:
# A failed ACPI request is not allowed to prevent an
# administrative suspension. Recheck the target state,
# then fall through to the bounded force-stop path.
LOG.warning("Could not gracefully stop VM %s: %s", uuid, exc)
deadline = time.monotonic() + SERVICE_SUSPEND_SHUTDOWN_TIMEOUT
while domain.isActive() and time.monotonic() < deadline:
time.sleep(SERVICE_SUSPEND_SHUTDOWN_POLL_INTERVAL)
if domain.isActive():
try:
domain.destroy()
except libvirt.libvirtError as exc:
# destroy() may have reached libvirt even when its
# response was lost. Only fail if the VM is still on.
if domain.isActive():
raise VMError("虚拟机强制停机失败", 502) from exc
if domain.isActive():
raise VMError("虚拟机停机状态未确认", 502)
result = self._vm_dict(domain)
# PHP uses this durable result to distinguish a VM stopped by the
# expiry policy from one the tenant had already stopped. Only the
# former may be started automatically when a paid period begins.
result["service_was_running"] = was_running
return result
def service_resume(self, uuid: str, *, start_if_suspended: bool = False) -> dict[str, Any]:
"""Remove an administrative suspension and optionally restore runtime.
``start_if_suspended`` is supplied only when the billing ledger proves
the expiry policy stopped a previously running guest. It is a target
state and therefore remains safe to replay after a lost response.
"""
with self._connect() as conn:
domain = self._domain(conn, uuid)
if not domain.isPersistent():
raise VMError("只能恢复持久化虚拟机", 409)
if not bool(domain.autostart()):
domain.setAutostart(1)
if start_if_suspended and not domain.isActive():
try:
domain.create()
except libvirt.libvirtError as exc:
# create() may have succeeded while its transport response
# was lost. Confirm the target state before reporting a
# retryable failure.
if not domain.isActive():
raise VMError("虚拟机服务恢复后启动失败", 502) from exc
return self._vm_dict(domain)
@staticmethod
def _interface_link_state(interface: ET.Element) -> str:
link = interface.find("link")
# libvirt omits the element for its default, connected state.
return link.get("state", "up") if link is not None else "up"
@staticmethod
def _interface_with_link_state(interface: ET.Element, state: str) -> str:
updated = ET.fromstring(ET.tostring(interface, encoding="unicode"))
link = updated.find("link")
if link is None:
link = ET.SubElement(updated, "link")
link.set("state", state)
return ET.tostring(updated, encoding="unicode")
@classmethod
def _update_interface_links(cls, domain: Any, root: ET.Element,
state: str, flags: int) -> None:
for interface in root.findall("./devices/interface"):
if cls._interface_link_state(interface) == state:
continue
domain.updateDeviceFlags(
cls._interface_with_link_state(interface, state), flags)
@classmethod
def _interface_links_match(cls, root: ET.Element, state: str) -> bool:
return all(cls._interface_link_state(interface) == state
for interface in root.findall("./devices/interface"))
def _network_service_state(self, uuid: str, *, suspended: bool) -> dict[str, Any]:
"""Persist and, when running, apply one link state to every VM NIC."""
target = "down" if suspended else "up"
with self._connect() as conn:
domain = self._domain(conn, uuid)
if suspended and domain.isActive():
self._assert_no_active_snapshot_backup(domain)
if not domain.isPersistent():
raise VMError("只能修改持久化虚拟机的网络状态", 409)
inactive = ET.fromstring(domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
self._update_interface_links(
domain, inactive, target, libvirt.VIR_DOMAIN_AFFECT_CONFIG)
inactive = ET.fromstring(domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
if not self._interface_links_match(inactive, target):
raise VMError("虚拟机持久网络状态未确认", 502)
if domain.isActive():
live = ET.fromstring(domain.XMLDesc(0))
self._update_interface_links(
domain, live, target, libvirt.VIR_DOMAIN_AFFECT_LIVE)
if domain.isActive():
live = ET.fromstring(domain.XMLDesc(0))
if not self._interface_links_match(live, target):
raise VMError("虚拟机实时网络状态未确认", 502)
return {**self._vm_dict(domain), "network_suspended": suspended}
def network_suspend(self, uuid: str) -> dict[str, Any]:
"""Disconnect every NIC without stopping the VM or changing autostart."""
return self._network_service_state(uuid, suspended=True)
def network_resume(self, uuid: str) -> dict[str, Any]:
"""Reconnect every NIC without starting the VM or changing autostart."""
return self._network_service_state(uuid, suspended=False)
def _firewall_interface(
self, root: ET.Element, vm_uuid: str,
) -> tuple[ET.Element, str, str]:
"""Return the one managed public NIC, its IP and current filter name."""
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
public_ip_cidr = managed.get("public-ip-cidr") if managed is not None else None
if (managed is None or managed.get("version") != "2"
or managed.get("os-source") != "cloud_template"
or not public_ip_cidr):
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]
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):
raise VMError("虚拟机公网网卡不在面板管理的 Linux 网桥上", 409,
error_code="firewall_capability_missing")
refs = interface.findall("filterref")
expected_name = firewall_filter_name(vm_uuid)
if (len(refs) != 1
or refs[0].get("filter") not in {
CLEAN_TRAFFIC_FILTER, expected_name,
}):
raise VMError("虚拟机公网过滤器已被外部修改", 409,
error_code="firewall_drift_detected")
parameters = refs[0].findall("parameter")
public_ip = public_ip_cidr.split("/", 1)[0]
if (len(parameters) != 1 or parameters[0].get("name") != "IP"
or parameters[0].get("value") != public_ip):
raise VMError("虚拟机公网过滤器 IP 参数已漂移", 409,
error_code="firewall_drift_detected")
return interface, public_ip, refs[0].get("filter") or ""
@staticmethod
def _interface_with_firewall(
interface: ET.Element, filter_name: str, public_ip: str,
) -> str:
updated = ET.fromstring(ET.tostring(interface, encoding="unicode"))
refs = updated.findall("filterref")
if len(refs) != 1:
raise VMError("虚拟机公网过滤器已被外部修改", 409,
error_code="firewall_drift_detected")
position = list(updated).index(refs[0])
updated.remove(refs[0])
replacement = ET.Element("filterref", filter=filter_name)
ET.SubElement(replacement, "parameter", name="IP", value=public_ip)
updated.insert(position, replacement)
return ET.tostring(updated, encoding="unicode")
@staticmethod
def _lookup_filter(conn: Any, name: str) -> Any | None:
lookup = getattr(conn, "nwfilterLookupByName", None)
if not callable(lookup):
raise VMError("宿主机 libvirt 不支持网络过滤器", 502,
error_code="firewall_capability_missing")
try:
return lookup(name)
except libvirt.libvirtError as exc:
get_error_code = getattr(exc, "get_error_code", None)
no_filter_code = getattr(libvirt, "VIR_ERR_NO_NWFILTER", None)
if (callable(get_error_code) and no_filter_code is not None
and get_error_code() == no_filter_code):
return None
raise VMError(
"无法确认宿主机防火墙过滤器状态", 502,
error_code="firewall_result_uncertain",
) from exc
def _firewall_observation(
self, conn: Any, domain: Any, expected_xml: str | None = None,
) -> dict[str, Any]:
vm_uuid = domain.UUIDString()
expected_name = firewall_filter_name(vm_uuid)
inactive = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
inactive_managed = inactive.find(
f"./metadata/{{{PANEL_NS}}}managed")
inactive_policy_explicit = bool(
inactive_managed is not None
and inactive_managed.findall(f"{{{PANEL_NS}}}platform-policy")
)
platform_policy = _platform_policy_from_domain_xml(inactive)
_inactive_interface, inactive_ip, inactive_filter = self._firewall_interface(
inactive, vm_uuid)
live_filter = inactive_filter
live_ip = inactive_ip
if domain.isActive():
live = ET.fromstring(domain.XMLDesc(0))
live_managed = live.find(f"./metadata/{{{PANEL_NS}}}managed")
live_policy_explicit = bool(
live_managed is not None
and live_managed.findall(f"{{{PANEL_NS}}}platform-policy")
)
live_platform_policy = _platform_policy_from_domain_xml(live)
if (inactive_policy_explicit != live_policy_explicit
or not hmac.compare_digest(
platform_policy["digest"],
live_platform_policy["digest"])
or platform_policy != live_platform_policy):
raise VMError(
"虚拟机实时与持久平台网络策略不一致", 409,
error_code="firewall_drift_detected",
)
_live_interface, live_ip, live_filter = self._firewall_interface(
live, vm_uuid)
policy_evidence = {
"platform_policy_snapshot": platform_policy,
"platform_policy_digest": platform_policy["digest"],
}
coherent_refs = (
inactive_filter == live_filter and inactive_ip == live_ip)
if inactive_filter == CLEAN_TRAFFIC_FILTER:
return {
**policy_evidence,
"enabled": False,
"filter_mode": "baseline",
"filter_name": CLEAN_TRAFFIC_FILTER,
"filter_digest": None,
"sync_state": "active" if coherent_refs else "drifted",
"matches": False if expected_xml is not None else coherent_refs,
"coherent": coherent_refs,
}
if inactive_filter != expected_name:
return {
**policy_evidence,
"enabled": None,
"filter_mode": "unknown",
"filter_name": inactive_filter,
"filter_digest": None,
"sync_state": "drifted",
"matches": False,
"coherent": False,
}
filter_object = self._lookup_filter(conn, expected_name)
if filter_object is None or not callable(getattr(filter_object, "XMLDesc", None)):
return {
**policy_evidence,
"enabled": None,
"filter_mode": "managed",
"filter_name": expected_name,
"filter_digest": None,
"sync_state": "drifted",
"matches": False,
"coherent": False,
}
actual_xml = filter_object.XMLDesc(0)
actual_digest = firewall_xml_digest(actual_xml)
root = ET.fromstring(actual_xml)
enabled = any(
rule.get("action") == "drop"
and rule.get("direction") == "in"
and rule.find("all") is not None
for rule in root.findall("rule")
)
expected_filter_digest = (firewall_xml_digest(expected_xml)
if expected_xml is not None else None)
matches = (coherent_refs and expected_filter_digest is not None
and actual_digest == expected_filter_digest)
return {
**policy_evidence,
"enabled": enabled,
"filter_mode": "managed",
"filter_name": expected_name,
"filter_digest": actual_digest,
"sync_state": "active" if coherent_refs else "drifted",
"matches": matches,
"coherent": coherent_refs,
}
def get_firewall_policy(self, vm_id: str) -> dict[str, Any]:
"""Read live/inactive nwfilter evidence without changing the host."""
with self._connect() as conn:
domain = self._domain(conn, vm_id)
if not domain.isPersistent():
raise VMError("只能管理持久化虚拟机的防火墙", 409,
error_code="firewall_capability_missing")
return self._firewall_observation(conn, domain)
def reconcile_firewall_policy(
self, vm_id: str, *, enabled: bool, rules: Any,
compiler_version: int = FIREWALL_FILTER_COMPILER_VERSION,
) -> dict[str, Any]:
"""Compare exact host evidence with one target policy; never mutate."""
with self._connect() as conn:
domain = self._domain(conn, vm_id)
inactive_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
platform_policy = _platform_policy_from_domain_xml(inactive_root)
(expected_xml, normalized, policy_digest,
expected_filter_digest) = build_firewall_filter_xml(
vm_id, enabled, rules, compiler_version=compiler_version,
platform_policy_snapshot=platform_policy)
observation = self._firewall_observation(
conn, domain, expected_xml)
return {
**observation,
"policy_digest": policy_digest,
"expected_filter_digest": expected_filter_digest,
"rules": normalized,
}
def apply_firewall_policy(
self, vm_id: str, *, enabled: bool, rules: Any,
) -> dict[str, Any]:
"""Atomically converge one VM's typed ingress policy where possible."""
expected_name = firewall_filter_name(vm_id)
with self._connect() as conn:
self._require_clean_traffic_filter(conn)
define_filter = getattr(conn, "nwfilterDefineXML", None)
if not callable(define_filter):
raise VMError("宿主机 libvirt 不支持定义网络过滤器", 502,
error_code="firewall_capability_missing")
domain = self._domain(conn, vm_id)
if not domain.isPersistent():
raise VMError("只能管理持久化虚拟机的防火墙", 409,
error_code="firewall_capability_missing")
inactive_root = ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE))
platform_policy = _platform_policy_from_domain_xml(inactive_root)
(expected_xml, normalized, policy_digest,
expected_filter_digest) = build_firewall_filter_xml(
vm_id, enabled, rules,
platform_policy_snapshot=platform_policy)
inactive_interface, public_ip, old_filter_name = \
self._firewall_interface(inactive_root, domain.UUIDString())
old_inactive_xml = ET.tostring(
inactive_interface, encoding="unicode")
old_live_xml = None
if domain.isActive():
live_root = ET.fromstring(domain.XMLDesc(0))
live_interface, live_ip, live_filter_name = self._firewall_interface(
live_root, domain.UUIDString())
if live_ip != public_ip:
raise VMError("虚拟机实时与持久网络配置不一致", 409,
error_code="firewall_drift_detected")
if live_filter_name != old_filter_name:
raise VMError("虚拟机实时与持久防火墙配置不一致", 409,
error_code="firewall_drift_detected")
old_live_xml = ET.tostring(live_interface, encoding="unicode")
old_filter = self._lookup_filter(conn, expected_name)
old_filter_xml = (old_filter.XMLDesc(0)
if old_filter is not None
and callable(getattr(old_filter, "XMLDesc", None))
else None)
if (old_filter_name == expected_name
and old_filter_xml is None):
raise VMError("虚拟机引用的防火墙过滤器不存在", 409,
error_code="firewall_drift_detected")
old_filter_digest = (firewall_xml_digest(old_filter_xml)
if old_filter_xml is not None else None)
definition_xml = expected_xml
if old_filter_xml is not None:
old_filter_root = ET.fromstring(old_filter_xml)
filter_uuids = old_filter_root.findall("uuid")
if (old_filter_root.get("name") != expected_name
or len(filter_uuids) != 1
or not filter_uuids[0].text):
raise VMError(
"宿主机现有防火墙过滤器 UUID 无效", 409,
error_code="firewall_drift_detected",
)
try:
filter_uuid = str(uuidlib.UUID(filter_uuids[0].text.strip()))
except (ValueError, AttributeError) as exc:
raise VMError(
"宿主机现有防火墙过滤器 UUID 无效", 409,
error_code="firewall_drift_detected",
) from exc
definition_root = ET.fromstring(expected_xml)
uuid_node = ET.Element("uuid")
uuid_node.text = filter_uuid
definition_root.insert(0, uuid_node)
definition_xml = ET.tostring(
definition_root, encoding="unicode")
target_interface = self._interface_with_firewall(
inactive_interface, expected_name, public_ip)
try:
defined = define_filter(definition_xml)
if defined is None:
raise VMError("宿主机未能定义防火墙过滤器", 502,
error_code="firewall_apply_failed")
domain.updateDeviceFlags(
target_interface, libvirt.VIR_DOMAIN_AFFECT_CONFIG)
if domain.isActive():
domain.updateDeviceFlags(
target_interface, libvirt.VIR_DOMAIN_AFFECT_LIVE)
evidence = self._firewall_observation(
conn, domain, expected_xml)
if not evidence["matches"]:
raise VMError("防火墙应用后校验失败", 502,
error_code="firewall_result_uncertain")
except Exception as exc:
# A transport error may arrive after libvirt committed. Exact
# evidence wins over the lost response and makes the operation
# safely idempotent.
try:
evidence = self._firewall_observation(
conn, domain, expected_xml)
if evidence["matches"]:
return {
**evidence,
"enabled": enabled,
"rules": normalized,
"policy_digest": policy_digest,
"filter_digest": expected_filter_digest,
}
except Exception:
evidence = None
restored = True
try:
domain.updateDeviceFlags(
old_inactive_xml, libvirt.VIR_DOMAIN_AFFECT_CONFIG)
if old_live_xml is not None and domain.isActive():
domain.updateDeviceFlags(
old_live_xml, libvirt.VIR_DOMAIN_AFFECT_LIVE)
if old_filter_xml is not None:
define_filter(old_filter_xml)
else:
created = self._lookup_filter(conn, expected_name)
if created is not None:
created.undefine()
restored_filter = self._lookup_filter(conn, expected_name)
if old_filter_xml is None:
filter_restored = restored_filter is None
else:
filter_restored = (
restored_filter is not None
and callable(getattr(restored_filter, "XMLDesc", None))
and firewall_xml_digest(restored_filter.XMLDesc(0))
== old_filter_digest
)
if old_filter_name == CLEAN_TRAFFIC_FILTER:
restored_evidence = self._firewall_observation(
conn, domain)
references_restored = (
restored_evidence.get("filter_mode") == "baseline"
and restored_evidence.get("coherent") is True
)
else:
restored_evidence = self._firewall_observation(
conn, domain, old_filter_xml)
references_restored = (
restored_evidence.get("matches") is True)
if not filter_restored or not references_restored:
restored = False
except Exception:
LOG.exception(
"Could not fully roll back VM firewall: uuid=%s", vm_id)
restored = False
if not restored:
raise VMError(
"防火墙应用结果不确定,必须查询原操作核对", 503,
error_code="firewall_result_uncertain",
) from exc
raise VMError(
"防火墙应用失败,已恢复原有网络策略", 502,
error_code="firewall_apply_failed",
) from exc
return {
**evidence,
"enabled": enabled,
"rules": normalized,
"policy_digest": policy_digest,
"filter_digest": expected_filter_digest,
}
def delete_firewall_filter(self, vm_id: str) -> dict[str, Any]:
"""Delete only the deterministic wrapper after no domain references it."""
vm_uuid = self._uuid(vm_id)
filter_name = firewall_filter_name(vm_uuid)
with self._connect() as conn:
for domain in conn.listAllDomains(0):
roots = [ET.fromstring(domain.XMLDesc(0))]
if domain.isPersistent():
roots.append(ET.fromstring(
domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)))
if any(
ref.get("filter") == filter_name
for root in roots
for ref in root.findall("./devices/interface/filterref")):
raise VMError("防火墙过滤器仍被虚拟机引用", 409,
error_code="firewall_cleanup_pending")
filter_object = self._lookup_filter(conn, filter_name)
if filter_object is None:
return {"deleted": True, "already_absent": True}
filter_object.undefine()
if self._lookup_filter(conn, filter_name) is not None:
raise VMError("防火墙过滤器删除未确认", 502,
error_code="firewall_cleanup_pending")
return {"deleted": True, "already_absent": False}
@staticmethod
def _disk_sources(root: ET.Element) -> list[ET.Element]:
return [source for disk in root.findall("./devices/disk")
if disk.get("device") == "disk"
for source in [disk.find("source")] if source is not None]
@staticmethod
def _all_disk_sources(root: ET.Element) -> list[ET.Element]:
# Include primary, backing, external data-file and mirror sources. A
# second VM can depend on this volume in any of those positions.
return root.findall("./devices/disk//source")
def _other_domain_uses_volume(self, conn: Any, vm_uuid: str,
pool_name: str, volume_name: str,
volume_path: str) -> bool:
for other in conn.listAllDomains(0):
if other.UUIDString() == vm_uuid:
continue
flags = [0]
if other.isActive() and other.isPersistent():
flags.append(libvirt.VIR_DOMAIN_XML_INACTIVE)
for flag in flags:
try:
root = ET.fromstring(other.XMLDesc(flag))
except ET.ParseError as exc:
raise VMError("其他虚拟机配置 XML 无效,无法安全删除磁盘", 502) from exc
for source in self._all_disk_sources(root):
if ((source.get("pool") == pool_name
and source.get("volume") == volume_name)
or volume_path in (source.get("file"), source.get("dev"))):
return True
return False
@staticmethod
def _snapshot_job_type(domain: Any, flags: int) -> tuple[int, dict[str, Any]]:
job_stats = getattr(domain, "jobStats", None)
if not callable(job_stats):
raise VMError(
"宿主机 libvirt 不支持在线备份状态查询,无法安全创建快照", 409,
error_code="live_snapshot_unsupported",
)
result = job_stats(flags)
if not isinstance(result, dict):
raise VMSnapshotUncertainError(
"宿主机返回的在线快照任务状态无效,必须人工核查")
job_type = result.get("type")
if isinstance(job_type, bool) or not isinstance(job_type, int):
raise VMSnapshotUncertainError(
"宿主机返回的在线快照任务类型无效,必须人工核查")
return job_type, result
@classmethod
def _snapshot_job_type_if_active(
cls, domain: Any, flags: int,
) -> tuple[int, dict[str, Any]] | None:
"""Query backup stats only while libvirt reports an active domain.
``virDomainGetJobStats`` rejects an inactive domain. A VM can also
shut down between the activity check and the query, so re-check the
state when libvirt reports that race and let callers decide whether
the missing runtime evidence is safe to defer.
"""
try:
if not domain.isActive():
return None
except libvirt.libvirtError as exc:
raise VMSnapshotUncertainError(
"无法确认虚拟机运行状态,不能安全查询在线备份任务"
) from exc
try:
return cls._snapshot_job_type(domain, flags)
except libvirt.libvirtError as exc:
try:
if not domain.isActive():
return None
except libvirt.libvirtError:
pass
raise VMSnapshotUncertainError(
"宿主机无法查询在线备份任务状态,必须人工核查"
) from exc
@classmethod
def _assert_no_active_snapshot_backup(cls, domain: Any) -> None:
"""Keep expiry target states from interrupting an active disk copy."""
if not callable(getattr(domain, "jobStats", None)):
job_info = getattr(domain, "jobInfo", None)
if not callable(job_info):
raise VMSnapshotUncertainError(
"宿主机不能查询虚拟机活动作业,无法安全执行到期暂停")
try:
legacy = job_info()
except libvirt.libvirtError as exc:
raise VMSnapshotUncertainError(
"宿主机无法查询虚拟机活动作业,无法安全执行到期暂停"
) from exc
if (not isinstance(legacy, (tuple, list)) or not legacy
or isinstance(legacy[0], bool)
or not isinstance(legacy[0], int)):
raise VMSnapshotUncertainError(
"宿主机返回的虚拟机活动作业状态无效")
if legacy[0] == getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0):
return
# Legacy jobInfo cannot distinguish a backup from migration or a
# block job. Interrupting any of them would be unsafe, so defer
# the fail-safe target state until the active job has ended.
raise VMError("虚拟机仍有活动 libvirt 作业,请稍后重试到期暂停", 409)
job_type, stats = cls._snapshot_job_type(domain, 0)
if job_type == getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0):
return
backup_operation = getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)
operation = stats.get("operation")
if backup_operation is None or not isinstance(operation, int):
raise VMSnapshotUncertainError(
"无法识别虚拟机当前 libvirt 作业,不能安全执行到期暂停")
if operation == backup_operation:
raise VMError("虚拟机仍在执行在线快照备份,请稍后重试到期暂停", 409)
@classmethod
def _wait_for_snapshot_backup(
cls,
domain: Any,
progress: Callable[[str], None] | None = None,
*,
timeout: float = SNAPSHOT_JOB_TIMEOUT,
abort_timeout: float = SNAPSHOT_ABORT_TIMEOUT,
) -> str:
"""Wait for a push backup and require its retained terminal result."""
if timeout <= 0 or abort_timeout <= 0:
raise ValueError("snapshot wait timeouts must be positive")
none = getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0)
failed = getattr(libvirt, "VIR_DOMAIN_JOB_FAILED", 4)
cancelled = getattr(libvirt, "VIR_DOMAIN_JOB_CANCELLED", 5)
completed = getattr(libvirt, "VIR_DOMAIN_JOB_COMPLETED", 3)
completed_flag = getattr(libvirt, "VIR_DOMAIN_JOB_STATS_COMPLETED", None)
keep_completed_flag = getattr(
libvirt, "VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED", None)
if completed_flag is None or keep_completed_flag is None:
raise VMError(
"宿主机 libvirt 版本过旧,不能保留在线快照最终证据", 409,
error_code="live_snapshot_unsupported",
)
deadline = time.monotonic() + timeout
abort_deadline = None
while True:
job_type, stats = cls._snapshot_job_type(domain, 0)
backup_operation = getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)
if (job_type != none
and (backup_operation is None
or stats.get("operation") != backup_operation)):
raise VMSnapshotUncertainError(
"等待在线快照时发现了非备份 libvirt 作业")
if job_type == none:
break
if job_type == failed:
return "failed"
if job_type == cancelled:
return "cancelled"
if progress is not None:
progress("copying")
now = time.monotonic()
if abort_deadline is None and now >= deadline:
if not cls._abort_snapshot_backup(domain):
raise VMSnapshotUncertainError(
"在线快照超过最大执行时间,且无法确认备份任务已停止")
abort_deadline = now + abort_timeout
elif abort_deadline is not None and now >= abort_deadline:
raise VMSnapshotUncertainError(
"在线快照超时后已请求取消,但宿主机未在安全时限内结束任务")
time.sleep(SNAPSHOT_JOB_POLL_INTERVAL)
try:
terminal_type, _terminal_stats = cls._snapshot_job_type(
domain, completed_flag | keep_completed_flag)
except libvirt.libvirtError as exc:
raise VMSnapshotUncertainError(
"在线快照任务已结束,但宿主机没有保留可验证的最终状态") from exc
if (_terminal_stats.get("operation")
!= getattr(libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)):
raise VMSnapshotUncertainError(
"宿主机保留的最终作业不是在线备份任务")
if terminal_type == completed:
return "completed"
if terminal_type == failed:
return "failed"
if terminal_type == cancelled:
return "cancelled"
raise VMSnapshotUncertainError(
"在线快照任务已结束,但最终结果无法确认,必须人工核查")
@staticmethod
def _abort_snapshot_backup(domain: Any) -> bool:
abort = getattr(domain, "abortJob", None)
if not callable(abort):
return False
try:
result = abort()
return result in (None, 0)
except libvirt.libvirtError:
LOG.exception("Could not abort a live snapshot backup job")
return False
@classmethod
def _reconcile_ambiguous_backup_start(cls, domain: Any) -> str:
"""Prove the terminal state after ``backupBegin`` loses its reply."""
none = getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0)
completed = getattr(libvirt, "VIR_DOMAIN_JOB_COMPLETED", 3)
failed = getattr(libvirt, "VIR_DOMAIN_JOB_FAILED", 4)
cancelled = getattr(libvirt, "VIR_DOMAIN_JOB_CANCELLED", 5)
completed_flag = getattr(libvirt, "VIR_DOMAIN_JOB_STATS_COMPLETED", None)
keep_completed_flag = getattr(
libvirt, "VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED", None)
if completed_flag is None or keep_completed_flag is None:
raise VMSnapshotUncertainError(
"在线快照启动响应丢失,且宿主机不能查询最终状态")
try:
current, current_stats = cls._snapshot_job_type(domain, 0)
if current != none:
backup_operation = getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)
if (backup_operation is None
or current_stats.get("operation") != backup_operation):
raise VMSnapshotUncertainError(
"在线快照启动响应丢失,但当前活动作业不是可确认的备份任务")
if current == completed:
return "completed"
if current == failed:
return "failed"
if current == cancelled:
return "cancelled"
if not cls._abort_snapshot_backup(domain):
raise VMSnapshotUncertainError(
"在线快照启动响应丢失,且活动备份任务无法安全停止")
return cls._wait_for_snapshot_backup(
domain,
timeout=SNAPSHOT_ABORT_TIMEOUT,
abort_timeout=SNAPSHOT_ABORT_TIMEOUT,
)
terminal, terminal_stats = cls._snapshot_job_type(
domain, completed_flag | keep_completed_flag)
except VMSnapshotUncertainError:
raise
except Exception as exc:
raise VMSnapshotUncertainError(
"在线快照启动响应丢失,无法确认宿主机是否已开始复制") from exc
if (terminal != none
and terminal_stats.get("operation") != getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)):
raise VMSnapshotUncertainError(
"在线快照启动响应丢失,但保留的最终作业不是备份任务")
if terminal == completed:
return "completed"
if terminal == failed:
return "failed"
if terminal == cancelled:
return "cancelled"
if terminal == none:
return "not_started"
raise VMSnapshotUncertainError(
"在线快照启动响应丢失,宿主机返回了无法识别的最终状态")
@classmethod
def _snapshot_target_path(cls, pool: Any, volume: Any) -> str:
root = cls._file_pool_path(pool)
path = volume.path()
if (root is None or not isinstance(path, str) or not path.startswith("/")
or posixpath.dirname(posixpath.normpath(path)) != root):
raise VMError(
"在线本地快照当前只支持文件型存储池中的直属 qcow2 卷", 409,
error_code="snapshot_pool_unsupported",
)
return posixpath.normpath(path)
def _snapshot_disk_context(
self, conn: Any, domain: Any,
) -> tuple[ET.Element, ET.Element, ET.Element, Any, Any]:
if not domain.isPersistent():
raise VMError("临时虚拟机不支持本地快照", 409)
root = self._vm_xml(domain)
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
if (managed is None or managed.get("os-source") != "cloud_template"):
raise VMError("只有面板创建的云镜像虚拟机支持本地快照", 409)
disks = root.findall("./devices/disk[@device='disk']")
if len(disks) != 1:
raise VMError("本地快照当前只支持一块系统盘", 409)
disk = disks[0]
target = disk.find("target")
driver = disk.find("driver")
if (target is None or target.get("dev") != "vda"
or driver is None or driver.get("type") != "qcow2"):
raise VMError("本地快照当前只支持 qcow2 格式的 vda 系统盘", 409)
volume = self._owned_volume(conn, domain)
pool = self._active_pool(conn, self.storage_pool)
if managed.get("disk-volume") != volume.name():
raise VMError("虚拟机系统盘记录不一致,已停止快照操作", 409)
try:
volume_root = ET.fromstring(volume.XMLDesc(0))
except ET.ParseError as exc:
raise VMError("宿主机返回的系统盘卷 XML 无效", 502) from exc
volume_format = volume_root.find("./target/format")
if volume_format is None or volume_format.get("type") != "qcow2":
raise VMError("虚拟机系统盘存储卷不是 qcow2 格式", 409)
return root, managed, disk, pool, volume
def _delete_unreferenced_volume(
self, conn: Any, pool: Any, volume: Any, *, vm_uuid: str = "",
) -> bool:
try:
if self._other_domain_uses_volume(
conn, vm_uuid, pool.name(),
volume.name(), volume.path()):
return False
volume.delete(0)
return True
except Exception:
LOG.exception("Could not safely remove snapshot volume %s", volume.name())
return False
def create_live_snapshot(
self,
vm_id: str,
snapshot_key: str,
*,
consistency: str = "filesystem",
progress: Callable[[str], None] | None = None,
) -> dict[str, Any]:
"""Create an independent local qcow2 with libvirt push backup.
``filesystem`` consistency is strict: guest-agent freeze and thaw must
both succeed. ``crash`` is accepted only when explicitly requested;
it never acts as an implicit fallback for a guest-agent failure.
"""
vm_uuid = self._uuid(vm_id)
volume_name = snapshot_volume_name(vm_uuid, snapshot_key)
if consistency not in {"filesystem", "crash"}:
raise VMError("快照一致性模式无效", 422)
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
if not domain.isActive():
raise VMError("在线快照要求虚拟机处于运行状态", 409)
_root, _managed, _disk, pool, source = self._snapshot_disk_context(
conn, domain)
self._refresh_directory_pool(pool)
if volume_name in set(pool.listVolumes()):
raise VMError("快照存储卷已存在,不能覆盖", 409)
source_capacity = int(source.info()[1])
if source_capacity <= 0:
raise VMError("无法确认系统盘容量,已停止创建快照", 502)
if source_capacity > int(pool.info()[3]):
raise VMError("存储池可用空间不足,无法创建本地快照", 409)
reuse_flag = getattr(
libvirt, "VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL", None)
if (reuse_flag is None
or getattr(libvirt, "VIR_DOMAIN_JOB_STATS_COMPLETED", None) is None
or getattr(libvirt, "VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED", None) is None
or getattr(libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None) is None
or not callable(getattr(domain, "backupBegin", None))):
raise VMError(
"宿主机 libvirt 版本过旧,不支持安全的在线本地快照", 409,
error_code="live_snapshot_unsupported",
)
# A retained completed result is domain-scoped, not target-scoped.
# Clear older evidence before allocating this operation's target,
# otherwise a lost backupBegin response could be mistaken for the
# previous backup's success.
current_type, _current_stats = self._snapshot_job_type(domain, 0)
if current_type != getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0):
raise VMError("虚拟机已有 libvirt 作业,暂时不能创建快照", 409)
completed_flag = libvirt.VIR_DOMAIN_JOB_STATS_COMPLETED
keep_completed_flag = libvirt.VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED
previous_type, previous_stats = self._snapshot_job_type(
domain, completed_flag | keep_completed_flag)
if (previous_type != getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0)
and previous_stats.get("operation")
!= libvirt.VIR_DOMAIN_JOB_OPERATION_BACKUP):
raise VMSnapshotUncertainError(
"无法安全清除非备份 libvirt 作业的旧终态证据")
if previous_type != getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0):
consumed_type, consumed_stats = self._snapshot_job_type(
domain, completed_flag)
if (consumed_type != previous_type
or consumed_stats.get("operation")
!= libvirt.VIR_DOMAIN_JOB_OPERATION_BACKUP):
raise VMSnapshotUncertainError(
"旧在线备份终态证据未能被一致地清除")
target = None
backup_attempted = False
backup_started = False
backup_terminal = False
freeze_attempted = False
thaw_failed = False
try:
try:
target = pool.createXML(
self._volume_xml_bytes(
volume_name, source_capacity, "qcow2",
allocation=source_capacity), 0)
except libvirt.libvirtError as exc:
try:
self._refresh_directory_pool(pool)
target_exists = volume_name in set(pool.listVolumes())
except Exception as verify_exc:
raise VMSnapshotUncertainError(
"快照卷预留响应异常,且无法确认确定性目标卷状态"
) from verify_exc
if target_exists:
observed = pool.storageVolLookupByName(volume_name)
if not self._delete_unreferenced_volume(
conn, pool, observed):
raise VMSnapshotUncertainError(
"快照卷预留响应异常,确定性目标卷已出现且无法安全清理"
) from exc
raise VMError("宿主机未能预留快照存储卷", 502) from exc
if target is None:
raise VMError("宿主机未能预留快照存储卷", 502)
target_path = self._snapshot_target_path(pool, target)
if consistency == "filesystem":
freeze = getattr(domain, "fsFreeze", None)
thaw = getattr(domain, "fsThaw", None)
if not callable(freeze) or not callable(thaw):
raise VMError(
"宿主机不支持 QEMU Guest Agent 文件系统冻结", 409,
error_code="snapshot_guest_agent_unavailable",
)
if progress is not None:
progress("freezing")
freeze_attempted = True
try:
frozen_count = freeze(None, 0)
except libvirt.libvirtError as exc:
raise VMError(
"QEMU Guest Agent 无法冻结文件系统,快照未创建", 409,
error_code="snapshot_guest_agent_unavailable",
) from exc
if (isinstance(frozen_count, bool)
or not isinstance(frozen_count, int)
or frozen_count < 1):
raise VMError(
"QEMU Guest Agent 未确认任何文件系统已冻结,快照未创建", 409,
error_code="snapshot_guest_agent_unavailable",
)
backup = ET.Element("domainbackup", mode="push")
disks = ET.SubElement(backup, "disks")
backup_disk = ET.SubElement(
disks, "disk", name="vda", backup="yes", type="file")
ET.SubElement(backup_disk, "driver", type="qcow2")
ET.SubElement(backup_disk, "target", file=target_path)
begin_error = None
try:
backup_attempted = True
result = domain.backupBegin(
ET.tostring(backup, encoding="unicode"), None, reuse_flag)
if result not in (None, 0):
raise libvirt.libvirtError("backup begin failed")
backup_started = True
except libvirt.libvirtError as exc:
begin_error = exc
finally:
if freeze_attempted:
try:
thawed_count = domain.fsThaw(None, 0)
thaw_failed = (
isinstance(thawed_count, bool)
or not isinstance(thawed_count, int)
or thawed_count < 1
)
except libvirt.libvirtError:
thaw_failed = True
if not thaw_failed:
freeze_attempted = False
if progress is not None:
progress("thawed")
if thaw_failed:
aborted = self._abort_snapshot_backup(domain)
try:
thawed_count = domain.fsThaw(None, 0)
thaw_failed = (
isinstance(thawed_count, bool)
or not isinstance(thawed_count, int)
or thawed_count < 1
)
except libvirt.libvirtError:
thaw_failed = True
if not thaw_failed:
freeze_attempted = False
if progress is not None:
progress("thawed")
if not aborted:
raise VMSnapshotUncertainError(
"访客文件系统解冻失败,已停止继续操作;请立即检查虚拟机")
try:
cancelled_status = self._wait_for_snapshot_backup(
domain,
timeout=SNAPSHOT_ABORT_TIMEOUT,
abort_timeout=SNAPSHOT_ABORT_TIMEOUT,
)
except Exception as exc:
raise VMSnapshotUncertainError(
"访客解冻异常后已请求取消,但备份任务终态无法确认") from exc
backup_terminal = cancelled_status in {"failed", "cancelled"}
if cancelled_status == "completed":
raise VMSnapshotUncertainError(
"访客解冻异常期间备份已完成,已保留快照卷等待核查")
if thaw_failed:
raise VMSnapshotUncertainError(
"访客文件系统仍未确认解冻;请立即检查虚拟机")
raise VMError("访客文件系统首次解冻失败,快照已取消", 502)
if begin_error is not None:
status = self._reconcile_ambiguous_backup_start(domain)
backup_terminal = True
if status == "not_started":
raise VMError(
"宿主机未接受在线快照任务,未保留恢复点", 502) from begin_error
backup_started = True
else:
status = self._wait_for_snapshot_backup(domain, progress)
backup_terminal = True
if status != "completed":
raise VMError("在线快照复制失败,未生成可用恢复点", 502)
if progress is not None:
progress("verifying")
self._refresh_directory_pool(pool)
target = pool.storageVolLookupByName(volume_name)
try:
target_root = ET.fromstring(target.XMLDesc(0))
except ET.ParseError as exc:
raise VMSnapshotUncertainError(
"快照复制完成,但存储卷信息无法验证") from exc
target_format = target_root.find("./target/format")
target_capacity = int(target.info()[1])
if (target_format is None or target_format.get("type") != "qcow2"
or target_capacity != source_capacity):
raise VMSnapshotUncertainError(
"快照复制完成,但独立 qcow2 存储卷验证失败")
target_identity = self._snapshot_volume_identity(pool, target)
return {
"snapshot_key": snapshot_key,
"created": True,
"consistency": consistency,
"size_bytes": target_capacity,
"power_state": "running",
"volume_name": volume_name,
"volume_identity": target_identity,
}
except BaseException as exc:
if freeze_attempted:
try:
thawed_count = domain.fsThaw(None, 0)
thaw_failed = (
isinstance(thawed_count, bool)
or not isinstance(thawed_count, int)
or thawed_count < 1
)
except Exception:
thaw_failed = True
if not thaw_failed:
freeze_attempted = False
if progress is not None:
progress("thawed")
if backup_started and not backup_terminal:
if self._abort_snapshot_backup(domain):
try:
terminal = self._wait_for_snapshot_backup(
domain,
timeout=SNAPSHOT_ABORT_TIMEOUT,
abort_timeout=SNAPSHOT_ABORT_TIMEOUT,
)
except Exception:
terminal = "uncertain"
backup_terminal = terminal in {"failed", "cancelled"}
cleaned = True
if target is not None and (not backup_attempted or backup_terminal):
cleaned = self._delete_unreferenced_volume(
conn, pool, target)
elif target is not None:
cleaned = False
if (thaw_failed or not cleaned
or (backup_attempted and not backup_terminal)):
if isinstance(exc, VMSnapshotUncertainError):
raise
raise VMSnapshotUncertainError(
"在线快照失败且清理结果无法确认,必须人工核查") from exc
if isinstance(exc, VMError):
raise
if isinstance(exc, libvirt.libvirtError):
raise VMError("在线快照创建失败,未保留恢复点", 502) from exc
raise
def thaw_guest_filesystems(self, vm_id: str) -> dict[str, Any]:
"""Best-effort startup recovery for an interrupted QGA freeze window."""
vm_uuid = self._uuid(vm_id)
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
if not domain.isActive():
return {"uuid": vm_uuid, "thawed": True, "count": 0,
"power_state": "stopped"}
thaw = getattr(domain, "fsThaw", None)
if not callable(thaw):
raise VMError(
"无法执行中断快照的 QEMU Guest Agent 解冻恢复", 409,
error_code="snapshot_guest_agent_unavailable",
)
try:
count = thaw(None, 0)
except libvirt.libvirtError as exc:
raise VMError(
"中断快照的访客文件系统解冻恢复失败", 409,
error_code="snapshot_guest_agent_unavailable",
) from exc
if (isinstance(count, bool) or not isinstance(count, int) or count < 0):
raise VMSnapshotUncertainError(
"宿主机未返回有效的访客文件系统解冻结果")
return {"uuid": vm_uuid, "thawed": True, "count": count,
"power_state": "running"}
def release_live_snapshot_completed_evidence(self, vm_id: str) -> None:
"""Consume retained backup stats only after durable panel evidence exists."""
vm_uuid = self._uuid(vm_id)
completed_flag = getattr(
libvirt, "VIR_DOMAIN_JOB_STATS_COMPLETED", None)
keep_completed_flag = getattr(
libvirt, "VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED", None)
if completed_flag is None or keep_completed_flag is None:
return
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
retained = self._snapshot_job_type_if_active(
domain, completed_flag | keep_completed_flag)
# A completed result is only cleanup evidence. If the VM has
# already been powered off, leave that evidence for a later
# active-domain pass instead of asking libvirt for runtime stats.
if retained is None:
return
job_type, stats = retained
none = getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0)
if job_type == none:
return
if stats.get("operation") != getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None):
raise VMSnapshotUncertainError(
"拒绝清除非备份 libvirt 作业的最终证据")
consumed = self._snapshot_job_type_if_active(
domain, completed_flag)
if consumed is None:
return
consumed_type, consumed_stats = consumed
if (consumed_type != job_type
or consumed_stats.get("operation") != getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)):
raise VMSnapshotUncertainError(
"在线备份最终证据未能被一致地清除")
def snapshot_restore_plan(
self, vm_id: str, operation_id: str,
) -> dict[str, Any]:
"""Capture private disk identities before crossing restore's commit point."""
vm_uuid = self._uuid(vm_id)
replacement_name = snapshot_restore_volume_name(vm_uuid, operation_id)
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
_root, _managed, _disk, _pool, old_disk = (
self._snapshot_disk_context(conn, domain))
return {
"old_volume_name": old_disk.name(),
"replacement_volume_name": replacement_name,
"was_running": bool(domain.isActive()),
}
@classmethod
def _snapshot_volume_identity(cls, pool: Any, volume: Any) -> str:
"""Fingerprint an immutable snapshot volume without exposing paths."""
try:
return cls._template_replica_identity(pool, volume)
except VMError as exc:
raise VMSnapshotUncertainError(
"无法确认在线快照卷的具体存储代际") from exc
def reconcile_live_snapshot_create(
self,
vm_id: str,
snapshot_key: str,
snapshot_volume: str,
*,
verified_capacity: int | None = None,
verified_identity: str | None = None,
) -> dict[str, Any]:
"""Resolve an uncertain create only from retained libvirt evidence."""
vm_uuid = self._uuid(vm_id)
if snapshot_volume != snapshot_volume_name(vm_uuid, snapshot_key):
raise VMSnapshotUncertainError("快照登记卷身份不一致,不能自动核对")
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
_root, _managed, _disk, _pool, source = (
self._snapshot_disk_context(conn, domain))
durable_marker = (
isinstance(verified_capacity, int)
and not isinstance(verified_capacity, bool)
and verified_capacity > 0
and isinstance(verified_identity, str)
and re.fullmatch(r"[0-9a-f]{64}", verified_identity) is not None
)
marker_supplied = (
verified_capacity is not None or verified_identity is not None)
if marker_supplied and not durable_marker:
raise VMSnapshotUncertainError(
"在线快照的持久化验证标记不完整,不能自动核对")
none = getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0)
current_result = self._snapshot_job_type_if_active(domain, 0)
if current_result is not None:
current, _stats = current_result
if current != none:
raise VMSnapshotUncertainError(
"在线快照备份任务仍存在,暂不能完成自动核对")
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
if snapshot_volume not in set(pool.listVolumes()):
return {"outcome": "failed", "snapshot_key": snapshot_key}
volume = pool.storageVolLookupByName(snapshot_volume)
try:
volume_root = ET.fromstring(volume.XMLDesc(0))
except ET.ParseError as exc:
raise VMSnapshotUncertainError(
"在线快照已完成,但卷信息无法验证") from exc
volume_format = volume_root.find("./target/format")
capacity = int(volume.info()[1])
self._snapshot_target_path(pool, volume)
identity = self._snapshot_volume_identity(pool, volume)
if (volume_format is None or volume_format.get("type") != "qcow2"
or capacity <= 0 or capacity != int(source.info()[1])
or self._other_domain_uses_volume(
conn, "", pool.name(), volume.name(), volume.path())):
raise VMSnapshotUncertainError(
"在线快照最终卷未通过独立 qcow2 验证")
if durable_marker:
if capacity != verified_capacity or identity != verified_identity:
raise VMSnapshotUncertainError(
"在线快照卷与已持久化的验证代际不一致")
else:
completed_flag = getattr(
libvirt, "VIR_DOMAIN_JOB_STATS_COMPLETED", None)
keep_completed_flag = getattr(
libvirt, "VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED", None)
backup_operation = getattr(
libvirt, "VIR_DOMAIN_JOB_OPERATION_BACKUP", None)
if (completed_flag is None or keep_completed_flag is None
or backup_operation is None):
raise VMSnapshotUncertainError(
"宿主机不能提供在线备份最终状态,无法自动核对")
terminal_result = self._snapshot_job_type_if_active(
domain, completed_flag | keep_completed_flag)
if terminal_result is None:
raise VMSnapshotUncertainError(
"虚拟机已关机且没有可验证的在线备份最终状态")
terminal, terminal_stats = terminal_result
operation = terminal_stats.get("operation")
failed = getattr(libvirt, "VIR_DOMAIN_JOB_FAILED", 4)
cancelled = getattr(libvirt, "VIR_DOMAIN_JOB_CANCELLED", 5)
if terminal in {failed, cancelled}:
if operation != backup_operation:
raise VMSnapshotUncertainError(
"宿主机保留的失败作业不是在线备份任务")
if not self._delete_unreferenced_volume(conn, pool, volume):
raise VMSnapshotUncertainError(
"失败的在线快照卷无法安全清理")
return {"outcome": "failed", "snapshot_key": snapshot_key}
completed = getattr(libvirt, "VIR_DOMAIN_JOB_COMPLETED", 3)
if terminal != completed or operation != backup_operation:
raise VMSnapshotUncertainError(
"宿主机没有保留可证明成功的在线备份最终状态")
return {
"outcome": "succeeded",
"snapshot_key": snapshot_key,
"size_bytes": capacity,
"power_state": "running" if domain.isActive() else "stopped",
}
def reconcile_live_snapshot_delete(
self, vm_id: str, snapshot_key: str, snapshot_volume: str,
) -> dict[str, Any]:
"""Resolve delete strictly from presence of the registered volume."""
vm_uuid = self._uuid(vm_id)
if snapshot_volume != snapshot_volume_name(vm_uuid, snapshot_key):
raise VMSnapshotUncertainError("快照登记卷身份不一致,不能自动核对")
with self._connect() as conn:
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
exists = snapshot_volume in set(pool.listVolumes())
return {
"outcome": "failed" if exists else "succeeded",
"snapshot_key": snapshot_key,
}
def reconcile_live_snapshot_restore(
self,
vm_id: str,
snapshot_key: str,
snapshot_volume: str,
operation_id: str,
old_volume_name: str,
was_running: bool,
) -> dict[str, Any]:
"""Resolve a restore from its deterministic disk and domain metadata."""
vm_uuid = self._uuid(vm_id)
expected_snapshot = snapshot_volume_name(vm_uuid, snapshot_key)
replacement_name = snapshot_restore_volume_name(vm_uuid, operation_id)
if snapshot_volume != expected_snapshot:
raise VMSnapshotUncertainError("快照登记卷身份不一致,不能自动核对")
if (not isinstance(old_volume_name, str)
or not old_volume_name.endswith(".qcow2")
or not NAME_RE.fullmatch(old_volume_name.removesuffix(".qcow2"))
or old_volume_name == replacement_name):
raise VMSnapshotUncertainError("恢复任务缺少可信的原系统盘身份")
if not isinstance(was_running, bool):
raise VMSnapshotUncertainError("恢复任务缺少可信的原电源状态")
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
_root, managed, _disk, pool, current = (
self._snapshot_disk_context(conn, domain))
self._refresh_directory_pool(pool)
names = set(pool.listVolumes())
current_name = managed.get("disk-volume")
if current_name != current.name():
raise VMSnapshotUncertainError(
"虚拟机系统盘元数据与实际来源不一致")
if snapshot_volume not in names:
raise VMSnapshotUncertainError(
"不可变快照卷缺失,不能自动判定恢复结果")
if current_name == replacement_name:
if replacement_name not in names:
raise VMSnapshotUncertainError(
"恢复后的系统盘或不可变快照卷缺失")
if was_running and not domain.isActive():
try:
domain.create()
except libvirt.libvirtError as exc:
if not domain.isActive():
raise VMSnapshotUncertainError(
"恢复系统盘已切换,但原运行状态尚未恢复") from exc
live_managed = self._vm_xml(domain).find(
f"./metadata/{{{PANEL_NS}}}managed")
if (not domain.isActive() or live_managed is None
or live_managed.get("disk-volume") != replacement_name):
raise VMSnapshotUncertainError(
"恢复系统盘已切换,但运行状态无法安全确认")
if old_volume_name in names:
old_volume = pool.storageVolLookupByName(old_volume_name)
if self._other_domain_uses_volume(
conn, "", pool.name(), old_volume.name(),
old_volume.path()):
raise VMSnapshotUncertainError(
"原系统盘仍被虚拟机定义引用,不能自动清理")
try:
old_volume.delete(0)
except libvirt.libvirtError as exc:
raise VMSnapshotUncertainError(
"恢复已生效,但原系统盘清理仍未完成") from exc
return {
"outcome": "succeeded",
"snapshot_key": snapshot_key,
"power_state": (
"running" if domain.isActive() else "stopped"),
}
if current_name == old_volume_name:
if was_running and not domain.isActive():
try:
domain.create()
except libvirt.libvirtError as exc:
if not domain.isActive():
raise VMSnapshotUncertainError(
"快照恢复未生效,但原虚拟机运行状态尚未恢复") from exc
live_managed = self._vm_xml(domain).find(
f"./metadata/{{{PANEL_NS}}}managed")
if (not domain.isActive() or live_managed is None
or live_managed.get("disk-volume") != old_volume_name):
raise VMSnapshotUncertainError(
"原系统盘仍在使用,但运行状态无法安全确认")
if replacement_name in names:
replacement = pool.storageVolLookupByName(replacement_name)
if self._other_domain_uses_volume(
conn, "", pool.name(), replacement.name(),
replacement.path()):
raise VMSnapshotUncertainError(
"未生效的恢复临时盘仍被虚拟机定义引用")
try:
replacement.delete(0)
except libvirt.libvirtError as exc:
raise VMSnapshotUncertainError(
"未生效的恢复临时盘无法安全清理") from exc
return {"outcome": "failed", "snapshot_key": snapshot_key}
raise VMSnapshotUncertainError(
"虚拟机当前系统盘既不是原盘也不是确定性恢复盘")
def restore_live_snapshot(
self,
vm_id: str,
snapshot_key: str,
snapshot_volume: str,
operation_id: str,
*,
expected_old_volume: str | None = None,
progress: Callable[[str], None] | None = None,
) -> dict[str, Any]:
"""Clone an immutable snapshot, then atomically switch the system disk."""
vm_uuid = self._uuid(vm_id)
expected_snapshot = snapshot_volume_name(vm_uuid, snapshot_key)
if snapshot_volume != expected_snapshot:
raise VMError("快照存储记录不一致,已停止恢复", 409)
replacement_name = snapshot_restore_volume_name(vm_uuid, operation_id)
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
_root, _managed, _disk, pool, old_disk = self._snapshot_disk_context(
conn, domain)
self._refresh_directory_pool(pool)
names = set(pool.listVolumes())
if snapshot_volume not in names:
raise VMError("快照数据已不存在,无法恢复", 409)
if replacement_name in names:
raise VMSnapshotUncertainError(
"该恢复操作的确定性系统盘已存在,必须核查原操作,不能重复克隆")
snapshot = pool.storageVolLookupByName(snapshot_volume)
if self._other_domain_uses_volume(
conn, "", pool.name(), snapshot.name(), snapshot.path()):
raise VMError("快照卷正在被虚拟机引用,不能作为不可变恢复点", 409)
try:
snapshot_root = ET.fromstring(snapshot.XMLDesc(0))
except ET.ParseError as exc:
raise VMError("宿主机返回的快照卷 XML 无效", 502) from exc
snapshot_format = snapshot_root.find("./target/format")
capacity = int(snapshot.info()[1])
if (snapshot_format is None or snapshot_format.get("type") != "qcow2"
or capacity <= 0):
raise VMError("快照不是可恢复的独立 qcow2 存储卷", 409)
if capacity > int(pool.info()[3]):
raise VMError("存储池空间不足,无法构建恢复系统盘", 409)
replacement = None
switched = False
restore_committed = False
was_running = bool(domain.isActive())
old_xml = domain.XMLDesc(
libvirt.VIR_DOMAIN_XML_INACTIVE if domain.isPersistent() else 0)
old_root = ET.fromstring(old_xml)
platform_policy, platform_policy_was_explicit = (
_platform_policy_state_from_domain_xml(old_root))
old_name = old_disk.name()
if expected_old_volume is not None and old_name != expected_old_volume:
raise VMSnapshotUncertainError(
"恢复前系统盘已变化,拒绝跨越未登记的磁盘状态")
try:
if progress is not None:
progress("cloning")
try:
replacement = pool.createXMLFrom(
self._volume_xml_bytes(
replacement_name, capacity, "qcow2",
allocation=capacity),
snapshot, 0)
if replacement is None:
raise libvirt.libvirtError(
"clone returned no storage volume")
except libvirt.libvirtError as exc:
try:
self._refresh_directory_pool(pool)
replacement_exists = replacement_name in set(
pool.listVolumes())
except Exception as verify_exc:
raise VMSnapshotUncertainError(
"恢复系统盘克隆响应异常,且无法确认确定性存储卷是否已创建"
) from verify_exc
if replacement_exists:
raise VMSnapshotUncertainError(
"恢复系统盘克隆响应异常,但确定性存储卷已出现;已保留现场"
) from exc
raise VMError(
"宿主机未能从快照构建恢复系统盘", 502) from exc
if progress is not None:
progress("shutting_down")
if was_running:
domain.shutdown()
deadline = time.monotonic() + SNAPSHOT_RESTORE_SHUTDOWN_TIMEOUT
while domain.isActive():
if time.monotonic() >= deadline:
raise VMError(
"正常关机超时,快照恢复已停止;当前系统盘未改变", 409)
time.sleep(SNAPSHOT_RESTORE_SHUTDOWN_POLL_INTERVAL)
inactive_xml = domain.XMLDesc(libvirt.VIR_DOMAIN_XML_INACTIVE)
inactive_root = ET.fromstring(inactive_xml)
_require_same_platform_policy_state(
inactive_root, platform_policy,
require_explicit=platform_policy_was_explicit,
message="关机后虚拟机平台网络策略已变化,快照恢复已停止",
)
inactive_managed = inactive_root.find(
f"./metadata/{{{PANEL_NS}}}managed")
if inactive_managed is None or inactive_managed.get("disk-volume") != old_name:
raise VMError("关机后虚拟机系统盘配置已变化,恢复已停止", 409)
current_old = self._owned_volume(conn, domain)
if current_old.name() != old_name:
raise VMError("关机后虚拟机系统盘已变化,恢复已停止", 409)
new_root = ET.fromstring(inactive_xml)
new_disk = next((
candidate
for candidate in new_root.findall("./devices/disk[@device='disk']")
if (candidate.find("target") is not None
and candidate.find("target").get("dev") == "vda")
), None)
if new_disk is None:
raise VMError("虚拟机 vda 系统盘配置已变化,恢复已停止", 409)
old_source = new_disk.find("source")
if old_source is None:
raise VMError("虚拟机系统盘来源已变化,恢复已停止", 409)
source_type, source_attrs = self._volume_source(pool, replacement)
new_disk.set("type", source_type)
source_index = list(new_disk).index(old_source)
new_disk.remove(old_source)
new_disk.insert(source_index, ET.Element("source", **source_attrs))
new_managed = new_root.find(f"./metadata/{{{PANEL_NS}}}managed")
if new_managed is None:
raise VMError("虚拟机面板元数据已变化,恢复已停止", 409)
new_managed.set("disk-volume", replacement_name)
if progress is not None:
progress("switching")
try:
new_domain = conn.defineXML(
ET.tostring(new_root, encoding="unicode"))
if new_domain is None:
raise libvirt.libvirtError("define returned no domain")
switched = True
except libvirt.libvirtError as exc:
observed = self._domain(conn, vm_uuid)
observed_managed = self._vm_xml(observed).find(
f"./metadata/{{{PANEL_NS}}}managed")
observed_volume = (observed_managed.get("disk-volume")
if observed_managed is not None else None)
if observed_volume == replacement_name:
new_domain = observed
switched = True
elif observed_volume == old_name:
raise VMError("宿主机未能切换恢复系统盘", 502) from exc
else:
raise VMSnapshotUncertainError(
"恢复系统盘切换结果不确定,已保留新旧磁盘") from exc
if platform_policy is not None:
_verify_platform_policy_in_domain(
new_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
warning = None
if was_running:
if progress is not None:
progress("starting")
try:
new_domain.create()
except libvirt.libvirtError as exc:
try:
live_managed = self._vm_xml(new_domain).find(
f"./metadata/{{{PANEL_NS}}}managed")
started_new = (new_domain.isActive()
and live_managed is not None
and live_managed.get("disk-volume")
== replacement_name)
except Exception:
started_new = False
if started_new:
warning = "虚拟机已从快照系统盘启动,但启动响应异常,请检查运行状态"
else:
raise VMError("快照系统盘启动失败,正在恢复原系统盘", 502) from exc
live_managed = self._vm_xml(new_domain).find(
f"./metadata/{{{PANEL_NS}}}managed")
if (not new_domain.isActive() or live_managed is None
or live_managed.get("disk-volume") != replacement_name):
raise VMError(
"快照系统盘启动后未通过运行状态核验,正在恢复原系统盘",
502,
)
restore_committed = True
if self._other_domain_uses_volume(
conn, vm_uuid, pool.name(),
old_disk.name(), old_disk.path()):
raise VMSnapshotUncertainError(
"快照恢复已生效,但原系统盘仍被其他定义引用")
try:
old_disk.delete(0)
except libvirt.libvirtError as exc:
LOG.exception(
"Snapshot restored but old system disk remains: %s",
vm_uuid,
)
raise VMSnapshotUncertainError(
"快照恢复已生效,但原系统盘清理失败") from exc
result = {
"snapshot_key": snapshot_key,
"restored": True,
"power_state": "running" if was_running else "stopped",
"active_volume_name": replacement_name,
}
if warning is not None:
result["warning"] = warning
return result
except BaseException as exc:
if restore_committed:
if isinstance(exc, VMSnapshotUncertainError):
raise
raise VMSnapshotUncertainError(
"快照恢复已生效,但提交后清理结果不确定") from exc
restored = True
if switched:
try:
current_domain = self._domain(conn, vm_uuid)
if current_domain.isActive():
current_domain.destroy()
if current_domain.isActive():
restored = False
restored_domain = conn.defineXML(old_xml)
if restored_domain is None:
restored = False
else:
if platform_policy is not None:
_verify_platform_policy_in_domain(
restored_domain, platform_policy,
require_explicit=platform_policy_was_explicit,
)
restored_root = ET.fromstring(restored_domain.XMLDesc(
libvirt.VIR_DOMAIN_XML_INACTIVE))
restored_managed = restored_root.find(
f"./metadata/{{{PANEL_NS}}}managed")
if (restored_managed is None
or restored_managed.get("disk-volume") != old_name):
restored = False
elif was_running:
restored_domain.create()
live_managed = self._vm_xml(restored_domain).find(
f"./metadata/{{{PANEL_NS}}}managed")
if (not restored_domain.isActive()
or live_managed is None
or live_managed.get("disk-volume") != old_name):
restored = False
except Exception:
LOG.exception("Could not restore original disk definition for %s", vm_uuid)
restored = False
elif was_running and not domain.isActive():
try:
domain.create()
except Exception:
LOG.exception("Could not restart original VM after restore failure: %s", vm_uuid)
restored = False
cleaned = True
if replacement is not None and restored:
cleaned = self._delete_unreferenced_volume(
conn, pool, replacement)
elif replacement is not None:
cleaned = False
if not restored or not cleaned:
if isinstance(exc, VMSnapshotUncertainError):
raise
raise VMSnapshotUncertainError(
"快照恢复失败且自动回退不完整,已保留新旧磁盘") from exc
if isinstance(exc, VMError):
raise
if isinstance(exc, (libvirt.libvirtError, ET.ParseError)):
raise VMError("快照恢复失败,已恢复原系统盘", 502) from exc
raise
def _validated_snapshot_volume(
self,
conn: Any,
vm_uuid: str,
snapshot_key: str,
snapshot_volume: str,
*,
allow_missing_vm: bool,
) -> tuple[Any, Any | None]:
vm_uuid = self._uuid(vm_uuid)
expected = snapshot_volume_name(vm_uuid, snapshot_key)
if snapshot_volume != expected:
raise VMError("快照存储记录不一致,已停止删除", 409)
if not allow_missing_vm:
domain = self._domain(conn, vm_uuid)
self._snapshot_disk_context(conn, domain)
# A powered-off domain cannot have an active backup job. libvirt
# rejects virDomainGetJobStats for that state with
# ``domain is not running``; snapshot deletion is deliberately
# performed after the caller has shut the VM off, so only query
# job stats while the domain is active.
if (domain.isActive()
and callable(getattr(domain, "jobStats", None))):
try:
job_type, _stats = self._snapshot_job_type(domain, 0)
except VMSnapshotUncertainError:
raise
except Exception as exc:
raise VMSnapshotUncertainError(
"无法确认虚拟机是否仍有在线备份任务,拒绝删除快照") from exc
if job_type != getattr(libvirt, "VIR_DOMAIN_JOB_NONE", 0):
raise VMError("虚拟机仍有在线备份任务,暂时不能删除快照", 409)
pool = self._active_pool(conn, self.storage_pool)
self._refresh_directory_pool(pool)
if snapshot_volume not in set(pool.listVolumes()):
return pool, None
volume = pool.storageVolLookupByName(snapshot_volume)
try:
root = ET.fromstring(volume.XMLDesc(0))
except ET.ParseError as exc:
raise VMError("宿主机返回的快照卷 XML 无效", 502) from exc
fmt = root.find("./target/format")
if fmt is None or fmt.get("type") != "qcow2":
raise VMError("登记的快照卷不是 qcow2,拒绝自动删除", 409)
if self._other_domain_uses_volume(
conn, "", pool.name(), volume.name(), volume.path()):
raise VMError("快照卷仍被虚拟机引用,拒绝删除", 409)
return pool, volume
def validate_snapshot_volume(
self,
vm_id: str,
snapshot_key: str,
snapshot_volume: str,
) -> dict[str, Any]:
"""Prove a registered snapshot is deletable without mutating it."""
vm_uuid = self._uuid(vm_id)
expected = snapshot_volume_name(vm_uuid, snapshot_key)
if snapshot_volume != expected:
raise VMError("快照存储记录不一致,已停止删除", 409)
with self._connect() as conn:
_pool, volume = self._validated_snapshot_volume(
conn, vm_uuid, snapshot_key, snapshot_volume,
allow_missing_vm=False,
)
return {
"snapshot_key": snapshot_key,
"deletable": True,
"already_absent": volume is None,
}
def delete_snapshot_volume(
self,
vm_id: str,
snapshot_key: str,
snapshot_volume: str,
*,
allow_missing_vm: bool = False,
) -> dict[str, Any]:
"""Delete exactly one registered snapshot after proving no VM uses it."""
vm_uuid = self._uuid(vm_id)
with self._connect() as conn:
_pool, volume = self._validated_snapshot_volume(
conn, vm_uuid, snapshot_key, snapshot_volume,
allow_missing_vm=allow_missing_vm,
)
if volume is None:
return {"snapshot_key": snapshot_key, "deleted": True,
"already_absent": True}
volume.delete(0)
return {"snapshot_key": snapshot_key, "deleted": True}
def _owned_volume(self, conn: Any, domain: Any) -> Any:
root = self._vm_xml(domain)
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
if managed is None:
raise VMError("只能删除由面板创建的磁盘", 403)
disk_name = managed.get("disk-volume") or f"panel-{domain.UUIDString()}.qcow2"
if (not disk_name.endswith(".qcow2") or "/" in disk_name
or not NAME_RE.fullmatch(disk_name.removesuffix(".qcow2"))):
raise VMError("面板记录的磁盘文件名无效,无法安全删除", 409)
pool = self._active_pool(conn, self.storage_pool)
pool_name = pool.name()
volume = pool.storageVolLookupByName(disk_name)
volume_path = volume.path()
sources = self._disk_sources(root)
if len(sources) != 1:
raise VMError("虚拟机磁盘配置已变化,无法安全删除磁盘", 409)
source = sources[0]
volume_source = (source.get("pool") == pool_name
and source.get("volume") == disk_name)
file_source = source.get("file") == volume_path
if not (volume_source or file_source):
raise VMError("虚拟机磁盘不属于面板配置的存储池", 409)
if self._other_domain_uses_volume(conn, domain.UUIDString(),
pool_name, disk_name, volume_path):
raise VMError("磁盘还被其他虚拟机使用", 409)
if domain.snapshotNum(0) > 0:
# ``snapshotNum`` reports libvirt native snapshot metadata. The
# panel's online snapshots are independent qcow2 backup volumes
# and are validated/removed by the panel cleanup path instead.
raise VMError(
"虚拟机存在 libvirt 原生快照,请先处理原生快照后再删除磁盘",
409,
error_code="vm_native_snapshot_present",
)
return volume
def _owned_seed_volume(self, conn: Any, domain: Any) -> Any | None:
root = self._vm_xml(domain)
managed = root.find(f"./metadata/{{{PANEL_NS}}}managed")
seed_name = managed.get("seed-volume") if managed is not None else None
if seed_name is None:
return None
if SEED_VOLUME_RE.fullmatch(seed_name or "") is None:
raise VMError("面板记录的 cloud-init 配置盘名称无效", 409)
pool = self._active_pool(conn, self.storage_pool)
volume = pool.storageVolLookupByName(seed_name)
volume_path = volume.path()
sources = [
source
for cdrom in root.findall("./devices/disk[@device='cdrom']")
for source in [cdrom.find("source")]
if source is not None
and ((source.get("pool") == pool.name()
and source.get("volume") == seed_name)
or source.get("file") == volume_path)
]
if len(sources) != 1:
raise VMError("cloud-init 配置盘已被修改,无法安全删除", 409)
source = sources[0]
if self._other_domain_uses_volume(conn, domain.UUIDString(),
pool.name(), seed_name, volume_path):
raise VMError("cloud-init 配置盘还被其他虚拟机使用", 409)
return volume
@staticmethod
def _undefine_domain(
domain: Any,
*,
remove_nvram: bool,
remove_managed_save: bool = False,
remove_snapshots_metadata: bool = False,
remove_checkpoints_metadata: bool = False,
) -> None:
"""Remove a domain and any explicitly requested libvirt metadata.
The panel's online snapshots are external ``panel-snap-*`` qcow2
volumes and are not affected by these flags. Native snapshot data is
rejected by the delete preflight when it is present; the metadata
flag remains enabled for stale metadata and for domains imported from
outside the panel.
"""
flags = 0
metadata_flags = (
("VIR_DOMAIN_UNDEFINE_MANAGED_SAVE", remove_managed_save),
("VIR_DOMAIN_UNDEFINE_SNAPSHOTS_METADATA",
remove_snapshots_metadata),
("VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA",
remove_checkpoints_metadata),
)
for flag_name, enabled in metadata_flags:
if not enabled:
continue
flag = getattr(libvirt, flag_name, 0)
if not flag:
raise VMError(
"当前 libvirt 绑定不支持安全清理虚拟机元数据",
502,
error_code="vm_undefine_metadata_unsupported",
)
flags |= flag
if remove_nvram:
nvram_flag = getattr(libvirt, "VIR_DOMAIN_UNDEFINE_NVRAM", 0)
if nvram_flag:
flags |= nvram_flag
else:
# Older bindings cannot request deletion; retain NVRAM so
# undefine still succeeds rather than leaving a partial VM.
flags |= getattr(libvirt, "VIR_DOMAIN_UNDEFINE_KEEP_NVRAM", 0)
else:
flags |= getattr(libvirt, "VIR_DOMAIN_UNDEFINE_KEEP_NVRAM", 0)
if flags:
domain.undefineFlags(flags)
else:
domain.undefine()
def delete_vm(self, uuid: str, delete_disks: bool) -> dict[str, Any]:
if not isinstance(delete_disks, bool):
raise VMError("delete_disks 必须是布尔值")
with self._connect() as conn:
domain = self._domain(conn, uuid)
if domain.isActive():
raise VMError("请先关闭虚拟机,再删除", 409)
if not domain.isPersistent():
raise VMError("无法删除临时虚拟机定义", 409)
# A managed-save image is part of the domain definition and can
# be removed atomically with ``undefineFlags``. Native snapshot
# metadata is different: the panel has no native snapshot
# cleanup API and cannot prove ownership of its external data, so
# fail closed before deleting a system disk or a definition-only
# VM. The metadata flags below still remove stale metadata when
# ``snapshotNum`` reports no live native snapshot.
managed_save_present = bool(
getattr(domain, "hasManagedSaveImage", lambda _flags: 0)(0)
)
try:
snapshot_count = int(
getattr(domain, "snapshotNum", lambda _flags: 0)(0)
)
except (TypeError, ValueError) as exc:
raise VMError(
"无法确认虚拟机原生快照状态,已停止删除",
502,
error_code="vm_native_snapshot_state_unknown",
) from exc
if snapshot_count < 0:
raise VMError(
"无法确认虚拟机原生快照状态,已停止删除",
502,
error_code="vm_native_snapshot_state_unknown",
)
if snapshot_count > 0:
raise VMError(
"虚拟机存在 libvirt 原生快照,请先处理原生快照后再删除",
409,
error_code="vm_native_snapshot_present",
)
if managed_save_present:
LOG.info("Removing managed-save image while deleting VM %s", uuid)
volume = self._owned_volume(conn, domain) if delete_disks else None
seed_volume = self._owned_seed_volume(conn, domain) if delete_disks else None
vm_uuid = domain.UUIDString()
managed = self._vm_xml(domain).find(f"./metadata/{{{PANEL_NS}}}managed")
self._undefine_domain(
domain, remove_nvram=(delete_disks and managed is not None
and managed.get("version") == "2"),
# Permanent VM deletion owns the domain metadata. Request
# all three flags even when the corresponding state is not
# visible in a preflight query so a race or stale metadata
# cannot make undefine fail after the commit boundary.
remove_managed_save=True,
remove_snapshots_metadata=True,
remove_checkpoints_metadata=True,
)
deleted_disks: list[str] = []
for removable in (seed_volume, volume):
if removable is None:
continue
# Never use WITH_SNAPSHOTS or zeroing flags here.
volume_name = ""
try:
volume_name = removable.name()
removable.delete(0)
except libvirt.libvirtError as exc:
LOG.exception("Domain %s undefined but volume %s remains", vm_uuid, volume_name)
# ``undefine`` has already crossed the destructive commit
# boundary. Let the engine persist the exact resource
# manifest and finish this volume (and later snapshots)
# through its idempotent cleanup operation instead of
# treating the whole delete as an uncommitted request.
raise VMError(
"虚拟机定义已删除,但磁盘删除失败;将继续核对并清理残留磁盘",
503,
error_code="vm_delete_volume_cleanup_pending",
) from exc
deleted_disks.append(volume_name)
return {"uuid": vm_uuid, "deleted": True, "deleted_disks": deleted_disks}
def delete_vm_cleanup_manifest(self, vm_id: str) -> dict[str, Any]:
"""Capture exact VM-owned volumes before a destructive delete.
The manifest is persisted by the engine before ``delete_vm`` runs. It
is intentionally limited to the current system disk and cloud-init
seed; snapshot volumes are captured from the panel catalog separately.
Libvirt managed-save, native snapshot metadata, and checkpoint
metadata are removed by the same ``undefineFlags`` commit and are not
treated as panel-owned storage resources here.
"""
vm_uuid = self._uuid(vm_id)
with self._connect() as conn:
domain = self._domain(conn, vm_uuid)
primary = self._owned_volume(conn, domain)
seed = self._owned_seed_volume(conn, domain)
return {
"vm_uuid": vm_uuid,
"primary_volume": primary.name(),
"seed_volume": seed.name() if seed is not None else None,
}
@staticmethod
def _validate_delete_cleanup_volume_name(
vm_uuid: str, name: Any, *, seed: bool,
) -> str:
if name is None and not seed:
raise VMError("删除检查点缺少当前系统盘身份", 409)
if name is None:
return ""
if not isinstance(name, str) or "/" in name:
raise VMError("删除检查点中的磁盘身份无效", 409)
if seed:
if SEED_VOLUME_RE.fullmatch(name) is None:
raise VMError("删除检查点中的配置盘身份不一致", 409)
elif (not name.endswith(".qcow2")
or not NAME_RE.fullmatch(name.removesuffix(".qcow2"))):
raise VMError("删除检查点中的系统盘身份无效", 409)
return name
@staticmethod
def _storage_volume_missing(exc: BaseException) -> bool:
get_error_code = getattr(exc, "get_error_code", None)
missing_code = getattr(libvirt, "VIR_ERR_NO_STORAGE_VOL", None)
if callable(get_error_code) and missing_code is not None:
try:
return get_error_code() == missing_code
except Exception: # pragma: no cover - defensive for adapters
pass
message = str(exc).casefold()
return bool(
"no matching storage volume" in message
or "storage volume" in message and "not found" in message
or "存储卷" in message and "不存在" in message
)
def cleanup_deleted_vm_volumes(
self, vm_id: str, resources: dict[str, Any],
) -> dict[str, Any]:
"""Idempotently remove the exact disks captured before VM deletion."""
vm_uuid = self._uuid(vm_id)
if not isinstance(resources, dict):
raise VMError("删除检查点中的磁盘清单无效", 409)
seed_name = self._validate_delete_cleanup_volume_name(
vm_uuid, resources.get("seed_volume"), seed=True)
primary_name = self._validate_delete_cleanup_volume_name(
vm_uuid, resources.get("primary_volume"), seed=False)
with self._connect() as conn:
try:
self._domain(conn, vm_uuid)
except VMError as exc:
if exc.status != 404:
raise
else:
raise VMError("虚拟机定义仍存在,暂不能清理删除资源", 409)
pool = self._active_pool(conn, self.storage_pool)
deleted: list[str] = []
for name in (seed_name, primary_name):
if not name:
continue
self._refresh_directory_pool(pool)
if name not in set(pool.listVolumes()):
continue
try:
volume = pool.storageVolLookupByName(name)
except libvirt.libvirtError as exc:
if self._storage_volume_missing(exc):
continue
raise
if self._other_domain_uses_volume(
conn, vm_uuid, pool.name(), name, volume.path()):
raise VMError("删除磁盘仍被其他虚拟机引用,已停止清理", 409)
try:
volume.delete(0)
except libvirt.libvirtError as exc:
raise VMError(
"删除残留磁盘失败,稍后将继续核对", 503,
error_code="vm_delete_volume_cleanup_pending",
) from exc
deleted.append(name)
return {"deleted": deleted, "already_absent": len(deleted) == 0}
def console_port(self, uuid: str) -> int:
with self._connect() as conn:
domain = self._domain(conn, uuid)
if not domain.isActive():
raise VMError("请先启动虚拟机,再打开 VNC 控制台", 409)
port = self._vnc_port(self._vm_xml(domain))
if port is None:
raise VMError("虚拟机没有可用的 VNC 控制台", 409)
return port