cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/services/opsbffsrv/interface/api/caddy/route_api.py

@@ -0,0 +1,250 @@
+"""
+Caddy 路由管理 API 接口
+
+提供路由的 CRUD 操作、同步、统计等功能
+"""
+from typing import (
+    Any,
+    Dict,
+    Optional,
+)
+import http
+
+from linglong_web.utils import logger
+from linglong_web import limiter
+from cancan_microstack.public.schemas.common import APIResponse
+from cancan_microstack.public.schemas.caddy.route import (
+    ToggleRoutePayload,
+)
+from linglong_web import (
+    build_success_response,
+)
+from cancan_microstack.public.schemas.caddy import CaddyRouteCreate, CaddyRouteUpdate
+from cancan_microstack.public.error import HTTPException
+from cancan_microstack.services.opsbffsrv.application.caddy.route_management_app import RouteManagementApp
+
+# 应用层实例
+_route_app = RouteManagementApp()
+
+
+@limiter("20/second")
+async def create_route_handler(route_data: CaddyRouteCreate) -> APIResponse[Dict[str, Any]]:
+    """
+    创建新路由
+    
+    Args:
+        route_data: 路由创建数据
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"创建路由: domain={route_data.domain}, path={route_data.path_pattern}")
+    result = await _route_app.create_route_and_sync(route_data)
+
+    if result.get("status") == "success":
+        return build_success_response(data=result)
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.BAD_REQUEST.value,
+        msg=result.get("message") or result.get("error") or "创建路由失败",
+        detail=str(result)
+    )
+
+
+@limiter("20/second")
+async def update_route_handler(route_id: int, route_data: CaddyRouteUpdate) -> APIResponse[Dict[str, Any]]:
+    """
+    更新路由
+    
+    Args:
+        route_id: 路由ID
+        route_data: 更新数据
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"更新路由: id={route_id}")
+    update_payload = route_data.model_dump(exclude_unset=True)
+    # 确保包含有效更新字段，避免空请求 / Ensure payload carries real updates and reject empty requests
+    if not update_payload:
+        raise HTTPException(
+            status_code=http.HTTPStatus.BAD_REQUEST.value,
+            msg="更新内容不能为空",
+        )
+
+    result = await _route_app.update_route_and_sync(route_id, update_payload)
+
+    if result.get("status") == "success":
+        return build_success_response(data=result)
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.BAD_REQUEST.value,
+        msg=result.get("message") or result.get("error") or "更新路由失败",
+        detail=str(result)
+    )
+
+
+@limiter("20/second")
+async def get_route_handler(route_id: int) -> APIResponse[Dict[str, Any]]:
+    """
+    获取单个路由详情
+    
+    Args:
+        route_id: 路由ID
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"获取路由: id={route_id}")
+    route = await _route_app.get_route(route_id)
+
+    if route:
+        return build_success_response(data=route.model_dump())
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.NOT_FOUND.value,
+        msg="路由不存在"
+    )
+
+
+@limiter("20/second")
+async def list_routes_handler(
+        domain: Optional[str] = None,
+        service_name: Optional[str] = None,
+        is_enabled: Optional[bool] = None
+) -> APIResponse[Dict[str, Any]]:
+    """
+    列出路由（支持过滤）
+    
+    Args:
+        domain: 域名过滤
+        service_name: 服务名称过滤
+        is_enabled: 启用状态过滤
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"列出路由: domain={domain}, service={service_name}, enabled={is_enabled}")
+
+    # 构建过滤条件
+    filters = {}
+    if domain:
+        filters['domain'] = domain
+    if service_name:
+        filters['upstream_service'] = service_name
+    if is_enabled is not None:
+        filters['is_enabled'] = is_enabled
+
+    routes = await _route_app.list_all_routes(filters=filters if filters else None)
+
+    return build_success_response(data={
+        "routes": [r.model_dump() for r in routes],
+        "total": len(routes)
+    })
+
+
+@limiter("10/second")
+async def delete_route_handler(route_id: int) -> APIResponse[Dict[str, Any]]:
+    """
+    删除路由
+    
+    Args:
+        route_id: 路由ID
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"删除路由: id={route_id}")
+    result = await _route_app.delete_route_and_sync(route_id)
+
+    if result.get("status") == "success":
+        return build_success_response(data=result)
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.BAD_REQUEST.value,
+        msg=result.get("message") or result.get("error") or "删除路由失败",
+        detail=str(result)
+    )
+
+
+@limiter("10/second")
+async def toggle_route_handler(route_id: int, payload: Optional[ToggleRoutePayload] = None) -> APIResponse[
+    Dict[str, Any]]:
+    """
+    切换路由启用状态
+    
+    Args:
+        route_id: 路由ID
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"切换路由状态: id={route_id}")
+    target_enabled = payload.enabled if payload else None
+    # 支持指定目标状态，默认自动取反 / Allow explicit target state while auto-inverting when absent
+    result = await _route_app.toggle_route_and_sync(route_id, target_enabled)
+
+    if result.get("status") == "success":
+        return build_success_response(data=result)
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.BAD_REQUEST.value,
+        msg=result.get("message") or result.get("error") or "切换路由状态失败",
+        detail=str(result)
+    )
+
+
+@limiter("5/second")
+async def sync_all_routes_handler() -> APIResponse[Dict[str, Any]]:
+    """
+    同步所有路由到 Caddy
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info("同步所有路由到 Caddy")
+    result = await _route_app.sync_all_routes()
+
+    if result.get("status") == "success":
+        return build_success_response(data=result)
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+        msg=result.get("message", "同步路由失败"),
+        detail=str(result)
+    )
+
+
+@limiter("20/second")
+async def get_route_statistics_handler() -> APIResponse[Dict[str, Any]]:
+    """
+    获取路由统计信息
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info("获取路由统计信息")
+    stats = await _route_app.get_route_statistics()
+
+    return build_success_response(data=stats)
+
+
+@limiter("20/second")
+async def get_routes_by_domain_handler(domain: str) -> APIResponse[Dict[str, Any]]:
+    """
+    根据域名获取路由列表
+    
+    Args:
+        domain: 域名
+    
+    Returns:
+        统一响应格式
+    """
+    logger.info(f"根据域名获取路由: domain={domain}")
+    routes = await _route_app.get_routes_by_domain(domain)
+
+    return build_success_response(data={
+        "domain": domain,
+        "routes": [r.model_dump() for r in routes],
+        "total": len(routes)
+    })

