feat: add network topology page
Some checks failed
Backend Tests / pytest (Python 3.12) (push) Failing after 1m22s
Deploy to Production / Trigger production update (push) Failing after 10s
SonarCloud / SonarCloud Analysis (push) Failing after 2m22s

Interactive infrastructure map (panel -> cluster -> node -> guest) rendered
with React Flow, backed by a single aggregated /api/network/topology endpoint
instead of fanning out over servers/nodes/SDN/VMs. Adds a netN NIC parser for
QEMU/LXC guest configs, status/threshold filters, canvas tools, and PNG/SVG
export.
This commit is contained in:
markmorado
2026-08-20 01:31:37 +05:00
parent f6d9932849
commit d99e67a60e
30 changed files with 2450 additions and 5 deletions

View File

@@ -4,6 +4,18 @@ All notable changes to PVEmanager will be documented in this file.
---
## [Unreleased]
### ✨ Network topology page
- **New `/topology` page** — an interactive map of the infrastructure: panel → cluster → Proxmox node → VM/LXC, rendered with React Flow. Node cards carry live CPU/RAM meters, guests show status, IP, bridge/VLAN and tags
- **Filters** — narrow the graph to one connection, filter guests by status (all / running / stopped), and collapse a node's guests into a single badge above a configurable threshold (remembered per browser); expand a collapsed node individually
- **Canvas tools** — zoom, pan, fit-to-screen, fullscreen, minimap, legend and PNG/SVG export of the whole graph
- **New API `GET /proxmox/api/network/topology`** — one aggregated request instead of fanning out over servers/nodes/SDN/VMs; gated on `network:view`, honours workspace scoping and per-owner VM isolation. Unreachable connections degrade to cached data plus a warning instead of failing the page
- **`netN` parser** — guest NIC strings are now parsed (bridge, VLAN tag, MAC, model, firewall, rate, MTU) for both the QEMU and LXC dialects, available via `include_nics=true`
---
## [v1.16.1] - 2026-08-17
### 🎨 UI

View File

@@ -4,6 +4,18 @@
---
## [Не выпущено]
### ✨ Страница «Топология сети»
- **Новая страница `/topology`** — интерактивная карта инфраструктуры: панель → кластер → нода Proxmox → VM/LXC на базе React Flow. На карточках нод — живые индикаторы CPU/RAM, у гостей видны статус, IP, bridge/VLAN и теги
- **Фильтры** — сужение графа до одного подключения, фильтр гостей по статусу (все / запущенные / остановленные) и схлопывание гостей ноды в один узел при превышении настраиваемого порога (запоминается в браузере); свернувшуюся ноду можно раскрыть по отдельности
- **Инструменты холста** — зум, панорама, вписать в экран, полноэкранный режим, миникарта, легенда и экспорт всего графа в PNG/SVG
- **Новый API `GET /proxmox/api/network/topology`** — один агрегированный запрос вместо обхода серверов/нод/SDN/VM; требует право `network:view`, учитывает рабочие области и изоляцию VM по владельцу. Недоступное подключение отдаёт данные из кэша с предупреждением, а не ломает страницу
- **Парсер `netN`** — строки сетевых карт гостей теперь разбираются (bridge, VLAN-тег, MAC, модель, firewall, rate, MTU) для обоих диалектов, QEMU и LXC; доступно через `include_nics=true`
---
## [v1.16.1] - 2026-08-17
### 🎨 Интерфейс

View File

@@ -15,6 +15,7 @@ from .pools import router as pools_router
from .disks import router as disks_router
from .access import router as access_router
from .node_admin import router as node_admin_router
from .topology import router as topology_router
from ._helpers import get_next_vmid, save_vm_instance, get_vm_instance
router = APIRouter()
@@ -34,3 +35,4 @@ router.include_router(pools_router)
router.include_router(disks_router)
router.include_router(access_router)
router.include_router(node_admin_router)
router.include_router(topology_router)

View File

