Merge pull request #148 from ThreeFish-AI/vk/b1c7-

feat(logging): 实现日志双写（控制台+文件）

Author: ThreeFish-AI

.gitignore

@@ -22,3 +22,6 @@ junit.xml
 config.yaml
 .claude/.prompts.md
 .python-version
+
+# Log files (dual-write logging)
+coding-proxy.log*

src/coding/proxy/cli/__init__.py

@@ -104,11 +104,18 @@ def start(
     # 打印启动品牌横幅
     print_banner(console, host=cfg.server.host, port=cfg.server.port)
 
+    # 解析文件日志路径：未显式配置时使用默认值
+    _file_path: str | None = cfg.logging.file or "coding-proxy.log"
     uvicorn.run(
         fastapi_app,
         host=cfg.server.host,
         port=cfg.server.port,
-        log_config=build_log_config(cfg.logging.level),
+        log_config=build_log_config(
+            level=cfg.logging.level,
+            file_path=_file_path,
+            max_bytes=cfg.logging.max_bytes,
+            backup_count=cfg.logging.backup_count,
+        ),
     )
 
 

src/coding/proxy/config/config.default.yaml

@@ -8,6 +8,9 @@ server:
 
 logging:
   level: "INFO"
+  # file: "coding-proxy.log"          # 文件日志路径；设为 null 或空字符串禁用
+  # max_bytes: 5242880                # 单文件上限（5 MB），触发轮转
+  # backup_count: 5                   # 保留 gzip 压缩备份文件数
 
 # === 降级链路优先级（可选） ===
 #

src/coding/proxy/config/server.py

@@ -17,8 +17,19 @@ class DatabaseConfig(BaseModel):
 
 
 class LoggingConfig(BaseModel):
+    """日志配置.
+
+    Attributes:
+        level: 控制台日志级别（INFO / WARNING / DEBUG 等）。
+        file: 文件日志路径。为 ``None`` 时使用默认值 ``coding-proxy.log``；
+             设为空字符串可禁用文件日志。
+        max_bytes: 单个日志文件最大字节数（触发轮转）。默认 5 MB。
+        backup_count: 保留的已压缩备份文件数。默认 5。
+    """
     level: str = "INFO"
     file: str | None = None
+    max_bytes: int = 5 * 1024 * 1024
+    backup_count: int = 5
 
 
 __all__ = ["ServerConfig", "DatabaseConfig", "LoggingConfig"]

src/coding/proxy/logging/__init__.py

@@ -1,11 +1,92 @@
-"""日志模块."""
+"""日志模块.
+
+提供 uvicorn 兼容的 dictConfig 构建、JSON 结构化格式化器、
+以及 gzip 压缩轮转支持。
+"""
 
 from __future__ import annotations
 
+import gzip
+import logging
+import logging.handlers
+import os
+from pathlib import Path
+
+from .formatters import JsonFormatter
+
+# ── 常量 ────────────────────────────────────────────────────────
+
+_DEFAULT_MAX_BYTES = 5 * 1024 * 1024  # 5 MB per file
+_DEFAULT_BACKUP_COUNT = 5  # Keep 5 rotated backups
+_FILE_LOG_LEVEL = "DEBUG"  # File logs capture everything
+
+
+def _gzip_namer(default_name: str) -> str:
+    """RotatingFileHandler namer: 为轮转文件添加 .gz 后缀."""
+    return default_name + ".gz"
+
+
+def _gzip_rotator(source: str, dest: str) -> None:
+    """RotatingFileHandler rotator: 将源文件 gzip 压缩后写入目标.
+
+    流程：
+    1. 读取 source 文件全部内容
+    2. gzip 压缩写入 dest 文件
+    3. 删除 source 原文件
+    """
+    with open(source, "rb") as f_in:
+        data = f_in.read()
+    with open(dest, "wb") as f_out:
+        f_out.write(gzip.compress(data, compresslevel=6))
+    os.remove(source)
+
+
+def _create_rotating_file_handler(
+    *,
+    filename: str,
+    maxBytes: int = _DEFAULT_MAX_BYTES,
+    backupCount: int = _DEFAULT_BACKUP_COUNT,
+    encoding: str = "utf-8",
+) -> logging.handlers.RotatingFileHandler:
+    """创建带 gzip 压缩轮转的 RotatingFileHandler（dictConfig 兼容工厂函数）.
+
+    ``logging.config.dictConfig`` 仅支持通过构造函数 kwargs 配置 handler，
+    而 ``namer`` / ``rotator`` 是实例属性而非构造参数，因此需要通过工厂函数注入。
+    """
+    handler = logging.handlers.RotatingFileHandler(
+        filename=filename,
+        maxBytes=maxBytes,
+        backupCount=backupCount,
+        encoding=encoding,
+    )
+    handler.namer = _gzip_namer
+    handler.rotator = _gzip_rotator
+    return handler
+
 
-def build_log_config(level: str = "INFO") -> dict:
-    """构建 uvicorn log_config，使用 yyyy-MM-dd HH:mm:ss 时间格式."""
-    return {
+def build_log_config(
+    level: str = "INFO",
+    file_path: str | None = None,
+    max_bytes: int = _DEFAULT_MAX_BYTES,
+    backup_count: int = _DEFAULT_BACKUP_COUNT,
+) -> dict:
+    """构建 uvicorn log_config，支持双写（控制台 + 文件）.
+
+    Args:
+        level: 控制台日志级别（默认 INFO）。
+        file_path: 文件日志路径。为 ``None`` 时仅输出到控制台（向后兼容）。
+        max_bytes: 单个日志文件最大字节数（默认 5 MB）。
+        backup_count: 保留的轮转备份文件数（默认 5）。
+
+    Returns:
+        符合 ``logging.config.dictConfig`` 规范的字典。
+
+    双写行为：
+        - 控制台：人类可读格式，级别由 ``level`` 参数控制（handler 级别过滤）
+        - 文件：JSON 结构化格式，固定 DEBUG 级别（捕获所有日志）
+        - 当 ``file_path`` 为 ``None`` 或空字符串时，退化为纯控制台模式（向后兼容）
+    """
+    config: dict = {
         "version": 1,
         "disable_existing_loggers": False,
         "formatters": {
@@ -17,7 +98,7 @@ def build_log_config(level: str = "INFO") -> dict:
             },
             "access": {
                 "()": "uvicorn.logging.AccessFormatter",
-                "fmt": '%(asctime)s %(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
+                'fmt': '%(asctime)s %(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
                 "datefmt": "%Y-%m-%d %H:%M:%S",
             },
         },
@@ -26,11 +107,13 @@ def build_log_config(level: str = "INFO") -> dict:
                 "formatter": "default",
                 "class": "logging.StreamHandler",
                 "stream": "ext://sys.stderr",
+                "level": level,
             },
             "access": {
                 "formatter": "access",
                 "class": "logging.StreamHandler",
                 "stream": "ext://sys.stdout",
+                "level": "INFO",
             },
         },
         "loggers": {
@@ -48,3 +131,53 @@ def build_log_config(level: str = "INFO") -> dict:
             },
         },
     }