cancan_microstack/services/opsbffsrv/interface/api/caddy/stats_api.py

@@ -0,0 +1,243 @@
+"""
+Caddy 统计分析 API 接口
+
+提供实时统计、趋势分析、Top 排行等功能
+Provides realtime statistics, trend analysis, and top rankings for Caddy traffic
+"""
+from typing import (
+    List,
+    Optional,
+)
+import http
+
+from linglong_web.utils import logger
+from cancan_microstack.public.const.opsbffsrv_error import OpsbffsrvCaddyStatsErrorCode
+from cancan_microstack.public.schemas.caddy import (
+    CaddyStats,
+    RealtimeStatsResponse,
+    GlobalTrendResponse,
+    ServiceTrendResponse,
+    RouteTrendResponse,
+    TopDimensionResponse,
+    CleanupStatsResponse,
+)
+from cancan_microstack.public.schemas.common import APIResponse
+from linglong_web import build_success_response
+from linglong_web import limiter
+from cancan_microstack.public.error import HTTPException
+from cancan_microstack.services.opsbffsrv.application.caddy.stats_aggregation_app import StatsAggregationApp
+
+# 应用层实例 / Application layer instance
+_stats_app = StatsAggregationApp()
+
+
+def _check_result_or_raise(
+        result: Optional[dict],
+        error_code: OpsbffsrvCaddyStatsErrorCode,
+        default_message: str,
+) -> dict:
+    """验证应用层返回的结果字典，失败则抛出异常"""
+
+    if not isinstance(result, dict):
+        raise HTTPException(
+            status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+            error_code=error_code,
+            msg=default_message
+        )
+
+    if result.get("status") != "success":
+        message = result.get("error") or default_message
+        raise HTTPException(
+            status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+            error_code=error_code,
+            msg=message
+        )
+
+    return result
+
+
+def _normalize_stats_sequence(raw_items: List[object]) -> List[CaddyStats]:
+    """将原始数据转换为 CaddyStats 列表
+    Normalize raw stats payload into a list of CaddyStats models
+    """
+
+    normalized: List[CaddyStats] = []
+    for item in raw_items:
+        if isinstance(item, CaddyStats):
+            normalized.append(item)
+        else:
+            normalized.append(CaddyStats.model_validate(item))
+    return normalized
+
+
+@limiter("30/second")
+async def get_realtime_global_stats_handler() -> APIResponse[RealtimeStatsResponse]:
+    """获取实时全局统计 / Fetch realtime global statistics"""
+
+    logger.info("获取实时全局统计")
+    stats = await _stats_app.get_realtime_global_stats()
+    payload = RealtimeStatsResponse(stats=stats)
+    return build_success_response(data=payload)
+
+
+@limiter("30/second")
+async def get_realtime_service_stats_handler(service_name: str) -> APIResponse[RealtimeStatsResponse]:
+    """获取实时服务统计 / Fetch realtime statistics for specific service"""
+
+    logger.info("获取实时服务统计: service=%s", service_name)
+    stats = await _stats_app.get_realtime_service_stats(service_name)
+    if stats:
+        payload = RealtimeStatsResponse(stats=stats)
+        return build_success_response(data=payload)
+
+    raise HTTPException(
+        status_code=http.HTTPStatus.NOT_FOUND.value,
+        error_code=OpsbffsrvCaddyStatsErrorCode.REALTIME_SERVICE_NOT_FOUND,
+        msg="服务统计不存在"
+    )
+
+
+@limiter("20/second")
+async def get_global_trend_handler(
+        period: str = "hourly",
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+) -> APIResponse[GlobalTrendResponse]:
+    """获取全局趋势数据 / Fetch global traffic trend"""
+
+    logger.info("获取全局趋势: period=%s", period)
+    raw_result = await _stats_app.get_global_trend(period, start_time, end_time)
+    result = _check_result_or_raise(
+        raw_result,
+        OpsbffsrvCaddyStatsErrorCode.GLOBAL_TREND_FAILED,
+        "获取全局趋势失败",
+    )
+
+    trend_items = _normalize_stats_sequence(result.get("data", [])) if result else []
+    payload = GlobalTrendResponse(
+        period=result.get("period", period),
+        hours=result.get("hours", 0),
+        trend=trend_items,
+    )
+    return build_success_response(data=payload)
+
+
+@limiter("20/second")
+async def get_service_trend_handler(
+        service_name: str,
+        period: str = "hourly",
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+) -> APIResponse[ServiceTrendResponse]:
+    """获取服务趋势数据 / Fetch service-specific trend"""
+
+    logger.info("获取服务趋势: service=%s, period=%s", service_name, period)
+    raw_result = await _stats_app.get_service_trend(service_name, period, start_time, end_time)
+    result = _check_result_or_raise(
+        raw_result,
+        OpsbffsrvCaddyStatsErrorCode.SERVICE_TREND_FAILED,
+        "获取服务趋势失败",
+    )
+
+    trend_items = _normalize_stats_sequence(result.get("data", [])) if result else []
+    payload = ServiceTrendResponse(
+        service_name=result.get("service", service_name),
+        period=result.get("period", period),
+        hours=result.get("hours", 0),
+        trend=trend_items,
+    )
+    return build_success_response(data=payload)
+
+
+@limiter("20/second")
+async def get_route_trend_handler(
+        route_id: int,
+        period: str = "hourly",
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+) -> APIResponse[RouteTrendResponse]:
+    """获取路由趋势数据 / Fetch route-specific trend"""
+
+    logger.info("获取路由趋势: route_id=%s, period=%s", route_id, period)
+    raw_result = await _stats_app.get_route_trend(route_id, period, start_time, end_time)
+    result = _check_result_or_raise(
+        raw_result,
+        OpsbffsrvCaddyStatsErrorCode.ROUTE_TREND_FAILED,
+        "获取路由趋势失败",
+    )
+
+    trend_items = _normalize_stats_sequence(result.get("data", [])) if result else []
+    payload = RouteTrendResponse(
+        route_id=route_id,
+        period=result.get("period", period),
+        hours=result.get("hours", 0),
+        trend=trend_items,
+    )
+    return build_success_response(data=payload)
+
+
+@limiter("20/second")
+async def get_top_countries_handler(
+        limit: int = 10,
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+) -> APIResponse[TopDimensionResponse]:
+    """获取访问量 Top 国家 / Fetch top countries by traffic volume"""
+
+    logger.info("获取Top国家: limit=%s", limit)
+    raw_result = await _stats_app.get_top_countries(limit, start_time, end_time)
+    result = _check_result_or_raise(
+        raw_result,
+        OpsbffsrvCaddyStatsErrorCode.TOP_COUNTRY_FAILED,
+        "获取Top国家失败",
+    )
+
+    items = _normalize_stats_sequence(result.get("data", [])) if result else []
+    payload = TopDimensionResponse(
+        period=result.get("period", "hour"),
+        limit=limit,
+        items=items,
+    )
+    return build_success_response(data=payload)
+
+
+@limiter("20/second")
+async def get_top_ips_handler(
+        limit: int = 10,
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+) -> APIResponse[TopDimensionResponse]:
+    """获取访问量 Top IP / Fetch top IPs by request volume"""
+
+    logger.info("获取Top IP: limit=%s", limit)
+    raw_result = await _stats_app.get_top_ips(limit, start_time, end_time)
+    result = _check_result_or_raise(
+        raw_result,
+        OpsbffsrvCaddyStatsErrorCode.TOP_IP_FAILED,
+        "获取Top IP失败",
+    )
+
+    items = _normalize_stats_sequence(result.get("data", [])) if result else []
+    payload = TopDimensionResponse(
+        period=result.get("period", "hour"),
+        limit=limit,
+        items=items,
+    )
+    return build_success_response(data=payload)
+
+
+@limiter("5/second")
+async def cleanup_old_stats_handler(days: int = 90) -> APIResponse[CleanupStatsResponse]:
+    """清理旧统计数据 / Cleanup outdated statistics records"""
+
+    logger.info("清理旧统计数据: days=%s", days)
+    raw_result = await _stats_app.cleanup_old_stats(days)
+    result = _check_result_or_raise(
+        raw_result,
+        OpsbffsrvCaddyStatsErrorCode.CLEANUP_FAILED,
+        "清理旧统计数据失败",
+    )
+
+    message = result.get("message", "清理完成") if result else "清理完成"
+    payload = CleanupStatsResponse(message=message)
+    return build_success_response(data=payload)