@@ -0,0 +1,486 @@
"""Aggregated network topology: panel -> cluster -> node -> guest.
One endpoint feeds the whole /topology page so the frontend makes a single
request instead of fanning out over servers/nodes/sdn/vms. Everything the graph
draws - plus the bridge/VLAN/MAC data the planned "group by VLAN" view will
need - is collected here.
Kept separate from ``cluster.py``'s ``/api/cluster/topology``, which answers a
different question (which servers form which cluster) and is consumed by the
Cluster page.
"""
import asyncio
import threading
import time as time_lib
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime, timezone
from typing import Any, Dict, List, Optional, Tuple
from fastapi import APIRouter, Depends, HTTPException, Query, Request
from loguru import logger
from sqlalchemy.orm import Session, joinedload
from ...auth import PermissionChecker
from ...db import get_db
from ...models import IPAMAllocation, IPAMNetwork, ProxmoxServer, User, VMInstance
from ...proxmox import _run_in_executor, parse_guest_nics
from ...schemas import (NetworkTopologyResponse, TopologyBridge, TopologyCluster,
TopologyGuest, TopologyNic, TopologyNode,
TopologyPanelSummary, TopologyWarning)
from ._helpers import _get_proxmox_client, can_view_all_instances, get_visible_server_ids
router = APIRouter()
# Live cluster/resources + node networks, keyed by server id. Short TTL: the
# page auto-refreshes every 30s and several users may watch it at once.
_topo_cache: Dict[int, Dict[str, Any]] = {}
_topo_lock = threading.Lock()
TOPO_TTL = 15
# Guest configs change rarely, and reading them costs one HTTP call per guest.
_nic_cache: Dict[Tuple[int, int], Dict[str, Any]] = {}
_nic_lock = threading.Lock()
NIC_TTL = 300
NIC_MAX_WORKERS = 8
NIC_MAX_FETCHES = 300 # hard ceiling so a huge cluster cannot hang the request
def _truthy(value: Any) -> bool:
"""Proxmox returns flags as 1/0, "1"/"0" or bools depending on the field."""
return str(value).strip().lower() in ("1", "true", "yes", "on")
# ==================== Live collection (runs off the request thread) ====================
def _collect_server(server: ProxmoxServer, include_bridges: bool) -> Dict[str, Any]:
"""Everything one Proxmox connection can tell us, in as few calls as possible."""
client = _get_proxmox_client(server)
# A single /cluster/resources call carries both node and guest metrics.
resources = client.get_cluster_resources() or []
nodes = [r for r in resources if r.get("type") == "node"]
guests = [r for r in resources if r.get("type") in ("qemu", "lxc")]
bridges: Dict[str, List[Dict[str, Any]]] = {}
if include_bridges:
# Zones/vnets are cluster-wide; fetch once and filter per node below.
try:
zones = {z.get("zone"): z for z in (client.get_sdn_zones() or [])}
vnets = client.get_sdn_vnets() or []
except Exception as exc: # SDN is optional and older PVE lacks it
logger.debug(f"SDN unavailable on {server.name}: {exc}")
zones, vnets = {}, []
for node_res in nodes:
node_name = node_res.get("node")
if not node_name:
continue
entries: List[Dict[str, Any]] = []
try:
for iface in client.get_node_networks(node_name) or []:
name = iface.get("iface") or iface.get("name")
if not name:
continue
cidr = iface.get("cidr")
if not cidr and iface.get("address") and iface.get("netmask"):
cidr = "{0}/{1}".format(iface["address"], iface["netmask"])
entries.append({
"name": name,
"type": iface.get("type"),
"cidr": cidr,
"vlan_aware": _truthy(iface.get("bridge_vlan_aware")),
"ports": iface.get("bridge_ports") or iface.get("slaves"),
"active": _truthy(iface.get("active")),
})
except Exception as exc:
logger.debug(f"Could not read networks of {server.name}/{node_name}: {exc}")
# SDN vnets are attachable as bridges but never appear in /network.
for vnet in vnets:
vnet_name = vnet.get("vnet")
if not vnet_name:
continue
zone_name = vnet.get("zone", "")
zone_nodes = (zones.get(zone_name, {}).get("nodes") or "").replace(" ", "")
if zone_nodes and node_name not in zone_nodes.split(","):
continue
entries.append({
"name": vnet_name,
"type": "vnet",
"zone": zone_name,
"active": True,
})
bridges[node_name] = entries
return {"nodes": nodes, "guests": guests, "bridges": bridges}
def _fetch_nics(server: ProxmoxServer, targets: List[Tuple[str, int, str]]) -> Dict[int, List[Dict[str, Any]]]:
"""``netN`` cards for the given guests. ``targets`` = [(node, vmid, type)]."""
if not targets:
return {}
client = _get_proxmox_client(server)
def _one(node: str, vmid: int, vm_type: str) -> Tuple[int, List[Dict[str, Any]]]:
getter = client.get_vm_config if vm_type == "qemu" else client.get_container_config
config = getter(node, vmid) or {}
return vmid, [nic.to_dict() for nic in parse_guest_nics(config)]
result: Dict[int, List[Dict[str, Any]]] = {}
with ThreadPoolExecutor(max_workers=min(NIC_MAX_WORKERS, len(targets))) as pool:
futures = [pool.submit(_one, *target) for target in targets]
for future in as_completed(futures):
try:
vmid, nics = future.result()
except Exception as exc:
logger.debug(f"Could not read guest config on {server.name}: {exc}")
continue
result[vmid] = nics
return result
# ==================== Helpers ====================
def _split_tags(raw: Optional[str]) -> List[str]:
"""Proxmox stores tags as a ``;``-separated string; the graph wants a list."""
if not raw:
return []
return [t.strip() for t in str(raw).replace(",", ";").split(";") if t.strip()]
def _to_int(value: Any) -> Optional[int]:
try:
return int(value)
except (TypeError, ValueError):
return None
def _to_float(value: Any) -> Optional[float]:
try:
return float(value)
except (TypeError, ValueError):
return None
def _empty_response() -> NetworkTopologyResponse:
return NetworkTopologyResponse(
generated_at=datetime.now(timezone.utc),
panel=TopologyPanelSummary(),
clusters=[],
warnings=[],
)
# ==================== Endpoint ====================
@router.get("/api/network/topology", response_model=NetworkTopologyResponse)
async def get_network_topology(
request: Request,
server_id: Optional[int] = Query(None, description="Limit to a single connection"),
include_stopped: bool = Query(True),
include_templates: bool = Query(False),
include_bridges: bool = Query(True),
include_nics: bool = Query(False, description="Read every guest config for bridge/VLAN/MAC - one call per guest"),
db: Session = Depends(get_db),
current_user: User = Depends(PermissionChecker("network:view")),
):
"""Infrastructure tree for the topology page.
Always answers 200 (bar a permission denial): an unreachable server
degrades to cached rows plus a warning rather than failing the page.
"""
warnings: List[TopologyWarning] = []
# -- Visibility ----------------------------------------------------------
# None means "no restriction" and is NOT the same as an empty set.
visible_ids = get_visible_server_ids(request, db, current_user)
if visible_ids is not None and not visible_ids:
return _empty_response()
servers_q = db.query(ProxmoxServer)
if visible_ids is not None:
servers_q = servers_q.filter(ProxmoxServer.id.in_(visible_ids))
if server_id is not None:
if visible_ids is not None and server_id not in visible_ids:
# 404 rather than 403 so the response cannot confirm the server exists.
raise HTTPException(status_code=404, detail="Proxmox server not found")
servers_q = servers_q.filter(ProxmoxServer.id == server_id)
servers = servers_q.order_by(ProxmoxServer.name).all()
if not servers:
return _empty_response()
server_map = {s.id: s for s in servers}
# -- Ownership: live Proxmox data carries no owner, the DB does ----------
see_all = can_view_all_instances(current_user)
db_q = (
db.query(VMInstance)
.options(joinedload(VMInstance.owner))
.filter(VMInstance.deleted_at.is_(None), VMInstance.server_id.in_(server_map.keys()))
)
if not see_all:
db_q = db_q.filter(VMInstance.owner_id == current_user.id)
db_guests = db_q.all()
db_by_key: Dict[Tuple[int, int], VMInstance] = {(g.server_id, g.vmid): g for g in db_guests}
# Pair-scoped, not vmid-scoped: the same vmid on two servers is two guests.
owned_keys = set(db_by_key.keys())
# -- IP addresses from IPAM, falling back to the cached instance row ------
ipam_by_key: Dict[Tuple[int, int], str] = {}
for alloc in (
db.query(IPAMAllocation)
.filter(IPAMAllocation.status.in_(["allocated", "reserved"]))
.all()
):
if alloc.proxmox_server_id and alloc.proxmox_vmid and alloc.ip_address:
ipam_by_key[(alloc.proxmox_server_id, alloc.proxmox_vmid)] = alloc.ip_address
ipam_nets = db.query(IPAMNetwork).filter(
IPAMNetwork.proxmox_server_id.in_(server_map.keys())
).all()
ipam_by_bridge: Dict[Tuple[int, str], IPAMNetwork] = {
(n.proxmox_server_id, n.proxmox_bridge): n for n in ipam_nets if n.proxmox_bridge
}
# -- Live data, in parallel: one dead cluster must not stall the rest -----
live: Dict[int, Dict[str, Any]] = {}
stale_servers: List[ProxmoxServer] = []
now = time_lib.time()
with _topo_lock: # guards the dict only, never a network call
for server in servers:
cached = _topo_cache.get(server.id)
if cached and (now - cached["time"]) < TOPO_TTL:
live[server.id] = cached["data"]
elif server.is_online is False:
# Offline servers contribute nothing but a connection timeout.
continue
else:
stale_servers.append(server)
if stale_servers:
tasks = [_run_in_executor(_collect_server, s, include_bridges) for s in stale_servers]
results = await asyncio.gather(*tasks, return_exceptions=True)
for server, result in zip(stale_servers, results):
if isinstance(result, HTTPException):
warnings.append(TopologyWarning(
server_id=server.id, server_name=server.name,
code="no_credentials", message=str(result.detail),
))
continue
if isinstance(result, BaseException):
logger.warning(f"Topology collection failed for {server.name}: {result}")
warnings.append(TopologyWarning(
server_id=server.id, server_name=server.name,
code="error", message=str(result),
))
continue
live[server.id] = result
with _topo_lock:
_topo_cache[server.id] = {"time": time_lib.time(), "data": result}
for server in servers:
if server.id not in live and not any(w.server_id == server.id for w in warnings):
warnings.append(TopologyWarning(
server_id=server.id, server_name=server.name,
code="offline", message=f"'{server.name}' is unreachable - showing cached data",
))
# -- NICs (opt-in): bridge / VLAN / MAC straight from the guest configs ---
nics_by_key: Dict[Tuple[int, int], List[Dict[str, Any]]] = {}
if include_nics:
pending: Dict[int, List[Tuple[str, int, str]]] = {}
budget = NIC_MAX_FETCHES
truncated = False
now = time_lib.time()
for sid, data in live.items():
for guest in data["guests"]:
vmid = _to_int(guest.get("vmid"))
node = guest.get("node")
if vmid is None or not node:
continue
if not see_all and (sid, vmid) not in owned_keys:
continue
with _nic_lock:
cached = _nic_cache.get((sid, vmid))
if cached and (now - cached["time"]) < NIC_TTL:
nics_by_key[(sid, vmid)] = cached["data"]
continue
if budget <= 0:
truncated = True
continue
budget -= 1
pending.setdefault(sid, []).append((node, vmid, guest.get("type", "qemu")))
if truncated:
warnings.append(TopologyWarning(
code="nics_truncated",
message=f"Network card details limited to {NIC_MAX_FETCHES} guests per request",
))
if pending:
server_ids = list(pending.keys())
tasks = [_run_in_executor(_fetch_nics, server_map[sid], pending[sid]) for sid in server_ids]
results = await asyncio.gather(*tasks, return_exceptions=True)
stamp = time_lib.time()
for sid, result in zip(server_ids, results):
if isinstance(result, BaseException):
logger.debug(f"NIC collection failed for server {sid}: {result}")
continue
for vmid, nics in result.items():
nics_by_key[(sid, vmid)] = nics
with _nic_lock:
_nic_cache[(sid, vmid)] = {"time": stamp, "data": nics}
# -- Assemble ------------------------------------------------------------
def _build_guest(sid: int, node_name: str, res: Optional[Dict[str, Any]],
row: Optional[VMInstance]) -> Optional[TopologyGuest]:
res = res or {}
vmid = _to_int(res.get("vmid"))
if vmid is None and row is not None:
vmid = row.vmid
if vmid is None:
return None
vm_type = res.get("type") or (row.vm_type if row else None) or "qemu"
is_template = _truthy(res.get("template")) or bool(row and row.is_template)
if is_template and not include_templates:
return None
status = res.get("status") or (row.status if row else None) or "unknown"
if not include_stopped and status != "running":
return None
tags = _split_tags(res.get("tags")) or _split_tags(row.tags if row else None)
name = res.get("name") or (row.name if row else None) or f"vm-{vmid}"
return TopologyGuest(
id=f"guest:{sid}:{vmid}",
server_id=sid,
node=node_name,
vmid=vmid,
type=vm_type,
name=name,
status=status,
is_template=is_template,
lock=res.get("lock"),
cpu=_to_float(res.get("cpu")),
cores=_to_int(res.get("maxcpu")) or (row.cores if row else None),
mem=_to_int(res.get("mem")),
maxmem=_to_int(res.get("maxmem")) or (row.memory if row else None),
disk=_to_int(res.get("disk")),
maxdisk=_to_int(res.get("maxdisk")),
uptime=_to_int(res.get("uptime")),
tags=tags,
owner_id=row.owner_id if row else None,
owner_username=(row.owner.username if row and row.owner else None),
ip=ipam_by_key.get((sid, vmid)) or (row.ip_address if row else None),
nics=[
TopologyNic(**{k: v for k, v in nic.items() if k in TopologyNic.model_fields})
for nic in nics_by_key.get((sid, vmid), [])
],
)
# cluster_name groups connections; a server without one stands alone.
cluster_buckets: Dict[str, Dict[str, Any]] = {}
for server in servers:
key = f"cluster:{server.cluster_name}" if server.cluster_name else f"cluster:server:{server.id}"
bucket = cluster_buckets.setdefault(key, {
"id": key,
"name": server.cluster_name or server.name,
"kind": "cluster" if server.cluster_name else "standalone",
"server_ids": [],
"online": False,
"nodes": {}, # node name -> TopologyNode, deduplicated per cluster
})
bucket["server_ids"].append(server.id)
if server.id in live:
bucket["online"] = True
data = live.get(server.id)
if data is None:
# Rebuild from the 10s VM cache so an offline server still shows up.
by_node: Dict[str, List[VMInstance]] = {}
for row in db_guests:
if row.server_id != server.id:
continue
by_node.setdefault(row.node or server.name, []).append(row)
for node_name, node_rows in by_node.items():
if node_name in bucket["nodes"]:
continue
guests = [g for g in (_build_guest(server.id, node_name, None, r) for r in node_rows) if g]
guests.sort(key=lambda g: g.vmid)
bucket["nodes"][node_name] = TopologyNode(
id=f"node:{server.id}:{node_name}",
server_id=server.id, server_name=server.name, node=node_name,
status="unknown", stale=True, guests=guests,
)
continue
guests_by_node: Dict[str, List[Dict[str, Any]]] = {}
for res in data["guests"]:
node_name = res.get("node")
vmid = _to_int(res.get("vmid"))
if not node_name or vmid is None:
continue
if not see_all and (server.id, vmid) not in owned_keys:
continue
guests_by_node.setdefault(node_name, []).append(res)
for node_res in data["nodes"]:
node_name = node_res.get("node")
if not node_name or node_name in bucket["nodes"]:
continue # same PVE cluster reachable through two connections
bridges = []
for entry in data["bridges"].get(node_name, []):
ipam_net = ipam_by_bridge.get((server.id, entry["name"]))
bridges.append(TopologyBridge(
**entry,
ipam_network_id=ipam_net.id if ipam_net else None,
ipam_cidr=ipam_net.network if ipam_net else None,
ipam_name=ipam_net.name if ipam_net else None,
))
guests = [
g for g in (
_build_guest(server.id, node_name, res,
db_by_key.get((server.id, _to_int(res.get("vmid")))))
for res in guests_by_node.get(node_name, [])
) if g
]
guests.sort(key=lambda g: g.vmid)
bucket["nodes"][node_name] = TopologyNode(
id=f"node:{server.id}:{node_name}",
server_id=server.id,
server_name=server.name,
node=node_name,
status=node_res.get("status") or "unknown",
stale=False,
cpu=_to_float(node_res.get("cpu")),
maxcpu=_to_int(node_res.get("maxcpu")),
mem=_to_int(node_res.get("mem")),
maxmem=_to_int(node_res.get("maxmem")),
uptime=_to_int(node_res.get("uptime")),
bridges=bridges,
guests=guests,
)
clusters = [
TopologyCluster(
id=b["id"], name=b["name"], kind=b["kind"],
server_ids=b["server_ids"], online=b["online"],
nodes=sorted(b["nodes"].values(), key=lambda n: n.node),
)
for b in cluster_buckets.values()
]
clusters.sort(key=lambda c: (c.kind != "cluster", c.name.lower()))
node_count = sum(len(c.nodes) for c in clusters)
guest_count = sum(len(n.guests) for c in clusters for n in c.nodes)
return NetworkTopologyResponse(
generated_at=datetime.now(timezone.utc),
panel=TopologyPanelSummary(
cluster_count=len(clusters), node_count=node_count, guest_count=guest_count,
),
clusters=clusters,
warnings=warnings,
)

View File

@@ -1,9 +1,13 @@
from .client import ProxmoxClient, get_proxmox_resources, _run_in_executor, clear_all_cache, clear_server_cache
from .net_parser import ParsedNic, parse_net_string, parse_guest_nics
__all__ = [
'ProxmoxClient',
'get_proxmox_resources',
'_run_in_executor',
'clear_all_cache',
'clear_server_cache'
'clear_server_cache',
'ParsedNic',
'parse_net_string',
'parse_guest_nics',
]

View File

