init: api-gateway v2.4.0(Agnes/b.ai/火山方舟 三家供应商网关)

This commit is contained in:
api-gateway committed 2026-09-15 17:05:46 +08:00
commit 6cc65ff76f
91 files changed
+24653

No files matched your search

+1
View File
@@ -0,0 +1 @@
"""API Gateway - 统一多供应商 LLM 接入网关"""
+31
View File
@@ -0,0 +1,31 @@
"""供应商适配器注册表。"""
from __future__ import annotations
from app.adapters.base import BaseAdapter
from app.adapters.openai_compat import OpenAICompatAdapter
from app.config import ProviderConfig
def create_adapter(
pconfig: ProviderConfig, token: str, timeout: int = 120
) -> BaseAdapter:
"""根据供应商配置创建对应适配器。
当前三个供应商(Agnes / b.ai / 火山方舟)均为 OpenAI 兼容协议,
统一使用 OpenAICompatAdapter,通过 base_url 和 extra_headers 区分。
图像/视频端点通过 media 配置覆盖(Agnes 走 /videos + /agnesapi)。
"""
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
headers.update(pconfig.extra_headers)
return OpenAICompatAdapter(
name=pconfig.name,
base_url=pconfig.base_url,
headers=headers,
timeout=timeout,
media=pconfig.media,
)
+191
View File
@@ -0,0 +1,191 @@
"""适配器基类:定义统一的 chat / 流式 / 图像 / 视频接口。"""
from __future__ import annotations
import asyncio
import json
from abc import ABC, abstractmethod
from contextlib import asynccontextmanager
from typing import Any, AsyncIterator
import httpx
from app.config import MediaConfig
class UpstreamResponseError(RuntimeError):
"""上游返回了"协议外"的响应(HTTP 200 但不是 JSON / body 为空)。
第六轮: 此前这类响应直接在 `resp.json()` 处抛 json.JSONDecodeError,
错误信息是 `Expecting value: line 1 column 1 (char 0)` —— 与真正的上游 5xx
无法区分,排查时极具误导性。
"""
def json_or_raise(resp) -> dict:
"""解析上游 JSON;失败时抛带 HTTP 状态与响应片段的 UpstreamResponseError。"""
try:
data = resp.json()
except (ValueError, json.JSONDecodeError) as e:
snippet = (resp.text or "")[:200]
raise UpstreamResponseError(
f"上游返回非 JSON 响应(HTTP {resp.status_code}): {snippet!r}") from e
if not isinstance(data, dict):
raise UpstreamResponseError(
f"上游返回了非预期的 JSON 类型({type(data).__name__}),HTTP {resp.status_code}")
return data
class BaseAdapter(ABC):
"""所有供应商适配器必须实现此接口。"""
def __init__(self, name: str, base_url: str, timeout: int = 120, media: MediaConfig | None = None):
self.name = name
self.base_url = base_url.rstrip("/")
self.timeout = timeout
self.media = media or MediaConfig()
self._client: httpx.AsyncClient | None = None
self._client_lock = asyncio.Lock() # Bug 1: 防并发竞态建多个 client
self._closing = False # 正在物理关闭连接
self._close_requested = False # 收到关闭请求,但仍有在途请求,等待排空后再关
self._active = 0 # 在途请求/流占用数(Bug 4: 热重载不打断在途请求)
async def get_client(self) -> httpx.AsyncClient:
"""获取共享 client 并占用一次(并发安全)。
之前:两个 coroutine 同时 if self._client is None 各建一个 → 泄漏。
现在:用 asyncio.Lock 保证只建一次,并 +1 占用计数(每次在途请求/流占用一次)。
"""
async with self._client_lock:
if self._client is None or self._closing:
self._closing = False
self._client = httpx.AsyncClient(
base_url=self.base_url,
timeout=httpx.Timeout(self.timeout),
)
self._active += 1
return self._client
async def _release(self) -> None:
"""归还一次占用。最后一次归还且曾收到关闭请求时,才真正关闭连接池。
Bug 4 修复: 让 close() 能感知『仍有请求在用』而延迟真正的网络关闭,
避免热重载关闭 client 时打断正在流式/在途的请求。
"""
async with self._client_lock:
self._active = max(0, self._active - 1)
if self._active == 0 and self._close_requested and self._client is not None:
self._closing = True
try:
await self._client.aclose()
except Exception:
pass
self._client = None
self._closing = False
self._close_requested = False
@asynccontextmanager
async def _lease(self) -> AsyncIterator[httpx.AsyncClient]:
"""async context manager:占用 client 执行一次网络操作,结束自动归还占用。"""
client = await self.get_client()
try:
yield client
finally:
await self._release()
async def _close_now_locked(self) -> None:
"""物理关闭连接池。**调用方必须已持有 _client_lock。**
第六轮并发审计实测的竞态:`close()` 先在锁内判定 `_active == 0`,出锁后再调
`_close_now()` 重新抢锁 —— 两步之间排队的 `get_client()` 可能先拿到锁、把
`_active` 加到 1 并返回该 client,随后它被 aclose() 掉,在途请求直接
`RuntimeError: Cannot send a request, as the client has been closed.`
现在把"判定 + 关闭"合并到同一次持锁内完成。
"""
if self._client is not None:
self._closing = True
try:
await self._client.aclose()
except Exception:
pass
self._client = None
self._closing = False
self._close_requested = False
async def close(self) -> None:
"""关闭 client(幂等可重入)。
之前:并发两次 close → 第二次对已关闭 client 抛 RuntimeError。
现在:有在途请求时置 _close_requested 等待排空(由最后一次 _release 关闭);
无在途请求则立即关闭。重复调用安全。
"""
async with self._client_lock:
if self._client is None and not self._close_requested:
return
if self._active > 0:
self._close_requested = True # 等在途请求排空后由最后一次 _release 关闭
return
# 第六轮: 置位 + 关闭都在同一次持锁内完成(见 _close_now_locked 的说明)
self._close_requested = True
await self._close_now_locked()
@abstractmethod
async def chat(
self,
model: str,
messages: list[dict],
temperature: float | None = None,
top_p: float | None = None,
max_tokens: int | None = None,
stream: bool = False,
stop: str | list[str] | None = None,
tools: list[dict] | None = None,
tool_choice: str | dict | None = None,
extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""非流式 chat completion,返回统一格式的 dict。"""
...
@abstractmethod
async def chat_stream(
self,
model: str,
messages: list[dict],
temperature: float | None = None,
top_p: float | None = None,
max_tokens: int | None = None,
stop: str | list[str] | None = None,
tools: list[dict] | None = None,
tool_choice: str | dict | None = None,
extra: dict[str, Any] | None = None,
) -> AsyncIterator[dict]:
"""流式 chat completion,逐块 yield。"""
...
# ── 图像 / 视频(可选实现,默认不支持) ──────────
async def generate_image(
self,
model: str,
prompt: str,
size: str | None = None,
ratio: str | None = None,
image: list[str] | None = None,
n: int = 1,
extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
raise NotImplementedError(f"供应商 {self.name} 不支持图像生成")
async def create_video(
self,
model: str,
prompt: str,
seconds: str = "5",
mode: str = "text",
aspect_ratio: str = "16:9",
size: str = "720P",
extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
raise NotImplementedError(f"供应商 {self.name} 不支持视频创建")
async def poll_video(self, video_id: str, model: str = "", extra: dict[str, Any] | None = None) -> dict[str, Any]:
raise NotImplementedError(f"供应商 {self.name} 不支持视频查询")
+228
View File
@@ -0,0 +1,228 @@
"""OpenAI 兼容协议适配器。
Agnes / b.ai / 火山方舟 coding plan 三家均使用 OpenAI 兼容 API
(POST {base_url}/chat/completions),本适配器统一处理。
图像/视频端点可通过 media 配置覆盖:
- 图像:默认 {base_url}/images/generations(OpenAI 兼容)
- 视频:Agnes 用 {base_url}/videos 创建 + {poll_base}{poll_path}?video_id=...&model_name=... 轮询
"""
from __future__ import annotations
import json
from typing import Any, AsyncIterator
from app.adapters.base import BaseAdapter, json_or_raise
from app.models import CHAT_CORE_KEYS, PROTECTED_VIDEO_KEYS, strip_protected
class OpenAICompatAdapter(BaseAdapter):
"""适用于所有 OpenAI 兼容 /chat/completions 端点的适配器。"""
def __init__(
self,
name: str,
base_url: str,
headers: dict[str, str] | None = None,
timeout: int = 120,
media=None,
):
super().__init__(name=name, base_url=base_url, timeout=timeout, media=media)
self._headers: dict[str, str] = headers or {}
def _build_payload(
self,
model: str,
messages: list[dict],
temperature: float | None,
top_p: float | None,
max_tokens: int | None,
stream: bool,
stop: str | list[str] | None,
tools: list[dict] | None,
tool_choice: str | dict | None,
extra: dict[str, Any] | None,
) -> dict[str, Any]:
payload: dict[str, Any] = {"model": model, "messages": messages, "stream": stream}
if temperature is not None:
payload["temperature"] = temperature
if top_p is not None:
payload["top_p"] = top_p
if max_tokens is not None:
payload["max_tokens"] = max_tokens
if stop is not None:
payload["stop"] = stop
if tools:
payload["tools"] = tools
if tool_choice is not None:
payload["tool_choice"] = tool_choice
# 合并供应商特有参数(如 Agnes 的 chat_template_kwargs)。
# 第六轮安全修复: 先剔除核心键 —— 否则 `extra={"model": ..., "stream": ...}`
# 会覆盖掉上面写好的值(路由劫持 / 协议错配)。models.upstream_extra() 已过滤,
# 这里是适配器侧的最后一道防线。
# 只剔除"本函数上面刚写好的核心键";其余(网关 _PASSTHROUGH 的标准参数、
# 以及供应商特有参数)必须放行 —— 见 models.CHAT_CORE_KEYS 的说明。
if extra:
payload.update(strip_protected(extra, CHAT_CORE_KEYS))
return payload
async def chat(
self,
model: str,
messages: list[dict],
temperature: float | None = None,
top_p: float | None = None,
max_tokens: int | None = None,
stream: bool = False,
stop: str | list[str] | None = None,
tools: list[dict] | None = None,
tool_choice: str | dict | None = None,
extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
payload = self._build_payload(
model, messages, temperature, top_p, max_tokens,
stream, stop, tools, tool_choice, extra,
)
# Bug 4 修复: 用 lease 占用 client,热重载 close 会等本次请求结束才真正关连接
async with self._lease() as client:
resp = await client.post("/chat/completions", json=payload, headers=self._headers)
resp.raise_for_status()
data = json_or_raise(resp)
# 统一返回格式
return {
"provider": self.name,
"model": model,
"choices": data.get("choices", []),
"usage": data.get("usage"),
"raw": data,
"id": data.get("id", ""),
}
async def chat_stream(
self,
model: str,
messages: list[dict],
temperature: float | None = None,
top_p: float | None = None,
max_tokens: int | None = None,
stop: str | list[str] | None = None,
tools: list[dict] | None = None,
tool_choice: str | dict | None = None,
extra: dict[str, Any] | None = None,
) -> AsyncIterator[dict]:
payload = self._build_payload(
model, messages, temperature, top_p, max_tokens,
True, stop, tools, tool_choice, extra,
)
# Bug 4 修复: lease 在整个流式期间持有占用,热重载/关闭不会掐断在途流
async with self._lease() as client:
async with client.stream(
"POST", "/chat/completions", json=payload, headers=self._headers
) as resp:
resp.raise_for_status()
async for line in resp.aiter_lines():
if not line.startswith("data: "):
continue
raw = line[6:]
if raw.strip() == "[DONE]":
yield {"done": True}
break
# 本轮修复: 上游可能有非 JSON 的行(keep-alive `data: ping`、空行、
# 注释、被截断的半行)。此前 json.loads 抛异常会直接**中断整个流式响应**,
# 客户端拿到一半就断。现在跳过坏行并继续。
try:
data = json.loads(raw)
except (json.JSONDecodeError, ValueError):
continue
yield data
# ── 图像生成 ────────────────────────────────────
async def generate_image(
self,
model: str,
prompt: str,
size: str | None = None,
ratio: str | None = None,
image: list[str] | None = None,
n: int = 1,
extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
endpoint = self.media.image_endpoint or "/images/generations"
# Bug 12: 默认档位来自 media.image_default_size(默认 1K 兜底,Agnes 要求 size 必填)
size = size or self.media.image_default_size or "1K"
payload: dict[str, Any] = {"model": model, "prompt": prompt, "size": size}
# #5: 仅当需要多张才带 n(Agnes 一次一张,n=1 省略避免噪音)
if n and n != 1:
payload["n"] = n
if ratio:
payload["ratio"] = ratio
# 图生图 / 多图:图像 URL 放 extra_body.image(Agnes 写法)
extra_body: dict[str, Any] = dict(extra or {})
if image:
extra_body["image"] = image
if extra_body:
payload["extra_body"] = extra_body
async with self._lease() as client:
resp = await client.post(endpoint, json=payload, headers=self._headers)
resp.raise_for_status()
data = json_or_raise(resp)
# 统一:返回 data 数组
return {"data": data.get("data", []), "raw": data}
# ── 视频创建(异步任务) ────────────────────────
async def create_video(
self,
model: str,
prompt: str,
seconds: str = "5",
mode: str = "text",
aspect_ratio: str = "16:9",
size: str = "720P",
extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
endpoint = self.media.video_create_endpoint or "/videos"
payload: dict[str, Any] = {
"model": model,
"prompt": prompt,
"seconds": seconds,
"mode": mode,
"size": size,
"aspect_ratio": aspect_ratio,
"n": 1,
}
# 合并模式专用字段(first_frame/last_frame/images/audios 等);
# 第六轮: 但不允许覆盖 model/prompt/seconds/mode/size/aspect_ratio(同 chat 的越权面)。
for k, v in strip_protected(extra, PROTECTED_VIDEO_KEYS).items():
payload[k] = v
async with self._lease() as client:
resp = await client.post(endpoint, json=payload, headers=self._headers)
resp.raise_for_status()
data = json_or_raise(resp)
# video_id 用于查询;id/task_id 是任务 id
return {
"video_id": data.get("video_id") or data.get("id") or data.get("task_id"),
"raw": data,
}
# ── 视频轮询 ────────────────────────────────────
async def poll_video(self, video_id: str, model: str = "", extra: dict[str, Any] | None = None) -> dict[str, Any]:
mname = self.media.video_model_name or model or ""
poll_base = self.media.video_poll_base or self.base_url
poll_path = self.media.video_poll_path or "/agnesapi"
params: dict[str, str] = {"video_id": video_id}
if mname:
params["model_name"] = mname
# 轮询用绝对 URL(poll_base 可能是去掉 /v1 的域名根)
url = poll_base.rstrip("/") + poll_path
async with self._lease() as client:
resp = await client.get(url, params=params, headers=self._headers)
resp.raise_for_status()
data = json_or_raise(resp)
return {"raw": data}
+205
View File
@@ -0,0 +1,205 @@
"""供应商级熔断器(Circuit Breaker)。
状态机:CLOSED → OPEN(连续失败达到 threshold)→ HALF_OPEN(cooldown 到期)
→ 试探一次:成功回 CLOSED,失败回 OPEN。
目的:某供应商持续 502/超时期间,直接跳过白等 60s,让 fallback 快速生效。
"""
from __future__ import annotations
import logging
import threading
import time
from collections import deque
log = logging.getLogger("api-gateway.circuit")
class CircuitBreaker:
"""单供应商熔断器。线程安全。
滑动窗口按**次数**生效(最近 window 次调用里失败 ≥ failure_threshold 即熔断),
而非写死时间窗口——window 配置项真正起作用。
"""
CLOSED = "closed"
OPEN = "open"
HALF_OPEN = "half_open"
def __init__(self, provider: str, failure_threshold: int = 3, cooldown: float = 30.0, window: int = 10):
self.provider = provider
self.failure_threshold = max(1, failure_threshold)
self.cooldown = cooldown # 秒
self.window = max(1, window) # 最近 N 次调用作为判定窗口
self._lock = threading.Lock()
self._state: str = self.CLOSED
self._recent: deque[bool] = deque(maxlen=self.window) # 最近 N 次结果(按次数)
self._opened_at: float = 0.0
self._probing: bool = False # HALF_OPEN 期间是否已有试探请求在途
self._probe_at: float = 0.0 # 试探请求发出的时刻(用于探测超时兜底)
# 探测超时:HALF_OPEN 的试探请求可能**永远不回报**(客户端中途断开时
# CancelledError/GeneratorExit 不会走到 record()),若不兜底,breaker 会
# 永久停在 HALF_OPEN 并一直拒绝该供应商,直到重启或改配置。
self.probe_timeout: float = max(30.0, cooldown * 2)
def _probe_expired(self) -> bool:
return self._probing and (time.time() - self._probe_at) > self.probe_timeout
# ── 对外 API ──
def allow(self) -> bool:
"""当前是否允许调用该供应商。"""
with self._lock:
if self._state == self.CLOSED:
return True
if self._state == self.OPEN:
if time.time() - self._opened_at >= self.cooldown:
self._state = self.HALF_OPEN
self._probing = True # 本次调用即唯一试探
self._probe_at = time.time()
log.warning("[%s] 熔断 HALF_OPEN(试探)", self.provider)
return True
return False
# HALF_OPEN:只放行一个试探请求(其余拒绝,避免并发试探打穿下游)
if self._probing:
if self._probe_expired():
# 试探请求超时未回报 → 认定这次探测失败,回 OPEN 等下一轮冷却,
# 避免 breaker 被卡死在 HALF_OPEN(永久拒绝所有请求)。
self._state = self.OPEN
self._opened_at = time.time()
self._probing = False
log.warning("[%s] 试探请求 %.0fs 未回报,判定失败回 OPEN %.0fs",
self.provider, self.probe_timeout, self.cooldown)
return False
self._probing = True
self._probe_at = time.time()
return True
def release_probe(self) -> None:
"""归还 HALF_OPEN 试探令牌(调用方在 `allow()==True` 之后**没真正发请求**时调用)。
第六轮并发审计实测:拿到试探令牌后若在 record() 之前离开(限流跳过、凭证缺失
等),令牌永远不会归还 → 该供应商被半开状态**永久**拒绝。除了下面的探测超时兜底,
主动归还才是正解。
注意(第七轮回归审计):本方法不校验令牌归属,因此**只能由令牌持有者调用**,
且必须满足"`allow()==True` 与本调用之间没有 await"(否则可能把并发请求 B 在
HALF_OPEN 抢到的探测令牌误归还,导致双探)。当前全部调用点均满足该约束
(限流跳过分支、images 的 except 分支为同 tick;videos_create 的 except 分支内
不存在能抛 HTTPException 的源)。如需放宽,请改为 `allow()` 发放 probe token
并由 `release_probe(token)` 校验归属。
"""
with self._lock:
if self._state == self.HALF_OPEN and self._probing:
self._probing = False
self._probe_at = 0.0
def reconfigure(self, failure_threshold: int, cooldown: float, window: int) -> None:
"""热重载更新参数,保留当前状态与最近结果(Bug 4 修复)。"""
with self._lock:
self.failure_threshold = max(1, int(failure_threshold))
self.cooldown = cooldown
new_window = max(1, int(window))
if new_window != self.window:
self._recent = deque(self._recent, maxlen=new_window)
self.window = new_window
self.probe_timeout = max(30.0, cooldown * 2)
def reset(self) -> None:
"""强制复位到 CLOSED 并清空窗口(热重载禁用熔断时用,Bug 7)。
否则一个已 OPEN 的 breaker 即使熔断被关掉,仍会拒绝请求直到冷却结束。
"""
with self._lock:
self._state = self.CLOSED
self._recent.clear()
self._opened_at = 0.0
self._probing = False
self._probe_at = 0.0
def record(self, ok: bool) -> None:
"""记录一次调用结果(最近 window 次按次数滑动),驱动状态机。"""
now = time.time()
with self._lock:
self._recent.append(ok) # deque(maxlen=window) 自动淘汰最旧
recent_fails = sum(1 for okk in self._recent if not okk)
if self._state == self.HALF_OPEN:
self._probing = False
self._probe_at = 0.0
if ok:
self._state = self.CLOSED
self._recent.clear()
log.info("[%s] 熔断恢复 CLOSED", self.provider)
else:
self._state = self.OPEN
self._opened_at = now
log.warning("[%s] 试探失败,回 OPEN %.0fs", self.provider, self.cooldown)
elif self._state == self.CLOSED and not ok and recent_fails >= self.failure_threshold:
self._state = self.OPEN
self._opened_at = now
self._probing = False
log.warning("[%s] 最近 %d 次中失败 %d,达阈值 %d,熔断 OPEN %.0fs",
self.provider, len(self._recent), recent_fails, self.failure_threshold, self.cooldown)
def status(self) -> dict:
with self._lock:
recent_fails = sum(1 for okk in self._recent if not okk)
return {
"provider": self.provider,
"state": self._state,
"recent_failures": recent_fails,
"probing": self._probing,
"window_size": self.window,
"threshold": self.failure_threshold,
"cooldown_seconds": self.cooldown,
}
class CircuitBreakerRegistry:
"""按供应商 key 管理多个熔断器。"""
def __init__(self, default_config: dict | None = None):
self._lock = threading.Lock()
self._breakers: dict[str, CircuitBreaker] = {}
self._cfg = default_config or {}
def _defaults(self, provider: str) -> CircuitBreaker:
enabled = self._cfg.get("enabled", False)
if not enabled:
return CircuitBreaker(provider, failure_threshold=10**6, cooldown=3600)
return CircuitBreaker(
provider,
failure_threshold=self._cfg.get("failure_threshold", 3),
cooldown=self._cfg.get("cooldown", 30),
window=self._cfg.get("window", 10),
)
def get(self, provider: str) -> CircuitBreaker:
with self._lock:
if provider not in self._breakers:
self._breakers[provider] = self._defaults(provider)
return self._breakers[provider]
def update_config(self, cfg: dict) -> None:
"""热重载更新熔断参数(Bug 4 修复):就地更新已有熔断器,**保留其状态**。
之前热重载会整个重建 registry → 已熔断的坏供应商被立刻恢复重试。
"""
with self._lock:
self._cfg = dict(cfg)
enabled = self._cfg.get("enabled", False)
for cb in self._breakers.values():
if not enabled:
cb.reset() # Bug 7: 关掉熔断时复位已 OPEN 的 breaker,立刻恢复放行
cb.reconfigure(10**6, cb.cooldown, cb.window) # 等效禁用
else:
cb.reconfigure(
self._cfg.get("failure_threshold", 3),
self._cfg.get("cooldown", 30),
self._cfg.get("window", 10),
)
def statuses(self) -> list[dict]:
with self._lock:
return [b.status() for b in self._breakers.values()]
+535
View File
@@ -0,0 +1,535 @@
"""配置加载模块:从 YAML 文件读取供应商、模型、路由、鉴权、运维配置。"""
from __future__ import annotations
import os
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
import yaml
class ConfigError(ValueError):
"""配置结构性错误(缺必填项等)。启动/热重载时抛出,附友好说明。"""
# ── 模型 / 供应商 ──
@dataclass
class ModelInfo:
id: str
display_name: str = ""
type: str = "text" # text | image | video
# 第十三轮: 是否支持「图像输入」(多模态 / 视觉)。
# Agnes 3.0 Flash 文档明确「输入模态:文本、图像 URL」,实测 data:image/png;base64 也能识别;
# 其余文本模型(ark-code / b.ai 系)文档未声明图像输入 → 默认 False。
# 用途:① /v1/models 暴露给前端标注/告警;② 带图请求走路由别名时把有视觉能力的模型排到前面。
vision: bool = False
@dataclass
class AuthConfig:
token: str = ""
token_env: str = ""
def resolve_token(self) -> str:
"""优先读环境变量,其次用配置中的 token。"""
if self.token_env:
env_val = os.environ.get(self.token_env, "")
if env_val:
return env_val
return self.token
@dataclass
class MediaConfig:
"""供应商的图像/视频端点覆盖。
默认按 OpenAI 兼容路径;Agnes 等非标准端点在此覆盖。
全部为 None 表示该供应商不支持对应的媒体生成。
"""
image_endpoint: str | None = None # 相对 base_url,默认 /images/generations
image_default_size: str | None = None # 图像默认档位(Agnes 需 1K/2K/3K/4K;其它供应商可覆盖)
video_create_endpoint: str | None = None # 相对 base_url,默认 /videos
video_poll_base: str | None = None # 绝对 base(视频查询,默认同 base_url 去掉 /v1)
video_poll_path: str | None = None # 默认 /agnesapi(Agnes)
video_model_name: str | None = None # 轮询用的 model_name 参数
@property
def supports_image(self) -> bool:
return self.image_endpoint is not None
@property
def supports_video(self) -> bool:
return self.video_create_endpoint is not None
@dataclass
class ProviderConfig:
key: str
name: str
base_url: str
auth: AuthConfig
extra_headers: dict[str, str] = field(default_factory=dict)
models: list[ModelInfo] = field(default_factory=list)
media: MediaConfig = field(default_factory=MediaConfig)
rate_limit_rps: float | None = None # 该供应商全局 QPS 上限(可选)
# ── 网关入口鉴权 ──
# 账号体系(用户名/密码/API Key)由页面管理,保存在 data/users.json(见 app/users.py),
# 配置文件**不再承载**鉴权用户/密钥 —— 这里只保留前端会话时长这一个运维开关。
@dataclass
class AuthGate:
session_ttl_minutes: int = 1440 # 前端 /auth/login 签发的 session 有效时长(分钟,默认 24h)
# ── 路由别名 + 优先级 fallback ──
@dataclass
class RouteInfo:
"""路由别名 → 按优先级排列的 fallback 模型链。
models: 第 0 个为最高优先级,调用失败/超时依次切换。
timeout: 单个模型尝试的超时(秒),None 用 server.timeout。
retry: 切到下一个模型前,同一模型的重试次数(含首次)。
rate_limit_rps: 该路由别名整体 QPS 上限(None=不限)。
"""
name: str
models: list[str] = field(default_factory=list)
timeout: int | None = None
retry: int = 1
rate_limit_rps: float | None = None
@dataclass
class CircuitConfig:
"""供应商熔断器配置。"""
enabled: bool = False
failure_threshold: int = 3 # 连续/滑动窗口失败次数达到即熔断
cooldown: int = 30 # 熔断冷却秒
window: int = 10 # 滑动窗口
@dataclass
class ObservabilityConfig:
"""可观测性配置。"""
log_level: str = "INFO"
log_json: bool = False # 结构化 JSON 行日志
access_log_maxlen: int = 500 # 访问日志环形缓冲长度
@dataclass
class Pricing:
"""按模型估算成本(人民币 / 百万 token)。None 表示不估算。"""
per_model: dict[str, dict[str, float]] = field(default_factory=dict) # model -> {input, output}
def estimate(self, model: str, prompt_tokens: int, completion_tokens: int) -> float | None:
m = self.per_model.get(model)
if not m:
return None
return (prompt_tokens * m.get("input", 0) + completion_tokens * m.get("output", 0)) / 1_000_000.0
@dataclass
class DownloadConfig:
"""媒体下载代理(GET /v1/media/download)的白名单与大小限制。
产物挂在第三方 CDN 上且**不带 CORS 头**:浏览器里 `fetch` 拿不到 blob、跨域
`<a download>` 也不生效(只会变成"打开新标签页")。所以让网关代拉一次再加上
`Content-Disposition: attachment`,前端才能真下载。
这也是全网关**唯一一个服务端主动出网**的接口,因此白名单是硬性要求:
- allowed_hosts 为空 = 该功能整体关闭(任何 url 都 400,不会退化成开放代理);
- 命中的域名还要过公网 IP 校验(见 main.py `_dl_host_is_public`),挡 DNS 指内网。
"""
allowed_hosts: list[str] = field(default_factory=list) # 允许代下载的产物域名(含子域)
max_bytes: int = 64 * 1024 * 1024 # 单文件上限(默认 64MB)
@dataclass
class ServerConfig:
host: str = "127.0.0.1"
port: int = 8808
timeout: int = 120
retry: int = 1
# 运维开关
health_auth: bool = False # /health/* 是否也要鉴权(默认否,留给探活)
hot_reload: bool = False # 监听 yaml mtime 变化自动重载
hot_reload_interval: int = 15 # 重载检查间隔(秒)
metrics_enabled: bool = True # 是否记录调用指标
rate_limit_rps: float | None = None # 全局单 user QPS 上限(None=不限)
max_body_size: int = 2_000_000 # 请求体字节上限(防 DDoS)
cors_origins: list[str] = field(default_factory=lambda: ["*"])
graceful_shutdown: int = 30 # 优雅关闭等待秒
# ── 防滥用 / 安全 ──
batch_max_concurrency: int = 16 # /batch 并发上限(客户端 max_concurrency 会被钳到这个值)
batch_max_items: int = 64 # /batch 单次最大条目数(超过直接 400)
webhook_allow_private: bool = False # 视频 callback_url 是否允许指向内网/回环地址(SSRF 防护,默认否)
docs_enabled: bool = False # 是否开放 FastAPI 文档(/docs、/redoc、/openapi.json)——安全默认关
auth_fail_limit_per_min: int = 20 # 同一来源 IP 每分钟允许的鉴权失败次数,超过 → 429(防暴力枚举)
@dataclass
class GatewayConfig:
providers: dict[str, ProviderConfig] = field(default_factory=dict)
server: ServerConfig = field(default_factory=ServerConfig)
auth: AuthGate = field(default_factory=AuthGate)
routes: dict[str, RouteInfo] = field(default_factory=dict)
circuit: CircuitConfig = field(default_factory=CircuitConfig)
observability: ObservabilityConfig = field(default_factory=ObservabilityConfig)
pricing: Pricing = field(default_factory=Pricing)
download: DownloadConfig = field(default_factory=DownloadConfig)
# 模型 → (pkey, ProviderConfig, ModelInfo) 索引,避免每次请求线性扫描(性能)
_model_index: dict[str, tuple[str, ProviderConfig, ModelInfo]] = field(
default_factory=dict, init=False, repr=False, compare=False
)
def __post_init__(self) -> None:
self._rebuild_index()
def _rebuild_index(self) -> None:
index: dict[str, tuple[str, ProviderConfig, ModelInfo]] = {}
for pkey, pconfig in self.providers.items():
for m in pconfig.models:
index.setdefault(m.id, (pkey, pconfig, m)) # 重名保留首个(与原线性扫描一致)
self._model_index = index
def find_provider_for_model(self, model_id: str) -> tuple[str, ProviderConfig, ModelInfo] | None:
return self._model_index.get(model_id)
def find_route(self, model_id: str) -> RouteInfo | None:
return self.routes.get(model_id)
def validate_routes(self) -> list[str]:
"""启动校验:路由里的 model ID 是否都存在。返回告警列表(空=全合法)。"""
known = {m["id"] for m in self.all_models()}
warnings: list[str] = []
for rname, route in self.routes.items():
for mid in route.models:
if mid not in known:
warnings.append(f"路由 {rname} 引用了未知模型 '{mid}'")
return warnings
def all_models(self) -> list[dict[str, Any]]:
result = []
for pkey, pconfig in self.providers.items():
for m in pconfig.models:
result.append({
"id": m.id,
"display_name": m.display_name or m.id,
"type": m.type,
"vision": m.vision,
"provider": pkey,
"provider_name": pconfig.name,
})
return result
def all_routes(self) -> list[dict[str, Any]]:
out = []
for rname, r in self.routes.items():
out.append({
"name": rname,
"models": r.models,
"timeout": r.timeout,
"retry": r.retry,
})
return out
def _opt_float(v: Any, field_name: str = "rate_limit_rps") -> float | None:
"""可选数值解析:None/空串 → None;数字或数字字符串 → float;其它 → ConfigError。
修复:此前直接把 YAML 值塞进配置,写成字符串(如 `rate_limit_rps: "5"`)时
会在限流计算 `rps * 2` 处抛 TypeError 崩掉请求。
"""
if v is None or v == "":
return None
try:
return float(v)
except (TypeError, ValueError):
raise ConfigError(f"{field_name} 必须是数字,得到: {v!r}")
def _opt_bool(v: Any, field_name: str, default: bool = False) -> bool:
"""健壮的可选布尔解析(第二十三轮)。
起因:管理页面提交的是 JSON 真布尔,但 yaml 里手写 `"false"`(带引号)或
`yes/no/on/off` 也常见 —— 原来一律 `bool(v)`,于是字符串 `"false"` 变成 **True**,
与作者本意相反且毫无提示。现在认这些写法,认不出来直接报错(带字段名)。
"""
if v is None:
return default
if isinstance(v, bool):
return v
if isinstance(v, (int, float)):
return bool(v)
if isinstance(v, str):
s = v.strip().lower()
if s in ("1", "true", "yes", "on", "y", "t"):
return True
if s in ("0", "false", "no", "off", "n", "f", ""):
return False
raise ConfigError(f"{field_name} 必须是布尔值(true / false),得到: {v!r}")
def _opt_int(v: Any, field_name: str, default: int, minimum: int | None = None) -> int:
"""健壮的可选整数解析(第六轮)。
此前这里全是裸 `int(...)`:配置里写成 `null` / 字符串 / 留空会抛未包装的
TypeError/ValueError,而 `load_config` 在 import 期就被调用 → **进程直接起不来**
(热重载路径反而是被 try 兜住的,启动/热重载行为不一致)。
现在统一:None/空串 → 默认值;非法 → ConfigError(带字段名);可选下限校验。
"""
if v is None or v == "":
val = default
else:
try:
val = int(v)
except (TypeError, ValueError):
raise ConfigError(f"{field_name} 必须是整数,得到: {v!r}")
if minimum is not None and val < minimum:
raise ConfigError(f"{field_name} 不能小于 {minimum},得到: {val}")
return val
def _parse_media(pval: dict[str, Any]) -> MediaConfig:
m = pval.get("media", {}) or {}
return MediaConfig(
image_endpoint=m.get("image_endpoint"),
image_default_size=m.get("image_default_size"),
video_create_endpoint=m.get("video_create_endpoint"),
video_poll_base=m.get("video_poll_base"),
video_poll_path=m.get("video_poll_path"),
video_model_name=m.get("video_model_name"),
)
def _parse_download(pval: dict[str, Any]) -> DownloadConfig:
"""解析 `download:` 段(媒体下载代理白名单)。
容错:`allowed_hosts` 允许写成字符串(单个域名)或列表;自动去空白、去前导点、
转小写并去重 —— 这样 `cos-platform-outputs.agnes-ai.cn`、
`.cos-platform-outputs.agnes-ai.cn`、`COS-...` 三种写法等价。
"""
d = pval.get("download", {}) or {}
raw_hosts = d.get("allowed_hosts", []) or []
if isinstance(raw_hosts, str):
raw_hosts = [raw_hosts]
hosts: list[str] = []
for h in raw_hosts:
if not isinstance(h, str):
continue
hh = h.strip().lower().lstrip(".")
if hh and hh not in hosts:
hosts.append(hh)
return DownloadConfig(
allowed_hosts=hosts,
max_bytes=_opt_int(d.get("max_bytes"), "download.max_bytes", 64 * 1024 * 1024, minimum=1),
)
def validate_config(cfg: GatewayConfig) -> list[str]:
"""结构性校验(Bug 12 修复):返回问题列表,空 = 通过。
校验供应商必填项与路由链,给出可读的中文说明(而非运行到一半才崩)。
"""
issues: list[str] = []
if not cfg.providers:
issues.append("未配置任何供应商(providers 为空)")
for pkey, p in cfg.providers.items():
if not p.base_url:
issues.append(f"供应商 '{pkey}' 缺少 base_url")
if not p.models:
issues.append(f"供应商 '{pkey}' 未配置任何模型(models 为空)")
for idx, m in enumerate(p.models):
if not m.id:
issues.append(f"供应商 '{pkey}' 的第 {idx + 1} 个模型缺少 id")
for rname, r in cfg.routes.items():
if not r.models:
issues.append(f"路由 '{rname}' 的模型链为空")
# 账号体系已由页面管理(data/users.json,见 app/users.py),配置文件不再承载鉴权。
# 首次启动会创建 admin/admin,不存在「自锁」场景。
return issues
def validate_warnings(cfg: GatewayConfig) -> list[str]:
"""非致命告警(启动/热重载时打印,不阻止运行)。"""
warns: list[str] = []
seen: dict[str, str] = {}
for pkey, p in cfg.providers.items():
for m in p.models:
if not m.id:
continue
owner = seen.get(m.id)
if owner is not None and owner != pkey:
warns.append(f"模型 id '{m.id}' 被多个供应商定义({owner}、{pkey}),"
f"按 id 调用将始终命中 '{owner}'")
else:
seen.setdefault(m.id, pkey)
# 第六轮安全审计: 「以为已保护」的两处错觉,显式告警
# 网关鉴权恒定开启(账号体系页面管理),health_auth 总是生效。
if "*" in (cfg.server.cors_origins or []):
warns.append("cors_origins 含通配 '*' —— 任意网站的浏览器页面都能跨域驱动本网关(含消耗你的上游额度)。"
"建议把 cors_origins 收敛为可信前端域名白名单(网关鉴权已恒定开启)。")
# 供应商缺 Key / 缺模型:上线前就点出来,而不是调用时才 503 / fallback 悄悄失效
for pkey, p in cfg.providers.items():
if not p.models:
warns.append(f"供应商 '{pkey}' 没有任何模型 —— 路由链里指向它的 fallback 项永远不可用")
if not p.auth.token and not (p.auth.token_env and os.environ.get(p.auth.token_env)):
warns.append(f"供应商 '{pkey}' 未配置 API Key(token 与 token_env 均空/环境变量未设置)"
f" —— 调用该供应商的任何模型都会 503")
# (账号/密码/API Key 已改由页面管理,弱凭证检查不再适用于配置文件。)
# 路由引用了不存在的模型 id → 该 fallback 项永远不可用(多半是打错字)
known = {m["id"] for m in cfg.all_models()}
for r in cfg.all_routes():
miss = [mid for mid in r["models"] if mid not in known]
if miss:
warns.append(f"路由 '{r['name']}' 引用了未定义的模型 {miss} —— 这些 fallback 项永远不可用")
return warns
def load_config(path: str | Path) -> GatewayConfig:
"""从 YAML 文件加载完整网关配置。
结构性错误(缺供应商/缺 base_url/空模型链等)抛 ConfigError,带友好说明。
"""
path = Path(path)
if not path.exists():
raise FileNotFoundError(f"配置文件不存在: {path}")
with open(path, "r", encoding="utf-8") as f:
raw: dict[str, Any] = yaml.safe_load(f) or {}
return parse_config(raw)
def parse_config(raw: dict[str, Any]) -> GatewayConfig:
"""把一份 YAML 字典解析成 GatewayConfig(不做文件 IO)。
第二十三轮拆出来:管理页面(app/settings.py)保存前要**先在内存里校验**这份配置,
不能让"写坏文件 → 重启起不来"发生;同时面板也用同一套解析得到"面板视图"。
解析与校验口径与 load_config 完全一致(load_config 现在就是"读文件 + 这里")。
"""
raw = raw or {}
providers: dict[str, ProviderConfig] = {}
for pkey, pval in raw.get("providers", {}).items():
auth_raw = pval.get("auth", {}) or {}
auth = AuthConfig(
token=auth_raw.get("token", ""),
token_env=auth_raw.get("token_env", ""),
)
models = [
ModelInfo(id=m.get("id", ""), display_name=m.get("display_name", ""),
type=m.get("type", "text"), vision=_opt_bool(m.get("vision"), "providers.*.models.*.vision", False))
for m in pval.get("models", [])
]
providers[pkey] = ProviderConfig(
key=pkey,
name=pval.get("name", pkey),
base_url=pval.get("base_url", ""),
auth=auth,
extra_headers=pval.get("extra_headers", {}) or {},
models=models,
media=_parse_media(pval),
rate_limit_rps=_opt_float(pval.get("rate_limit_rps")),
)
srv_raw = raw.get("server", {}) or {}
# 第二十三轮: port 也走 _opt_int —— 此前是裸 `srv_raw.get("port", 8808)`,
# 配置里写成字符串/空值会**穿过校验**,直到 uvicorn 绑定端口时才炸(而且报的是
# 一个跟配置无关的堆栈)。管理页面可以直接改端口,更得在这里拦住。
port = _opt_int(srv_raw.get("port"), "server.port", 8808, minimum=1)
if port > 65535:
raise ConfigError(f"server.port 必须在 1-65535 之间,得到: {port}")
server = ServerConfig(
host=str(srv_raw.get("host") or "127.0.0.1"),
port=port,
timeout=_opt_int(srv_raw.get("timeout"), "server.timeout", 120, minimum=1),
retry=_opt_int(srv_raw.get("retry"), "server.retry", 1, minimum=1),
health_auth=_opt_bool(srv_raw.get("health_auth"), "server.health_auth", False),
hot_reload=_opt_bool(srv_raw.get("hot_reload"), "server.hot_reload", False),
hot_reload_interval=_opt_int(srv_raw.get("hot_reload_interval"), "server.hot_reload_interval", 15, minimum=1),
metrics_enabled=_opt_bool(srv_raw.get("metrics_enabled"), "server.metrics_enabled", True),
rate_limit_rps=_opt_float(srv_raw.get("rate_limit_rps")),
max_body_size=_opt_int(srv_raw.get("max_body_size"), "server.max_body_size", 2_000_000, minimum=1),
cors_origins=list(srv_raw.get("cors_origins", ["*"])),
graceful_shutdown=_opt_int(srv_raw.get("graceful_shutdown"), "server.graceful_shutdown", 30, minimum=0),
batch_max_concurrency=_opt_int(srv_raw.get("batch_max_concurrency"), "server.batch_max_concurrency", 16, minimum=1),
batch_max_items=_opt_int(srv_raw.get("batch_max_items"), "server.batch_max_items", 64, minimum=1),
webhook_allow_private=_opt_bool(srv_raw.get("webhook_allow_private"), "server.webhook_allow_private", False),
docs_enabled=_opt_bool(srv_raw.get("docs_enabled"), "server.docs_enabled", False),
auth_fail_limit_per_min=_opt_int(srv_raw.get("auth_fail_limit_per_min"),
"server.auth_fail_limit_per_min", 20, minimum=1),
)
# 网关入口鉴权(客户端 key 数组,可配多用户)
auth_raw = raw.get("auth", {}) or {}
# 账号体系已改由页面管理(data/users.json,见 app/users.py);配置文件不再含用户/密钥,
# 仅保留前端会话时长这一个运维开关。
auth = AuthGate(session_ttl_minutes=_opt_int(auth_raw.get("session_ttl_minutes"),
"auth.session_ttl_minutes", 1440, minimum=1))
# 路由别名 → 优先级 fallback 链(支持 list 或 dict 两种写法)
routes_raw = raw.get("routes", {}) or {}
routes: dict[str, RouteInfo] = {}
for rname, rval in routes_raw.items():
if isinstance(rval, dict):
chain: list[str] = []
for item in (rval.get("models", []) or []):
if isinstance(item, str):
chain.append(item)
elif isinstance(item, dict) and item.get("model"):
chain.append(item["model"])
routes[rname] = RouteInfo(
name=rname,
models=chain,
# 注意 minimum=0:缺省值是 0(=未设置,下面 `or None` 转 None)。
# 若写 minimum=1,会让"路由没写 timeout"的配置直接报 ConfigError —— 这正是
# 第七轮自查抓到的一个自伤 bug(之前只有在配置恰好写了 timeout 时才不炸)。
timeout=(_opt_int(rval.get("timeout"), f"routes.{rname}.timeout", 0, minimum=0) or None),
retry=_opt_int(rval.get("retry"), f"routes.{rname}.retry", 1, minimum=1),
rate_limit_rps=_opt_float(rval.get("rate_limit_rps")),
)
else:
chain = [x for x in (rval or []) if isinstance(x, str)]
routes[rname] = RouteInfo(name=rname, models=chain)
# 熔断器
c_raw = raw.get("circuit", {}) or {}
circuit = CircuitConfig(
enabled=_opt_bool(c_raw.get("enabled"), "circuit.enabled", False),
failure_threshold=_opt_int(c_raw.get("failure_threshold"), "circuit.failure_threshold", 3, minimum=1),
cooldown=_opt_int(c_raw.get("cooldown"), "circuit.cooldown", 30, minimum=1),
window=_opt_int(c_raw.get("window"), "circuit.window", 10, minimum=1),
)
# 可观测性
o_raw = raw.get("observability", {}) or {}
observability = ObservabilityConfig(
log_level=str(o_raw.get("log_level", "INFO")),
log_json=_opt_bool(o_raw.get("log_json"), "observability.log_json", False),
access_log_maxlen=_opt_int(o_raw.get("access_log_maxlen"), "observability.access_log_maxlen", 500, minimum=1),
)
# 定价(用于成本估算)
p_raw = raw.get("pricing", {}) or {}
per_model: dict[str, dict[str, float]] = {}
for pm, pv in (p_raw.get("per_model", {}) or {}).items():
per_model[pm] = {
"input": _opt_float(pv.get("input"), f"pricing.per_model.{pm}.input") or 0.0,
"output": _opt_float(pv.get("output"), f"pricing.per_model.{pm}.output") or 0.0,
}
pricing = Pricing(per_model=per_model)
cfg = GatewayConfig(
providers=providers, server=server, auth=auth, routes=routes,
circuit=circuit, observability=observability, pricing=pricing,
download=_parse_download(raw),
)
# Bug 12 修复: 结构性校验,坏配置立刻抛友好错误(启动/热重载都能拦住)
issues = validate_config(cfg)
if issues:
raise ConfigError("配置校验失败:\n - " + "\n - ".join(issues))
return cfg
+427
View File
@@ -0,0 +1,427 @@
"""意见反馈(第二十二轮):普通账号提意见(可附图),管理员在「用户反馈」页看全部。
为什么单独一个文件、不塞进 history.py:
history 的语义是「每个账号自己的生成记录 + 按 id upsert 覆盖」(前端可以整份重推);
反馈是「一次性提交、不可改、管理员全局只读」—— 生命周期与读写模式都不一样,
混在一起只会让两边的边界都变模糊。
存储形态(沿用本项目「无 DB」的约束):
- data/feedback.json:`{"items": [条目…]}`,条目按「新 → 旧」;
- data/feedback_media/<fid>-<i>.<ext>:图片正文(解码后的二进制)。
为什么图片落文件、缩略图进 JSON:
一条最多 3 张图、每张压到 ~300KB(base64 后 ×1.37)→ 单单图片就 1.2MB。
若全塞进 JSON,而 JSON 是「每次写入都重写整份」的,几十条就能把它顶到几十 MB
(history.py 的注释里记过同一个坑)。拆开之后:
- JSON 维持百 KB 级,列表页靠内嵌的**缩略图**(≤320px,一二十 KB)零额外请求就能预览;
- 点开大图才走 GET /feedback/media/{fid}/{i} 取那一张。
容量与边界:
- 最多 max_entries 条(默认 500),超了丢最旧的一条并**连带删掉它的图片文件**;
- 正文 ≤ MAX_CONTENT 字符;图片 ≤ MAX_IMAGES 张、每张解码后 ≤ MAX_IMAGE_BYTES;
- 图片类型以**解码后的魔数**为准(不信任客户端声明的 MIME),只收 jpeg/png/webp/gif;
- 正文/缩略图都按 UTF-8 逐字符计数,避免"看着没超,字节超了";
- 每条另存 `history`(处理记录):提交 + 每一次状态变更(谁/何时/从哪到哪/说明),
只增不改,最多 MAX_STEPS 条;老数据在 _load 时按现有字段补出来(见 _fix_history)。
权限在 main.py 里判(存储层只管数据):提交看自己 = 任意登录会话;看全部/看别人的图 = admin;
「撤回」= 提交人本人 + 还停在「待处理」(`withdraw`)。
"""
from __future__ import annotations
import base64
import json
import os
import re
import threading
import time
from uuid import uuid4
MAX_ENTRIES = 500 # 保留条数(超出丢最旧,含其图片文件)
MAX_CONTENT = 2000 # 正文上限(字符)
MAX_NOTE = 500 # 管理员处理说明上限(字符)
MAX_IMAGES = 3 # 每条最多几张图
MAX_IMAGE_BYTES = 700_000 # 单张原图解码后上限(字节)
MAX_THUMB_BYTES = 150_000 # 单张缩略图解码后上限(字节)
MAX_NAME_CHARS = 80 # 原文件名只做展示,截断防超长
# 处理进度(第二十二轮追加):提交即 pending,管理员在「用户反馈」里改。
# 状态机就三档,别搞复杂 —— 提交人看进度、管理员改状态,够了。
STATUSES = ("pending", "doing", "done")
MAX_STEPS = 50 # 每条反馈最多留多少条处理记录(超出丢最旧,只影响展示)
_URI_HEAD = re.compile(r"^data:image/[a-z0-9.+-]+;base64,", re.I)
def _step(ts, frm, to, note, by) -> dict:
"""一条处理记录。`from` 为空串表示「提交」那一步(没有前一个状态)。"""
return {
"ts": round(float(ts or 0), 1),
"from": str(frm or ""),
"to": str(to or "pending"),
"note": note if isinstance(note, str) else "",
"by": str(by or ""),
}
def _fix_history(e: dict) -> list[dict]:
"""处理记录:老数据(本轮之前提交的)没有 history —— 用现有字段补出来,
保证「每个环节都有记录」对历史单子也成立:
第 1 条「提交 → 待处理」(提交人自己);
若已经推进过,再补 1 条「待处理 → 现状态」(当时是谁点的已不可考,by 留空)。
"""
h = e.get("history")
if isinstance(h, list) and h:
out = []
for s in h:
if not isinstance(s, dict):
continue
out.append(_step(
s.get("ts") or e.get("created"),
s.get("from"),
s.get("to") if s.get("to") in STATUSES else "pending",
s.get("note"),
s.get("by"),
))
if out:
return out[-MAX_STEPS:]
created = e.get("created") or 0
built = [_step(created, "", "pending", "", e.get("account"))]
st = e.get("status") or "pending"
if st != "pending":
built.append(_step(e.get("updated") or created, "pending", st, e.get("note") or "", ""))
return built
class FeedbackError(Exception):
"""校验失败(main.py 映射为 400)。"""
def _sniff(data: bytes) -> str | None:
"""按魔数认图片类型。不信任客户端写的 MIME —— 扩展名/声明都能伪造。"""
if data.startswith(b"\xff\xd8\xff"):
return "jpeg"
if data.startswith(b"\x89PNG\r\n\x1a\n"):
return "png"
if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
return "webp"
if data[:6] in (b"GIF87a", b"GIF89a"):
return "gif"
return None
def _decode_image(uri, max_bytes: int, label: str) -> tuple[bytes, str]:
"""data URI → (二进制, 类型)。任何不合规都抛 FeedbackError(不静默丢弃)。"""
if not isinstance(uri, str) or not uri.startswith("data:"):
raise FeedbackError(f"{label}必须是 data URI 图片")
i = uri.find(",")
if i < 0 or not _URI_HEAD.match(uri[: i + 8]):
raise FeedbackError(f"{label}只支持 base64 编码的图片 data URI")
try:
raw = base64.b64decode(uri[i + 1:], validate=True)
except Exception:
raise FeedbackError(f"{label}的 base64 内容损坏")
if not raw:
raise FeedbackError(f"{label}是空文件")
if len(raw) > max_bytes:
raise FeedbackError(f"{label}解码后 {len(raw) // 1024}KB,超过 {max_bytes // 1024}KB 上限")
kind = _sniff(raw)
if kind is None:
raise FeedbackError(f"{label}不是可识别的图片(只收 jpeg/png/webp/gif)")
return raw, kind
def _clean_text(v, limit: int, label: str) -> str:
s = v if isinstance(v, str) else ""
s = s.strip()
if len(s) > limit:
raise FeedbackError(f"{label}最多 {limit} 字(当前 {len(s)})")
return s
def _thumb_uri(raw: bytes, kind: str) -> str:
"""把落盘的缩略图重新拼回 data URI(列表页 <img> 直接用,CSP 已放行 data:)。"""
mime = "image/jpeg" if kind in ("jpeg", "jpg") else f"image/{kind}"
return f"data:{mime};base64," + base64.b64encode(raw).decode("ascii")
class FeedbackStore:
def __init__(self, path: str, media_dir: str, max_entries: int = MAX_ENTRIES):
self._path = path
self._media_dir = media_dir
self._max = max(1, int(max_entries))
self._lock = threading.Lock()
self._items: list[dict] = []
self._load()
self._prune_media()
# ── 持久化 ─────────────────────────────
def _load(self) -> None:
try:
with open(self._path, encoding="utf-8") as f:
d = json.load(f)
items = d.get("items") if isinstance(d, dict) else d
self._items = [it for it in (items or []) if isinstance(it, dict)]
except FileNotFoundError:
self._items = []
except Exception:
# 坏文件不能让网关起不来:备份后从空开始(与 history.py 同一口径)
try:
os.replace(self._path, self._path + ".bad")
except OSError:
pass
self._items = []
# 补齐/纠正进度字段:老数据(没有 status 的)按待处理算,非法值也归到待处理,
# 免得前端拿到一个它不认识的状态白屏;处理记录缺失的按现有字段补出来。
for e in self._items:
if e.get("status") not in STATUSES:
e["status"] = "pending"
e["note"] = e.get("note") if isinstance(e.get("note"), str) else ""
if not isinstance(e.get("updated"), (int, float)):
e["updated"] = e.get("created") or 0
e["history"] = _fix_history(e)
def _save(self) -> None:
# 调用方持锁
d = os.path.dirname(self._path)
if d and not os.path.isdir(d):
os.makedirs(d, exist_ok=True)
tmp = self._path + ".tmp"
with open(tmp, "w", encoding="utf-8") as f:
json.dump({"items": self._items}, f, ensure_ascii=False)
os.chmod(tmp, 0o600) # 反馈是隐私内容
os.replace(tmp, self._path)
# ── 图片文件 ───────────────────────────
def _img_path(self, fid: str, idx: int, ext: str) -> str:
return os.path.join(self._media_dir, f"{fid}-{idx}.{ext}")
def _write_image(self, fid: str, idx: int, raw: bytes, kind: str) -> None:
if not os.path.isdir(self._media_dir):
os.makedirs(self._media_dir, exist_ok=True)
p = self._img_path(fid, idx, kind)
with open(p, "wb") as f:
f.write(raw)
os.chmod(p, 0o600)
def _drop_media(self, entry: dict) -> None:
"""删掉某条反馈的全部图片文件(条目被淘汰 / 数据修复时用)。"""
fid = str(entry.get("id") or "")
if not fid:
return
for i in range(len(entry.get("images") or [])):
for ext in ("jpeg", "png", "webp", "gif"):
try:
os.remove(self._img_path(fid, i, ext))
except OSError:
pass
def _prune_media(self) -> None:
"""清掉不属于任何现存条目的图片文件(异常中断留下的孤儿)。"""
if not os.path.isdir(self._media_dir):
return
alive = {str(e.get("id")) for e in self._items if e.get("id")}
try:
names = os.listdir(self._media_dir)
except OSError:
return
for name in names:
fid = name.rsplit("-", 1)[0]
if fid not in alive:
try:
os.remove(os.path.join(self._media_dir, name))
except OSError:
pass
# ── 写 ─────────────────────────────────
def add(self, account: str, content, images) -> dict:
"""新增一条反馈,返回落库后的条目(含缩略图)。校验失败抛 FeedbackError。"""
text = _clean_text(content, MAX_CONTENT, "反馈内容")
if not text:
raise FeedbackError("反馈内容不能为空")
imgs = images if isinstance(images, list) else []
if len(imgs) > MAX_IMAGES:
raise FeedbackError(f"最多上传 {MAX_IMAGES} 张图片(当前 {len(imgs)} 张)")
# 先全部解码校验(任何一张不合格就整条拒绝,不留半成品文件)
decoded: list[tuple[bytes, str, str, bytes | None, str | None, str]] = []
for i, it in enumerate(imgs):
if not isinstance(it, dict):
raise FeedbackError(f"第 {i + 1} 张图片格式不对")
label = f"第 {i + 1} 张图片"
raw, kind = _decode_image(it.get("uri"), MAX_IMAGE_BYTES, label)
thumb_raw = thumb_kind = None
if it.get("thumb"):
thumb_raw, thumb_kind = _decode_image(it.get("thumb"), MAX_THUMB_BYTES, f"{label}的缩略图")
name = _clean_text(it.get("name"), MAX_NAME_CHARS, f"{label}文件名")
decoded.append((raw, kind, name, thumb_raw, thumb_kind, label))
fid = "f%d-%s" % (int(time.time()), uuid4().hex[:6])
entry_images: list[dict] = []
for i, (raw, kind, name, thumb_raw, thumb_kind, _label) in enumerate(decoded):
self._write_image(fid, i, raw, kind)
entry_images.append({
"name": name,
"bytes": len(raw),
# 缩略图内嵌 JSON:列表页零请求就能预览(体积:一二十 KB/张)
"thumb": _thumb_uri(thumb_raw, thumb_kind) if thumb_raw else "",
"type": kind,
})
now = round(time.time(), 1)
who = account or "anonymous"
entry = {
"id": fid,
"account": who,
"content": text,
"created": now,
"images": entry_images,
# 进度:提交即「待处理」,管理员在「用户反馈」里推进
"status": "pending",
"note": "",
"updated": now,
# 处理记录第 1 条=提交(后面的每一步由 update() 追加,只增不改)
"history": [_step(now, "", "pending", "", who)],
}
with self._lock:
self._items.insert(0, entry)
evicted = self._items[self._max:]
del self._items[self._max:]
self._save()
for e in evicted: # 落盘之后再删文件,避免"删了文件但条目还在"
self._drop_media(e)
return entry
# ── 处理进度(只有管理员能改,权限在 main.py 判) ──────────
def update(self, fid: str, status, note, by: str = "") -> dict:
"""更新某条反馈的处理状态 / 处理说明,返回更新后的条目。
**每一步都进 `history`(只增不改)**:谁(by)、什么时候(ts)、
从哪个状态到哪个状态(from → to)、留了什么说明(note)。
提交人看到的「处理记录」就是这个数组,管理员改几次就有几条。
fid 不存在返回 {}(调用方据此 404);参数不合法抛 FeedbackError。
"""
if status not in STATUSES:
raise FeedbackError("处理状态只能是 pending / doing / done")
text = _clean_text(note, MAX_NOTE, "处理说明")
with self._lock:
hit = next((e for e in self._items if str(e.get("id")) == str(fid)), None)
if hit is None:
return {}
step = _step(time.time(), hit.get("status"), status, text, by)
hit["status"] = status
hit["note"] = text
hit["updated"] = step["ts"]
hist = hit.get("history") if isinstance(hit.get("history"), list) else []
hit["history"] = (hist + [step])[-MAX_STEPS:]
self._save()
return dict(hit)
# ── 撤回(只有提交人本人、且还停在「待处理」时) ────────────
def withdraw(self, account: str, fid: str) -> dict:
"""提交人撤回自己的反馈,返回 {"ok": True, "item": …} 或 {"ok": False, "reason": …}。
规则(老板 2026-09-13 追加):**待处理**的单子提交人可以自己撤回;
一旦管理员推进到「处理中 / 已处理」,就不允许再撤 —— 否则管理员白干一场,
而且"已处理"的单子从提交人列表里凭空消失也不合理。
reason:notfound(没这条)/ forbidden(不是自己的)/ locked(已进流程)。
"""
who = account or "anonymous"
with self._lock:
idx = next((i for i, e in enumerate(self._items) if str(e.get("id")) == str(fid)), None)
if idx is None:
return {"ok": False, "reason": "notfound"}
entry = self._items[idx]
if str(entry.get("account") or "") != who:
return {"ok": False, "reason": "forbidden"}
if entry.get("status") != "pending":
return {"ok": False, "reason": "locked"}
del self._items[idx]
self._save()
# 落盘之后再删图片文件(与容量淘汰同一顺序,避免"文件没了条目还在")
self._drop_media(entry)
return {"ok": True, "item": entry}
# ── 归档 / 删除(管理员,收件箱专属;第N轮追加)─────────────────
def set_archived(self, fid: str, archived: bool) -> dict:
"""归档/取消归档一条反馈(管理员在收件箱里整理用)。
归档不清数据、不动处理状态 —— 只是打 `archived` 标记,让收件箱能按
「未归档 / 全部 / 已归档」过滤看。旧数据(本轮之前)没有该字段:视为未归档。
提交人自己仍然能看到自己的那条(归档只影响管理员收件箱的整洁度)。
"""
with self._lock:
hit = next((e for e in self._items if str(e.get("id")) == str(fid)), None)
if hit is None:
return {}
hit["archived"] = bool(archived)
hit["updated"] = round(time.time(), 1)
self._save()
return dict(hit)
def admin_delete(self, fid: str) -> dict:
"""管理员永久删除一条反馈(连同它的全部图片文件)。不存在返回 {}。"""
with self._lock:
idx = next((i for i, e in enumerate(self._items) if str(e.get("id")) == str(fid)), None)
if idx is None:
return {}
entry = self._items.pop(idx)
self._save()
self._drop_media(entry) # 落盘后再删图片,避免"文件没了条目还在"
return entry
# ── 读 ─────────────────────────────────
def mine(self, account: str) -> list[dict]:
with self._lock:
return [dict(e) for e in self._items if e.get("account") == (account or "anonymous")]
def all(self) -> list[dict]:
with self._lock:
return [dict(e) for e in self._items]
def count(self) -> int:
with self._lock:
return len(self._items)
def owner_of(self, fid: str) -> str | None:
"""条目归属账号;条目不存在返回 None(调用方据此 404)。"""
with self._lock:
for e in self._items:
if str(e.get("id")) == str(fid):
return str(e.get("account") or "")
return None
def image_count(self, fid: str) -> int:
with self._lock:
for e in self._items:
if str(e.get("id")) == str(fid):
return len(e.get("images") or [])
return 0
def media_uri(self, fid: str, idx: int) -> str | None:
"""读原图并拼成 data URI。fid 必须先在库里存在(查不到直接 None,不做路径拼接猜测)。"""
with self._lock:
hit = next((e for e in self._items if str(e.get("id")) == str(fid)), None)
if hit is None or idx < 0 or idx >= len(hit.get("images") or []):
return None
meta = hit["images"][idx]
kind = str(meta.get("type") or "jpeg")
if kind not in ("jpeg", "png", "webp", "gif"):
return None
try:
with open(self._img_path(fid, idx, kind), "rb") as f:
raw = f.read()
except OSError:
return None
return _thumb_uri(raw, kind)
def stats(self) -> dict:
with self._lock:
return {
"count": len(self._items),
"with_images": sum(1 for e in self._items if e.get("images")),
"cap": self._max,
"bytes": os.path.getsize(self._path) if os.path.exists(self._path) else 0,
}
+204
View File
@@ -0,0 +1,204 @@
"""按账号持久化的前端历史(图像 / 视频 / 对话)。
背景:这三类历史原先只存在浏览器里(图像、视频在 localStorage,对话在 sessionStorage),
于是有三个老问题:① 换设备/换浏览器就看不见;② 关标签页对话即丢;③ 视频每条带一大段
上游 rawtext,很容易把 5MB 配额撑满,而前端 `setItem` 失败是被静默 catch 掉的 ——
表现就是"生成过的东西莫名其妙没了"。
这里给一份最小落盘存储(纯标准库、无数据库,符合本项目"无 DB"的架构约束):
data/history.json,结构 `{账号: {类别: [条目...]}}`,条目按"新→旧"排列。
写入语义是 **按 id upsert**(前端提交增量或整份都可以):带已存在 id 的条目就地更新
(视频状态从"生成中"变"完成"就是走这条路),没有 id 或 id 没见过的新插到最前。
这样两台设备各自生成图像/视频时不会互相整份覆盖掉 —— 这是"全量 PUT"最容易踩的坑。
边界控制:
- 每账号每类别最多 MAX_ITEMS 条(超出截掉最旧的尾部);
- 单条序列化超过 MAX_ITEM_BYTES 时,把里面过长的字符串字段截断(rawtext/推理正文这类);
- 整份文件超过 MAX_FILE_BYTES 时,按账号逐个削条目,保证不会无限膨胀;
- 文件权限 600(里面是提示词/回答正文,属隐私),且已进 .gitignore。
并发:写操作都在锁内做「改 + 落盘」,读走快照,单实例够用。
"""
from __future__ import annotations
import json
import os
import threading
KINDS = ("chat", "images", "videos")
# 各类别的容量按"内容天然体量"分开定:对话一条就是一整段多轮消息(正文可能很长),
# 图像一条只有 URL + prompt,视频一条带一段上游 raw 回执 —— 一刀切会把对话正文截坏。
LIMITS: dict[str, dict[str, int]] = {
"chat": {"items": 50, "item_bytes": 512 * 1024, "field_chars": 20000},
"images": {"items": 200, "item_bytes": 8 * 1024, "field_chars": 1200},
"videos": {"items": 200, "item_bytes": 16 * 1024, "field_chars": 2000},
}
MAX_ITEMS = 200 # 兜底默认(未知类别用)
MAX_ITEM_BYTES = 8 * 1024
MAX_FIELD_CHARS = 1200
MAX_FILE_BYTES = 4 * 1024 * 1024 # 整份 history.json 的软上限
def _lim(kind: str) -> dict[str, int]:
return LIMITS.get(kind, {"items": MAX_ITEMS, "item_bytes": MAX_ITEM_BYTES,
"field_chars": MAX_FIELD_CHARS})
class HistoryError(Exception):
"""校验失败(映射为 400)。"""
def _shrink(obj, field_chars: int, depth: int = 0):
"""递归压缩:长字符串截断、容器规模限制,防单条撑爆配额。"""
if isinstance(obj, str):
return obj if len(obj) <= field_chars else obj[:field_chars] + "…(已截断)"
if depth > 6:
return "…(层级过深)"
if isinstance(obj, list):
return [_shrink(v, field_chars, depth + 1) for v in obj[:2000]]
if isinstance(obj, dict):
return {str(k)[:64]: _shrink(v, field_chars, depth + 1) for k, v in list(obj.items())[:64]}
if isinstance(obj, (int, float, bool)) or obj is None:
return obj
return _shrink(str(obj), field_chars, depth + 1)
def _normalize_item(item, kind: str) -> dict | None:
"""条目必须是对象;顺手做体积收缩。返回 None 表示非法条目(丢弃)。"""
if not isinstance(item, dict):
return None
lim = _lim(kind)
s = json.dumps(item, ensure_ascii=False, default=str)
if len(s.encode("utf-8")) > lim["item_bytes"]:
s = json.dumps(_shrink(item, lim["field_chars"]), ensure_ascii=False, default=str)
try:
item = json.loads(s)
except Exception:
return None
return item
class HistoryStore:
def __init__(self, path: str):
self._path = path
self._lock = threading.Lock()
self._data: dict = {}
self._load()
# ── 持久化 ─────────────────────────────
def _load(self) -> None:
try:
with open(self._path, encoding="utf-8") as f:
d = json.load(f)
self._data = d if isinstance(d, dict) else {}
except FileNotFoundError:
self._data = {}
except Exception:
# 坏文件不能让网关起不来:备份后从空开始
try:
os.replace(self._path, self._path + ".bad")
except OSError:
pass
self._data = {}
def _save(self) -> None:
# 调用方持锁。超软上限时按账号逐个削最旧的尾部(前端提交顺序是新→旧)。
while len(self._data) and len(json.dumps(self._data, ensure_ascii=False).encode()) > MAX_FILE_BYTES:
trimmed = False
for acc in list(self._data):
for kind in list(self._data.get(acc) or {}):
lst = self._data[acc][kind]
if len(lst) > 10:
del lst[len(lst) // 2:]
trimmed = True
break
if trimmed:
break
if not trimmed:
break
d = os.path.dirname(self._path)
if d and not os.path.isdir(d):
os.makedirs(d, exist_ok=True)
tmp = self._path + ".tmp"
with open(tmp, "w", encoding="utf-8") as f:
json.dump(self._data, f, ensure_ascii=False)
os.chmod(tmp, 0o600)
os.replace(tmp, self._path)
# ── 读写 ───────────────────────────────
@staticmethod
def _check_kind(kind: str) -> str:
if kind not in KINDS:
raise HistoryError(f"未知历史类别 {kind!r},可选:{'/'.join(KINDS)}")
return kind
def get(self, account: str, kind: str) -> list[dict]:
self._check_kind(kind)
with self._lock:
return list(((self._data.get(account) or {}).get(kind)) or [])
def upsert(self, account: str, kind: str, items: list) -> list[dict]:
"""按 id 合并写入,返回合并后的整份列表。
- 条目必须是对象;带 `id` 且已存在 → 原地替换(保留原位置,视频状态刷新走这里)
- 无 `id` 或 id 没见过 → 新插到最前面
- 合并后裁剪到 MAX_ITEMS 条(丢最旧的尾部)
"""
if not isinstance(items, list):
raise HistoryError("items 必须是数组")
lim = _lim(kind)
incoming = [it for it in (_normalize_item(x, kind) for x in items) if it is not None]
if not incoming:
return self.get(account, kind)
with self._lock:
acc = self._data.setdefault(account or "anonymous", {})
lst = acc.setdefault(kind, [])
index = {str(it.get("id")): i for i, it in enumerate(lst) if it.get("id") is not None}
for it in incoming:
iid = it.get("id")
key = str(iid) if iid is not None else None
if key is not None and key in index:
lst[index[key]] = it
else:
lst.insert(0, it)
# 第十八轮: 无条件重建索引 —— 此前只在"带 id 的新条目"分支重建,
# 而**无 id 的插入同样会把后面所有元素顶后一位**,旧下标随即失效:
# 同一批 items 里「无 id 新增 + 带 id 更新」混排时,后者会按过期下标
# 覆盖到错误的位置(接口契约允许这么传,只是前端目前总带 id)。
index = {str(x.get("id")): i for i, x in enumerate(lst)
if x.get("id") is not None}
del lst[lim["items"]:]
self._save()
return list(lst)
def delete_item(self, account: str, kind: str, item_id: str) -> bool:
"""按 id 删单条(前端逐条删除用这个)。"""
self._check_kind(kind)
with self._lock:
acc = self._data.get(account or "anonymous") or {}
lst = acc.get(kind) or []
keep = [it for it in lst if str(it.get("id")) != str(item_id)]
if len(keep) == len(lst):
return False
acc[kind] = keep
self._save()
return True
def clear(self, account: str, kind: str) -> int:
self._check_kind(kind)
with self._lock:
acc = self._data.get(account or "anonymous") or {}
n = len(acc.get(kind) or [])
acc[kind] = []
self._save()
return n
def stats(self) -> dict:
with self._lock:
return {
"accounts": len(self._data),
"items": {k: sum(len((a or {}).get(k) or []) for a in self._data.values()) for k in KINDS},
"bytes": os.path.getsize(self._path) if os.path.exists(self._path) else 0,
}
+3175
View File
File diff suppressed because it is too large. Load diff
+333
View File
@@ -0,0 +1,333 @@
"""用量指标、访问日志、简单限流。
设计为无外部依赖、进程内内存态,足够网关运维排障用。
"""
from __future__ import annotations
import logging
import math
import threading
import time
from collections import deque
from contextvars import ContextVar
from typing import Any
log = logging.getLogger("api-gateway.metrics")
# 请求级「归属账号」上下文(ContextVar,每 task/请求独立;由 main.py require_auth 写入)。
# 访问日志与指标通过它给每条记录打上账号,实现:
# 普通账号只看自己名下(会话 + 自己的 API Key)产生的记录,admin 看全部。
ACCOUNT: ContextVar[str] = ContextVar("gw_account", default="anonymous")
ROLE: ContextVar[str] = ContextVar("gw_role", default="member")
# M4: 按 rid 暂存请求体摘要(由 main.py 中间件写入)。AccessLog.add() 用它给每条日志
# 附上「具体请求内容」,便于在日志页查看实际发了什么。有界缓存,防无界增长。
BODY_BY_RID: dict[str, str] = {}
# ── 视频轮询历史(/logs 按 video_id 合成到「创建」那一条里,不再每个轮询各占一行) ──
VIDEO_POLLS: dict[str, "deque"] = {}
_vp_lock = threading.Lock()
_VP_MAX_VIDEOS = 200 # 同时追踪的视频任务数
_VP_MAX_POLLS = 500 # 单个任务最多保留多少条轮询
def video_poll_push(video_id: str, snap: dict) -> None:
"""记录一次视频轮询快照(内存态、有界)。"""
if not video_id:
return
with _vp_lock:
dq = VIDEO_POLLS.get(video_id)
if dq is None:
if len(VIDEO_POLLS) >= _VP_MAX_VIDEOS:
# 超上限:踢掉最老的视频任务
oldest = next(iter(VIDEO_POLLS))
VIDEO_POLLS.pop(oldest, None)
dq = deque(maxlen=_VP_MAX_POLLS)
VIDEO_POLLS[video_id] = dq
dq.append(snap)
def video_polls(video_id: str) -> list[dict]:
with _vp_lock:
return list(VIDEO_POLLS.get(video_id) or [])
_BODY_MAX = 2000
# ── 用量指标 ──────────────────────────────────────────
class Metrics:
"""按 模型/供应商/路由 维度统计调用次数、fallback、token、耗时。"""
def __init__(self, enabled: bool = True, started_at: float | None = None):
self.enabled = enabled
self._lock = threading.Lock()
self.calls: dict[str, dict[str, int]] = {} # model -> {ok, fail}
self.providers: dict[str, dict[str, int]] = {} # provider -> {ok, fail}
self.routes: dict[str, dict[str, int]] = {} # route -> {ok, fallback}
self.fallback_total: int = 0
self.tokens_prompt: int = 0
self.tokens_completion: int = 0
self.latency_samples: dict[str, deque[float]] = {} # model -> 最近 N 次耗时
# 功能 11: 在途请求计数
self.in_flight: int = 0
self.in_flight_peak: int = 0
# M5+: 按账号维度的聚合(普通账号只看到自己的调用;admin 看全局)。
# 结构:account -> {"calls","providers","routes","tokens","latency","fallback"}
self.by_account: dict[str, dict[str, Any]] = {}
# Bug 4: 热重载时保留 started_at,uptime 不因重载清零
self.started_at: float = started_at if started_at is not None else time.time()
def _acc(self, account: str) -> dict[str, Any]:
"""懒建某一账号的聚合桶(须已持 self._lock)。"""
acc = self.by_account.get(account)
if acc is None:
acc = {
"calls": {}, "providers": {}, "routes": {},
"tokens": {"prompt": 0, "completion": 0},
"latency": {}, "fallback": 0,
}
self.by_account[account] = acc
return acc
def increment_inflight(self) -> None:
"""功能 11:请求进入 +1。"""
with self._lock:
self.in_flight += 1
if self.in_flight > self.in_flight_peak:
self.in_flight_peak = self.in_flight
def decrement_inflight(self) -> None:
"""功能 11:请求结束 -1。"""
with self._lock:
self.in_flight = max(0, self.in_flight - 1)
def in_flight_snapshot(self) -> int:
with self._lock:
return self.in_flight
@staticmethod
def _bucket(d: dict, k: str) -> dict[str, int]:
return d.setdefault(k, {"ok": 0, "fail": 0})
def record_call(self, model: str, provider: str | None, ok: bool, route: str | None = None,
account: str | None = None) -> None:
"""记录一次调用结果。
route 维度(Bug 8 修复):传入 route 时同时累加 routes 的 ok/fail。
account(M5+):未显式传入时取请求级 ACCOUNT 上下文;非 anonymous 时额外累加
到该账号自己的聚合桶,供「只看本人的指标」使用。
"""
if not self.enabled:
return
a = account or ACCOUNT.get()
with self._lock:
self._bucket(self.calls, model)["ok" if ok else "fail"] += 1
if provider:
self._bucket(self.providers, provider)["ok" if ok else "fail"] += 1
if route:
self._bucket(self.routes, route)["ok" if ok else "fail"] += 1
if a and a != "anonymous":
acc = self._acc(a)
self._bucket(acc["calls"], model)["ok" if ok else "fail"] += 1
if provider:
self._bucket(acc["providers"], provider)["ok" if ok else "fail"] += 1
if route:
self._bucket(acc["routes"], route)["ok" if ok else "fail"] += 1
def record_fallback(self, route: str | None, account: str | None = None) -> None:
if not self.enabled:
return
a = account or ACCOUNT.get()
with self._lock:
self.fallback_total += 1
if route:
self._bucket(self.routes, route).setdefault("fallback", 0)
self.routes[route]["fallback"] += 1
if a and a != "anonymous":
acc = self._acc(a)
acc["fallback"] += 1
if route:
b = self._bucket(acc["routes"], route)
b["fallback"] = b.get("fallback", 0) + 1
def record_tokens(self, prompt: int, completion: int, account: str | None = None) -> None:
if not self.enabled:
return
a = account or ACCOUNT.get()
with self._lock:
self.tokens_prompt += prompt
self.tokens_completion += completion
if a and a != "anonymous":
acc = self._acc(a)
acc["tokens"]["prompt"] += prompt
acc["tokens"]["completion"] += completion
def record_latency(self, model: str, seconds: float, account: str | None = None) -> None:
if not self.enabled:
return
a = account or ACCOUNT.get()
with self._lock:
dq = self.latency_samples.setdefault(model, deque(maxlen=200))
dq.append(seconds)
if a and a != "anonymous":
acc = self._acc(a)
adq = acc["latency"].setdefault(model, deque(maxlen=200))
adq.append(seconds)
def recent_avg_latency(self, model: str, k: int = 12) -> float | None:
"""最近 k 次调用的平均耗时(秒),用于「按速度排序」路由(第十一轮 #4)。
没有样本返回 None(冷启动时上层会退回配置里的优先级顺序)。
"""
if not self.enabled:
return None
with self._lock:
dq = self.latency_samples.get(model)
if not dq:
return None
vals = list(dq)[-k:]
return (sum(vals) / len(vals)) if vals else None
def snapshot(self, account: str | None = None) -> dict[str, Any]:
"""聚合快照。account=None 返回全局(admin / 未鉴权详情用);
account 非空则只返回该账号自己的聚合(不含全局 circuits —— 熔断是供应商级基础设施,admin 才见)。
"""
if account and account != "anonymous":
with self._lock:
acc = self.by_account.get(account)
if not acc:
return dict(uptime_seconds=round(time.time() - self.started_at, 1),
in_flight=self.in_flight, in_flight_peak=self.in_flight_peak,
calls={}, providers={}, routes={}, fallback_total=0,
tokens={"prompt": 0, "completion": 0}, latency={})
lat = {}
for m, dq in acc["latency"].items():
if dq:
lat[m] = _latency_summary(dq)
return {
"uptime_seconds": round(time.time() - self.started_at, 1),
"in_flight": self.in_flight,
"in_flight_peak": self.in_flight_peak,
"calls": {k: dict(v) for k, v in acc["calls"].items()},
"providers": {k: dict(v) for k, v in acc["providers"].items()},
"routes": {k: dict(v) for k, v in acc["routes"].items()},
"fallback_total": acc["fallback"],
"tokens": dict(acc["tokens"]),
"latency": lat,
}
return self._snapshot_global()
def _snapshot_global(self) -> dict[str, Any]:
# Bug 7 修复: 整个快照在锁内构造,避免并发写 dict 时迭代抛
# RuntimeError: dictionary changed size during iteration
with self._lock:
latency_out: dict[str, dict[str, float]] = {}
for m, dq in self.latency_samples.items():
if dq:
latency_out[m] = _latency_summary(dq)
return {
"uptime_seconds": round(time.time() - self.started_at, 1),
"in_flight": self.in_flight,
"in_flight_peak": self.in_flight_peak,
"calls": {k: dict(v) for k, v in self.calls.items()},
"providers": {k: dict(v) for k, v in self.providers.items()},
"routes": {k: dict(v) for k, v in self.routes.items()},
"fallback_total": self.fallback_total,
"tokens": {"prompt": self.tokens_prompt, "completion": self.tokens_completion},
"latency": latency_out,
}
def _latency_summary(dq: deque) -> dict[str, float]:
"""把某模型/账号的耗时样本汇总成 avg/p50/p95(nearest-rank)。"""
s = sorted(dq)
n = len(s)
p50 = s[min(n - 1, math.ceil(0.50 * n) - 1)]
p95 = s[min(n - 1, math.ceil(0.95 * n) - 1)]
return {"avg": round(sum(s) / n, 3), "p50": p50, "p95": p95, "count": n}
# ── 访问日志 ──────────────────────────────────────────
class AccessLog:
"""最近 N 条请求的环形日志,可经 /logs 查看。"""
def __init__(self, maxlen: int = 500):
self._max = maxlen
self._buf: deque[dict[str, Any]] = deque(maxlen=maxlen)
self._lock = threading.Lock()
def add(self, entry: dict[str, Any]) -> None:
entry["ts"] = round(time.time(), 3)
# M5+: 自动补充「归属账号」(普通账号只看到自己的日志,admin 看全部)。
entry.setdefault("account", ACCOUNT.get())
# M4: 附加请求体摘要(若有)。与 main.py 中间件按 rid 暂存的内容对应。
rid = entry.get("rid")
if rid:
snip = BODY_BY_RID.pop(rid, None)
if snip:
entry["body"] = snip
with self._lock:
self._buf.append(entry)
def tail(self, n: int = 100) -> list[dict[str, Any]]:
with self._lock:
items = list(self._buf)
return items[-n:] if n < len(items) else items
def resize(self, maxlen: int) -> None:
"""调整环形缓冲上限(热重载用),保留已有历史条目。"""
with self._lock:
if maxlen == self._max or maxlen <= 0:
return
self._max = maxlen
self._buf = deque(self._buf, maxlen=maxlen)
# ── 简单限流(per-key 令牌桶,带 LRU 桶清理) ──────────
class RateLimiter:
"""按 key 限流(QPS)。rps=None/<=0 表示不限。
Bug 2:桶数带上限(max_buckets),超出时按最后访问顺序 LRU 淘汰,
避免长时间运行 + 多 key 导致 dict 无界增长。
"""
def __init__(self, max_buckets: int = 10000):
self._max_buckets = max_buckets
self._buckets: dict[str, list[float, float]] = {}
self._lock = threading.Lock()
def _evict_if_needed(self) -> None:
"""调用方需已持锁。超出上限时,按桶的 last-access(ts)淘汰最旧的一半。"""
if len(self._buckets) <= self._max_buckets:
return
entries = sorted(self._buckets.items(), key=lambda kv: kv[1][1]) # 按 ts 升序
for k in [kk for kk, _ in entries[: len(entries) // 2]]:
self._buckets.pop(k, None)
def allow(self, key: str | None, rps: float | None) -> bool:
if not rps or rps <= 0:
return True
if not key:
return True
now = time.monotonic()
with self._lock:
cap = rps * 2 # 桶容量
entry = self._buckets.get(key)
if entry is None:
self._evict_if_needed()
# Bug 6: 首次请求也消耗一个 token(此前存满桶直接放行,等效放宽 cap+1 突发)
self._buckets[key] = [max(0.0, cap - 1.0), now]
return True
tokens, ts = entry
tokens = min(cap, tokens + (now - ts) * rps)
entry[1] = now # 更新 last-access
if tokens >= 1.0:
entry[0] = tokens - 1.0
return True
entry[0] = tokens
return False
def size(self) -> int:
with self._lock:
return len(self._buckets)
+208
View File
@@ -0,0 +1,208 @@
"""请求 / 响应数据模型。"""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, ConfigDict, Field
# 不允许被客户端 `extra` / 未知字段覆盖的"核心键"。
# 这些键承载网关已解析的路由结果与协议语义,一旦让 extra 覆盖就会出现:
# - `extra={"model": "..."}` → 劫持路由,用网关的供应商 Key 调任意(更贵/未登记)模型;
# - `extra={"stream": ...}` → 与网关自身的解析结果矛盾,非流式客户端收到 SSE(502)或反之;
# - `extra={"messages": [...]}` → 绕过入参校验。
# 第六轮安全审计实测确认了上述越权路径,故在**组装时**统一剔除。
PROTECTED_PAYLOAD_KEYS: frozenset[str] = frozenset({
"model", "messages", "stream", "tools", "tool_choice",
"temperature", "top_p", "max_tokens", "stop", "n",
"presence_penalty", "frequency_penalty", "seed", "user",
"response_format", "logprobs", "top_logprobs",
"parallel_tool_calls", "stream_options",
"prompt", "input", "image", "images", "seconds", "mode",
"aspect_ratio", "size", "extra", "extra_body",
})
# 视频路径的保护集**刻意更窄**:first_frame / last_frame / images / audios / seed
# 是模式专用参数,必须允许透传;只挡住会改变"调哪个模型/多长/什么模式"的键。
PROTECTED_VIDEO_KEYS: frozenset[str] = frozenset({
"model", "prompt", "seconds", "mode", "size", "aspect_ratio", "n", "extra", "extra_body",
})
# 图像路径同理:只挡"会改变调哪个模型/什么尺寸/几张/输入图"的键。
# 注意**不能**沿用 PROTECTED_PAYLOAD_KEYS —— 那会把 response_format / user 一起删掉。
PROTECTED_IMAGE_KEYS: frozenset[str] = frozenset({
"model", "prompt", "size", "n", "image", "images", "extra", "extra_body",
})
# 适配器 `_build_payload` **自己写进去**的键(chat)。
# 只有这些才需要防覆盖 —— 其余键(n / seed / user / response_format /
# presence_penalty / logprobs …)恰恰是 ChatRequest._PASSTHROUGH 特意塞进 extra
# 要透传给上游的,第七轮回归审计实测:若用宽集合过滤,这些参数会被**静默丢弃**
# (等于废掉 _PASSTHROUGH 机制),属本轮引入的兼容性倒退。
CHAT_CORE_KEYS: frozenset[str] = frozenset({
"model", "messages", "stream", "tools", "tool_choice",
"temperature", "top_p", "max_tokens", "stop",
})
def strip_protected(extra: dict[str, Any] | None,
keys: frozenset[str] = PROTECTED_PAYLOAD_KEYS) -> dict[str, Any]:
"""剔除受保护的核心键,其余原样透传(适配器侧的最后一道防线)。"""
return {k: v for k, v in (extra or {}).items() if k not in keys}
class Message(BaseModel):
# 兼容性修复(第六轮): 此前只有 role/content,导致 function calling 的多轮对话
# **直接坏掉** —— assistant 消息上的 tool_calls、tool 消息上的 tool_call_id 被静默丢弃,
# 上游收到的是 `{"role":"assistant","content":null}` 这种缺胳膊少腿的历史。
# 现在显式声明这几个字段,并用 extra="allow" 兜住其余规范字段(refusal / audio 等)。
model_config = ConfigDict(extra="allow")
role: str
content: Any = None # string / array(多模态)/ null(带 tool_calls 的 assistant 消息)
name: str | None = None
tool_calls: list[dict[str, Any]] | None = None
tool_call_id: str | None = None
def to_upstream(self) -> dict[str, Any]:
"""转发给上游用:丢掉 None 字段,其余(含未知字段)原样带上。"""
return self.model_dump(exclude_none=True)
class ToolFunction(BaseModel):
name: str
description: str | None = None
parameters: dict[str, Any] | None = None
class ToolDef(BaseModel):
type: str = "function"
function: ToolFunction
class ChatRequest(BaseModel):
# 兼容性修复:OpenAI 官方 SDK 会带不少可选参数(n / presence_penalty / response_format …),
# 之前未声明的字段被 pydantic 静默丢弃,导致"网关号称 OpenAI 全兼容但参数悄悄丢失"。
# 现在:常用标准参数显式声明,其余未知字段用 extra="allow" 捕获后一并透传上游。
model_config = ConfigDict(extra="allow")
model: str
messages: list[Message] = Field(min_length=1) # 空 messages 上游会报错,这里先给 400
temperature: float | None = None
top_p: float | None = None
max_tokens: int | None = None
# strict: `"stream": "yes"` 这类拼错不应被宽松强转成 True(会拿到 SSE 而非 JSON)
stream: bool = Field(default=False, strict=True)
stop: str | list[str] | None = None
tools: list[ToolDef] | None = None
tool_choice: str | dict | None = None
# ── OpenAI 标准可选参数(透传上游) ──
n: int | None = None
presence_penalty: float | None = None
frequency_penalty: float | None = None
seed: int | None = None
user: str | None = None
response_format: dict[str, Any] | None = None
logprobs: bool | None = None
top_logprobs: int | None = None
parallel_tool_calls: bool | None = None
stream_options: dict[str, Any] | None = None
# 透传供应商特有参数
extra: dict[str, Any] = Field(default_factory=dict)
# 需要透传的标准参数白名单
_PASSTHROUGH = (
"n", "presence_penalty", "frequency_penalty", "seed", "user",
"response_format", "logprobs", "top_logprobs",
"parallel_tool_calls", "stream_options",
)
def upstream_extra(self) -> dict[str, Any]:
"""组装要透传给上游的额外参数。
优先级(后者覆盖前者):显式声明的标准参数 < 未知透传字段(model_extra) < `extra`。
但**核心键一律剔除**(见 PROTECTED_PAYLOAD_KEYS):`extra` 是"供应商特有参数"的
逃生舱,不是用来覆盖 model/messages/stream 的 —— 否则等同把路由与协议语义交给客户端。
"""
out: dict[str, Any] = {}
for k in self._PASSTHROUGH:
v = getattr(self, k, None)
if v is not None:
out[k] = v
merged: dict[str, Any] = {}
merged.update(self.model_extra or {})
merged.update(self.extra or {})
for k, v in merged.items():
if k in PROTECTED_PAYLOAD_KEYS:
continue
out[k] = v
return out
def unknown_fields(self) -> list[str]:
"""未被显式声明、靠 extra="allow" 兜住的字段名(用于日志提示,避免悄悄透传)。"""
return sorted(k for k in (self.model_extra or {}) if k not in PROTECTED_PAYLOAD_KEYS)
# ── 图像生成 ─────────────────────────────────────────
class ImageRequest(BaseModel):
# 第六轮: extra="allow" —— quality/style/response_format/user 等标准参数此前被
# pydantic 静默丢弃(客户端以为生效了)。现在统一收进 model_extra 再透传。
model_config = ConfigDict(extra="allow")
model: str
prompt: str
size: str | None = None
ratio: str | None = None
image: list[str] | None = None # 图生图 / 多图输入 URL 或 DataURI
n: int = 1
return_base64: bool = False
extra: dict[str, Any] = Field(default_factory=dict)
# ── 视频生成(异步任务) ─────────────────────────────
class VideoCreateRequest(BaseModel):
model: str
prompt: str
seconds: str = "5"
mode: str = "text" # text | keyframe | reference
size: str = "720P"
aspect_ratio: str = "16:9"
n: int = 1 # 第十三轮: 上游只支持 1,>1 在网关入站就回 400
seed: int | None = None
# 模式专用
first_frame: str | None = None
last_frame: str | None = None
images: list[str] | None = None
audios: list[str] | None = None
# 第十三轮: 声明出来只为**明确拒绝**(Agnes Video 2.5 Flash 不支持参考视频)。
# 此前该字段未声明 → pydantic 静默丢弃,用户以为"传了参考视频",实际被悄悄忽略。
videos: list[Any] | None = None
extra: dict[str, Any] = Field(default_factory=dict)
# ── 视频等待模式 / Webhook ───────────────────────────
class VideoCreateRequestExtended(VideoCreateRequest):
"""支持 wait=true 和 callback_url 的视频创建请求。"""
wait: bool = False
wait_timeout: int = 120 # 等待完成的最大秒数
callback_url: str | None = None # 任务完成/失败时 POST 通知
# ── Batch 调用 ────────────────────────────────────────
class BatchItem(BaseModel):
"""Batch 中单个调用项。"""
messages: list[Message]
temperature: float | None = None
top_p: float | None = None
max_tokens: int | None = None
label: str = "" # 自定义标签(结果对应)
class BatchRequest(BaseModel):
"""一次 POST 并发调多个 prompt(同模型)。"""
model: str
items: list[BatchItem]
max_concurrency: int = 8 # 最大并发数
extra: dict[str, Any] = Field(default_factory=dict)
+46
View File
@@ -0,0 +1,46 @@
"""模型路由:根据请求中的 model 字段查找对应供应商。"""
from __future__ import annotations
from app.config import GatewayConfig, ModelInfo, ProviderConfig
class ModelNotFoundError(Exception):
def __init__(self, model_id: str, known: list[str] | None = None):
self.model_id = model_id # 只存裸模型名(此前误存整句消息)
self.known = list(known or [])
msg = f"未知模型 '{model_id}'"
if self.known:
msg += f"。可用模型: {self.known}"
super().__init__(msg)
class AuthConfigError(Exception):
def __init__(self, provider_key: str, detail: str):
self.provider_key = provider_key
super().__init__(f"供应商 {provider_key} 认证配置错误: {detail}")
def resolve(
config: GatewayConfig, model_id: str
) -> tuple[str, ProviderConfig, ModelInfo]:
"""解析 model_id → (provider_key, ProviderConfig, ModelInfo)。"""
found = config.find_provider_for_model(model_id)
if found is None:
known = [m["id"] for m in config.all_models()]
raise ModelNotFoundError(model_id, known)
return found
def resolve_with_auth(
config: GatewayConfig, model_id: str
) -> tuple[str, ProviderConfig, ModelInfo, str]:
"""解析 + 校验认证 token,返回 (pkey, pconfig, minfo, token)。"""
pkey, pconfig, minfo = resolve(config, model_id)
token = pconfig.auth.resolve_token()
if not token:
raise AuthConfigError(
pkey,
f"未找到 API Key(env: {pconfig.auth.token_env or '无'},配置 token: 未设置)"
)
return pkey, pconfig, minfo, token
+99
View File
@@ -0,0 +1,99 @@
"""前端登录会话(短时、内存态)。
设计:前端用**账号 + 密码**调 POST /auth/login 换一个 short-lived 的 `sess-` token,
后续请求带这个会话 token —— 密码只在登录那一刻提交一次,前端不长期持有;
API Key 也不需要交给浏览器。会话存内存,单实例必需;
多实例如需共享会话再换 Redis(当前网关单实例,足够)。
吊销语义(第八轮审计补):账号被删除、改密或被管理员重置密码时,其名下**全部会话**
立即失效 —— 否则「删号 / 重置密码」无法止损(旧 token 仍能调用到 TTL 结束)。
"""
from __future__ import annotations
import secrets
import threading
import time
class SessionStore:
def __init__(self, ttl_seconds: int = 86400, max_tokens: int = 5000):
self._ttl = ttl_seconds
self._max = max_tokens
self._s: dict[str, dict] = {}
self._lock = threading.Lock()
def ttl(self) -> int:
return self._ttl
def set_ttl(self, seconds: int) -> None:
"""按当前配置动态调整会话时长(下限 60s,防误配成 0 让会话瞬间过期)。"""
self._ttl = max(60, int(seconds))
def count(self) -> int:
with self._lock:
self._purge()
return len(self._s)
def create(self, ip: str, account: str = "") -> str:
with self._lock:
self._purge()
if len(self._s) >= self._max: # 超上限:踢最老的
oldest = min(self._s, key=lambda k: self._s[k]["created"])
del self._s[oldest]
tok = "sess-" + secrets.token_hex(24)
# ip 只做记录、不做绑定:移动网络/NAT 下换出口 IP 是常态,绑定会把人踢下线。
self._s[tok] = {"created": time.time(), "ip": ip or "", "account": account or ""}
return tok
def validate(self, token: str, ip: str | None = None) -> bool:
if not token:
return False
with self._lock:
ent = self._s.get(token)
if not ent:
return False
if time.time() - ent["created"] > self._ttl:
del self._s[token]
return False
return True
def account_for(self, token: str) -> str | None:
"""返回会话所属账号(用于指标/日志归属与鉴权 identity)。"""
if not token or not self.validate(token):
return None
with self._lock:
ent = self._s.get(token)
return (ent or {}).get("account")
def is_session(self, token: str) -> bool:
"""该凭证是否为**密码登录换来的会话**(区别于长期 API Key)。
账号管理/改密/铸 Key 这类「改凭证」操作只认会话凭证 —— 泄漏的 API Key
就不可能再给自己铸一把新 Key 或改密码,堵住持久化后门。
"""
return bool(token and token.startswith("sess-") and self.validate(token))
def revoke(self, token: str) -> None:
with self._lock:
self._s.pop(token, None)
def revoke_account(self, account: str) -> int:
"""吊销某账号的全部会话,返回被踢掉的会话数(改密/重置密码/删号时调用)。"""
if not account:
return 0
with self._lock:
dead = [k for k, v in self._s.items() if v.get("account") == account]
for k in dead:
del self._s[k]
return len(dead)
def clear(self) -> None:
with self._lock:
self._s.clear()
def _purge(self) -> None:
now = time.time()
for k in list(self._s):
if now - self._s[k]["created"] > self._ttl:
del self._s[k]
+485
View File
@@ -0,0 +1,485 @@
"""网关配置的面板化管理(第二十三轮)。
老板要求:`data/gateway.yaml` 里的**每一项**都能在管理员账号的页面上改,**保存后实时生效**。
这个模块只干"配置文本 ↔ 面板 JSON"这一件事,不碰运行时对象:
- `config_to_view(cfg)` 运行中的配置 → 面板 JSON(密钥只回报"配没配",不回显内容)
- `view_to_raw(cfg, raw, view)` 面板提交 → 完整 yaml 字典(以**文件原文为底**,只覆盖面板管得着的键)
- `parse_and_validate(raw)` 先在内存里解析 + 校验,**通过了才写盘**(绝不出现"写坏文件 → 重启起不来")
- `render_yaml(raw)` 生成带注释的 yaml 文本(注释由本文件维护,见下方各 section 抬头)
- `write_config(path, text)` 滚动备份 + 原子替换(tmp + os.replace,热重载循环读不到半个文件)
"实时生效"由 main.py 负责:它拿到新 `GatewayConfig` 后就地更新指标/日志/熔断/限流并丢弃
adapter 缓存,与 mtime 热重载走**同一条** `_apply_config` 路径(两处逻辑不可能再跑偏)。
哪些键改了需要重启进程(启动时定死的东西)见 `RESTART_KEYS`;其余都是每请求读配置,
保存即生效。这个清单也回给前端,页面会在对应输入框旁标出来 —— 不标就是骗人。
"""
from __future__ import annotations
import copy
import os
import shutil
import time
from pathlib import Path
from typing import Any
import yaml
from app.config import (
ConfigError,
GatewayConfig,
parse_config,
validate_config,
validate_warnings,
)
# ── 改了必须重启进程才生效的键(其余都是"每请求读配置",保存即生效) ──
# host / port:uvicorn 在进程启动时绑定,改文件不会重绑。
# graceful_shutdown:run.py 启动时读一次,传给 uvicorn 的 timeout_graceful_shutdown。
# docs_enabled:FastAPI 实例在 import 期就按它决定 docs_url / openapi_url。
# hot_reload:热重载任务本身在 lifespan 里创建/取消 —— 关掉能立刻停(循环每轮检查),
# 但从「关」改成「开」不会凭空长出任务来,所以按"需重启"标注。
RESTART_KEYS = (
"server.host",
"server.port",
"server.graceful_shutdown",
"server.docs_enabled",
"server.hot_reload",
)
# 时间戳备份最多留几份(滚动 .bak 之外)
BACKUP_KEEP = 5
# 供应商 media 段的字段名(面板逐项编辑,顺序即展示顺序)
MEDIA_KEYS = (
"image_endpoint",
"image_default_size",
"video_create_endpoint",
"video_poll_base",
"video_poll_path",
"video_model_name",
)
MODEL_TYPES = ("text", "image", "video")
# ── 读取:运行中的配置 → 面板 JSON ─────────────────────────
def config_to_view(cfg: GatewayConfig) -> dict[str, Any]:
"""把运行中的配置摊平成面板能直接吃的 JSON(结构与 yaml 一一对应)。
密钥只回报 `token_set`(明文 token 是否配了),**不回显 token 本身**;
`token_env` 是环境变量名,不是秘密,照常回显。
"""
providers: dict[str, Any] = {}
for pkey, p in cfg.providers.items():
providers[pkey] = {
"name": p.name,
"base_url": p.base_url,
"auth": {
"token_env": p.auth.token_env,
# 面板里 token 输入框永远留空;placeholder 提示"留空 = 不修改"
"token_set": bool(p.auth.token),
"token_env_set": bool(p.auth.token_env and os.environ.get(p.auth.token_env)),
},
"extra_headers": dict(p.extra_headers or {}),
"rate_limit_rps": p.rate_limit_rps,
"media": {k: getattr(p.media, k) for k in MEDIA_KEYS},
"models": [
{"id": m.id, "display_name": m.display_name, "type": m.type, "vision": bool(m.vision)}
for m in p.models
],
}
s = cfg.server
return {
"providers": providers,
"server": {
"host": s.host,
"port": s.port,
"timeout": s.timeout,
"retry": s.retry,
"health_auth": s.health_auth,
"hot_reload": s.hot_reload,
"hot_reload_interval": s.hot_reload_interval,
"metrics_enabled": s.metrics_enabled,
"rate_limit_rps": s.rate_limit_rps,
"max_body_size": s.max_body_size,
"cors_origins": list(s.cors_origins or []),
"graceful_shutdown": s.graceful_shutdown,
"batch_max_concurrency": s.batch_max_concurrency,
"batch_max_items": s.batch_max_items,
"webhook_allow_private": s.webhook_allow_private,
"docs_enabled": s.docs_enabled,
"auth_fail_limit_per_min": s.auth_fail_limit_per_min,
},
"auth": {"session_ttl_minutes": cfg.auth.session_ttl_minutes},
"routes": {
rname: {
"models": list(r.models or []),
"timeout": r.timeout,
"retry": r.retry,
"rate_limit_rps": r.rate_limit_rps,
}
for rname, r in cfg.routes.items()
},
"circuit": {
"enabled": cfg.circuit.enabled,
"failure_threshold": cfg.circuit.failure_threshold,
"cooldown": cfg.circuit.cooldown,
"window": cfg.circuit.window,
},
"observability": {
"log_level": cfg.observability.log_level,
"log_json": cfg.observability.log_json,
"access_log_maxlen": cfg.observability.access_log_maxlen,
},
"pricing": {
"per_model": {
name: {"input": v.get("input", 0.0), "output": v.get("output", 0.0)}
for name, v in (cfg.pricing.per_model or {}).items()
}
},
"download": {
"allowed_hosts": list(cfg.download.allowed_hosts or []),
"max_bytes": cfg.download.max_bytes,
},
}
# ── 写入:面板 JSON → 完整 yaml 字典 ───────────────────────
def _as_dict(v: Any, field_name: str) -> dict[str, Any]:
if v is None:
return {}
if not isinstance(v, dict):
raise ConfigError(f"{field_name} 必须是对象(键值对),得到: {type(v).__name__}")
return v
def _str_list(v: Any, field_name: str) -> list[str]:
if v is None:
return []
if isinstance(v, str):
# 容错:单个值写成字符串也认(前端偶尔只传一项)
v = [v]
if not isinstance(v, list):
raise ConfigError(f"{field_name} 必须是数组,得到: {type(v).__name__}")
out: list[str] = []
for x in v:
if x is None:
continue
if not isinstance(x, str):
raise ConfigError(f"{field_name} 只能填字符串,得到: {x!r}")
out.append(x.strip())
return out
def _str_map(v: Any, field_name: str) -> dict[str, str]:
d = _as_dict(v, field_name)
out: dict[str, str] = {}
for k, val in d.items():
kk = str(k).strip()
if not kk:
continue
out[kk] = "" if val is None else str(val)
return out
def view_to_raw(cfg: GatewayConfig, raw: dict[str, Any], view: dict[str, Any]) -> dict[str, Any]:
"""面板提交 → 完整 yaml 字典。
以**文件原文为底**(`raw`),只覆盖面板管得着的键:
- 这样文件里将来多出来的自定义段/键不会因为页面保存一次就消失;
- 供应商的明文 token 面板留空时也不会被清掉(原文里的值原样留着);
- 面板没传的段(局部提交/脚本调用)保持原文不动,不会"顺手清空"。
校验不在这里做 —— 调用方拿到 raw 后交给 `parse_and_validate`,不通过就别写盘。
"""
out = copy.deepcopy(raw) if isinstance(raw, dict) else {}
# ── providers(整段以面板为准)──
if "providers" in view:
prov_in = _as_dict(view.get("providers"), "providers")
base_prov = out.get("providers") if isinstance(out.get("providers"), dict) else {}
providers: dict[str, Any] = {}
for pkey, pv in prov_in.items():
key = str(pkey).strip()
if not key:
raise ConfigError("供应商的 key 不能为空")
pv = _as_dict(pv, f"providers.{key}")
base_p = base_prov.get(key) if isinstance(base_prov.get(key), dict) else {}
auth_in = _as_dict(pv.get("auth"), f"providers.{key}.auth")
base_auth = _as_dict(base_p.get("auth"), f"providers.{key}.auth")
token = auth_in.get("token")
# 留空 = 不修改:沿用文件里已有的明文 token(面板从不回显它)
if token is None or (isinstance(token, str) and not token.strip()):
token = base_auth.get("token", "") or ""
media_in = _as_dict(pv.get("media"), f"providers.{key}.media")
base_media = _as_dict(base_p.get("media"), f"providers.{key}.media")
models = []
for i, m in enumerate(pv.get("models") or []):
m = _as_dict(m, f"providers.{key}.models[{i}]")
models.append({
"id": str(m.get("id") or "").strip(),
"display_name": str(m.get("display_name") or "").strip(),
"type": str(m.get("type") or "text").strip(),
"vision": bool(m.get("vision", False)),
})
providers[key] = {
"name": str(pv.get("name") or key).strip(),
"base_url": str(pv.get("base_url") or "").strip(),
"auth": {
"token_env": str(auth_in.get("token_env") or "").strip(),
"token": token,
},
"extra_headers": _str_map(pv.get("extra_headers"), f"providers.{key}.extra_headers"),
"rate_limit_rps": pv.get("rate_limit_rps"),
# media 留空 = 该供应商不支持对应媒体(写回时保留原文里的空 {} 语义)
"media": {
k: (media_in.get(k) if k in media_in else base_media.get(k))
for k in MEDIA_KEYS
},
"models": models,
}
out["providers"] = providers
# ── server(逐键覆盖,缺的沿用原文)──
if "server" in view:
sv = _as_dict(view.get("server"), "server")
base_s = _as_dict(out.get("server"), "server")
out["server"] = {**base_s, **{k: v for k, v in sv.items() if k in _SERVER_KEYS}}
# ── auth ──
if "auth" in view:
av = _as_dict(view.get("auth"), "auth")
base_a = _as_dict(out.get("auth"), "auth")
merged = {**base_a}
if "session_ttl_minutes" in av:
merged["session_ttl_minutes"] = av["session_ttl_minutes"]
out["auth"] = merged
# ── routes(整段以面板为准:删掉的路由别名就是删掉)──
if "routes" in view:
rv = _as_dict(view.get("routes"), "routes")
routes: dict[str, Any] = {}
for rname, rv1 in rv.items():
name = str(rname).strip()
if not name:
raise ConfigError("路由别名的名字不能为空")
rv1 = _as_dict(rv1, f"routes.{name}")
routes[name] = {
"models": _str_list(rv1.get("models"), f"routes.{name}.models"),
"timeout": rv1.get("timeout"),
"retry": rv1.get("retry"),
"rate_limit_rps": rv1.get("rate_limit_rps"),
}
out["routes"] = routes
# ── circuit / observability ──
for sec, keys in (("circuit", _CIRCUIT_KEYS), ("observability", _OBS_KEYS)):
if sec in view:
vv = _as_dict(view.get(sec), sec)
out[sec] = {k: vv[k] for k in keys if k in vv} or _as_dict(out.get(sec), sec)
# ── pricing.per_model(整表以面板为准)──
if "pricing" in view:
pv = _as_dict(view.get("pricing"), "pricing")
per_model: dict[str, Any] = {}
for model, price in _as_dict(pv.get("per_model"), "pricing.per_model").items():
name = str(model).strip()
if not name:
continue
price = _as_dict(price, f"pricing.per_model.{name}")
per_model[name] = {"input": price.get("input"), "output": price.get("output")}
out["pricing"] = {"per_model": per_model}
# ── download ──
if "download" in view:
dv = _as_dict(view.get("download"), "download")
base_d = _as_dict(out.get("download"), "download")
merged_d = {**base_d}
if "allowed_hosts" in dv:
merged_d["allowed_hosts"] = _str_list(dv.get("allowed_hosts"), "download.allowed_hosts")
if "max_bytes" in dv:
merged_d["max_bytes"] = dv["max_bytes"]
out["download"] = merged_d
return out
_SERVER_KEYS = (
"host", "port", "timeout", "retry", "health_auth", "hot_reload", "hot_reload_interval",
"metrics_enabled", "rate_limit_rps", "max_body_size", "cors_origins", "graceful_shutdown",
"batch_max_concurrency", "batch_max_items", "webhook_allow_private", "docs_enabled",
"auth_fail_limit_per_min",
)
_CIRCUIT_KEYS = ("enabled", "failure_threshold", "cooldown", "window")
_OBS_KEYS = ("log_level", "log_json", "access_log_maxlen")
def parse_and_validate(raw: dict[str, Any]) -> tuple[GatewayConfig, list[str]]:
"""解析 + 结构校验 + 收集告警。返回 (配置, 告警列表)。
校验不通过抛 `ConfigError`(调用方据此 400,**不写盘**)。
告警不阻塞保存(比如 cors 还是通配),但会原样回给页面提示。
"""
cfg = parse_config(raw) # 类型/必填/下限都在这里把关
issues = validate_config(cfg)
if issues:
raise ConfigError("配置校验失败:\n - " + "\n - ".join(issues))
return cfg, validate_warnings(cfg)
def restart_keys_changed(old: GatewayConfig, new: GatewayConfig) -> list[str]:
"""哪些"需重启"的键这次真的变了(页面据此提示,不变就不吓人)。"""
changed: list[str] = []
for key in RESTART_KEYS:
_, field = key.split(".", 1)
if getattr(old.server, field) != getattr(new.server, field):
changed.append(key)
return changed
# ── 渲染 yaml 文本 ────────────────────────────────────────
_HEADER = """\
# AI 网关配置文件(data/ 目录)
#
# ⚠ 本文件由管理页面「网关配置」生成(管理员账号),页面保存时会**整份重写**:
# 想要的历史决策/踩坑说明在 README.md(按轮次记录),这里只保留必要的现场注释。
# 手改本文件仍然有效(server.hot_reload=true 时按 mtime 自动重载),
# 但页面下次保存会以页面上的值为准 —— 改配置优先用页面。
#
# 端口默认 8808;密钥统一走 auth.token_env 指向的环境变量(本机见 .env),不在 yaml 存明文。
# 本文件是项目的唯一配置文件(run.py 默认读取;GATEWAY_CONFIG 可覆盖)。
"""
_SECTION_COMMENTS = {
"providers": """\
# ── 供应商 + 模型清单 ───────────────────────────────────
# auth.token_env 指向存放密钥的环境变量;auth.token 只有在不用环境变量时才填(明文)。
# media 段留空 = 该供应商不支持图像/视频(Agnes 是自有非标准端点,故单独覆盖)。
# models.type: text | image | video;vision: 该模型是否支持图像输入(带图对话会被优先排到链首)。
""",
"server": """\
# ── 服务与运维开关 ──────────────────────────────────────
# host/port/graceful_shutdown/docs_enabled/hot_reload 这几项**改完要重启进程**才生效,
# 其余每请求读取,页面保存即生效。
# 安全相关:health_auth(/health/* 是否鉴权)、webhook_allow_private(视频回调是否允许内网地址)、
# docs_enabled(FastAPI 文档,默认关)、auth_fail_limit_per_min(同源 IP 每分钟鉴权失败上限)。
# cors_origins 写 ["*"] 表示任意站点都能跨域驱动本网关(会把上游额度暴露给陌生网页),
# 生产建议收敛成可信前端域名白名单。
""",
"auth": """\
# ── 网关入口鉴权 ────────────────────────────────────────
# 账号与 API Key 由页面管理,存在 data/users.json(见 app/users.py):
# 管理员在「用户管理」建账号,各账号在「设置 → 我的 API Key」自助铸 Key。
# 本文件里没有任何用户/密钥,只有会话时长这一个开关。
""",
"routes": """\
# ── 路由别名 + 按优先级 fallback ────────────────────────
# model 填别名(如 wjd)时按 models 数组顺序逐个尝试:第 1 个失败/超时/重试耗尽 → 第 2 个 …
# 全失败才 502。timeout = 单模型超时秒(null 用 server.timeout),retry = 切下一个前该模型重试次数。
# 数组顺序即优先级(第 0 个最高)。可用模型 = 上面 providers 里定义的全部模型 id。
""",
"circuit": """\
# ── 供应商熔断 ──────────────────────────────────────────
# 某供应商在 window 秒内失败达到 failure_threshold 次就熔断 cooldown 秒,
# 期间直接跳过它(不再白等),让 fallback 快速切到健康供应商。
""",
"observability": """\
# ── 可观测性 ────────────────────────────────────────────
# log_level 支持 DEBUG/INFO/WARNING/ERROR;log_json=true 输出结构化 JSON 行(接 ELK)。
# access_log_maxlen = 访问日志环形缓冲长度(日志页「已加载 N 条」的上限)。
""",
"pricing": """\
# ── 定价(人民币 / 百万 token,用于 /v1 响应里估算成本) ─
# 不配则该模型不返回 estimated_cost_cny(不影响调用)。
""",
"download": """\
# ── 媒体下载代理白名单 ──────────────────────────────────
# 生成的图片/视频挂在第三方 CDN 上且不带 CORS 头,浏览器 fetch 不到 blob、跨域 <a download>
# 也不生效 —— 所以由网关代拉一次并加 Content-Disposition: attachment。
# 安全:这是全网关唯一一个服务端主动出网的接口,只有这里列出的域名(含子域)允许被代下载,
# 且解析出的 IP 必须是公网地址;allowed_hosts 为空 = 该功能整体关闭。
# 换了供应商/CDN 域名时,往这里加一条即可(如 volc 的 tos-*.volces.com)。
""",
}
_SECTION_ORDER = ("providers", "server", "circuit", "observability", "pricing", "download", "auth", "routes")
def _dump(obj: Any) -> str:
"""稳定的 block 风格 dump(不排序键,保留插入顺序 = 面板里的顺序)。"""
return yaml.safe_dump(
obj,
allow_unicode=True,
sort_keys=False,
default_flow_style=False,
width=1000, # 别把长 base_url 折行(折了也能读,但难看)
indent=2,
)
def render_yaml(raw: dict[str, Any]) -> str:
"""生成带注释的 yaml 文本(注释见 _SECTION_COMMENTS,改注释改这里)。"""
parts: list[str] = [_HEADER]
known = set(_SECTION_ORDER)
for sec in _SECTION_ORDER:
if sec not in raw:
continue
parts.append(_SECTION_COMMENTS.get(sec, ""))
parts.append(_dump({sec: raw[sec]}))
# 文件里多出来的、面板不管的段(人工加的)原样保留在末尾,不静默丢掉
extra = {k: v for k, v in raw.items() if k not in known}
if extra:
parts.append("# ── 以下是面板不管理的自定义配置(原样保留)──\n")
parts.append(_dump(extra))
text = "".join(p for p in parts if p)
return text if text.endswith("\n") else text + "\n"
# ── 写盘(备份 + 原子替换)────────────────────────────────
def _prune_backups(path: Path) -> None:
"""只留最近 BACKUP_KEEP 份时间戳备份(滚动 .bak 不动)。"""
pat = f"{path.name}.*.bak"
cands = sorted(path.parent.glob(pat))
for old in cands[:-BACKUP_KEEP] if len(cands) > BACKUP_KEEP else []:
try:
old.unlink()
except OSError:
pass
def write_config(path: str | Path, text: str) -> dict[str, Any]:
"""把配置文本写盘:先备份原文,再 tmp + os.replace 原子替换。
原子替换是必须的:`server.hot_reload` 的循环按 mtime 触发重载,
直接覆盖写会让它有机会读到半份文件 → 重载失败(旧配置继续跑,但白报一次错)。
权限 600:配置里可能被填了明文 token(正常应走 token_env),别让它可读给同机其它用户。
"""
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
bak_path = path.with_name(path.name + ".bak")
stamp_path = path.with_name(f"{path.name}.{time.strftime('%Y%m%d-%H%M%S')}.bak")
if path.exists():
shutil.copy2(path, bak_path)
shutil.copy2(path, stamp_path)
_prune_backups(path)
tmp = path.with_name(path.name + ".tmp")
tmp.write_text(text, encoding="utf-8")
os.chmod(tmp, 0o600)
os.replace(tmp, path)
return {"path": str(path), "backup": str(bak_path) if bak_path.exists() else "", "bytes": len(text.encode("utf-8"))}
def read_raw(path: str | Path) -> dict[str, Any]:
"""读文件原文(缺失/空文件 → {}),供 view_to_raw 当"底"。"""
path = Path(path)
if not path.exists():
return {}
with open(path, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
return data if isinstance(data, dict) else {}
+362
View File
@@ -0,0 +1,362 @@
"""页面配置的账号体系(替代原先写死在 data/gateway.yaml / .env 的鉴权)。
- 用户持久化在 data/users.json(自动创建,权限 600,不进 git):密码只存 PBKDF2 哈希;
API Key 存哈希用于鉴权 + **额外存一份明文**,为的是页面随时能再复制(详见 keys() 的取舍说明)。
- 初始管理员 admin/admin,唯一管理员;admin 可建账号(账号名仅字母数字,默认密码=账号名)。
- 普通账号只能管自己的 API Key(**每人最多 3 把**);admin 看全部指标/日志,且**建 Key 不限数量**。
- 凭证分两类:**会话**(sess-,密码登录换来、短时、可被吊销)与 **API Key**(wjd-,长期、
只能调模型)。改密码 / 铸 Key / 管账号这类「动凭证」的操作只认会话凭证。
- 吊销:删账号、改密、管理员重置密码 → 该账号全部会话立即失效。
- 停用 / 启用(第二十四轮,老板要求):账号记录里的 `disabled` 字段。停用后 ①密码正确也不给
会话;②名下 API Key 一律失效(`resolve_key` 直接跳过,但**不删除** —— 重新启用即恢复);
③停用瞬间由调用方吊销其全部网页会话。admin 账号永不可停用(唯一管理员被停用后没人能进
管理页,只能改盘上 JSON 救回)。
- 纯标准库(hashlib.pbkdf2 + hmac),无第三方依赖。
如需改密码哈希强度或迭代次数,改 ITERATIONS 即可(已存的 salt 仍可校验)。
"""
from __future__ import annotations
import hashlib
import hmac
import json
import logging
import os
import re
import secrets
import threading
import time
log = logging.getLogger("api-gateway.users")
USERNAME_RE = re.compile(r"^[A-Za-z0-9]+$")
ITERATIONS = 200_000
KEY_PREFIX = "wjd-" # 新建 API Key 的统一前缀(与对外品牌一致)
# 迁移期仍承认旧前缀,免得已发出去的长期 Key 被无声作废;想一刀切就改成 ()
LEGACY_KEY_PREFIXES: tuple[str, ...] = ("ak-",)
_KEY_PREFIXES: tuple[str, ...] = (KEY_PREFIX,) + LEGACY_KEY_PREFIXES
KEY_BYTES = 28 # token_urlsafe(28) ≈ 38 chars → 整把 key 42 字符
MIN_PASSWORD = 4 # 显式设置/修改的密码下限(默认密码=账号名不受此限,按老板约定)
MAX_KEYS_PER_MEMBER = 3 # 普通账号每人最多 3 把 API Key(防失控膨胀 / 泄漏后无限铸 Key)
def key_limit_for_role(role: str) -> int | None:
"""该角色的 API Key 数量上限。None = 不限(admin 按需发长期凭证)。"""
return None if role == "admin" else MAX_KEYS_PER_MEMBER
# 账号不存在时也走一次 PBKDF2:否则「不存在的账号」明显更快返回,
# 成了用户名枚举的时序侧信道(第八轮审计)。
_DUMMY_SALT = secrets.token_hex(16)
class UserError(Exception):
"""业务校验失败(映射为 400/409)。"""
def _hash_pw(password: str, salt_hex: str | None = None):
salt = salt_hex or secrets.token_hex(16)
dig = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"),
bytes.fromhex(salt), ITERATIONS).hex()
return salt, dig
def _hash_key(key: str) -> str:
return hashlib.sha256(key.encode("utf-8")).hexdigest()
class UsersStore:
def __init__(self, path: str):
self._path = path
self._lock = threading.Lock()
self._data: dict = {}
self._load()
self.ensure_admin()
# ── 持久化 ─────────────────────────────
def _load(self) -> None:
try:
with open(self._path, encoding="utf-8") as f:
self._data = json.load(f)
except FileNotFoundError:
self._data = {"users": {}}
except Exception:
self._data = {"users": {}}
self._data.setdefault("users", {})
def _save(self) -> None:
d = os.path.dirname(self._path)
if d and not os.path.isdir(d):
os.makedirs(d, exist_ok=True)
tmp = self._path + ".tmp"
with open(tmp, "w", encoding="utf-8") as f:
json.dump(self._data, f, ensure_ascii=False, indent=2)
# 文件里是密码哈希 + API Key 哈希,属凭证材料 → 仅属主可读写(第八轮审计补)。
os.chmod(tmp, 0o600)
os.replace(tmp, self._path)
# ── 初始管理员 ─────────────────────────
def ensure_admin(self) -> None:
"""首次运行自动创建 admin/admin(唯一管理员,登录后应立刻改密)。已存在则跳过。"""
with self._lock:
if "admin" in self._data["users"]:
self._keep_admin_usable()
return
salt, dig = _hash_pw("admin")
self._data["users"]["admin"] = {
"password_salt": salt, "password_hash": dig, "role": "admin",
"created": round(time.time(), 1),
"api_keys": {},
}
self._save()
def _keep_admin_usable(self) -> None:
"""兜底:admin 被人手工改盘上 JSON 标成 disabled 时自动恢复(调用方需已持锁)。
接口层已经拒绝停用 admin(set_disabled 抛 UserError),这条只防「手工编辑 users.json」——
唯一管理员被停用意味着谁也进不了管理页,只能停机改文件,代价太大。
"""
u = self._data["users"].get("admin") or {}
if u.get("disabled"):
u["disabled"] = False
u.pop("disabled_at", None)
self._data["users"]["admin"] = u
self._save()
log.warning("检测到 admin 被标记为停用,已自动恢复启用(管理员账号不允许停用)")
# ── 账号查询 ───────────────────────────
def find(self, name: str) -> dict | None:
with self._lock:
return self._data["users"].get(name)
def is_admin(self, name: str) -> bool:
u = self.find(name)
return bool(u and u.get("role") == "admin")
def role(self, name: str) -> str:
u = self.find(name)
return (u or {}).get("role", "member")
def list_users(self) -> list[dict]:
"""不含密码/Key 明文,仅管理视图(含停用状态,页面据此显示「已停用」并切换按钮)。"""
with self._lock:
users = self._data["users"]
return [{
"name": n,
"role": u.get("role", "member"),
"created": u.get("created"),
"api_key_count": len(u.get("api_keys") or {}),
"disabled": bool(u.get("disabled")),
"disabled_at": u.get("disabled_at"),
} for n, u in sorted(users.items())]
def is_disabled(self, name: str) -> bool:
"""账号是否已停用(账号不存在按未停用处理:不存在自会撞上别的判断)。"""
u = self.find(name)
return bool(u and u.get("disabled"))
def set_disabled(self, name: str, disabled: bool = True, by: str | None = None) -> bool:
"""停用 / 启用账号。返回账号是否存在(不存在 → False,由上层回 404)。
幂等:重复设置同一状态也算成功(页面连点两下不会报错)。
两条拒绝规则都放在这里(规则只有一处,接口层不用再判一遍):
- admin 永不可停用 —— 唯一管理员被停用后没人能进管理页,只能改盘上 JSON 救回;
- 不能停用自己(by=操作者)—— 手滑点自己那行的按钮就把自己锁在外面,没必要。
"""
if disabled and name == "admin":
raise UserError("不能停用管理员账号 admin")
if disabled and by and by == name:
raise UserError("不能停用当前登录的账号")
with self._lock:
u = self._data["users"].get(name)
if u is None:
return False
if bool(u.get("disabled")) != bool(disabled):
u["disabled"] = bool(disabled)
if disabled:
u["disabled_at"] = round(time.time(), 1) # 页面 tooltip 用(「什么时候停的」)
else:
u.pop("disabled_at", None)
self._save()
return True
# ── 创建 / 删除账号 ────────────────────
def create_user(self, name: str, password: str | None = None, role: str = "member") -> str:
if not name or not USERNAME_RE.match(name):
raise UserError("账号名只能由字母和数字组成")
if len(name) < 2 or len(name) > 32:
raise UserError("账号名长度需在 2~32 之间")
if password is not None:
# 显式传密码才校验强度;不传则按约定用账号名作默认密码
if len(str(password)) < MIN_PASSWORD:
raise UserError(f"密码至少 {MIN_PASSWORD} 位")
password = str(password)
with self._lock:
if name in self._data["users"]:
raise UserError(f"账号 {name} 已存在")
pw = password if password is not None else name # 默认密码=账号名
salt, dig = _hash_pw(pw)
self._data["users"][name] = {
"password_salt": salt, "password_hash": dig,
"role": role, "created": round(time.time(), 1),
"api_keys": {},
}
self._save()
return name
def delete_user(self, name: str) -> bool:
"""删除账号。返回是否真的删掉了(不存在 → False,供上层回 404)。
第八轮审计: 原先返回 `bytes | None` 且不存在与已删除都返回 None,
调用方无从区分,前端「删除一个不存在的账号」也报成功。
"""
with self._lock:
users = self._data["users"]
if name not in users:
return False
if name == "admin":
raise UserError("不能删除管理员账号 admin")
del users[name]
self._save()
return True
# ── 密码 ───────────────────────────────
def verify(self, name: str, password: str) -> bool:
u = self.find(name)
if not password:
# 空密码不做校验,但补一次哑哈希,保持与「账号不存在」同样的耗时
_hash_pw("", _DUMMY_SALT)
return False
if not u:
_hash_pw(password, _DUMMY_SALT) # 时序对齐:防用户名枚举
return False
salt, dig = u.get("password_salt", ""), u.get("password_hash", "")
if not salt or not dig:
return False
_, calc = _hash_pw(password, salt)
return hmac.compare_digest(dig, calc)
def change_password(self, name: str, new_password: str) -> None:
if not new_password or len(new_password) < MIN_PASSWORD:
raise UserError(f"新密码至少 {MIN_PASSWORD} 位")
with self._lock:
users = self._data["users"]
if name not in users:
raise UserError("账号不存在")
salt, dig = _hash_pw(new_password)
users[name]["password_salt"] = salt
users[name]["password_hash"] = dig
self._save()
# ── API Key(各账号自建,默认无;member 最多 3 把,admin 不限) ──
def add_api_key(self, name: str, label: str = "") -> str:
key = KEY_PREFIX + secrets.token_urlsafe(KEY_BYTES)
kh = _hash_key(key)
with self._lock:
users = self._data["users"]
u = users.get(name)
if u is None:
raise UserError("账号不存在")
keys = u.setdefault("api_keys", {})
# 第八轮审计: 不设上限时,一个泄漏的凭证可以无限铸 Key 把 users.json 撑爆。
# 现在按角色区分:普通账号 3 把封顶,admin 不限(要能按需发长期凭证)。
# 角色与计数都在**同一次持锁**里读,避免"检查时是 member、写入前变了"的错位。
limit = key_limit_for_role(u.get("role", "member"))
if limit is not None and len(keys) >= limit:
# 第十六轮(老板要求):这条提示只留「已达上限」四个字 —— 上限是几把、要不要删,
# 页面上(按钮 tooltip / 顶部告警)已经写着了,接口里再铺一段话只会让 toast 变啰嗦。
raise UserError("已达上限")
keys[kh] = {"label": label or "", "created": round(time.time(), 1),
"key": key} # 明文一并存:老板要能在页面上反复复制(见下方取舍说明)
self._save()
return key # 创建响应里也给一次明文
def clear_api_keys(self, name: str) -> int:
"""一次性吊销该账号的全部 API Key,返回删掉的把数。
第八轮审计: 改密/重置密码只能踢会话,救不了**泄漏的长期 Key**(Key 与密码无关)。
所以给管理员一个一键止血手段;本人也随时可在设置页逐把删除。
"""
with self._lock:
u = self._data["users"].get(name)
if u is None:
raise UserError("账号不存在")
keys = u.get("api_keys") or {}
n = len(keys)
u["api_keys"] = {}
if n:
self._save()
return n
def remove_api_key(self, name: str, key_or_hint: str) -> bool:
# 传入完整明文 Key → 直接哈希匹配;传入 8 位 hint(id)→ 按前缀匹配存储的 key 哈希。
kh = _hash_key(key_or_hint) if len(key_or_hint) > 40 else key_or_hint
with self._lock:
users = self._data["users"]
if name not in users:
return False
keys = users[name].get("api_keys", {})
target = kh
if len(key_or_hint) <= 40:
target = next((k for k in keys if k[:8] == key_or_hint), None)
if target is None:
return False
if target not in keys:
return False
del keys[target]
self._save()
return True
def keys(self, name: str) -> list[dict]:
"""Key 元信息 + 明文(明文回显是为了能反复复制)。
取舍(老板 2026-09-13 拍板):以前只存 SHA-256、明文只在创建那一秒返回,
页面刷新就再也看不到,只能重新建一把。现在明文随记录一起存在 data/users.json,
换来「随时可复制」。代价是凭证以明文落在盘上 —— 所以这个文件的权限固定 600、
且在 .gitignore 里;因此**只有会话凭证**能读这个列表(泄漏的 API Key 不能再
顺走同账号其它 Key 的明文)。
本改动之前发的 Key 无法反推明文,`key` 字段回空串,页面按 hint 显示。
"""
with self._lock:
u = self._data["users"].get(name) or {}
return [{
"id": kh[:8],
"label": k.get("label", ""),
"created": k.get("created"),
"hint": k.get("key") or kh[:8], # 有明文就给明文(页面直接展示/复制),旧数据退回哈希前缀
"key": k.get("key", ""),
} for kh, k in sorted((u.get("api_keys") or {}).items())]
def resolve_key(self, key: str) -> tuple[str, str] | None:
"""任一**未停用**账号拥有该 API Key 则返回 (account, role)。恒定时间比较。
前缀只是**廉价预筛**(真正的判定是哈希查表),故这里同时接受新前缀与
LEGACY_KEY_PREFIXES 里的旧前缀,避免已发放的长期 Key 被格式变更无声作废。
第二十四轮:被停用账号的 Key 在这里直接当作无效(Key 本身不删,重新启用即恢复)。
"""
if not key or not key.startswith(_KEY_PREFIXES):
return None
kh = _hash_key(key)
with self._lock:
users = self._data["users"]
for name, u in users.items():
if u.get("disabled"):
continue
if kh in (u.get("api_keys") or {}):
return name, u.get("role", "member")
return None
def disabled_key_owner(self, key: str) -> str | None:
"""该 API Key 是否属于一个**已停用**账号 → 返回该账号名(否则 None)。
只给鉴权层用来把「Key 有效但账号被停用」从 401 里挑出来回 403 —— 对拿不出 Key 的人
仍然是 401,不泄露任何账号状态。返回的账号名只进日志,不回给调用方。
"""
if not key or not key.startswith(_KEY_PREFIXES):
return None
kh = _hash_key(key)
with self._lock:
for name, u in self._data["users"].items():
if u.get("disabled") and kh in (u.get("api_keys") or {}):
return name
return None