cancan_microstack/services/opsbffsrv/interface/api/db_admin_api.py

@@ -0,0 +1,62 @@
+"""数据库结构管理 API 处理器 / API handlers for database schema management tasks."""
+from typing import Optional
+
+from linglong_web import build_success_response
+
+from cancan_microstack.public.schemas.common import APIResponse
+from cancan_microstack.public.schemas.opsbffsrv.db_admin import (
+    SchemaApplyRequest,
+    SchemaDiffRequest,
+    SchemaOperationResponse,
+    SchemaRebuildDatabaseRequest,
+    SchemaRebuildTablesRequest,
+)
+from cancan_microstack.services.opsbffsrv.application.db_admin_app import DatabaseAdminApp
+
+# 应用层实例（懒加载）/ Lazily instantiated application layer
+_db_admin_app: Optional[DatabaseAdminApp] = None
+
+
+def _get_app() -> DatabaseAdminApp:
+    """获取数据库管理应用层实例 / Retrieve the database admin application instance."""
+
+    global _db_admin_app
+    if _db_admin_app is None:
+        _db_admin_app = DatabaseAdminApp()
+    return _db_admin_app
+
+
+async def schema_apply_handler(
+        payload: SchemaApplyRequest,
+) -> APIResponse[SchemaOperationResponse]:
+    """执行模式应用操作 / Apply canonical schema definitions."""
+
+    result = await _get_app().ensure_schema(payload)
+    return build_success_response(data=result)
+
+
+async def schema_diff_handler(
+        payload: SchemaDiffRequest,
+) -> APIResponse[SchemaOperationResponse]:
+    """执行模式比对操作 / Inspect schema drift without applying changes."""
+
+    result = await _get_app().diff_schema(payload)
+    return build_success_response(data=result)
+
+
+async def schema_rebuild_database_handler(
+        payload: SchemaRebuildDatabaseRequest,
+) -> APIResponse[SchemaOperationResponse]:
+    """重建整个数据库 / Rebuild an entire database."""
+
+    result = await _get_app().rebuild_database(payload)
+    return build_success_response(data=result)
+
+
+async def schema_rebuild_tables_handler(
+        payload: SchemaRebuildTablesRequest,
+) -> APIResponse[SchemaOperationResponse]:
+    """重建指定数据表 / Rebuild selected tables."""
+
+    result = await _get_app().rebuild_tables(payload)
+    return build_success_response(data=result)