@@ -0,0 +1,139 @@
"""Parser for Proxmox ``netN`` guest NIC strings.
Proxmox stores every guest network card as one comma-separated key=value
string in the guest config (``net0``, ``net1``, …). Two dialects exist:
* QEMU — ``virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=100,firewall=1``
The NIC model is itself the key holding the MAC address.
* LXC — ``name=eth0,bridge=vmbr0,hwaddr=AA:BB:CC:DD:EE:FF,ip=10.0.0.5/24,``
``gw=10.0.0.1,type=veth,firewall=1``
The repository only ever *builds* these strings (``api/proxmox/lxc.py``,
``proxmox/mixins/vm.py``); this module reads them back so callers can learn
which bridge/VLAN a guest actually sits on.
Deliberately free of any ``proxmoxer`` import so both the API layer and the
client mixins can use it. Parsing never raises: an unparsable token is skipped
rather than failing the whole request.
"""
from dataclasses import dataclass, field, asdict
from typing import Any, Dict, List, Optional
import re
# NIC models QEMU accepts. The model name doubles as the key carrying the MAC,
# which is the only way to tell "virtio=AA:.." from an ordinary option.
QEMU_MODELS = {
"virtio", "e1000", "e1000e", "e1000-82540em", "e1000-82544gc",
"e1000-82545em", "rtl8139", "vmxnet3", "ne2k_pci", "ne2k_isa",
"pcnet", "i82551", "i82557b", "i82559er",
}
_NET_KEY_RE = re.compile(r"^net(\d+)$")
@dataclass
class ParsedNic:
"""One guest network interface, normalised across the QEMU/LXC dialects."""
key: str # "net0"
index: int # 0
model: Optional[str] = None # virtio / e1000 / … (QEMU only)
mac: Optional[str] = None # uppercase, from model= or hwaddr=
bridge: Optional[str] = None # vmbr0 or an SDN vnet
vlan_tag: Optional[int] = None
trunks: List[int] = field(default_factory=list)
firewall: bool = False
link_down: bool = False
name: Optional[str] = None # LXC: name=eth0
ip: Optional[str] = None # LXC: "10.0.0.5/24" or "dhcp"
ip6: Optional[str] = None
gw: Optional[str] = None
gw6: Optional[str] = None
rate: Optional[float] = None # MB/s
mtu: Optional[int] = None
queues: Optional[int] = None
raw: str = ""
def to_dict(self) -> Dict[str, Any]:
return asdict(self)
def _as_int(value: str) -> Optional[int]:
try:
return int(value)
except (TypeError, ValueError):
return None
def _as_float(value: str) -> Optional[float]:
try:
return float(value)
except (TypeError, ValueError):
return None
def _as_bool(value: str) -> bool:
return str(value).strip().lower() in ("1", "true", "yes", "on")
def parse_net_string(key: str, value: str) -> ParsedNic:
"""Parse a single ``netN`` value. Never raises."""
match = _NET_KEY_RE.match(key or "")
nic = ParsedNic(key=key or "", index=int(match.group(1)) if match else 0, raw=value or "")
for token in (value or "").split(","):
token = token.strip()
if not token or "=" not in token:
# Bare tokens (rare, e.g. a stray flag) carry nothing we need.
continue
opt, _, raw_val = token.partition("=")
opt = opt.strip().lower()
raw_val = raw_val.strip()
if opt in QEMU_MODELS:
nic.model = opt
nic.mac = raw_val.upper() or None
elif opt == "hwaddr":
nic.mac = raw_val.upper() or None
elif opt == "bridge":
nic.bridge = raw_val or None
elif opt == "tag":
nic.vlan_tag = _as_int(raw_val)
elif opt == "trunks":
nic.trunks = [v for v in (_as_int(p) for p in raw_val.split(";")) if v is not None]
elif opt == "firewall":
nic.firewall = _as_bool(raw_val)
elif opt == "link_down":
nic.link_down = _as_bool(raw_val)
elif opt == "name":
nic.name = raw_val or None
elif opt == "ip":
nic.ip = raw_val or None
elif opt == "ip6":
nic.ip6 = raw_val or None
elif opt == "gw":
nic.gw = raw_val or None
elif opt == "gw6":
nic.gw6 = raw_val or None
elif opt == "rate":
nic.rate = _as_float(raw_val)
elif opt == "mtu":
nic.mtu = _as_int(raw_val)
elif opt == "queues":
nic.queues = _as_int(raw_val)
return nic
def parse_guest_nics(config: Dict[str, Any]) -> List[ParsedNic]:
"""Every ``netN`` entry of a QEMU/LXC config, ordered by interface index."""
nics: List[ParsedNic] = []
for key, value in (config or {}).items():
if not isinstance(key, str) or not _NET_KEY_RE.match(key):
continue
if not isinstance(value, str):
continue
nics.append(parse_net_string(key, value))
nics.sort(key=lambda n: n.index)
return nics

View File

@@ -861,3 +861,115 @@ class WorkspaceResponse(BaseModel):
class WorkspaceDetail(WorkspaceResponse):
servers: List[WorkspaceServerItem] = []
users: List[WorkspaceUserItem] = []
# ==================== Network topology ====================
# Response shape for GET /proxmox/api/network/topology. Deliberately a domain
# hierarchy (panel → cluster → node → guest) rather than ready-made graph
# nodes/edges: the frontend derives edges from nesting, and the grouping
# threshold changes the rendered node count client-side without a round-trip.
# Fields the graph does not draw yet (bridges, nic.bridge/vlan_tag, tags) are
# the groundwork for the planned "group by VLAN / by tag" views.
class TopologyNic(BaseModel):
"""One guest network card, parsed out of its ``netN`` config string."""
key: str
model: Optional[str] = None
mac: Optional[str] = None
bridge: Optional[str] = None
vlan_tag: Optional[int] = None
trunks: List[int] = []
firewall: bool = False
link_down: bool = False
name: Optional[str] = None
ip: Optional[str] = None
gw: Optional[str] = None
rate: Optional[float] = None
mtu: Optional[int] = None
class TopologyBridge(BaseModel):
"""A bridge / bond / SDN vnet a guest can be attached to."""
name: str
type: Optional[str] = None
cidr: Optional[str] = None
vlan_aware: bool = False
ports: Optional[str] = None
active: bool = False
zone: Optional[str] = None
ipam_network_id: Optional[int] = None
ipam_cidr: Optional[str] = None
ipam_name: Optional[str] = None
class TopologyGuest(BaseModel):
id: str
server_id: int
node: str
vmid: int
type: str # "qemu" | "lxc"
name: str
status: str # running | stopped | paused | unknown
is_template: bool = False
lock: Optional[str] = None
cpu: Optional[float] = None
cores: Optional[int] = None
mem: Optional[int] = None
maxmem: Optional[int] = None
disk: Optional[int] = None
maxdisk: Optional[int] = None
uptime: Optional[int] = None
tags: List[str] = []
owner_id: Optional[int] = None
owner_username: Optional[str] = None
ip: Optional[str] = None
nics: List[TopologyNic] = []
class TopologyNode(BaseModel):
id: str
server_id: int
server_name: str
node: str
status: str # online | offline | unknown
stale: bool = False # True → rebuilt from cache, server unreachable
cpu: Optional[float] = None
maxcpu: Optional[int] = None
mem: Optional[int] = None
maxmem: Optional[int] = None
uptime: Optional[int] = None
bridges: List[TopologyBridge] = []
guests: List[TopologyGuest] = []
class TopologyCluster(BaseModel):
id: str
name: str
kind: str # "cluster" | "standalone"
server_ids: List[int] = []
online: bool = False
nodes: List[TopologyNode] = []
class TopologyWarning(BaseModel):
server_id: Optional[int] = None
server_name: Optional[str] = None
code: str # offline | no_credentials | error | nics_truncated
message: str
class TopologyPanelSummary(BaseModel):
name: str = "PVEmanager"
cluster_count: int = 0
node_count: int = 0
guest_count: int = 0
class NetworkTopologyResponse(BaseModel):
generated_at: datetime
panel: TopologyPanelSummary
clusters: List[TopologyCluster] = []
warnings: List[TopologyWarning] = []

View File

@@ -18,8 +18,10 @@
"@xterm/addon-fit": "^0.11.0",
"@xterm/addon-web-links": "^0.12.0",
"@xterm/xterm": "^6.0.0",
"@xyflow/react": "^12.8.0",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"html-to-image": "^1.11.13",
"i18next": "^26.0.3",
"i18next-browser-languagedetector": "^8.2.1",
"lucide-react": "^1.7.0",
@@ -2033,6 +2035,15 @@
"integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
"license": "MIT"
},
"node_modules/@types/d3-drag": {
"version": "3.0.7",
"resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
"integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
"license": "MIT",
"dependencies": {
"@types/d3-selection": "*"
}
},
"node_modules/@types/d3-ease": {
"version": "3.0.2",
"resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
@@ -2063,6 +2074,12 @@
"@types/d3-time": "*"
}
},
"node_modules/@types/d3-selection": {
"version": "3.0.11",
"resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.11.tgz",
"integrity": "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==",
"license": "MIT"
},
"node_modules/@types/d3-shape": {
"version": "3.1.8",
"resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.8.tgz",
@@ -2084,6 +2101,25 @@
"integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
"license": "MIT"
},
"node_modules/@types/d3-transition": {
"version": "3.0.9",
"resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
"integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
"license": "MIT",
"dependencies": {
"@types/d3-selection": "*"
}
},
"node_modules/@types/d3-zoom": {
"version": "3.0.8",
"resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.8.tgz",
"integrity": "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==",
"license": "MIT",
"dependencies": {
"@types/d3-interpolate": "*",
"@types/d3-selection": "*"
}
},
"node_modules/@types/debug": {
"version": "4.1.13",
"resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz",
@@ -2162,7 +2198,7 @@
"version": "19.2.3",
"resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.3.tgz",
"integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
"dev": true,
"devOptional": true,
"license": "MIT",
"peerDependencies": {
"@types/react": "^19.2.0"
@@ -2540,6 +2576,76 @@
"addons/*"
]
},
"node_modules/@xyflow/react": {
"version": "12.11.3",
"resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.11.3.tgz",
"integrity": "sha512-G3jogHz2GWUtIOkhavUGno2YzY9u6fILIJBttfsBendb0/HWB90JG+sOTAvlIMEwyvq9zgy9V9ZQSwyQjR5QzQ==",
"license": "MIT",
"dependencies": {
"@xyflow/system": "0.0.80",
"classcat": "^5.0.3",
"zustand": "^4.4.0"
},
"peerDependencies": {
"@types/react": ">=17",
"@types/react-dom": ">=17",
"react": ">=17",
"react-dom": ">=17"
},
"peerDependenciesMeta": {
"@types/react": {
"optional": true
},
"@types/react-dom": {
"optional": true
}
}
},
"node_modules/@xyflow/react/node_modules/zustand": {
"version": "4.5.7",
"resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
"integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
"license": "MIT",
"dependencies": {
"use-sync-external-store": "^1.2.2"
},
"engines": {
"node": ">=12.7.0"
},
"peerDependencies": {
"@types/react": ">=16.8",
"immer": ">=9.0.6",
"react": ">=16.8"
},
"peerDependenciesMeta": {
"@types/react": {
"optional": true
},
"immer": {
"optional": true
},
"react": {
"optional": true
}
}
},
"node_modules/@xyflow/system": {
"version": "0.0.80",
"resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.80.tgz",
"integrity": "sha512-ywc3ZqG91brzWrH1WlwMdIX4goOfrpBy6AbLdVSaof/Xx9l138ijIKRExM6EkMro2F+OImGmSiA/WKcXvKVcfA==",
"license": "MIT",
"dependencies": {
"@types/d3-drag": "^3.0.7",
"@types/d3-interpolate": "^3.0.4",
"@types/d3-selection": "^3.0.10",
"@types/d3-transition": "^3.0.8",
"@types/d3-zoom": "^3.0.8",
"d3-drag": "^3.0.0",
"d3-interpolate": "^3.0.1",
"d3-selection": "^3.0.0",
"d3-zoom": "^3.0.0"
}
},
"node_modules/accepts": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -2956,6 +3062,12 @@
"url": "https://polar.sh/cva"
}
},
"node_modules/classcat": {
"version": "5.0.5",
"resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz",
"integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
"license": "MIT"
},
"node_modules/cli-cursor": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz",
@@ -3269,6 +3381,28 @@
"node": ">=12"
}
},
"node_modules/d3-dispatch": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
"integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
"license": "ISC",
"engines": {
"node": ">=12"
}
},
"node_modules/d3-drag": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
"integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
"license": "ISC",
"dependencies": {
"d3-dispatch": "1 - 3",
"d3-selection": "3"
},
"engines": {
"node": ">=12"
}
},
"node_modules/d3-ease": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
@@ -3324,6 +3458,15 @@
"node": ">=12"
}
},
"node_modules/d3-selection": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
"integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
"license": "ISC",
"engines": {
"node": ">=12"
}
},
"node_modules/d3-shape": {
"version": "3.2.0",
"resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
@@ -3369,6 +3512,41 @@
"node": ">=12"
}
},
"node_modules/d3-transition": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
"integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
"license": "ISC",
"dependencies": {
"d3-color": "1 - 3",
"d3-dispatch": "1 - 3",
"d3-ease": "1 - 3",
"d3-interpolate": "1 - 3",
"d3-timer": "1 - 3"
},
"engines": {
"node": ">=12"
},
"peerDependencies": {
"d3-selection": "2 - 3"
}
},
"node_modules/d3-zoom": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
"integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
"license": "ISC",
"dependencies": {
"d3-dispatch": "1 - 3",
"d3-drag": "2 - 3",
"d3-interpolate": "1 - 3",
"d3-selection": "2 - 3",
"d3-transition": "2 - 3"
},
"engines": {
"node": ">=12"
}
},
"node_modules/data-uri-to-buffer": {
"version": "4.0.1",
"resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
@@ -4716,6 +4894,12 @@
"void-elements": "3.1.0"
}
},
"node_modules/html-to-image": {
"version": "1.11.13",
"resolved": "https://registry.npmjs.org/html-to-image/-/html-to-image-1.11.13.tgz",
"integrity": "sha512-cuOPoI7WApyhBElTTb9oqsawRvZ0rHhaHwghRLlTuffoD1B2aDemlCruLeZrUIIdvG7gs9xeELEPm6PhuASqrg==",
"license": "MIT"
},
"node_modules/html-url-attributes": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",

