fix(logging): 审计日志此前全部被丢弃 + 三层日志轮转方案

## 生产缺陷（实测）

uvicorn 默认 LOGGING_CONFIG 只配置 `uvicorn` / `uvicorn.access`
（propagate=false），**从不配置 root**；root 默认 level=WARNING 且无 handler。
于是应用里 9 个模块 `logging.getLogger(__name__)` 的 INFO 被静默丢弃：

- PROPOSAL §8 要求的凭证审计日志（增删改/pin/账号切换，7 处 logger.info）
  一条都没落盘（grep -c 管理员 logs/*.log → 全 0）
- executor 的上游错误 WARNING、quota_probe/checkin 的失败也全部消失

生产路径是 `uvicorn src.main:build_app --factory`（launchd/容器/systemd 均如此），
不经过 run()，因此配置挂在 build_app 上（幂等，测试反复调用不叠加 handler）。

同时把 httpx/httpcore 的 INFO 压到 WARNING：root 升到 INFO 后它们给每个上游
请求打一条含完整 URL 的日志，既是噪音也与 §8「日志脱敏」冲突（URL 可能带
query 参数）；root=DEBUG 时放开，排查上游问题仍可看详情。

## 轮转：应用只写 stderr，交给平台（三平台通用）

不在应用内开文件/用 RotatingFileHandler：launchd、systemd、docker 三种形态
采集方式不同但都靠 stdout/stderr 对接；应用自己写文件会与平台轮转争抢同一
文件，容器里还会写进镜像层（重启即丢、docker logs 看不到）。

- Docker：compose 加 logging 段（json-file 默认无上限，是真实缺口）
- macOS：deploy/newsyslog/ + scripts/install-newsyslog.sh（需 sudo）
- Linux systemd：deploy/systemd/（journald 自带轮转，顺带补上缺失的 unit 模板）
- Linux 非 systemd：deploy/logrotate/（用 copytruncate，进程持有 fd）

newsyslog 字段已核对 man page（when=* 表示仅按 size；J=bzip2；N=不发信号），
规则里的路径与属主已与 launchd plist、实际文件属主逐项对齐。清理了
logs/{server,uvicorn}.log 两个失联残留（已无任何代码引用）。

测试：审计日志真的写到 handler（直接看 emit，不用 caplog——caplog 靠往 root
加 handler，不能证明我们的 handler 收到记录）、幂等、级别归一、降噪与 DEBUG
放开、stderr 而非文件、以及部署资产静态断言（compose 限额、newsyslog 字段数
与属主匹配、logrotate 用 copytruncate、systemd 走 journal、安装脚本可执行）。

Author: RobbsLuo

README.md

@@ -131,6 +131,38 @@ curl http://127.0.0.1:8000/v1/user/balance -H "Authorization: Bearer sk-你的ke
 
 - **时区**：镜像默认 `TZ=Asia/Shanghai`；如需其它时区显式覆盖 `TZ`。
 
+## 日志
+
+应用只写 **stdout / stderr**，不自己写文件也不自己轮转（原因见
+[`src/webapp/logging.py`](src/webapp/logging.py) 顶部说明）：三种部署形态的
+采集方式不同，但都靠这两个 fd 对接，轮转交给各自的平台工具。因此**日志自己
+不会停止增长**——按下面对应形态配一次即可。
+
+| 部署形态 | 日志到哪 | 轮转机制 | 需做什么 |
+|---|---|---|---|
+| **Docker / compose** | `docker logs coding2api` | json-file 驱动（已在 compose 配好 `10m × 5`） | **无需操作** |
+| **macOS（launchd）** | `logs/launchd.{out,err}.log` | 系统自带 `newsyslog` | 跑一次 `./scripts/install-newsyslog.sh`（需 sudo） |
+| **Linux（systemd）** | `journalctl -u coding2api` | journald 自带 | **无需操作**（模板见 `deploy/systemd/`） |
+| **Linux（非 systemd）** | 重定向到 `/var/log/coding2api/*.log` | `logrotate` | `sudo cp deploy/logrotate/coding2api /etc/logrotate.d/` |
+| **裸跑**（`uv run python -m src.main`） | 终端 stderr | 无 | 自己重定向并自备轮转 |
+
+级别用 `LOG_LEVEL`（默认 `INFO`）控制。**审计日志（凭证增删改/pin/账号切换）
+是 INFO 级**，把 `LOG_LEVEL` 调到 `WARNING` 会把它一并关掉。
+
+```bash
+# macOS：装轮转规则（单文件超 10MB 转，留 7 份，bzip2 压缩）
+./scripts/install-newsyslog.sh
+./scripts/install-newsyslog.sh --uninstall   # 卸载
+
+# 看日志
+tail -f logs/launchd.err.log          # macOS
+docker logs -f coding2api             # 容器
+journalctl -u coding2api -f           # systemd
+```
+
+> 容器里的 `data/dumps/`（诊断开关 `DUMP_REQUEST_BODIES=true` 写入）不在
+> docker 日志体系内，由应用自行保持最多 200 份。
+
 ## 开发
 
 ```bash

TECHNICAL.md

@@ -32,6 +32,7 @@ coding2api/
 │   │   ├── limits.py            # 请求体上限 ASGI 中间件（登录 8KB / 其余 16MB）
 │   │   ├── security.py          # Host 白名单 + 安全响应头（CSP/nosniff）
 │   │   ├── handlers.py          # 异常 → HTTP 响应（稳定错误码，TECHNICAL §6.5）
+│   │   ├── logging.py           # root logger 配置（审计/上游日志落 stderr）
 │   │   └── static.py            # 前端产物定位 + SPA catch-all
 │   ├── db/
 │   │   ├── schema.sql           # DDL 定稿
@@ -378,6 +379,16 @@ fixture 断言两个方向：**解析正确**（样本 → 期望 Event）与**
   全量重算作对账，两者结果一致（幂等）
 - **延迟均值只算成功请求**：分子 `SUM(latency_ms WHERE ok=1)` 与分母 `ok_count`
   配对；失败请求的耗时不能拉偏「典型耗时」（与图表口径一致）
+- **应用日志只写 stderr，轮转交给平台**：不在应用内开文件、不用
+  `RotatingFileHandler`。理由：三种部署形态（launchd / systemd / docker）的
+  采集方式不同但都靠 stdout/stderr 对接；应用自己写文件会与平台轮转争抢同一个
+  文件，容器里还会写进镜像层（重启即丢且 `docker logs` 看不到）。
+  各自配置见 `deploy/`（newsyslog / logrotate / systemd）与 compose 的 `logging` 段
+- **必须在 build_app 里配 root logger**：uvicorn 默认 `LOGGING_CONFIG` 只配
+  `uvicorn` / `uvicorn.access`（`propagate=false`），**从不配 root**；root 默认
+  `WARNING` 且无 handler，导致 `logging.getLogger(__name__)` 的 INFO 静默丢失。
+  生产路径 `uvicorn src.main:build_app --factory` 不经过 `run()`，
+  所以配置必须挂在 `build_app`（幂等，见 `src/webapp/logging.py`）
 - **两套数据源共存（已知不一致）**：`overview` / `by_provider` 读 `usage_events`（即时，
   仅覆盖 90 天明细），`timeline` / `model-timeline` 读 `usage_hourly`（≤5 分钟滞后，永久）。
   时间范围 ≤90 天时两者一致（汇总由同一批明细算出）；选「全部」时总览会小于图表，

deploy/logrotate/coding2api

@@ -0,0 +1,24 @@
+# Linux（非 systemd，或 systemd 但想把日志落独立文件）日志轮转
+#
+# 安装：
+#     sudo cp deploy/logrotate/coding2api /etc/logrotate.d/
+#     sudo logrotate -d /etc/logrotate.d/coding2api    # 干跑校验
+#
+# 路径按实际部署改（systemd 版见 deploy/systemd/coding2api.service，
+# 那条路线用 journald 自带轮转，不需要本文件）。
+#
+# 注意：本配置依赖应用把日志写到 stdout/stderr 后被重定向到该文件，
+# 而不是应用自己写文件——见 src/webapp/logging.py 的说明。
+# 因此必须配合 copytruncate（进程持有 fd 时 rename 不会让它换文件）：
+#     >> /var/log/coding2api/app.log 这种重定向下，用 copytruncate 最稳。
+
+/var/log/coding2api/*.log {
+    daily
+    rotate 7
+    maxsize 10M
+    missingok
+    notifempty
+    compress
+    delaycompress
+    copytruncate
+}

deploy/newsyslog/coding2api.conf

@@ -0,0 +1,25 @@
+# macOS 日志轮转规则（newsyslog）
+#
+# 安装（需 root，newsyslog 只读 /etc/newsyslog.d/）：
+#     sudo cp deploy/newsyslog/coding2api.conf /etc/newsyslog.d/
+#     sudo launchctl kickstart -k system/com.apple.newsyslog   # 立即生效
+# 卸载：
+#     sudo rm /etc/newsyslog.d/coding2api.conf
+#
+# 字段含义（newsyslog.conf(5)，已核 man page）：
+#   logfilename  owner:group  mode  count  size(KB)  when  flags
+#
+#   size=10240     单文件超 10MB 即轮转
+#   when=*         仅依据 size 轮转（不按时间）；磁盘占用只与总量相关
+#   count=7        最多保留 7 份归档（不含当前日志）
+#   flags=J        归档用 bzip2 压缩
+#   flags=N        轮转后不发信号（进程以 >> 追加模式持有文件句柄，
+#                  newsyslog 轮转后新文件同名，进程继续写入）
+#
+# 注意：日志路径必须与 ~/Library/LaunchAgents/com.coding2api.plist 的
+# StandardOutPath / StandardErrorPath 一致。改 plist 时同步改这里。
+# 本仓库的 plist 把两路日志分别写 launchd.out.log / launchd.err.log，
+# 因此这里给两条规则。
+
+/Users/robbs/Develpment/PartTimeJob/coding2api/logs/launchd.out.log  robbs:staff  644  7  10240  *  JN
+/Users/robbs/Develpment/PartTimeJob/coding2api/logs/launchd.err.log  robbs:staff  644  7  10240  *  JN

deploy/systemd/coding2api.service

@@ -0,0 +1,57 @@
+# systemd unit 模板（Linux 生产部署）
+#
+# 安装：
+#     sudo useradd --system --home /opt/coding2api coding2api
+#     sudo cp deploy/systemd/coding2api.service /etc/systemd/system/
+#     sudo systemctl daemon-reload && sudo systemctl enable --now coding2api
+#     journalctl -u coding2api -f        # 看日志
+#
+# 日志：走 journald（StandardOutput=journal），journald 自带容量轮转，
+# 无需 logrotate。全局限额在 /etc/systemd/journald.conf：
+#     SystemMaxUse=500M
+#     SystemMaxFileSize=50M
+# 也可按 unit 限制：
+#     sudo systemctl edit coding2api
+#     [Service]
+#     LogRateLimitIntervalSec=30s
+#     LogRateLimitBurst=1000
+#
+# 注意：应用只写 stdout/stderr，不自己写文件、不自己轮转
+# （见 src/webapp/logging.py 的原因说明）。
+
+[Unit]
+Description=Coding2API — CodeBuddy / TRAE SOLO 统一 OpenAI 兼容出口
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=exec
+User=coding2api
+Group=coding2api
+WorkingDirectory=/opt/coding2api
+
+# 必填：凭证列加密密钥。放独立文件（权限 600，属主 coding2api），
+# 不要写在本 unit 里，否则 systemctl cat 会把密钥暴露给任何用户。
+EnvironmentFile=/opt/coding2api/.env
+Environment=HOST=127.0.0.1
+Environment=PORT=8000
+Environment=DATA_DIR=/opt/coding2api/data
+
+ExecStart=/opt/coding2api/.venv/bin/python -m uvicorn src.main:build_app --factory
+Restart=always
+RestartSec=5
+
+# 日志交给 journald（自带轮转）
+StandardOutput=journal
+StandardError=journal
+
+# 安全加固：只需要写 data/ 与读 secrets/
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/coding2api/data
+ReadOnlyPaths=/opt/coding2api/secrets
+
+[Install]
+WantedBy=multi-user.target

docker-compose.yml

@@ -55,3 +55,12 @@ services:
       interval: 30s
       timeout: 5s
       retries: 3
+    # 日志轮转（唯一声明式、无需运维动手的一层）：json-file 驱动默认
+    # **无上限**，长期运行会把宿主磁盘写满。应用只写 stdout/stderr，
+    # 由 docker 采集，因此限额必须在这里给。
+    # 查看：docker logs coding2api；宿主机路径见 docker inspect 的 LogPath
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "5"

scripts/install-newsyslog.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# 安装 macOS newsyslog 轮转规则（需 sudo：newsyslog 只读 /etc/newsyslog.d/）。
+#
+#     ./scripts/install-newsyslog.sh            # 安装 + 立即生效
+#     ./scripts/install-newsyslog.sh --uninstall
+#
+# 日志路径取自 ~/Library/LaunchAgents/com.coding2api.plist，因此 plist 改了
+# 日志位置时需要重新跑本脚本。
+set -euo pipefail
+
+RULES_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/deploy/newsyslog/coding2api.conf"
+RULES_DST="/etc/newsyslog.d/coding2api.conf"
+
+if [[ "${1:-}" == "--uninstall" ]]; then
+    sudo rm -f "$RULES_DST"
+    sudo launchctl kickstart -k system/com.apple.newsyslog
+    echo "已移除 $RULES_DST"
+    exit 0
+fi
+
+if [[ ! -f "$RULES_SRC" ]]; then
+    echo "找不到规则文件: $RULES_SRC" >&2
+    exit 1
+fi
+
+# 用规则里第一条路径做一次 dry-run 校验，避免装进坏规则导致 newsyslog 整体失败
+echo "== 规则内容 =="
+cat "$RULES_SRC"
+
+sudo cp "$RULES_SRC" "$RULES_DST"
+sudo launchctl kickstart -k system/com.apple.newsyslog
+echo "已安装: $RULES_DST（单文件超 10MB 轮转，保留 7 份，bzip2 压缩）"
+echo "查看结果: ls -la $(dirname "$(awk 'NF && $1 !~ /^#/ {print $1; exit}' "$RULES_SRC")")"

src/main.py

@@ -46,6 +46,7 @@
 from .webapp import static as _static
 from .webapp.handlers import register_exception_handlers
 from .webapp.limits import BodySizeLimitMiddleware
+from .webapp.logging import configure_logging
 from .webapp.security import host_allowed, security_middleware
 
 logger = logging.getLogger(__name__)
@@ -108,6 +109,10 @@ def _forget_task(task: asyncio.Task, pending: list) -> None:
 def build_app(settings: Settings | None = None, *, providers: dict | None = None,
               users: object | None = None) -> FastAPI:
     config = settings or load_settings()
+    # 这里必须配：生产路径是 `uvicorn src.main:build_app --factory`（launchd /
+    # 容器 / systemd 均如此），不经过 run()，否则审计等 INFO 日志仍被丢弃。
+    # 幂等，测试反复调用 build_app 不会叠加 handler。
+    configure_logging(config.log_level)
     db = Database(config.db_path)
     apply_schema(db.connect())
     cipher = CredentialCipher(config.app_secret)
@@ -284,6 +289,8 @@ def run() -> None:
     import uvicorn
 
     config = load_settings()
+    # 应用日志（审计、上游错误等）在此之前无 handler 会被丢弃
+    configure_logging(config.log_level)
     uvicorn.run(
         build_app(config), host=config.host, port=config.port, log_level=config.log_level.lower()
     )

src/webapp/logging.py

@@ -0,0 +1,71 @@
+"""日志配置：应用只写 stderr，轮转交给平台。
+
+**为什么应用不自己写文件、不自己轮转**
+三种部署形态的日志采集方式完全不同，且都靠「进程的 stdout/stderr」这个
+统一接口对接：
+
+- macOS launchd：`StandardOutPath` / `StandardErrorPath` 重定向到文件，
+  轮转交给系统自带的 `newsyslog`（规则见 `deploy/newsyslog/`）
+- Linux systemd：journald 接管并自带轮转（`deploy/systemd/`）
+- Docker：json-file 驱动捕获，按 `logging.options` 限制大小
+  （`docker-compose.yml` 已配，三平台统一）
+
+应用自己写文件会把日志切成两份、与平台轮转争抢同一个文件，而且容器里
+写进镜像层重启即丢、`docker logs` 也看不到。所以这里只挂一个 stderr
+handler，文件与轮转全交给平台。
+
+**为什么必须显式配置 root**
+uvicorn 的默认 `LOGGING_CONFIG` 只配置 `uvicorn` 与 `uvicorn.access`
+两个 logger（且 `propagate=false`），**从不配置 root**，而 root 默认
+`level=WARNING` 且无 handler。后果是应用里 `logging.getLogger(__name__)`
+的 INFO 被静默丢弃——`PROPOSAL §8` 要求的凭证审计日志（增删改/pin/
+账号切换）首当其冲，一条都不会落盘。
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+# 带时间戳：launchd/newsyslog 重定向的文件里只有进程自己写的内容，
+# 没有 journald/docker 那种外部时间戳，格式必须自立
+LOG_FORMAT = "%(asctime)s %(levelname)-7s %(name)s: %(message)s"
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# 第三方库降噪：root 升到 INFO 后 httpx/httpcore 会给每个上游请求打一条
+# INFO，带完整 URL（可能含 query 参数，与 PROPOSAL §8「日志脱敏」冲突），
+# 且量级与请求数线性增长、把审计日志淡出视野。只保留它们的 WARNING+。
+_NOISY_LOGGERS = ("httpx", "httpcore")
+
+
+class _RootHandler(logging.StreamHandler):
+    """标记类：用于识别本模块已配置过的 handler，保证 configure_logging 幂等。
+
+    build_app 会被测试反复调用（每个用例一次），重复 addHandler 会让每条
+    日志打印多遍，因此必须有可靠的「已配置」判定。
+    """
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """配置 root logger：应用日志走 stderr（平台采集/轮转）。
+
+    幂等：重复调用只更新级别，不重复添加 handler。
+    uvicorn 的 logger 不在此处配置——它自带的配置已经够用，且
+    `disable_existing_loggers=false` 不会覆盖这里设置的 root。
+    """
+    normalized = (level or "INFO").upper()
+    root = logging.getLogger()
+    root.setLevel(normalized)
+
+    handler = next((h for h in root.handlers if isinstance(h, _RootHandler)), None)
+    if handler is None:
+        handler = _RootHandler(sys.stderr)
+        handler.setFormatter(logging.Formatter(LOG_FORMAT, DATE_FORMAT))
+        root.addHandler(handler)
+    handler.setLevel(normalized)
+
+    # 降噪而非禁用：默认（INFO 及以上）把这两个库压到 WARNING；
+    # root 调到 DEBUG 时放开到 INFO，排查上游问题需要看请求详情
+    noisy_level = logging.INFO if root.level <= logging.DEBUG else logging.WARNING
+    for name in _NOISY_LOGGERS:
+        logging.getLogger(name).setLevel(noisy_level)