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

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

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

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

backend/app/api/v1/permission_monitoring.py

@@ -28,6 +28,7 @@ from app.models.permission_metric_snapshot import PermissionMetricSnapshot
 from app.models.security_access_log import SecurityAccessLog
 from app.models.user import User
 from app.services.geo_location_metadata import GeoLocationMetadata, resolve_geo_location_metadata
+from app.services.ip_geolocation_fallback import resolve_external_ip_locations
 from app.services.ip_location import IpLocation, resolve_ip_location
 from app.services.monitoring_retention import get_monitoring_retention_status
 from app.services.permission_log_writer import get_log_writer
@@ -1604,12 +1605,15 @@ async def get_ip_locations(
             SecurityAccessLog.category,
         )
     )
+    permission_rows = permission_result.all()
+    security_rows = security_result.all()
     buckets: dict[tuple[str, str, str], dict] = {}
     all_ip_addresses: set[str] = set()
     all_user_ids: set[str] = set()
     located_ip_addresses: set[str] = set()
     private_ip_addresses: set[str] = set()
     unknown_ip_addresses: set[str] = set()
+    external_fallback_ip_addresses: set[str] = set()
     total_count = 0
     allowed_count = 0
     denied_count = 0
@@ -1619,6 +1623,28 @@ async def get_ip_locations(
     resolved_locations: dict[str, IpLocation] = {}
     resolved_metadata: dict[str, GeoLocationMetadata] = {}
 
+    source_ip_addresses = list(
+        dict.fromkeys(
+            [str(row[0]) for row in permission_rows if row[0]]
+            + [str(row[0]) for row in security_rows if row[0]]
+        )
+    )
+    for ip_address in source_ip_addresses:
+        ip_info = resolve_ip_location(ip_address)
+        resolved_locations[ip_address] = ip_info
+        resolved_metadata[ip_address] = resolve_geo_location_metadata(ip_info)
+    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()
+        external_fallback_ip_addresses.add(ip_address)
+
     def normalize_observed_at(value: datetime | None) -> datetime | None:
         if value is None:
             return None
@@ -1725,7 +1751,7 @@ async def get_ip_locations(
         if user_id:
             all_user_ids.add(str(user_id))
 
-    for ip_address, user_id, allowed, event_count, first_seen_at, last_seen_at in permission_result.all():
+    for ip_address, user_id, allowed, event_count, first_seen_at, last_seen_at in permission_rows:
         add_ip_location_row(
             ip_address,
             user_id,
@@ -1736,7 +1762,7 @@ async def get_ip_locations(
             source_kind="permission",
         )
 
-    for client_ip, user_identifier, auth_status, allowed, severity, category, event_count, first_seen_at, last_seen_at in security_result.all():
+    for client_ip, user_identifier, auth_status, allowed, severity, category, event_count, first_seen_at, last_seen_at in security_rows:
         user_id = None
         if auth_status == "AUTHENTICATED" and user_identifier:
             try:
@@ -1837,10 +1863,11 @@ async def get_ip_locations(
         },
         "server_location": server_location.to_public_dict() if server_location else None,
         "data_quality": {
-            "resolver": "ip2region",
+            "resolver": "ip2region+ip2location.io" if external_fallback_ip_addresses else "ip2region",
             "located_ip_count": located_count,
             "private_ip_count": private_count,
             "unknown_ip_count": unknown_count,
+            "external_fallback_ip_count": len(external_fallback_ip_addresses),
             "location_coverage_rate": round((located_count / public_ip_count) * 100, 1) if public_ip_count else 100.0,
             "returned_region_count": len(items),
         },

backend/app/api/v1/users.py

@@ -1,6 +1,6 @@
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -10,7 +10,7 @@ from app.crud import user as user_crud
 from app.crud import member as member_crud
 from app.utils.pagination import paginate
 from app.schemas.user import LoginStatus, UserCreate, UserLoginActivityRead, UserRead, UserStatus, UserUpdate
-from app.services.user_login_sessions import get_login_summaries, list_login_activities
+from app.services.user_login_sessions import get_login_summaries, list_login_activities, login_activity_payload
 
 router = APIRouter()
 
@@ -53,13 +53,16 @@ async def list_users(
 @router.get("/{user_id}/login-activities", response_model=list[UserLoginActivityRead])
 async def read_user_login_activities(
     user_id: uuid.UUID,
+    response: Response,
     limit: int = Query(default=30, ge=1, le=100),
     db: AsyncSession = Depends(get_db_session),
     current_user=Depends(require_roles(["ADMIN"])),
 ) -> list[UserLoginActivityRead]:
+    response.headers["Cache-Control"] = "no-store"
     if not await user_crud.get_by_id(db, user_id):
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="用户不存在")
-    return await list_login_activities(db, user_id=user_id, limit=limit)
+    activities = await list_login_activities(db, user_id=user_id, limit=limit)
+    return [login_activity_payload(activity) for activity in activities]
 
 
 @router.post("/", response_model=UserRead, status_code=status.HTTP_201_CREATED)

backend/app/core/config.py

@@ -40,6 +40,11 @@ class Settings(BaseSettings):
     )
     MONITORING_PUBLIC_IP_DISCOVERY_TIMEOUT_SECONDS: float = Field(default=2.5, ge=0.5, le=10)
     MONITORING_SERVER_LOCATION_CACHE_SECONDS: int = Field(default=86400, ge=300, le=604800)
+    MONITORING_IP_GEO_FALLBACK_ENABLED: bool = True
+    MONITORING_IP_GEO_FALLBACK_API_KEY: Optional[str] = None
+    MONITORING_IP_GEO_FALLBACK_TIMEOUT_SECONDS: float = Field(default=2.5, ge=0.5, le=10)
+    MONITORING_IP_GEO_FALLBACK_CACHE_SECONDS: int = Field(default=604800, ge=3600, le=2592000)
+    MONITORING_IP_GEO_FALLBACK_MAX_LOOKUPS: int = Field(default=10, ge=1, le=100)
     MONITORING_ACCESS_LOG_RETENTION_DAYS: int = Field(default=90, ge=7, le=3650)
     MONITORING_METRIC_RETENTION_DAYS: int = Field(default=400, ge=30, le=3650)
     MONITORING_RETENTION_INTERVAL_SECONDS: int = Field(default=86400, ge=60, le=604800)

backend/app/models/user_login_session.py

@@ -11,7 +11,7 @@ from app.db.base_class import Base
 
 
 class UserLoginSession(Base):
-    """Server-side login activity record without storing credentials or raw IPs."""
+    """Server-side login activity record without storing credentials."""
 
     __tablename__ = "user_login_sessions"
 
@@ -26,6 +26,7 @@ class UserLoginSession(Base):
     client_platform: Mapped[str | None] = mapped_column(String(32), nullable=True)
     client_version: Mapped[str | None] = mapped_column(String(64), nullable=True)
     client_source: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    login_ip: Mapped[str | None] = mapped_column(String(45), nullable=True)
     login_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())
     last_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())
     ended_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

backend/app/schemas/user.py

@@ -89,10 +89,14 @@ class UserLoginActivityRead(BaseModel):
     client_type: Literal["web", "desktop"]
     client_platform: Optional[str] = None
     client_version: Optional[str] = None
+    client_source: Optional[str] = None
+    login_ip: Optional[str] = None
+    ip_location: Optional[str] = None
     login_at: datetime
     last_seen_at: datetime
     ended_at: Optional[datetime] = None
     end_reason: Optional[str] = None
+    activity_status: Literal["ONLINE", "OFFLINE", "ENDED"]
 
     model_config = ConfigDict(from_attributes=True)
 

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