View File

@@ -21,8 +21,10 @@
"@xterm/addon-fit": "^0.11.0",
"@xterm/addon-web-links": "^0.12.0",
"@xterm/xterm": "^6.0.0",
"@xyflow/react": "^12.8.0",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"html-to-image": "^1.11.13",
"i18next": "^26.0.3",
"i18next-browser-languagedetector": "^8.2.1",
"lucide-react": "^1.7.0",

View File

@@ -0,0 +1,20 @@
import { Slider as SliderPrimitive } from "@base-ui/react/slider"
import { cn } from "@/lib/utils"
function Slider({ className, ...props }: SliderPrimitive.Root.Props) {
return (
<SliderPrimitive.Root data-slot="slider" {...props}>
<SliderPrimitive.Control
className={cn("flex w-full touch-none items-center py-2 select-none", className)}
>
<SliderPrimitive.Track className="h-1 w-full rounded-full bg-input select-none">
<SliderPrimitive.Indicator className="rounded-full bg-primary select-none" />
<SliderPrimitive.Thumb className="size-3.5 rounded-full bg-background border-2 border-primary shadow-xs outline-none select-none focus-visible:ring-3 focus-visible:ring-ring/50" />
</SliderPrimitive.Track>
</SliderPrimitive.Control>
</SliderPrimitive.Root>
)
}
export { Slider }

View File

@@ -0,0 +1,119 @@
import { useCallback, useEffect, useMemo } from 'react';
import {
Background,
BackgroundVariant,
Controls,
MiniMap,
Panel,
ReactFlow,
useReactFlow,
type Edge,
type Node,
} from '@xyflow/react';
import '@xyflow/react/dist/style.css';
import { useThemeStore } from '@/stores/theme-store';
import { useTranslation } from 'react-i18next';
import { TopologyLegend } from './TopologyLegend';
import { ClusterNode } from './nodes/ClusterNode';
import { GuestGroupNode } from './nodes/GuestGroupNode';
import { GuestNode } from './nodes/GuestNode';
import { PanelNode } from './nodes/PanelNode';
import { PveNode } from './nodes/PveNode';
import './topology.css';
// Declared at module scope: recreating this object on every render makes React
// Flow remount every node and the canvas crawls.
const nodeTypes = {
panel: PanelNode,
cluster: ClusterNode,
pve: PveNode,
guest: GuestNode,
guestGroup: GuestGroupNode,
} as const;
const defaultEdgeOptions = { type: 'smoothstep' as const, animated: false };
// Above this many nodes React Flow only mounts what is on screen, and the
// minimap (which renders every node again) is dropped.
const VIRTUALIZE_ABOVE = 150;
const MINIMAP_LIMIT = 400;
interface TopologyCanvasProps {
nodes: Node[];
edges: Edge[];
onExpandNode: (nodeId: string) => void;
/** Rendered inside the canvas only in fullscreen, where the page chrome is gone. */
toolbar?: React.ReactNode;
}
export function TopologyCanvas({ nodes, edges, onExpandNode, toolbar }: TopologyCanvasProps) {
const { t } = useTranslation();
// The panel drives its theme through this store, not next-themes (which
// ships only as a sonner dependency and has no provider mounted here).
const theme = useThemeStore((state) => state.theme);
const { fitView } = useReactFlow();
// The group node's expand button lives in node data; buildGraph is pure and
// cannot know about the callback, so it is attached here.
const decorated = useMemo(
() =>
nodes.map((node) =>
node.type === 'guestGroup'
? { ...node, data: { ...node.data, onExpand: onExpandNode } }
: node,
),
[nodes, onExpandNode],
);
const handleInit = useCallback(() => {
fitView({ padding: 0.15, duration: 0 });
}, [fitView]);
// Filtering, grouping or expanding changes how much space the tree needs, so
// refit whenever the node count moves — otherwise the graph drifts off-screen
// or stays zoomed out after a filter shrinks it.
const nodeCount = decorated.length;
useEffect(() => {
if (nodeCount === 0) return;
const timer = window.setTimeout(() => fitView({ padding: 0.15, duration: 300 }), 0);
return () => window.clearTimeout(timer);
}, [nodeCount, fitView]);
return (
<ReactFlow
nodes={decorated}
edges={edges}
nodeTypes={nodeTypes}
defaultEdgeOptions={defaultEdgeOptions}
colorMode={theme === 'light' ? 'light' : 'dark'}
onInit={handleInit}
fitView
fitViewOptions={{ padding: 0.15 }}
minZoom={0.05}
maxZoom={2}
nodesDraggable={false}
nodesConnectable={false}
zoomOnDoubleClick={false}
proOptions={{ hideAttribution: false }}
onlyRenderVisibleElements={decorated.length > VIRTUALIZE_ABOVE}
>
<Background variant={BackgroundVariant.Dots} gap={18} size={1} />
{/* Top-right keeps the zoom buttons clear of the toolbar and the legend. */}
<Controls showInteractive={false} position="top-right" orientation="horizontal" />
{decorated.length <= MINIMAP_LIMIT ? <MiniMap pannable zoomable className="!h-24 !w-40" /> : null}
{toolbar ? (
<Panel position="top-left" className="!m-3 max-w-[calc(100%-1.5rem)]">
{toolbar}
</Panel>
) : null}
<Panel position="bottom-left" className="!m-3">
<TopologyLegend />
</Panel>
{decorated.length === 0 ? (
<Panel position="top-center" className="!mt-24">
<p className="text-sm text-muted-foreground">{t('topology.empty', 'No servers available')}</p>
</Panel>
) : null}
</ReactFlow>
);
}

View File

@@ -0,0 +1,42 @@
import { useTranslation } from 'react-i18next';
import { Box, Boxes, Monitor, Network, Server, WifiOff } from 'lucide-react';
const ITEMS = [
{ key: 'panel', Icon: Boxes, className: 'text-primary' },
{ key: 'cluster', Icon: Network, className: 'text-muted-foreground' },
{ key: 'node', Icon: Server, className: 'text-muted-foreground' },
{ key: 'vm', Icon: Monitor, className: 'text-emerald-500' },
{ key: 'lxc', Icon: Box, className: 'text-emerald-500' },
{ key: 'stale', Icon: WifiOff, className: 'text-amber-500' },
] as const;
export function TopologyLegend() {
const { t } = useTranslation();
return (
<div
data-export-ignore="true"
className="rounded-lg border border-border bg-card/95 px-3 py-2 shadow-sm backdrop-blur"
>
<div className="mb-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
{t('topology.legend.title', 'Legend')}
</div>
<div className="space-y-1">
{ITEMS.map(({ key, Icon, className }) => (
<div key={key} className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
<Icon className={`h-3 w-3 shrink-0 ${className}`} />
<span>{t(`topology.legend.${key}`, key)}</span>
</div>
))}
<div className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
<span className="h-2 w-2 shrink-0 rounded-full bg-emerald-500" />
<span>{t('topology.legend.running', 'Running')}</span>
</div>
<div className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
<span className="h-2 w-2 shrink-0 rounded-full bg-muted-foreground/50" />
<span>{t('topology.legend.stopped', 'Stopped')}</span>
</div>
</div>
</div>
);
}

View File