+
+    # ── 条件注入：文件日志基础设施 ────────────────────────────
+    if file_path:
+        # 确保日志目录存在
+        log_file = Path(file_path)
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # 注入 JSON formatter
+        config["formatters"]["json"] = {
+            "()": "coding.proxy.logging.formatters.JsonFormatter",
+        }
+
+        # 注入 RotatingFileHandler（gzip 压缩轮转）
+        # 使用工厂函数（而非 class + namer/rotator kwargs），
+        # 因为 dictConfig 不支持将 namer/rotator 作为构造参数传递
+        config["handlers"]["file"] = {
+            "formatter": "json",
+            "()": "coding.proxy.logging._create_rotating_file_handler",
+            "filename": str(log_file.resolve()),
+            "maxBytes": max_bytes,
+            "backupCount": backup_count,
+            "encoding": "utf-8",
+        }
+
+        # 为每个 logger 添加 file handler
+        # 注意：uvicorn.error 无 handlers 键（通过 propagate 继承 uvicorn 的 handler）
+        for logger_name in ("uvicorn", "uvicorn.error", "uvicorn.access", "coding.proxy"):
+            logger_cfg = config["loggers"][logger_name]
+            handlers = logger_cfg.get("handlers", [])
+            if isinstance(handlers, list):
+                handlers.append("file")
+                logger_cfg["handlers"] = handlers
+            else:
+                logger_cfg["handlers"] = [handlers, "file"]
+
+        # Logger 级别设为 DEBUG（让所有消息通过到 file handler）
+        # Console handler 已设 level 过滤，确保控制台仅输出 INFO+
+        config["loggers"]["coding.proxy"]["level"] = _FILE_LOG_LEVEL
+        config["loggers"]["uvicorn"]["level"] = _FILE_LOG_LEVEL
+        config["loggers"]["uvicorn.error"]["level"] = _FILE_LOG_LEVEL
+
+    return config
+
+
+__all__ = [
+    "build_log_config",
+    "JsonFormatter",
+    "_gzip_namer",
+    "_gzip_rotator",
+]

src/coding/proxy/logging/formatters.py

@@ -0,0 +1,51 @@
+"""结构化日志格式化器（JSON 输出）.
+
+为文件日志提供机器可读的 JSON 格式输出，
+与控制台的人类可读格式形成正交双写。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+
+
+class JsonFormatter(logging.Formatter):
+    """将 LogRecord 格式化为单行 JSON 字符串.
+
+    输出字段：
+    - ``timestamp``: ISO 8601 UTC 时间戳
+    - ``level``: 日志级别名称（DEBUG/INFO/WARNING/ERROR）
+    - ``logger``: logger 名称（如 ``coding.proxy.routing.executor``）
+    - ``message``: 格式化后的日志消息
+    - ``exception``: 异常堆栈（仅当存在时）
+
+    设计要点：
+    - 使用 ``ensure_ascii=False`` 支持中文日志内容
+    - 异常信息（exc_info）序列化为 ``exception`` 字段
+    - 时间戳统一使用 UTC ISO 格式，便于跨时区聚合分析
+    - ``sort_keys=True`` 保证输出确定性，便于日志聚合工具处理
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """将 LogRecord 序列化为 JSON 行."""
+        message = record.getMessage()
+
+        exception: str | None = None
+        if record.exc_info and record.exc_info[0] is not None:
+            exception = self.formatException(record.exc_info)
+
+        log_entry: dict[str, object] = {
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            ).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": message,
+        }
+
+        if exception:
+            log_entry["exception"] = exception
+
+        return json.dumps(log_entry, ensure_ascii=False, sort_keys=True)

src/coding/proxy/routing/usage_recorder.py

@@ -66,7 +66,7 @@ def log_model_call(
             )
             if cost_value is not None:
                 cost_str = cost_value.format()
-        logger.info(
+        logger.debug(
             "ModelCall: vendor=%s model_requested=%s model_served=%s "
             "duration=%dms tokens=[in:%d out:%d cache_create:%d cache_read:%d] cost=%s",
             vendor,