diff --git a/.gitignore b/.gitignore index 9bd89e8..e9da0bc 100644 --- a/.gitignore +++ b/.gitignore @@ -58,3 +58,8 @@ frontend/dist/ dist/ *.egg-info/ .DS_Store + +# 调用日志数据库(2026-10-23 落地方案):运行时生成,不入库 +data/calllog.db +data/calllog.db-wal +data/calllog.db-shm diff --git a/CHANGELOG.md b/CHANGELOG.md index 8342fbb..d00a841 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,47 @@ # CHANGELOG +## 2026-10-23 · 调用日志落地(SQLite / 90 天 / 仅管理员可查全部)(2.7.3 → 2.8.0) + +老板:「ai网关项目,现在我想把调用日志落地,有什么方案」→ 方案确认后:「1,要记 / 2,90天 / +3,要前端查询界面,然后这个查询界面集成在日志菜单里,只有管理员有这个权限查看全部人的日志」。 + +### 后端:`app/calllog.py`(SQLite,零新依赖) +- 表 `api_calls` **21 列**:时间、rid、账号、Key 前 8 位、类型、方法、路径、模型、实际模型、 + 供应商、是否流式、成功、状态码、耗时、IP、UA、**提示词**、**回复**、网关版本。 +- **异步批量写**:`AccessLog.add()` → 内存队列 → 后台 task 每 1 秒或攒满 200 条 `executemany` 提交; + 队列满(默认 1 万条)即丢弃并计数,**绝不反压请求**;进程退出前 flush。 +- **双向握手**(本轮最关键的设计):一条日志的两半来自不同位置 —— 访问日志条目(`AccessLog.add`) + 和响应元数据(中间件收尾,含状态码/耗时/IP/UA)。两半先后顺序不确定: + 非流式是「条目先、元数据后」,**流式是「元数据先、条目后」**(SSE 真正发完才 add)。 + 所以两边都先暂存,谁后到谁拼成一行落库。 +- **早失败也记**:未知模型 400、鉴权 401/403、限流 429 这类请求走不到 `AccessLog.add`, + 中间件用请求体补一条(含模型名与提示词),否则日志里只剩一行"400、无模型",排查时没有信息量。 +- **失败也记 Key 前缀**:401 时 `request.state.credential` 是空的,但恰恰这时最需要知道 + 客户端拿的是哪把 Key —— 记前 8 位即可对账(2026-10-23 的真实工单就是靠这个抓到 + 「客户端在发 `wjd-5Da_…`,而库里他的有效 Key 是 `wjd-15zs…`」)。 +- 保留 **90 天**:启动时清理 + 每 6 小时清理一次;`CALLLOG_RETENTION_DAYS` 可调。 +- 隐私:**API Key 只存前 8 位**;提示词/回复按 `CALLLOG_CONTENT_MAX`(默认 8000 字)截断; + 库文件权限 600。IP 存完整地址(仅管理员可见,便于与 WAF/防火墙日志对账)。 + +### 接口(新增 4 个,全部**仅管理员**) +| 端点 | 用途 | +|---|---| +| `GET /logs/calls` | 分页 + 筛选(时间段/账号/模型/成功失败/状态码/类型/关键词),`content=1` 时带内容 | +| `GET /logs/calls/stats` | 按天、按模型、按账号、按状态码聚合 + 库大小/写入/丢弃计数 | +| `GET /logs/calls/{id}` | 单条详情(含完整提示词与回复)| +| `GET /logs/calls/export` | CSV 导出(最多 5 万条,UTF-8 BOM,Excel 直接打开)| + +成员访问以上端点一律 **403**(`_require_admin_logs`)。 + +### 前端:集成在「日志」菜单 +- 日志页顶部新增两个页签:**实时**(原有内存环形缓冲)/ **调用日志**(仅管理员可见)。 +- 新组件 `CallLogs.vue`:日期范围、账号、模型、仅成功/仅失败、关键词(内容/rid/IP/UA)筛选; + 列表显示时间/账号/模型/耗时/状态/流式/UA;点击行弹出详情看**完整提示词与回复**;CSV 导出。 + +### 现状说明 +- `/metrics` 仍是内存态(重启清零),本次没动它;**调用日志是持久化的**, + 需要历史统计时可以基于 `api_calls` 做(二期可把 Dashboard 数据源切过来)。 + ## 2026-10-22 · 成员只看自己的用量 + AI 接口不再被 WAF 误杀(2.7.2 → 2.7.3) 老板:「改,替换重启,更新文档,推送 gitea」;随后补充「成员在首页是要看到自己调用的次数统计」。 diff --git a/app/calllog.py b/app/calllog.py new file mode 100644 index 0000000..6d60639 --- /dev/null +++ b/app/calllog.py @@ -0,0 +1,480 @@ +"""调用日志落地(SQLite 持久化,默认保留 90 天)。 + +为什么需要它 +------------ +`AccessLog` 是**内存**环形缓冲(重启即丢),`/metrics` 只有聚合计数。出工单时最常被问的是 +「谁、什么时候、用哪个模型、失败原因是什么、当时发了什么内容」—— 这些必须落盘可查。 + +设计取舍 +-------- +- **零新依赖**:`sqlite3` 是标准库,不引入 ORM / 数据库驱动(与本项目"依赖极简"的基调一致)。 +- **不阻塞请求**:`stage()` 只往内存队列 append;后台 task 每 1 秒或攒满 `BATCH` 条批量写库。 + 队列满(默认 10000 条)即丢弃并计数,**绝不反压请求**。 +- **隐私**:API Key 只存前 8 位(`key_id`);提示词/回复按 `CALLLOG_CONTENT_MAX` 截断(默认 8000 字)。 +- **保留**:默认 90 天,启动时清理一次 + 每 6 小时清理一次(不依赖外部 cron)。 +- **只增不改**:日志表不做 UPDATE;清理只按 `ts` 删。 + +环境变量 +-------- +- `CALLLOG_DB` 默认 `data/calllog.db` +- `CALLLOG_RETENTION_DAYS` 默认 90 +- `CALLLOG_QUEUE_MAX` 默认 10000 +- `CALLLOG_CONTENT_MAX` 默认 8000(提示词/回复各自截断长度) +- `CALLLOG_DISABLED=1` 整体关闭(不回退任何现有行为) +""" + +from __future__ import annotations + +import asyncio +import logging +import os +import sqlite3 +import threading +import time +from collections import deque +from typing import Any + +log = logging.getLogger("calllog") + +_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +DB_PATH = os.environ.get("CALLLOG_DB") or os.path.join(_ROOT, "data", "calllog.db") +RETENTION_DAYS = int(os.environ.get("CALLLOG_RETENTION_DAYS") or 90) +QUEUE_MAX = int(os.environ.get("CALLLOG_QUEUE_MAX") or 10000) +CONTENT_MAX = int(os.environ.get("CALLLOG_CONTENT_MAX") or 8000) +DISABLED = os.environ.get("CALLLOG_DISABLED", "") not in ("", "0", "false", "False") + +BATCH = 200 # 攒够多少条提交一次 +FLUSH_INTERVAL = 1.0 # 最长多久提交一次(秒) +CLEAN_INTERVAL = 6 * 3600 # 清理间隔(秒) + +SCHEMA = """ +CREATE TABLE IF NOT EXISTS api_calls ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + ts REAL NOT NULL, + rid TEXT, + account TEXT, + key_id TEXT, + kind TEXT, + method TEXT, + path TEXT, + model TEXT, + served TEXT, + provider TEXT, + caller TEXT, + stream INTEGER DEFAULT 0, + ok INTEGER DEFAULT 1, + status INTEGER, + latency_ms INTEGER, + ip TEXT, + ua TEXT, + prompt TEXT, + completion TEXT, + ver TEXT +); +CREATE INDEX IF NOT EXISTS idx_calls_ts ON api_calls(ts); +CREATE INDEX IF NOT EXISTS idx_calls_acc_ts ON api_calls(account, ts); +CREATE INDEX IF NOT EXISTS idx_calls_model ON api_calls(model, ts); +CREATE INDEX IF NOT EXISTS idx_calls_ok ON api_calls(ok, ts); +CREATE INDEX IF NOT EXISTS idx_calls_status ON api_calls(status, ts); +CREATE INDEX IF NOT EXISTS idx_calls_rid ON api_calls(rid); +""" + +_COLUMNS = ("ts", "rid", "account", "key_id", "kind", "method", "path", "model", + "served", "provider", "caller", "stream", "ok", "status", "latency_ms", + "ip", "ua", "prompt", "completion", "ver") + +_INSERT = f"INSERT INTO api_calls ({', '.join(_COLUMNS)}) VALUES ({', '.join('?' * len(_COLUMNS))})" + + +def _clip(v: Any, n: int = CONTENT_MAX) -> str: + """内容裁剪:非字符串转字符串,超长截断并标注。""" + if v is None: + return "" + s = v if isinstance(v, str) else str(v) + if len(s) > n: + return s[:n] + f"\n…(已截断,共 {len(s)} 字)" + return s + + +class CallLogStore: + """SQLite 调用日志存储。线程安全的单写者 + 单读连接。""" + + def __init__(self, path: str = DB_PATH, *, retention_days: int = RETENTION_DAYS, + queue_max: int = QUEUE_MAX, enabled: bool = True) -> None: + self.path = path + self.retention_days = retention_days + self.queue_max = queue_max + self.enabled = enabled and not DISABLED + self._q: deque[tuple] = deque() + self._lock = threading.Lock() + self._db: sqlite3.Connection | None = None + self._task: asyncio.Task | None = None + self._running = False + self.written = 0 + self.dropped = 0 + self.last_error = "" + + # ── 生命周期 ──────────────────────────────────────────────── + def open(self) -> None: + if not self.enabled: + log.info("调用日志已禁用(CALLLOG_DISABLED)") + return + os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True) + db = sqlite3.connect(self.path, check_same_thread=False, timeout=10) + db.execute("PRAGMA journal_mode=WAL") + db.execute("PRAGMA synchronous=NORMAL") + db.executescript(SCHEMA) + db.commit() + try: + os.chmod(self.path, 0o600) + except OSError: + pass + self._db = db + log.info("调用日志已就绪: %s(保留 %d 天)", self.path, self.retention_days) + self.cleanup() + + async def start(self) -> None: + self.open() + if not self.enabled or self._task is not None: + return + self._running = True + self._task = asyncio.create_task(self._loop(), name="calllog-writer") + log.info("调用日志后台写入已启动") + + async def close(self) -> None: + self._running = False + if self._task: + self._task.cancel() + try: + await self._task + except (asyncio.CancelledError, Exception): + pass + self._task = None + self.flush() + if self._db: + self._db.close() + self._db = None + + async def _loop(self) -> None: + last_clean = time.time() + while self._running: + await asyncio.sleep(FLUSH_INTERVAL) + try: + self.flush() + sweep() + if time.time() - last_clean > CLEAN_INTERVAL: + last_clean = time.time() + self.cleanup() + except Exception as e: # noqa: BLE001 + self.last_error = f"{type(e).__name__}: {e}" + log.warning("调用日志写入失败: %s", e) + + # ── 写入 ──────────────────────────────────────────────────── + def stage(self, row: dict[str, Any]) -> None: + """入队(非阻塞)。队列满则丢弃并计数。""" + if not self.enabled: + return + try: + tup = tuple(row.get(c) for c in _COLUMNS) + except Exception: # noqa: BLE001 + return + with self._lock: + if len(self._q) >= self.queue_max: + self.dropped += 1 + return + self._q.append(tup) + + def flush(self) -> int: + """把队列里的行一次批量写库。返回写入条数。""" + if not self.enabled or self._db is None: + return 0 + with self._lock: + if not self._q: + return 0 + rows = list(self._q) + self._q.clear() + try: + with self._lock: + self._db.executemany(_INSERT, rows) + self._db.commit() + self.written += len(rows) + return len(rows) + except Exception as e: # noqa: BLE001 + self.last_error = f"{type(e).__name__}: {e}" + log.warning("调用日志批量写入失败(丢弃 %d 条): %s", len(rows), e) + return 0 + + # ── 清理 ──────────────────────────────────────────────────── + def cleanup(self) -> int: + if not self.enabled or self._db is None: + return 0 + cutoff = time.time() - self.retention_days * 86400 + try: + with self._lock: + cur = self._db.execute("DELETE FROM api_calls WHERE ts < ?", (cutoff,)) + self._db.commit() + n = cur.rowcount or 0 + if n: + log.info("调用日志清理:删除 %d 条(早于 %d 天前)", n, self.retention_days) + return n + except Exception as e: # noqa: BLE001 + log.warning("调用日志清理失败: %s", e) + return 0 + + # ── 查询 ──────────────────────────────────────────────────── + def _where(self, *, start: float | None, end: float | None, account: str | None, + model: str | None, ok: int | None, status: int | None, + kind: str | None, q: str | None, + with_content: bool = False) -> tuple[str, list[Any]]: + w: list[str] = [] + p: list[Any] = [] + if start is not None: + w.append("ts >= ?") + p.append(start) + if end is not None: + w.append("ts <= ?") + p.append(end) + if account: + w.append("(account = ? OR caller = ?)") + p.extend([account, account]) + if model: + w.append("(model = ? OR served = ?)") + p.extend([model, model]) + if ok is not None: + w.append("ok = ?") + p.append(int(ok)) + if status: + w.append("status = ?") + p.append(int(status)) + if kind: + w.append("kind = ?") + p.append(kind) + if q: + like = f"%{q}%" + w.append("(rid LIKE ? OR account LIKE ? OR model LIKE ? OR prompt LIKE ? " + "OR completion LIKE ? OR ua LIKE ? OR ip LIKE ?)") + p.extend([like] * 7) + return (" WHERE " + " AND ".join(w)) if w else "", p + + def query(self, *, start: float | None = None, end: float | None = None, + account: str | None = None, model: str | None = None, + ok: int | None = None, status: int | None = None, + kind: str | None = None, q: str | None = None, + limit: int = 50, offset: int = 0, + with_content: bool = False) -> dict[str, Any]: + """分页查询。with_content=False 时不返回 prompt/completion(列表页省流量)。""" + if not self.enabled or self._db is None: + return {"total": 0, "items": [], "enabled": False} + where, params = self._where(start=start, end=end, account=account, model=model, + ok=ok, status=status, kind=kind, q=q) + cols = ("id, ts, rid, account, key_id, kind, method, path, model, served, provider, " + "caller, stream, ok, status, latency_ms, ip, ua, ver") + if with_content: + cols += ", prompt, completion" + limit = max(1, min(int(limit), 500)) + offset = max(0, int(offset)) + try: + with self._lock: + total = self._db.execute(f"SELECT COUNT(*) FROM api_calls{where}", params).fetchone()[0] + rows = self._db.execute( + f"SELECT {cols} FROM api_calls{where} ORDER BY ts DESC LIMIT ? OFFSET ?", + [*params, limit, offset], + ).fetchall() + except Exception as e: # noqa: BLE001 + log.warning("调用日志查询失败: %s", e) + return {"total": 0, "items": [], "error": str(e)} + names = [d[0] for d in self._db.execute(f"SELECT {cols} FROM api_calls LIMIT 0").description] + items = [] + for r in rows: + d = dict(zip(names, r)) + d["ts_iso"] = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(d["ts"])) + items.append(d) + return {"total": total, "items": items, "limit": limit, "offset": offset} + + def get(self, call_id: int) -> dict[str, Any] | None: + if not self.enabled or self._db is None: + return None + try: + with self._lock: + cur = self._db.execute("SELECT * FROM api_calls WHERE id = ?", (int(call_id),)) + row = cur.fetchone() + names = [d[0] for d in cur.description] + except Exception: # noqa: BLE001 + return None + if not row: + return None + d = dict(zip(names, row)) + d["ts_iso"] = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(d["ts"])) + return d + + def stats(self, days: int = 7) -> dict[str, Any]: + """按天 / 模型 / 账号 / 状态码聚合(前端图表与概览用)。""" + if not self.enabled or self._db is None: + return {"enabled": False} + since = time.time() - max(1, int(days)) * 86400 + out: dict[str, Any] = {"enabled": True, "days": days} + try: + with self._lock: + out["daily"] = [ + {"date": r[0], "total": r[1], "ok": r[2], "fail": r[3], + "avg_ms": round(r[4] or 0, 1)} + for r in self._db.execute( + "SELECT date(ts, 'unixepoch', 'localtime') d, COUNT(*), " + "SUM(ok), SUM(CASE WHEN ok=0 THEN 1 ELSE 0 END), AVG(latency_ms) " + "FROM api_calls WHERE ts >= ? GROUP BY d ORDER BY d", (since,)) + ] + out["models"] = [ + {"model": r[0], "total": r[1], "fail": r[2], "avg_ms": round(r[3] or 0, 1)} + for r in self._db.execute( + "SELECT model, COUNT(*), SUM(CASE WHEN ok=0 THEN 1 ELSE 0 END), " + "AVG(latency_ms) FROM api_calls WHERE ts >= ? " + "GROUP BY model ORDER BY COUNT(*) DESC LIMIT 20", (since,)) + ] + out["accounts"] = [ + {"account": r[0], "total": r[1], "fail": r[2]} + for r in self._db.execute( + "SELECT account, COUNT(*), SUM(CASE WHEN ok=0 THEN 1 ELSE 0 END) " + "FROM api_calls WHERE ts >= ? GROUP BY account " + "ORDER BY COUNT(*) DESC LIMIT 50", (since,)) + ] + out["statuses"] = [ + {"status": r[0], "total": r[1]} + for r in self._db.execute( + "SELECT status, COUNT(*) FROM api_calls WHERE ts >= ? " + "GROUP BY status ORDER BY COUNT(*) DESC LIMIT 20", (since,)) + ] + out["total"] = self._db.execute( + "SELECT COUNT(*) FROM api_calls").fetchone()[0] + out["size_bytes"] = os.path.getsize(self.path) if os.path.exists(self.path) else 0 + except Exception as e: # noqa: BLE001 + out["error"] = str(e) + out["written"] = self.written + out["dropped"] = self.dropped + out["queued"] = len(self._q) + return out + + def export_rows(self, **kw: Any) -> list[dict[str, Any]]: + """导出用:不带分页,最多 50000 条。""" + kw.setdefault("limit", 50000) + kw.setdefault("offset", 0) + kw["with_content"] = True + return self.query(**kw).get("items", []) + + +store = CallLogStore() + +# ── 与请求生命周期的双向握手 ────────────────────────────────────── +# 一条调用日志由两半拼成: +# ① 访问日志条目(AccessLog.add):kind/model/provider/caller/ok/stream/body/response +# ② 响应元数据(中间件收尾):status/耗时/IP/UA/Key 前 8 位 +# 但两半的**先后顺序是不确定的**: +# · 非流式:① 在请求处理中途就 add 了 → ② 后到 +# · 流式:② 在 StreamingResponse 建好就返回了 → ① 要等流真正发完才 add(后到) +# 所以两边都先暂存、谁发现对方已就绪就立刻拼成一行落库。 +_PEND_ENTRY: dict[str, dict] = {} # rid -> 访问日志条目(等 meta) +_PEND_META: dict[str, dict] = {} # rid -> 响应元数据(等 entry) +_pend_lock = threading.Lock() +_PEND_MAX = 2000 +_META_TTL = 300.0 # 元数据最多等 5 分钟,避免泄漏 + + +def _trim(d: dict[str, dict]) -> None: + while len(d) > _PEND_MAX: + try: + d.pop(next(iter(d)), None) + except (StopIteration, KeyError): + break + + +def _row(entry: dict[str, Any], meta: dict[str, Any]) -> dict[str, Any]: + return { + "ts": entry.get("ts") or time.time(), + "rid": entry.get("rid") or meta.get("rid"), + "account": entry.get("account") or entry.get("caller") or meta.get("account"), + "key_id": meta.get("key_id", ""), + "kind": entry.get("kind") or meta.get("kind"), + "method": entry.get("method") or meta.get("method"), + "path": entry.get("path") or meta.get("path"), + "model": entry.get("model"), + "served": entry.get("served"), + "provider": entry.get("provider"), + "caller": entry.get("caller"), + "stream": 1 if entry.get("stream") else 0, + "ok": 1 if entry.get("ok") else 0, + "status": meta.get("status"), + "latency_ms": meta.get("latency_ms"), + "ip": meta.get("ip", ""), + "ua": _clip(meta.get("ua", ""), 200), + "prompt": _clip(entry.get("body"), CONTENT_MAX), + "completion": _clip(entry.get("response"), CONTENT_MAX), + "ver": meta.get("ver", ""), + } + + +def on_access(entry: dict[str, Any]) -> None: + """`AccessLog.add()` 调用:拿到访问日志条目;若响应元数据已就绪则立即落库。""" + if not store.enabled: + return + rid = str(entry.get("rid") or "") + if not rid: + store.stage(_row(entry, {})) + return + with _pend_lock: + meta = _PEND_META.pop(rid, None) + if meta is None: + _PEND_ENTRY[rid] = entry + _trim(_PEND_ENTRY) + return + store.stage(_row(entry, meta)) + + +def on_response(rid: str, *, status: int, latency_ms: float, ip: str = "", ua: str = "", + key_id: str = "", ver: str = "", method: str = "", path: str = "", + account: str = "", stream: bool = False, body: str = "") -> None: + """请求中间件收尾调用:补上响应元数据;条目已就绪则立即落库。 + + `stream=True` 时条目一定还没到(SSE 还没开始发),只暂存等 `on_access`; + 非流式且没有条目、又是 **/v1/ 下的失败**时,补一条"早失败"记录(例如未知模型 400、 + 鉴权 401/403、限流 429)—— 这类请求压根走不到 `_access.add`,但恰恰最需要留痕。 + """ + if not store.enabled: + return + rid = str(rid or "") + meta = {"rid": rid, "status": int(status) if status else None, + "latency_ms": int(latency_ms), "ip": ip, "ua": ua, "key_id": key_id, + "ver": ver, "method": method, "path": path, "account": account, + "kind": "chat" if path.startswith("/v1/") else None, + "ts": time.time()} + if rid: + with _pend_lock: + entry = _PEND_ENTRY.pop(rid, None) + if entry is not None: + store.stage(_row(entry, meta)) + return + if stream: + _PEND_META[rid] = meta # 等 event_stream 收尾时补条目 + _trim(_PEND_META) + return + # 没有条目且不是流式:只有 /v1/ 下的失败才补记(成功一定有条目;其余端点不算"调用") + if status and int(status) >= 400 and path.startswith("/v1/"): + # 早失败(未知模型 / 鉴权失败 / 限流)走不到 AccessLog.add,这里用请求体补全信息, + # 否则日志里只有一行"400、无模型",排查时看不出客户端到底请求了什么。 + model = "" + try: + import json as _json + model = str((_json.loads(body or "{}") or {}).get("model") or "") + except Exception: # noqa: BLE001 + model = "" + store.stage(_row({"model": model or None, "body": body}, meta)) + + +def sweep() -> int: + """丢弃超时未配对的暂存项(由后台循环定期调用)。""" + now = time.time() + n = 0 + with _pend_lock: + for d in (_PEND_META,): + for k in [k for k, v in d.items() if now - float(v.get("ts") or 0) > _META_TTL]: + d.pop(k, None) + n += 1 + return n diff --git a/app/main.py b/app/main.py index b83936e..6c573fa 100644 --- a/app/main.py +++ b/app/main.py @@ -44,6 +44,7 @@ from app.circuit import CircuitBreakerRegistry from app.config import (ConfigError, GatewayConfig, load_config, validate_warnings, PROTOCOL_CHAT, PROTOCOL_MESSAGES, PROTOCOL_RESPONSES, PROTOCOLS, ALIAS_PROTOCOLS) +from app import calllog from app.metrics import (Metrics, AccessLog, RateLimiter, BODY_BY_RID, _BODY_MAX, video_poll_push, video_polls, ACCOUNT, ROLE) @@ -220,6 +221,11 @@ async def lifespan(app: FastAPI): hot_task = None if config.server.hot_reload: hot_task = asyncio.create_task(_hot_reload_loop()) + # 调用日志落地(2026-10-23):SQLite + 后台批量写,失败不影响服务 + try: + await calllog.store.start() + except Exception as e: # noqa: BLE001 + log.warning("调用日志启动失败(不影响服务): %s", e) yield # 关闭阶段:先停热重载,再等在途请求(uvicorn 自身也做,这里补逻辑日志) if hot_task: @@ -239,6 +245,11 @@ async def lifespan(app: FastAPI): # 第六轮: 快照后再迭代(避免迭代中字典被改动 → RuntimeError) for adapter in list(_state.get("adapters", {}).values()): await adapter.close() + # 调用日志:把队列里剩下的刷盘再关库(否则重启会丢最后不到 1 秒的记录) + try: + await calllog.store.close() + except Exception as e: # noqa: BLE001 + log.warning("调用日志收尾失败: %s", e) async def _apply_config(new: GatewayConfig, *, source: str = "热重载") -> None: @@ -340,7 +351,7 @@ _docs_on = config.server.docs_enabled # 安全默认关(report: /docs、/ope # 2026-09-30: 2.6.1 → 2.7.0(按老板要求整个删除「火山方舟 Coding Plan」供应商:配置/模型/代码/文档/前端下拉/环境变量全清)。 # 2026-09-30: 2.7.0 → 2.7.1(界面提示白话化:熔断器→供应商自动保护、引擎→运行环境、slug→标识;删 120 个未引用死键)。 # ★ 版本号纪律:每次改动都要往上加,小改动加小版本号、大改动加大版本号(README 有专章)。 -VERSION = "2.7.3" +VERSION = "2.8.0" app = FastAPI( title="API Gateway", @@ -548,13 +559,65 @@ def _logsafe(v, maxlen: int = 200) -> str: return "".join(ch if ch.isprintable() else "?" for ch in str(v))[:maxlen] +def _client_ip(request: Request) -> str: + """取客户端真实 IP:优先 X-Forwarded-For(EO/OpenResty 回源会带),否则取连接地址。 + + 只给管理员看(/logs/calls 是 admin 端点),所以保留完整 IP 便于与 WAF/防火墙日志对账。 + """ + xff = request.headers.get("x-forwarded-for") or "" + if xff: + first = xff.split(",")[0].strip() + if first: + return first + return getattr(request.client, "host", "") or "" + + +def _flush_calllog(request: Request, rid: str, status: int, latency_ms: float, + stream: bool = False) -> None: + """请求收尾:把响应元数据交给 calllog,与访问日志条目拼成一行落库。""" + try: + # 只取前 8 位做标识,绝不落完整 Key。 + # 鉴权失败(401)时 request.state.credential 是空的,但**恰恰这时最需要知道 + # 客户端到底拿的是哪把 Key**(2026-10-23 真实工单:客户一直 401,靠这个前缀 + # 才能判断他手上是不是旧 Key)—— 所以失败路径也记前缀。 + hdr = request.headers.get("authorization") or "" + presented = (hdr[7:] if hdr.lower().startswith("bearer ") + else (request.headers.get("x-api-key") or "")).strip() + key_id = presented[:8] if presented else "" + calllog.on_response( + rid, + status=status, + latency_ms=latency_ms, + ip=_client_ip(request), + ua=request.headers.get("user-agent") or "", + key_id=key_id, + ver=VERSION, + method=request.method, + path=request.url.path, + account=getattr(request.state, "account", "") or "", + stream=stream, + body=BODY_BY_RID.pop(rid, "") or "", + ) + except Exception as e: # noqa: BLE001 + log.debug("调用日志落地失败(忽略): %s", e) + + @app.middleware("http") async def add_request_id(request: Request, call_next): rid = _sanitize_rid(request.headers.get("X-Request-ID")) or str(uuid.uuid4()) request.state.rid = rid - response = await call_next(request) - response.headers["X-Request-ID"] = rid - return response + t0 = time.perf_counter() + status = 500 + is_stream = False + try: + response = await call_next(request) + status = response.status_code + response.headers["X-Request-ID"] = rid + # SSE 请求的访问日志条目要等流真正发完才产生 → 告知 calllog 先等条目 + is_stream = str(response.headers.get("content-type", "")).startswith("text/event-stream") + return response + finally: + _flush_calllog(request, rid, status, (time.perf_counter() - t0) * 1000, is_stream) # Fix 5(本轮): CORS 注册放在最后 → 位于最外层,覆盖 limit_body 等短路响应。 @@ -3061,6 +3124,94 @@ async def logs(request: Request, n: int = 100, _auth=Depends(require_auth)): return {"entries": _logs_for_account(request.state.account, n)} +# ───────────────────────────────────── +# 调用日志(持久化,2026-10-23)—— 仅管理员 +# +# 与上面的 /logs 的区别: +# /logs 内存环形缓冲(默认 500 条,重启即丢),**只看自己的**; +# /logs/calls SQLite 落盘(默认保留 90 天),管理员可分页/筛选/看**所有人**的, +# 含提示词与回复内容(截断记录)。 +# ───────────────────────────────────── +def _require_admin_logs(request: Request) -> None: + """调用日志含全站内容,仅管理员可读(口径与 /metrics/prometheus、/health 收敛一致)。""" + if getattr(request.state, "role", "") != "admin": + raise HTTPException(403, "仅管理员可查看调用日志") + + +def _as_ts(v: str | None) -> float | None: + """时间参数:支持 epoch 秒、'2026-10-23'、'2026-10-23 03:00'、ISO 'T' 分隔。""" + if v is None or str(v).strip() == "": + return None + s2 = str(v).strip() + try: + return float(s2) + except ValueError: + pass + for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%dT%H:%M:%S", + "%Y-%m-%dT%H:%M", "%Y-%m-%d"): + try: + return time.mktime(time.strptime(s2, fmt)) + except ValueError: + continue + return None + + +@app.get("/logs/calls/stats") +async def logs_calls_stats(request: Request, days: int = 7, _auth=Depends(require_auth)): + _require_admin_logs(request) + return calllog.store.stats(days=days) + + +@app.get("/logs/calls/export") +async def logs_calls_export(request: Request, start: str | None = None, end: str | None = None, + account: str | None = None, model: str | None = None, + ok: int | None = None, status: int | None = None, + kind: str | None = None, q: str | None = None, + _auth=Depends(require_auth)): + """导出 CSV(最多 5 万条,含提示词与回复内容)。""" + _require_admin_logs(request) + rows = calllog.store.export_rows(start=_as_ts(start), end=_as_ts(end), account=account, + model=model, ok=ok, status=status, kind=kind, q=q) + import csv as _csv + import io as _io + buf = _io.StringIO() + w = _csv.writer(buf) + w.writerow(["时间", "rid", "账号", "Key前8位", "类型", "模型", "实际模型", "供应商", + "流式", "成功", "状态码", "耗时ms", "IP", "UA", "提示词", "回复"]) + for r in rows: + w.writerow([r.get("ts_iso"), r.get("rid"), r.get("account"), r.get("key_id"), + r.get("kind"), r.get("model"), r.get("served"), r.get("provider"), + "是" if r.get("stream") else "否", "是" if r.get("ok") else "否", + r.get("status"), r.get("latency_ms"), r.get("ip"), r.get("ua"), + (r.get("prompt") or "").replace("\n", "\\n"), + (r.get("completion") or "").replace("\n", "\\n")]) + fname = time.strftime("calllog-%Y%m%d-%H%M%S.csv", time.localtime()) + return Response(content=buf.getvalue().encode("utf-8-sig"), media_type="text/csv", + headers={"Content-Disposition": f'attachment; filename="{fname}"'}) + + +@app.get("/logs/calls") +async def logs_calls(request: Request, start: str | None = None, end: str | None = None, + account: str | None = None, model: str | None = None, + ok: int | None = None, status: int | None = None, + kind: str | None = None, q: str | None = None, + limit: int = 50, offset: int = 0, content: int = 0, + _auth=Depends(require_auth)): + _require_admin_logs(request) + return calllog.store.query(start=_as_ts(start), end=_as_ts(end), account=account, + model=model, ok=ok, status=status, kind=kind, q=q, + limit=limit, offset=offset, with_content=bool(content)) + + +@app.get("/logs/calls/{call_id}") +async def logs_call_detail(request: Request, call_id: int, _auth=Depends(require_auth)): + _require_admin_logs(request) + row = calllog.store.get(call_id) + if not row: + raise HTTPException(404, f"调用日志不存在: {call_id}") + return row + + # ───────────────────────────────────── # GET / — 端点导航(功能 7) # ───────────────────────────────────── diff --git a/app/metrics.py b/app/metrics.py index d55534d..eba4213 100644 --- a/app/metrics.py +++ b/app/metrics.py @@ -25,6 +25,7 @@ ROLE: ContextVar[str] = ContextVar("gw_role", default="member") # 附上「具体请求内容」,便于在日志页查看实际发了什么。有界缓存,防无界增长。 BODY_BY_RID: dict[str, str] = {} + # ── 视频轮询历史(/logs 按 video_id 合成到「创建」那一条里,不再每个轮询各占一行) ── VIDEO_POLLS: dict[str, "deque"] = {} _vp_lock = threading.Lock() @@ -272,6 +273,13 @@ class AccessLog: entry["body"] = snip with self._lock: self._buf.append(entry) + # 调用日志落地(2026-10-23):交给 app/calllog.py —— 它与请求中间件的响应元数据 + # 做双向握手(谁后到谁拼行),流式请求的条目比响应晚到也能落到库里。 + try: + from app import calllog + calllog.on_access(entry) + except Exception: # noqa: BLE001 + pass def tail(self, n: int = 100) -> list[dict[str, Any]]: with self._lock: diff --git a/docs/call-log-design.md b/docs/call-log-design.md new file mode 100644 index 0000000..1000132 --- /dev/null +++ b/docs/call-log-design.md @@ -0,0 +1,84 @@ +# 调用日志落地设计(2026-10-23) + +> 方案对比与取舍记录。实现在 `app/calllog.py`,界面在「日志」页的「调用日志」页签。 + +## 为什么需要 + +`AccessLog` 是内存环形缓冲(默认 500 条,**重启即丢**),`/metrics` 只有聚合计数。 + +2026-10-22 的真实工单很说明问题:成员反馈「拿 apikey 请求 403」,最后是靠 grep 1Panel 的 +WAF `access.log` 才定位 —— 网关这边**没有任何一条可查的调用记录**。调用日志要解决的就是这个。 + +## 方案对比 + +| | **A. SQLite(采用)** | B. JSONL 文件 | C. MySQL | D. Loki/ELK | +|---|---|---|---|---| +| 新增依赖 | **0**(标准库)| 0 | 驱动+连接池 | 整套平台 | +| 查询/聚合 | SQL ✅ | grep/jq | 强 | 最强 | +| 写入风险 | 低(WAL + 单写者 + 队列)| 最低 | 中(DB 挂了影响写)| 中 | +| 运维成本 | 极低(一个文件)| 极低 | 中 | 高 | +| 适合 | 单机、日调用 < 50 万 | 只求能查 | 多节点统一账单 | 规模化 | + +选 A:项目依赖极简(7 个包),引入 MySQL 驱动破坏基调;MySQL 容器是 Gitea 在用,混用会把 +「日志」和「业务库」绑死。 + +## 表结构要点 + +21 列,见 `app/calllog.py` 的 `SCHEMA`。索引覆盖四条最常用的查询路径: +`ts`、`(account, ts)`、`(model, ts)`、`(ok, ts)`、`(status, ts)`、`rid`。 + +## 三个关键设计 + +### 1. 双向握手(两半日志拼起来) + +一条日志由两处产生,**先后顺序不确定**: + +| 场景 | 先到 | 后到 | +|---|---|---| +| 非流式 | 访问日志条目(请求处理中途)| 响应元数据(状态码/耗时/IP/UA)| +| **流式** | 响应元数据(StreamingResponse 建好就返回)| 访问日志条目(SSE 真发完才 add)| + +实现上两边都先暂存(`_PEND_ENTRY` / `_PEND_META`),谁发现对方已就绪就立刻拼成一行落库; +元数据最多等 5 分钟(`sweep()` 定期丢弃),避免泄漏。 + +### 2. 早失败也记 + +未知模型(400)、鉴权失败(401/403)、限流(429)这些请求**走不到** `AccessLog.add`。 +中间件在收尾时若发现"没有条目 + `/v1/` 下 + status ≥ 400",就用请求体补一条记录, +并解析出 `model` 字段 —— 否则日志里只有一行"400、无模型",排查时没有任何信息量。 + +### 3. 失败也记 Key 前缀 + +401 时 `request.state.credential` 是空的,但**恰恰这时最需要知道客户端拿的是哪把 Key**。 +所以从 `Authorization` / `x-api-key` 里取前 8 位落库(完整 Key 绝不落盘)。 + +> 2026-10-23 实测:靠这个字段抓到客户一直在发 `wjd-5Da_…`,而库里他的有效 Key 是 +> `wjd-15zs…` —— 用的是旧 Key,与网关无关。 + +## 体量与保留 + +| 日调用量 | 单条约 | 90 天 | +|---|---|---| +| 100 次 | 400 B | ~4 MB | +| 1,000 次 | 400 B | ~36 MB | +| 10,000 次 | 400 B | ~360 MB | + +默认保留 **90 天**(`CALLLOG_RETENTION_DAYS`),启动时 + 每 6 小时清理;`VACUUM` 未自动跑, +需要时手动执行(或等保留策略删够量后由 SQLite 复用页)。 + +## 配置 + +| 环境变量 | 默认 | 说明 | +|---|---|---| +| `CALLLOG_DB` | `data/calllog.db` | 库路径 | +| `CALLLOG_RETENTION_DAYS` | `90` | 保留天数 | +| `CALLLOG_QUEUE_MAX` | `10000` | 内存队列上限(满了丢弃并计数)| +| `CALLLOG_CONTENT_MAX` | `8000` | 提示词/回复各自截断长度 | +| `CALLLOG_DISABLED` | 空 | 设为 1 可整体关闭(不影响现有行为)| + +## 已知限制 + +- 提示词内容受上游 `BODY_BY_RID` 的 2000 字符上限约束 —— 编码类长 prompt 会被截断。 + 想放长需要调 `app/main.py` 里 `limit_body` 中间件的 `raw[:2000]`。 +- 流式请求的 `latency_ms` 是**响应头返回的时间**(≈首字节时间),不是流的总时长。 +- 没有自动 `VACUUM`;库文件会随写入增长,90 天清理后页空间会被复用,不会无限膨胀。 diff --git a/frontend/src/locales/en.ts b/frontend/src/locales/en.ts index 968edaf..1642335 100644 --- a/frontend/src/locales/en.ts +++ b/frontend/src/locales/en.ts @@ -169,6 +169,8 @@ export default { byProvider: 'Calls by provider (success / fail)', }, logs: { + tabLive: 'Realtime', + tabCalls: 'Call log', all: 'All', chat: 'Chat', image: 'Image', @@ -818,5 +820,33 @@ export default { errAudioTooBig: '{name} is {size}, over the reference-audio limit of {max} (please trim or compress it)', errBodyBudget: 'This request body is about {size}, over the gateway upload limit (~{max}).', errBodyBudgetTip: 'Please use fewer materials, or smaller images/audio files.', + calllogs: { + title: 'Call log (persisted)', + count: '{n} rows', + failN: '{n} failed', + avgMs: 'avg {n}ms', + startDate: 'Start', + endDate: 'End', + account: 'Account', + model: 'Model', + result: 'Result', + onlyOk: 'OK only', + onlyFail: 'Failed only', + keyword: 'Keyword (content/rid/IP/UA)', + colTime: 'Time', + colAccount: 'Account', + colModel: 'Model', + colLatency: 'Latency', + colStatus: 'Status', + colStream: 'Stream', + colUa: 'UA', + yes: 'yes', + no: 'no', + detailTitle: 'Call detail', + prompt: 'Prompt (request body, truncated)', + completion: 'Completion (truncated)', + loading: 'Loading…', + }, + }, } diff --git a/frontend/src/locales/zh.ts b/frontend/src/locales/zh.ts index 3338857..e7ba697 100644 --- a/frontend/src/locales/zh.ts +++ b/frontend/src/locales/zh.ts @@ -169,6 +169,8 @@ export default { byProvider: '按供应商调用(成功 / 失败)', }, logs: { + tabLive: '实时', + tabCalls: '调用日志', all: '全部', chat: '对话', image: '图像', @@ -817,5 +819,33 @@ export default { errAudioTooBig: '{name} 有 {size},超过参考音频上限 {max}(请裁剪或压缩后再传)', errBodyBudget: '本次请求体约 {size},超过网关上送上限(约 {max})。', errBodyBudgetTip: '请减少素材数量,或换体积更小的图片/音频。', + calllogs: { + title: '调用日志(持久化)', + count: '共 {n} 条', + failN: '失败 {n}', + avgMs: '平均 {n}ms', + startDate: '开始日期', + endDate: '结束日期', + account: '账号', + model: '模型', + result: '结果', + onlyOk: '仅成功', + onlyFail: '仅失败', + keyword: '关键词(内容/rid/IP/UA)', + colTime: '时间', + colAccount: '账号', + colModel: '模型', + colLatency: '耗时', + colStatus: '状态', + colStream: '流式', + colUa: 'UA', + yes: '是', + no: '否', + detailTitle: '调用详情', + prompt: '提示词(请求体,截断记录)', + completion: '回复(截断记录)', + loading: '加载中…', + }, + }, } diff --git a/frontend/src/views/CallLogs.vue b/frontend/src/views/CallLogs.vue new file mode 100644 index 0000000..517c3b0 --- /dev/null +++ b/frontend/src/views/CallLogs.vue @@ -0,0 +1,239 @@ + + + + + diff --git a/frontend/src/views/Logs.vue b/frontend/src/views/Logs.vue index e4fea84..1f3ea87 100644 --- a/frontend/src/views/Logs.vue +++ b/frontend/src/views/Logs.vue @@ -1,5 +1,14 @@