@@ -0,0 +1,193 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { ReactFlowProvider, useReactFlow } from '@xyflow/react';
import { useTranslation } from 'react-i18next';
import { toast } from 'sonner';
import { AlertTriangle } from 'lucide-react';
import { useNetworkTopology } from '@/hooks/use-topology';
import { Skeleton } from '@/components/ui/skeleton';
import { cn } from '@/lib/utils';
import { TopologyCanvas } from './TopologyCanvas';
import { TopologyToolbar } from './TopologyToolbar';
import { buildGraph, listConnections } from './lib/build-graph';
import { exportGraph } from './lib/export';
import type { TopologyFilters } from './lib/types';
const THRESHOLD_STORAGE_KEY = 'pve-topology-threshold';
const DEFAULT_THRESHOLD = 20;
// Past this many guests an ungrouped graph is unusable, so grouping is forced.
const FORCE_GROUPING_ABOVE = 1500;
const EXPORT_NODE_LIMIT = 1200;
function readStoredThreshold(): number {
// Guard the missing key explicitly: Number(null) is 0, which would silently
// turn "never stored" into "grouping off" on a first visit.
const raw = localStorage.getItem(THRESHOLD_STORAGE_KEY);
if (raw === null) return DEFAULT_THRESHOLD;
const stored = Number(raw);
return Number.isFinite(stored) && stored >= 0 && stored <= 100 ? stored : DEFAULT_THRESHOLD;
}
function TopologyView() {
const { t } = useTranslation();
const { fitView } = useReactFlow();
const wrapperRef = useRef<HTMLDivElement>(null);
const [isFullscreen, setIsFullscreen] = useState(false);
const [expanded, setExpanded] = useState<Set<string>>(new Set());
const [filters, setFilters] = useState<TopologyFilters>(() => ({
serverId: 'all',
vmStatus: 'all',
groupThreshold: readStoredThreshold(),
groupMode: 'hierarchy',
}));
// The whole tree is fetched once and every filter — connection included — is
// applied in buildGraph. Putting the connection in the query key instead
// would blank the graph on each switch while the new response is in flight.
const { data, isLoading, error, refetch, isFetching } = useNetworkTopology();
const tooManyGuests = (data?.panel.guest_count ?? 0) > FORCE_GROUPING_ABOVE;
const effectiveFilters = useMemo<TopologyFilters>(
() =>
tooManyGuests && filters.groupThreshold === 0
? { ...filters, groupThreshold: DEFAULT_THRESHOLD }
: filters,
[filters, tooManyGuests],
);
const { nodes, edges } = useMemo(
() => buildGraph(data, effectiveFilters, expanded),
[data, effectiveFilters, expanded],
);
const connections = useMemo(() => listConnections(data), [data]);
const handleFiltersChange = useCallback((next: TopologyFilters) => {
setFilters((previous) => {
// Expanding is per-node state; a different connection shows other nodes.
if (previous.serverId !== next.serverId) setExpanded(new Set());
if (previous.groupThreshold !== next.groupThreshold) {
localStorage.setItem(THRESHOLD_STORAGE_KEY, String(next.groupThreshold));
}
return next;
});
}, []);
const handleExpandNode = useCallback((nodeId: string) => {
setExpanded((previous) => new Set(previous).add(nodeId));
}, []);
const handleFit = useCallback(() => {
fitView({ padding: 0.15, duration: 300 });
}, [fitView]);
useEffect(() => {
const onChange = () => setIsFullscreen(document.fullscreenElement === wrapperRef.current);
document.addEventListener('fullscreenchange', onChange);
return () => document.removeEventListener('fullscreenchange', onChange);
}, []);
const handleFullscreen = useCallback(() => {
if (document.fullscreenElement === wrapperRef.current) {
void document.exitFullscreen();
} else {
void wrapperRef.current?.requestFullscreen();
}
}, []);
const handleExport = useCallback(
(format: 'png' | 'svg') => {
toast.promise(exportGraph(nodes, format, 'topology'), {
loading: t('topology.export.progress', 'Rendering image…'),
success: t('topology.export.done', 'Image saved'),
error: t('topology.export.failed', 'Export failed'),
});
},
[nodes, t],
);
const toolbar = (
<TopologyToolbar
filters={effectiveFilters}
onChange={handleFiltersChange}
connections={connections}
isFullscreen={isFullscreen}
isFetching={isFetching}
onFit={handleFit}
onFullscreen={handleFullscreen}
onRefresh={() => void refetch()}
onExport={handleExport}
exportDisabled={nodes.length === 0 || nodes.length > EXPORT_NODE_LIMIT}
/>
);
const warnings = data?.warnings ?? [];
return (
<div className="space-y-4">
<div>
<h1 className="text-2xl font-bold">{t('topology.title', 'Network topology')}</h1>
<p className="text-sm text-muted-foreground">
{t('topology.subtitle', 'Hierarchical map of clusters, nodes and guests')}
</p>
</div>
{warnings.length > 0 ? (
<div className="space-y-1 rounded-lg border border-amber-500/40 bg-amber-500/5 px-3 py-2">
{warnings.map((warning, index) => (
<div key={`${warning.code}-${index}`} className="flex items-center gap-2 text-xs text-amber-600 dark:text-amber-400">
<AlertTriangle className="h-3.5 w-3.5 shrink-0" />
<span>
{warning.code === 'offline'
? t('topology.warning.offline', { server: warning.server_name ?? '' })
: warning.message}
</span>
</div>
))}
</div>
) : null}
{tooManyGuests ? (
<p className="text-xs text-muted-foreground">{t('topology.too_many', 'Too many objects; grouping enabled')}</p>
) : null}
{/* Above the canvas normally; in fullscreen it moves inside, where it is
the only way to reach the filters. */}
{isFullscreen ? null : toolbar}
<div
ref={wrapperRef}
className={cn(
'topology-canvas overflow-hidden border border-border bg-background',
// In fullscreen the browser sizes the element, so the page-layout
// height (and the rounded frame) would only leave a dead strip.
isFullscreen ? 'h-full w-full' : 'h-[calc(100vh-19rem)] min-h-[480px] rounded-lg',
)}
>
{isLoading ? (
<div className="flex h-full flex-col gap-3 p-4">
<Skeleton className="h-10 w-full" />
<Skeleton className="h-full w-full" />
</div>
) : error ? (
<div className="flex h-full items-center justify-center text-sm text-destructive">
{t('topology.error', 'Failed to load topology')}
</div>
) : (
<TopologyCanvas
nodes={nodes}
edges={edges}
onExpandNode={handleExpandNode}
toolbar={isFullscreen ? toolbar : undefined}
/>
)}
</div>
</div>
);
}
export default function TopologyPage() {
return (
<ReactFlowProvider>
<TopologyView />
</ReactFlowProvider>
);
}

View File

@@ -0,0 +1,154 @@
import { useTranslation } from 'react-i18next';
import { Download, Maximize2, Minimize2, RefreshCw, Scan } from 'lucide-react';
import { Button } from '@/components/ui/button';
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
import { Slider } from '@/components/ui/slider';
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu';
import { cn } from '@/lib/utils';
import type { TopologyFilters, VmStatusFilter } from './lib/types';
const STATUSES: VmStatusFilter[] = ['all', 'running', 'stopped'];
interface TopologyToolbarProps {
filters: TopologyFilters;
onChange: (filters: TopologyFilters) => void;
connections: Array<{ id: number; name: string }>;
isFullscreen: boolean;
isFetching: boolean;
onFit: () => void;
onFullscreen: () => void;
onRefresh: () => void;
onExport: (format: 'png' | 'svg') => void;
exportDisabled: boolean;
}
export function TopologyToolbar({
filters,
onChange,
connections,
isFullscreen,
isFetching,
onFit,
onFullscreen,
onRefresh,
onExport,
exportDisabled,
}: TopologyToolbarProps) {
const { t } = useTranslation();
return (
<div
data-export-ignore="true"
className="flex flex-wrap items-center gap-3 rounded-lg border border-border bg-card/95 px-3 py-2 shadow-sm backdrop-blur"
>
<Select
value={String(filters.serverId)}
onValueChange={(value) =>
onChange({ ...filters, serverId: value === 'all' ? 'all' : Number(value) })
}
>
<SelectTrigger className="h-8 w-[190px] text-xs">
<SelectValue placeholder={t('topology.filters.connection', 'Connection')} />
</SelectTrigger>
<SelectContent>
<SelectItem value="all">{t('topology.filters.all_connections', 'All connections')}</SelectItem>
{connections.map((connection) => (
<SelectItem key={connection.id} value={String(connection.id)}>
{connection.name}
</SelectItem>
))}
</SelectContent>
</Select>
<div className="flex items-center gap-1.5">
<span className="text-xs text-muted-foreground">{t('topology.filters.vm_status', 'VM status')}:</span>
<div className="flex overflow-hidden rounded-md border border-border">
{STATUSES.map((status) => (
<button
key={status}
type="button"
onClick={() => onChange({ ...filters, vmStatus: status })}
className={cn(
'px-2 py-1 text-xs transition-colors',
filters.vmStatus === status
? 'bg-primary text-primary-foreground'
: 'text-muted-foreground hover:bg-accent',
)}
>
{t(`topology.filters.status_${status}`, status)}
</button>
))}
</div>
</div>
<div className="flex items-center gap-2">
<span className="text-xs whitespace-nowrap text-muted-foreground">
{t('topology.filters.threshold', 'Group VMs above')}
</span>
<Slider
className="w-28"
min={0}
max={100}
step={5}
value={filters.groupThreshold}
onValueChange={(value) =>
onChange({ ...filters, groupThreshold: Array.isArray(value) ? value[0] : value })
}
/>
<span className="w-8 text-xs tabular-nums text-muted-foreground">
{filters.groupThreshold === 0 ? t('topology.filters.threshold_off', 'Off') : filters.groupThreshold}
</span>
</div>
<div className="ml-auto flex items-center gap-1">
<Button variant="ghost" size="icon" className="h-8 w-8" onClick={onRefresh} title={t('topology.actions.refresh', 'Refresh')}>
<RefreshCw className={cn('h-4 w-4', isFetching && 'animate-spin')} />
</Button>
<Button variant="ghost" size="icon" className="h-8 w-8" onClick={onFit} title={t('topology.actions.fit', 'Fit to screen')}>
<Scan className="h-4 w-4" />
</Button>
<DropdownMenu>
<DropdownMenuTrigger
render={
<Button
variant="ghost"
size="icon"
className="h-8 w-8"
disabled={exportDisabled}
title={t('topology.actions.export', 'Export')}
/>
}
>
<Download className="h-4 w-4" />
</DropdownMenuTrigger>
<DropdownMenuContent align="end">
<DropdownMenuItem onClick={() => onExport('png')}>
{t('topology.actions.export_png', 'Export PNG')}
</DropdownMenuItem>
<DropdownMenuItem onClick={() => onExport('svg')} title={t('topology.export.svg_hint', '')}>
{t('topology.actions.export_svg', 'Export SVG')}
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
<Button
variant="ghost"
size="icon"
className="h-8 w-8"
onClick={onFullscreen}
title={
isFullscreen
? t('topology.actions.exit_fullscreen', 'Exit fullscreen')
: t('topology.actions.fullscreen', 'Fullscreen')
}
>
{isFullscreen ? <Minimize2 className="h-4 w-4" /> : <Maximize2 className="h-4 w-4" />}
</Button>
</div>
</div>
);
}

View File