cancan_microstack/services/opsbffsrv/interface/api/db_init_api.py

@@ -0,0 +1,109 @@
+"""
+数据库初始化 API
+提供数据库初始化和增量构建的 HTTP 接口
+"""
+from linglong_web import build_success_response
+from linglong_web.utils import logger
+
+from cancan_microstack.public.schemas.common import APIResponse
+from cancan_microstack.public.schemas.opsbffsrv.db_init import (
+    DatabaseInitRequest,
+    DatabaseIncrementalBuildRequest,
+    DatabaseBuildResult,
+    DatabaseStatus,
+)
+from cancan_microstack.services.opsbffsrv.application.db_init_app import DatabaseInitApp
+
+# 应用层实例（懒加载）
+_db_init_app = None
+
+
+def _get_app():
+    """获取应用层实例"""
+    global _db_init_app
+    if _db_init_app is None:
+        _db_init_app = DatabaseInitApp()
+    return _db_init_app
+
+
+async def initialize_databases_handler(
+        request: DatabaseInitRequest,
+) -> APIResponse[DatabaseBuildResult]:
+    """
+    一键初始化所有数据库
+    
+    POST /v1/opsbffsrv/db_init/initialize
+    
+    Body:
+    {
+        "force": false,  // 是否强制重建（会删除已有数据）
+        "databases": ["infra", "ops", "biz"]  // 可选，不传则初始化全部
+    }
+    
+    适用场景：
+    - 首次部署，需要创建所有数据库和表
+    - 测试环境重置
+    """
+    logger.info(f"Initialize databases request: {request}")
+    app = _get_app()
+    result = await app.initialize_all_databases(request)
+
+    return build_success_response(data=result)
+
+
+async def incremental_build_handler(
+        request: DatabaseIncrementalBuildRequest,
+) -> APIResponse[DatabaseBuildResult]:
+    """
+    增量构建数据库和表
+    
+    POST /v1/opsbffsrv/db_init/incremental
+    
+    Body:
+    {
+        "databases": ["infra", "ops"],  // 可选，不传则处理全部数据库
+        "tables": ["service_config_tbl"]  // 可选，不传则处理全部表
+    }
+    
+    逻辑：
+    - 数据库不存在则创建，存在则跳过
+    - 表不存在则创建，存在则跳过
+    
+    适用场景：
+    - 新增数据库或表
+    - 修复缺失的数据库/表
+    - 开发环境同步
+    """
+    logger.info(f"Incremental build request: {request}")
+    app = _get_app()
+    result = await app.incremental_build(request)
+
+    return build_success_response(data=result)
+
+
+async def get_database_status_handler() -> APIResponse[DatabaseStatus]:
+    """
+    获取数据库状态
+    
+    GET /v1/opsbffsrv/db_init/status
+    
+    返回：
+    {
+        "success": true,
+        "data": {
+            "databases": [
+                {
+                    "name": "infra",
+                    "exists": true,
+                    "tables": ["service_config_tbl", "service_info_tbl", ...]
+                },
+                ...
+            ],
+            "ddl_path": "/path/to/ddl"
+        }
+    }
+    """
+    app = _get_app()
+    status = await app.get_database_status()
+
+    return build_success_response(data=status)