feat(桌面与监控): 完善工作台导航和登录活动定位

- 优化桌面标签、上下文标题、前进后退、导航栏隐藏和原生菜单体验

- 补充登录会话 IP 采集、地理位置回退、管理端展示及数据库迁移

- 更新桌面发布检查、运维文档和前后端测试覆盖

backend/app/services/ip_geolocation_fallback.py

@@ -0,0 +1,174 @@
+"""Bounded third-party coordinate fallback for public source IPs.
+
+IPAddress.my identifies IP2Location.io as its data provider. We use the
+provider's documented JSON API instead of scraping the public HTML page.
+Only globally routable addresses are eligible, and results are cached so the
+monitoring UI does not turn into a per-refresh third-party lookup fan-out.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import logging
+import math
+import time
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+import httpx
+
+from app.core.config import settings
+from app.services.geo_location_metadata import GeoLocationMetadata
+from app.services.ip_location import IpLocation
+
+logger = logging.getLogger("ctms.ip_geolocation_fallback")
+
+_API_URL = "https://api.ip2location.io/"
+_MAX_RESPONSE_BYTES = 64 * 1024
+_MAX_CACHE_ENTRIES = 4096
+_NEGATIVE_CACHE_SECONDS = 3600
+_cache: dict[str, tuple[float, "ExternalIpLocation | None"]] = {}
+_cache_lock = asyncio.Lock()
+
+
+def _text(value: Any, limit: int = 160) -> str:
+    candidate = str(value or "").strip()
+    return "" if candidate in {"", "-", "0"} else candidate[:limit]
+
+
+def _coordinate(value: Any, *, minimum: float, maximum: float) -> float | None:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if math.isfinite(number) and minimum <= number <= maximum else None
+
+
+def _global_ip(value: str | None) -> str | None:
+    try:
+        address = ipaddress.ip_address((value or "").strip())
+    except ValueError:
+        return None
+    return str(address) if address.is_global else None
+
+
+@dataclass(frozen=True)
+class ExternalIpLocation:
+    ip_address: str
+    country: str
+    country_code: str
+    region: str
+    city: str
+    isp: str
+    longitude: float
+    latitude: float
+
+    def merge_ip_location(self, local: IpLocation) -> IpLocation:
+        country = self.country or local.country
+        province = self.region or local.province
+        city = self.city or local.city
+        isp = self.isp or local.isp
+        location = " / ".join(part for part in [country, province, city, isp] if part) or local.location
+        return IpLocation(location=location, country=country, province=province, city=city, isp=isp)
+
+    def to_metadata(self) -> GeoLocationMetadata:
+        return GeoLocationMetadata(
+            country=self.country,
+            country_code=self.country_code,
+            region_code="",
+            longitude=self.longitude,
+            latitude=self.latitude,
+            accuracy_level="city" if self.city else "country",
+        )
+
+
+def _parse_response(expected_ip: str, payload: Any) -> ExternalIpLocation | None:
+    if not isinstance(payload, dict):
+        return None
+    response_ip = _global_ip(_text(payload.get("ip"), 45))
+    if response_ip != expected_ip:
+        return None
+    latitude = _coordinate(payload.get("latitude"), minimum=-90, maximum=90)
+    longitude = _coordinate(payload.get("longitude"), minimum=-180, maximum=180)
+    if latitude is None or longitude is None:
+        return None
+    country_code = _text(payload.get("country_code"), 2).upper()
+    if len(country_code) != 2:
+        country_code = ""
+    return ExternalIpLocation(
+        ip_address=expected_ip,
+        country=_text(payload.get("country_name"), 100),
+        country_code=country_code,
+        region=_text(payload.get("region_name"), 100),
+        city=_text(payload.get("city_name"), 100),
+        isp=_text(payload.get("isp"), 160),
+        longitude=longitude,
+        latitude=latitude,
+    )
+
+
+async def _fetch_one(
+    client: httpx.AsyncClient,
+    semaphore: asyncio.Semaphore,
+    ip_address: str,
+) -> ExternalIpLocation | None:
+    async with semaphore:
+        try:
+            response = await client.get(_API_URL, params={"ip": ip_address, "format": "json"})
+            response.raise_for_status()
+            if len(response.content) > _MAX_RESPONSE_BYTES:
+                return None
+            return _parse_response(ip_address, response.json())
+        except (httpx.HTTPError, ValueError):
+            logger.warning("External IP coordinate fallback unavailable")
+            return None
+
+
+async def resolve_external_ip_locations(ip_addresses: Iterable[str]) -> dict[str, ExternalIpLocation]:
+    if not settings.MONITORING_IP_GEO_FALLBACK_ENABLED or settings.ENV == "test":
+        return {}
+
+    candidates = list(dict.fromkeys(filter(None, (_global_ip(value) for value in ip_addresses))))
+    if not candidates:
+        return {}
+
+    now = time.monotonic()
+    resolved: dict[str, ExternalIpLocation] = {}
+    pending: list[str] = []
+    async with _cache_lock:
+        for ip_address in candidates:
+            cached = _cache.get(ip_address)
+            if cached and cached[0] > now:
+                if cached[1] is not None:
+                    resolved[ip_address] = cached[1]
+                continue
+            pending.append(ip_address)
+
+    pending = pending[: settings.MONITORING_IP_GEO_FALLBACK_MAX_LOOKUPS]
+    if not pending:
+        return resolved
+
+    headers = {"Accept": "application/json", "User-Agent": "CTMS-IP-Coordinate-Fallback/1.0"}
+    api_key = (settings.MONITORING_IP_GEO_FALLBACK_API_KEY or "").strip()
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    timeout = httpx.Timeout(settings.MONITORING_IP_GEO_FALLBACK_TIMEOUT_SECONDS)
+    semaphore = asyncio.Semaphore(min(5, len(pending)))
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=False, headers=headers) as client:
+        fetched = await asyncio.gather(*(_fetch_one(client, semaphore, item) for item in pending))
+
+    now = time.monotonic()
+    async with _cache_lock:
+        for ip_address, item in zip(pending, fetched):
+            ttl = settings.MONITORING_IP_GEO_FALLBACK_CACHE_SECONDS if item else _NEGATIVE_CACHE_SECONDS
+            _cache[ip_address] = (now + ttl, item)
+            if item is not None:
+                resolved[ip_address] = item
+        while len(_cache) > _MAX_CACHE_ENTRIES:
+            _cache.pop(next(iter(_cache)))
+    return resolved
+
+
+def reset_ip_geolocation_fallback_cache() -> None:
+    _cache.clear()

backend/app/services/monitoring_server_location.py

@@ -21,6 +21,7 @@ import httpx
 
 from app.core.config import settings
 from app.services.geo_location_metadata import resolve_geo_location_metadata
+from app.services.ip_geolocation_fallback import resolve_external_ip_locations
 from app.services.ip_location import resolve_ip_location
 
 logger = logging.getLogger("ctms.monitoring_server_location")
@@ -128,6 +129,11 @@ async def resolve_monitoring_server_location(*, force: bool = False) -> Monitori
         if public_ip:
             ip_location = resolve_ip_location(public_ip)
             metadata = resolve_geo_location_metadata(ip_location)
+            if metadata.longitude is None or metadata.latitude is None:
+                external_location = (await resolve_external_ip_locations([public_ip])).get(public_ip)
+                if external_location is not None:
+                    ip_location = external_location.merge_ip_location(ip_location)
+                    metadata = external_location.to_metadata()
             if metadata.longitude is not None and metadata.latitude is not None:
                 country = metadata.country or ip_location.country
                 name = " / ".join(

backend/app/services/source_location_aggregator.py

@@ -20,6 +20,7 @@ from app.models.permission_access_log import PermissionAccessLog
 from app.models.security_access_log import SecurityAccessLog
 from app.models.source_location_snapshot import SourceLocationSnapshot
 from app.services.geo_location_metadata import resolve_geo_location_metadata
+from app.services.ip_geolocation_fallback import resolve_external_ip_locations
 from app.services.ip_location import resolve_ip_location
 
 logger = logging.getLogger("ctms.source_location_aggregator")
@@ -149,12 +150,31 @@ async def aggregate_source_location_hour(bucket_start: datetime, bucket_end: dat
                 auth_failure_count=auth_failures,
             )
 
+        resolved_locations = {
+            ip_address: resolve_ip_location(ip_address)
+            for ip_address, _user_identity in aggregates
+        }
+        resolved_metadata = {
+            ip_address: resolve_geo_location_metadata(ip_info)
+            for ip_address, ip_info in resolved_locations.items()
+        }
+        missing_coordinate_ips = [
+            ip_address
+            for ip_address, metadata in resolved_metadata.items()
+            if metadata.accuracy_level != "private"
+            and (metadata.longitude is None or metadata.latitude is None)
+        ]
+        external_locations = await resolve_external_ip_locations(missing_coordinate_ips)
+        for ip_address, external_location in external_locations.items():
+            resolved_locations[ip_address] = external_location.merge_ip_location(resolved_locations[ip_address])
+            resolved_metadata[ip_address] = external_location.to_metadata()
+
         await session.execute(
             delete(SourceLocationSnapshot).where(SourceLocationSnapshot.bucket_time == bucket_start)
         )
         for row in aggregates.values():
-            ip_info = resolve_ip_location(row["ip_address"])
-            metadata = resolve_geo_location_metadata(ip_info)
+            ip_info = resolved_locations[row["ip_address"]]
+            metadata = resolved_metadata[row["ip_address"]]
             longitude = metadata.longitude
             latitude = metadata.latitude
             country = metadata.country or ip_info.country

backend/app/services/user_login_sessions.py

@@ -11,7 +11,9 @@ from sqlalchemy import select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
+from app.core.request_context import resolve_client_ip
 from app.models.user_login_session import UserLoginSession
+from app.services.ip_location import resolve_ip_location
 
 
 @dataclass(frozen=True)
@@ -59,6 +61,35 @@ def session_client_type(payload: dict[str, Any], headers: Any) -> str:
     return "desktop" if "desktop" in {from_payload, from_header} else "web"
 
 
+def login_activity_status(session: UserLoginSession, *, reference_time: datetime | None = None) -> str:
+    if session.ended_at is not None:
+        return "ENDED"
+    cutoff = (reference_time or _now()) - timedelta(seconds=settings.USER_SESSION_ONLINE_SECONDS)
+    return "ONLINE" if _as_utc(session.last_seen_at) >= cutoff else "OFFLINE"
+
+
+def login_activity_payload(
+    session: UserLoginSession,
+    *,
+    reference_time: datetime | None = None,
+) -> dict[str, Any]:
+    ip_location = resolve_ip_location(session.login_ip) if session.login_ip else None
+    return {
+        "id": session.id,
+        "client_type": session.client_type,
+        "client_platform": session.client_platform,
+        "client_version": session.client_version,
+        "client_source": session.client_source,
+        "login_ip": session.login_ip,
+        "ip_location": ip_location.location if ip_location else None,
+        "login_at": session.login_at,
+        "last_seen_at": session.last_seen_at,
+        "ended_at": session.ended_at,
+        "end_reason": session.end_reason,
+        "activity_status": login_activity_status(session, reference_time=reference_time),
+    }
+
+
 async def create_login_session(
     db: AsyncSession,
     *,
@@ -75,6 +106,7 @@ async def create_login_session(
         client_platform=_text_header(request.headers, "x-ctms-client-platform", 32),
         client_version=_text_header(request.headers, "x-ctms-client-version", 64),
         client_source=_text_header(request.headers, "x-ctms-client-source", 32),
+        login_ip=resolve_client_ip(request),
         login_at=occurred_at,
         last_seen_at=occurred_at,
     )
@@ -102,6 +134,7 @@ async def touch_login_session(
             client_platform=_text_header(request.headers, "x-ctms-client-platform", 32),
             client_version=_text_header(request.headers, "x-ctms-client-version", 64),
             client_source=_text_header(request.headers, "x-ctms-client-source", 32),
+            login_ip=resolve_client_ip(request),
             login_at=now,
             last_seen_at=now,
         )