@@ -0,0 +1,158 @@
import type { Edge, Node } from '@xyflow/react';
import { layoutTree, type LayoutNode } from './layout';
import type { NetworkTopology, TopologyFilters, TopologyGuest } from './types';
const PANEL_ID = 'panel:root';
// Wrapping earlier keeps the tree closer to the viewport's aspect ratio:
// one tall column per node forces fitView to shrink everything to a ribbon.
const GUESTS_PER_COLUMN = 6;
export interface BuildGraphResult {
nodes: Node[];
edges: Edge[];
/** Guests left out by the status filter — shown in the toolbar counter. */
filteredOut: number;
}
function matchesStatus(guest: TopologyGuest, filter: TopologyFilters['vmStatus']): boolean {
if (filter === 'all') return true;
if (filter === 'running') return guest.status === 'running';
return guest.status !== 'running';
}
/**
* Turns the API hierarchy into React Flow nodes and edges.
*
* Pure and synchronous so it can live inside a `useMemo` and rerun on every
* filter or slider change. Edges are derived from nesting — the API does not
* ship them.
*/
export function buildGraph(
data: NetworkTopology | undefined,
filters: TopologyFilters,
expanded: Set<string>,
): BuildGraphResult {
if (!data) return { nodes: [], edges: [], filteredOut: 0 };
const nodes: Node[] = [];
const edges: Edge[] = [];
let filteredOut = 0;
let widestGuestList = 0;
const tree: LayoutNode = { id: PANEL_ID, kind: 'panel', children: [] };
const clusters =
filters.serverId === 'all'
? data.clusters
: data.clusters.filter((cluster) => cluster.server_ids.includes(filters.serverId as number));
nodes.push({
id: PANEL_ID,
type: 'panel',
position: { x: 0, y: 0 },
data: { panel: data.panel },
draggable: false,
});
for (const cluster of clusters) {
const clusterBranch: LayoutNode = { id: cluster.id, kind: 'cluster', children: [] };
const pveNodes =
filters.serverId === 'all'
? cluster.nodes
: cluster.nodes.filter((node) => node.server_id === filters.serverId);
if (pveNodes.length === 0) continue;
let clusterGuests = 0;
for (const node of pveNodes) {
const visible = node.guests.filter((guest) => matchesStatus(guest, filters.vmStatus));
filteredOut += node.guests.length - visible.length;
clusterGuests += visible.length;
const nodeBranch: LayoutNode = { id: node.id, kind: 'pve', children: [] };
const collapse =
filters.groupThreshold > 0 &&
visible.length > filters.groupThreshold &&
!expanded.has(node.id);
if (collapse) {
const groupId = `${node.id}:group`;
const running = visible.filter((guest) => guest.status === 'running').length;
nodes.push({
id: groupId,
type: 'guestGroup',
position: { x: 0, y: 0 },
data: {
parentId: node.id,
total: visible.length,
running,
stopped: visible.length - running,
},
draggable: false,
});
edges.push({ id: `e:${node.id}:${groupId}`, source: node.id, target: groupId });
nodeBranch.children.push({ id: groupId, kind: 'guestGroup', children: [] });
} else {
widestGuestList = Math.max(widestGuestList, visible.length);
for (const guest of visible) {
nodes.push({
id: guest.id,
type: 'guest',
position: { x: 0, y: 0 },
data: { guest },
draggable: false,
});
edges.push({ id: `e:${node.id}:${guest.id}`, source: node.id, target: guest.id });
nodeBranch.children.push({ id: guest.id, kind: 'guest', children: [] });
}
}
nodes.push({
id: node.id,
type: 'pve',
position: { x: 0, y: 0 },
data: { node, guestCount: visible.length },
draggable: false,
});
edges.push({ id: `e:${cluster.id}:${node.id}`, source: cluster.id, target: node.id });
clusterBranch.children.push(nodeBranch);
}
nodes.push({
id: cluster.id,
type: 'cluster',
position: { x: 0, y: 0 },
data: { cluster, nodeCount: pveNodes.length, guestCount: clusterGuests },
draggable: false,
});
edges.push({ id: `e:${PANEL_ID}:${cluster.id}`, source: PANEL_ID, target: cluster.id });
tree.children.push(clusterBranch);
}
// A single column of dozens of guests makes the graph a thin unreadable
// ribbon, so long lists wrap into a block once they exceed this.
const positions = layoutTree(tree, {
guestsPerColumn: widestGuestList > GUESTS_PER_COLUMN + 2 ? GUESTS_PER_COLUMN : undefined,
});
for (const node of nodes) {
const position = positions.get(node.id);
if (position) node.position = position;
}
return { nodes, edges, filteredOut };
}
/** Connections present in the response, for the toolbar's connection filter. */
export function listConnections(data: NetworkTopology | undefined): Array<{ id: number; name: string }> {
if (!data) return [];
const byId = new Map<number, string>();
for (const cluster of data.clusters) {
for (const node of cluster.nodes) {
if (!byId.has(node.server_id)) byId.set(node.server_id, node.server_name);
}
}
return [...byId.entries()]
.map(([id, name]) => ({ id, name }))
.sort((a, b) => a.name.localeCompare(b.name));
}

View File

@@ -0,0 +1,56 @@
import { getNodesBounds, getViewportForBounds, type Node } from '@xyflow/react';
import { toPng, toSvg } from 'html-to-image';
const MAX_SIDE = 4096;
/**
* Saves the graph as an image.
*
* Custom nodes are HTML, so a native SVG serialisation is impossible — the SVG
* variant wraps the markup in `<foreignObject>`, which browsers render fine but
* vector editors only partially. PNG is the default for that reason.
*
* The capture always covers the whole graph rather than the current viewport,
* which is what people expect from an export button.
*/
export async function exportGraph(
nodes: Node[],
format: 'png' | 'svg',
filename: string,
): Promise<void> {
const viewport = document.querySelector<HTMLElement>('.react-flow__viewport');
if (!viewport || nodes.length === 0) return;
const bounds = getNodesBounds(nodes);
const width = Math.min(MAX_SIDE, Math.max(1200, Math.round(bounds.width + 160)));
const height = Math.min(MAX_SIDE, Math.max(800, Math.round(bounds.height + 160)));
const transform = getViewportForBounds(bounds, width, height, 0.2, 2, 40);
const background =
getComputedStyle(document.documentElement).getPropertyValue('--background').trim() || '#0a0a0a';
const options = {
backgroundColor: background,
width,
height,
style: {
width: `${width}px`,
height: `${height}px`,
transform: `translate(${transform.x}px, ${transform.y}px) scale(${transform.zoom})`,
},
// Controls and the minimap are UI chrome, not part of the diagram.
filter: (element: HTMLElement) =>
!element?.classList?.contains?.('react-flow__minimap') &&
!element?.classList?.contains?.('react-flow__controls') &&
!element?.dataset?.exportIgnore,
cacheBust: true,
pixelRatio: format === 'png' ? 2 : 1,
};
const dataUrl = format === 'png' ? await toPng(viewport, options) : await toSvg(viewport, options);
const link = document.createElement('a');
link.download = `${filename}.${format}`;
link.href = dataUrl;
link.click();
}

View File

@@ -0,0 +1,152 @@
/**
* Tidy-tree layout for the topology graph.
*
* The graph is a strict tree of fixed depth (panel → cluster → node → guest),
* so a dedicated layout engine would be all cost and no benefit: this is ~60
* synchronous lines, deterministic, and O(n) — it can rerun on every slider
* tick without the flicker an async layout pass introduces.
*
* Orientation is left-to-right: with hundreds of guests a tall column scrolls
* far better than an endlessly wide row.
*/
export type LayoutKind = 'panel' | 'cluster' | 'pve' | 'guest' | 'guestGroup';
export interface LayoutNode {
id: string;
kind: LayoutKind;
children: LayoutNode[];
}
export interface XY {
x: number;
y: number;
}
export const COLUMN_X: Record<LayoutKind, number> = {
panel: 0,
cluster: 330,
pve: 700,
guest: 1080,
guestGroup: 1080,
};
export const NODE_SIZE: Record<LayoutKind, { width: number; height: number }> = {
panel: { width: 230, height: 92 },
cluster: { width: 250, height: 96 },
pve: { width: 270, height: 132 },
guest: { width: 250, height: 84 },
guestGroup: { width: 250, height: 96 },
};
const GAP_Y = 14;
const SUBTREE_GAP = 26;
const COLUMN_GAP_X = 40;
export interface LayoutOptions {
/**
* Wrap a node's guests into extra columns once the list is longer than this.
* Keeps a busy node from stretching the graph into an unreadable ribbon.
*/
guestsPerColumn?: number;
}
/** How many columns a node's guest list is wrapped into. */
function columnsFor(node: LayoutNode, opts: LayoutOptions): number {
if (node.kind !== 'pve' || !opts.guestsPerColumn) return 1;
return Math.max(1, Math.ceil(node.children.length / opts.guestsPerColumn));
}
/** Vertical space a subtree needs, including the gaps between its children. */
function subtreeHeight(node: LayoutNode, opts: LayoutOptions): number {
const own = NODE_SIZE[node.kind].height;
if (node.children.length === 0) return own;
const columns = columnsFor(node, opts);
if (columns > 1) {
const perColumn = Math.ceil(node.children.length / columns);
const tallest = Math.max(...node.children.map((c) => subtreeHeight(c, opts)));
return Math.max(own, perColumn * tallest + (perColumn - 1) * GAP_Y);
}
const childrenHeight = node.children.reduce(
(sum, child, index) => sum + subtreeHeight(child, opts) + (index > 0 ? GAP_Y : 0),
0,
);
return Math.max(own, childrenHeight);
}
/**
* Absolute position of every node, keyed by id. Parents are centred on the
* vertical span of their children.
*/
export function layoutTree(root: LayoutNode, opts: LayoutOptions = {}): Map<string, XY> {
const positions = new Map<string, XY>();
function place(node: LayoutNode, top: number): number {
const size = NODE_SIZE[node.kind];
const height = subtreeHeight(node, opts);
const x = COLUMN_X[node.kind];
if (node.children.length === 0) {
positions.set(node.id, { x, y: top + (height - size.height) / 2 });
return height;
}
const columns = columnsFor(node, opts);
if (columns > 1) {
// Wrap the guest list into a block so a busy node stays readable.
const perColumn = Math.ceil(node.children.length / columns);
const childWidth = NODE_SIZE[node.children[0].kind].width;
node.children.forEach((child, index) => {
const column = Math.floor(index / perColumn);
const row = index % perColumn;
const childHeight = NODE_SIZE[child.kind].height;
positions.set(child.id, {
x: COLUMN_X[child.kind] + column * (childWidth + COLUMN_GAP_X),
y: top + row * (childHeight + GAP_Y),
});
});
} else {
let cursor = top;
node.children.forEach((child, index) => {
if (index > 0) cursor += GAP_Y;
cursor += place(child, cursor);
});
}
positions.set(node.id, { x, y: top + (height - size.height) / 2 });
return height;
}
place(root, 0);
// Separate top-level subtrees a little more than siblings inside one.
let extra = 0;
for (const cluster of root.children) {
if (extra > 0) shift(cluster, extra, positions);
extra += SUBTREE_GAP;
}
if (root.children.length > 0) {
const clusterPositions = root.children
.map((c) => positions.get(c.id))
.filter((p): p is XY => Boolean(p));
if (clusterPositions.length > 0) {
const first = clusterPositions[0].y;
const last = clusterPositions[clusterPositions.length - 1].y;
positions.set(root.id, {
x: COLUMN_X.panel,
y: (first + last) / 2 + (NODE_SIZE.cluster.height - NODE_SIZE.panel.height) / 2,
});
}
}
return positions;
}
function shift(node: LayoutNode, delta: number, positions: Map<string, XY>): void {
const position = positions.get(node.id);
if (position) positions.set(node.id, { ...position, y: position.y + delta });
for (const child of node.children) shift(child, delta, positions);
}

View File

@@ -0,0 +1,137 @@
/** Shapes returned by GET /proxmox/api/network/topology (backend schemas.py). */
export interface TopologyNic {
key: string;
model?: string | null;
mac?: string | null;
bridge?: string | null;
vlan_tag?: number | null;
trunks: number[];
firewall: boolean;
link_down: boolean;
name?: string | null;
ip?: string | null;
gw?: string | null;
rate?: number | null;
mtu?: number | null;
}
export interface TopologyBridge {
name: string;
type?: string | null;
cidr?: string | null;
vlan_aware: boolean;
ports?: string | null;
active: boolean;
zone?: string | null;
ipam_network_id?: number | null;
ipam_cidr?: string | null;
ipam_name?: string | null;
}
export interface TopologyGuest {
id: string;
server_id: number;
node: string;
vmid: number;
type: 'qemu' | 'lxc' | string;
name: string;
status: string;
is_template: boolean;
lock?: string | null;
cpu?: number | null;
cores?: number | null;
mem?: number | null;
maxmem?: number | null;
disk?: number | null;
maxdisk?: number | null;
uptime?: number | null;
tags: string[];
owner_id?: number | null;
owner_username?: string | null;
ip?: string | null;
nics: TopologyNic[];
}
export interface TopologyNode {
id: string;
server_id: number;
server_name: string;
node: string;
status: string;
/** Rebuilt from the local VM cache because the connection is unreachable. */
stale: boolean;
cpu?: number | null;
maxcpu?: number | null;
mem?: number | null;
maxmem?: number | null;
uptime?: number | null;
bridges: TopologyBridge[];
guests: TopologyGuest[];
}
export interface TopologyCluster {
id: string;
name: string;
kind: 'cluster' | 'standalone' | string;
server_ids: number[];
online: boolean;
nodes: TopologyNode[];
}
export interface TopologyWarning {
server_id?: number | null;
server_name?: string | null;
code: string;
message: string;
}
export interface TopologyPanelSummary {
name: string;
cluster_count: number;
node_count: number;
guest_count: number;
}
export interface NetworkTopology {
generated_at: string;
panel: TopologyPanelSummary;
clusters: TopologyCluster[];
warnings: TopologyWarning[];
}
export type VmStatusFilter = 'all' | 'running' | 'stopped';
/** Grouping mode. Only `hierarchy` ships today; VLAN/tag views reuse this switch. */
export type GroupMode = 'hierarchy';
export interface TopologyFilters {
serverId: number | 'all';
vmStatus: VmStatusFilter;
/** Collapse a node's guests into one badge above this count. 0 disables it. */
groupThreshold: number;
groupMode: GroupMode;
}
/** Data carried by each React Flow node type. */
export interface PanelNodeData extends Record<string, unknown> {
panel: TopologyPanelSummary;
}
export interface ClusterNodeData extends Record<string, unknown> {
cluster: TopologyCluster;
nodeCount: number;
guestCount: number;
}
export interface PveNodeData extends Record<string, unknown> {
node: TopologyNode;
guestCount: number;
}
export interface GuestNodeData extends Record<string, unknown> {
guest: TopologyGuest;
}
export interface GuestGroupNodeData extends Record<string, unknown> {
parentId: string;
total: number;
running: number;
stopped: number;
}

