cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/public/logging/mq_handler.py

@@ -0,0 +1,279 @@
+"""
+本模块提供了一个可重用的日志处理器，用于将日志记录发布到 RabbitMQ 交换机。
+This module provides a reusable logging handler for publishing log records to a RabbitMQ exchange.
+"""
+import asyncio
+import logging
+import os
+import socket
+import threading
+from concurrent.futures import Future
+from datetime import (
+    datetime,
+    timezone,
+)
+from typing import (
+    Any,
+    Dict,
+)
+
+import aio_pika
+import orjson
+from aio_pika import (
+    DeliveryMode,
+    ExchangeType,
+    Message,
+    RobustConnection,
+)
+from nanoid import generate
+
+from cancan_microstack.public.const.app_consts import LogLevelEnum
+from cancan_microstack.public.schemas.logging.log_event import LogEventCreate
+from linglong_web.utils import get_request_id
+from linglong_web.utils import logger as app_logger
+
+
+def build_log_routing_key(template: str, service_name: str, level: LogLevelEnum) -> str:
+    """构建日志路由键 / Build log routing key."""
+    try:
+        return template.format(service=service_name, level=level.value.lower())
+    except KeyError:
+        return f"logs.business.{service_name}.{level.value.lower()}"
+
+
+class RabbitMQHandler(logging.Handler):
+    """
+    一个将日志记录异步发布到 RabbitMQ 交换机 (Exchange) 的日志处理器。
+    它的设计是线程安全的，旨在连接同步日志框架与异步 RabbitMQ 客户端 (`aio_pika`)。
+
+    A logging handler that asynchronously publishes log records to a RabbitMQ exchange.
+    It is designed to be thread-safe and to bridge the synchronous logging framework
+    with an asynchronous RabbitMQ client (`aio_pika`).
+    """
+
+    def __init__(
+            self,
+            *,
+            connection: RobustConnection,
+            service_name: str,
+            exchange_name: str,
+            routing_template: str = "log.{service}.{level}",
+            instance_id: str | None = None,
+            loop: asyncio.AbstractEventLoop | None = None,
+    ):
+        """
+        初始化处理器。
+        Initializes the handler.
+
+        Args:
+            connection: 一个 aio_pika 的 RobustConnection 实例。/ An instance of aio_pika's RobustConnection.
+            service_name: 当前服务的名称。/ Name of the current service.
+            exchange_name: 要发布到的 RabbitMQ 交换机名称。/ Name of the RabbitMQ exchange to publish to.
+            instance_id: 服务实例的唯一标识符。如果未提供，将自动生成。/ A unique identifier for the service instance. Auto-generated if not provided.
+            loop: 运行 aio_pika 的事件循环。如果未提供，将获取当前正在运行的循环。/ The event loop running aio_pika. Gets the current running loop if not provided.
+        """
+        super().__init__()
+        self._connection = connection
+        self._service_name = service_name
+        self._exchange_name = exchange_name
+        self._routing_template = routing_template
+        self._instance_id = instance_id or generate(size=12)
+        self._loop = loop or asyncio.get_running_loop()
+
+        self._channel: aio_pika.RobustChannel | None = None
+        self._exchange: aio_pika.Exchange | None = None
+
+        self._host = os.environ.get("HOSTNAME") or socket.gethostname()
+        self._cached_ip: str | None = None
+
+        self._pending_futures: set[Future] = set()
+        self._pending_lock = threading.Lock()
+
+        # 在事件循环中初始化 Channel 和 Exchange
+        # Initialize channel and exchange in the event loop
+        asyncio.run_coroutine_threadsafe(self._initialize_mq_objects(), self._loop)
+
+    async def _initialize_mq_objects(self):
+        """
+        创建 Channel 并声明 Exchange。此方法应在目标事件循环中运行。
+        Create channel and declare exchange. This should be run in the target event loop.
+        """
+        try:
+            self._channel = await self._connection.channel()
+            self._exchange = await self._channel.declare_exchange(
+                self._exchange_name, ExchangeType.TOPIC, durable=True
+            )
+            app_logger.info(
+                "RabbitMQHandler initialized for service '%s' on exchange '%s'",
+                self._service_name,
+                self._exchange_name,
+            )
+        except Exception as e:
+            app_logger.error("Failed to initialize RabbitMQHandler: %s", e, exc_info=True)
+            # 在这里可以更优雅地处理错误，例如设置一个失败状态
+            # You might want to handle this more gracefully, e.g., by setting a failed state.
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        格式化日志记录，并将其调度到事件循环上进行发布。
+        这是从同步的 logging 调用到异步世界的桥梁。
+
+        Formats the log record and schedules it for publishing on the event loop.
+        This is the bridge from the synchronous logging call to the asynchronous world.
+        """
+        try:
+            # 将日志级别字符串转换为枚举成员
+            # Convert log level string to the enum member
+            level = LogLevelEnum(record.levelname.upper())
+        except (KeyError, ValueError):
+            # 对自定义日志级别，默认使用 INFO
+            # Default to INFO for custom log levels
+            level = LogLevelEnum.INFO
+
+        try:
+            # 构建日志事件模型和路由键
+            # Build the log event model and routing key
+            event = self._build_log_event(record, level)
+            routing_key = build_log_routing_key(self._routing_template, self._service_name, level)
+
+            # 线程安全地在事件循环中调度发布任务
+            # Thread-safely schedule the publish task in the event loop
+            future = asyncio.run_coroutine_threadsafe(self._publish(event, routing_key), self._loop)
+
+            # 追踪待处理的 future，以便在关闭时可以等待它们
+            # Track the pending future so we can wait for it on close
+            with self._pending_lock:
+                self._pending_futures.add(future)
+            future.add_done_callback(self._on_future_done)
+
+        except Exception:
+            self.handleError(record)
+
+    def _on_future_done(self, future: Future) -> None:
+        """
+        当一个 future 完成时的回调，将其从待处理集合中移除。
+        Callback for when a future is done to remove it from the pending set.
+        """
+        with self._pending_lock:
+            self._pending_futures.discard(future)
+        try:
+            # 调用 result() 可以触发并记录在协程中发生的任何异常
+            # Calling result() can trigger and log any exceptions that occurred in the coroutine
+            future.result()
+        except Exception as e:
+            # 这是 `_publish` 协程中的异常浮现的地方
+            # This is where exceptions from the `_publish` coroutine will be surfaced.
+            app_logger.warning("Failed to publish log to RabbitMQ: %s", e)
+
+    async def _publish(self, event: LogEventCreate, routing_key: str) -> None:
+        """
+        实际执行消息发布的协程。
+        The actual coroutine that publishes the message.
+        """
+        if not self._exchange:
+            # 如果初始化失败或仍在进行中，exchange 可能不可用
+            # This can happen if initialization failed or is still in progress.
+            app_logger.warning("RabbitMQ exchange not available, dropping log message.")
+            return
+
+        # 序列化并创建 aio_pika 消息对象
+        # Serialize and create an aio_pika message object
+        body = orjson.dumps(event.model_dump(mode="json"))
+        message = Message(
+            body=body,
+            delivery_mode=DeliveryMode.PERSISTENT,
+            content_type="application/json",
+        )
+        # 发布消息
+        # Publish the message
+        await self._exchange.publish(message, routing_key=routing_key, mandatory=False)
+
+    def _build_log_event(self, record: logging.LogRecord, level: LogLevelEnum) -> LogEventCreate:
+        """
+        从 logging.LogRecord 构建一个 LogEventCreate Pydantic 模型。
+        Constructs a LogEventCreate Pydantic model from a LogRecord.
+        """
+        return LogEventCreate(
+            event_id=generate(size=16),
+            service_name=self._service_name,
+            instance_id=self._instance_id,
+            level=level,
+            message=record.getMessage(),
+            timestamp=datetime.fromtimestamp(record.created, tz=timezone.utc),
+            ip=self._resolve_ip(),
+            host=self._host,
+            logger_name=record.name,
+            file=record.pathname,
+            line_no=record.lineno,
+            func_name=record.funcName,
+            trace_id=get_request_id(),
+            metadata=self._collect_metadata(record),
+        )
+
+    def _collect_metadata(self, record: logging.LogRecord) -> Dict[str, Any]:
+        """
+        从日志记录中收集并字符串化元数据。
+        Collects and stringifies metadata from the log record.
+        """
+        metadata: Dict[str, Any] = {
+            "module": record.module,
+            "process": record.process,
+            "thread": record.thread,
+        }
+        # 添加传递给 logger 的任何额外字段，确保它们是可序列化的
+        # Add any extra fields passed to the logger, ensuring they are serializable.
+        standard_keys = {"args", "asctime", "created", "exc_info", "exc_text", "filename", "funcName",
+                         "levelname", "levelno", "lineno", "module", "msecs", "message", "msg", "name",
+                         "pathname", "process", "processName", "relativeCreated", "stack_info", "thread",
+                         "threadName"}
+        for key, value in record.__dict__.items():
+            if key not in standard_keys:
+                metadata[key] = str(value)  # 为安全起见，进行简单的字符串转换
+        return metadata
+
+    def _resolve_ip(self) -> str:
+        """
+        解析主机的非环回 IP 地址。
+        Resolves the primary non-loopback IP address of the host.
+        """
+        if self._cached_ip:
+            return self._cached_ip
+        try:
+            # 连接到一个公共 DNS 服务器以找到主出站 IP
+            # Connect to a public DNS server to find the primary outbound IP
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+                s.settimeout(0.1)
+                s.connect(("8.8.8.8", 80))
+                ip_addr = s.getsockname()[0]
+        except Exception:
+            ip_addr = "127.0.0.1"
+        self._cached_ip = ip_addr
+        return ip_addr
+
+    async def close_async(self) -> None:
+        """
+        优雅地关闭 Channel。
+        Gracefully close the channel.
+        """
+        if self._channel and not self._channel.is_closed:
+            await self._channel.close()
+            app_logger.info("RabbitMQ channel closed.")
+
+    def close(self) -> None:
+        """
+        关闭处理器，并等待任何待处理的日志消息被发送。
+        Closes the handler, waiting for any pending log messages to be sent.
+        """
+        # 等待待处理的 futures 完成
+        # Wait for pending futures to complete
+        pending = list(self._pending_futures)
+        if pending:
+            # 这是一个同步上下文，所以我们不能 await
+            # 我们在这里能做的就是记录下我们正在放弃待处理的消息
+            # This is a synchronous context, so we can't await.
+            # We can't do much here other than log that we are abandoning pending messages.
+            app_logger.info("Closing RabbitMQHandler with %d pending messages.", len(pending))
+
+        if self._loop.is_running():
+            asyncio.run_coroutine_threadsafe(self.close_async(), self._loop)
+        super().close()

cancan_microstack/public/schemas/__init__.py

@@ -0,0 +1 @@
+"""Shared schema models provided by Cancan Microstack."""

cancan_microstack/public/schemas/caddy/__init__.py

@@ -0,0 +1,381 @@
+"""
+Caddy 相关的 Pydantic 类型定义
+"""
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+)
+from datetime import datetime
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+from decimal import Decimal
+
+
+# ==================== Caddy Route（路由） ====================
+
+class CaddyRouteCreate(BaseModel):
+    """创建路由的请求模型"""
+    route_name: str = Field(..., description="路由名称（唯一标识）", min_length=1, max_length=100)
+    domain: str = Field(..., description="域名", min_length=1, max_length=255)
+    path_pattern: str = Field(..., description="路径匹配模式", min_length=1, max_length=500)
+    upstream_service: str = Field(..., description="上游服务名称", min_length=1, max_length=100)
+    upstream_host: str = Field(..., description="上游主机", min_length=1, max_length=100)
+    upstream_port: int = Field(..., description="上游端口", ge=1, le=65535)
+    strip_path_prefix: Optional[str] = Field(None, description="去除路径前缀", max_length=200)
+    add_path_prefix: Optional[str] = Field(None, description="添加路径前缀", max_length=200)
+    enable_https: bool = Field(default=True, description="是否启用 HTTPS")
+    force_https: bool = Field(default=True, description="是否强制 HTTPS")
+    enable_waf: bool = Field(default=True, description="是否启用 WAF")
+    waf_rule_set: str = Field(default="default", description="WAF 规则集")
+    load_balance_strategy: str = Field("round_robin", description="负载均衡策略")
+    health_check_path: Optional[str] = Field(default=None, description="健康检查路径", max_length=200)
+    health_check_interval: int = Field(default=30, description="健康检查间隔（秒）", ge=5)
+    is_enabled: bool = Field(default=True, description="是否启用")
+    priority: int = Field(default=100, description="优先级", ge=0)
+    route_metadata: Optional[Dict[str, Any]] = Field(default=None, description="路由附加元数据")
+    description: Optional[str] = Field(default=None, description="路由描述")
+
+
+class CaddyRouteUpdate(BaseModel):
+    """更新路由的请求模型（所有字段可选）"""
+    domain: Optional[str] = Field(None, description="域名", min_length=1, max_length=255)
+    path_pattern: Optional[str] = Field(None, description="路径匹配模式", min_length=1, max_length=500)
+    upstream_service: Optional[str] = Field(None, description="上游服务名称", min_length=1, max_length=100)
+    upstream_host: Optional[str] = Field(None, description="上游主机", min_length=1, max_length=100)
+    upstream_port: Optional[int] = Field(None, description="上游端口", ge=1, le=65535)
+    strip_path_prefix: Optional[str] = Field(None, description="去除路径前缀", max_length=200)
+    add_path_prefix: Optional[str] = Field(None, description="添加路径前缀", max_length=200)
+    enable_https: Optional[bool] = Field(None, description="是否启用 HTTPS")
+    force_https: Optional[bool] = Field(None, description="是否强制 HTTPS")
+    enable_waf: Optional[bool] = Field(None, description="是否启用 WAF")
+    waf_rule_set: Optional[str] = Field(None, description="WAF 规则集")
+    load_balance_strategy: Optional[str] = Field(None, description="负载均衡策略")
+    health_check_path: Optional[str] = Field(None, description="健康检查路径", max_length=200)
+    health_check_interval: Optional[int] = Field(None, description="健康检查间隔（秒）", ge=5)
+    is_enabled: Optional[bool] = Field(None, description="是否启用")
+    priority: Optional[int] = Field(None, description="优先级", ge=0)
+    route_metadata: Optional[Dict[str, Any]] = Field(None, description="路由附加元数据")
+    description: Optional[str] = Field(None, description="路由描述")
+
+
+class CaddyRoute(BaseModel):
+    """路由数据模型"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: Optional[int] = None
+    route_name: str
+    domain: str
+    path_pattern: str
+    upstream_service: str
+    upstream_host: str
+    upstream_port: int
+    strip_path_prefix: Optional[str] = None
+    add_path_prefix: Optional[str] = None
+    enable_https: bool = True
+    force_https: bool = True
+    enable_waf: bool = True
+    waf_rule_set: str = "default"
+    load_balance_strategy: str = "round_robin"
+    health_check_path: Optional[str] = None
+    health_check_interval: int = 30
+    is_enabled: bool = True
+    priority: int = 100
+    route_metadata: Optional[Dict[str, Any]] = None
+    description: Optional[str] = None
+    created_time: Optional[datetime] = None
+    update_time: Optional[datetime] = None
+
+
+
+# ==================== Caddy Rate Limit（限流） ====================
+
+class CaddyRateLimitCreate(BaseModel):
+    """创建限流规则的请求模型"""
+    rule_name: str = Field(..., description="规则名称（唯一标识）", min_length=1, max_length=100)
+    description: Optional[str] = Field(None, description="规则描述")
+    match_type: str = Field(..., description="匹配类型（path/domain/ip/header/all）")
+    match_pattern: Optional[str] = Field(None, description="匹配模式", max_length=500)
+    match_domain: Optional[str] = Field(None, description="匹配域名", max_length=255)
+    limit_type: str = Field("request", description="限流类型（request/bandwidth）")
+    limit_value: int = Field(..., description="限流值", ge=1)
+    limit_window: int = Field(60, description="时间窗口（秒）", ge=1)
+    limit_key: str = Field("ip", description="限流键（ip/header/cookie/path）")
+    burst_size: int = Field(0, description="突发流量大小", ge=0)
+    block_status_code: int = Field(429, description="被限流时的状态码", ge=100, le=599)
+    block_message: str = Field("Too Many Requests", description="被限流时的消息", max_length=500)
+    whitelist_ips: Optional[List[str]] = Field(None, description="IP 白名单")
+    blacklist_ips: Optional[List[str]] = Field(None, description="IP 黑名单")
+    is_enabled: bool = Field(True, description="是否启用")
+    priority: int = Field(100, description="优先级", ge=0)
+    rule_metadata: Optional[Dict[str, Any]] = Field(default=None, description="限流附加元数据")
+
+
+class CaddyRateLimitUpdate(BaseModel):
+    """更新限流规则的请求模型（所有字段可选）"""
+    description: Optional[str] = Field(None, description="规则描述")
+    match_type: Optional[str] = Field(None, description="匹配类型（path/domain/ip/header/all）")
+    match_pattern: Optional[str] = Field(None, description="匹配模式", max_length=500)
+    match_domain: Optional[str] = Field(None, description="匹配域名", max_length=255)
+    limit_type: Optional[str] = Field(None, description="限流类型（request/bandwidth）")
+    limit_value: Optional[int] = Field(None, description="限流值", ge=1)
+    limit_window: Optional[int] = Field(None, description="时间窗口（秒）", ge=1)
+    limit_key: Optional[str] = Field(None, description="限流键（ip/header/cookie/path）")
+    burst_size: Optional[int] = Field(None, description="突发流量大小", ge=0)
+    block_status_code: Optional[int] = Field(None, description="被限流时的状态码", ge=100, le=599)
+    block_message: Optional[str] = Field(None, description="被限流时的消息", max_length=500)
+    whitelist_ips: Optional[List[str]] = Field(None, description="IP 白名单")
+    blacklist_ips: Optional[List[str]] = Field(None, description="IP 黑名单")
+    is_enabled: Optional[bool] = Field(None, description="是否启用")
+    priority: Optional[int] = Field(None, description="优先级", ge=0)
+    rule_metadata: Optional[Dict[str, Any]] = Field(None, description="限流附加元数据")
+
+
+class CaddyRateLimit(BaseModel):
+    """限流规则数据模型"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: Optional[int] = None
+    rule_name: str
+    description: Optional[str] = None
+    match_type: str
+    match_pattern: Optional[str] = None
+    match_domain: Optional[str] = None
+    limit_type: str = "request"
+    limit_value: int
+    limit_window: int = 60
+    limit_key: str = "ip"
+    burst_size: int = 0
+    block_status_code: int = 429
+    block_message: str = "Too Many Requests"
+    whitelist_ips: Optional[List[str]] = None
+    blacklist_ips: Optional[List[str]] = None
+    is_enabled: bool = True
+    priority: int = 100
+    rule_metadata: Optional[Dict[str, Any]] = None
+    created_time: Optional[datetime] = None
+    update_time: Optional[datetime] = None
+
+
+
+# ==================== Caddy Access Log（访问日志） ====================
+
+class CaddyAccessLog(BaseModel):
+    """访问日志数据模型"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: Optional[int] = None
+    request_id: str
+    timestamp: datetime
+    client_ip: str
+    client_port: Optional[int] = None
+    user_agent: Optional[str] = None
+    referer: Optional[str] = None
+    country: Optional[str] = None
+    country_code: Optional[str] = None
+    region: Optional[str] = None
+    city: Optional[str] = None
+    latitude: Optional[Decimal] = None
+    longitude: Optional[Decimal] = None
+    timezone: Optional[str] = None
+    isp: Optional[str] = None
+    method: str
+    protocol: Optional[str] = None
+    host: Optional[str] = None
+    path: str
+    query_string: Optional[str] = None
+    matched_route: Optional[str] = None
+    upstream_service: Optional[str] = None
+    upstream_host: Optional[str] = None
+    upstream_port: Optional[int] = None
+    status_code: int
+    response_size: Optional[int] = None
+    response_time: Optional[int] = None
+    waf_action: Optional[str] = None
+    waf_rule_id: Optional[str] = None
+    waf_score: Optional[int] = None
+    rate_limited: bool = False
+    rate_limit_rule: Optional[str] = None
+    tls_version: Optional[str] = None
+    tls_cipher: Optional[str] = None
+    log_metadata: Optional[Dict[str, Any]] = None
+    created_time: Optional[datetime] = None
+
+
+
+# ==================== Caddy Stats（统计） ====================
+
+class CaddyStats(BaseModel):
+    """统计数据模型"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: Optional[int] = None
+    stat_time: datetime
+    stat_period: str
+    dimension_type: str
+    dimension_value: Optional[str] = None
+    total_requests: int = 0
+    success_requests: int = 0
+    client_error_requests: int = 0
+    server_error_requests: int = 0
+    total_bytes_sent: int = 0
+    total_bytes_received: int = 0
+    avg_response_time: Optional[int] = None
+    min_response_time: Optional[int] = None
+    max_response_time: Optional[int] = None
+    p50_response_time: Optional[int] = None
+    p95_response_time: Optional[int] = None
+    p99_response_time: Optional[int] = None
+    waf_blocked_requests: int = 0
+    waf_logged_requests: int = 0
+    rate_limited_requests: int = 0
+    tls_requests: int = 0
+    non_tls_requests: int = 0
+    unique_ips: int = 0
+    unique_user_agents: int = 0
+    stats_metadata: Optional[Dict[str, Any]] = None
+    created_time: Optional[datetime] = None
+    update_time: Optional[datetime] = None
+
+
+
+class RealtimeStatsResponse(BaseModel):
+    """实时统计响应模型
+    Realtime statistics response model
+    """
+
+    stats: Optional[CaddyStats] = Field(default=None, description="统计数据 / Statistics payload")
+
+
+class GlobalTrendResponse(BaseModel):
+    """全局趋势响应模型
+    Global trend response model
+    """
+
+    period: str = Field(..., description="统计周期（hourly/daily/monthly）/ Aggregation period")
+    hours: int = Field(..., description="聚合的小时数 / Number of aggregated hours")
+    trend: List[CaddyStats] = Field(default_factory=list, description="统计数据序列 / Statistics series")
+
+
+class ServiceTrendResponse(GlobalTrendResponse):
+    """服务趋势响应模型
+    Service trend response model
+    """
+
+    service_name: str = Field(..., description="服务名称 / Service name")
+
+
+class RouteTrendResponse(GlobalTrendResponse):
+    """路由趋势响应模型
+    Route trend response model
+    """
+
+    route_id: int = Field(..., description="路由 ID / Route identifier")
+
+
+class TopDimensionResponse(BaseModel):
+    """Top 维度统计响应模型
+    Top dimension statistics response model
+    """
+
+    period: str = Field(..., description="统计周期 / Aggregation period")
+    limit: int = Field(..., description="返回数量上限 / Maximum number of items")
+    items: List[CaddyStats] = Field(default_factory=list, description="统计项列表 / Statistics items")
+
+
+class CleanupStatsResponse(BaseModel):
+    """统计数据清理结果模型
+    Cleanup statistics response model
+    """
+
+    message: str = Field(..., description="执行结果信息 / Result message")
+
+
+# ==================== Caddy Certificate（证书） ====================
+
+class CaddyCertificateCreate(BaseModel):
+    """创建证书的请求模型"""
+    domain: str = Field(..., description="主域名", min_length=1, max_length=255)
+    alt_domains: Optional[List[str]] = Field(None, description="备用域名列表")
+    auto_renew: bool = Field(True, description="是否自动续期")
+    renew_before_days: int = Field(30, description="提前多少天续期", ge=1, le=90)
+    acme_provider: str = Field("letsencrypt", description="ACME 提供商")
+    acme_email: Optional[str] = Field(None, description="ACME 邮箱", max_length=255)
+    acme_challenge_type: str = Field("http-01", description="ACME 挑战类型（http-01/dns-01）")
+    certificate_metadata: Optional[Dict[str, Any]] = Field(None, description="证书附加元数据")
+
+
+class CaddyCertificateUpdate(BaseModel):
+    """更新证书的请求模型（所有字段可选）"""
+    alt_domains: Optional[List[str]] = Field(None, description="备用域名列表")
+    auto_renew: Optional[bool] = Field(None, description="是否自动续期")
+    renew_before_days: Optional[int] = Field(None, description="提前多少天续期", ge=1, le=90)
+    acme_provider: Optional[str] = Field(None, description="ACME 提供商")
+    acme_email: Optional[str] = Field(None, description="ACME 邮箱", max_length=255)
+    acme_challenge_type: Optional[str] = Field(None, description="ACME 挑战类型（http-01/dns-01）")
+    certificate_metadata: Optional[Dict[str, Any]] = Field(None, description="证书附加元数据")
+
+
+class CaddyCertificate(BaseModel):
+    """证书数据模型"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: Optional[int] = None
+    domain: str
+    alt_domains: Optional[List[str]] = None
+    certificate_pem: Optional[str] = None
+    private_key_pem: Optional[str] = None
+    issuer: Optional[str] = None
+    issued_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+    auto_renew: bool = True
+    renew_before_days: int = 30
+    status: str = "pending"
+    last_renew_attempt: Optional[datetime] = None
+    last_renew_success: Optional[datetime] = None
+    renew_error: Optional[str] = None
+    acme_provider: str = "letsencrypt"
+    acme_email: Optional[str] = None
+    acme_challenge_type: str = "http-01"
+    certificate_metadata: Optional[Dict[str, Any]] = None
+    created_time: Optional[datetime] = None
+    update_time: Optional[datetime] = None
+
+
+
+# ==================== 查询参数模型 ====================
+
+class AccessLogQuery(BaseModel):
+    """访问日志查询参数"""
+    client_ip: Optional[str] = Field(default=None, description="客户端 IP")
+    country: Optional[str] = Field(default=None, description="国家")
+    country_code: Optional[str] = Field(default=None, description="国家代码")
+    upstream_service: Optional[str] = Field(default=None, description="上游服务")
+    matched_route: Optional[str] = Field(default=None, description="匹配的路由")
+    waf_action: Optional[str] = Field(default=None, description="WAF 动作")
+    rate_limited: Optional[bool] = Field(default=None, description="是否被限流")
+    min_response_time: Optional[int] = Field(default=None, description="最小响应时间（毫秒）")
+    max_response_time: Optional[int] = Field(default=None, description="最大响应时间（毫秒）")
+    start_time: Optional[datetime] = Field(default=None, description="开始时间")
+    end_time: Optional[datetime] = Field(default=None, description="结束时间")
+    limit: int = Field(default=100, description="返回数量限制", ge=1, le=1000)
+    offset: int = Field(default=0, description="偏移量", ge=0)
+
+
+class StatsQuery(BaseModel):
+    """统计数据查询参数"""
+    stat_period: Optional[str] = Field(None, description="统计周期（minute/hour/day/month）")
+    dimension_type: Optional[str] = Field(None, description="维度类型（global/service/route/ip/country）")
+    dimension_value: Optional[str] = Field(None, description="维度值")
+    start_time: Optional[datetime] = Field(None, description="开始时间")
+    end_time: Optional[datetime] = Field(None, description="结束时间")
+    limit: int = Field(100, description="返回数量限制", ge=1, le=1000)