View File

@@ -0,0 +1,48 @@
import { memo } from 'react';
import { Handle, Position, type NodeProps } from '@xyflow/react';
import { useTranslation } from 'react-i18next';
import { Network, Server } from 'lucide-react';
import { Badge } from '@/components/ui/badge';
import { cn } from '@/lib/utils';
import type { ClusterNodeData } from '../lib/types';
function ClusterNodeImpl({ data }: NodeProps) {
const { t } = useTranslation();
const { cluster, nodeCount, guestCount } = data as ClusterNodeData;
const isCluster = cluster.kind === 'cluster';
const Icon = isCluster ? Network : Server;
return (
<div
className={cn(
'w-[250px] rounded-lg border bg-card px-3 py-2.5 shadow-sm',
cluster.online ? 'border-emerald-500/60' : 'border-border',
)}
>
<Handle type="target" position={Position.Left} isConnectable={false} className="!bg-border" />
<div className="flex items-center gap-2">
<Icon className="h-4 w-4 shrink-0 text-muted-foreground" />
<span className="truncate text-sm font-medium">{cluster.name}</span>
<span
className={cn(
'ml-auto h-2 w-2 shrink-0 rounded-full',
cluster.online ? 'bg-emerald-500' : 'bg-muted-foreground/50',
)}
/>
</div>
<div className="mt-2 flex items-center gap-2">
<Badge variant="outline" className="text-[10px]">
{isCluster
? t('topology.legend.cluster', 'Cluster')
: t('topology.legend.standalone', 'Standalone')}
</Badge>
<span className="text-[11px] text-muted-foreground">
{t('topology.node.nodes_count', { count: nodeCount })} · {t('topology.node.guests_count', { count: guestCount })}
</span>
</div>
<Handle type="source" position={Position.Right} isConnectable={false} className="!bg-border" />
</div>
);
}
export const ClusterNode = memo(ClusterNodeImpl);

View File

@@ -0,0 +1,38 @@
import { memo } from 'react';
import { Handle, Position, type NodeProps } from '@xyflow/react';
import { useTranslation } from 'react-i18next';
import { Layers } from 'lucide-react';
import { Button } from '@/components/ui/button';
import type { GuestGroupNodeData } from '../lib/types';
interface GuestGroupNodeProps extends NodeProps {
data: GuestGroupNodeData & { onExpand?: (nodeId: string) => void };
}
function GuestGroupNodeImpl({ data }: GuestGroupNodeProps) {
const { t } = useTranslation();
const { parentId, total, running, stopped, onExpand } = data;
return (
<div className="w-[250px] rounded-md border border-dashed border-primary/60 bg-card px-2.5 py-2 shadow-sm">
<Handle type="target" position={Position.Left} isConnectable={false} className="!bg-border" />
<div className="flex items-center gap-1.5">
<Layers className="h-3.5 w-3.5 shrink-0 text-primary" />
<span className="text-xs font-medium">{t('topology.group.count', { count: total })}</span>
</div>
<div className="mt-0.5 text-[10px] text-muted-foreground">
{t('topology.group.breakdown', { running, stopped })}
</div>
<Button
variant="ghost"
size="sm"
className="mt-1 h-6 w-full text-[10px]"
onClick={() => onExpand?.(parentId)}
>
{t('topology.group.expand', 'Show all')}
</Button>
</div>
);
}
export const GuestGroupNode = memo(GuestGroupNodeImpl);

View File

@@ -0,0 +1,54 @@
import { memo } from 'react';
import { Handle, Position, type NodeProps } from '@xyflow/react';
import { Box, Monitor } from 'lucide-react';
import { Badge } from '@/components/ui/badge';
import { cn } from '@/lib/utils';
import type { GuestNodeData } from '../lib/types';
const VISIBLE_TAGS = 2;
function GuestNodeImpl({ data }: NodeProps) {
const { guest } = data as GuestNodeData;
const running = guest.status === 'running';
const Icon = guest.type === 'lxc' ? Box : Monitor;
const extraTags = guest.tags.length - VISIBLE_TAGS;
return (
<div
className={cn(
'w-[250px] rounded-md border bg-card px-2.5 py-2 shadow-sm',
running ? 'border-emerald-500/50' : 'border-border',
)}
>
<Handle type="target" position={Position.Left} isConnectable={false} className="!bg-border" />
<div className="flex items-center gap-1.5">
<Icon className={cn('h-3.5 w-3.5 shrink-0', running ? 'text-emerald-500' : 'text-muted-foreground')} />
<span className="truncate text-xs font-medium">{guest.name}</span>
<span className="ml-auto shrink-0 font-mono text-[10px] text-muted-foreground">#{guest.vmid}</span>
</div>
<div className="mt-1 flex items-center gap-1.5 text-[10px]">
<span className={cn(running ? 'text-emerald-500' : 'text-muted-foreground')}>{guest.status}</span>
{guest.ip ? <span className="truncate font-mono text-muted-foreground">{guest.ip}</span> : null}
{guest.nics[0]?.bridge ? (
<span className="truncate text-muted-foreground">{guest.nics[0].bridge}</span>
) : null}
{guest.nics[0]?.vlan_tag ? (
<span className="text-muted-foreground">VLAN {guest.nics[0].vlan_tag}</span>
) : null}
</div>
{guest.tags.length > 0 ? (
<div className="mt-1 flex flex-wrap items-center gap-1">
{guest.tags.slice(0, VISIBLE_TAGS).map((tag) => (
<Badge key={tag} variant="secondary" className="px-1 py-0 text-[9px]">{tag}</Badge>
))}
{extraTags > 0 ? (
<span className="text-[9px] text-muted-foreground">+{extraTags}</span>
) : null}
</div>
) : null}
<Handle type="source" position={Position.Right} isConnectable={false} className="!bg-border" />
</div>
);
}
export const GuestNode = memo(GuestNodeImpl);

View File

@@ -0,0 +1,27 @@
import { memo } from 'react';
import { Handle, Position, type NodeProps } from '@xyflow/react';
import { useTranslation } from 'react-i18next';
import { Boxes } from 'lucide-react';
import type { PanelNodeData } from '../lib/types';
function PanelNodeImpl({ data }: NodeProps) {
const { t } = useTranslation();
const { panel } = data as PanelNodeData;
return (
<div className="w-[230px] rounded-lg border-2 border-primary bg-card px-3 py-2.5 shadow-md">
<div className="flex items-center gap-2">
<Boxes className="h-5 w-5 shrink-0 text-primary" />
<span className="truncate text-sm font-semibold">{panel.name}</span>
</div>
<div className="mt-2 flex gap-3 text-[11px] text-muted-foreground">
<span>{t('topology.node.clusters_count', { count: panel.cluster_count })}</span>
<span>{t('topology.node.nodes_count', { count: panel.node_count })}</span>
<span>{t('topology.node.guests_count', { count: panel.guest_count })}</span>
</div>
<Handle type="source" position={Position.Right} isConnectable={false} className="!bg-primary" />
</div>
);
}
export const PanelNode = memo(PanelNodeImpl);

View File

@@ -0,0 +1,79 @@
import { memo } from 'react';
import { Handle, Position, type NodeProps } from '@xyflow/react';
import { useTranslation } from 'react-i18next';
import { Server, WifiOff } from 'lucide-react';
import { formatBytes } from '@/lib/format';
import { cn } from '@/lib/utils';
import type { PveNodeData } from '../lib/types';
function Meter({ label, value, hint }: { label: string; value: number | null; hint?: string }) {
const percent = value === null ? 0 : Math.min(100, Math.max(0, value * 100));
return (
<div className="space-y-0.5">
<div className="flex justify-between text-[10px] text-muted-foreground">
<span>{label}</span>
<span>{value === null ? '—' : `${percent.toFixed(0)}%`}{hint ? ` · ${hint}` : ''}</span>
</div>
<div className="h-1 w-full overflow-hidden rounded-full bg-input">
<div
className={cn(
'h-full rounded-full transition-[width]',
percent > 90 ? 'bg-red-500' : percent > 70 ? 'bg-amber-500' : 'bg-primary',
)}
style={{ width: `${percent}%` }}
/>
</div>
</div>
);
}
function PveNodeImpl({ data }: NodeProps) {
const { t } = useTranslation();
const { node, guestCount } = data as PveNodeData;
const online = node.status === 'online';
const memRatio = node.mem && node.maxmem ? node.mem / node.maxmem : null;
return (
<div
className={cn(
'w-[270px] rounded-lg border bg-card px-3 py-2.5 shadow-sm',
node.stale ? 'border-dashed border-amber-500/60' : online ? 'border-emerald-500/50' : 'border-border',
)}
>
<Handle type="target" position={Position.Left} isConnectable={false} className="!bg-border" />
<div className="flex items-center gap-2">
<Server className="h-4 w-4 shrink-0 text-muted-foreground" />
<span className="truncate text-sm font-medium">{node.node}</span>
{node.stale ? (
<WifiOff className="ml-auto h-3.5 w-3.5 shrink-0 text-amber-500" aria-label={t('topology.legend.stale', 'Cached data')} />
) : (
<span
className={cn(
'ml-auto h-2 w-2 shrink-0 rounded-full',
online ? 'bg-emerald-500' : 'bg-muted-foreground/50',
)}
/>
)}
</div>
<div className="mt-0.5 flex items-center justify-between text-[10px] text-muted-foreground">
<span className="truncate">{node.server_name}</span>
<span>{t('topology.node.guests_count', { count: guestCount })}</span>
</div>
<div className="mt-2 space-y-1.5">
<Meter
label={t('topology.node.cpu', 'CPU')}
value={node.cpu ?? null}
hint={node.maxcpu ? `${node.maxcpu} vCPU` : undefined}
/>
<Meter
label={t('topology.node.ram', 'RAM')}
value={memRatio}
hint={node.maxmem ? formatBytes(node.maxmem, 0) : undefined}
/>
</div>
<Handle type="source" position={Position.Right} isConnectable={false} className="!bg-border" />
</div>
);
}
export const PveNode = memo(PveNodeImpl);

View File

@@ -0,0 +1,35 @@
/* React Flow chrome follows the panel's design tokens, in both themes. */
.topology-canvas .react-flow {
--xy-background-color: var(--background);
--xy-edge-stroke: var(--border);
--xy-edge-stroke-selected: var(--primary);
--xy-node-border-radius: var(--radius);
--xy-controls-button-background-color: var(--card);
--xy-controls-button-background-color-hover: var(--accent);
--xy-controls-button-color: var(--foreground);
--xy-controls-button-color-hover: var(--foreground);
--xy-controls-button-border-color: var(--border);
--xy-minimap-background-color: var(--card);
--xy-minimap-mask-background-color-props: color-mix(in oklab, var(--background) 70%, transparent);
--xy-attribution-background-color: transparent;
}
/* Nodes bring their own card styling; the default white box would fight it. */
.topology-canvas .react-flow__node {
background: transparent;
border: none;
padding: 0;
width: auto;
font-size: inherit;
color: inherit;
}
.topology-canvas .react-flow__handle {
width: 6px;
height: 6px;
border: none;
}
.topology-canvas .react-flow__attribution {
opacity: 0.4;
}

View File

@@ -3,6 +3,7 @@ import { useQueryClient } from '@tanstack/react-query';
import { getTasksWebSocket } from '@/lib/websocket';
import { vmKeys } from './use-instances';
import { nodeKeys } from './use-nodes';
import { topologyKeys } from './use-topology';
/**
* Глобальная подписка на real-time события WebSocket, которая инвалидирует
@@ -41,11 +42,13 @@ export function useGlobalRealtimeSync() {
old?.filter((vm) => !(vm.server_id === msg.server_id && vm.vmid === msg.vmid))
);
qc.invalidateQueries({ queryKey: vmKeys.resourcesAll });
qc.invalidateQueries({ queryKey: topologyKeys.all });
});
const unsubVmCreated = ws.onType('vm_created', () => {
qc.invalidateQueries({ queryKey: vmKeys.all });
qc.invalidateQueries({ queryKey: vmKeys.resourcesAll });
qc.invalidateQueries({ queryKey: topologyKeys.all });
});
const unsubVmOwnerChanged = ws.onType('vm_owner_changed', (data: unknown) => {
@@ -73,6 +76,8 @@ export function useGlobalRealtimeSync() {
// Список VM/LXC зависит от набора серверов и их online-статуса
qc.invalidateQueries({ queryKey: vmKeys.all });
qc.invalidateQueries({ queryKey: vmKeys.resourcesAll });
// Топология рисует те же серверы/ноды — иначе граф останется старым
qc.invalidateQueries({ queryKey: topologyKeys.all });
};
const unsubServerAdded = ws.onType('server_added', invalidateServerCaches);

View File

@@ -0,0 +1,35 @@
import { useQuery } from '@tanstack/react-query';
import { apiClient } from '@/lib/api-client';
import type { NetworkTopology } from '@/features/topology/lib/types';
export interface TopologyParams {
serverId?: number;
includeNics?: boolean;
includeTemplates?: boolean;
}
export const topologyKeys = {
all: ['network-topology'] as const,
filtered: (params: TopologyParams) => ['network-topology', params] as const,
};
/**
* The whole infrastructure tree in one request.
*
* The VM status filter is applied client-side (see build-graph) rather than
* through `include_stopped`, so flipping it never costs a round-trip.
*/
export function useNetworkTopology(params: TopologyParams = {}) {
const query = new URLSearchParams();
if (params.serverId !== undefined) query.set('server_id', String(params.serverId));
if (params.includeNics) query.set('include_nics', 'true');
if (params.includeTemplates) query.set('include_templates', 'true');
const suffix = query.toString() ? `?${query.toString()}` : '';
return useQuery({
queryKey: topologyKeys.filtered(params),
queryFn: () => apiClient.get<NetworkTopology>(`/proxmox/api/network/topology${suffix}`),
refetchInterval: 30_000,
staleTime: 15_000,
});
}

View File

@@ -16,6 +16,7 @@ import {
Package,
Terminal,
UserCog,
Waypoints,
} from 'lucide-react';
import { hasPermission } from './permissions';
@@ -64,6 +65,7 @@ export const navGroups: NavGroup[] = [
{
title: 'Network',
items: [
{ label: 'Topology', icon: Waypoints, path: '/topology', permission: 'network:view' },
{ label: 'IPAM', icon: Globe, path: '/ipam', permission: 'ipam:view' },
{ label: 'Networks', icon: Network, path: '/networks', permission: 'server:manage' },
],

View File

@@ -23,7 +23,8 @@
"my apps": "My Apps",
"search": "Search sections",
"searchPlaceholder": "Jump to a section...",
"searchEmpty": "No results found"
"searchEmpty": "No results found",
"topology": "Topology"
},
"appstore": {
"title": "App Store",
@@ -1898,5 +1899,70 @@
"notafter": "Valid until",
"pubkey": "Key",
"fingerprint": "Fingerprint"
},
"topology": {
"title": "Network topology",
"subtitle": "Hierarchical map of clusters, nodes and guests",
"empty": "No servers available",
"error": "Failed to load topology",
"too_many": "Too many objects; grouping is enabled",
"filters": {
"connection": "Connection",
"all_connections": "All connections",
"vm_status": "VM status",
"status_all": "All",
"status_running": "Running",
"status_stopped": "Stopped",
"threshold": "Group VMs above",
"threshold_off": "Off"
},
"actions": {
"fit": "Fit to screen",
"fullscreen": "Fullscreen",
"exit_fullscreen": "Exit fullscreen",
"export": "Export",
"export_png": "Export PNG",
"export_svg": "Export SVG",
"refresh": "Refresh"
},
"export": {
"progress": "Rendering image…",
"done": "Image saved",
"failed": "Export failed",
"svg_hint": "SVG embeds HTML; some vector editors render it only partially"
},
"legend": {
"title": "Legend",
"panel": "Panel",
"cluster": "Cluster",
"standalone": "Standalone",
"node": "Proxmox node",
"vm": "Virtual machine",
"lxc": "Container",
"running": "Running",
"stopped": "Stopped",
"stale": "Cached data"
},
"node": {
"cpu": "CPU",
"ram": "RAM",
"clusters_count_one": "{{count}} cluster",
"clusters_count_other": "{{count}} clusters",
"nodes_count_one": "{{count}} node",
"nodes_count_other": "{{count}} nodes",
"guests_count_one": "{{count}} guest",
"guests_count_other": "{{count}} guests"
},
"group": {
"count": "{{count}} VMs",
"count_one": "{{count}} VM",
"expand": "Show all",
"collapse": "Collapse",
"breakdown": "{{running}} running · {{stopped}} stopped"
},
"warning": {
"offline": "{{server}} is unreachable — showing cached data",
"error": "{{server}}: {{message}}"
}
}
}

View File

@@ -23,7 +23,8 @@
"my apps": "Мои приложения",
"search": "Поиск разделов",
"searchPlaceholder": "Перейти к разделу...",
"searchEmpty": "Ничего не найдено"
"searchEmpty": "Ничего не найдено",
"topology": "Топология"
},
"appstore": {
"title": "Каталог приложений",
@@ -311,7 +312,6 @@
"queued": "В очереди...",
"no_data": "Нет данных",
"confirm_delete": "Вы уверены, что хотите удалить?",
"no_data": "Нет данных",
"all": "Все",
"date": "Дата",
"user": "Пользователь",
@@ -2007,5 +2007,75 @@
"notafter": "Действителен до",
"pubkey": "Ключ",
"fingerprint": "Отпечаток"
},
"topology": {
"title": "Топология сети",
"subtitle": "Иерархическая карта кластеров, нод и гостей",
"empty": "Нет доступных серверов",
"error": "Не удалось загрузить топологию",
"too_many": "Слишком много объектов — включена группировка",
"filters": {
"connection": "Подключение",
"all_connections": "Все подключения",
"vm_status": "Статус VM",
"status_all": "Все",
"status_running": "Запущенные",
"status_stopped": "Остановленные",
"threshold": "Группировать VM свыше",
"threshold_off": "Выкл"
},
"actions": {
"fit": "Вписать в экран",
"fullscreen": "Полный экран",
"exit_fullscreen": "Выйти из полного экрана",
"export": "Экспорт",
"export_png": "Экспорт в PNG",
"export_svg": "Экспорт в SVG",
"refresh": "Обновить"
},
"export": {
"progress": "Готовим изображение…",
"done": "Изображение сохранено",
"failed": "Не удалось экспортировать",
"svg_hint": "SVG содержит HTML внутри; некоторые векторные редакторы отрисуют его частично"
},
"legend": {
"title": "Легенда",
"panel": "Панель",
"cluster": "Кластер",
"standalone": "Отдельный сервер",
"node": "Нода Proxmox",
"vm": "Виртуальная машина",
"lxc": "Контейнер",
"running": "Запущен",
"stopped": "Остановлен",
"stale": "Данные из кэша"
},
"node": {
"cpu": "CPU",
"ram": "RAM",
"clusters_count_one": "{{count}} кластер",
"clusters_count_few": "{{count}} кластера",
"clusters_count_many": "{{count}} кластеров",
"nodes_count_one": "{{count}} нода",
"nodes_count_few": "{{count}} ноды",
"nodes_count_many": "{{count}} нод",
"guests_count_one": "{{count}} гость",
"guests_count_few": "{{count}} гостя",
"guests_count_many": "{{count}} гостей"
},
"group": {
"count_one": "{{count}} VM",
"count_few": "{{count}} VM",
"count_many": "{{count}} VM",
"count_other": "{{count}} VM",
"expand": "Показать все",
"collapse": "Свернуть",
"breakdown": "{{running}} запущено · {{stopped}} остановлено"
},
"warning": {
"offline": "{{server}} недоступен — показаны данные из кэша",
"error": "{{server}}: {{message}}"
}
}
}

View File

@@ -25,6 +25,7 @@ const TemplatesPage = lazy(() => import('./features/templates/TemplatesPage.tsx'
const ImagesPage = lazy(() => import('./features/images/ImagesPage.tsx'));
const BackupsPage = lazy(() => import('./features/backups/BackupsPage.tsx'));
const TasksPage = lazy(() => import('./features/tasks/TasksPage.tsx'));
const TopologyPage = lazy(() => import('./features/topology/TopologyPage.tsx'));
const IPAMDashboardPage = lazy(() => import('./features/ipam/IPAMDashboardPage.tsx'));
const IPAMNetworksPage = lazy(() => import('./features/ipam/IPAMNetworksPage.tsx'));
const IPAMNetworkDetailPage = lazy(() => import('./features/ipam/IPAMNetworkDetailPage.tsx'));
@@ -111,6 +112,7 @@ export const router = createBrowserRouter([
{ path: '/images', element: <Page perm="template:manage"><ImagesPage /></Page> },
{ path: '/backups', element: <Page perm="backup:view"><BackupsPage /></Page> },
{ path: '/tasks', element: <Page perm="vm:view"><TasksPage /></Page> },
{ path: '/topology', element: <Page perm="network:view"><TopologyPage /></Page> },
{ path: '/ipam', element: <Page perm="ipam:view"><IPAMDashboardPage /></Page> },
{ path: '/ipam/networks', element: <Page perm="ipam:view"><IPAMNetworksPage /></Page> },
{ path: '/ipam/network/:id', element: <Page perm="ipam:view"><IPAMNetworkDetailPage /></Page> },