Configure for Hugging Face Spaces

.env.example

@@ -0,0 +1,72 @@
+# 代理服务配置文件示例
+# 复制此文件为 .env 并根据需要修改配置值
+
+# ========== API 基础配置 ==========
+# 客户端访问本服务使用的 Bearer 密钥，不是上游 Z.AI 用户 Token
+# 上游用户 Token 请在管理后台导入，由数据库 Token 池统一管理
+AUTH_TOKEN=sk-your-api-key
+
+# 跳过客户端认证（仅开发环境使用）
+SKIP_AUTH_TOKEN=false
+
+# ========== 用户 Token 池配置 ==========
+# 仅作用于管理后台导入的 Z.AI 用户 Token
+# 失败多少次后标记为不可用
+TOKEN_FAILURE_THRESHOLD=3
+
+# 失败 Token 多久后重新参与调度（秒）
+TOKEN_RECOVERY_TIMEOUT=1800
+
+# 定时扫描服务端目录导入 Token
+TOKEN_AUTO_IMPORT_ENABLED=false
+
+# 自动导入的服务端本地目录
+TOKEN_AUTO_IMPORT_SOURCE_DIR=
+
+# 自动导入扫描间隔（秒）
+TOKEN_AUTO_IMPORT_INTERVAL=300
+
+# 定时维护 Token 池
+TOKEN_AUTO_MAINTENANCE_ENABLED=false
+
+# 自动维护执行间隔（秒）
+TOKEN_AUTO_MAINTENANCE_INTERVAL=1800
+
+# 自动维护动作开关
+TOKEN_AUTO_REMOVE_DUPLICATES=true
+TOKEN_AUTO_HEALTH_CHECK=true
+TOKEN_AUTO_DELETE_INVALID=false
+
+# ========== 匿名 Guest 会话池 ==========
+# false: 禁用 guest 匿名池，仅使用后台导入的用户 Token 池
+# true: 启用 guest 匿名池；当没有可用用户 Token 时允许匿名会话
+ANONYMOUS_MODE=true
+
+# 预热和维持的 guest 会话数量
+GUEST_POOL_SIZE=10
+
+# ========== 服务器配置 ==========
+LISTEN_PORT=8080
+SERVICE_NAME=api-proxy-server
+DEBUG_LOGGING=false
+
+# Nginx 反向代理路径前缀（可选）
+ROOT_PATH=
+
+# Function Call 功能开关
+TOOL_SUPPORT=true
+
+# 工具调用扫描限制（字符数）
+SCAN_LIMIT=200000
+
+# SQLite 数据库路径
+DB_PATH=tokens.db
+
+# ========== 代理配置 ==========
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
+# SOCKS5_PROXY=socks5://127.0.0.1:1080
+
+# ========== 管理后台认证 ==========
+ADMIN_PASSWORD=admin123
+SESSION_SECRET_KEY=your-secret-key-change-in-production

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.github/workflows/docker.yml

@@ -0,0 +1,64 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+
+env:
+  IMAGE_NAME: z-ai2api-python
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+            ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./deploy/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -0,0 +1,181 @@
+# Custom
+.vs/
+.vscode/
+.idea/
+.conda/
+*.zip
+*.txt
+*.pid
+docs/
+output/
+main.build/
+main.dist/
+main.onefile-build/
+*report.xml
+*.yaml
+logs/
+backup/
+uv.lock
+AGENTS.md
+*.db
+
+# AI Toolset
+.augment/
+.cursor/
+.claude/
+CLAUDE.md
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+.ace-tool/

Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.12-slim
+
+# Set environment variables
+ENV LISTEN_PORT=7860
+ENV DB_PATH=/app/data/tokens.db
+ENV PYTHONUNBUFFERED=1
+
+# Set working directory
+WORKDIR /app
+
+# Create data and logs directories and set permissions
+# HF Spaces runs as user 1000, so we make sure it can write to these directories
+RUN mkdir -p /app/data /app/logs && \
+    chmod -R 777 /app/data /app/logs
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Ensure all files are accessible
+RUN chmod -R 777 /app
+
+# Expose port
+EXPOSE 7860
+
+# Run the application
+CMD ["python", "main.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZyphrZero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,132 @@
+---
+title: Z.ai API
+emoji: 🚀
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+---
+
+# z-ai2api_python
+
+基于 FastAPI + Granian 的 GLM 代理服务
+适合本地开发、自托管代理、Token 池管理和兼容客户端接入
+
+中文简体 / [English](README_EN.md)  
+
+## 特性
+
+- 兼容 `OpenAI`、`Claude Code`、`Anthropic` 风格请求
+- 支持流式响应、工具调用、Thinking 模型
+- 内置 Token 池，支持轮询、失败熔断、恢复和健康检查
+- 提供后台页面：仪表盘、Token 管理、配置管理、实时日志
+- 使用 SQLite 存储 Token 和请求日志，部署简单
+- 支持本地运行和 Docker / Docker Compose 部署
+
+## 快速开始
+
+### 环境要求
+
+- Python `3.9` 到 `3.12`
+- 推荐使用 `uv`
+
+### 本地启动
+
+```bash
+git clone https://github.com/ZyphrZero/z.ai2api_python.git
+cd z.ai2api_python
+
+uv sync
+cp .env.example .env
+uv run python main.py
+```
+
+首次启动会自动初始化数据库。
+
+默认地址：
+
+- API 根路径：`http://127.0.0.1:8080`
+- OpenAI 文档：`http://127.0.0.1:8080/docs`
+- 管理后台：`http://127.0.0.1:8080/admin`
+
+### Docker Compose
+
+```bash
+docker compose -f deploy/docker-compose.yml up -d --build
+```
+
+更多部署说明见 [deploy/README_DOCKER.md](deploy/README_DOCKER.md)。
+
+## 最小配置
+
+至少建议确认这些环境变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `AUTH_TOKEN` | 客户端访问本服务使用的 Bearer Token |
+| `ADMIN_PASSWORD` | 管理后台登录密码，默认值必须修改 |
+| `LISTEN_PORT` | 服务监听端口，默认 `8080` |
+| `ANONYMOUS_MODE` | 是否启用匿名模式 |
+| `GUEST_POOL_SIZE` | 匿名池容量 |
+| `DB_PATH` | SQLite 数据库路径 |
+| `TOKEN_FAILURE_THRESHOLD` | Token 连续失败阈值 |
+| `TOKEN_RECOVERY_TIMEOUT` | Token 恢复等待时间 |
+
+完整配置请看 [.env.example](.env.example)。
+
+## 管理后台
+
+管理后台统一入口：
+
+- `/admin`：仪表盘
+- `/admin/tokens`：Token 管理
+- `/admin/config`：配置管理
+- `/admin/logs`：实时日志
+
+## 常用命令
+
+```bash
+# 启动服务
+uv run python main.py
+
+# 运行测试
+uv run pytest
+
+# 运行一个现有 smoke test
+uv run python tests/test_simple_signature.py
+
+# Lint
+uv run ruff check app tests main.py
+```
+
+## 兼容接口
+
+常见接口入口：
+
+- OpenAI 兼容：`/v1/chat/completions`
+- Anthropic 兼容：`/v1/messages`
+- Claude Code 兼容：`/anthropic/v1/messages`
+
+模型映射和默认模型可在 `.env` 或后台配置页中调整。
+
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=ZyphrZero/z.ai2api_python&type=Date)](https://star-history.com/#ZyphrZero/z.ai2api_python&Date)
+
+## 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
+
+## 免责声明
+
+- **本项目仅供学习和研究使用，切勿用于其他用途**
+- 本项目与 Z.AI 官方无关
+- 使用前请确保遵守 Z.AI 的服务条款
+- 请勿用于商业用途或违反使用条款的场景
+- 用户需自行承担使用风险
+
+---
+
+<div align="center">
+Made with ❤️ by the community
+</div>

README_EN.md

@@ -0,0 +1,123 @@
+# z-ai2api_python
+
+GLM proxy service based on FastAPI + Granian
+Suitable for local development, self-hosted proxy, Token pool management, and compatible client access
+
+English / [中文简体](README.md)
+
+## Features
+
+- Compatible with `OpenAI`, `Claude Code`, `Anthropic` style requests
+- Supports streaming responses, tool calls, Thinking models
+- Built-in Token pool, supports polling, failure circuit breaker, recovery, and health checks
+- Provides admin panel: Dashboard, Token management, Configuration management, Real-time logs
+- Uses SQLite to store Tokens and request logs, simple deployment
+- Supports local running and Docker / Docker Compose deployment
+
+## Quick Start
+
+### Environment Requirements
+
+- Python `3.9` to `3.12`
+- Recommend using `uv`
+
+### Local Startup
+
+```bash
+git clone https://github.com/ZyphrZero/z.ai2api_python.git
+cd z.ai2api_python
+
+uv sync
+cp .env.example .env
+uv run python main.py
+```
+
+First startup will automatically initialize the database.
+
+Default addresses:
+
+- API root path: `http://127.0.0.1:8080`
+- OpenAI docs: `http://127.0.0.1:8080/docs`
+- Admin panel: `http://127.0.0.1:8080/admin`
+
+### Docker Compose
+
+```bash
+docker compose -f deploy/docker-compose.yml up -d --build
+```
+
+More deployment instructions see [deploy/README_DOCKER.md](deploy/README_DOCKER.md).
+
+## Minimum Configuration
+
+At least suggest confirming these environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `AUTH_TOKEN` | Bearer Token used by clients to access this service |
+| `ADMIN_PASSWORD` | Admin panel login password, default value must be changed |
+| `LISTEN_PORT` | Service listening port, default `8080` |
+| `ANONYMOUS_MODE` | Whether to enable anonymous mode |
+| `GUEST_POOL_SIZE` | Anonymous pool capacity |
+| `DB_PATH` | SQLite database path |
+| `TOKEN_FAILURE_THRESHOLD` | Token consecutive failure threshold |
+| `TOKEN_RECOVERY_TIMEOUT` | Token recovery wait time |
+
+Complete configuration please see [.env.example](.env.example).
+
+## Admin Panel
+
+Admin panel unified entry:
+
+- `/admin`: Dashboard
+- `/admin/tokens`: Token management
+- `/admin/config`: Configuration management
+- `/admin/logs`: Real-time logs
+
+## Common Commands
+
+```bash
+# Start service
+uv run python main.py
+
+# Run tests
+uv run pytest
+
+# Run an existing smoke test
+uv run python tests/test_simple_signature.py
+
+# Lint
+uv run ruff check app tests main.py
+```
+
+## Compatible Interfaces
+
+Common interface entries:
+
+- OpenAI compatible: `/v1/chat/completions`
+- Anthropic compatible: `/v1/messages`
+- Claude Code compatible: `/anthropic/v1/messages`
+
+Model mapping and default model can be adjusted in `.env` or admin configuration page.
+
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=ZyphrZero/z.ai2api_python&type=Date)](https://star-history.com/#ZyphrZero/z.ai2api_python&Date)
+
+## License
+
+This project uses MIT license - see [LICENSE](LICENSE) file for details.
+
+## Disclaimer
+
+- **This project is for learning and research use only, do not use for other purposes**
+- This project is not affiliated with Z.AI official
+- Please ensure compliance with Z.AI's terms of service before use
+- Do not use for commercial purposes or scenarios that violate terms of service
+- Users must bear their own usage risks
+
+---
+
+<div align="center">
+Made with ❤️ by the community
+</div>

app/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from app import core, models, utils
+
+__all__ = ["core", "models", "utils"]

app/admin/__init__.py

@@ -0,0 +1,3 @@
+"""
+管理后台模块初始化
+"""

app/admin/api.py

@@ -0,0 +1,1111 @@
+"""
+管理后台 API 接口
+用于 htmx 调用的 HTML 片段返回
+"""
+from datetime import datetime
+from html import escape
+from pathlib import Path
+import re
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.templating import Jinja2Templates
+
+from app.admin.auth import require_auth
+from app.admin.config_manager import (
+    read_env_content,
+    reset_env_to_example,
+    save_form_config,
+    save_source_config,
+)
+from app.admin.stats import collect_admin_stats, normalize_trend_window
+from app.services.request_log_dao import get_request_log_dao
+from app.utils.logger import logger
+
+router = APIRouter(prefix="/admin/api", tags=["admin-api"])
+templates = Jinja2Templates(directory="app/templates")
+DEFAULT_TOKEN_NAMESPACE = "zai"
+
+
+# ==================== 认证 API ====================
+
+@router.post("/login")
+async def login(request: Request):
+    """管理后台登录"""
+    from app.admin.auth import create_session
+
+    try:
+        data = await request.json()
+        password = data.get("password", "")
+
+        # 创建 session
+        session_token = create_session(password)
+
+        if session_token:
+            # 登录成功，设置 cookie
+            response = JSONResponse({
+                "success": True,
+                "message": "登录成功"
+            })
+            response.set_cookie(
+                key="admin_session",
+                value=session_token,
+                httponly=True,
+                max_age=86400,  # 24小时
+                samesite="lax"
+            )
+            logger.info("✅ 管理后台登录成功")
+            return response
+        else:
+            # 密码错误
+            logger.warning("❌ 管理后台登录失败：密码错误")
+            return JSONResponse({
+                "success": False,
+                "message": "密码错误"
+            }, status_code=401)
+
+    except Exception as e:
+        logger.error(f"❌ 登录异常: {e}")
+        return JSONResponse({
+            "success": False,
+            "message": "登录失败"
+        }, status_code=500)
+
+
+@router.post("/logout")
+async def logout(request: Request):
+    """管理后台登出"""
+    from app.admin.auth import delete_session, get_session_token_from_request
+
+    session_token = get_session_token_from_request(request)
+    delete_session(session_token)
+
+    # 清除 cookie
+    response = JSONResponse({
+        "success": True,
+        "message": "已登出"
+    })
+    response.delete_cookie("admin_session")
+    logger.info("✅ 管理后台已登出")
+    return response
+
+
+async def reload_settings():
+    """热重载配置（重新加载环境变量并更新 settings 对象）"""
+    from dotenv import load_dotenv
+
+    from app.core.config import settings
+    from app.utils.logger import setup_logger
+
+    # 重新加载 .env 文件
+    load_dotenv(override=True)
+
+    # 重新创建 Settings 对象并更新全局配置
+    new_settings = type(settings)()
+
+    # 更新全局 settings 的所有属性
+    for field_name in new_settings.model_fields.keys():
+        setattr(settings, field_name, getattr(new_settings, field_name))
+
+    # 重新初始化 logger（使用新的 DEBUG_LOGGING 配置）
+    setup_logger(log_dir="logs", debug_mode=settings.DEBUG_LOGGING)
+
+    logger.info(f"🔄 配置已热重载 (DEBUG_LOGGING={settings.DEBUG_LOGGING})")
+
+
+def _build_alert(
+    message: str,
+    *,
+    title: str,
+    level: str,
+    status_code: int = 200,
+) -> HTMLResponse:
+    level_classes = {
+        "success": "bg-green-100 border-green-400 text-green-700",
+        "warning": "bg-yellow-100 border-yellow-400 text-yellow-700",
+        "error": "bg-red-100 border-red-400 text-red-700",
+        "info": "bg-blue-100 border-blue-400 text-blue-700",
+    }
+    classes = level_classes.get(level, level_classes["info"])
+    safe_title = escape(title)
+    safe_message = escape(message)
+    return HTMLResponse(
+        f"""
+        <div class="{classes} border px-4 py-3 rounded relative" role="alert">
+            <strong class="font-bold">{safe_title}</strong>
+            <span class="block sm:inline">{safe_message}</span>
+        </div>
+        """,
+        status_code=status_code,
+    )
+
+
+def _with_hx_trigger(response: HTMLResponse, event_name: str) -> HTMLResponse:
+    response.headers["HX-Trigger"] = event_name
+    return response
+
+
+def _get_int_query_param(
+    request: Request,
+    name: str,
+    default: int,
+    *,
+    minimum: int = 1,
+    maximum: Optional[int] = None,
+) -> int:
+    """解析查询参数中的正整数，非法值回退到默认值。"""
+    raw_value = request.query_params.get(name)
+    if raw_value is None:
+        return default
+
+    try:
+        value = int(str(raw_value).strip())
+    except (TypeError, ValueError):
+        return default
+
+    value = max(minimum, value)
+    if maximum is not None:
+        value = min(value, maximum)
+    return value
+
+
+def _build_pagination(
+    *,
+    total_items: int,
+    page: int,
+    page_size: int,
+) -> dict:
+    """构建分页上下文。"""
+    total_items = max(0, int(total_items))
+    page_size = max(1, int(page_size))
+    total_pages = max(1, (total_items + page_size - 1) // page_size)
+    current_page = min(max(1, int(page)), total_pages)
+
+    if total_items == 0:
+        start_item = 0
+        end_item = 0
+    else:
+        start_item = (current_page - 1) * page_size + 1
+        end_item = min(total_items, current_page * page_size)
+
+    return {
+        "current_page": current_page,
+        "page_size": page_size,
+        "total_items": total_items,
+        "total_pages": total_pages,
+        "has_previous": current_page > 1,
+        "has_next": current_page < total_pages,
+        "previous_page": max(1, current_page - 1),
+        "next_page": min(total_pages, current_page + 1),
+        "start_item": start_item,
+        "end_item": end_item,
+    }
+
+
+def _normalize_display_value(value: str) -> str:
+    normalized = re.sub(r"[^a-z0-9]+", "", str(value or "").casefold())
+    return normalized
+
+
+def _is_redundant_source(source: str, client_name: str) -> bool:
+    normalized_source = _normalize_display_value(source)
+    normalized_client = _normalize_display_value(client_name)
+    if not normalized_source:
+        return True
+    if not normalized_client:
+        return False
+    return normalized_source == normalized_client
+
+
+def _humanize_protocol(protocol: str) -> str:
+    normalized = str(protocol or "").strip().lower()
+    if normalized == "openai":
+        return "OpenAI"
+    if normalized == "anthropic":
+        return "Anthropic"
+    if normalized == "unknown":
+        return "Unknown"
+    return normalized or "Unknown"
+
+
+@router.get(
+    "/dashboard/usage-trend",
+    response_class=JSONResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def get_dashboard_usage_trend(request: Request):
+    """返回仪表盘趋势图数据。"""
+    trend_window = normalize_trend_window(
+        request.query_params.get("window")
+    )
+    dao = get_request_log_dao()
+    trend_points = await dao.get_provider_usage_trend(
+        DEFAULT_TOKEN_NAMESPACE,
+        window=trend_window,
+    )
+    return JSONResponse(
+        {
+            "window": trend_window,
+            "points": trend_points,
+        }
+    )
+
+
+def _validate_directory_path(source_dir: str) -> str:
+    if not source_dir:
+        raise ValueError("请先填写服务端可访问的本地目录路径。")
+
+    source_path = Path(source_dir).expanduser()
+    if not source_path.exists():
+        raise ValueError(f"导入目录不存在: {source_path}")
+    if not source_path.is_dir():
+        raise ValueError(f"导入路径不是目录: {source_path}")
+
+    return str(source_path)
+
+
+@router.get("/token-pool", response_class=HTMLResponse)
+async def get_token_pool_status(request: Request):
+    """获取 Token 池状态（HTML 片段）"""
+    from app.utils.token_pool import get_token_pool
+
+    token_pool = get_token_pool()
+
+    if not token_pool:
+        # Token 池未初始化
+        context = {
+            "request": request,
+            "tokens": [],
+        }
+        return templates.TemplateResponse("components/token_pool.html", context)
+
+    # 获取 token 状态统计
+    pool_status = token_pool.get_pool_status()
+    tokens_info = []
+
+    for idx, token_info in enumerate(pool_status.get("tokens", []), 1):
+        is_available = token_info.get("is_available", False)
+        is_healthy = token_info.get("is_healthy", False)
+
+        # 确定状态和颜色
+        if is_healthy:
+            status = "健康"
+            status_color = "bg-green-100 text-green-800"
+        elif is_available:
+            status = "可用"
+            status_color = "bg-yellow-100 text-yellow-800"
+        else:
+            status = "失败"
+            status_color = "bg-red-100 text-red-800"
+
+        # 格式化最后使用时间
+        last_success = token_info.get("last_success_time", 0)
+        if last_success > 0:
+            from datetime import datetime
+            last_used = datetime.fromtimestamp(last_success).strftime("%Y-%m-%d %H:%M:%S")
+        else:
+            last_used = "从未使用"
+
+        tokens_info.append({
+            "index": idx,
+            "key": token_info.get("token", "")[:20] + "...",
+            "status": status,
+            "status_color": status_color,
+            "last_used": last_used,
+            "failure_count": token_info.get("failure_count", 0),
+            "success_rate": token_info.get("success_rate", "0%"),
+            "token_type": token_info.get("token_type", "unknown"),
+        })
+
+    context = {
+        "request": request,
+        "tokens": tokens_info,
+    }
+
+    return templates.TemplateResponse("components/token_pool.html", context)
+
+
+@router.get("/recent-logs", response_class=HTMLResponse)
+async def get_recent_logs(request: Request):
+    """获取最近的请求日志（HTML 片段）"""
+    dao = get_request_log_dao()
+    page_size = _get_int_query_param(
+        request,
+        "page_size",
+        12,
+        maximum=50,
+    )
+    requested_page = _get_int_query_param(request, "page", 1, maximum=100000)
+    total_count = await dao.count_logs()
+    pagination = _build_pagination(
+        total_items=total_count,
+        page=requested_page,
+        page_size=page_size,
+    )
+
+    rows = await dao.get_recent_logs(
+        limit=page_size,
+        offset=(pagination["current_page"] - 1) * page_size,
+    )
+    logs = []
+    for row in rows:
+        timestamp = (
+            row.get("timestamp")
+            or row.get("created_at")
+            or datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        )
+        success = bool(row.get("success"))
+        status_code = int(
+            row.get("status_code") or (200 if success else 500)
+        )
+        duration_value = float(row.get("duration") or 0.0)
+        first_token_value = float(row.get("first_token_time") or 0.0)
+        source = row.get("source") or "unknown"
+        client_name = row.get("client_name") or "Unknown"
+        provider = row.get("provider") or "-"
+        source_display = (
+            ""
+            if _is_redundant_source(source, client_name)
+            else source
+        )
+        provider_display = "" if provider == "zai" else provider
+        logs.append(
+            {
+                "timestamp": timestamp,
+                "endpoint": row.get("endpoint") or "-",
+                "model": row.get("model") or "-",
+                "provider": provider,
+                "provider_display": provider_display,
+                "source": source,
+                "source_display": source_display,
+                "protocol": row.get("protocol") or "unknown",
+                "protocol_display": _humanize_protocol(
+                    row.get("protocol") or "unknown"
+                ),
+                "client_name": client_name,
+                "success": success,
+                "status_code": status_code,
+                "duration_display": f"{duration_value:.2f}s",
+                "first_token_display": (
+                    f"{first_token_value:.2f}s"
+                    if first_token_value > 0
+                    else "--"
+                ),
+                "input_tokens": int(row.get("input_tokens") or 0),
+                "output_tokens": int(row.get("output_tokens") or 0),
+                "cache_creation_tokens": int(
+                    row.get("cache_creation_tokens") or 0
+                ),
+                "cache_read_tokens": int(
+                    row.get("cache_read_tokens") or 0
+                ),
+                "error_message": row.get("error_message") or "",
+            }
+        )
+
+    context = {
+        "request": request,
+        "logs": logs,
+        "page": pagination,
+    }
+
+    return templates.TemplateResponse("components/recent_logs.html", context)
+
+
+@router.post("/config/save", dependencies=[Depends(require_auth)])
+async def save_config(request: Request):
+    """保存结构化配置并热重载。"""
+    try:
+        form_data = await request.form()
+        await save_form_config(
+            form_data,
+            reload_callback=reload_settings,
+        )
+        logger.info("✅ 结构化配置已保存")
+        return _with_hx_trigger(
+            _build_alert(
+                "配置已保存并热重载，页面即将刷新。",
+                title="保存成功！",
+                level="success",
+            ),
+            "admin-config-refresh",
+        )
+    except ValueError as exc:
+        return _build_alert(
+            str(exc),
+            title="校验失败！",
+            level="error",
+            status_code=400,
+        )
+    except Exception as exc:
+        logger.error(f"❌ 配置保存失败: {exc}")
+        return _build_alert(
+            f"保存失败: {exc}",
+            title="错误！",
+            level="error",
+            status_code=500,
+        )
+
+
+@router.post("/config/source", dependencies=[Depends(require_auth)])
+async def save_config_source(request: Request):
+    """保存 .env 源文件并热重载。"""
+    try:
+        form_data = await request.form()
+        await save_source_config(
+            str(form_data.get("env_content", "")),
+            reload_callback=reload_settings,
+        )
+        logger.info("✅ 配置源文件已保存")
+        return _with_hx_trigger(
+            _build_alert(
+                ".env 源文件已保存并热重载，页面即将刷新。",
+                title="保存成功！",
+                level="success",
+            ),
+            "admin-config-refresh",
+        )
+    except ValueError as exc:
+        return _build_alert(
+            str(exc),
+            title="源文件校验失败！",
+            level="error",
+            status_code=400,
+        )
+    except Exception as exc:
+        logger.error(f"❌ 源��件保存失败: {exc}")
+        return _build_alert(
+            f"源文件保存失败: {exc}",
+            title="错误！",
+            level="error",
+            status_code=500,
+        )
+
+
+@router.post("/config/reset", dependencies=[Depends(require_auth)])
+async def reset_config():
+    """将配置重置为 .env.example 并热重载。"""
+    try:
+        await reset_env_to_example(reload_callback=reload_settings)
+        logger.info("✅ 配置已重置为 .env.example 默认值")
+        return _with_hx_trigger(
+            _build_alert(
+                "配置已恢复为 .env.example 默认值，页面即将刷新。",
+                title="已重置！",
+                level="success",
+            ),
+            "admin-config-refresh",
+        )
+    except FileNotFoundError:
+        logger.error("❌ 未找到 .env.example，无法重置配置")
+        return _build_alert(
+            "未找到 .env.example，无法重置配置。",
+            title="错误！",
+            level="error",
+            status_code=404,
+        )
+    except Exception as exc:
+        logger.error(f"❌ 配置重置失败: {exc}")
+        return _build_alert(
+            f"重置失败: {exc}",
+            title="错误！",
+            level="error",
+            status_code=500,
+        )
+
+
+@router.get("/env-preview", dependencies=[Depends(require_auth)])
+async def get_env_preview():
+    """获取 .env 文件预览"""
+    try:
+        content = read_env_content()
+        if not content:
+            content = "# .env 文件不存在"
+        return HTMLResponse(f"<pre>{escape(content)}</pre>")
+    except Exception as exc:
+        return HTMLResponse(f"<pre># 读取失败: {escape(str(exc))}</pre>")
+
+
+@router.get("/live-logs", response_class=HTMLResponse)
+async def get_live_logs():
+    """获取实时日志（最新 50 行）"""
+    import os
+    from datetime import datetime
+
+    logs = []
+
+    # 尝试读取日志文件
+    log_dir = "logs"
+    if os.path.exists(log_dir):
+        log_files = sorted([f for f in os.listdir(log_dir) if f.endswith('.log')], reverse=True)
+        if log_files:
+            log_file = os.path.join(log_dir, log_files[0])
+            try:
+                with open(log_file, 'r', encoding='utf-8') as f:
+                    # 读取最后 50 行
+                    lines = f.readlines()[-50:]
+                    logs = lines
+            except Exception as e:
+                logs = [f"# [{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] 读取日志失败: {str(e)}"]
+
+    if not logs:
+        logs = [f"# [{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] 暂无日志数据"]
+
+    html = ""
+    for log in logs:
+        log_line = log.strip()
+        if not log_line:
+            continue
+
+        # 根据日志级别设置颜色和样式
+        if "ERROR" in log_line or "CRITICAL" in log_line:
+            color_class = "text-red-400 font-semibold"
+            icon = "❌"
+        elif "WARNING" in log_line or "WARN" in log_line:
+            color_class = "text-yellow-400"
+            icon = "⚠️"
+        elif "SUCCESS" in log_line or "✅" in log_line:
+            color_class = "text-green-400"
+            icon = "✅"
+        elif "INFO" in log_line:
+            color_class = "text-blue-400"
+            icon = "ℹ️"
+        elif "DEBUG" in log_line:
+            color_class = "text-gray-400 text-xs"
+            icon = "🔍"
+        else:
+            color_class = "text-gray-300"
+            icon = "•"
+
+        # 转义 HTML 特殊字符
+        log_escaped = log_line.replace('<', '&lt;').replace('>', '&gt;')
+
+        html += f'<div class="{color_class} py-0.5 hover:bg-gray-800 px-2 rounded transition-colors">{icon} {log_escaped}</div>'
+
+    return HTMLResponse(html)
+
+
+# ==================== Token 管理 API ====================
+
+@router.get("/tokens/list", response_class=HTMLResponse)
+async def get_tokens_list(request: Request):
+    """获取 Token 列表（HTML 片段）"""
+    from app.services.token_dao import get_token_dao
+
+    dao = get_token_dao()
+    page_size = _get_int_query_param(
+        request,
+        "page_size",
+        20,
+        maximum=100,
+    )
+    requested_page = _get_int_query_param(request, "page", 1, maximum=100000)
+    total_count = await dao.count_tokens_by_provider(
+        DEFAULT_TOKEN_NAMESPACE,
+        enabled_only=False,
+    )
+    pagination = _build_pagination(
+        total_items=total_count,
+        page=requested_page,
+        page_size=page_size,
+    )
+    tokens = await dao.get_tokens_by_provider(
+        DEFAULT_TOKEN_NAMESPACE,
+        enabled_only=False,
+        limit=page_size,
+        offset=(pagination["current_page"] - 1) * page_size,
+    )
+
+    context = {
+        "request": request,
+        "tokens": tokens,
+        "page": pagination,
+    }
+
+    return templates.TemplateResponse("components/token_list.html", context)
+
+
+@router.post("/tokens/add")
+async def add_tokens(request: Request):
+    """添�� Token"""
+    from app.services.token_dao import get_token_dao
+    from app.utils.token_pool import get_token_pool
+
+    form_data = await request.form()
+    single_token = form_data.get("single_token", "").strip()
+    bulk_tokens = form_data.get("bulk_tokens", "").strip()
+
+    dao = get_token_dao()
+    added_count = 0
+    failed_count = 0
+
+    # 添加单个 Token（带验证）
+    if single_token:
+        token_id = await dao.add_token(
+            DEFAULT_TOKEN_NAMESPACE,
+            single_token,
+            validate=True,
+        )
+        if token_id:
+            added_count += 1
+        else:
+            failed_count += 1
+
+    # 批量添加 Token（带验证）
+    if bulk_tokens:
+        # 支持换行和逗号分隔
+        tokens = []
+        for line in bulk_tokens.split('\n'):
+            line = line.strip()
+            if ',' in line:
+                tokens.extend([t.strip() for t in line.split(',') if t.strip()])
+            elif line:
+                tokens.append(line)
+
+        success, failed = await dao.bulk_add_tokens(
+            DEFAULT_TOKEN_NAMESPACE,
+            tokens,
+            validate=True,
+        )
+        added_count += success
+        failed_count += failed
+
+    # 同步 Token 池状态（如果有新增成功的 Token）
+    if added_count > 0:
+        pool = get_token_pool()
+        if pool:
+            await pool.sync_from_database(DEFAULT_TOKEN_NAMESPACE)
+            logger.info(f"✅ Token 池已同步，新增 {added_count} 个 Token")
+
+    # 生成响应
+    if added_count > 0 and failed_count == 0:
+        return HTMLResponse(f"""
+        <div class="bg-green-100 border border-green-400 text-green-700 px-4 py-3 rounded relative" role="alert">
+            <strong class="font-bold">成功！</strong>
+            <span class="block sm:inline">已添加 {added_count} 个有效 Token</span>
+        </div>
+        """)
+    elif added_count > 0 and failed_count > 0:
+        return HTMLResponse(f"""
+        <div class="bg-yellow-100 border border-yellow-400 text-yellow-700 px-4 py-3 rounded relative" role="alert">
+            <strong class="font-bold">部分成功！</strong>
+            <span class="block sm:inline">已添加 {added_count} 个 Token，{failed_count} 个失败（可能是重复、无效或匿名 Token）</span>
+        </div>
+        """)
+    else:
+        return HTMLResponse("""
+        <div class="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded relative" role="alert">
+            <strong class="font-bold">失败！</strong>
+            <span class="block sm:inline">所有 Token 添加失败（可能是重复、无效或匿名 Token）</span>
+        </div>
+        """)
+
+
+@router.post("/tokens/import-directory", dependencies=[Depends(require_auth)])
+async def import_tokens_from_directory_api(request: Request):
+    """从本地目录导入 token 文件。"""
+    from app.core.config import settings
+    from app.services.token_automation import run_directory_import
+
+    form_data = await request.form()
+    source_dir = str(
+        form_data.get("source_dir")
+        or settings.TOKEN_AUTO_IMPORT_SOURCE_DIR
+        or ""
+    ).strip()
+    try:
+        source_dir = _validate_directory_path(source_dir)
+    except ValueError as exc:
+        return _build_alert(
+            str(exc),
+            title="导入失败！",
+            level="error",
+            status_code=400,
+        )
+
+    try:
+        summary = await run_directory_import(
+            source_dir,
+            provider=DEFAULT_TOKEN_NAMESPACE,
+            validate=True,
+        )
+    except (FileNotFoundError, NotADirectoryError) as exc:
+        return _build_alert(
+            str(exc),
+            title="导入失败！",
+            level="error",
+            status_code=400,
+        )
+    except RuntimeError as exc:
+        return _build_alert(
+            str(exc),
+            title="导入稍后重试",
+            level="warning",
+            status_code=409,
+        )
+    except Exception as exc:
+        logger.exception(f"❌ 本地目录导入 Token 失败: {exc}")
+        return _build_alert(
+            f"目录扫描或入库异常: {exc}",
+            title="导入失败！",
+            level="error",
+            status_code=500,
+        )
+
+    if summary.imported_count > 0:
+        title = "导入成功！" if summary.failed_count == 0 else "导入完成！"
+        detail = (
+            f"目录 {summary.source_dir} 共扫描 {summary.scanned_files} 个文件，"
+            f"成功导入 {summary.imported_count} 个 Token，"
+            f"重复 {summary.duplicate_count} 个，"
+            f"无效 JSON {summary.invalid_json_count} 个，"
+            f"缺少 token {summary.missing_token_count} 个，"
+            f"验证失败 {summary.invalid_token_count} 个。"
+        )
+        return _build_alert(
+            detail,
+            title=title,
+            level="success" if summary.failed_count == 0 else "warning",
+        )
+
+    return _build_alert(
+        (
+            f"目录 {summary.source_dir} 共扫描 {summary.scanned_files} 个文件，"
+            f"其中重复 {summary.duplicate_count} 个，无效 JSON {summary.invalid_json_count} 个，"
+            f"缺少 token {summary.missing_token_count} 个，验证失败 {summary.invalid_token_count} 个。"
+        ),
+        title="未导入任何 Token！",
+        level="warning",
+    )
+
+
+@router.post("/tokens/auto-import/save", dependencies=[Depends(require_auth)])
+async def save_auto_import_settings(request: Request):
+    """兼容旧入口，提示用户改到配置管理页。"""
+    return _build_alert(
+        "自动导入配置入口已迁移到 /admin/config#tokens，当前页面仅保留手动执行入口。",
+        title="入口已迁移",
+        level="info",
+    )
+
+
+@router.post("/tokens/maintenance/save", dependencies=[Depends(require_auth)])
+async def save_auto_maintenance_settings(request: Request):
+    """兼容旧入口，提示用户改到配置管理页。"""
+    return _build_alert(
+        "自动维护配置入口已迁移到 /admin/config#tokens，当前页面仅保留手动执行入口。",
+        title="入口已迁移",
+        level="info",
+    )
+
+
+@router.post("/tokens/maintenance/run", dependencies=[Depends(require_auth)])
+async def run_token_maintenance_api(request: Request):
+    """立即执行一次 Token 维护。"""
+    from app.core.config import settings
+    from app.services.token_automation import run_token_maintenance
+
+    form_data = await request.form()
+    action_fields = (
+        "auto_remove_duplicates",
+        "auto_health_check",
+        "auto_delete_invalid",
+    )
+    has_explicit_actions = any(field in form_data for field in action_fields)
+
+    if has_explicit_actions:
+        remove_duplicates = "auto_remove_duplicates" in form_data
+        run_health_check = "auto_health_check" in form_data
+        delete_invalid = "auto_delete_invalid" in form_data
+    else:
+        remove_duplicates = settings.TOKEN_AUTO_REMOVE_DUPLICATES
+        run_health_check = settings.TOKEN_AUTO_HEALTH_CHECK
+        delete_invalid = settings.TOKEN_AUTO_DELETE_INVALID
+
+    if not any((remove_duplicates, run_health_check, delete_invalid)):
+        return _build_alert(
+            "当前没有可执行的维护动作，请先到 /admin/config#tokens 配置至少一个维护动作。",
+            title="未执行维护！",
+            level="warning",
+            status_code=400,
+        )
+
+    try:
+        summary = await run_token_maintenance(
+            provider=DEFAULT_TOKEN_NAMESPACE,
+            remove_duplicates=remove_duplicates,
+            run_health_check=run_health_check,
+            delete_invalid_tokens=delete_invalid,
+        )
+    except RuntimeError as exc:
+        return _build_alert(
+            str(exc),
+            title="维护稍后重试",
+            level="warning",
+            status_code=409,
+        )
+    except Exception as exc:
+        logger.exception(f"❌ 手动执行 Token 维护失败: {exc}")
+        return _build_alert(
+            f"Token 维护失败: {exc}",
+            title="维护失败！",
+            level="error",
+            status_code=500,
+        )
+
+    return _build_alert(
+        (
+            f"本次维护共去重 {summary.duplicate_removed_count} 个，"
+            f"测活 {summary.checked_count} 个（有效 {summary.valid_count} / "
+            f"匿名 {summary.guest_count} / 无效 {summary.invalid_count}），"
+            f"删除失效 Token {summary.deleted_invalid_count} 个。"
+        ),
+        title="维护完成！",
+        level="success",
+    )
+
+
+@router.post("/tokens/toggle/{token_id}")
+async def toggle_token(token_id: int, enabled: bool):
+    """切换 Token 启用状态"""
+    from app.services.token_dao import get_token_dao
+    from app.utils.token_pool import get_token_pool
+
+    dao = get_token_dao()
+    await dao.update_token_status(token_id, enabled)
+
+    # 同步 Token 池状态
+    pool = get_token_pool()
+    if pool:
+        # 获取 Token 的提供商信息
+        async with dao.get_connection() as conn:
+            cursor = await conn.execute("SELECT provider FROM tokens WHERE id = ?", (token_id,))
+            row = await cursor.fetchone()
+            if row:
+                provider = row[0]
+                await pool.sync_from_database(provider)
+                logger.info("✅ Token 池已同步")
+
+    # 根据状态返回不同样式的按钮
+    if enabled:
+        button_class = "bg-green-100 text-green-800 hover:bg-green-200"
+        indicator_class = "bg-green-500"
+        label = "已启用"
+        next_state = "false"
+    else:
+        button_class = "bg-red-100 text-red-800 hover:bg-red-200"
+        indicator_class = "bg-red-500"
+        label = "已禁用"
+        next_state = "true"
+
+    return HTMLResponse(f"""
+    <button hx-post="/admin/api/tokens/toggle/{token_id}?enabled={next_state}"
+            hx-swap="outerHTML"
+            class="inline-flex items-center px-2.5 py-0.5 text-xs font-semibold rounded-full transition-colors {button_class}">
+        <span class="h-2 w-2 rounded-full mr-1.5 {indicator_class}"></span>
+        {label}
+    </button>
+    """)
+
+
+@router.delete("/tokens/delete/{token_id}")
+async def delete_token(token_id: int):
+    """删除 Token"""
+    from app.services.token_dao import get_token_dao
+    from app.utils.token_pool import get_token_pool
+
+    dao = get_token_dao()
+
+    # 获取 Token 信息以确定提供商
+    async with dao.get_connection() as conn:
+        cursor = await conn.execute("SELECT provider FROM tokens WHERE id = ?", (token_id,))
+        row = await cursor.fetchone()
+        provider = row[0] if row else "zai"
+
+    await dao.delete_token(token_id)
+
+    # 同步 Token 池状态
+    pool = get_token_pool()
+    if pool:
+        await pool.sync_from_database(provider)
+        logger.info("✅ Token 池已同步")
+
+    return HTMLResponse("")  # 返回空内容，让 htmx 移除元素
+
+
+@router.get("/tokens/stats", response_class=HTMLResponse)
+async def get_tokens_stats(request: Request):
+    """获取 Token 统计信息（HTML 片段）"""
+    stats_data = await collect_admin_stats(DEFAULT_TOKEN_NAMESPACE)
+
+    context = {
+        "request": request,
+        "stats": stats_data,
+    }
+
+    return templates.TemplateResponse("components/token_stats.html", context)
+
+
+@router.post("/tokens/validate")
+async def validate_tokens():
+    """批量验证 Token"""
+    from app.services.token_dao import get_token_dao
+    from app.utils.token_pool import get_token_pool
+
+    dao = get_token_dao()
+
+    # 执行批量验证
+    stats = await dao.validate_all_tokens(DEFAULT_TOKEN_NAMESPACE)
+
+    pool = get_token_pool()
+    if pool:
+        await pool.sync_from_database(DEFAULT_TOKEN_NAMESPACE)
+
+    valid_count = stats.get("valid", 0)
+    guest_count = stats.get("guest", 0)
+    invalid_count = stats.get("invalid", 0)
+
+    # 生成通知消息
+    if guest_count > 0:
+        message_class = "bg-yellow-100 border-yellow-400 text-yellow-700"
+        message = f"验证完成：有效 {valid_count} 个，匿名 {guest_count} 个，无效 {invalid_count} 个。匿名 Token 已标记。"
+    elif invalid_count > 0:
+        message_class = "bg-blue-100 border-blue-400 text-blue-700"
+        message = f"验证完成：有效 {valid_count} 个，无效 {invalid_count} 个。"
+    else:
+        message_class = "bg-green-100 border-green-400 text-green-700"
+        message = f"验证完成：所有 {valid_count} 个 Token 均有效！"
+
+    return HTMLResponse(f"""
+    <div class="{message_class} border px-4 py-3 rounded relative" role="alert">
+        <strong class="font-bold">批量验证完成！</strong>
+        <span class="block sm:inline">{message}</span>
+    </div>
+    """)
+
+
+@router.post("/tokens/validate-single/{token_id}")
+async def validate_single_token(request: Request, token_id: int):
+    """验证单个 Token 并返回更新后的行"""
+    from app.services.token_dao import get_token_dao
+    from app.utils.token_pool import get_token_pool
+
+    dao = get_token_dao()
+
+    # 验证 Token
+    await dao.validate_and_update_token(token_id)
+
+    pool = get_token_pool()
+    if pool:
+        await pool.sync_from_database(DEFAULT_TOKEN_NAMESPACE)
+
+    # 获取更新后的 Token 信息
+    async with dao.get_connection() as conn:
+        cursor = await conn.execute("""
+            SELECT t.*, ts.total_requests, ts.successful_requests, ts.failed_requests,
+                   ts.last_success_time, ts.last_failure_time
+            FROM tokens t
+            LEFT JOIN token_stats ts ON t.id = ts.token_id
+            WHERE t.id = ?
+        """, (token_id,))
+        row = await cursor.fetchone()
+
+    if row:
+        # 返回更新后的单行 HTML
+        token = dict(row)
+        context = {
+            "request": request,
+            "token": token,
+        }
+        # 使用单行模板渲染
+        return templates.TemplateResponse("components/token_row.html", context)
+    else:
+        return HTMLResponse("")
+
+
+@router.post("/tokens/health-check")
+async def health_check_tokens():
+    """执行 Token 池健康检查"""
+    from app.utils.token_pool import get_token_pool
+
+    pool = get_token_pool()
+
+    if not pool:
+        return HTMLResponse("""
+        <div class="bg-yellow-100 border border-yellow-400 text-yellow-700 px-4 py-3 rounded relative" role="alert">
+            <strong class="font-bold">提示！</strong>
+            <span class="block sm:inline">Token 池未初始化，请重启服务。</span>
+        </div>
+        """)
+
+    # 执行健康检查
+    await pool.health_check_all()
+
+    # 获取健康状态
+    status = pool.get_pool_status()
+    healthy_count = status.get("healthy_tokens", 0)
+    total_count = status.get("total_tokens", 0)
+
+    if healthy_count == total_count:
+        message_class = "bg-green-100 border-green-400 text-green-700"
+        message = f"所有 {total_count} 个 Token 均健康！"
+    elif healthy_count > 0:
+        message_class = "bg-blue-100 border-blue-400 text-blue-700"
+        message = f"健康检查完成：{healthy_count}/{total_count} 个 Token 健康。"
+    else:
+        message_class = "bg-red-100 border-red-400 text-red-700"
+        message = f"警告：0/{total_count} 个 Token 健康，请检查配置。"
+
+    return HTMLResponse(f"""
+    <div class="{message_class} border px-4 py-3 rounded relative" role="alert">
+        <strong class="font-bold">健康检查完成！</strong>
+        <span class="block sm:inline">{message}</span>
+    </div>
+    """)
+
+
+@router.post("/tokens/sync-pool")
+async def sync_token_pool():
+    """手动同步 Token 池（从数据库重新加载）"""
+    from app.utils.token_pool import get_token_pool
+
+    pool = get_token_pool()
+
+    if not pool:
+        return HTMLResponse("""
+        <div class="bg-yellow-100 border border-yellow-400 text-yellow-700 px-4 py-3 rounded relative" role="alert">
+            <strong class="font-bold">提示！</strong>
+            <span class="block sm:inline">Token 池未初始化，请重启服务。</span>
+        </div>
+        """)
+
+    # 从数据库同步
+    await pool.sync_from_database(DEFAULT_TOKEN_NAMESPACE)
+
+    # 获取同步后的状态
+    status = pool.get_pool_status()
+    total_count = status.get("total_tokens", 0)
+    available_count = status.get("available_tokens", 0)
+    user_count = status.get("user_tokens", 0)
+
+    logger.info(
+        f"✅ Token 池手动同步完成，总计 {total_count} 个 Token, 可用 {available_count} 个, 认证用户 {user_count} 个"
+    )
+
+    if total_count == 0:
+        message_class = "bg-yellow-100 border-yellow-400 text-yellow-700"
+        message = "同步完成：当前没有可用 Token，请在数据库中启用 Token。"
+    elif available_count == 0:
+        message_class = "bg-orange-100 border-orange-400 text-orange-700"
+        message = f"同步完成：共 {total_count} 个 Token，但无可用 Token（可能都已禁用）。"
+    else:
+        message_class = "bg-green-100 border-green-400 text-green-700"
+        message = f"同步完成：共 {total_count} 个 Token，{available_count} 个可用，{user_count} 个认证用户。"
+
+    return HTMLResponse(f"""
+    <div class="{message_class} border px-4 py-3 rounded relative" role="alert">
+        <strong class="font-bold">Token 池同步完成！</strong>
+        <span class="block sm:inline">{message}</span>
+    </div>
+    """)

app/admin/auth.py

@@ -0,0 +1,129 @@
+"""
+管理后台认证中间件
+"""
+from fastapi import Request, HTTPException, status
+from fastapi.responses import RedirectResponse
+from typing import Optional
+import hashlib
+import secrets
+from datetime import datetime, timedelta
+
+from app.core.config import settings
+
+# 简单的内存 Session 存储（生产环境建议使用 Redis）
+_sessions = {}
+
+# Session 有效期（小时）
+SESSION_EXPIRE_HOURS = 24
+
+
+def generate_session_token() -> str:
+    """生成随机 session token"""
+    return secrets.token_urlsafe(32)
+
+
+def create_session(password: str) -> Optional[str]:
+    """
+    创建 session
+
+    Args:
+        password: 用户输入的密码
+
+    Returns:
+        session_token 或 None（密码错误）
+    """
+    # 验证密码
+    if password != settings.ADMIN_PASSWORD:
+        return None
+
+    # 生成 session token
+    session_token = generate_session_token()
+
+    # 存储 session（包含过期时间）
+    _sessions[session_token] = {
+        "created_at": datetime.now(),
+        "expires_at": datetime.now() + timedelta(hours=SESSION_EXPIRE_HOURS),
+        "authenticated": True
+    }
+
+    return session_token
+
+
+def verify_session(session_token: Optional[str]) -> bool:
+    """
+    验证 session 是否有效
+
+    Args:
+        session_token: Session token
+
+    Returns:
+        是否已认证
+    """
+    if not session_token:
+        return False
+
+    session = _sessions.get(session_token)
+    if not session:
+        return False
+
+    # 检查是否过期
+    if datetime.now() > session["expires_at"]:
+        # 删除过期 session
+        del _sessions[session_token]
+        return False
+
+    return session.get("authenticated", False)
+
+
+def delete_session(session_token: Optional[str]):
+    """删除 session（登出）"""
+    if session_token and session_token in _sessions:
+        del _sessions[session_token]
+
+
+def get_session_token_from_request(request: Request) -> Optional[str]:
+    """从请求中获取 session token"""
+    return request.cookies.get("admin_session")
+
+
+async def require_auth(request: Request):
+    """
+    认证依赖项：要求用户已登录
+
+    在路由中使用：
+    @router.get("/admin", dependencies=[Depends(require_auth)])
+    """
+    session_token = get_session_token_from_request(request)
+
+    if not verify_session(session_token):
+        # 未认证，重定向到登录页
+        raise HTTPException(
+            status_code=status.HTTP_303_SEE_OTHER,
+            detail="未登录",
+            headers={"Location": "/admin/login"}
+        )
+
+
+def get_authenticated_user(request: Request) -> bool:
+    """
+    获取当前认证状态（用于模板）
+
+    Returns:
+        是否已认证
+    """
+    session_token = get_session_token_from_request(request)
+    return verify_session(session_token)
+
+
+def cleanup_expired_sessions():
+    """清理过期的 session（定时任务调用）"""
+    now = datetime.now()
+    expired_tokens = [
+        token for token, session in _sessions.items()
+        if now > session["expires_at"]
+    ]
+
+    for token in expired_tokens:
+        del _sessions[token]
+
+    return len(expired_tokens)

app/admin/config_manager.py

@@ -0,0 +1,682 @@
+"""Admin config metadata and helpers for the configuration console."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Mapping
+
+from dotenv import dotenv_values
+
+from app.core.config import settings
+from app.utils.env_file import update_env_file
+from app.utils.logger import logger
+
+ENV_PATH = Path(".env")
+ENV_EXAMPLE_PATH = Path(".env.example")
+_ENV_SOURCE_LINE_PATTERN = re.compile(
+    r"^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=.*$"
+)
+
+
+@dataclass(frozen=True)
+class ConfigFieldSpec:
+    key: str
+    label: str
+    description: str
+    value_type: str
+    default_value: object
+    input_type: str = "text"
+    placeholder: str = ""
+    required: bool = False
+    wide: bool = False
+    sensitive: bool = False
+    restart_required: bool = False
+    min_value: int | None = None
+    max_value: int | None = None
+
+
+@dataclass(frozen=True)
+class ConfigSectionSpec:
+    id: str
+    title: str
+    description: str
+    fields: tuple[ConfigFieldSpec, ...]
+
+
+CONFIG_SECTIONS: tuple[ConfigSectionSpec, ...] = (
+    ConfigSectionSpec(
+        id="access",
+        title="接入与认证",
+        description="控制上游接口地址、客户端鉴权和 Function Call 行为。",
+        fields=(
+            ConfigFieldSpec(
+                key="API_ENDPOINT",
+                label="上游 API 地址",
+                description="代理请求实际转发到的上游聊天完成接口。",
+                value_type="str",
+                default_value="https://chat.z.ai/api/v2/chat/completions",
+                input_type="url",
+                placeholder="https://chat.z.ai/api/v2/chat/completions",
+                required=True,
+                wide=True,
+            ),
+            ConfigFieldSpec(
+                key="AUTH_TOKEN",
+                label="客户端认证密钥",
+                description="客户端访问本服务时使用的 Bearer Token。",
+                value_type="str",
+                default_value="sk-your-api-key",
+                input_type="password",
+                placeholder="sk-your-api-key",
+                wide=True,
+                sensitive=True,
+            ),
+            ConfigFieldSpec(
+                key="SKIP_AUTH_TOKEN",
+                label="跳过客户端认证",
+                description="仅建议开发环境使用，开启后不校验 AUTH_TOKEN。",
+                value_type="bool",
+                default_value=False,
+            ),
+            ConfigFieldSpec(
+                key="TOOL_SUPPORT",
+                label="启用 Function Call",
+                description="允许 OpenAI 兼容接口使用工具调用能力。",
+                value_type="bool",
+                default_value=True,
+            ),
+            ConfigFieldSpec(
+                key="SCAN_LIMIT",
+                label="工具调用扫描限制",
+                description="Function Call 扫描的最大字符数。",
+                value_type="int",
+                default_value=200000,
+                input_type="number",
+                min_value=1,
+                placeholder="200000",
+            ),
+        ),
+    ),
+    ConfigSectionSpec(
+        id="server",
+        title="服务运行",
+        description="服务监听、日志、数据库路径和反向代理前缀。",
+        fields=(
+            ConfigFieldSpec(
+                key="SERVICE_NAME",
+                label="服务名称",
+                description="显示在进程列表中的服务名称。",
+                value_type="str",
+                default_value="api-proxy-server",
+                placeholder="api-proxy-server",
+                required=True,
+                restart_required=True,
+            ),
+            ConfigFieldSpec(
+                key="LISTEN_PORT",
+                label="监听端口",
+                description="HTTP 服务监听端口。",
+                value_type="int",
+                default_value=8080,
+                input_type="number",
+                min_value=1,
+                max_value=65535,
+                required=True,
+                restart_required=True,
+                placeholder="8080",
+            ),
+            ConfigFieldSpec(
+                key="ROOT_PATH",
+                label="反向代理路径前缀",
+                description="例如 /api，部署在子路径时使用。",
+                value_type="str",
+                default_value="",
+                placeholder="/api",
+                restart_required=True,
+            ),
+            ConfigFieldSpec(
+                key="DEBUG_LOGGING",
+                label="启用调试日志",
+                description="开启后会输出更详细的调试信息。",
+                value_type="bool",
+                default_value=False,
+            ),
+            ConfigFieldSpec(
+                key="DB_PATH",
+                label="数据库路径",
+                description="SQLite 数据库文件位置。",
+                value_type="str",
+                default_value="tokens.db",
+                placeholder="tokens.db",
+                required=True,
+                wide=True,
+                restart_required=True,
+            ),
+        ),
+    ),
+    ConfigSectionSpec(
+        id="tokens",
+        title="Token 池策略",
+        description="失败判定、恢复时间和自动导入、自动维护计划任务。",
+        fields=(
+            ConfigFieldSpec(
+                key="TOKEN_FAILURE_THRESHOLD",
+                label="失败阈值",
+                description="连续失败多少次后将 Token 标记为不可用。",
+                value_type="int",
+                default_value=3,
+                input_type="number",
+                min_value=1,
+                required=True,
+                restart_required=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_RECOVERY_TIMEOUT",
+                label="恢复超时（秒）",
+                description="失败 Token 重新参与调度前的等待时间。",
+                value_type="int",
+                default_value=1800,
+                input_type="number",
+                min_value=1,
+                required=True,
+                restart_required=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_IMPORT_ENABLED",
+                label="启用自动导入",
+                description="按固定周期扫描服务端目录并导入 Token。",
+                value_type="bool",
+                default_value=False,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_IMPORT_SOURCE_DIR",
+                label="自动导入目录",
+                description="服务端本地目录，开启自动导入时需要可访问。",
+                value_type="str",
+                default_value="",
+                placeholder="E:\\tokens\\input",
+                wide=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_IMPORT_INTERVAL",
+                label="自动导入间隔（秒）",
+                description="自动导入的扫描周期。",
+                value_type="int",
+                default_value=300,
+                input_type="number",
+                min_value=1,
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_MAINTENANCE_ENABLED",
+                label="启用自动维护",
+                description="定时执行去重、健康检查和删除失效 Token。",
+                value_type="bool",
+                default_value=False,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_MAINTENANCE_INTERVAL",
+                label="自动维护间隔（秒）",
+                description="自动维护的执行周期。",
+                value_type="int",
+                default_value=1800,
+                input_type="number",
+                min_value=1,
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_REMOVE_DUPLICATES",
+                label="自动去重",
+                description="自动维护时清理重复 Token。",
+                value_type="bool",
+                default_value=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_HEALTH_CHECK",
+                label="自动健康检查",
+                description="自动维护时验证 Token 可用性。",
+                value_type="bool",
+                default_value=True,
+            ),
+            ConfigFieldSpec(
+                key="TOKEN_AUTO_DELETE_INVALID",
+                label="自动删除失效 Token",
+                description="自动维护时移除已验证为无效的 Token。",
+                value_type="bool",
+                default_value=False,
+            ),
+        ),
+    ),
+    ConfigSectionSpec(
+        id="guest",
+        title="匿名 Guest 会话池",
+        description="没有用户 Token 时，仅控制是否启用匿名池和池容量。",
+        fields=(
+            ConfigFieldSpec(
+                key="ANONYMOUS_MODE",
+                label="启用匿名模式",
+                description="无可用用户 Token 时允许使用匿名会话。",
+                value_type="bool",
+                default_value=True,
+                restart_required=True,
+            ),
+            ConfigFieldSpec(
+                key="GUEST_POOL_SIZE",
+                label="Guest 池容量",
+                description="启动和维持的 guest 会话数量。",
+                value_type="int",
+                default_value=3,
+                input_type="number",
+                min_value=1,
+                required=True,
+                restart_required=True,
+            ),
+        ),
+    ),
+    ConfigSectionSpec(
+        id="models",
+        title="模型映射",
+        description="映射 OpenAI 兼容模型名到上游 Z.AI 实际模型名。",
+        fields=(
+            ConfigFieldSpec(
+                key="GLM45_MODEL",
+                label="GLM 4.5",
+                description="标准 GLM 4.5 模型标识。",
+                value_type="str",
+                default_value="GLM-4.5",
+                placeholder="GLM-4.5",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM45_THINKING_MODEL",
+                label="GLM 4.5 Thinking",
+                description="推理增强版 GLM 4.5 模型标识。",
+                value_type="str",
+                default_value="GLM-4.5-Thinking",
+                placeholder="GLM-4.5-Thinking",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM45_SEARCH_MODEL",
+                label="GLM 4.5 Search",
+                description="搜索增强版 GLM 4.5 模型标识。",
+                value_type="str",
+                default_value="GLM-4.5-Search",
+                placeholder="GLM-4.5-Search",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM45_AIR_MODEL",
+                label="GLM 4.5 Air",
+                description="轻量版 GLM 4.5 模型标识。",
+                value_type="str",
+                default_value="GLM-4.5-Air",
+                placeholder="GLM-4.5-Air",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM46V_MODEL",
+                label="GLM 4.6V",
+                description="视觉模型标识。",
+                value_type="str",
+                default_value="GLM-4.6V",
+                placeholder="GLM-4.6V",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM5_MODEL",
+                label="GLM 5",
+                description="GLM 5 模型标识。",
+                value_type="str",
+                default_value="GLM-5",
+                placeholder="GLM-5",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM47_MODEL",
+                label="GLM 4.7",
+                description="GLM 4.7 主模型标识。",
+                value_type="str",
+                default_value="GLM-4.7",
+                placeholder="GLM-4.7",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM47_THINKING_MODEL",
+                label="GLM 4.7 Thinking",
+                description="GLM 4.7 推理版模型标识。",
+                value_type="str",
+                default_value="GLM-4.7-Thinking",
+                placeholder="GLM-4.7-Thinking",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM47_SEARCH_MODEL",
+                label="GLM 4.7 Search",
+                description="GLM 4.7 搜索版模型标识。",
+                value_type="str",
+                default_value="GLM-4.7-Search",
+                placeholder="GLM-4.7-Search",
+                required=True,
+            ),
+            ConfigFieldSpec(
+                key="GLM47_ADVANCED_SEARCH_MODEL",
+                label="GLM 4.7 Advanced Search",
+                description="GLM 4.7 高级搜索模型标识。",
+                value_type="str",
+                default_value="GLM-4.7-advanced-search",
+                placeholder="GLM-4.7-advanced-search",
+                required=True,
+                wide=True,
+            ),
+        ),
+    ),
+    ConfigSectionSpec(
+        id="proxy",
+        title="代理网络",
+        description="上游访问使用的 HTTP、HTTPS 和 SOCKS5 代理。",
+        fields=(
+            ConfigFieldSpec(
+                key="HTTP_PROXY",
+                label="HTTP 代理",
+                description="例如 http://127.0.0.1:7890。",
+                value_type="str",
+                default_value="",
+                placeholder="http://127.0.0.1:7890",
+                wide=True,
+            ),
+            ConfigFieldSpec(
+                key="HTTPS_PROXY",
+                label="HTTPS 代理",
+                description="例如 http://127.0.0.1:7890。",
+                value_type="str",
+                default_value="",
+                placeholder="http://127.0.0.1:7890",
+                wide=True,
+            ),
+            ConfigFieldSpec(
+                key="SOCKS5_PROXY",
+                label="SOCKS5 代理",
+                description="例如 socks5://127.0.0.1:1080。",
+                value_type="str",
+                default_value="",
+                placeholder="socks5://127.0.0.1:1080",
+                wide=True,
+            ),
+        ),
+    ),
+    ConfigSectionSpec(
+        id="admin",
+        title="后台安全",
+        description="管理后台密码和会话密钥。修改后建议重新登录。",
+        fields=(
+            ConfigFieldSpec(
+                key="ADMIN_PASSWORD",
+                label="后台密码",
+                description="管理后台登录密码。",
+                value_type="str",
+                default_value="admin123",
+                input_type="password",
+                placeholder="admin123",
+                required=True,
+                sensitive=True,
+            ),
+            ConfigFieldSpec(
+                key="SESSION_SECRET_KEY",
+                label="会话密钥",
+                description="用于后台会话签名的密钥。",
+                value_type="str",
+                default_value="your-secret-key-change-in-production",
+                input_type="password",
+                placeholder="your-secret-key-change-in-production",
+                required=True,
+                sensitive=True,
+                wide=True,
+            ),
+        ),
+    ),
+)
+
+CONFIG_FIELD_SPECS = {
+    field.key: field
+    for section in CONFIG_SECTIONS
+    for field in section.fields
+}
+MANAGED_ENV_KEYS = tuple(CONFIG_FIELD_SPECS.keys())
+ReloadCallback = Callable[[], Awaitable[None]]
+
+
+def read_env_content(env_path: str | Path = ENV_PATH) -> str:
+    path = Path(env_path)
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def validate_env_source(content: str) -> str:
+    normalized = content.replace("\r\n", "\n").replace("\r", "\n")
+
+    for line_number, line in enumerate(normalized.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if not _ENV_SOURCE_LINE_PATTERN.match(line):
+            raise ValueError(
+                f"第 {line_number} 行不是合法的 KEY=VALUE 格式。"
+            )
+
+    return normalized
+
+
+def build_config_page_data(
+    *,
+    settings_obj: Any = settings,
+    env_path: str | Path = ENV_PATH,
+    env_example_path: str | Path = ENV_EXAMPLE_PATH,
+) -> dict[str, Any]:
+    env_file = Path(env_path)
+    env_content = read_env_content(env_file)
+    env_values = dotenv_values(env_file) if env_file.exists() else {}
+    sections: list[dict[str, Any]] = []
+    total_fields = 0
+    overridden_fields = 0
+    sensitive_fields = 0
+    restart_required_fields = 0
+
+    for section in CONFIG_SECTIONS:
+        rendered_fields: list[dict[str, Any]] = []
+        for field in section.fields:
+            total_fields += 1
+            if field.sensitive:
+                sensitive_fields += 1
+            if field.restart_required:
+                restart_required_fields += 1
+
+            is_overridden = field.key in env_values
+            if is_overridden:
+                overridden_fields += 1
+
+            value = getattr(settings_obj, field.key, field.default_value)
+            if value is None:
+                value = ""
+
+            rendered_fields.append(
+                {
+                    "key": field.key,
+                    "label": field.label,
+                    "description": field.description,
+                    "value_type": field.value_type,
+                    "value": value,
+                    "input_type": field.input_type,
+                    "placeholder": field.placeholder,
+                    "required": field.required,
+                    "wide": field.wide,
+                    "sensitive": field.sensitive,
+                    "restart_required": field.restart_required,
+                    "min_value": field.min_value,
+                    "max_value": field.max_value,
+                    "source_label": ".env" if is_overridden else "默认值",
+                    "source_badge_class": (
+                        "bg-emerald-50 text-emerald-700 ring-emerald-200"
+                        if is_overridden
+                        else "bg-slate-100 text-slate-600 ring-slate-200"
+                    ),
+                }
+            )
+
+        sections.append(
+            {
+                "id": section.id,
+                "title": section.title,
+                "description": section.description,
+                "fields": rendered_fields,
+                "field_count": len(rendered_fields),
+            }
+        )
+
+    return {
+        "sections": sections,
+        "env_content": env_content,
+        "overview": {
+            "total_sections": len(CONFIG_SECTIONS),
+            "total_fields": total_fields,
+            "overridden_fields": overridden_fields,
+            "default_fields": total_fields - overridden_fields,
+            "sensitive_fields": sensitive_fields,
+            "restart_required_fields": restart_required_fields,
+            "env_exists": env_file.exists(),
+            "env_path": str(env_file.resolve()),
+            "env_line_count": len(env_content.splitlines()) if env_content else 0,
+            "example_exists": Path(env_example_path).exists(),
+        },
+    }
+
+
+def build_form_updates(form_data: Mapping[str, Any]) -> dict[str, object]:
+    updates: dict[str, object] = {}
+
+    for key in MANAGED_ENV_KEYS:
+        field = CONFIG_FIELD_SPECS[key]
+
+        if field.value_type == "bool":
+            updates[key] = key in form_data
+            continue
+
+        raw_value = str(form_data.get(key, "") or "").strip()
+        if field.required and raw_value == "":
+            raise ValueError(f"{field.label} 不能为空。")
+
+        if field.value_type == "int":
+            try:
+                parsed = int(raw_value)
+            except ValueError as exc:
+                raise ValueError(f"{field.label} 必须是整数。") from exc
+
+            if field.min_value is not None and parsed < field.min_value:
+                raise ValueError(
+                    f"{field.label} 不能小于 {field.min_value}。"
+                )
+            if field.max_value is not None and parsed > field.max_value:
+                raise ValueError(
+                    f"{field.label} 不能大于 {field.max_value}。"
+                )
+            updates[key] = parsed
+            continue
+
+        updates[key] = raw_value
+
+    return updates
+
+
+async def _apply_env_change(
+    writer: Callable[[Path], None],
+    *,
+    reload_callback: ReloadCallback,
+    env_path: str | Path = ENV_PATH,
+) -> None:
+    path = Path(env_path)
+    had_existing_file = path.exists()
+    previous_content = read_env_content(path) if had_existing_file else ""
+
+    try:
+        writer(path)
+        await reload_callback()
+    except Exception:
+        if had_existing_file:
+            path.write_text(previous_content, encoding="utf-8")
+        elif path.exists():
+            path.unlink()
+
+        try:
+            await reload_callback()
+        except Exception as restore_exc:
+            logger.warning(f"⚠️ 回滚配置后重新加载失败: {restore_exc}")
+        raise
+
+
+async def save_form_config(
+    form_data: Mapping[str, Any],
+    *,
+    reload_callback: ReloadCallback,
+    env_path: str | Path = ENV_PATH,
+) -> dict[str, object]:
+    updates = build_form_updates(form_data)
+
+    async def _reload() -> None:
+        await reload_callback()
+
+    def _writer(target_path: Path) -> None:
+        update_env_file(updates, env_path=target_path)
+
+    await _apply_env_change(_writer, reload_callback=_reload, env_path=env_path)
+    return updates
+
+
+async def save_source_config(
+    env_content: str,
+    *,
+    reload_callback: ReloadCallback,
+    env_path: str | Path = ENV_PATH,
+) -> None:
+    normalized = validate_env_source(env_content)
+
+    def _writer(target_path: Path) -> None:
+        content = normalized.rstrip("\n")
+        target_path.write_text(
+            f"{content}\n" if content else "",
+            encoding="utf-8",
+        )
+
+    await _apply_env_change(
+        _writer,
+        reload_callback=reload_callback,
+        env_path=env_path,
+    )
+
+
+async def reset_env_to_example(
+    *,
+    reload_callback: ReloadCallback,
+    env_path: str | Path = ENV_PATH,
+    env_example_path: str | Path = ENV_EXAMPLE_PATH,
+) -> None:
+    example_path = Path(env_example_path)
+    if not example_path.exists():
+        raise FileNotFoundError(".env.example 不存在")
+
+    example_content = example_path.read_text(encoding="utf-8")
+
+    def _writer(target_path: Path) -> None:
+        content = example_content.rstrip("\n")
+        target_path.write_text(
+            f"{content}\n" if content else "",
+            encoding="utf-8",
+        )
+
+    await _apply_env_change(
+        _writer,
+        reload_callback=reload_callback,
+        env_path=env_path,
+    )

app/admin/routes.py

@@ -0,0 +1,109 @@
+"""
+管理后台路由模块
+"""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+
+from app.admin.auth import require_auth
+from app.admin.config_manager import build_config_page_data
+from app.admin.stats import (
+    DEFAULT_TREND_WINDOW,
+    TREND_WINDOW_OPTIONS,
+    collect_admin_stats,
+    get_process_uptime,
+)
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+templates = Jinja2Templates(directory="app/templates")
+DEFAULT_TOKEN_NAMESPACE = "zai"
+
+
+@router.get("/login", response_class=HTMLResponse)
+async def login_page(request: Request):
+    """登录页面"""
+    return templates.TemplateResponse("login.html", {"request": request})
+
+
+@router.get("/", response_class=HTMLResponse, dependencies=[Depends(require_auth)])
+async def dashboard(request: Request):
+    """仪表盘首页"""
+    stats = await collect_admin_stats(
+        DEFAULT_TOKEN_NAMESPACE,
+        trend_window=DEFAULT_TREND_WINDOW,
+    )
+    stats["uptime"] = get_process_uptime()
+
+    context = {
+        "request": request,
+        "stats": stats,
+        "current_time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        "trend_windows": TREND_WINDOW_OPTIONS,
+    }
+
+    return templates.TemplateResponse("index.html", context)
+
+
+@router.get(
+    "/config",
+    response_class=HTMLResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def config_page(request: Request):
+    """配置管理页面"""
+    page_data = build_config_page_data()
+
+    context = {
+        "request": request,
+        "sections": page_data["sections"],
+        "env_content": page_data["env_content"],
+        "overview": page_data["overview"],
+    }
+    return templates.TemplateResponse("config.html", context)
+
+
+@router.get("/logs", response_class=HTMLResponse, dependencies=[Depends(require_auth)])
+async def logs_page(request: Request):
+    """实时日志页面"""
+    context = {
+        "request": request,
+    }
+    return templates.TemplateResponse("logs.html", context)
+
+
+@router.get(
+    "/tokens",
+    response_class=HTMLResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def tokens_page(request: Request):
+    """Token 管理页面"""
+    from app.core.config import settings
+
+    maintenance_actions: list[str] = []
+    if settings.TOKEN_AUTO_REMOVE_DUPLICATES:
+        maintenance_actions.append("删除重复 Token")
+    if settings.TOKEN_AUTO_HEALTH_CHECK:
+        maintenance_actions.append("批量测活")
+    if settings.TOKEN_AUTO_DELETE_INVALID:
+        maintenance_actions.append("删除失效 Token")
+
+    context = {
+        "request": request,
+        "automation": {
+            "config_url": "/admin/config#tokens",
+            "import_enabled": settings.TOKEN_AUTO_IMPORT_ENABLED,
+            "import_source_dir": settings.TOKEN_AUTO_IMPORT_SOURCE_DIR,
+            "import_interval": settings.TOKEN_AUTO_IMPORT_INTERVAL,
+            "has_import_source_dir": bool(
+                settings.TOKEN_AUTO_IMPORT_SOURCE_DIR.strip()
+            ),
+            "maintenance_enabled": settings.TOKEN_AUTO_MAINTENANCE_ENABLED,
+            "maintenance_interval": settings.TOKEN_AUTO_MAINTENANCE_INTERVAL,
+            "maintenance_actions": maintenance_actions,
+            "has_maintenance_actions": bool(maintenance_actions),
+        },
+    }
+    return templates.TemplateResponse("tokens.html", context)

app/admin/stats.py

@@ -0,0 +1,184 @@
+"""管理后台统计聚合辅助函数。"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, Optional
+
+import psutil
+
+from app.services.request_log_dao import RequestLogDAO, get_request_log_dao
+from app.services.token_dao import TokenDAO, get_token_dao
+from app.utils.token_pool import TokenPool, get_token_pool
+
+_TOKEN_POOL_SENTINEL = object()
+DEFAULT_TREND_WINDOW = "7d"
+TREND_WINDOW_OPTIONS = (
+    {"key": "24h", "label": "24 小时"},
+    {"key": "7d", "label": "7 天"},
+    {"key": "30d", "label": "30 天"},
+)
+
+
+def _coerce_int(value: Any) -> int:
+    """将数据库聚合结果安全转换为整数。"""
+    return int(value or 0)
+
+
+def calculate_success_rate(
+    successful_requests: int,
+    total_requests: int,
+) -> float:
+    """计算成功率百分比。"""
+    if total_requests <= 0:
+        return 0.0
+    return round(successful_requests / total_requests * 100, 1)
+
+
+def format_compact_number(value: Any) -> str:
+    """格式化大数字，便于仪表盘展示。"""
+    number = int(value or 0)
+    if number >= 1_000_000:
+        return f"{number / 1_000_000:.1f}M"
+    if number >= 10_000:
+        return f"{number / 10_000:.1f}万"
+    if number >= 1_000:
+        return f"{number / 1_000:.1f}k"
+    return str(number)
+
+
+def normalize_trend_window(value: Any) -> str:
+    """规范化趋势窗口参数，非法值回退到默认值。"""
+    normalized = str(value or "").strip().lower()
+    if normalized in {"24h", "7d", "30d"}:
+        return normalized
+    if normalized == "1d":
+        return "24h"
+    return DEFAULT_TREND_WINDOW
+
+
+def format_uptime(total_seconds: int) -> str:
+    """格式化运行时长。"""
+    total_seconds = max(0, int(total_seconds))
+    days, remainder = divmod(total_seconds, 86400)
+    hours, remainder = divmod(remainder, 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    parts = []
+    if days:
+        parts.append(f"{days}天")
+    if days or hours:
+        parts.append(f"{hours}小时")
+    if days or hours or minutes:
+        parts.append(f"{minutes}分钟")
+    parts.append(f"{seconds}秒")
+
+    return " ".join(parts)
+
+
+def get_process_uptime() -> str:
+    """获取当前进程运行时长。"""
+    created_at = psutil.Process(os.getpid()).create_time()
+    return format_uptime(int(time.time() - created_at))
+
+
+async def collect_admin_stats(
+    provider: str,
+    *,
+    token_dao: Optional[TokenDAO] = None,
+    request_log_dao: Optional[RequestLogDAO] = None,
+    token_pool: Any = _TOKEN_POOL_SENTINEL,
+    trend_window: str = DEFAULT_TREND_WINDOW,
+) -> Dict[str, Any]:
+    """聚合管理后台所需的 Token 与请求统计。"""
+    token_dao = token_dao or get_token_dao()
+    request_log_dao = request_log_dao or get_request_log_dao()
+    if token_pool is _TOKEN_POOL_SENTINEL:
+        token_pool = get_token_pool()
+    trend_window = normalize_trend_window(trend_window)
+
+    token_counts = await token_dao.get_provider_token_counts(provider)
+    request_stats = await request_log_dao.get_provider_request_stats(provider)
+    usage_trend = await request_log_dao.get_provider_usage_trend(
+        provider,
+        window=trend_window,
+    )
+
+    pool_status: Dict[str, Any] = {}
+    if isinstance(token_pool, TokenPool) or hasattr(token_pool, "get_pool_status"):
+        pool_status = token_pool.get_pool_status() if token_pool else {}
+
+    total_tokens = _coerce_int(token_counts.get("total_tokens"))
+    enabled_tokens = _coerce_int(token_counts.get("enabled_tokens"))
+    user_tokens = _coerce_int(token_counts.get("user_tokens"))
+    guest_tokens = _coerce_int(token_counts.get("guest_tokens"))
+    unknown_tokens = _coerce_int(token_counts.get("unknown_tokens"))
+
+    pool_total_tokens = _coerce_int(pool_status.get("total_tokens"))
+    if pool_total_tokens == 0 and token_pool is None:
+        pool_total_tokens = max(0, enabled_tokens - guest_tokens)
+
+    available_tokens = _coerce_int(pool_status.get("available_tokens"))
+    healthy_tokens = _coerce_int(pool_status.get("healthy_tokens"))
+    unhealthy_tokens = _coerce_int(pool_status.get("unhealthy_tokens"))
+
+    total_requests = _coerce_int(request_stats.get("total_requests"))
+    successful_requests = _coerce_int(request_stats.get("successful_requests"))
+    failed_requests = _coerce_int(request_stats.get("failed_requests"))
+    input_tokens = _coerce_int(request_stats.get("input_tokens"))
+    output_tokens = _coerce_int(request_stats.get("output_tokens"))
+    total_consumed_tokens = _coerce_int(request_stats.get("total_tokens"))
+    cache_creation_tokens = _coerce_int(
+        request_stats.get("cache_creation_tokens")
+    )
+    cache_read_tokens = _coerce_int(request_stats.get("cache_read_tokens"))
+    cache_creation_requests = _coerce_int(
+        request_stats.get("cache_creation_requests")
+    )
+    cache_hit_requests = _coerce_int(request_stats.get("cache_hit_requests"))
+    average_latency = round(float(request_stats.get("avg_duration") or 0.0), 2)
+    average_first_token_latency = round(
+        float(request_stats.get("avg_first_token_time") or 0.0),
+        2,
+    )
+    total_cache_tokens = cache_creation_tokens + cache_read_tokens
+
+    return {
+        "total_tokens": total_tokens,
+        "enabled_tokens": enabled_tokens,
+        "user_tokens": user_tokens,
+        "guest_tokens": guest_tokens,
+        "unknown_tokens": unknown_tokens,
+        "pool_total_tokens": pool_total_tokens,
+        "available_tokens": available_tokens,
+        "healthy_tokens": healthy_tokens,
+        "unhealthy_tokens": unhealthy_tokens,
+        "total_requests": total_requests,
+        "successful_requests": successful_requests,
+        "failed_requests": failed_requests,
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "total_consumed_tokens": total_consumed_tokens,
+        "cache_creation_tokens": cache_creation_tokens,
+        "cache_read_tokens": cache_read_tokens,
+        "total_cache_tokens": total_cache_tokens,
+        "cache_creation_requests": cache_creation_requests,
+        "cache_hit_requests": cache_hit_requests,
+        "average_latency": average_latency,
+        "average_first_token_latency": average_first_token_latency,
+        "trend_window": trend_window,
+        "usage_trend": usage_trend,
+        "total_consumed_tokens_display": format_compact_number(
+            total_consumed_tokens
+        ),
+        "total_cache_tokens_display": format_compact_number(
+            total_cache_tokens
+        ),
+        "input_tokens_display": format_compact_number(input_tokens),
+        "output_tokens_display": format_compact_number(output_tokens),
+        "success_rate": calculate_success_rate(
+            successful_requests,
+            total_requests,
+        ),
+    }

app/core/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from app.core import claude, config, openai
+
+__all__ = ["claude", "config", "openai"]

app/core/claude.py

@@ -0,0 +1,582 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import json
+import math
+import time
+import uuid
+from typing import Any, AsyncGenerator, Dict, List, Optional
+
+from fastapi import APIRouter, Header, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from app.core.claude_compat import (
+    build_non_stream_response,
+    claude_messages_to_openai,
+    claude_tool_choice_to_openai,
+    claude_tools_to_openai,
+    extract_text,
+    make_claude_id,
+    sse_content_block_delta,
+    sse_content_block_start,
+    sse_content_block_stop,
+    sse_error,
+    sse_message_delta,
+    sse_message_start,
+    sse_message_stop,
+    sse_ping,
+)
+from app.core.config import settings
+from app.core.openai import get_upstream_client
+from app.models.schemas import Message, OpenAIRequest
+from app.utils.logger import get_logger
+from app.utils.request_logging import (
+    extract_openai_usage,
+    extract_claude_usage,
+    wrap_claude_stream_with_logging,
+    write_request_log,
+)
+from app.utils.request_source import detect_request_source, format_request_source
+
+logger = get_logger()
+router = APIRouter()
+
+
+def _resolve_claude_model(model: Any) -> str:
+    """Map Claude/Claude Code model aliases to local upstream-supported models."""
+    if not isinstance(model, str) or not model.strip():
+        return settings.GLM5_MODEL
+
+    raw_model = model.strip()
+    normalized = raw_model.casefold()
+    if normalized.endswith("[1m]"):
+        normalized = normalized[:-4].rstrip()
+
+    direct_models = {
+        settings.GLM45_MODEL.casefold(): settings.GLM45_MODEL,
+        settings.GLM45_THINKING_MODEL.casefold(): settings.GLM45_THINKING_MODEL,
+        settings.GLM45_SEARCH_MODEL.casefold(): settings.GLM45_SEARCH_MODEL,
+        settings.GLM45_AIR_MODEL.casefold(): settings.GLM45_AIR_MODEL,
+        settings.GLM46V_MODEL.casefold(): settings.GLM46V_MODEL,
+        settings.GLM5_MODEL.casefold(): settings.GLM5_MODEL,
+        settings.GLM47_MODEL.casefold(): settings.GLM47_MODEL,
+        settings.GLM47_THINKING_MODEL.casefold(): settings.GLM47_THINKING_MODEL,
+        settings.GLM47_SEARCH_MODEL.casefold(): settings.GLM47_SEARCH_MODEL,
+        settings.GLM47_ADVANCED_SEARCH_MODEL.casefold(): settings.GLM47_ADVANCED_SEARCH_MODEL,
+    }
+    if normalized in direct_models:
+        return direct_models[normalized]
+
+    alias_map = {
+        "default": settings.GLM5_MODEL,
+        "sonnet": settings.GLM5_MODEL,
+        "haiku": settings.GLM45_AIR_MODEL,
+        "opus": settings.GLM5_MODEL,
+        "opusplan": settings.GLM47_THINKING_MODEL,
+    }
+    if normalized in alias_map:
+        return alias_map[normalized]
+
+    if normalized.startswith("claude-sonnet") or normalized.startswith("claude-3-7-sonnet") or normalized.startswith("claude-3-5-sonnet"):
+        return settings.GLM5_MODEL
+    if normalized.startswith("claude-opus") or normalized.startswith("claude-4-opus"):
+        return settings.GLM5_MODEL
+    if normalized.startswith("claude-haiku") or normalized.startswith("claude-3-5-haiku"):
+        return settings.GLM45_AIR_MODEL
+
+    return raw_model
+
+
+def _estimate_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return max(1, math.ceil(len(text) / 2))
+
+
+def _extract_api_key(
+    authorization: Optional[str],
+    x_api_key: Optional[str],
+) -> Optional[str]:
+    if x_api_key:
+        return x_api_key
+    if authorization and authorization.startswith("Bearer "):
+        return authorization[7:]
+    return None
+
+
+def _claude_error_response(
+    message: str,
+    status_code: int,
+    error_type: str,
+) -> JSONResponse:
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "type": "error",
+            "error": {"type": error_type, "message": message},
+        },
+    )
+
+
+def _build_openai_request(body: Dict[str, Any]) -> OpenAIRequest:
+    system = body.get("system")
+    claude_messages = body.get("messages", [])
+    openai_messages = claude_messages_to_openai(system, claude_messages)
+    openai_tools = claude_tools_to_openai(body.get("tools"))
+    tool_choice = claude_tool_choice_to_openai(body.get("tool_choice"))
+
+    thinking = body.get("thinking")
+    enable_thinking = None
+    if isinstance(thinking, dict):
+        thinking_type = thinking.get("type")
+        if thinking_type == "enabled":
+            enable_thinking = True
+        elif thinking_type == "disabled":
+            enable_thinking = False
+
+    messages = [Message.model_validate(message) for message in openai_messages]
+    resolved_model = _resolve_claude_model(body.get("model", settings.GLM5_MODEL))
+    if resolved_model != body.get("model", settings.GLM5_MODEL):
+        logger.info(
+            f"🔀 Claude 模型映射: "
+            f"{body.get('model', settings.GLM5_MODEL)} -> {resolved_model}"
+        )
+
+    return OpenAIRequest(
+        model=resolved_model,
+        messages=messages,
+        stream=bool(body.get("stream", False)),
+        temperature=body.get("temperature"),
+        max_tokens=body.get("max_tokens"),
+        tools=openai_tools,
+        tool_choice=tool_choice,
+        enable_thinking=enable_thinking,
+    )
+
+
+def _build_prompt_text(body: Dict[str, Any]) -> str:
+    prompt_parts: List[str] = []
+    system = body.get("system")
+    if system:
+        prompt_parts.append(extract_text(system))
+
+    for message in body.get("messages", []):
+        content = message.get("content") if isinstance(message, dict) else None
+        text = extract_text(content)
+        if text:
+            prompt_parts.append(text)
+
+    return "\n".join(part for part in prompt_parts if part)
+
+
+def _normalize_tool_calls(tool_calls: Any) -> List[Dict[str, Any]]:
+    if not isinstance(tool_calls, list):
+        return []
+
+    normalized: List[Dict[str, Any]] = []
+    seen_ids = set()
+    for tool_call in tool_calls:
+        if not isinstance(tool_call, dict):
+            continue
+
+        tool_call_id = tool_call.get("id") or f"call_{uuid.uuid4().hex[:24]}"
+        if tool_call_id in seen_ids:
+            continue
+        seen_ids.add(tool_call_id)
+
+        function_data = (
+            tool_call.get("function")
+            if isinstance(tool_call.get("function"), dict)
+            else {}
+        )
+        arguments = function_data.get("arguments", "{}")
+        if not isinstance(arguments, str):
+            try:
+                arguments = json.dumps(arguments, ensure_ascii=False)
+            except Exception:
+                arguments = "{}"
+
+        normalized.append(
+            {
+                "id": tool_call_id,
+                "type": "function",
+                "function": {
+                    "name": function_data.get("name", ""),
+                    "arguments": arguments,
+                },
+            }
+        )
+
+    return normalized
+
+
+def _convert_openai_response_to_claude(response: Dict[str, Any], msg_id: str) -> Dict[str, Any]:
+    choice = ((response.get("choices") or [{}])[0]) if isinstance(response, dict) else {}
+    message = choice.get("message") or {}
+    reasoning = message.get("reasoning_content")
+    usage = extract_openai_usage(response)
+    return build_non_stream_response(
+        msg_id=msg_id,
+        model=response.get("model", settings.GLM5_MODEL),
+        reasoning_parts=[reasoning] if isinstance(reasoning, str) and reasoning else [],
+        answer_text=message.get("content") or "",
+        tool_calls=_normalize_tool_calls(message.get("tool_calls")),
+        input_tokens=usage["input_tokens"],
+        output_tokens=usage["output_tokens"],
+        cache_creation_tokens=usage["cache_creation_tokens"],
+        cache_read_tokens=usage["cache_read_tokens"],
+    )
+
+
+async def _stream_openai_to_claude(
+    openai_stream: AsyncGenerator[str, None],
+    msg_id: str,
+    model: str,
+    input_tokens: int,
+) -> AsyncGenerator[str, None]:
+    reasoning_parts: List[str] = []
+    answer_parts: List[str] = []
+    tool_calls: List[Dict[str, Any]] = []
+    block_index = 0
+    thinking_started = False
+    final_input_tokens = input_tokens
+    final_output_tokens = 0
+    cache_creation_tokens = 0
+    cache_read_tokens = 0
+
+    yield sse_message_start(msg_id, model, input_tokens)
+    yield sse_ping()
+
+    try:
+        async for chunk in openai_stream:
+            if not chunk.startswith("data: "):
+                continue
+
+            payload_text = chunk[6:].strip()
+            if not payload_text or payload_text == "[DONE]":
+                continue
+
+            payload = json.loads(payload_text)
+            if isinstance(payload, dict) and "error" in payload:
+                error = payload.get("error") or {}
+                yield sse_error(
+                    error.get("type", "api_error"),
+                    error.get("message", "Upstream error"),
+                )
+                return
+
+            choice = ((payload.get("choices") or [{}])[0]) if isinstance(payload, dict) else {}
+            delta = choice.get("delta") or {}
+
+            reasoning_delta = delta.get("reasoning_content")
+            if reasoning_delta:
+                if not thinking_started:
+                    yield sse_content_block_start(
+                        block_index,
+                        {"type": "thinking", "thinking": ""},
+                    )
+                    thinking_started = True
+
+                reasoning_parts.append(reasoning_delta)
+                yield sse_content_block_delta(
+                    block_index,
+                    {"type": "thinking_delta", "thinking": reasoning_delta},
+                )
+
+            content_delta = delta.get("content")
+            if content_delta:
+                answer_parts.append(content_delta)
+
+            if payload.get("usage"):
+                usage = extract_openai_usage(payload)
+                if usage["input_tokens"] > 0:
+                    final_input_tokens = usage["input_tokens"]
+                if usage["output_tokens"] > 0:
+                    final_output_tokens = usage["output_tokens"]
+                if usage["cache_creation_tokens"] > 0:
+                    cache_creation_tokens = usage["cache_creation_tokens"]
+                if usage["cache_read_tokens"] > 0:
+                    cache_read_tokens = usage["cache_read_tokens"]
+
+            tool_calls.extend(_normalize_tool_calls(delta.get("tool_calls")))
+
+        if thinking_started:
+            yield sse_content_block_stop(block_index)
+            block_index += 1
+
+        answer_text = "".join(answer_parts)
+        if answer_text:
+            yield sse_content_block_start(block_index, {"type": "text", "text": ""})
+            yield sse_content_block_delta(
+                block_index,
+                {"type": "text_delta", "text": answer_text},
+            )
+            yield sse_content_block_stop(block_index)
+            block_index += 1
+
+        if tool_calls:
+            for tool_call in tool_calls:
+                function_data = tool_call.get("function") or {}
+                tool_id = tool_call.get(
+                    "id",
+                    f"toolu_{uuid.uuid4().hex[:20]}",
+                ).replace("call_", "toolu_")
+                yield sse_content_block_start(
+                    block_index,
+                    {
+                        "type": "tool_use",
+                        "id": tool_id,
+                        "name": function_data.get("name", ""),
+                        "input": {},
+                    },
+                )
+                yield sse_content_block_delta(
+                    block_index,
+                    {
+                        "type": "input_json_delta",
+                        "partial_json": function_data.get("arguments", "{}"),
+                    },
+                )
+                yield sse_content_block_stop(block_index)
+                block_index += 1
+
+        if not final_output_tokens:
+            final_output_tokens = _estimate_tokens(
+                "".join(reasoning_parts) + answer_text
+            )
+
+        yield sse_message_delta(
+            "tool_use" if tool_calls else "end_turn",
+            final_output_tokens,
+            input_tokens=final_input_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cache_read_tokens=cache_read_tokens,
+        )
+        yield sse_message_stop()
+    except Exception as exc:
+        logger.error(f"❌ Claude 流式响应转换失败: {exc}")
+        yield sse_error("api_error", str(exc))
+
+
+@router.post("/v1/messages")
+@router.post("/anthropic/v1/messages")
+async def claude_messages(
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    x_api_key: Optional[str] = Header(None, alias="x-api-key"),
+):
+    source_info = detect_request_source(
+        request,
+        protocol_hint="anthropic",
+    )
+    source_prefix = format_request_source(source_info)
+    started_at = time.perf_counter()
+    requested_model = "unknown"
+
+    try:
+        body = await request.json()
+    except Exception:
+        await write_request_log(
+            provider="zai",
+            model=requested_model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=400,
+            error_message="Invalid JSON body",
+        )
+        return _claude_error_response(
+            "Invalid JSON body",
+            400,
+            "invalid_request_error",
+        )
+
+    requested_model = str(body.get("model") or "unknown")
+    source_info = detect_request_source(
+        request,
+        protocol_hint="anthropic",
+        model_hint=body.get("model"),
+    )
+    source_prefix = format_request_source(source_info)
+
+    if not settings.SKIP_AUTH_TOKEN:
+        api_key = _extract_api_key(authorization, x_api_key)
+        if not api_key:
+            await write_request_log(
+                provider="zai",
+                model=requested_model,
+                source_info=source_info,
+                success=False,
+                started_at=started_at,
+                status_code=401,
+                error_message="Missing API key",
+            )
+            return _claude_error_response(
+                "Missing API key",
+                401,
+                "authentication_error",
+            )
+        if api_key != settings.AUTH_TOKEN:
+            await write_request_log(
+                provider="zai",
+                model=requested_model,
+                source_info=source_info,
+                success=False,
+                started_at=started_at,
+                status_code=401,
+                error_message="Invalid API key",
+            )
+            return _claude_error_response(
+                "Invalid API key",
+                401,
+                "authentication_error",
+            )
+
+    try:
+        openai_request = _build_openai_request(body)
+    except Exception as exc:
+        await write_request_log(
+            provider="zai",
+            model=requested_model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=400,
+            error_message=f"Invalid request: {exc}",
+        )
+        return _claude_error_response(
+            f"Invalid request: {exc}",
+            400,
+            "invalid_request_error",
+        )
+
+    if not openai_request.messages:
+        await write_request_log(
+            provider="zai",
+            model=openai_request.model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=400,
+            error_message="messages is required",
+        )
+        return _claude_error_response(
+            "messages is required",
+            400,
+            "invalid_request_error",
+        )
+    logger.info(
+        f"{source_prefix} 🤖 收到 Claude 请求 - 模型: {body.get('model')}, 映射模型: {openai_request.model}, 流式: {openai_request.stream}, 消息数: {len(openai_request.messages)}, 工具数: {len(openai_request.tools) if openai_request.tools else 0}"
+    )
+
+    msg_id = make_claude_id()
+    input_tokens = _estimate_tokens(_build_prompt_text(body))
+
+    try:
+        client = get_upstream_client()
+        result = await client.chat_completion(openai_request)
+    except Exception as exc:
+        logger.error(f"{source_prefix} ❌ Claude 请求处理失败: {exc}")
+        await write_request_log(
+            provider="zai",
+            model=openai_request.model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=500,
+            error_message=str(exc),
+        )
+        return _claude_error_response(str(exc), 500, "api_error")
+
+    if isinstance(result, dict) and "error" in result:
+        error = result.get("error") or {}
+        error_code = error.get("code")
+        status_code = error_code if isinstance(error_code, int) else 500
+        await write_request_log(
+            provider="zai",
+            model=openai_request.model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=status_code,
+            error_message=error.get("message", "Unknown upstream error"),
+        )
+        return _claude_error_response(
+            error.get("message", "Unknown upstream error"),
+            status_code,
+            error.get("type", "api_error"),
+        )
+
+    if openai_request.stream:
+        if not hasattr(result, "__aiter__"):
+            await write_request_log(
+                provider="zai",
+                model=openai_request.model,
+                source_info=source_info,
+                success=False,
+                started_at=started_at,
+                status_code=500,
+                error_message="Expected streaming response",
+            )
+            return _claude_error_response(
+                "Expected streaming response",
+                500,
+                "api_error",
+            )
+
+        return StreamingResponse(
+            wrap_claude_stream_with_logging(
+                _stream_openai_to_claude(
+                    result,
+                    msg_id,
+                    openai_request.model,
+                    input_tokens,
+                ),
+                provider="zai",
+                model=openai_request.model,
+                source_info=source_info,
+                started_at=started_at,
+                input_tokens=input_tokens,
+            ),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Access-Control-Allow-Origin": "*",
+            },
+        )
+
+    if not isinstance(result, dict):
+        await write_request_log(
+            provider="zai",
+            model=openai_request.model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=500,
+            error_message="Expected non-streaming response payload",
+        )
+        return _claude_error_response(
+            "Expected non-streaming response payload",
+            500,
+            "api_error",
+        )
+
+    response_data = _convert_openai_response_to_claude(result, msg_id)
+    if not response_data.get("usage", {}).get("input_tokens"):
+        response_data["usage"]["input_tokens"] = input_tokens
+    usage = extract_claude_usage(response_data)
+    await write_request_log(
+        provider="zai",
+        model=openai_request.model,
+        source_info=source_info,
+        success=True,
+        started_at=started_at,
+        status_code=200,
+        input_tokens=usage["input_tokens"],
+        output_tokens=usage["output_tokens"],
+        cache_creation_tokens=usage["cache_creation_tokens"],
+        cache_read_tokens=usage["cache_read_tokens"],
+        total_tokens=usage["total_tokens"],
+    )
+    return JSONResponse(content=response_data)

app/core/claude_compat.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""Claude Messages API 兼容辅助函数。"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, Optional
+
+
+def extract_text(content: Any) -> str:
+    """Extract plain text from Claude/OpenAI mixed content blocks."""
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        return " ".join(
+            str(block.get("text", ""))
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "text"
+        ).strip()
+
+    return str(content) if content else ""
+
+
+def claude_messages_to_openai(system: Any, messages: list[dict]) -> list[dict]:
+    """Convert Claude messages payload into OpenAI-style messages."""
+    converted: list[dict] = []
+
+    if system:
+        if isinstance(system, str):
+            converted.append({"role": "system", "content": system})
+        elif isinstance(system, list):
+            system_text = [
+                block.get("text", "")
+                for block in system
+                if isinstance(block, dict) and block.get("type") == "text"
+            ]
+            if system_text:
+                converted.append({
+                    "role": "system",
+                    "content": "\n".join(system_text),
+                })
+
+    for message in messages:
+        role = message.get("role", "user")
+        content = message.get("content", "")
+
+        if role == "assistant" and isinstance(content, list):
+            text_parts: list[str] = []
+            tool_calls: list[dict] = []
+
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+
+                block_type = block.get("type")
+                if block_type == "text":
+                    text_parts.append(block.get("text", ""))
+                elif block_type == "tool_use":
+                    tool_calls.append(
+                        {
+                            "id": block.get(
+                                "id",
+                                f"call_{uuid.uuid4().hex[:24]}",
+                            ),
+                            "type": "function",
+                            "function": {
+                                "name": block.get("name", ""),
+                                "arguments": json.dumps(
+                                    block.get("input", {}),
+                                    ensure_ascii=False,
+                                ),
+                            },
+                        }
+                    )
+
+            openai_message: dict = {
+                "role": "assistant",
+                "content": " ".join(text_parts).strip() or None,
+            }
+            if tool_calls:
+                openai_message["tool_calls"] = tool_calls
+            converted.append(openai_message)
+            continue
+
+        if role == "user" and isinstance(content, list):
+            has_tool_result = any(
+                isinstance(block, dict) and block.get("type") == "tool_result"
+                for block in content
+            )
+            if has_tool_result:
+                for block in content:
+                    if not isinstance(block, dict):
+                        continue
+
+                    block_type = block.get("type")
+                    if block_type == "tool_result":
+                        result_content = block.get("content", "")
+                        if isinstance(result_content, str):
+                            rendered = result_content
+                        elif isinstance(result_content, list):
+                            rendered = " ".join(
+                                item.get("text", "")
+                                for item in result_content
+                                if isinstance(item, dict)
+                                and item.get("type") == "text"
+                            )
+                        else:
+                            rendered = str(result_content)
+
+                        converted.append(
+                            {
+                                "role": "tool",
+                                "tool_call_id": block.get("tool_use_id", ""),
+                                "content": rendered,
+                            }
+                        )
+                    elif block_type == "text":
+                        converted.append(
+                            {"role": "user", "content": block.get("text", "")}
+                        )
+                continue
+
+        converted.append({"role": role, "content": extract_text(content)})
+
+    return converted
+
+
+def claude_tools_to_openai(tools: Optional[list[dict]]) -> Optional[list[dict]]:
+    """Convert Claude tool schemas into OpenAI function tools."""
+    if not tools:
+        return None
+
+    converted = [
+        {
+            "type": "function",
+            "function": {
+                "name": tool.get("name", ""),
+                "description": tool.get("description", ""),
+                "parameters": tool.get("input_schema", {}),
+            },
+        }
+        for tool in tools
+        if isinstance(tool, dict)
+    ]
+    return converted or None
+
+
+def claude_tool_choice_to_openai(tool_choice: Any) -> Any:
+    """Convert Claude tool_choice payload into OpenAI-compatible form."""
+    if not isinstance(tool_choice, dict):
+        return tool_choice
+
+    tool_choice_type = tool_choice.get("type", "auto")
+    if tool_choice_type == "auto":
+        return "auto"
+    if tool_choice_type == "any":
+        return "required"
+    if tool_choice_type == "none":
+        return "none"
+    if tool_choice_type == "tool":
+        name = tool_choice.get("name", "")
+        if name:
+            return {"type": "function", "function": {"name": name}}
+    return tool_choice
+
+
+def make_claude_id() -> str:
+    """Generate a Claude-style message id."""
+    return f"msg_{uuid.uuid4().hex[:24]}"
+
+
+def build_tool_call_blocks(tool_calls: list[dict]) -> list[dict]:
+    """Convert OpenAI tool calls to Claude tool_use blocks."""
+    blocks = []
+    for tool_call in tool_calls:
+        function_data = (
+            tool_call.get("function")
+            if isinstance(tool_call.get("function"), dict)
+            else {}
+        )
+        arguments = function_data.get("arguments", "{}")
+        try:
+            input_data = json.loads(arguments) if isinstance(arguments, str) else arguments
+        except Exception:
+            input_data = {}
+
+        blocks.append(
+            {
+                "type": "tool_use",
+                "id": tool_call.get(
+                    "id",
+                    f"toolu_{uuid.uuid4().hex[:20]}",
+                ).replace("call_", "toolu_"),
+                "name": function_data.get("name", ""),
+                "input": input_data,
+            }
+        )
+    return blocks
+
+
+def build_non_stream_response(
+    msg_id: str,
+    model: str,
+    reasoning_parts: list[str],
+    answer_text: str,
+    tool_calls: Optional[list[dict]],
+    input_tokens: int,
+    output_tokens: int,
+    cache_creation_tokens: int = 0,
+    cache_read_tokens: int = 0,
+) -> dict:
+    """Build a Claude non-streaming message response."""
+    content: list[dict] = []
+    if reasoning_parts:
+        content.append(
+            {"type": "thinking", "thinking": "".join(reasoning_parts)}
+        )
+    if answer_text:
+        content.append({"type": "text", "text": answer_text})
+    elif not tool_calls:
+        content.append({"type": "text", "text": ""})
+    if tool_calls:
+        content.extend(build_tool_call_blocks(tool_calls))
+
+    return {
+        "id": msg_id,
+        "type": "message",
+        "role": "assistant",
+        "content": content,
+        "model": model,
+        "stop_reason": "tool_use" if tool_calls else "end_turn",
+        "stop_sequence": None,
+        "usage": {
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cache_creation_input_tokens": cache_creation_tokens,
+            "cache_read_input_tokens": cache_read_tokens,
+        },
+    }
+
+
+def sse(event: str, data: dict) -> str:
+    """Format a Claude SSE event."""
+    return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
+
+
+def sse_message_start(
+    msg_id: str,
+    model: str,
+    input_tokens: int,
+    cache_creation_tokens: int = 0,
+    cache_read_tokens: int = 0,
+) -> str:
+    """Create Claude message_start SSE event."""
+    return sse(
+        "message_start",
+        {
+            "type": "message_start",
+            "message": {
+                "id": msg_id,
+                "type": "message",
+                "role": "assistant",
+                "content": [],
+                "model": model,
+                "stop_reason": None,
+                "stop_sequence": None,
+                "usage": {
+                    "input_tokens": input_tokens,
+                    "cache_creation_input_tokens": cache_creation_tokens,
+                    "cache_read_input_tokens": cache_read_tokens,
+                    "output_tokens": 0,
+                },
+            },
+        },
+    )
+
+
+def sse_ping() -> str:
+    """Create Claude ping SSE event."""
+    return sse("ping", {"type": "ping"})
+
+
+def sse_content_block_start(index: int, block: dict) -> str:
+    """Create Claude content_block_start SSE event."""
+    return sse(
+        "content_block_start",
+        {
+            "type": "content_block_start",
+            "index": index,
+            "content_block": block,
+        },
+    )
+
+
+def sse_content_block_delta(index: int, delta: dict) -> str:
+    """Create Claude content_block_delta SSE event."""
+    return sse(
+        "content_block_delta",
+        {"type": "content_block_delta", "index": index, "delta": delta},
+    )
+
+
+def sse_content_block_stop(index: int) -> str:
+    """Create Claude content_block_stop SSE event."""
+    return sse(
+        "content_block_stop",
+        {"type": "content_block_stop", "index": index},
+    )
+
+
+def sse_message_delta(
+    stop_reason: str,
+    output_tokens: int,
+    *,
+    input_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+    cache_read_tokens: int = 0,
+) -> str:
+    """Create Claude message_delta SSE event."""
+    return sse(
+        "message_delta",
+        {
+            "type": "message_delta",
+            "delta": {"stop_reason": stop_reason, "stop_sequence": None},
+            "usage": {
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "cache_creation_input_tokens": cache_creation_tokens,
+                "cache_read_input_tokens": cache_read_tokens,
+            },
+        },
+    )
+
+
+def sse_message_stop() -> str:
+    """Create Claude message_stop SSE event."""
+    return sse("message_stop", {"type": "message_stop"})
+
+
+def sse_error(error_type: str, message: str) -> str:
+    """Create Claude error SSE event."""
+    return sse(
+        "error",
+        {
+            "type": "error",
+            "error": {"type": error_type, "message": message},
+        },
+    )

app/core/config.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import os
+from typing import Optional
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings"""
+
+    # API Configuration
+    API_ENDPOINT: str = "https://chat.z.ai/api/v2/chat/completions"
+    
+    # Authentication
+    AUTH_TOKEN: Optional[str] = os.getenv("AUTH_TOKEN")
+
+    # Token池配置
+    TOKEN_FAILURE_THRESHOLD: int = int(
+        os.getenv("TOKEN_FAILURE_THRESHOLD", "3")
+    )
+    TOKEN_RECOVERY_TIMEOUT: int = int(
+        os.getenv("TOKEN_RECOVERY_TIMEOUT", "1800")
+    )
+    TOKEN_AUTO_IMPORT_ENABLED: bool = (
+        os.getenv("TOKEN_AUTO_IMPORT_ENABLED", "false").lower() == "true"
+    )
+    TOKEN_AUTO_IMPORT_SOURCE_DIR: str = os.getenv("TOKEN_AUTO_IMPORT_SOURCE_DIR", "")
+    TOKEN_AUTO_IMPORT_INTERVAL: int = int(
+        os.getenv("TOKEN_AUTO_IMPORT_INTERVAL", "300")
+    )
+    TOKEN_AUTO_MAINTENANCE_ENABLED: bool = (
+        os.getenv("TOKEN_AUTO_MAINTENANCE_ENABLED", "false").lower() == "true"
+    )
+    TOKEN_AUTO_MAINTENANCE_INTERVAL: int = int(
+        os.getenv("TOKEN_AUTO_MAINTENANCE_INTERVAL", "1800")
+    )
+    TOKEN_AUTO_REMOVE_DUPLICATES: bool = (
+        os.getenv("TOKEN_AUTO_REMOVE_DUPLICATES", "true").lower() == "true"
+    )
+    TOKEN_AUTO_HEALTH_CHECK: bool = (
+        os.getenv("TOKEN_AUTO_HEALTH_CHECK", "true").lower() == "true"
+    )
+    TOKEN_AUTO_DELETE_INVALID: bool = (
+        os.getenv("TOKEN_AUTO_DELETE_INVALID", "false").lower() == "true"
+    )
+
+    # Model Configuration
+    GLM45_MODEL: str = os.getenv("GLM45_MODEL", "GLM-4.5")
+    GLM45_THINKING_MODEL: str = os.getenv("GLM45_THINKING_MODEL", "GLM-4.5-Thinking")
+    GLM45_SEARCH_MODEL: str = os.getenv("GLM45_SEARCH_MODEL", "GLM-4.5-Search")
+    GLM45_AIR_MODEL: str = os.getenv("GLM45_AIR_MODEL", "GLM-4.5-Air")
+    GLM46V_MODEL: str = os.getenv("GLM46V_MODEL", "GLM-4.6V")
+    GLM5_MODEL: str = os.getenv("GLM5_MODEL", "GLM-5")
+    GLM47_MODEL: str = os.getenv("GLM47_MODEL", "GLM-4.7")
+    GLM47_THINKING_MODEL: str = os.getenv("GLM47_THINKING_MODEL", "GLM-4.7-Thinking")
+    GLM47_SEARCH_MODEL: str = os.getenv("GLM47_SEARCH_MODEL", "GLM-4.7-Search")
+    GLM47_ADVANCED_SEARCH_MODEL: str = os.getenv(
+        "GLM47_ADVANCED_SEARCH_MODEL",
+        "GLM-4.7-advanced-search",
+    )
+
+    # Server Configuration
+    LISTEN_PORT: int = int(os.getenv("LISTEN_PORT", "8080"))
+    DEBUG_LOGGING: bool = os.getenv("DEBUG_LOGGING", "true").lower() == "true"
+    SERVICE_NAME: str = os.getenv("SERVICE_NAME", "api-proxy-server")
+    ROOT_PATH: str = os.getenv("ROOT_PATH", "")
+
+    ANONYMOUS_MODE: bool = os.getenv("ANONYMOUS_MODE", "true").lower() == "true"
+    GUEST_POOL_SIZE: int = int(os.getenv("GUEST_POOL_SIZE", "3"))
+    TOOL_SUPPORT: bool = os.getenv("TOOL_SUPPORT", "true").lower() == "true"
+    SCAN_LIMIT: int = int(os.getenv("SCAN_LIMIT", "200000"))
+    SKIP_AUTH_TOKEN: bool = os.getenv("SKIP_AUTH_TOKEN", "false").lower() == "true"
+
+    # Proxy Configuration
+    HTTP_PROXY: Optional[str] = os.getenv("HTTP_PROXY")
+    HTTPS_PROXY: Optional[str] = os.getenv("HTTPS_PROXY")
+    SOCKS5_PROXY: Optional[str] = os.getenv("SOCKS5_PROXY")
+
+    # Admin Panel Authentication
+    ADMIN_PASSWORD: str = os.getenv("ADMIN_PASSWORD", "admin123")
+    SESSION_SECRET_KEY: str = os.getenv(
+        "SESSION_SECRET_KEY",
+        "your-secret-key-change-in-production",
+    )
+    DB_PATH: str = os.getenv("DB_PATH", "tokens.db")
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        extra="ignore",  # 忽略额外字段，防止环境变量中的未知字段导致验证错误
+    )
+
+
+settings = Settings()

app/core/openai.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import json
+import time
+from typing import Optional
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from app.core.config import settings
+from app.models.schemas import (
+    Choice,
+    Message,
+    Model,
+    ModelsResponse,
+    OpenAIRequest,
+    OpenAIResponse,
+    Usage,
+)
+from app.core.upstream import UpstreamClient
+from app.utils.logger import get_logger
+from app.utils.request_logging import (
+    extract_openai_usage,
+    wrap_openai_stream_with_logging,
+    write_request_log,
+)
+from app.utils.request_source import detect_request_source, format_request_source
+
+logger = get_logger()
+router = APIRouter()
+
+_upstream_client: Optional[UpstreamClient] = None
+
+
+def get_upstream_client() -> UpstreamClient:
+    """获取懒加载的上游适配器单例。"""
+    global _upstream_client
+    if _upstream_client is None:
+        _upstream_client = UpstreamClient()
+    return _upstream_client
+
+
+async def handle_non_stream_response(stream_response, request: OpenAIRequest) -> JSONResponse:
+    """处理非流式响应。"""
+    logger.info("📄 开始处理非流式响应")
+
+    full_content = []
+    async for chunk_data in stream_response():
+        if chunk_data.startswith("data: "):
+            chunk_str = chunk_data[6:].strip()
+            if chunk_str and chunk_str != "[DONE]":
+                try:
+                    chunk = json.loads(chunk_str)
+                    if "choices" in chunk and chunk["choices"]:
+                        choice = chunk["choices"][0]
+                        if "delta" in choice and "content" in choice["delta"]:
+                            content = choice["delta"]["content"]
+                            if content:
+                                full_content.append(content)
+                except json.JSONDecodeError:
+                    continue
+
+    response_data = OpenAIResponse(
+        id=f"chatcmpl-{int(time.time())}",
+        object="chat.completion",
+        created=int(time.time()),
+        model=request.model,
+        choices=[
+            Choice(
+                index=0,
+                message=Message(
+                    role="assistant",
+                    content="".join(full_content),
+                    tool_calls=None,
+                ),
+                finish_reason="stop",
+            )
+        ],
+        usage=Usage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+    )
+
+    logger.info("✅ 非流式响应处理完成")
+    return JSONResponse(content=response_data.model_dump(exclude_none=True))
+
+
+@router.get("/v1/models")
+async def list_models():
+    """返回当前服务支持的模型列表。"""
+    try:
+        client = get_upstream_client()
+        current_time = int(time.time())
+        response = ModelsResponse(
+            data=[
+                Model(id=model_id, created=current_time, owned_by=settings.SERVICE_NAME)
+                for model_id in client.get_supported_models()
+            ]
+        )
+        return JSONResponse(content=response.model_dump(exclude_none=True))
+    except Exception as exc:
+        logger.error(f"❌ 获取模型列表失败: {exc}")
+        raise HTTPException(status_code=500, detail=f"Failed to list models: {exc}")
+
+
+@router.post("/v1/chat/completions")
+async def chat_completions(
+    body: OpenAIRequest,
+    http_request: Request,
+    authorization: Optional[str] = Header(None),
+):
+    """直接调用上游适配器处理请求。"""
+    source_info = detect_request_source(
+        http_request,
+        protocol_hint="openai",
+        model_hint=body.model,
+    )
+    source_prefix = format_request_source(source_info)
+    started_at = time.perf_counter()
+
+    role = body.messages[0].role if body.messages else "unknown"
+    logger.info(
+        f"{source_prefix} 😶‍🌫️ 收到客户端请求 - 模型: {body.model}, 流式: {body.stream}, 消息数: {len(body.messages)}, 角色: {role}, 工具数: {len(body.tools) if body.tools else 0}"
+    )
+
+    try:
+        if not settings.SKIP_AUTH_TOKEN:
+            if not authorization or not authorization.startswith("Bearer "):
+                raise HTTPException(status_code=401, detail="Missing or invalid Authorization header")
+
+            api_key = authorization[7:]
+            if api_key != settings.AUTH_TOKEN:
+                raise HTTPException(status_code=401, detail="Invalid API key")
+
+        client = get_upstream_client()
+        result = await client.chat_completion(body)
+
+        if isinstance(result, dict) and "error" in result:
+            error_info = result["error"]
+            error_message = error_info.get("message", "Unknown upstream error")
+            error_code = error_info.get("code")
+            status_code = 404 if error_code == "model_not_found" else 500
+            raise HTTPException(status_code=status_code, detail=error_message)
+
+        if body.stream:
+            if hasattr(result, "__aiter__"):
+                return StreamingResponse(
+                    wrap_openai_stream_with_logging(
+                        result,
+                        provider="zai",
+                        model=body.model,
+                        source_info=source_info,
+                        started_at=started_at,
+                    ),
+                    media_type="text/event-stream",
+                    headers={
+                        "Cache-Control": "no-cache",
+                        "Connection": "keep-alive",
+                        "Access-Control-Allow-Origin": "*",
+                    },
+                )
+            raise HTTPException(
+                status_code=500,
+                detail="Expected streaming response but got non-streaming result",
+            )
+
+        if isinstance(result, dict):
+            usage = extract_openai_usage(result)
+            await write_request_log(
+                provider="zai",
+                model=body.model,
+                source_info=source_info,
+                success="error" not in result,
+                started_at=started_at,
+                status_code=200 if "error" not in result else 500,
+                input_tokens=usage["input_tokens"],
+                output_tokens=usage["output_tokens"],
+                cache_creation_tokens=usage["cache_creation_tokens"],
+                cache_read_tokens=usage["cache_read_tokens"],
+                total_tokens=usage["total_tokens"],
+                error_message=(result.get("error") or {}).get("message") if isinstance(result, dict) else None,
+            )
+            return JSONResponse(content=result)
+
+        response = await handle_non_stream_response(result, body)
+        response_body = json.loads(response.body)
+        usage = extract_openai_usage(response_body)
+        await write_request_log(
+            provider="zai",
+            model=body.model,
+            source_info=source_info,
+            success=True,
+            started_at=started_at,
+            status_code=200,
+            input_tokens=usage["input_tokens"],
+            output_tokens=usage["output_tokens"],
+            cache_creation_tokens=usage["cache_creation_tokens"],
+            cache_read_tokens=usage["cache_read_tokens"],
+            total_tokens=usage["total_tokens"],
+        )
+        return response
+
+    except HTTPException as exc:
+        await write_request_log(
+            provider="zai",
+            model=body.model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=exc.status_code,
+            error_message=str(exc.detail),
+        )
+        raise
+    except Exception as exc:
+        logger.error(f"{source_prefix} ❌ 请求处理失败: {exc}")
+        await write_request_log(
+            provider="zai",
+            model=body.model,
+            source_info=source_info,
+            success=False,
+            started_at=started_at,
+            status_code=500,
+            error_message=str(exc),
+        )
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(exc)}")

app/core/openai_compat.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""OpenAI 兼容响应辅助函数。"""
+
+import json
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+from app.utils.logger import get_logger
+
+logger = get_logger()
+SYSTEM_FINGERPRINT = "fp_api_proxy_001"
+
+
+def create_chat_id() -> str:
+    """生成聊天 ID。"""
+    return f"chatcmpl-{uuid.uuid4().hex}"
+
+
+def create_openai_chunk(
+    chat_id: str,
+    model: str,
+    delta: Dict[str, Any],
+    finish_reason: Optional[str] = None,
+) -> Dict[str, Any]:
+    """创建 OpenAI 格式的流式响应块。"""
+    return {
+        "id": chat_id,
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "delta": delta,
+                "finish_reason": finish_reason,
+                "logprobs": None,
+            }
+        ],
+        "system_fingerprint": SYSTEM_FINGERPRINT,
+    }
+
+
+def create_openai_response(
+    chat_id: str,
+    model: str,
+    content: str,
+    usage: Optional[Dict[str, int]] = None,
+) -> Dict[str, Any]:
+    """创建 OpenAI 格式的非流式响应。"""
+    return {
+        "id": chat_id,
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "message": {"role": "assistant", "content": content},
+                "finish_reason": "stop",
+                "logprobs": None,
+            }
+        ],
+        "usage": usage
+        or {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        },
+        "system_fingerprint": SYSTEM_FINGERPRINT,
+    }
+
+
+def create_openai_response_with_reasoning(
+    chat_id: str,
+    model: str,
+    content: str,
+    reasoning_content: Optional[str] = None,
+    usage: Optional[Dict[str, int]] = None,
+    tool_calls: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """创建包含 reasoning/tool_calls 的 OpenAI 响应。"""
+    message: Dict[str, Any] = {
+        "role": "assistant",
+        "content": content,
+    }
+
+    if reasoning_content and reasoning_content.strip():
+        message["reasoning_content"] = reasoning_content
+
+    if tool_calls:
+        message["tool_calls"] = tool_calls
+
+    return {
+        "id": chat_id,
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "message": message,
+                "finish_reason": "tool_calls" if tool_calls else "stop",
+                "logprobs": None,
+            }
+        ],
+        "usage": usage
+        or {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        },
+        "system_fingerprint": SYSTEM_FINGERPRINT,
+    }
+
+
+async def format_sse_chunk(chunk: Dict[str, Any]) -> str:
+    """格式化 SSE 响应块。"""
+    return f"data: {json.dumps(chunk, ensure_ascii=False)}\n\n"
+
+
+async def format_sse_done() -> str:
+    """格式化 SSE 结束标记。"""
+    return "data: [DONE]\n\n"
+
+
+def handle_error(error: Exception, context: str = "") -> Dict[str, Any]:
+    """统一错误处理。"""
+    error_msg = f"上游{context}错误: {str(error)}" if context else f"上游错误: {str(error)}"
+    logger.error(error_msg)
+    return {
+        "error": {
+            "message": error_msg,
+            "type": "upstream_error",
+            "code": "internal_error",
+        }
+    }

app/core/upstream.py

@@ -0,0 +1,2245 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""上游适配器。"""
+
+import asyncio
+import base64
+import json
+import random
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, AsyncGenerator, Dict, List, Optional, Set, Tuple, Union
+from urllib.parse import urlencode
+
+import httpx
+
+from app.core.config import settings
+from app.core.openai_compat import (
+    create_openai_chunk,
+    create_openai_response_with_reasoning,
+    format_sse_chunk,
+    handle_error,
+)
+from app.models.schemas import OpenAIRequest
+from app.utils.fe_version import get_latest_fe_version
+from app.utils.guest_session_pool import get_guest_session_pool
+from app.utils.logger import get_logger
+from app.utils.signature import generate_signature
+from app.utils.token_pool import get_token_pool
+from app.utils.tool_call_handler import (
+    parse_and_extract_tool_calls,
+)
+from app.utils.user_agent import get_random_user_agent
+
+logger = get_logger()
+
+DEFAULT_ZAI_BASE_URL = "https://chat.z.ai"
+CHAT_BOOTSTRAP_MAX_CONTENT_LEN = 500
+DEFAULT_PLATFORM = "web"
+DEFAULT_CLIENT_VERSION = "0.0.1"
+DEFAULT_TIMEZONE = "Asia/Shanghai"
+DEFAULT_LANGUAGE = "zh-CN"
+DEFAULT_SCREEN_WIDTH = "1920"
+DEFAULT_SCREEN_HEIGHT = "1080"
+DEFAULT_VIEWPORT_WIDTH = "944"
+DEFAULT_VIEWPORT_HEIGHT = "919"
+DEFAULT_VIEWPORT_SIZE = f"{DEFAULT_VIEWPORT_WIDTH}x{DEFAULT_VIEWPORT_HEIGHT}"
+DEFAULT_SCREEN_RESOLUTION = f"{DEFAULT_SCREEN_WIDTH}x{DEFAULT_SCREEN_HEIGHT}"
+DEFAULT_COLOR_DEPTH = "24"
+DEFAULT_PIXEL_RATIO = "1.25"
+DEFAULT_MAX_TOUCH_POINTS = "10"
+DEFAULT_TIMEZONE_OFFSET = "-480"
+DEFAULT_PAGE_TITLE = "Z.ai Chat Proxy"
+DEFAULT_COMPLETION_FEATURES = [
+    {"type": "mcp", "server": "vibe-coding", "status": "hidden"},
+    {"type": "mcp", "server": "ppt-maker", "status": "hidden"},
+    {"type": "mcp", "server": "image-search", "status": "hidden"},
+    {"type": "mcp", "server": "deep-research", "status": "hidden"},
+    {"type": "tool_selector", "server": "tool_selector", "status": "hidden"},
+    {"type": "mcp", "server": "advanced-search", "status": "hidden"},
+]
+GLM46V_MCP_SERVERS = [
+    "vlm-image-search",
+    "vlm-image-recognition",
+    "vlm-image-processing",
+]
+GLM46V_SELECTED_FEATURES = [
+    {"type": "mcp", "server": "vlm-image-search", "status": "selected"},
+    {"type": "mcp", "server": "vlm-image-recognition", "status": "selected"},
+    {"type": "mcp", "server": "vlm-image-processing", "status": "selected"},
+]
+
+def generate_uuid() -> str:
+    """生成UUID v4"""
+    return str(uuid.uuid4())
+
+def get_dynamic_headers(
+    chat_id: str = "",
+    browser_type: Optional[str] = None,
+) -> Dict[str, str]:
+    """生成上游请求所需的动态浏览器 headers。"""
+    browser_choices = [
+        "chrome",
+        "chrome",
+        "chrome",
+        "edge",
+        "edge",
+        "firefox",
+        "safari",
+    ]
+    selected_browser = browser_type or random.choice(browser_choices)
+    user_agent = get_random_user_agent(selected_browser)
+    fe_version = get_latest_fe_version()
+
+    chrome_version = "139"
+    edge_version = "139"
+
+    if "Chrome/" in user_agent:
+        try:
+            chrome_version = user_agent.split("Chrome/")[1].split(".")[0]
+        except Exception:
+            pass
+
+    if "Edg/" in user_agent:
+        try:
+            edge_version = user_agent.split("Edg/")[1].split(".")[0]
+            sec_ch_ua = (
+                f'"Microsoft Edge";v="{edge_version}", '
+                f'"Chromium";v="{chrome_version}", "Not_A Brand";v="24"'
+            )
+        except Exception:
+            sec_ch_ua = (
+                f'"Not_A Brand";v="8", "Chromium";v="{chrome_version}", '
+                f'"Google Chrome";v="{chrome_version}"'
+            )
+    elif "Firefox/" in user_agent:
+        sec_ch_ua = None
+    else:
+        sec_ch_ua = (
+            f'"Not_A Brand";v="8", "Chromium";v="{chrome_version}", '
+            f'"Google Chrome";v="{chrome_version}"'
+        )
+
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        "Connection": "keep-alive",
+        "Cache-Control": "no-cache",
+        "User-Agent": user_agent,
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "X-FE-Version": fe_version,
+        "Origin": "https://chat.z.ai",
+    }
+
+    if sec_ch_ua:
+        headers["sec-ch-ua"] = sec_ch_ua
+        headers["sec-ch-ua-mobile"] = "?0"
+        headers["sec-ch-ua-platform"] = '"Windows"'
+
+    if chat_id:
+        headers["Referer"] = f"https://chat.z.ai/c/{chat_id}"
+    else:
+        headers["Referer"] = "https://chat.z.ai/"
+
+    return headers
+
+def _urlsafe_b64decode(data: str) -> bytes:
+    """Decode a URL-safe base64 string with proper padding."""
+    if isinstance(data, str):
+        data_bytes = data.encode("utf-8")
+    else:
+        data_bytes = data
+    padding = b"=" * (-len(data_bytes) % 4)
+    return base64.urlsafe_b64decode(data_bytes + padding)
+
+
+def _decode_jwt_payload(token: str) -> Dict[str, Any]:
+    """Decode JWT payload without verification to extract metadata."""
+    try:
+        parts = token.split(".")
+        if len(parts) < 2:
+            return {}
+        payload_raw = _urlsafe_b64decode(parts[1])
+        return json.loads(payload_raw.decode("utf-8", errors="ignore"))
+    except Exception:
+        return {}
+
+
+def _extract_user_id_from_token(token: str) -> str:
+    """Extract user_id from a JWT's payload. Fallback to 'guest'."""
+    payload = _decode_jwt_payload(token) if token else {}
+    for key in ("id", "user_id", "uid", "sub"):
+        val = payload.get(key)
+        if isinstance(val, (str, int)) and str(val):
+            return str(val)
+    return "guest"
+
+
+def _extract_text_from_content(content: Any) -> str:
+    """Extract text parts from OpenAI-compatible content payloads."""
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        parts: List[str] = []
+        for item in content:
+            if isinstance(item, dict) and item.get("type") == "text":
+                parts.append(str(item.get("text", "")))
+        return " ".join(part for part in parts if part).strip()
+
+    if content is None:
+        return ""
+
+    try:
+        return json.dumps(content, ensure_ascii=False)
+    except Exception:
+        return str(content)
+
+
+def _stringify_tool_arguments(arguments: Any) -> str:
+    """Normalize tool-call arguments into a JSON string."""
+    if isinstance(arguments, str):
+        return arguments
+
+    try:
+        return json.dumps(arguments or {}, ensure_ascii=False)
+    except Exception:
+        return "{}"
+
+
+def _build_tool_call_index(
+    messages: List[Dict[str, Any]],
+) -> Dict[str, Dict[str, str]]:
+    """Index assistant tool calls by id for later tool-result messages."""
+    index: Dict[str, Dict[str, str]] = {}
+
+    for message in messages:
+        if message.get("role") != "assistant":
+            continue
+
+        tool_calls = message.get("tool_calls")
+        if not isinstance(tool_calls, list):
+            continue
+
+        for tool_call in tool_calls:
+            if not isinstance(tool_call, dict):
+                continue
+
+            tool_call_id = tool_call.get("id")
+            function_data = (
+                tool_call.get("function")
+                if isinstance(tool_call.get("function"), dict)
+                else {}
+            )
+            name = str(function_data.get("name", "")).strip()
+            if not isinstance(tool_call_id, str) or not name:
+                continue
+
+            index[tool_call_id] = {
+                "name": name,
+                "arguments": _stringify_tool_arguments(
+                    function_data.get("arguments")
+                ),
+            }
+
+    return index
+
+
+def _format_tool_result_message(
+    tool_name: str,
+    tool_arguments: str,
+    result_content: str,
+) -> str:
+    """Serialize a tool result into a text block the upstream can consume."""
+    return (
+        "<tool_execution_result>\n"
+        f"<tool_name>{tool_name}</tool_name>\n"
+        f"<tool_arguments>{tool_arguments}</tool_arguments>\n"
+        f"<tool_output>{result_content}</tool_output>\n"
+        "</tool_execution_result>"
+    )
+
+
+def _format_assistant_tool_calls(tool_calls: List[Dict[str, Any]]) -> str:
+    """Serialize historical assistant tool calls into a text block."""
+    blocks: List[str] = []
+
+    for tool_call in tool_calls:
+        if not isinstance(tool_call, dict):
+            continue
+
+        function_data = (
+            tool_call.get("function")
+            if isinstance(tool_call.get("function"), dict)
+            else {}
+        )
+        name = str(function_data.get("name", "")).strip()
+        if not name:
+            continue
+
+        arguments = _stringify_tool_arguments(function_data.get("arguments"))
+        blocks.append(
+            "<function_call>\n"
+            f"<name>{name}</name>\n"
+            f"<args_json>{arguments}</args_json>\n"
+            "</function_call>"
+        )
+
+    if not blocks:
+        return ""
+
+    return "<function_calls>\n" + "\n".join(blocks) + "\n</function_calls>"
+
+
+def _preprocess_openai_messages(
+    messages: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Normalize OpenAI history into shapes accepted by the upstream service."""
+    tool_call_index = _build_tool_call_index(messages)
+    normalized: List[Dict[str, Any]] = []
+
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+
+        role = message.get("role")
+
+        if role == "developer":
+            converted = dict(message)
+            converted["role"] = "system"
+            normalized.append(converted)
+            continue
+
+        if role == "tool":
+            tool_call_id = message.get("tool_call_id")
+            content = _extract_text_from_content(message.get("content"))
+            tool_info = tool_call_index.get(
+                tool_call_id,
+                {
+                    "name": str(message.get("name") or "unknown_tool"),
+                    "arguments": "{}",
+                },
+            )
+            normalized.append(
+                {
+                    "role": "user",
+                    "content": _format_tool_result_message(
+                        tool_info["name"],
+                        tool_info["arguments"],
+                        content,
+                    ),
+                }
+            )
+            continue
+
+        if role == "assistant" and isinstance(message.get("tool_calls"), list):
+            content = _extract_text_from_content(message.get("content"))
+            tool_calls_text = _format_assistant_tool_calls(message["tool_calls"])
+            merged_content = "\n".join(
+                part for part in (content, tool_calls_text) if part
+            ).strip()
+            normalized.append({"role": "assistant", "content": merged_content})
+            continue
+
+        normalized.append(dict(message))
+
+    return normalized
+
+
+def _extract_last_user_text(messages: List[Dict[str, Any]]) -> str:
+    """Extract the last user text from the original OpenAI message history."""
+    for message in reversed(messages):
+        if message.get("role") != "user":
+            continue
+        content = _extract_text_from_content(message.get("content"))
+        if content:
+            return content
+    return ""
+
+
+
+class UpstreamClient:
+    """当前服务使用的上游适配器。"""
+
+    def __init__(self):
+        self.name = "upstream"
+        self.logger = logger
+        self.api_endpoint = settings.API_ENDPOINT
+
+        # 当前上游特定配置
+        self.base_url = DEFAULT_ZAI_BASE_URL
+        self.auth_url = f"{self.base_url}/api/v1/auths/"
+        
+        # 模型映射
+        self.model_mapping = {
+            settings.GLM45_MODEL: "0727-360B-API",  # GLM-4.5
+            settings.GLM45_THINKING_MODEL: "0727-360B-API",  # GLM-4.5-Thinking
+            settings.GLM45_SEARCH_MODEL: "0727-360B-API",  # GLM-4.5-Search
+            settings.GLM45_AIR_MODEL: "0727-106B-API",  # GLM-4.5-Air
+            settings.GLM46V_MODEL: "glm-4.6v",  # GLM-4.6V多模态
+            settings.GLM5_MODEL: "glm-5",  # GLM-5
+            settings.GLM47_MODEL: "glm-4.7",  # GLM-4.7
+            settings.GLM47_THINKING_MODEL: "glm-4.7",  # GLM-4.7-Thinking
+            settings.GLM47_SEARCH_MODEL: "glm-4.7",  # GLM-4.7-Search
+            settings.GLM47_ADVANCED_SEARCH_MODEL: "glm-4.7",  # GLM-4.7-advanced-search
+        }
+
+    def _get_guest_retry_limit(self) -> int:
+        """匿名号池可提供的最大重试预算。"""
+        if not settings.ANONYMOUS_MODE:
+            return 0
+
+        guest_pool = get_guest_session_pool()
+        if not guest_pool:
+            return max(2, settings.GUEST_POOL_SIZE + 1)
+
+        pool_status = guest_pool.get_pool_status()
+        available_sessions = int(
+            pool_status.get("valid_sessions")
+            or pool_status.get("available_sessions")
+            or 0
+        )
+        return max(2, available_sessions + 1)
+
+    def _get_authenticated_retry_limit(self) -> int:
+        """认证号池与静态 Token 可提供的最大重试预算。"""
+        available_tokens = 0
+        token_pool = get_token_pool()
+        if token_pool:
+            available_tokens = int(
+                token_pool.get_pool_status().get("available_tokens", 0) or 0
+            )
+
+        return max(0, available_tokens)
+
+    def _get_total_retry_limit(self) -> int:
+        """综合认证号池与匿名号池的最大尝试次数。"""
+        return max(
+            1,
+            self._get_authenticated_retry_limit() + self._get_guest_retry_limit(),
+        )
+
+    def _is_guest_auth(self, transformed: Dict[str, Any]) -> bool:
+        """判断当前请求是否使用匿名会话。"""
+        return str(transformed.get("auth_mode") or "") == "guest"
+
+    def _should_retry_guest_session(
+        self,
+        status_code: int,
+        is_concurrency_limited: bool,
+        attempt: int,
+        max_attempts: int,
+        transformed: Dict[str, Any],
+    ) -> bool:
+        """判断匿名号池是否需要刷新会话后重试。"""
+        return (
+            self._is_guest_auth(transformed)
+            and (status_code == 401 or is_concurrency_limited)
+            and attempt + 1 < max_attempts
+        )
+
+    def _should_retry_authenticated_session(
+        self,
+        status_code: int,
+        is_concurrency_limited: bool,
+        attempt: int,
+        max_attempts: int,
+        transformed: Dict[str, Any],
+    ) -> bool:
+        """判断认证号池是否需要切号重试。"""
+        current_token = str(transformed.get("token") or "")
+        return (
+            not self._is_guest_auth(transformed)
+            and bool(current_token)
+            and (status_code == 401 or is_concurrency_limited)
+            and attempt + 1 < max_attempts
+        )
+
+    async def _release_guest_session(self, transformed: Dict[str, Any]):
+        """释放当前匿名会话占用。"""
+        if not self._is_guest_auth(transformed):
+            return
+
+        guest_pool = get_guest_session_pool()
+        guest_user_id = str(
+            transformed.get("guest_user_id") or transformed.get("user_id") or ""
+        )
+        if guest_pool and guest_user_id:
+            guest_pool.release(guest_user_id)
+
+    async def _report_guest_session_failure(
+        self,
+        transformed: Dict[str, Any],
+        *,
+        is_concurrency_limited: bool = False,
+    ):
+        """上报匿名会话失败并补齐新会话。"""
+        if not self._is_guest_auth(transformed):
+            return
+
+        guest_pool = get_guest_session_pool()
+        guest_user_id = str(
+            transformed.get("guest_user_id") or transformed.get("user_id") or ""
+        )
+        if not guest_pool or not guest_user_id:
+            return
+
+        if is_concurrency_limited:
+            await guest_pool.cleanup_idle_chats()
+
+        await guest_pool.report_failure(guest_user_id)
+
+    async def _refresh_guest_request(
+        self,
+        request: OpenAIRequest,
+        attempt: int,
+        excluded_tokens: Set[str],
+        excluded_guest_user_ids: Set[str],
+        failed_transformed: Dict[str, Any],
+        is_concurrency_limited: bool = False,
+    ) -> Dict[str, Any]:
+        """匿名会话失效或并发受限后切换会话并重签请求。"""
+        retry_number = attempt + 2
+        self.logger.warning(
+            "🔄 匿名会话不可用，正在切换匿名会话并进行第 "
+            f"{retry_number} 次请求"
+        )
+        await self._report_guest_session_failure(
+            failed_transformed,
+            is_concurrency_limited=is_concurrency_limited,
+        )
+        return await self.transform_request(
+            request,
+            excluded_tokens=excluded_tokens,
+            excluded_guest_user_ids=excluded_guest_user_ids,
+        )
+
+    async def _refresh_authenticated_request(
+        self,
+        request: OpenAIRequest,
+        attempt: int,
+        excluded_tokens: Set[str],
+        excluded_guest_user_ids: Set[str],
+    ) -> Dict[str, Any]:
+        """认证模式下切换到下一枚 Token，并允许回退匿名池。"""
+        retry_number = attempt + 2
+        self.logger.warning(
+            "🔄 检测到认证会话不可用，正在切换认证 Token/回退匿名池并进行第 "
+            f"{retry_number} 次请求"
+        )
+        return await self.transform_request(
+            request,
+            excluded_tokens=excluded_tokens,
+            excluded_guest_user_ids=excluded_guest_user_ids,
+        )
+
+    def _extract_upstream_error_details(
+        self,
+        status_code: int,
+        error_text: str,
+    ) -> Tuple[Optional[int], str]:
+        """解析上游错误响应中的 code/message。"""
+        parsed_code: Optional[int] = None
+        parsed_message = (error_text or "").strip()
+
+        try:
+            payload = json.loads(error_text)
+        except Exception:
+            return parsed_code, parsed_message
+
+        if not isinstance(payload, dict):
+            return parsed_code, parsed_message
+
+        candidates = [
+            payload,
+            payload.get("error") if isinstance(payload.get("error"), dict) else None,
+            payload.get("detail") if isinstance(payload.get("detail"), dict) else None,
+            payload.get("data") if isinstance(payload.get("data"), dict) else None,
+        ]
+
+        for candidate in candidates:
+            if not isinstance(candidate, dict):
+                continue
+
+            code = candidate.get("code")
+            if isinstance(code, int):
+                parsed_code = code
+            elif isinstance(code, str) and code.isdigit():
+                parsed_code = int(code)
+
+            for key in ("message", "msg", "detail", "error"):
+                value = candidate.get(key)
+                if isinstance(value, str) and value.strip():
+                    parsed_message = value.strip()
+                    break
+
+            if parsed_code is not None or parsed_message:
+                break
+
+        return parsed_code, parsed_message
+
+    def _is_concurrency_limited(
+        self,
+        status_code: int,
+        error_code: Optional[int],
+        error_message: str,
+    ) -> bool:
+        """判断是否为上游并发限制/429 场景。"""
+        message = (error_message or "").casefold()
+        return (
+            status_code == 429
+            or error_code == 429
+            or "concurrency" in message
+            or "too many requests" in message
+            or "并发" in error_message
+        )
+    
+    def get_supported_models(self) -> List[str]:
+        """获取支持的模型列表"""
+        return [
+            settings.GLM45_MODEL,
+            settings.GLM45_THINKING_MODEL,
+            settings.GLM45_SEARCH_MODEL,
+            settings.GLM45_AIR_MODEL,
+            settings.GLM46V_MODEL,
+            settings.GLM5_MODEL,
+            settings.GLM47_MODEL,
+            settings.GLM47_THINKING_MODEL,
+            settings.GLM47_SEARCH_MODEL,
+            settings.GLM47_ADVANCED_SEARCH_MODEL,
+        ]
+
+    def _requires_persisted_chat(self, upstream_model_id: str) -> bool:
+        """需要挂载真实 chat 会话的上游模型。"""
+        return bool(
+            self._get_model_request_profile(upstream_model_id)["use_persisted_chat"]
+        )
+
+    def _get_model_request_profile(self, upstream_model_id: str) -> Dict[str, Any]:
+        """返回模型专属的请求配置。"""
+        if upstream_model_id == "glm-4.6v":
+            return {
+                "use_persisted_chat": True,
+                "preview_mode": False,
+                "mcp_servers": list(GLM46V_MCP_SERVERS),
+                "feature_entries": [dict(item) for item in GLM46V_SELECTED_FEATURES],
+                "default_enable_thinking": True,
+            }
+
+        if upstream_model_id == "glm-5":
+            return {
+                "use_persisted_chat": False,
+                "preview_mode": True,
+                "mcp_servers": [],
+                "feature_entries": [],
+                "default_enable_thinking": True,
+            }
+
+        return {
+            "use_persisted_chat": upstream_model_id == "glm-4.7",
+            "preview_mode": True,
+            "mcp_servers": [],
+            "feature_entries": [],
+            "default_enable_thinking": None,
+        }
+
+    def _build_request_variables(self) -> Dict[str, str]:
+        """构建上游请求需要的运行时变量。"""
+        now = datetime.now()
+        return {
+            "{{USER_NAME}}": "Guest",
+            "{{USER_LOCATION}}": "Unknown",
+            "{{CURRENT_DATETIME}}": now.strftime("%Y-%m-%d %H:%M:%S"),
+            "{{CURRENT_DATE}}": now.strftime("%Y-%m-%d"),
+            "{{CURRENT_TIME}}": now.strftime("%H:%M:%S"),
+            "{{CURRENT_WEEKDAY}}": now.strftime("%A"),
+            "{{CURRENT_TIMEZONE}}": DEFAULT_TIMEZONE,
+            "{{USER_LANGUAGE}}": DEFAULT_LANGUAGE,
+        }
+
+    def _build_browser_query_params(
+        self,
+        *,
+        chat_id: str,
+        token: str,
+        user_id: str,
+        user_agent: str,
+        timestamp_ms: int,
+    ) -> Dict[str, str]:
+        """构建 GLM-4.7 所需的浏览器指纹查询参数。"""
+        now = datetime.now(timezone.utc)
+        browser_name = "Chrome"
+        if "Edg/" in user_agent:
+            browser_name = "Microsoft Edge"
+        elif "Firefox/" in user_agent:
+            browser_name = "Firefox"
+        elif "Safari/" in user_agent and "Chrome/" not in user_agent:
+            browser_name = "Safari"
+
+        return {
+            "version": DEFAULT_CLIENT_VERSION,
+            "platform": DEFAULT_PLATFORM,
+            "token": token,
+            "user_agent": user_agent,
+            "language": DEFAULT_LANGUAGE,
+            "languages": DEFAULT_LANGUAGE,
+            "timezone": DEFAULT_TIMEZONE,
+            "cookie_enabled": "true",
+            "screen_width": DEFAULT_SCREEN_WIDTH,
+            "screen_height": DEFAULT_SCREEN_HEIGHT,
+            "screen_resolution": DEFAULT_SCREEN_RESOLUTION,
+            "viewport_height": DEFAULT_VIEWPORT_HEIGHT,
+            "viewport_width": DEFAULT_VIEWPORT_WIDTH,
+            "viewport_size": DEFAULT_VIEWPORT_SIZE,
+            "color_depth": DEFAULT_COLOR_DEPTH,
+            "pixel_ratio": DEFAULT_PIXEL_RATIO,
+            "current_url": f"{self.base_url}/c/{chat_id}",
+            "pathname": f"/c/{chat_id}",
+            "search": "",
+            "hash": "",
+            "host": "chat.z.ai",
+            "hostname": "chat.z.ai",
+            "protocol": "https:",
+            "referrer": "",
+            "title": DEFAULT_PAGE_TITLE,
+            "timezone_offset": DEFAULT_TIMEZONE_OFFSET,
+            "local_time": (
+                now.strftime("%Y-%m-%dT%H:%M:%S.")
+                + f"{now.microsecond // 1000:03d}Z"
+            ),
+            "utc_time": now.strftime("%a, %d %b %Y %H:%M:%S GMT"),
+            "is_mobile": "false",
+            "is_touch": "false",
+            "max_touch_points": DEFAULT_MAX_TOUCH_POINTS,
+            "browser_name": browser_name,
+            "os_name": "Windows",
+            "signature_timestamp": str(timestamp_ms),
+        }
+
+    def _build_signed_completion_request(
+        self,
+        *,
+        prompt: str,
+        chat_id: str,
+        token: str,
+        user_id: str,
+        user_agent: str,
+        use_browser_fingerprint: bool,
+    ) -> Tuple[str, str, str]:
+        """构建上游 completions 的签名 URL 与请求头元数据。"""
+        timestamp_ms = int(time.time() * 1000)
+        request_id = generate_uuid()
+        core_params = {
+            "requestId": request_id,
+            "timestamp": str(timestamp_ms),
+            "user_id": user_id,
+        }
+        canonical_payload = ",".join(
+            f"{key},{value}" for key, value in sorted(core_params.items())
+        )
+        signature = generate_signature(
+            e=canonical_payload,
+            t=prompt or "",
+            s=timestamp_ms,
+        )["signature"]
+        query_params = dict(core_params)
+        if use_browser_fingerprint:
+            query_params.update(
+                self._build_browser_query_params(
+                    chat_id=chat_id,
+                    token=token,
+                    user_id=user_id,
+                    user_agent=user_agent,
+                    timestamp_ms=timestamp_ms,
+                )
+            )
+        else:
+            query_params.update(
+                {
+                    "token": token,
+                    "version": DEFAULT_CLIENT_VERSION,
+                    "platform": DEFAULT_PLATFORM,
+                    "current_url": f"{self.base_url}/c/{chat_id}",
+                    "pathname": f"/c/{chat_id}",
+                    "signature_timestamp": str(timestamp_ms),
+                }
+            )
+
+        return (
+            f"{self.api_endpoint}?{urlencode(query_params)}",
+            signature,
+            str(timestamp_ms),
+        )
+
+    async def _create_upstream_chat(
+        self,
+        *,
+        prompt: str,
+        model: str,
+        token: str,
+        headers: Dict[str, str],
+        enable_thinking: bool,
+        web_search: bool,
+        user_message_id: Optional[str] = None,
+        files: Optional[List[Dict[str, Any]]] = None,
+        feature_entries: Optional[List[Dict[str, Any]]] = None,
+        mcp_servers: Optional[List[str]] = None,
+    ) -> str:
+        """为 GLM-4.7 系列创建上游真实 chat 会话。"""
+        init_content = prompt[:CHAT_BOOTSTRAP_MAX_CONTENT_LEN]
+        if len(prompt) > CHAT_BOOTSTRAP_MAX_CONTENT_LEN:
+            init_content = init_content + "..."
+
+        message_id = user_message_id or generate_uuid()
+        timestamp_seconds = int(time.time())
+        chat_features = (
+            [dict(item) for item in feature_entries]
+            if feature_entries
+            else [
+                {
+                    "type": "tool_selector",
+                    "server": "tool_selector_h",
+                    "status": "hidden",
+                }
+            ]
+        )
+        body = {
+            "chat": {
+                "id": "",
+                "title": "新聊天",
+                "models": [model],
+                "params": {},
+                "history": {
+                    "messages": {
+                        message_id: {
+                            "id": message_id,
+                            "parentId": None,
+                            "childrenIds": [],
+                            "role": "user",
+                            "content": init_content,
+                            **({"files": [dict(item) for item in files]} if files else {}),
+                            "timestamp": timestamp_seconds,
+                            "models": [model],
+                        }
+                    },
+                    "currentId": message_id,
+                },
+                "tags": [],
+                "flags": [],
+                "features": chat_features,
+                "mcp_servers": list(mcp_servers or []),
+                "enable_thinking": enable_thinking,
+                "auto_web_search": web_search,
+                "message_version": 1,
+                "extra": {},
+                "timestamp": int(time.time() * 1000),
+            }
+        }
+        request_headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": headers["User-Agent"],
+            "Accept-Language": headers.get("Accept-Language", DEFAULT_LANGUAGE),
+            "Origin": self.base_url,
+            "Referer": f"{self.base_url}/",
+        }
+        async with httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self._build_timeout(),
+            limits=self._build_limits(),
+            proxy=self._get_proxy_config(),
+            follow_redirects=True,
+        ) as client:
+            response = await client.post(
+                "/api/v1/chats/new",
+                headers=request_headers,
+                json=body,
+            )
+
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"上游创建 chat 失败: {response.status_code} {response.text}"
+            )
+
+        payload = response.json()
+        chat_id = str(payload.get("id") or payload.get("chat", {}).get("id") or "")
+        if not chat_id:
+            raise RuntimeError("上游创建 chat 成功但未返回 chat_id")
+        return chat_id
+
+    def _build_glm47_completion_body(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        prompt: str,
+        chat_id: str,
+        enable_thinking: bool,
+        web_search: bool,
+        files: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]],
+        tool_choice: Any,
+        temperature: Optional[float],
+        max_tokens: Optional[int],
+        mcp_servers: List[str],
+        preview_mode: bool,
+        feature_entries: Optional[List[Dict[str, Any]]],
+        message_id: str,
+        current_user_message_id: str,
+        current_user_message_parent_id: Optional[str],
+    ) -> Dict[str, Any]:
+        """构建兼容持久化 chat 模型的精简 completions 请求体。"""
+        params: Dict[str, Any] = {}
+        if temperature is not None:
+            params["temperature"] = temperature
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+
+        body: Dict[str, Any] = {
+            "stream": True,
+            "model": model,
+            "messages": messages,
+            "signature_prompt": prompt,
+            "params": params,
+            "extra": {},
+            "features": {
+                "image_generation": False,
+                "web_search": web_search,
+                "auto_web_search": web_search,
+                "preview_mode": preview_mode,
+                "flags": [],
+                "enable_thinking": enable_thinking,
+            },
+            "variables": self._build_request_variables(),
+            "chat_id": chat_id,
+            "id": message_id,
+            "current_user_message_id": current_user_message_id,
+            "current_user_message_parent_id": current_user_message_parent_id,
+            "background_tasks": {
+                "title_generation": True,
+                "tags_generation": True,
+            },
+        }
+        if files:
+            body["files"] = files
+        if mcp_servers:
+            body["mcp_servers"] = mcp_servers
+        if tools:
+            body["tools"] = tools
+            if tool_choice is not None:
+                body["tool_choice"] = tool_choice
+        return body
+
+    def _clean_reasoning_delta(self, delta_content: str) -> str:
+        """清理思考阶段的 details 包裹内容。"""
+        if not delta_content:
+            return ""
+
+        if delta_content.startswith("<details"):
+            if "</summary>\n>" in delta_content:
+                return delta_content.split("</summary>\n>")[-1].strip()
+            if "</summary>\n" in delta_content:
+                return delta_content.split("</summary>\n")[-1].lstrip("> ").strip()
+
+        return delta_content
+
+    def _extract_answer_content(self, text: str) -> str:
+        """提取思考结束后的答案正文。"""
+        if not text:
+            return ""
+
+        if "</details>\n" in text:
+            return text.split("</details>\n")[-1]
+
+        if "</details>" in text:
+            return text.split("</details>")[-1].lstrip()
+
+        return text
+
+    def _normalize_tool_calls(
+        self,
+        raw_tool_calls: Any,
+        start_index: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """标准化上游工具调用为 OpenAI 兼容格式。"""
+        if not raw_tool_calls:
+            return []
+
+        tool_calls = raw_tool_calls if isinstance(raw_tool_calls, list) else [raw_tool_calls]
+        normalized: List[Dict[str, Any]] = []
+
+        for offset, tool_call in enumerate(tool_calls):
+            if not isinstance(tool_call, dict):
+                continue
+
+            function_data = tool_call.get("function") or {}
+            normalized.append(
+                {
+                    "index": tool_call.get("index", start_index + offset),
+                    "id": tool_call.get("id") or f"call_{uuid.uuid4().hex[:24]}",
+                    "type": "function",
+                    "function": {
+                        "name": function_data.get("name", ""),
+                        "arguments": function_data.get("arguments", ""),
+                    },
+                }
+            )
+
+        return normalized
+
+    def _format_search_results(self, data: Dict[str, Any]) -> str:
+        """将上游搜索结果格式化为可追加的 Markdown 引用。"""
+        search_info = data.get("results") or data.get("sources") or data.get("citations")
+        if not isinstance(search_info, list) or not search_info:
+            return ""
+
+        citations = []
+        for index, item in enumerate(search_info, 1):
+            if not isinstance(item, dict):
+                continue
+
+            title = item.get("title") or item.get("name") or f"Result {index}"
+            url = item.get("url") or item.get("link")
+            if url:
+                citations.append(f"[{index}] [{title}]({url})")
+
+        if not citations:
+            return ""
+
+        return "\n\n---\n" + "\n".join(citations)
+
+    def _get_proxy_config(self) -> Optional[str]:
+        """Get proxy configuration from settings"""
+        # In httpx 0.28.1, proxy parameter expects a single URL string
+        # Support HTTP_PROXY, HTTPS_PROXY and SOCKS5_PROXY
+        
+        if settings.HTTPS_PROXY:
+            self.logger.info(f"🔄 使用HTTPS代理: {settings.HTTPS_PROXY}")
+            return settings.HTTPS_PROXY
+            
+        if settings.HTTP_PROXY:
+            self.logger.info(f"🔄 使用HTTP代理: {settings.HTTP_PROXY}")
+            return settings.HTTP_PROXY
+            
+        if settings.SOCKS5_PROXY:
+            self.logger.info(f"🔄 使用SOCKS5代理: {settings.SOCKS5_PROXY}")
+            return settings.SOCKS5_PROXY
+
+        return None
+
+    def _build_timeout(self, read_timeout: float = 30.0) -> httpx.Timeout:
+        """Create httpx timeout settings tuned for upstream chat traffic."""
+        return httpx.Timeout(
+            connect=5.0,
+            read=read_timeout,
+            write=10.0,
+            pool=5.0,
+        )
+
+    def _build_limits(self) -> httpx.Limits:
+        """Create conservative connection-pool limits for upstream requests."""
+        return httpx.Limits(
+            max_keepalive_connections=5,
+            max_connections=10,
+        )
+
+    async def _fetch_direct_guest_auth(self) -> Dict[str, Any]:
+        """匿名号池缺席时，兜底直连拉取一个访客令牌。"""
+        max_retries = 3
+
+        for retry_count in range(max_retries):
+            try:
+                headers = get_dynamic_headers()
+                self.logger.debug(
+                    f"尝试获取访客令牌 (第{retry_count + 1}次): {self.auth_url}"
+                )
+
+                proxies = self._get_proxy_config()
+                async with httpx.AsyncClient(
+                    timeout=self._build_timeout(),
+                    follow_redirects=True,
+                    limits=self._build_limits(),
+                    proxy=proxies,
+                ) as client:
+                    response = await client.get(self.auth_url, headers=headers)
+
+                if response.status_code == 200:
+                    data = response.json()
+                    token = str(data.get("token") or "").strip()
+                    if token:
+                        user_id = str(
+                            data.get("id")
+                            or data.get("user_id")
+                            or _extract_user_id_from_token(token)
+                        )
+                        username = str(
+                            data.get("name")
+                            or str(data.get("email") or "").split("@")[0]
+                            or "Guest"
+                        )
+                        self.logger.info(
+                            f"✅ 直连获取匿名令牌成功: {token[:20]}..."
+                        )
+                        return {
+                            "token": token,
+                            "user_id": user_id,
+                            "username": username or "Guest",
+                            "auth_mode": "guest",
+                            "token_source": "guest_direct",
+                            "guest_user_id": user_id,
+                        }
+
+                    self.logger.warning(f"响应中未找到 token 字段: {data}")
+                elif response.status_code == 405:
+                    self.logger.error(
+                        "🚫 请求被 WAF 拦截 (405)，无法直连获取匿名令牌"
+                    )
+                    break
+                else:
+                    self.logger.warning(
+                        f"直连获取匿名令牌失败，状态码: {response.status_code}"
+                    )
+            except httpx.TimeoutException as exc:
+                self.logger.warning(
+                    f"直连获取匿名令牌超时 (第{retry_count + 1}次): {exc}"
+                )
+            except httpx.ConnectError as exc:
+                self.logger.warning(
+                    f"直连获取匿名令牌连接错误 (第{retry_count + 1}次): {exc}"
+                )
+            except json.JSONDecodeError as exc:
+                self.logger.warning(
+                    f"直连获取匿名令牌 JSON 解析错误 (第{retry_count + 1}次): {exc}"
+                )
+            except Exception as exc:
+                self.logger.warning(
+                    f"直连获取匿名令牌失败 (第{retry_count + 1}次): {exc}"
+                )
+
+            if retry_count + 1 < max_retries:
+                await asyncio.sleep(2)
+
+        return {
+            "token": "",
+            "user_id": "guest",
+            "username": "Guest",
+            "auth_mode": "guest",
+            "token_source": "guest_direct",
+            "guest_user_id": None,
+        }
+
+    async def get_auth_info(
+        self,
+        excluded_tokens: Optional[Set[str]] = None,
+        excluded_guest_user_ids: Optional[Set[str]] = None,
+    ) -> Dict[str, Any]:
+        """优先获取认证 Token，必要时回退匿名会话池。"""
+        token_pool = get_token_pool()
+        if token_pool:
+            token = token_pool.get_next_token(exclude_tokens=excluded_tokens)
+            if token:
+                user_id = _extract_user_id_from_token(token)
+                self.logger.debug(f"从认证号池获取令牌: {token[:20]}...")
+                return {
+                    "token": token,
+                    "user_id": user_id,
+                    "username": "User",
+                    "auth_mode": "authenticated",
+                    "token_source": "auth_pool",
+                    "guest_user_id": None,
+                }
+
+        if settings.ANONYMOUS_MODE:
+            guest_pool = get_guest_session_pool()
+            if guest_pool:
+                try:
+                    session = await guest_pool.acquire(
+                        exclude_user_ids=excluded_guest_user_ids
+                    )
+                    self.logger.info(
+                        "🫥 认证池不可用，回退匿名会话池: "
+                        f"user_id={session.user_id}"
+                    )
+                    return {
+                        "token": session.token,
+                        "user_id": session.user_id,
+                        "username": session.username,
+                        "auth_mode": "guest",
+                        "token_source": "guest_pool",
+                        "guest_user_id": session.user_id,
+                    }
+                except Exception as exc:
+                    self.logger.warning(f"匿名会话池获取失败，转为直连访客鉴权: {exc}")
+
+            return await self._fetch_direct_guest_auth()
+
+        self.logger.error("❌ 无法获取有效的上游令牌")
+        return {
+            "token": "",
+            "user_id": "",
+            "username": "",
+            "auth_mode": "authenticated",
+            "token_source": "none",
+            "guest_user_id": None,
+        }
+
+    async def mark_token_failure(self, token: str, error: Exception = None):
+        """标记token使用失败"""
+        token_pool = get_token_pool()
+        if token_pool:
+            await token_pool.record_token_failure(token, error)
+
+    async def upload_image(
+        self,
+        data_url: str,
+        chat_id: str,
+        token: str,
+        user_id: str,
+        auth_mode: str = "authenticated",
+    ) -> Optional[Dict]:
+        """上传 base64 编码的图片到上游服务器。
+
+        Args:
+            data_url: data:image/xxx;base64,... 格式的图片数据
+            chat_id: 当前对话ID
+            token: 认证令牌
+            user_id: 用户ID
+            auth_mode: 当前鉴权模式，guest 模式下禁止上传
+
+        Returns:
+            上传成功返回完整的文件信息字典，失败返回 None
+        """
+        if auth_mode == "guest" or not data_url.startswith("data:"):
+            return None
+
+        try:
+            # 解析 data URL
+            header, encoded = data_url.split(",", 1)
+            mime_type = header.split(";")[0].split(":")[1] if ":" in header else "image/jpeg"
+
+            # 解码 base64 数据
+            image_data = base64.b64decode(encoded)
+            filename = str(uuid.uuid4())
+
+            self.logger.debug(f"📤 上传图片: {filename}, 大小: {len(image_data)} bytes")
+
+            # 构建上传请求
+            upload_url = f"{self.base_url}/api/v1/files/"
+            headers = {
+                "Accept": "*/*",
+                "Accept-Language": "zh-CN,zh;q=0.9",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Origin": f"{self.base_url}",
+                "Pragma": "no-cache",
+                "Referer": (
+                    f"{self.base_url}/c/{chat_id}" if chat_id else f"{self.base_url}/"
+                ),
+                "Sec-Ch-Ua": '"Microsoft Edge";v="141", "Not?A_Brand";v="8", "Chromium";v="141"',
+                "Sec-Ch-Ua-Mobile": "?0",
+                "Sec-Ch-Ua-Platform": '"Windows"',
+                "Sec-Fetch-Dest": "empty",
+                "Sec-Fetch-Mode": "cors",
+                "Sec-Fetch-Site": "same-origin",
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36 Edg/141.0.0.0",
+                "Authorization": f"Bearer {token}",
+            }
+
+            # Get proxy configuration
+            proxies = self._get_proxy_config()
+
+            # 使用 httpx 上传文件
+            async with httpx.AsyncClient(
+                timeout=self._build_timeout(),
+                limits=self._build_limits(),
+                proxy=proxies,
+            ) as client:
+                files = {
+                    "file": (filename, image_data, mime_type)
+                }
+                response = await client.post(upload_url, files=files, headers=headers)
+
+                if response.status_code == 200:
+                    result = response.json()
+                    file_id = result.get("id")
+                    file_name = result.get("filename")
+                    file_size = len(image_data)
+
+                    self.logger.info(f"✅ 图片上传成功: {file_id}_{file_name}")
+
+                    # 返回符合上游格式的文件信息
+                    current_timestamp = int(time.time())
+                    return {
+                        "type": "image",
+                        "file": {
+                            "id": file_id,
+                            "user_id": user_id,
+                            "hash": None,
+                            "filename": file_name,
+                            "data": {},
+                            "meta": {
+                                "name": file_name,
+                                "content_type": mime_type,
+                                "size": file_size,
+                                "data": {},
+                            },
+                            "created_at": current_timestamp,
+                            "updated_at": current_timestamp
+                        },
+                        "id": file_id,
+                        "url": f"/api/v1/files/{file_id}/content",
+                        "name": file_name,
+                        "status": "uploaded",
+                        "size": file_size,
+                        "error": "",
+                        "itemId": str(uuid.uuid4()),
+                        "media": "image"
+                    }
+                else:
+                    self.logger.error(f"❌ 图片上传失败: {response.status_code} - {response.text}")
+                    return None
+
+        except Exception as e:
+            self.logger.error(f"❌ 图片上传异常: {e}")
+            return None
+
+    async def transform_request(
+        self,
+        request: OpenAIRequest,
+        excluded_tokens: Optional[Set[str]] = None,
+        excluded_guest_user_ids: Optional[Set[str]] = None,
+    ) -> Dict[str, Any]:
+        """转换 OpenAI 请求为上游格式。"""
+        self.logger.info(f"🔄 转换 OpenAI 请求到上游格式: {request.model}")
+
+        raw_messages = [
+            message.model_dump(exclude_none=True)
+            for message in request.messages
+        ]
+        normalized_messages = _preprocess_openai_messages(raw_messages)
+
+        auth_info = await self.get_auth_info(
+            excluded_tokens=excluded_tokens,
+            excluded_guest_user_ids=excluded_guest_user_ids,
+        )
+        token = str(auth_info.get("token") or "")
+        if not token:
+            raise RuntimeError("无法获取上游认证令牌")
+
+        user_id = str(auth_info.get("user_id") or _extract_user_id_from_token(token))
+        auth_mode = str(auth_info.get("auth_mode") or "authenticated")
+        token_source = str(auth_info.get("token_source") or "unknown")
+        guest_user_id = auth_info.get("guest_user_id")
+        # 确定请求的模型特性
+        last_user_text = _extract_last_user_text(raw_messages)
+        requested_model = request.model
+        is_thinking_model = "-thinking" in requested_model.casefold()
+        is_search_model = "-search" in requested_model.casefold()
+        is_advanced_search = requested_model == settings.GLM47_ADVANCED_SEARCH_MODEL
+        upstream_model_id = self.model_mapping.get(requested_model, "0727-360B-API")
+        tools = request.tools if settings.TOOL_SUPPORT and request.tools else None
+        tool_choice = getattr(request, "tool_choice", None)
+        model_profile = self._get_model_request_profile(upstream_model_id)
+        enable_thinking = request.enable_thinking
+        if enable_thinking is None:
+            default_enable_thinking = model_profile["default_enable_thinking"]
+            enable_thinking = (
+                default_enable_thinking
+                if default_enable_thinking is not None
+                else is_thinking_model
+            )
+
+        web_search = request.web_search
+        if web_search is None:
+            web_search = is_search_model or is_advanced_search
+
+        use_persisted_chat = bool(model_profile["use_persisted_chat"])
+        preview_mode = bool(model_profile["preview_mode"])
+        feature_entries = list(model_profile["feature_entries"])
+        persisted_user_message_id = generate_uuid() if use_persisted_chat else None
+        persisted_assistant_message_id = generate_uuid() if use_persisted_chat else None
+
+        mcp_servers = list(model_profile["mcp_servers"])
+        if is_advanced_search and "advanced-search" not in mcp_servers:
+            mcp_servers.append("advanced-search")
+            self.logger.info("🔍 检测到高级搜索模型，添加 advanced-search MCP 服务器")
+
+        headers = get_dynamic_headers(
+            browser_type="chrome" if use_persisted_chat else None,
+        )
+        chat_id = generate_uuid()
+
+        # 处理消息格式 - 上游使用单独的 files 字段传递图片
+        messages = []
+        files = []
+        upload_chat_id = "" if use_persisted_chat else chat_id
+
+        for msg in normalized_messages:
+            role = str(msg.get("role", "user"))
+            content = msg.get("content")
+
+            if isinstance(content, str):
+                messages.append({"role": role, "content": content})
+                continue
+
+            if not isinstance(content, list):
+                continue
+
+            text_parts = []
+            image_parts = []
+            for part in content:
+                image_url = None
+                if hasattr(part, "type"):
+                    if part.type == "text" and hasattr(part, "text"):
+                        text_parts.append(part.text or "")
+                    elif part.type == "image_url" and hasattr(part, "image_url"):
+                        if hasattr(part.image_url, "url"):
+                            image_url = part.image_url.url
+                        elif (
+                            isinstance(part.image_url, dict)
+                            and "url" in part.image_url
+                        ):
+                            image_url = part.image_url["url"]
+                elif isinstance(part, dict):
+                    if part.get("type") == "text":
+                        text_parts.append(part.get("text", ""))
+                    elif part.get("type") == "image_url":
+                        image_url = part.get("image_url", {}).get("url", "")
+                elif isinstance(part, str):
+                    text_parts.append(part)
+
+                if not image_url:
+                    continue
+
+                self.logger.debug(f"✅ 检测到图片: {image_url[:50]}...")
+                if image_url.startswith("data:") and auth_mode != "guest":
+                    self.logger.info("🔄 上传 base64 图片到上游服务")
+                    file_info = await self.upload_image(
+                        image_url,
+                        upload_chat_id,
+                        token,
+                        user_id,
+                        auth_mode=auth_mode,
+                    )
+                    if not file_info:
+                        self.logger.warning("⚠️ 图片上传失败")
+                        text_parts.append("[系统提示: 图片上传失败]")
+                        continue
+
+                    files.append(file_info)
+                    self.logger.info("✅ 图片已添加到 files 数组")
+                    if persisted_user_message_id:
+                        file_info["ref_user_msg_id"] = persisted_user_message_id
+                    image_ref = str(file_info["id"])
+                    image_parts.append(
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": image_ref},
+                        }
+                    )
+                    self.logger.debug(f"📎 图片引用: {image_ref}")
+                    continue
+
+                if auth_mode != "guest":
+                    self.logger.warning("⚠️ 非 base64 图片或匿名模式，保留原始URL")
+                image_parts.append(
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": image_url},
+                    }
+                )
+
+            message_content = []
+            combined_text = " ".join(text_parts).strip()
+            if combined_text:
+                message_content.append({"type": "text", "text": combined_text})
+            message_content.extend(image_parts)
+            if message_content:
+                messages.append({"role": role, "content": message_content})
+
+        if use_persisted_chat:
+            chat_id = await self._create_upstream_chat(
+                prompt=last_user_text,
+                model=upstream_model_id,
+                token=token,
+                headers=headers,
+                enable_thinking=enable_thinking,
+                web_search=web_search,
+                user_message_id=persisted_user_message_id,
+                files=files or None,
+                feature_entries=feature_entries or None,
+                mcp_servers=mcp_servers or None,
+            )
+            self.logger.info(f"🧩 已为 {requested_model} 创建上游 chat: {chat_id}")
+        headers["Referer"] = f"{self.base_url}/c/{chat_id}"
+
+        if use_persisted_chat:
+            body = self._build_glm47_completion_body(
+                model=upstream_model_id,
+                messages=messages,
+                prompt=last_user_text,
+                chat_id=chat_id,
+                enable_thinking=enable_thinking,
+                web_search=web_search,
+                files=files,
+                tools=tools,
+                tool_choice=tool_choice,
+                temperature=request.temperature,
+                max_tokens=request.max_tokens,
+                mcp_servers=mcp_servers,
+                preview_mode=preview_mode,
+                feature_entries=feature_entries or None,
+                message_id=persisted_assistant_message_id or generate_uuid(),
+                current_user_message_id=persisted_user_message_id or generate_uuid(),
+                current_user_message_parent_id=None,
+            )
+        else:
+            message_id = generate_uuid()
+            session_id = generate_uuid()
+            body = {
+                "stream": True,
+                "model": upstream_model_id,
+                "messages": messages,
+                "signature_prompt": last_user_text,
+                "files": files,
+                "params": {},
+                "extra": {},
+                "features": {
+                    "image_generation": False,
+                    "web_search": web_search,
+                    "auto_web_search": web_search,
+                    "preview_mode": preview_mode,
+                    "flags": [],
+                    "features": [
+                        dict(item)
+                        for item in (feature_entries or DEFAULT_COMPLETION_FEATURES)
+                    ],
+                    "enable_thinking": enable_thinking,
+                },
+                "background_tasks": {
+                    "title_generation": False,
+                    "tags_generation": False,
+                },
+                "mcp_servers": mcp_servers,
+                "variables": self._build_request_variables(),
+                "model_item": {
+                    "id": upstream_model_id,
+                    "name": requested_model,
+                    "owned_by": settings.SERVICE_NAME,
+                },
+                "chat_id": chat_id,
+                "id": message_id,
+                "session_id": session_id,
+                "current_user_message_id": message_id,
+                "current_user_message_parent_id": None,
+            }
+            if tools:
+                body["tools"] = tools
+                if tool_choice is not None:
+                    body["tool_choice"] = tool_choice
+                self.logger.info(f"🔧 工具调用将直接透传到上游: {len(tools)} 个工具")
+            else:
+                body["tools"] = None
+            if request.temperature is not None:
+                body["params"]["temperature"] = request.temperature
+            if request.max_tokens is not None:
+                body["params"]["max_tokens"] = request.max_tokens
+
+        try:
+            signed_url, signature, timestamp_ms = self._build_signed_completion_request(
+                prompt=last_user_text,
+                chat_id=chat_id,
+                token=token,
+                user_id=user_id,
+                user_agent=headers["User-Agent"],
+                use_browser_fingerprint=use_persisted_chat,
+            )
+            logger.debug(
+                "[上游] 生成签名成功: %s... (user_id=%s, timestamp=%s)",
+                signature[:16],
+                user_id,
+                timestamp_ms,
+            )
+        except Exception as e:
+            logger.error(f"[上游] 签名生成失败: {e}")
+            signature = ""
+            timestamp_ms = "0"
+            signed_url = self.api_endpoint
+
+        fe_version = headers.get("X-FE-Version") or get_latest_fe_version()
+        headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Accept": "*/*" if use_persisted_chat else "application/json",
+                "X-FE-Version": fe_version,
+                "X-Signature": signature,
+            }
+        )
+
+        logger.debug(
+            "[上游] 请求头: Authorization=Bearer *****, X-Signature=%s...",
+            signature[:16] if signature else "(空)",
+        )
+        logger.debug(
+            "[上游] URL 参数: timestamp=%s, user_id=%s, persisted_chat=%s",
+            timestamp_ms,
+            user_id,
+            use_persisted_chat,
+        )
+        
+        # 存储当前token用于错误处理
+        self._current_token = token
+
+        return {
+            "url": signed_url,
+            "headers": headers,
+            "body": body,
+            "token": token,
+            "chat_id": chat_id,
+            "model": requested_model,
+            "user_id": user_id,
+            "auth_mode": auth_mode,
+            "token_source": token_source,
+            "guest_user_id": guest_user_id,
+        }
+    
+    async def chat_completion(
+        self,
+        request: OpenAIRequest,
+        **kwargs
+    ) -> Union[Dict[str, Any], AsyncGenerator[str, None]]:
+        """聊天完成接口。"""
+        self.logger.info(f"🔄 {self.name} 处理请求: {request.model}")
+        self.logger.debug(f"  消息数量: {len(request.messages)}")
+        self.logger.debug(f"  流式模式: {request.stream}")
+
+        try:
+            transformed = await self.transform_request(request)
+
+            if request.stream:
+                return self._create_stream_response(request, transformed)
+
+            proxies = self._get_proxy_config()
+            max_attempts = self._get_total_retry_limit()
+            excluded_tokens: Set[str] = set()
+            excluded_guest_user_ids: Set[str] = set()
+
+            for attempt in range(max_attempts):
+                async with httpx.AsyncClient(
+                    timeout=self._build_timeout(read_timeout=60.0),
+                    limits=self._build_limits(),
+                    proxy=proxies,
+                ) as client:
+                    response = await client.post(
+                        transformed["url"],
+                        headers=transformed["headers"],
+                        json=transformed["body"],
+                    )
+
+                error_code, error_message = self._extract_upstream_error_details(
+                    response.status_code,
+                    response.text,
+                )
+                is_concurrency_limited = self._is_concurrency_limited(
+                    response.status_code,
+                    error_code,
+                    error_message,
+                )
+
+                if self._should_retry_guest_session(
+                    response.status_code,
+                    is_concurrency_limited,
+                    attempt,
+                    max_attempts,
+                    transformed,
+                ):
+                    guest_user_id = str(
+                        transformed.get("guest_user_id")
+                        or transformed.get("user_id")
+                        or ""
+                    )
+                    if guest_user_id:
+                        excluded_guest_user_ids.add(guest_user_id)
+                    transformed = await self._refresh_guest_request(
+                        request,
+                        attempt,
+                        excluded_tokens,
+                        excluded_guest_user_ids,
+                        transformed,
+                        is_concurrency_limited=is_concurrency_limited,
+                    )
+                    continue
+
+                if self._should_retry_authenticated_session(
+                    response.status_code,
+                    is_concurrency_limited,
+                    attempt,
+                    max_attempts,
+                    transformed,
+                ):
+                    current_token = str(transformed.get("token") or "")
+                    if current_token:
+                        excluded_tokens.add(current_token)
+                        await self.mark_token_failure(
+                            current_token,
+                            Exception(error_message or "上游认证会话不可用"),
+                        )
+                        self.logger.warning(
+                            "⚠️ 认证会话不可用，准备切换认证 Token/回退匿名池: "
+                            f"{current_token[:20]}..."
+                        )
+                    transformed = await self._refresh_authenticated_request(
+                        request,
+                        attempt,
+                        excluded_tokens,
+                        excluded_guest_user_ids,
+                    )
+                    continue
+
+                if not response.is_success:
+                    error_msg = f"上游 API 错误: {response.status_code}"
+                    if not self._is_guest_auth(transformed):
+                        current_token = str(transformed.get("token") or "")
+                        if current_token:
+                            await self.mark_token_failure(
+                                current_token,
+                                Exception(error_message or error_msg),
+                            )
+                    await self._release_guest_session(transformed)
+                    self.logger.error(f"❌ {self.name} 响应失败: {error_msg}")
+                    return handle_error(Exception(error_message or error_msg))
+
+                try:
+                    result = await self.transform_response(response, request, transformed)
+                finally:
+                    await self._release_guest_session(transformed)
+
+                if not self._is_guest_auth(transformed):
+                    current_token = str(transformed.get("token") or "")
+                    if current_token:
+                        token_pool = get_token_pool()
+                        if token_pool:
+                            await token_pool.record_token_success(current_token)
+
+                return result
+
+        except Exception as e:
+            self.logger.error(f"❌ {self.name} 响应失败: {str(e)}")
+            return handle_error(e, "请求处理")
+
+    async def _create_stream_response(
+        self,
+        request: OpenAIRequest,
+        transformed: Dict[str, Any]
+    ) -> AsyncGenerator[str, None]:
+        """创建流式响应，并在首包前支持双池重试。"""
+        max_attempts = self._get_total_retry_limit()
+        excluded_tokens: Set[str] = set()
+        excluded_guest_user_ids: Set[str] = set()
+        current_token = str(transformed.get("token") or "")
+
+        try:
+            proxies = self._get_proxy_config()
+
+            async with httpx.AsyncClient(
+                timeout=self._build_timeout(read_timeout=180.0),
+                http2=True,
+                limits=self._build_limits(),
+                proxy=proxies,
+            ) as client:
+                for attempt in range(max_attempts):
+                    self.logger.info(f"�� 发送请求到上游: {transformed['url']}")
+                    async with client.stream(
+                        "POST",
+                        transformed["url"],
+                        json=transformed["body"],
+                        headers=transformed["headers"],
+                    ) as response:
+                        error_text = await response.aread() if response.status_code != 200 else b""
+                        error_msg = error_text.decode("utf-8", errors="ignore")
+                        error_code, parsed_error_message = (
+                            self._extract_upstream_error_details(
+                                response.status_code,
+                                error_msg,
+                            )
+                            if response.status_code != 200
+                            else (None, "")
+                        )
+                        is_concurrency_limited = self._is_concurrency_limited(
+                            response.status_code,
+                            error_code,
+                            parsed_error_message,
+                        )
+
+                        if self._should_retry_guest_session(
+                            response.status_code,
+                            is_concurrency_limited,
+                            attempt,
+                            max_attempts,
+                            transformed,
+                        ):
+                            guest_user_id = str(
+                                transformed.get("guest_user_id")
+                                or transformed.get("user_id")
+                                or ""
+                            )
+                            if guest_user_id:
+                                excluded_guest_user_ids.add(guest_user_id)
+                            transformed = await self._refresh_guest_request(
+                                request,
+                                attempt,
+                                excluded_tokens,
+                                excluded_guest_user_ids,
+                                transformed,
+                                is_concurrency_limited=is_concurrency_limited,
+                            )
+                            current_token = str(transformed.get("token") or "")
+                            continue
+
+                        if self._should_retry_authenticated_session(
+                            response.status_code,
+                            is_concurrency_limited,
+                            attempt,
+                            max_attempts,
+                            transformed,
+                        ):
+                            if current_token:
+                                excluded_tokens.add(current_token)
+                                await self.mark_token_failure(
+                                    current_token,
+                                    Exception(
+                                        parsed_error_message or "上游认证会话不可用"
+                                    ),
+                                )
+                                self.logger.warning(
+                                    "⚠️ 流式请求命中认证会话限制，准备切号/回退匿名池: "
+                                    f"{current_token[:20]}..."
+                                )
+                            transformed = await self._refresh_authenticated_request(
+                                request,
+                                attempt,
+                                excluded_tokens,
+                                excluded_guest_user_ids,
+                            )
+                            current_token = str(transformed.get("token") or "")
+                            continue
+
+                        if response.status_code != 200:
+                            self.logger.error(f"❌ 上游返回错误: {response.status_code}")
+                            if error_msg:
+                                self.logger.error(f"❌ 错误详情: {error_msg}")
+
+                            if not self._is_guest_auth(transformed) and current_token:
+                                await self.mark_token_failure(
+                                    current_token,
+                                    Exception(
+                                        parsed_error_message
+                                        or f"Upstream error: {response.status_code}"
+                                    ),
+                                )
+                            await self._release_guest_session(transformed)
+
+                            if response.status_code == 405:
+                                self.logger.error(
+                                    "🚫 请求被上游 WAF 拦截，可能是请求头或签名异常"
+                                )
+                                error_response = {
+                                    "error": {
+                                        "message": (
+                                            "请求被上游WAF拦截(405 Method Not Allowed),"
+                                            "可能是请求头或签名异常,请稍后重试..."
+                                        ),
+                                        "type": "waf_blocked",
+                                        "code": 405,
+                                    }
+                                }
+                            else:
+                                error_response = {
+                                    "error": {
+                                        "message": parsed_error_message
+                                        or f"Upstream error: {response.status_code}",
+                                        "type": "upstream_error",
+                                        "code": error_code or response.status_code,
+                                    }
+                                }
+                            yield f"data: {json.dumps(error_response)}\n\n"
+                            yield "data: [DONE]\n\n"
+                            return
+
+                        chat_id = transformed["chat_id"]
+                        model = transformed["model"]
+                        try:
+                            async for chunk in self._handle_stream_response(
+                                response,
+                                chat_id,
+                                model,
+                                request,
+                                transformed,
+                            ):
+                                yield chunk
+                        finally:
+                            await self._release_guest_session(transformed)
+
+                        if not self._is_guest_auth(transformed) and current_token:
+                            token_pool = get_token_pool()
+                            if token_pool:
+                                await token_pool.record_token_success(current_token)
+                        return
+        except Exception as e:
+            self.logger.error(f"❌ 流处理错误: {e}")
+            import traceback
+            self.logger.error(traceback.format_exc())
+            if self._is_guest_auth(transformed):
+                await self._release_guest_session(transformed)
+            elif current_token:
+                await self.mark_token_failure(current_token, e)
+
+            error_response = {
+                "error": {
+                    "message": str(e),
+                    "type": "stream_error"
+                }
+            }
+            yield f"data: {json.dumps(error_response)}\n\n"
+            yield "data: [DONE]\n\n"
+            return
+
+    async def transform_response(
+        self, 
+        response: httpx.Response, 
+        request: OpenAIRequest,
+        transformed: Dict[str, Any]
+    ) -> Union[Dict[str, Any], AsyncGenerator[str, None]]:
+        """转换上游响应为 OpenAI 格式。"""
+        chat_id = transformed["chat_id"]
+        model = transformed["model"]
+        
+        if request.stream:
+            return self._handle_stream_response(response, chat_id, model, request, transformed)
+        else:
+            return await self._handle_non_stream_response(response, chat_id, model)
+    
+    async def _handle_stream_response(
+        self,
+        response: httpx.Response,
+        chat_id: str,
+        model: str,
+        request: OpenAIRequest,
+        transformed: Dict[str, Any]
+    ) -> AsyncGenerator[str, None]:
+        """处理上游流式响应"""
+        self.logger.info("✅ 上游响应成功，开始处理 SSE 流")
+
+        has_tools = settings.TOOL_SUPPORT and bool(request.tools)
+        buffered_content = ""
+        usage_info: Dict[str, int] = {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        }
+        tool_calls_accum: List[Dict[str, Any]] = []
+        has_sent_role = False
+        finished = False
+        line_count = 0
+
+        async def ensure_role_sent() -> Optional[str]:
+            nonlocal has_sent_role
+            if has_sent_role:
+                return None
+
+            has_sent_role = True
+            return await format_sse_chunk(
+                create_openai_chunk(chat_id, model, {"role": "assistant"})
+            )
+
+        async def finalize_stream() -> AsyncGenerator[str, None]:
+            nonlocal finished, tool_calls_accum
+            if finished:
+                return
+
+            if has_tools and not tool_calls_accum:
+                parsed_tool_calls, _ = parse_and_extract_tool_calls(buffered_content)
+                normalized = self._normalize_tool_calls(parsed_tool_calls)
+                if normalized:
+                    tool_calls_accum = normalized
+                    role_output = await ensure_role_sent()
+                    if role_output:
+                        yield role_output
+                    for tool_call in normalized:
+                        yield await format_sse_chunk(
+                            create_openai_chunk(
+                                chat_id,
+                                model,
+                                {"tool_calls": [tool_call]},
+                            )
+                        )
+
+            if not has_sent_role:
+                role_output = await ensure_role_sent()
+                if role_output:
+                    yield role_output
+
+            finish_reason = "tool_calls" if tool_calls_accum else "stop"
+            finish_chunk = create_openai_chunk(
+                chat_id,
+                model,
+                {},
+                finish_reason,
+            )
+            finish_chunk["usage"] = usage_info
+            yield await format_sse_chunk(finish_chunk)
+            yield "data: [DONE]\n\n"
+            finished = True
+
+        try:
+            async for line in response.aiter_lines():
+                line_count += 1
+                if not line:
+                    continue
+
+                current_line = line.strip()
+                if not current_line.startswith("data:"):
+                    continue
+
+                chunk_str = current_line[5:].strip()
+                if not chunk_str:
+                    continue
+
+                if chunk_str == "[DONE]":
+                    async for final_chunk in finalize_stream():
+                        yield final_chunk
+                    continue
+
+                try:
+                    chunk = json.loads(chunk_str)
+                except json.JSONDecodeError as error:
+                    self.logger.debug(f"❌ JSON解析错误: {error}, 内容: {chunk_str[:1000]}")
+                    continue
+
+                chunk_type = chunk.get("type")
+                data = chunk.get("data", {}) if chunk_type == "chat:completion" else chunk
+                if not isinstance(data, dict):
+                    continue
+
+                phase = data.get("phase")
+                delta_content = data.get("delta_content", "")
+                edit_content = data.get("edit_content", "")
+
+                if phase and phase != getattr(self, "_last_phase", None):
+                    self.logger.info(f"📈 SSE 阶段: {phase}")
+                    self._last_phase = phase
+
+                if data.get("usage"):
+                    usage_info = data["usage"]
+
+                if delta_content:
+                    buffered_content += delta_content
+                elif edit_content:
+                    buffered_content += edit_content
+
+                direct_tool_calls = self._normalize_tool_calls(
+                    data.get("tool_calls"),
+                    len(tool_calls_accum),
+                )
+                if direct_tool_calls:
+                    role_output = await ensure_role_sent()
+                    if role_output:
+                        yield role_output
+                    tool_calls_accum.extend(direct_tool_calls)
+                    for tool_call in direct_tool_calls:
+                        yield await format_sse_chunk(
+                            create_openai_chunk(
+                                chat_id,
+                                model,
+                                {"tool_calls": [tool_call]},
+                            )
+                        )
+
+                if phase == "thinking" and delta_content:
+                    cleaned = self._clean_reasoning_delta(delta_content)
+                    if cleaned:
+                        role_output = await ensure_role_sent()
+                        if role_output:
+                            yield role_output
+                        yield await format_sse_chunk(
+                            create_openai_chunk(
+                                chat_id,
+                                model,
+                                {"reasoning_content": cleaned},
+                            )
+                        )
+
+                elif phase == "answer":
+                    text = delta_content or self._extract_answer_content(edit_content)
+                    if text:
+                        role_output = await ensure_role_sent()
+                        if role_output:
+                            yield role_output
+                        yield await format_sse_chunk(
+                            create_openai_chunk(
+                                chat_id,
+                                model,
+                                {"content": text},
+                            )
+                        )
+
+                elif phase == "other":
+                    other_text = self._extract_answer_content(edit_content)
+                    if other_text:
+                        role_output = await ensure_role_sent()
+                        if role_output:
+                            yield role_output
+                        yield await format_sse_chunk(
+                            create_openai_chunk(
+                                chat_id,
+                                model,
+                                {"content": other_text},
+                            )
+                        )
+
+                elif phase == "search" or chunk_type == "web_search":
+                    citation_text = self._format_search_results(data)
+                    if citation_text:
+                        role_output = await ensure_role_sent()
+                        if role_output:
+                            yield role_output
+                        yield await format_sse_chunk(
+                            create_openai_chunk(
+                                chat_id,
+                                model,
+                                {"content": citation_text},
+                            )
+                        )
+
+                if data.get("done"):
+                    async for final_chunk in finalize_stream():
+                        yield final_chunk
+                    return
+
+            self.logger.info(f"✅ SSE 流处理完成，共处理 {line_count} 行数据")
+
+            if not finished:
+                async for final_chunk in finalize_stream():
+                    yield final_chunk
+
+        except Exception as e:
+            self.logger.error(f"❌ 流式响应处理错误: {e}")
+            import traceback
+            self.logger.error(traceback.format_exc())
+            yield await format_sse_chunk(
+                create_openai_chunk(chat_id, model, {}, "stop")
+            )
+            yield "data: [DONE]\n\n"
+    
+    async def _handle_non_stream_response(
+        self, 
+        response: httpx.Response, 
+        chat_id: str, 
+        model: str
+    ) -> Dict[str, Any]:
+        """处理非流式响应，聚合上游 SSE 为一次性 OpenAI 响应。"""
+        final_content = ""
+        reasoning_content = ""
+        tool_calls_accum: List[Dict[str, Any]] = []
+        usage_info: Dict[str, int] = {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        }
+
+        try:
+            async for line in response.aiter_lines():
+                if not line:
+                    continue
+
+                line = line.strip()
+                if not line.startswith("data:"):
+                    try:
+                        maybe_err = json.loads(line)
+                        if isinstance(maybe_err, dict) and (
+                            "error" in maybe_err or "code" in maybe_err or "message" in maybe_err
+                        ):
+                            msg = (
+                                (maybe_err.get("error") or {}).get("message")
+                                if isinstance(maybe_err.get("error"), dict)
+                                else maybe_err.get("message")
+                            ) or "上游返回错误"
+                            return handle_error(Exception(msg), "API响应")
+                    except Exception:
+                        pass
+                    continue
+
+                data_str = line[5:].strip()
+                if not data_str or data_str in ("[DONE]", "DONE", "done"):
+                    continue
+
+                try:
+                    chunk = json.loads(data_str)
+                except json.JSONDecodeError:
+                    continue
+
+                chunk_type = chunk.get("type")
+                data = chunk.get("data", {}) if chunk_type == "chat:completion" else chunk
+                if not isinstance(data, dict):
+                    continue
+
+                phase = data.get("phase")
+                delta_content = data.get("delta_content", "")
+                edit_content = data.get("edit_content", "")
+
+                if data.get("usage"):
+                    usage_info = data["usage"]
+
+                if phase == "thinking" and delta_content:
+                    reasoning_content += self._clean_reasoning_delta(delta_content)
+
+                elif phase == "answer":
+                    if delta_content:
+                        final_content += delta_content
+                    elif edit_content:
+                        final_content += self._extract_answer_content(edit_content)
+
+                elif phase == "other" and edit_content:
+                    final_content += self._extract_answer_content(edit_content)
+
+                elif phase == "search" or chunk_type == "web_search":
+                    final_content += self._format_search_results(data)
+
+                tool_calls_accum.extend(
+                    self._normalize_tool_calls(
+                        data.get("tool_calls"),
+                        len(tool_calls_accum),
+                    )
+                )
+
+        except Exception as e:
+            self.logger.error(f"❌ 非流式响应处理错误: {e}")
+            import traceback
+            self.logger.error(traceback.format_exc())
+            return handle_error(e, "非流式聚合")
+
+        if not tool_calls_accum:
+            parsed_tool_calls, cleaned_content = parse_and_extract_tool_calls(final_content)
+            normalized = self._normalize_tool_calls(parsed_tool_calls)
+            if normalized:
+                tool_calls_accum = normalized
+                final_content = cleaned_content
+
+        final_content = (final_content or "").strip()
+        reasoning_content = (reasoning_content or "").strip()
+
+        if not final_content and reasoning_content:
+            final_content = reasoning_content
+
+        return create_openai_response_with_reasoning(
+            chat_id,
+            model,
+            final_content,
+            reasoning_content,
+            usage_info,
+            tool_calls_accum or None,
+        )

app/models/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from app.models import schemas
+
+__all__ = ["schemas"]

app/models/request_log.py

@@ -0,0 +1,35 @@
+"""请求日志数据库模型。"""
+
+from app.core.config import settings
+
+DB_PATH = settings.DB_PATH
+
+# 创建请求日志表的SQL
+SQL_CREATE_REQUEST_LOGS_TABLE = """
+CREATE TABLE IF NOT EXISTS request_logs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+    provider TEXT NOT NULL,
+    endpoint TEXT DEFAULT '',
+    source TEXT DEFAULT 'unknown',
+    protocol TEXT DEFAULT 'unknown',
+    client_name TEXT DEFAULT 'Unknown',
+    model TEXT NOT NULL,
+    status_code INTEGER DEFAULT 200,
+    success BOOLEAN NOT NULL,
+    duration REAL,
+    first_token_time REAL,
+    input_tokens INTEGER DEFAULT 0,
+    output_tokens INTEGER DEFAULT 0,
+    cache_creation_tokens INTEGER DEFAULT 0,
+    cache_read_tokens INTEGER DEFAULT 0,
+    total_tokens INTEGER DEFAULT 0,
+    error_message TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_request_logs_timestamp ON request_logs(timestamp);
+CREATE INDEX IF NOT EXISTS idx_request_logs_model ON request_logs(model);
+CREATE INDEX IF NOT EXISTS idx_request_logs_provider ON request_logs(provider);
+CREATE INDEX IF NOT EXISTS idx_request_logs_source ON request_logs(source);
+"""

app/models/schemas.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from typing import Dict, List, Optional, Any, Union, Literal
+from pydantic import BaseModel
+
+
+class ImageUrl(BaseModel):
+    """Image URL model for vision content"""
+    url: str
+
+
+class ContentPart(BaseModel):
+    """Content part model for OpenAI's new content format"""
+
+    type: str
+    text: Optional[str] = None
+    image_url: Optional[ImageUrl] = None  # 添加 image_url 字段
+
+
+class Message(BaseModel):
+    """Chat message model"""
+
+    role: str
+    content: Optional[Union[str, List[ContentPart]]] = None
+    reasoning_content: Optional[str] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+    tool_call_id: Optional[str] = None
+    name: Optional[str] = None
+
+
+class OpenAIRequest(BaseModel):
+    """OpenAI-compatible request model"""
+
+    model: str
+    messages: List[Message]
+    stream: Optional[bool] = False
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    tools: Optional[List[Dict[str, Any]]] = None
+    tool_choice: Optional[Any] = None
+    enable_thinking: Optional[bool] = None
+    web_search: Optional[bool] = None
+
+
+class ModelItem(BaseModel):
+    """Model information item"""
+
+    id: str
+    name: str
+    owned_by: str
+
+
+class UpstreamRequest(BaseModel):
+    """Upstream service request model"""
+
+    stream: bool
+    model: str
+    messages: List[Message]
+    params: Dict[str, Any] = {}
+    features: Dict[str, Any] = {}
+    signature_prompt: Optional[str] = None
+    files: Optional[List[Dict[str, Any]]] = None
+    extra: Optional[Dict[str, Any]] = None
+    background_tasks: Optional[Dict[str, bool]] = None
+    chat_id: Optional[str] = None
+    id: Optional[str] = None
+    session_id: Optional[str] = None
+    current_user_message_id: Optional[str] = None
+    current_user_message_parent_id: Optional[str] = None
+    mcp_servers: Optional[List[str]] = None
+    model_item: Optional[Dict[str, Any]] = {}  # Model item dictionary
+    tools: Optional[List[Dict[str, Any]]] = None  # Add tools field for OpenAI compatibility
+    tool_choice: Optional[Any] = None
+    variables: Optional[Dict[str, str]] = None
+    model_config = {"protected_namespaces": ()}
+
+
+class Delta(BaseModel):
+    """Stream delta model"""
+
+    role: Optional[str] = None
+    content: Optional[str] = "" or None
+    reasoning_content: Optional[str] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+
+
+class Choice(BaseModel):
+    """Response choice model"""
+
+    index: int
+    message: Optional[Message] = None
+    delta: Optional[Delta] = None
+    finish_reason: Optional[str] = None
+
+
+class Usage(BaseModel):
+    """Token usage statistics"""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class OpenAIResponse(BaseModel):
+    """OpenAI-compatible response model"""
+
+    id: str
+    object: str
+    created: int
+    model: str
+    choices: List[Choice]
+    usage: Optional[Usage] = None
+
+
+class UpstreamError(BaseModel):
+    """Upstream error model"""
+
+    detail: str
+    code: int
+
+
+class UpstreamDataInner(BaseModel):
+    """Inner upstream data model"""
+
+    error: Optional[UpstreamError] = None
+
+
+class UpstreamDataData(BaseModel):
+    """Upstream data content model"""
+
+    delta_content: str = ""
+    edit_content: str = ""
+    phase: str = ""
+    done: bool = False
+    results: Optional[List[Dict[str, Any]]] = None
+    sources: Optional[List[Dict[str, Any]]] = None
+    citations: Optional[List[Dict[str, Any]]] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+    usage: Optional[Usage] = None
+    error: Optional[UpstreamError] = None
+    inner: Optional[UpstreamDataInner] = None
+
+
+class UpstreamData(BaseModel):
+    """Upstream data model"""
+
+    type: str
+    data: UpstreamDataData
+    error: Optional[UpstreamError] = None
+
+
+class Model(BaseModel):
+    """Model information for listing"""
+
+    id: str
+    object: str = "model"
+    created: int
+    owned_by: str
+
+
+class ModelsResponse(BaseModel):
+    """Models list response model"""
+
+    object: str = "list"
+    data: List[Model]

app/models/token_db.py

@@ -0,0 +1,44 @@
+"""Token 数据库模型定义。"""
+
+from app.core.config import settings
+
+SQL_CREATE_TABLES = """
+-- Token 配置表
+CREATE TABLE IF NOT EXISTS tokens (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    provider TEXT NOT NULL,              -- 提供商: zai
+    token TEXT NOT NULL UNIQUE,          -- Token 值（唯一）
+    token_type TEXT DEFAULT 'user',      -- Token 类型: user, guest, unknown
+    is_enabled BOOLEAN DEFAULT 1,        -- 是否启用
+    priority INTEGER DEFAULT 0,          -- 优先级（用于排序）
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(provider, token)              -- 同一提供商内 Token 唯一
+);
+
+-- Token 使用统计表
+CREATE TABLE IF NOT EXISTS token_stats (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    token_id INTEGER NOT NULL,
+    total_requests INTEGER DEFAULT 0,
+    successful_requests INTEGER DEFAULT 0,
+    failed_requests INTEGER DEFAULT 0,
+    last_success_time DATETIME,
+    last_failure_time DATETIME,
+    FOREIGN KEY (token_id) REFERENCES tokens(id) ON DELETE CASCADE
+);
+
+-- 创建索引
+CREATE INDEX IF NOT EXISTS idx_tokens_provider ON tokens(provider);
+CREATE INDEX IF NOT EXISTS idx_tokens_enabled ON tokens(is_enabled);
+CREATE INDEX IF NOT EXISTS idx_token_stats_token_id ON token_stats(token_id);
+
+-- 触发器：自动更新 updated_at
+CREATE TRIGGER IF NOT EXISTS update_tokens_timestamp
+AFTER UPDATE ON tokens
+BEGIN
+    UPDATE tokens SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+END;
+"""
+
+DB_PATH = settings.DB_PATH

app/services/request_log_dao.py

@@ -0,0 +1,630 @@
+"""
+请求日志数据访问层 (DAO)
+提供请求日志的 CRUD 操作和查询功能
+"""
+import os
+import sqlite3
+from contextlib import asynccontextmanager
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional
+
+import aiosqlite
+
+from app.models.request_log import DB_PATH, SQL_CREATE_REQUEST_LOGS_TABLE
+from app.utils.logger import logger
+
+
+def _format_sqlite_datetime(value: datetime) -> str:
+    """格式化为 SQLite `CURRENT_TIMESTAMP` 兼容的时间字符串。"""
+    return value.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _normalize_trend_window(window: Optional[str], days: Optional[int]) -> str:
+    """统一趋势窗口参数，兼容旧版 `days` 调用。"""
+    if window:
+        normalized = str(window).strip().lower()
+    elif days == 30:
+        normalized = "30d"
+    elif days == 1:
+        normalized = "24h"
+    else:
+        normalized = "7d"
+
+    if normalized in {"24h", "7d", "30d"}:
+        return normalized
+    if normalized == "1d":
+        return "24h"
+    return "7d"
+
+
+class RequestLogDAO:
+    """请求日志数据访问对象"""
+
+    def __init__(self, db_path: str = DB_PATH):
+        """初始化 DAO"""
+        self.db_path = db_path
+        self._ensure_db_directory()
+        self._init_db()
+
+    def _ensure_db_directory(self):
+        """确保数据库目录存在"""
+        db_dir = os.path.dirname(self.db_path)
+        if db_dir and not os.path.exists(db_dir):
+            os.makedirs(db_dir, exist_ok=True)
+
+    def _init_db(self):
+        """初始化数据库表"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            conn.executescript(SQL_CREATE_REQUEST_LOGS_TABLE)
+            self._ensure_columns(conn)
+            conn.commit()
+            conn.close()
+            logger.debug("请求日志表初始化成功")
+        except Exception as e:
+            logger.error(f"初始化请求日志表失败: {e}")
+
+    def _ensure_columns(self, conn: sqlite3.Connection):
+        """为旧数据库补齐新增列。"""
+        cursor = conn.execute("PRAGMA table_info(request_logs)")
+        existing_columns = {row[1] for row in cursor.fetchall()}
+        required_columns = {
+            "endpoint": "TEXT DEFAULT ''",
+            "source": "TEXT DEFAULT 'unknown'",
+            "protocol": "TEXT DEFAULT 'unknown'",
+            "client_name": "TEXT DEFAULT 'Unknown'",
+            "status_code": "INTEGER DEFAULT 200",
+            "cache_creation_tokens": "INTEGER DEFAULT 0",
+            "cache_read_tokens": "INTEGER DEFAULT 0",
+        }
+
+        for column, definition in required_columns.items():
+            if column in existing_columns:
+                continue
+            conn.execute(
+                f"ALTER TABLE request_logs ADD COLUMN {column} {definition}"
+            )
+
+    @asynccontextmanager
+    async def get_connection(self):
+        """获取异步数据库连接"""
+        conn = await aiosqlite.connect(self.db_path)
+        conn.row_factory = aiosqlite.Row
+        try:
+            yield conn
+        finally:
+            await conn.close()
+
+    async def add_log(
+        self,
+        provider: str,
+        endpoint: str,
+        source: str,
+        protocol: str,
+        client_name: str,
+        model: str,
+        status_code: int,
+        success: bool,
+        duration: float = 0.0,
+        first_token_time: float = 0.0,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cache_creation_tokens: int = 0,
+        cache_read_tokens: int = 0,
+        total_tokens: Optional[int] = None,
+        error_message: str = None
+    ) -> int:
+        """
+        添加请求日志
+
+        Args:
+            provider: 提供商名称
+            endpoint: 请求端点
+            source: 请求来源标识
+            protocol: 协议类型
+            client_name: 客户端名称
+            model: 模型名称
+            status_code: 请求状态码
+            success: 是否成功
+            duration: 总耗时（秒）
+            first_token_time: 首字延迟（秒）
+            input_tokens: 输入 token 数
+            output_tokens: 输出 token 数
+            cache_creation_tokens: 缓存创建 token 数
+            cache_read_tokens: 缓存命中 token 数
+            total_tokens: 总 token 数
+            error_message: 错误信息
+
+        Returns:
+            日志 ID
+        """
+        if total_tokens is None:
+            total_tokens = input_tokens + output_tokens
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(
+                """
+                INSERT INTO request_logs
+                (provider, endpoint, source, protocol, client_name, model,
+                 status_code, success, duration, first_token_time,
+                 input_tokens, output_tokens, cache_creation_tokens,
+                 cache_read_tokens, total_tokens, error_message)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    provider,
+                    endpoint,
+                    source,
+                    protocol,
+                    client_name,
+                    model,
+                    status_code,
+                    success,
+                    duration,
+                    first_token_time,
+                    input_tokens,
+                    output_tokens,
+                    cache_creation_tokens,
+                    cache_read_tokens,
+                    total_tokens,
+                    error_message,
+                )
+            )
+            await conn.commit()
+            return cursor.lastrowid
+
+    async def get_recent_logs(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        provider: str = None,
+        model: str = None,
+        success: bool = None,
+        source: str = None,
+    ) -> List[Dict]:
+        """
+        获取最近的请求日志
+
+        Args:
+            limit: 返回数量限制
+            provider: 过滤提供商
+            model: 过滤模型
+            success: 过滤成功/失败状态
+
+        Returns:
+            日志列表
+        """
+        query = "SELECT * FROM request_logs WHERE 1=1"
+        params = []
+
+        if provider:
+            query += " AND provider = ?"
+            params.append(provider)
+
+        if model:
+            query += " AND model = ?"
+            params.append(model)
+
+        if success is not None:
+            query += " AND success = ?"
+            params.append(success)
+
+        if source:
+            query += " AND source = ?"
+            params.append(source)
+
+        query += " ORDER BY timestamp DESC, id DESC LIMIT ? OFFSET ?"
+        params.extend([limit, max(0, offset)])
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(query, params)
+            rows = await cursor.fetchall()
+            return [dict(row) for row in rows]
+
+    async def count_logs(
+        self,
+        provider: str = None,
+        model: str = None,
+        success: bool = None,
+        source: str = None,
+    ) -> int:
+        """统计日志总数。"""
+        query = "SELECT COUNT(*) AS total_count FROM request_logs WHERE 1=1"
+        params = []
+
+        if provider:
+            query += " AND provider = ?"
+            params.append(provider)
+
+        if model:
+            query += " AND model = ?"
+            params.append(model)
+
+        if success is not None:
+            query += " AND success = ?"
+            params.append(success)
+
+        if source:
+            query += " AND source = ?"
+            params.append(source)
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(query, params)
+            row = await cursor.fetchone()
+            return int(row["total_count"] or 0) if row else 0
+
+    async def get_logs_by_time_range(
+        self,
+        start_time: datetime,
+        end_time: datetime,
+        provider: str = None,
+        model: str = None
+    ) -> List[Dict]:
+        """
+        按时间范围获取日志
+
+        Args:
+            start_time: 开始时间
+            end_time: 结束时间
+            provider: 过滤提供商
+            model: 过滤模型
+
+        Returns:
+            日志列表
+        """
+        query = "SELECT * FROM request_logs WHERE timestamp BETWEEN ? AND ?"
+        params = [
+            _format_sqlite_datetime(start_time),
+            _format_sqlite_datetime(end_time),
+        ]
+
+        if provider:
+            query += " AND provider = ?"
+            params.append(provider)
+
+        if model:
+            query += " AND model = ?"
+            params.append(model)
+
+        query += " ORDER BY timestamp DESC, id DESC"
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(query, params)
+            rows = await cursor.fetchall()
+            return [dict(row) for row in rows]
+
+    async def get_provider_request_stats(self, provider: Optional[str] = None) -> Dict:
+        """聚合请求日志统计，可按提供商过滤。"""
+        query = """
+            SELECT
+                COUNT(*) as total_requests,
+                SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as successful_requests,
+                SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) as failed_requests,
+                SUM(input_tokens) as input_tokens,
+                SUM(output_tokens) as output_tokens,
+                SUM(total_tokens) as total_tokens,
+                SUM(cache_creation_tokens) as cache_creation_tokens,
+                SUM(cache_read_tokens) as cache_read_tokens,
+                SUM(
+                    CASE WHEN cache_creation_tokens > 0 THEN 1 ELSE 0 END
+                ) as cache_creation_requests,
+                SUM(
+                    CASE WHEN cache_read_tokens > 0 THEN 1 ELSE 0 END
+                ) as cache_hit_requests,
+                AVG(duration) as avg_duration,
+                AVG(
+                    CASE
+                        WHEN first_token_time > 0 THEN first_token_time
+                        ELSE NULL
+                    END
+                ) as avg_first_token_time
+            FROM request_logs
+        """
+        params: List[object] = []
+
+        if provider:
+            query += " WHERE provider = ?"
+            params.append(provider)
+
+        try:
+            async with self.get_connection() as conn:
+                cursor = await conn.execute(query, params)
+                row = await cursor.fetchone()
+
+            if not row:
+                return {
+                    "total_requests": 0,
+                    "successful_requests": 0,
+                    "failed_requests": 0,
+                    "input_tokens": 0,
+                    "output_tokens": 0,
+                    "total_tokens": 0,
+                    "cache_creation_tokens": 0,
+                    "cache_read_tokens": 0,
+                    "cache_creation_requests": 0,
+                    "cache_hit_requests": 0,
+                    "avg_duration": 0.0,
+                    "avg_first_token_time": 0.0,
+                }
+
+            return {
+                "total_requests": int(row["total_requests"] or 0),
+                "successful_requests": int(row["successful_requests"] or 0),
+                "failed_requests": int(row["failed_requests"] or 0),
+                "input_tokens": int(row["input_tokens"] or 0),
+                "output_tokens": int(row["output_tokens"] or 0),
+                "total_tokens": int(row["total_tokens"] or 0),
+                "cache_creation_tokens": int(
+                    row["cache_creation_tokens"] or 0
+                ),
+                "cache_read_tokens": int(row["cache_read_tokens"] or 0),
+                "cache_creation_requests": int(
+                    row["cache_creation_requests"] or 0
+                ),
+                "cache_hit_requests": int(row["cache_hit_requests"] or 0),
+                "avg_duration": float(row["avg_duration"] or 0.0),
+                "avg_first_token_time": float(
+                    row["avg_first_token_time"] or 0.0
+                ),
+            }
+        except Exception as e:
+            logger.error(f"❌ 获取请求统计失败: {e}")
+            return {
+                "total_requests": 0,
+                "successful_requests": 0,
+                "failed_requests": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "total_tokens": 0,
+                "cache_creation_tokens": 0,
+                "cache_read_tokens": 0,
+                "cache_creation_requests": 0,
+                "cache_hit_requests": 0,
+                "avg_duration": 0.0,
+                "avg_first_token_time": 0.0,
+            }
+
+    async def get_provider_usage_trend(
+        self,
+        provider: Optional[str] = None,
+        days: Optional[int] = None,
+        *,
+        window: Optional[str] = None,
+        now: Optional[datetime] = None,
+    ) -> List[Dict]:
+        """按窗口聚合最近一段时间的请求与 token 趋势。"""
+        trend_window = _normalize_trend_window(window, days)
+        current_time = now or datetime.utcnow()
+
+        if trend_window == "24h":
+            bucket_count = 24
+            current_hour = current_time.replace(
+                minute=0,
+                second=0,
+                microsecond=0,
+            )
+            start_time = current_hour - timedelta(hours=bucket_count - 1)
+            bucket_expression = "strftime('%Y-%m-%d %H:00:00', timestamp)"
+            row_key = "trend_bucket"
+            label_format = "%H:%M"
+            tooltip_format = "%Y-%m-%d %H:00"
+            rows = await self._query_usage_trend_rows(
+                provider,
+                start_time,
+                bucket_expression,
+                row_key,
+            )
+            rows_by_bucket = {str(row[row_key]): dict(row) for row in rows}
+            trend: List[Dict] = []
+
+            for offset in range(bucket_count):
+                bucket_time = start_time + timedelta(hours=offset)
+                bucket_key = bucket_time.strftime("%Y-%m-%d %H:00:00")
+                trend.append(
+                    self._build_usage_trend_point(
+                        row=rows_by_bucket.get(bucket_key, {}),
+                        bucket=bucket_key,
+                        label=bucket_time.strftime(label_format),
+                        tooltip_label=bucket_time.strftime(tooltip_format),
+                    )
+                )
+
+            return trend
+
+        bucket_count = 30 if trend_window == "30d" else 7
+        current_date = current_time.date()
+        start_date = current_date - timedelta(days=bucket_count - 1)
+        start_time = datetime.combine(start_date, datetime.min.time())
+        rows = await self._query_usage_trend_rows(
+            provider,
+            start_time,
+            "DATE(timestamp)",
+            "trend_bucket",
+        )
+        rows_by_bucket = {
+            str(row["trend_bucket"]): dict(row)
+            for row in rows
+        }
+        trend = []
+
+        for offset in range(bucket_count):
+            bucket_date = start_date + timedelta(days=offset)
+            bucket_key = bucket_date.isoformat()
+            trend.append(
+                self._build_usage_trend_point(
+                    row=rows_by_bucket.get(bucket_key, {}),
+                    bucket=bucket_key,
+                    label=bucket_date.strftime("%m-%d"),
+                    tooltip_label=bucket_date.strftime("%Y-%m-%d"),
+                )
+            )
+
+        return trend
+
+    async def _query_usage_trend_rows(
+        self,
+        provider: Optional[str],
+        start_time: datetime,
+        bucket_expression: str,
+        bucket_alias: str,
+    ) -> list[aiosqlite.Row]:
+        query = f"""
+            SELECT
+                {bucket_expression} as {bucket_alias},
+                COUNT(*) as total_requests,
+                SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as successful_requests,
+                SUM(input_tokens) as input_tokens,
+                SUM(output_tokens) as output_tokens,
+                SUM(total_tokens) as total_tokens,
+                SUM(cache_creation_tokens) as cache_creation_tokens,
+                SUM(cache_read_tokens) as cache_read_tokens
+            FROM request_logs
+            WHERE timestamp >= ?
+        """
+        params: List[object] = [_format_sqlite_datetime(start_time)]
+
+        if provider:
+            query += " AND provider = ?"
+            params.append(provider)
+
+        query += f" GROUP BY {bucket_expression} ORDER BY {bucket_alias} ASC"
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(query, params)
+            return await cursor.fetchall()
+
+    def _build_usage_trend_point(
+        self,
+        *,
+        row: Dict,
+        bucket: str,
+        label: str,
+        tooltip_label: str,
+    ) -> Dict:
+        total_requests = int(row.get("total_requests") or 0)
+        successful_requests = int(row.get("successful_requests") or 0)
+        cache_creation_tokens = int(row.get("cache_creation_tokens") or 0)
+        cache_read_tokens = int(row.get("cache_read_tokens") or 0)
+
+        return {
+            "bucket": bucket,
+            "label": label,
+            "tooltip_label": tooltip_label,
+            "total_requests": total_requests,
+            "successful_requests": successful_requests,
+            "failed_requests": max(0, total_requests - successful_requests),
+            "input_tokens": int(row.get("input_tokens") or 0),
+            "output_tokens": int(row.get("output_tokens") or 0),
+            "total_tokens": int(row.get("total_tokens") or 0),
+            "cache_creation_tokens": cache_creation_tokens,
+            "cache_read_tokens": cache_read_tokens,
+            "cache_total_tokens": (
+                cache_creation_tokens + cache_read_tokens
+            ),
+            "success_rate": round(
+                (
+                    successful_requests / total_requests * 100
+                ) if total_requests > 0 else 0,
+                1,
+            ),
+        }
+
+    async def get_model_stats_from_db(self, hours: int = 24) -> Dict:
+        """
+        从数据库获取模型统计（最近N小时）
+
+        Args:
+            hours: 小时数
+
+        Returns:
+            模型统计数据
+        """
+        start_time = datetime.utcnow() - timedelta(hours=hours)
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(
+                """
+                SELECT
+                    model,
+                    COUNT(*) as total,
+                    SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success,
+                    SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) as failed,
+                    SUM(input_tokens) as input_tokens,
+                    SUM(output_tokens) as output_tokens,
+                    SUM(total_tokens) as total_tokens,
+                    AVG(duration) as avg_duration,
+                    AVG(first_token_time) as avg_first_token_time
+                FROM request_logs
+                WHERE timestamp >= ?
+                GROUP BY model
+                ORDER BY total DESC
+                """,
+                (_format_sqlite_datetime(start_time),)
+            )
+            rows = await cursor.fetchall()
+
+            result = {}
+            for row in rows:
+                model = row['model']
+                result[model] = {
+                    'total': row['total'],
+                    'success': row['success'],
+                    'failed': row['failed'],
+                    'input_tokens': row['input_tokens'] or 0,
+                    'output_tokens': row['output_tokens'] or 0,
+                    'total_tokens': row['total_tokens'] or 0,
+                    'avg_duration': round(row['avg_duration'] or 0, 2),
+                    'avg_first_token_time': round(row['avg_first_token_time'] or 0, 2),
+                    'success_rate': round(
+                        (row['success'] / row['total'] * 100)
+                        if row['total'] > 0
+                        else 0,
+                        1,
+                    ),
+                }
+
+            return result
+
+    async def delete_old_logs(self, days: int = 30) -> int:
+        """
+        删除旧日志
+
+        Args:
+            days: 保留天数
+
+        Returns:
+            删除的记录数
+        """
+        cutoff_time = datetime.utcnow() - timedelta(days=days)
+
+        async with self.get_connection() as conn:
+            cursor = await conn.execute(
+                "DELETE FROM request_logs WHERE timestamp < ?",
+                (_format_sqlite_datetime(cutoff_time),)
+            )
+            await conn.commit()
+            return cursor.rowcount
+
+
+# 全局单例实例
+_request_log_dao: Optional[RequestLogDAO] = None
+
+
+def get_request_log_dao() -> RequestLogDAO:
+    """
+    获取请求日志 DAO 单例
+
+    Returns:
+        RequestLogDAO 实例
+    """
+    global _request_log_dao
+    if _request_log_dao is None:
+        _request_log_dao = RequestLogDAO()
+    return _request_log_dao
+
+
+def init_request_log_dao():
+    """初始化请求日志 DAO"""
+    global _request_log_dao
+    _request_log_dao = RequestLogDAO()
+    return _request_log_dao

app/services/token_automation.py

@@ -0,0 +1,278 @@
+"""Background automation for token import and maintenance."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Optional
+
+from app.core.config import settings
+from app.services.token_dao import TokenDAO, get_token_dao
+from app.services.token_importer import TokenImportSummary, import_tokens_from_directory
+from app.utils.logger import logger
+from app.utils.token_pool import TokenPool, get_token_pool
+
+DEFAULT_TOKEN_PROVIDER = "zai"
+_AUTO_IMPORT_LOCK = asyncio.Lock()
+_AUTO_MAINTENANCE_LOCK = asyncio.Lock()
+
+
+@dataclass(frozen=True)
+class TokenMaintenanceSummary:
+    provider: str
+    checked_count: int = 0
+    duplicate_removed_count: int = 0
+    valid_count: int = 0
+    guest_count: int = 0
+    invalid_count: int = 0
+    deleted_invalid_count: int = 0
+
+
+async def run_directory_import(
+    source_dir: str,
+    *,
+    provider: str = DEFAULT_TOKEN_PROVIDER,
+    validate: bool = True,
+    dao: Optional[TokenDAO] = None,
+    pool: Optional[TokenPool] = None,
+) -> TokenImportSummary:
+    """Import tokens from a configured directory and refresh the pool if needed."""
+    if _AUTO_IMPORT_LOCK.locked():
+        raise RuntimeError("目录导入任务正在执行，请稍后再试")
+
+    async with _AUTO_IMPORT_LOCK:
+        summary = await import_tokens_from_directory(
+            source_dir,
+            provider=provider,
+            validate=validate,
+            dao=dao,
+        )
+
+        active_pool = pool if pool is not None else get_token_pool()
+        if active_pool and summary.imported_count > 0:
+            await active_pool.sync_from_database(provider)
+            logger.info("✅ 目录导入后已同步 Token 池")
+
+        return summary
+
+
+async def run_token_maintenance(
+    *,
+    provider: str = DEFAULT_TOKEN_PROVIDER,
+    remove_duplicates: bool = True,
+    run_health_check: bool = True,
+    delete_invalid_tokens: bool = False,
+    dao: Optional[TokenDAO] = None,
+    pool: Optional[TokenPool] = None,
+) -> TokenMaintenanceSummary:
+    """Run dedupe, validation, and invalid-token cleanup as one maintenance cycle."""
+    if _AUTO_MAINTENANCE_LOCK.locked():
+        raise RuntimeError("Token 自动维护任务正在执行，请稍后再试")
+
+    token_dao = dao or get_token_dao()
+    duplicate_removed_count = 0
+    checked_count = 0
+    valid_count = 0
+    guest_count = 0
+    invalid_count = 0
+    deleted_invalid_count = 0
+
+    async with _AUTO_MAINTENANCE_LOCK:
+        if remove_duplicates:
+            duplicate_removed_count = await token_dao.remove_duplicate_tokens(provider)
+
+        should_validate = run_health_check or delete_invalid_tokens
+        invalid_token_ids: list[int] = []
+
+        if should_validate:
+            validation_result = await token_dao.validate_tokens_detailed(provider)
+            checked_count = int(validation_result.get("checked", 0) or 0)
+            valid_count = int(validation_result.get("valid", 0) or 0)
+            guest_count = int(validation_result.get("guest", 0) or 0)
+            invalid_count = int(validation_result.get("invalid", 0) or 0)
+            invalid_token_ids = list(
+                validation_result.get("invalid_token_ids", []) or []
+            )
+
+        if delete_invalid_tokens and invalid_token_ids:
+            deleted_invalid_count = await token_dao.delete_tokens_by_ids(
+                invalid_token_ids
+            )
+
+        active_pool = pool if pool is not None else get_token_pool()
+        if active_pool:
+            await active_pool.sync_from_database(provider)
+            logger.info("✅ Token 维护后已同步 Token 池")
+
+    return TokenMaintenanceSummary(
+        provider=provider,
+        checked_count=checked_count,
+        duplicate_removed_count=duplicate_removed_count,
+        valid_count=valid_count,
+        guest_count=guest_count,
+        invalid_count=invalid_count,
+        deleted_invalid_count=deleted_invalid_count,
+    )
+
+
+class TokenAutomationScheduler:
+    """Run token import and maintenance loops in the application background."""
+
+    def __init__(self) -> None:
+        self._stop_event = asyncio.Event()
+        self._tasks: list[asyncio.Task] = []
+        self._import_warning: Optional[str] = None
+        self._maintenance_warning: Optional[str] = None
+
+    async def start(self) -> None:
+        if self._tasks:
+            return
+
+        self._stop_event.clear()
+        self._tasks = [
+            asyncio.create_task(
+                self._auto_import_loop(),
+                name="token-auto-import",
+            ),
+            asyncio.create_task(
+                self._auto_maintenance_loop(),
+                name="token-auto-maintenance",
+            ),
+        ]
+        logger.info("✅ Token 自动任务调度器已启动")
+
+    async def stop(self) -> None:
+        if not self._tasks:
+            return
+
+        self._stop_event.set()
+        for task in self._tasks:
+            task.cancel()
+
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()
+        self._import_warning = None
+        self._maintenance_warning = None
+        logger.info("🛑 Token 自动任务调度器已停止")
+
+    async def _auto_import_loop(self) -> None:
+        while not self._stop_event.is_set():
+            wait_seconds = 15
+            try:
+                if settings.TOKEN_AUTO_IMPORT_ENABLED:
+                    wait_seconds = max(int(settings.TOKEN_AUTO_IMPORT_INTERVAL), 30)
+                    source_dir = settings.TOKEN_AUTO_IMPORT_SOURCE_DIR.strip()
+                    if not source_dir:
+                        self._log_import_warning_once(
+                            "已启用自动导入，但未配置导入目录"
+                        )
+                    else:
+                        self._import_warning = None
+                        summary = await run_directory_import(
+                            source_dir,
+                            provider=DEFAULT_TOKEN_PROVIDER,
+                        )
+                        logger.info(
+                            "🔄 自动导入完成: scanned={} imported={} duplicate={} invalid={}",
+                            summary.scanned_files,
+                            summary.imported_count,
+                            summary.duplicate_count,
+                            summary.invalid_json_count + summary.invalid_token_count,
+                        )
+            except asyncio.CancelledError:
+                raise
+            except RuntimeError as exc:
+                logger.info(f"⏭️ 跳过本轮自动导入: {exc}")
+            except (FileNotFoundError, NotADirectoryError) as exc:
+                self._log_import_warning_once(str(exc))
+            except Exception as exc:
+                logger.exception(f"❌ 自动导入 Token 失败: {exc}")
+
+            await self._wait_or_stop(wait_seconds)
+
+    async def _auto_maintenance_loop(self) -> None:
+        while not self._stop_event.is_set():
+            wait_seconds = 15
+            try:
+                if settings.TOKEN_AUTO_MAINTENANCE_ENABLED:
+                    wait_seconds = max(
+                        int(settings.TOKEN_AUTO_MAINTENANCE_INTERVAL),
+                        30,
+                    )
+                    if not self._has_enabled_maintenance_action():
+                        self._log_maintenance_warning_once(
+                            "已启用自动维护，但未选择任何维护动作"
+                        )
+                    else:
+                        self._maintenance_warning = None
+                        summary = await run_token_maintenance(
+                            provider=DEFAULT_TOKEN_PROVIDER,
+                            remove_duplicates=settings.TOKEN_AUTO_REMOVE_DUPLICATES,
+                            run_health_check=settings.TOKEN_AUTO_HEALTH_CHECK,
+                            delete_invalid_tokens=settings.TOKEN_AUTO_DELETE_INVALID,
+                        )
+                        logger.info(
+                            "🧹 自动维护完成: dedupe={} checked={} valid={} guest={} invalid={} deleted={}",
+                            summary.duplicate_removed_count,
+                            summary.checked_count,
+                            summary.valid_count,
+                            summary.guest_count,
+                            summary.invalid_count,
+                            summary.deleted_invalid_count,
+                        )
+            except asyncio.CancelledError:
+                raise
+            except RuntimeError as exc:
+                logger.info(f"⏭️ 跳过本轮自动维护: {exc}")
+            except Exception as exc:
+                logger.exception(f"❌ Token 自动维护失败: {exc}")
+
+            await self._wait_or_stop(wait_seconds)
+
+    async def _wait_or_stop(self, timeout: int) -> None:
+        try:
+            await asyncio.wait_for(self._stop_event.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return
+
+    def _has_enabled_maintenance_action(self) -> bool:
+        return any(
+            (
+                settings.TOKEN_AUTO_REMOVE_DUPLICATES,
+                settings.TOKEN_AUTO_HEALTH_CHECK,
+                settings.TOKEN_AUTO_DELETE_INVALID,
+            )
+        )
+
+    def _log_import_warning_once(self, message: str) -> None:
+        if self._import_warning == message:
+            return
+        self._import_warning = message
+        logger.warning(f"⚠️ {message}")
+
+    def _log_maintenance_warning_once(self, message: str) -> None:
+        if self._maintenance_warning == message:
+            return
+        self._maintenance_warning = message
+        logger.warning(f"⚠️ {message}")
+
+
+_scheduler: Optional[TokenAutomationScheduler] = None
+
+
+def get_token_automation_scheduler() -> TokenAutomationScheduler:
+    global _scheduler
+    if _scheduler is None:
+        _scheduler = TokenAutomationScheduler()
+    return _scheduler
+
+
+async def start_token_automation_scheduler() -> None:
+    await get_token_automation_scheduler().start()
+
+
+async def stop_token_automation_scheduler() -> None:
+    global _scheduler
+    if _scheduler is None:
+        return
+    await _scheduler.stop()

app/services/token_dao.py

@@ -0,0 +1,664 @@
+"""
+Token 数据访问层 (DAO)
+提供 Token 的 CRUD 操作和查询功能
+"""
+import os
+import sqlite3
+from contextlib import asynccontextmanager
+from typing import Any, Dict, List, Optional, Tuple
+
+import aiosqlite
+
+from app.models.token_db import DB_PATH, SQL_CREATE_TABLES
+from app.utils.logger import logger
+
+
+class TokenDAO:
+    """Token 数据访问对象"""
+
+    def __init__(self, db_path: str = DB_PATH):
+        """初始化 DAO"""
+        self.db_path = db_path
+        self._ensure_db_directory()
+
+    def _ensure_db_directory(self):
+        """确保数据库目录存在"""
+        db_dir = os.path.dirname(self.db_path)
+        if db_dir and not os.path.exists(db_dir):
+            os.makedirs(db_dir, exist_ok=True)
+
+    @asynccontextmanager
+    async def get_connection(self):
+        """获取异步数据库连接"""
+        conn = await aiosqlite.connect(self.db_path)
+        conn.row_factory = aiosqlite.Row  # 返回字典式结果
+
+        # 启用外键约束（SQLite 默认关闭）
+        await conn.execute("PRAGMA foreign_keys = ON")
+
+        try:
+            yield conn
+        finally:
+            await conn.close()
+
+    def get_sync_connection(self):
+        """获取同步数据库连接（用于初始化）"""
+        conn = sqlite3.connect(self.db_path)
+        # 启用外键约束
+        conn.execute("PRAGMA foreign_keys = ON")
+        return conn
+
+    async def init_database(self):
+        """初始化数据库表结构"""
+        try:
+            # 使用同步连接创建表（避免异步初始化问题）
+            conn = self.get_sync_connection()
+            conn.executescript(SQL_CREATE_TABLES)
+            conn.commit()
+            conn.close()
+        except Exception as e:
+            logger.error(f"❌ Token 数据库初始化失败: {e}")
+            raise
+
+    # ==================== Token CRUD 操作 ====================
+
+    async def add_token(
+        self,
+        provider: str,
+        token: str,
+        token_type: str = "user",
+        priority: int = 0,
+        validate: bool = True
+    ) -> Optional[int]:
+        """
+        添加新 Token（可选验证）
+
+        Args:
+            provider: 提供商名称
+            token: Token 值
+            token_type: Token 类型（如果 validate=True 将被验证结果覆盖）
+            priority: 优先级
+            validate: 是否验证 Token（仅针对 zai 提供商）
+
+        Returns:
+            token_id 或 None（验证失败或已存在）
+        """
+        try:
+            # 对于 zai 提供商，强制验证 Token
+            if provider == "zai" and validate:
+                from app.utils.token_pool import ZAITokenValidator
+
+                validated_type, is_valid, error_msg = await ZAITokenValidator.validate_token(token)
+
+                # 拒绝 guest token
+                if validated_type == "guest":
+                    logger.warning(f"🚫 拒绝添加匿名用户 Token: {token[:20]}... - {error_msg}")
+                    return None
+
+                # 拒绝无效 token
+                if not is_valid:
+                    logger.warning(f"🚫 Token 验证失败: {token[:20]}... - {error_msg}")
+                    return None
+
+                # 使用验证后的类型
+                token_type = validated_type
+
+            async with self.get_connection() as conn:
+                cursor = await conn.execute("""
+                    INSERT OR IGNORE INTO tokens (provider, token, token_type, priority)
+                    VALUES (?, ?, ?, ?)
+                """, (provider, token, token_type, priority))
+
+                await conn.commit()
+
+                if cursor.lastrowid > 0:
+                    # 同时创建统计记录
+                    await conn.execute("""
+                        INSERT INTO token_stats (token_id)
+                        VALUES (?)
+                    """, (cursor.lastrowid,))
+                    await conn.commit()
+                    logger.info(f"✅ 添加 Token: {provider} ({token_type}) - {token[:20]}...")
+                    return cursor.lastrowid
+                else:
+                    logger.warning(f"⚠️ Token 已存在: {provider} - {token[:20]}...")
+                    return None
+        except Exception as e:
+            logger.error(f"❌ 添加 Token 失败: {e}")
+            return None
+
+    async def get_tokens_by_provider(
+        self,
+        provider: str,
+        enabled_only: bool = True,
+        limit: Optional[int] = None,
+        offset: int = 0,
+    ) -> List[Dict]:
+        """
+        获取指定提供商的所有 Token
+
+        Args:
+            provider: 提供商名称
+            enabled_only: 是否只返回启用的 Token
+        """
+        try:
+            async with self.get_connection() as conn:
+                query = """
+                    SELECT t.*, ts.total_requests, ts.successful_requests, ts.failed_requests,
+                           ts.last_success_time, ts.last_failure_time
+                    FROM tokens t
+                    LEFT JOIN token_stats ts ON t.id = ts.token_id
+                    WHERE t.provider = ?
+                """
+                params = [provider]
+
+                if enabled_only:
+                    query += " AND t.is_enabled = 1"
+
+                query += " ORDER BY t.priority DESC, t.id ASC"
+
+                if limit is not None:
+                    query += " LIMIT ? OFFSET ?"
+                    params.extend([limit, max(0, offset)])
+
+                cursor = await conn.execute(query, params)
+                rows = await cursor.fetchall()
+
+                return [dict(row) for row in rows]
+        except Exception as e:
+            logger.error(f"❌ 查询 Token 失败: {e}")
+            return []
+
+    async def get_all_tokens(self, enabled_only: bool = False) -> List[Dict]:
+        """获取所有 Token"""
+        try:
+            async with self.get_connection() as conn:
+                query = """
+                    SELECT t.*, ts.total_requests, ts.successful_requests, ts.failed_requests,
+                           ts.last_success_time, ts.last_failure_time
+                    FROM tokens t
+                    LEFT JOIN token_stats ts ON t.id = ts.token_id
+                """
+
+                if enabled_only:
+                    query += " WHERE t.is_enabled = 1"
+
+                query += " ORDER BY t.provider, t.priority DESC, t.id ASC"
+
+                cursor = await conn.execute(query)
+                rows = await cursor.fetchall()
+
+                return [dict(row) for row in rows]
+        except Exception as e:
+            logger.error(f"❌ 查询所有 Token 失败: {e}")
+            return []
+
+    async def update_token_status(self, token_id: int, is_enabled: bool):
+        """更新 Token 启用状态"""
+        try:
+            async with self.get_connection() as conn:
+                await conn.execute("""
+                    UPDATE tokens SET is_enabled = ? WHERE id = ?
+                """, (is_enabled, token_id))
+                await conn.commit()
+                logger.info(f"✅ 更新 Token 状态: id={token_id}, enabled={is_enabled}")
+        except Exception as e:
+            logger.error(f"❌ 更新 Token 状态失败: {e}")
+
+    async def update_token_type(self, token_id: int, token_type: str):
+        """更新 Token 类型"""
+        try:
+            async with self.get_connection() as conn:
+                await conn.execute("""
+                    UPDATE tokens SET token_type = ? WHERE id = ?
+                """, (token_type, token_id))
+                await conn.commit()
+                logger.info(f"✅ 更新 Token 类型: id={token_id}, type={token_type}")
+        except Exception as e:
+            logger.error(f"❌ 更新 Token 类型失败: {e}")
+
+    async def delete_token(self, token_id: int):
+        """删除 Token（级联删除统计数据）"""
+        try:
+            async with self.get_connection() as conn:
+                await conn.execute("DELETE FROM tokens WHERE id = ?", (token_id,))
+                await conn.commit()
+                logger.info(f"✅ 删除 Token: id={token_id}")
+        except Exception as e:
+            logger.error(f"❌ 删除 Token 失败: {e}")
+
+    async def delete_tokens_by_ids(self, token_ids: List[int]) -> int:
+        """批量删除 Token（级联删除统计数据）"""
+        if not token_ids:
+            return 0
+
+        try:
+            placeholders = ",".join("?" for _ in token_ids)
+            async with self.get_connection() as conn:
+                await conn.execute(
+                    f"DELETE FROM tokens WHERE id IN ({placeholders})",
+                    token_ids,
+                )
+                cursor = await conn.execute("SELECT changes()")
+                row = await cursor.fetchone()
+                await conn.commit()
+
+            deleted_count = int(row[0] if row else 0)
+            logger.info(f"✅ 批量删除 Token: {deleted_count} 个")
+            return deleted_count
+        except Exception as e:
+            logger.error(f"❌ 批量删除 Token 失败: {e}")
+            return 0
+
+    async def delete_tokens_by_provider(self, provider: str):
+        """删除指定提供商的所有 Token"""
+        try:
+            async with self.get_connection() as conn:
+                await conn.execute("DELETE FROM tokens WHERE provider = ?", (provider,))
+                await conn.commit()
+                logger.info(f"✅ 删除提供商所有 Token: {provider}")
+        except Exception as e:
+            logger.error(f"❌ 删除提供商 Token 失败: {e}")
+
+    # ==================== Token 统计操作 ====================
+
+    async def record_success(self, token_id: int):
+        """记录 Token 使用成功"""
+        try:
+            async with self.get_connection() as conn:
+                await conn.execute("""
+                    UPDATE token_stats
+                    SET total_requests = total_requests + 1,
+                        successful_requests = successful_requests + 1,
+                        last_success_time = CURRENT_TIMESTAMP
+                    WHERE token_id = ?
+                """, (token_id,))
+                await conn.commit()
+        except Exception as e:
+            logger.error(f"❌ 记录成功失败: {e}")
+
+    async def record_failure(self, token_id: int):
+        """记录 Token 使用失败"""
+        try:
+            async with self.get_connection() as conn:
+                await conn.execute("""
+                    UPDATE token_stats
+                    SET total_requests = total_requests + 1,
+                        failed_requests = failed_requests + 1,
+                        last_failure_time = CURRENT_TIMESTAMP
+                    WHERE token_id = ?
+                """, (token_id,))
+                await conn.commit()
+        except Exception as e:
+            logger.error(f"❌ 记录失败失败: {e}")
+
+    async def get_token_stats(self, token_id: int) -> Optional[Dict]:
+        """获取 Token 统计信息"""
+        try:
+            async with self.get_connection() as conn:
+                cursor = await conn.execute("""
+                    SELECT * FROM token_stats WHERE token_id = ?
+                """, (token_id,))
+                row = await cursor.fetchone()
+                return dict(row) if row else None
+        except Exception as e:
+            logger.error(f"❌ 获取统计信息失败: {e}")
+            return None
+
+    # ==================== 批量操作 ====================
+
+    async def bulk_add_tokens(
+        self,
+        provider: str,
+        tokens: List[str],
+        token_type: str = "user",
+        validate: bool = True
+    ) -> Tuple[int, int]:
+        """
+        批量添加 Token（可选验证）
+
+        Args:
+            provider: 提供商名称
+            tokens: Token 列表
+            token_type: Token 类型（如果 validate=True 将被覆盖）
+            validate: 是否验证 Token（仅针对 zai）
+
+        Returns:
+            (成功添加数量, 失败数量)
+        """
+        added_count = 0
+        failed_count = 0
+
+        for token in tokens:
+            if token.strip():  # 过滤空 token
+                token_id = await self.add_token(
+                    provider,
+                    token.strip(),
+                    token_type,
+                    validate=validate
+                )
+                if token_id:
+                    added_count += 1
+                else:
+                    failed_count += 1
+
+        logger.info(f"✅ 批量添加完成: {provider} - 成功 {added_count}/{len(tokens)}，失败 {failed_count}")
+        return added_count, failed_count
+
+    async def replace_tokens(self, provider: str, tokens: List[str],
+                            token_type: str = "user"):
+        """
+        替换指定提供商的所有 Token（先删除后添加）
+        """
+        # 删除旧 Token
+        await self.delete_tokens_by_provider(provider)
+
+        # 添加新 Token
+        added_count = await self.bulk_add_tokens(provider, tokens, token_type)
+
+        logger.info(f"✅ 替换 Token 完成: {provider} - {added_count} 个")
+        return added_count
+
+    async def remove_duplicate_tokens(self, provider: Optional[str] = None) -> int:
+        """
+        删除重复 Token，保留每个 provider/token 组合中排序靠前的一条记录。
+
+        正常情况下唯一约束会阻止重复数据，这里主要处理历史数据或手工导入异常。
+        """
+        try:
+            tokens = (
+                await self.get_tokens_by_provider(provider, enabled_only=False)
+                if provider
+                else await self.get_all_tokens(enabled_only=False)
+            )
+
+            seen_keys: set[tuple[str, str]] = set()
+            duplicate_ids: list[int] = []
+
+            for token_record in tokens:
+                token_value = str(token_record.get("token") or "").strip()
+                token_provider = str(token_record.get("provider") or "")
+                key = (token_provider, token_value)
+
+                if key in seen_keys:
+                    duplicate_ids.append(int(token_record["id"]))
+                    continue
+
+                seen_keys.add(key)
+
+            deleted_count = await self.delete_tokens_by_ids(duplicate_ids)
+            if deleted_count > 0:
+                logger.info(f"✅ 已清理重复 Token: {deleted_count} 个")
+            return deleted_count
+        except Exception as e:
+            logger.error(f"❌ 清理重复 Token 失败: {e}")
+            return 0
+
+    # ==================== 实用方法 ====================
+
+    async def get_token_by_value(self, provider: str, token: str) -> Optional[Dict]:
+        """根据 Token 值查询"""
+        try:
+            async with self.get_connection() as conn:
+                cursor = await conn.execute("""
+                    SELECT t.*, ts.total_requests, ts.successful_requests, ts.failed_requests
+                    FROM tokens t
+                    LEFT JOIN token_stats ts ON t.id = ts.token_id
+                    WHERE t.provider = ? AND t.token = ?
+                """, (provider, token))
+                row = await cursor.fetchone()
+                return dict(row) if row else None
+        except Exception as e:
+            logger.error(f"❌ 查询 Token 失败: {e}")
+            return None
+
+    async def get_provider_stats(self, provider: str) -> Dict:
+        """获取提供商统计信息"""
+        try:
+            async with self.get_connection() as conn:
+                cursor = await conn.execute("""
+                    SELECT
+                        COUNT(*) as total_tokens,
+                        SUM(CASE WHEN is_enabled = 1 THEN 1 ELSE 0 END) as enabled_tokens,
+                        SUM(ts.total_requests) as total_requests,
+                        SUM(ts.successful_requests) as successful_requests,
+                        SUM(ts.failed_requests) as failed_requests
+                    FROM tokens t
+                    LEFT JOIN token_stats ts ON t.id = ts.token_id
+                    WHERE t.provider = ?
+                """, (provider,))
+                row = await cursor.fetchone()
+                return dict(row) if row else {}
+        except Exception as e:
+            logger.error(f"❌ 获取提供商统计失败: {e}")
+            return {}
+
+    async def get_provider_token_counts(self, provider: str) -> Dict[str, int]:
+        """聚合提供商的 Token 数量与类型分布。"""
+        try:
+            async with self.get_connection() as conn:
+                cursor = await conn.execute(
+                    """
+                    SELECT
+                        COUNT(*) as total_tokens,
+                        SUM(CASE WHEN is_enabled = 1 THEN 1 ELSE 0 END) as enabled_tokens,
+                        SUM(CASE WHEN token_type = 'user' THEN 1 ELSE 0 END) as user_tokens,
+                        SUM(CASE WHEN token_type = 'guest' THEN 1 ELSE 0 END) as guest_tokens,
+                        SUM(CASE WHEN token_type = 'unknown' THEN 1 ELSE 0 END) as unknown_tokens
+                    FROM tokens
+                    WHERE provider = ?
+                    """,
+                    (provider,),
+                )
+                row = await cursor.fetchone()
+
+            if not row:
+                return {
+                    "total_tokens": 0,
+                    "enabled_tokens": 0,
+                    "user_tokens": 0,
+                    "guest_tokens": 0,
+                    "unknown_tokens": 0,
+                }
+
+            return {
+                "total_tokens": int(row["total_tokens"] or 0),
+                "enabled_tokens": int(row["enabled_tokens"] or 0),
+                "user_tokens": int(row["user_tokens"] or 0),
+                "guest_tokens": int(row["guest_tokens"] or 0),
+                "unknown_tokens": int(row["unknown_tokens"] or 0),
+            }
+        except Exception as e:
+            logger.error(f"❌ 获取 Token 数量统计失败: {e}")
+            return {
+                "total_tokens": 0,
+                "enabled_tokens": 0,
+                "user_tokens": 0,
+                "guest_tokens": 0,
+                "unknown_tokens": 0,
+            }
+
+    async def count_tokens_by_provider(
+        self,
+        provider: str,
+        enabled_only: bool = False,
+    ) -> int:
+        """统计提供商下的 Token 总数。"""
+        try:
+            async with self.get_connection() as conn:
+                query = "SELECT COUNT(*) AS total_count FROM tokens WHERE provider = ?"
+                params: List[object] = [provider]
+                if enabled_only:
+                    query += " AND is_enabled = 1"
+
+                cursor = await conn.execute(query, params)
+                row = await cursor.fetchone()
+
+            return int(row["total_count"] or 0) if row else 0
+        except Exception as e:
+            logger.error(f"❌ 统计 Token 总数失败: {e}")
+            return 0
+
+    # ==================== Token 验证操作 ====================
+
+    async def validate_and_update_token(self, token_id: int) -> bool:
+        """
+        验证单个 Token 并更新其类型
+
+        Args:
+            token_id: Token 数据库 ID
+
+        Returns:
+            是否为有效的认证用户 Token
+        """
+        try:
+            # 获取 Token 信息
+            async with self.get_connection() as conn:
+                cursor = await conn.execute("""
+                    SELECT provider, token FROM tokens WHERE id = ?
+                """, (token_id,))
+                row = await cursor.fetchone()
+
+                if not row:
+                    logger.error(f"❌ Token ID {token_id} 不存在")
+                    return False
+
+                provider = row["provider"]
+                token = row["token"]
+
+            if provider != "zai":
+                logger.info(f"⏭️ 跳过非 zai 提供商的 Token 验证: {provider}")
+                return True
+
+            # 验证 Token
+            from app.utils.token_pool import ZAITokenValidator
+
+            token_type, is_valid, error_msg = await ZAITokenValidator.validate_token(token)
+
+            # 更新 Token 类型
+            await self.update_token_type(token_id, token_type)
+
+            if not is_valid:
+                logger.warning(f"⚠️ Token 验证失败: id={token_id}, type={token_type}, error={error_msg}")
+
+            return is_valid
+
+        except Exception as e:
+            logger.error(f"❌ 验证 Token 失败: {e}")
+            return False
+
+    async def validate_tokens_detailed(self, provider: str = "zai") -> Dict[str, Any]:
+        """
+        批量验证所有 Token，并返回详细结果。
+
+        Returns:
+            {
+                "checked": 数量,
+                "valid": 数量,
+                "guest": 数量,
+                "invalid": 数量,
+                "invalid_token_ids": [id, ...],
+            }
+        """
+        try:
+            tokens = await self.get_tokens_by_provider(provider, enabled_only=False)
+
+            if not tokens:
+                logger.warning(f"⚠️ 没有需要验证的 {provider} Token")
+                return {
+                    "checked": 0,
+                    "valid": 0,
+                    "guest": 0,
+                    "invalid": 0,
+                    "invalid_token_ids": [],
+                }
+
+            logger.info(f"🔍 开始批量验证 {len(tokens)} 个 {provider} Token...")
+
+            from app.utils.token_pool import ZAITokenValidator
+
+            stats: Dict[str, Any] = {
+                "checked": len(tokens),
+                "valid": 0,
+                "guest": 0,
+                "invalid": 0,
+                "invalid_token_ids": [],
+            }
+
+            for token_record in tokens:
+                token_id = int(token_record["id"])
+                token = str(token_record["token"])
+
+                token_type, is_valid, error_msg = await ZAITokenValidator.validate_token(
+                    token
+                )
+                await self.update_token_type(token_id, token_type)
+
+                if token_type == "user" and is_valid:
+                    stats["valid"] += 1
+                elif token_type == "guest":
+                    stats["guest"] += 1
+                    stats["invalid_token_ids"].append(token_id)
+                else:
+                    stats["invalid"] += 1
+                    stats["invalid_token_ids"].append(token_id)
+                    if error_msg:
+                        logger.warning(
+                            "⚠️ Token 验证失败: id={}, type={}, error={}",
+                            token_id,
+                            token_type,
+                            error_msg,
+                        )
+
+            logger.info(
+                "✅ 批量验证完成: 有效 {}, 匿名 {}, 无效 {}",
+                stats["valid"],
+                stats["guest"],
+                stats["invalid"],
+            )
+            return stats
+
+        except Exception as e:
+            logger.error(f"❌ 批量验证失败: {e}")
+            return {
+                "checked": 0,
+                "valid": 0,
+                "guest": 0,
+                "invalid": 0,
+                "invalid_token_ids": [],
+            }
+
+    async def validate_all_tokens(self, provider: str = "zai") -> Dict[str, int]:
+        """
+        批量验证所有 Token
+
+        Args:
+            provider: 提供商名称（默认 zai）
+
+        Returns:
+            统计结果 {"valid": 数量, "guest": 数量, "invalid": 数量}
+        """
+        stats = await self.validate_tokens_detailed(provider)
+        return {
+            "valid": int(stats.get("valid", 0) or 0),
+            "guest": int(stats.get("guest", 0) or 0),
+            "invalid": int(stats.get("invalid", 0) or 0),
+        }
+
+
+# 全局单例
+_token_dao: Optional[TokenDAO] = None
+
+
+def get_token_dao() -> TokenDAO:
+    """获取全局 TokenDAO 实例"""
+    global _token_dao
+    if _token_dao is None:
+        _token_dao = TokenDAO()
+    return _token_dao
+
+
+async def init_token_database():
+    """初始化 Token 数据库"""
+    dao = get_token_dao()
+    await dao.init_database()

app/services/token_importer.py

@@ -0,0 +1,138 @@
+"""本地目录 token 导入服务。"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from app.services.token_dao import TokenDAO, get_token_dao
+from app.utils.logger import logger
+
+
+@dataclass(frozen=True)
+class TokenImportSummary:
+    source_dir: str
+    scanned_files: int
+    imported_count: int
+    duplicate_count: int
+    invalid_json_count: int
+    missing_token_count: int
+    invalid_token_count: int
+
+    @property
+    def failed_count(self) -> int:
+        return (
+            self.duplicate_count
+            + self.invalid_json_count
+            + self.missing_token_count
+            + self.invalid_token_count
+        )
+
+
+def _load_token_payload(file_path: Path) -> dict:
+    try:
+        return json.loads(file_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"JSON 解析失败: {exc}") from exc
+
+
+async def import_tokens_from_directory(
+    source_dir: str | Path,
+    *,
+    provider: str = "zai",
+    validate: bool = True,
+    dao: Optional[TokenDAO] = None,
+) -> TokenImportSummary:
+    """
+    从本地目录导入 token。
+
+    目录中的每个 JSON 文件应至少包含 `token` 字段。
+    """
+    source_path = Path(source_dir).expanduser().resolve()
+    if not source_path.exists():
+        raise FileNotFoundError(f"导入目录不存在: {source_path}")
+    if not source_path.is_dir():
+        raise NotADirectoryError(f"导入路径不是目录: {source_path}")
+
+    token_dao = dao or get_token_dao()
+    token_files = sorted(source_path.rglob("*.json"))
+    seen_tokens: set[str] = set()
+    imported_count = 0
+    duplicate_count = 0
+    invalid_json_count = 0
+    missing_token_count = 0
+    invalid_token_count = 0
+
+    for file_path in token_files:
+        try:
+            payload = _load_token_payload(file_path)
+        except ValueError as exc:
+            invalid_json_count += 1
+            logger.warning(f"⚠️ 跳过无效 JSON 文件: {file_path} - {exc}")
+            continue
+
+        if not isinstance(payload, dict):
+            invalid_json_count += 1
+            logger.warning(f"⚠️ 跳过非对象 JSON 文件: {file_path}")
+            continue
+
+        token = str(payload.get("token") or "").strip()
+        email = str(payload.get("email") or "").strip()
+        if not token:
+            missing_token_count += 1
+            logger.warning(f"⚠️ 文件缺少 token 字段: {file_path}")
+            continue
+
+        if token in seen_tokens:
+            duplicate_count += 1
+            logger.info(f"↩️ 跳过本批次重复 Token: {file_path.name}")
+            continue
+        seen_tokens.add(token)
+
+        existing = await token_dao.get_token_by_value(provider, token)
+        if existing is not None:
+            duplicate_count += 1
+            logger.info(
+                "↩️ Token 已存在，跳过导入: {} ({})",
+                file_path.name,
+                email or "unknown",
+            )
+            continue
+
+        token_id = await token_dao.add_token(
+            provider=provider,
+            token=token,
+            token_type="user",
+            validate=validate,
+        )
+        if token_id is None:
+            invalid_token_count += 1
+            logger.warning(f"⚠️ Token 导入失败: {file_path.name} ({email or 'unknown'})")
+            continue
+
+        imported_count += 1
+        logger.info(f"✅ 已导入 Token: {file_path.name} ({email or 'unknown'})")
+
+    summary = TokenImportSummary(
+        source_dir=str(source_path),
+        scanned_files=len(token_files),
+        imported_count=imported_count,
+        duplicate_count=duplicate_count,
+        invalid_json_count=invalid_json_count,
+        missing_token_count=missing_token_count,
+        invalid_token_count=invalid_token_count,
+    )
+    logger.info(
+        "✅ Token 目录导入完成: "
+        "scanned={}, imported={}, duplicate={}, invalid_json={}, "
+        "missing_token={}, invalid_token={}",
+        summary.scanned_files,
+        summary.imported_count,
+        summary.duplicate_count,
+        summary.invalid_json_count,
+        summary.missing_token_count,
+        summary.invalid_token_count,
+    )
+    return summary

app/templates/base.html

@@ -0,0 +1,201 @@
+<!DOCTYPE html>
+<html lang="zh-CN" class="h-full bg-gray-50">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}管理后台{% endblock %} - API 控制台</title>
+
+    <!-- Tailwind CSS (CDN) -->
+    <script src="https://cdn.tailwindcss.com"></script>
+
+    <!-- Alpine.js (CDN) -->
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+
+    <!-- htmx (CDN) -->
+    <script src="https://unpkg.com/htmx.org@1.9.10"></script>
+
+    <!-- Chart.js (CDN) -->
+    <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1"></script>
+
+    <!-- 自定义样式 -->
+    <style>
+        /* 自定义滚动条 */
+        ::-webkit-scrollbar {
+            width: 8px;
+            height: 8px;
+        }
+        ::-webkit-scrollbar-track {
+            background: #f1f1f1;
+        }
+        ::-webkit-scrollbar-thumb {
+            background: #888;
+            border-radius: 4px;
+        }
+        ::-webkit-scrollbar-thumb:hover {
+            background: #555;
+        }
+
+        /* htmx 加载指示器 */
+        .htmx-indicator {
+            display: none;
+        }
+        .htmx-request .htmx-indicator {
+            display: inline-block;
+        }
+        .htmx-request.htmx-indicator {
+            display: inline-block;
+        }
+
+        /* 平滑过渡 */
+        .fade-in {
+            animation: fadeIn 0.3s ease-in;
+        }
+        @keyframes fadeIn {
+            from { opacity: 0; }
+            to { opacity: 1; }
+        }
+    </style>
+
+    {% block extra_head %}{% endblock %}
+</head>
+<body class="h-full" x-data="{
+    sidebarOpen: true,
+    async logout() {
+        if (confirm('确定要登出吗？')) {
+            try {
+                const response = await fetch('/admin/api/logout', {
+                    method: 'POST'
+                });
+                if (response.ok) {
+                    window.location.href = '/admin/login';
+                }
+            } catch (err) {
+                console.error('登出失败:', err);
+                alert('登出失败，请稍后重试');
+            }
+        }
+    }
+}">
+    <div class="min-h-full">
+        <!-- 顶部导航栏 -->
+        <nav class="bg-indigo-600 shadow-lg">
+            <div class="mx-auto px-4 sm:px-6 lg:px-8">
+                <div class="flex h-16 items-center justify-between">
+                    <!-- Logo 和切换按钮 -->
+                    <div class="flex items-center">
+                        <button @click="sidebarOpen = !sidebarOpen" class="text-white hover:bg-indigo-700 p-2 rounded-md">
+                            <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
+                            </svg>
+                        </button>
+                        <div class="ml-4 flex items-center">
+                            <h1 class="text-2xl font-bold text-white">API 管理后台</h1>
+                        </div>
+                    </div>
+
+                    <!-- 右侧信息 -->
+                    <div class="flex items-center space-x-4">
+                        <!-- 实时状态指示器 -->
+                        <div class="flex items-center text-white">
+                            <span class="relative flex h-3 w-3">
+                                <span class="animate-ping absolute inline-flex h-full w-full rounded-full bg-green-400 opacity-75"></span>
+                                <span class="relative inline-flex rounded-full h-3 w-3 bg-green-500"></span>
+                            </span>
+                            <span class="ml-2 text-sm">服务运行中</span>
+                        </div>
+
+                        <!-- 登出按钮 -->
+                        <button
+                            @click="logout()"
+                            class="flex items-center text-white hover:bg-indigo-700 px-3 py-2 rounded-md text-sm font-medium transition-colors">
+                            <svg class="h-5 w-5 mr-1" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1" />
+                            </svg>
+                            登出
+                        </button>
+                    </div>
+                </div>
+            </div>
+        </nav>
+
+        <div class="flex">
+            <!-- 侧边栏 -->
+            <aside
+                x-show="sidebarOpen"
+                x-transition:enter="transition ease-out duration-200"
+                x-transition:enter-start="transform -translate-x-full"
+                x-transition:enter-end="transform translate-x-0"
+                x-transition:leave="transition ease-in duration-200"
+                x-transition:leave-start="transform translate-x-0"
+                x-transition:leave-end="transform -translate-x-full"
+                class="w-64 bg-white shadow-lg min-h-screen">
+                <nav class="mt-5 px-2 space-y-1">
+                    {% set current_path = request.url.path %}
+
+                    <!-- 仪表盘 -->
+                    <a href="/admin"
+                       class="{% if current_path == '/admin' or current_path == '/admin/' %}bg-indigo-100 text-indigo-700{% else %}text-gray-700 hover:bg-gray-100{% endif %} group flex items-center px-3 py-2 text-sm font-medium rounded-md">
+                        <svg class="mr-3 h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
+                        </svg>
+                        仪表盘
+                    </a>
+
+                    <!-- 配置管理 -->
+                    <a href="/admin/config"
+                       class="{% if '/config' in current_path %}bg-indigo-100 text-indigo-700{% else %}text-gray-700 hover:bg-gray-100{% endif %} group flex items-center px-3 py-2 text-sm font-medium rounded-md">
+                        <svg class="mr-3 h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+                        </svg>
+                        配置管理
+                    </a>
+
+                    <!-- 实时日志 -->
+                    <a href="/admin/logs"
+                       class="{% if '/logs' in current_path %}bg-indigo-100 text-indigo-700{% else %}text-gray-700 hover:bg-gray-100{% endif %} group flex items-center px-3 py-2 text-sm font-medium rounded-md">
+                        <svg class="mr-3 h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
+                        </svg>
+                        实时日志
+                    </a>
+
+                    <!-- Token 管理 -->
+                    <a href="/admin/tokens"
+                       class="{% if '/tokens' in current_path %}bg-indigo-100 text-indigo-700{% else %}text-gray-700 hover:bg-gray-100{% endif %} group flex items-center px-3 py-2 text-sm font-medium rounded-md">
+                        <svg class="mr-3 h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 7a2 2 0 012 2m4 0a6 6 0 01-7.743 5.743L11 17H9v2H7v2H4a1 1 0 01-1-1v-2.586a1 1 0 01.293-.707l5.964-5.964A6 6 0 1121 9z" />
+                        </svg>
+                        Token 管理
+                    </a>
+
+                    <!-- 分隔线 -->
+                    <div class="border-t border-gray-200 my-4"></div>
+
+                    <!-- API 文档 -->
+                    <a href="/docs" target="_blank"
+                       class="text-gray-700 hover:bg-gray-100 group flex items-center px-3 py-2 text-sm font-medium rounded-md">
+                        <svg class="mr-3 h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+                        </svg>
+                        API 文档
+                    </a>
+                </nav>
+            </aside>
+
+            <!-- 主内容区 -->
+            <main class="flex-1 p-6">
+                <!-- 通知区域 -->
+                <div id="notification" class="mb-4"></div>
+
+                <!-- 页面内容 -->
+                <div class="fade-in">
+                    {% block content %}{% endblock %}
+                </div>
+            </main>
+        </div>
+    </div>
+
+    {% block extra_scripts %}{% endblock %}
+</body>
+</html>

app/templates/components/recent_logs.html

@@ -0,0 +1,128 @@
+<!-- 最近请求日志列表 -->
+<script>
+    window.dashboardRecentLogsPage = {{ page.current_page }};
+    window.dashboardRecentLogsPageSize = {{ page.page_size }};
+</script>
+
+<div class="space-y-4">
+    <div class="max-h-[30rem] overflow-auto rounded-2xl border border-slate-200">
+        {% if logs %}
+        <table class="min-w-[1240px] divide-y divide-slate-200">
+            <thead class="bg-slate-50/95 backdrop-blur">
+                <tr>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">时间</th>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">请求</th>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">标记</th>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">输入 / 输出</th>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">缓存创建 / 命中</th>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">用时 / 首字</th>
+                    <th class="sticky top-0 bg-slate-50/95 px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-slate-500">状态</th>
+                </tr>
+            </thead>
+            <tbody class="divide-y divide-slate-100 bg-white">
+                {% for log in logs %}
+                <tr class="transition-colors hover:bg-slate-50/70">
+                    <td class="px-4 py-3 whitespace-nowrap text-sm font-medium text-slate-900">
+                        {{ log.timestamp }}
+                    </td>
+                    <td class="px-4 py-3 text-sm text-slate-600">
+                        <div class="flex max-w-[28rem] items-center gap-2 overflow-hidden whitespace-nowrap">
+                            <span class="inline-flex items-center rounded-full bg-emerald-50 px-2 py-0.5 text-xs font-medium text-emerald-700">
+                                {{ log.model }}
+                            </span>
+                            <span class="truncate font-mono text-xs text-slate-500">
+                                {{ log.endpoint }}
+                            </span>
+                        </div>
+                        {% if log.error_message %}
+                        <p class="mt-1 max-w-[28rem] truncate text-xs text-red-500">
+                            {{ log.error_message }}
+                        </p>
+                        {% endif %}
+                    </td>
+                    <td class="px-4 py-3 text-sm text-slate-600">
+                        <div class="flex max-w-[20rem] items-center gap-2 overflow-hidden whitespace-nowrap">
+                            <span class="inline-flex items-center rounded-full bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-700">
+                                {{ log.client_name }}
+                            </span>
+                            <span class="inline-flex items-center rounded-full bg-sky-50 px-2 py-0.5 text-xs font-medium text-sky-700">
+                                {{ log.protocol_display }}
+                            </span>
+                            {% if log.source_display %}
+                            <span class="inline-flex items-center rounded-full bg-violet-50 px-2 py-0.5 text-xs font-medium text-violet-700">
+                                {{ log.source_display }}
+                            </span>
+                            {% endif %}
+                            {% if log.provider_display %}
+                            <span class="inline-flex items-center rounded-full bg-indigo-50 px-2 py-0.5 text-xs font-medium text-indigo-700">
+                                {{ log.provider_display }}
+                            </span>
+                            {% endif %}
+                        </div>
+                    </td>
+                    <td class="px-4 py-3 whitespace-nowrap text-sm font-medium tabular-nums text-slate-700">
+                        <span class="text-violet-700">输入 {{ log.input_tokens }}</span>
+                        <span class="mx-2 text-slate-300">/</span>
+                        <span class="text-rose-700">输出 {{ log.output_tokens }}</span>
+                    </td>
+                    <td class="px-4 py-3 whitespace-nowrap text-sm font-medium tabular-nums text-slate-700">
+                        <span class="text-emerald-700">创建 {{ log.cache_creation_tokens }}</span>
+                        <span class="mx-2 text-slate-300">/</span>
+                        <span class="text-amber-700">命中 {{ log.cache_read_tokens }}</span>
+                    </td>
+                    <td class="px-4 py-3 whitespace-nowrap text-sm font-medium tabular-nums text-slate-700">
+                        <span>用时 {{ log.duration_display }}</span>
+                        <span class="mx-2 text-slate-300">/</span>
+                        <span class="text-sky-700">首字 {{ log.first_token_display }}</span>
+                    </td>
+                    <td class="px-4 py-3 whitespace-nowrap text-sm">
+                        <span class="inline-flex items-center rounded-full px-2.5 py-1 text-xs font-semibold {% if log.success %}bg-emerald-100 text-emerald-800{% else %}bg-red-100 text-red-800{% endif %}">
+                            {{ "成功" if log.success else "失败" }}
+                        </span>
+                        <span class="ml-2 text-xs font-medium {% if log.success %}text-emerald-700{% else %}text-red-700{% endif %}">
+                            HTTP {{ log.status_code }}
+                        </span>
+                    </td>
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+        {% else %}
+        <div class="py-8 text-center text-gray-500">
+            <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+            <p class="mt-2">暂无请求日志</p>
+        </div>
+        {% endif %}
+    </div>
+
+    <div class="flex flex-col gap-3 border-t border-gray-100 pt-4 text-sm text-gray-600 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+            {% if page.total_items > 0 %}
+            显示第 {{ page.start_item }} - {{ page.end_item }} 条，共 {{ page.total_items }} 条
+            {% else %}
+            暂无日志数据
+            {% endif %}
+        </div>
+        <div class="flex items-center gap-2">
+            <button
+                type="button"
+                onclick="loadRecentLogsPage({{ page.previous_page }})"
+                class="rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium transition-colors {% if page.has_previous %}bg-white text-gray-700 hover:bg-gray-50{% else %}cursor-not-allowed bg-gray-100 text-gray-400{% endif %}"
+                {% if not page.has_previous %}disabled{% endif %}>
+                上一页
+            </button>
+            <span class="min-w-[88px] text-center text-xs text-gray-500">
+                第 {{ page.current_page }} / {{ page.total_pages }} 页
+            </span>
+            <button
+                type="button"
+                onclick="loadRecentLogsPage({{ page.next_page }})"
+                class="rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium transition-colors {% if page.has_next %}bg-white text-gray-700 hover:bg-gray-50{% else %}cursor-not-allowed bg-gray-100 text-gray-400{% endif %}"
+                {% if not page.has_next %}disabled{% endif %}>
+                下一页
+            </button>
+        </div>
+    </div>
+</div>

app/templates/components/token_list.html

@@ -0,0 +1,114 @@
+<!-- Token 列表表格 -->
+<script>
+    window.tokenListPage = {{ page.current_page }};
+    window.tokenListPageSize = {{ page.page_size }};
+</script>
+
+<div class="space-y-4">
+    <div class="max-h-[42rem] overflow-auto rounded-lg border border-gray-100">
+        {% if tokens %}
+        <table class="min-w-full divide-y divide-gray-200">
+            <thead class="bg-gray-50">
+                <tr>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">ID</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">Token</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">类型</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">健康度</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">状态</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">使用统计</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">创建时间</th>
+                    <th class="sticky top-0 bg-gray-50 px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500">操作</th>
+                </tr>
+            </thead>
+            <tbody class="bg-white divide-y divide-gray-200">
+                {% for token in tokens %}
+                {% include "components/token_row.html" %}
+                {% endfor %}
+            </tbody>
+        </table>
+        {% else %}
+        <div class="text-center py-12 text-gray-500">
+            <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20 13V6a2 2 0 00-2-2H6a2 2 0 00-2 2v7m16 0v5a2 2 0 01-2 2H6a2 2 0 01-2-2v-5m16 0h-2.586a1 1 0 00-.707.293l-2.414 2.414a1 1 0 01-.707.293h-3.172a1 1 0 01-.707-.293l-2.414-2.414A1 1 0 006.586 13H4" />
+            </svg>
+            <p class="mt-2 font-medium">暂无 Token</p>
+            <p class="mt-1 text-sm">点击右上角"添加 Token"按钮开始添加</p>
+        </div>
+        {% endif %}
+    </div>
+
+    <div class="flex flex-col gap-3 border-t border-gray-100 pt-4 text-sm text-gray-600 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+            {% if page.total_items > 0 %}
+            显示第 {{ page.start_item }} - {{ page.end_item }} 条，共 {{ page.total_items }} 个 Token
+            {% else %}
+            暂无 Token 数据
+            {% endif %}
+        </div>
+        <div class="flex items-center gap-2">
+            <button
+                type="button"
+                onclick="loadTokenListPage({{ page.previous_page }})"
+                class="rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium transition-colors {% if page.has_previous %}bg-white text-gray-700 hover:bg-gray-50{% else %}cursor-not-allowed bg-gray-100 text-gray-400{% endif %}"
+                {% if not page.has_previous %}disabled{% endif %}>
+                上一页
+            </button>
+            <span class="min-w-[88px] text-center text-xs text-gray-500">
+                第 {{ page.current_page }} / {{ page.total_pages }} 页
+            </span>
+            <button
+                type="button"
+                onclick="loadTokenListPage({{ page.next_page }})"
+                class="rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium transition-colors {% if page.has_next %}bg-white text-gray-700 hover:bg-gray-50{% else %}cursor-not-allowed bg-gray-100 text-gray-400{% endif %}"
+                {% if not page.has_next %}disabled{% endif %}>
+                下一页
+            </button>
+        </div>
+    </div>
+</div>
+
+<!-- Token 数量统计（更新页面标题） -->
+<script>
+    (function() {
+        const tokenCount = {{ page.total_items }};
+        const countElement = document.getElementById('token-count');
+        if (countElement) {
+            countElement.textContent = `(共 ${tokenCount} 个)`;
+        }
+    })();
+</script>
+
+<!-- 复制到剪贴板函数 -->
+<script>
+    function copyToClipboard(text) {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+            navigator.clipboard.writeText(text).then(() => {
+                const notification = document.createElement('div');
+                notification.className = 'fixed bottom-4 right-4 bg-green-500 text-white px-4 py-2 rounded shadow-lg z-50';
+                notification.textContent = '✓ Token 已复制到剪贴板';
+                document.body.appendChild(notification);
+
+                setTimeout(() => {
+                    notification.remove();
+                }, 2000);
+            }).catch(err => {
+                console.error('复制失败:', err);
+                alert('复制失败，请手动复制');
+            });
+        } else {
+            const textArea = document.createElement('textarea');
+            textArea.value = text;
+            textArea.style.position = 'fixed';
+            textArea.style.left = '-999999px';
+            document.body.appendChild(textArea);
+            textArea.select();
+            try {
+                document.execCommand('copy');
+                alert('Token 已复制到剪贴板');
+            } catch (err) {
+                alert('复制失败，请手动复制');
+            }
+            document.body.removeChild(textArea);
+        }
+    }
+</script>

app/templates/components/token_pool.html

@@ -0,0 +1,40 @@
+<!-- Token 池状态卡片 -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {% for token in tokens %}
+    <div class="border rounded-lg p-4 hover:shadow-lg transition-shadow">
+        <div class="flex items-center justify-between mb-2">
+            <span class="text-sm font-medium text-gray-700">Token #{{ token.index }}</span>
+            <span class="px-2 py-1 text-xs font-semibold rounded-full {{ token.status_color }}">
+                {{ token.status }}
+            </span>
+        </div>
+        <div class="space-y-1 text-sm text-gray-600">
+            <div class="truncate">
+                <span class="font-mono text-xs bg-gray-100 px-2 py-1 rounded">{{ token.key }}</span>
+            </div>
+            <div>类型:
+                {% if token.token_type == 'user' %}
+                <span class="text-green-600 font-semibold">认证用户</span>
+                {% elif token.token_type == 'guest' %}
+                <span class="text-yellow-600 font-semibold">匿名用户</span>
+                {% else %}
+                <span class="text-gray-600">未知</span>
+                {% endif %}
+            </div>
+            <div>成功率: <span class="font-medium">{{ token.success_rate }}</span></div>
+            <div>失败次数: <span class="font-medium">{{ token.failure_count }}</span></div>
+            <div class="text-xs text-gray-500">最后使用: {{ token.last_used }}</div>
+        </div>
+    </div>
+    {% endfor %}
+
+    {% if not tokens %}
+    <div class="col-span-full text-center py-8 text-gray-500">
+        <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20 13V6a2 2 0 00-2-2H6a2 2 0 00-2 2v7m16 0v5a2 2 0 01-2 2H6a2 2 0 01-2-2v-5m16 0h-2.586a1 1 0 00-.707.293l-2.414 2.414a1 1 0 01-.707.293h-3.172a1 1 0 01-.707-.293l-2.414-2.414A1 1 0 006.586 13H4" />
+        </svg>
+        <p class="mt-2">暂无 Token 配置</p>
+        <p class="mt-1 text-sm">请在配置管理页面添加 Token</p>
+    </div>
+    {% endif %}
+</div>

app/templates/components/token_row.html

@@ -0,0 +1,154 @@
+<!-- 单个 Token 行模板 -->
+{% set success_rate = (token.successful_requests / token.total_requests * 100) if token.total_requests else 0 %}
+{% set is_healthy = (token.token_type == 'user' and token.is_enabled and (success_rate >= 50 or token.total_requests <= 3)) %}
+<tr class="hover:bg-gray-50 transition-colors" id="token-row-{{ token.id }}">
+    <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-900 font-medium">
+        {{ token.id }}
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+        <div class="flex items-center space-x-2">
+            <span class="font-mono text-xs bg-gray-100 px-2 py-1 rounded">
+                {{ token.token[:30] }}...
+            </span>
+            <button onclick="copyToClipboard('{{ token.token }}')"
+                    class="text-gray-400 hover:text-indigo-600 transition-colors"
+                    title="复制完整 Token">
+                <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+                </svg>
+            </button>
+        </div>
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm">
+        {% if token.token_type == 'user' %}
+        <span class="inline-flex items-center px-2.5 py-0.5 text-xs font-semibold rounded-full bg-green-100 text-green-800">
+            <svg class="h-3 w-3 mr-1" fill="currentColor" viewBox="0 0 20 20">
+                <path fill-rule="evenodd" d="M10 9a3 3 0 100-6 3 3 0 000 6zm-7 9a7 7 0 1114 0H3z" clip-rule="evenodd" />
+            </svg>
+            认证用户
+        </span>
+        {% elif token.token_type == 'guest' %}
+        <span class="inline-flex items-center px-2.5 py-0.5 text-xs font-semibold rounded-full bg-yellow-100 text-yellow-800">
+            <svg class="h-3 w-3 mr-1" fill="currentColor" viewBox="0 0 20 20">
+                <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clip-rule="evenodd" />
+            </svg>
+            匿名用户
+        </span>
+        {% else %}
+        <span class="inline-flex items-center px-2.5 py-0.5 text-xs font-semibold rounded-full bg-gray-100 text-gray-800">
+            <svg class="h-3 w-3 mr-1" fill="currentColor" viewBox="0 0 20 20">
+                <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-3a1 1 0 00-.867.5 1 1 0 11-1.731-1A3 3 0 0113 8a3.001 3.001 0 01-2 2.83V11a1 1 0 11-2 0v-1a1 1 0 011-1 1 1 0 100-2zm0 8a1 1 0 100-2 1 1 0 000 2z" clip-rule="evenodd" />
+            </svg>
+            未知
+        </span>
+        {% endif %}
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm">
+        <!-- 健康度指示器 -->
+        <div class="flex items-center space-x-2">
+            {% if is_healthy %}
+            <div class="flex items-center">
+                <svg class="h-5 w-5 text-green-500" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
+                </svg>
+                <span class="ml-1 text-green-700 font-medium">健康</span>
+            </div>
+            {% elif token.token_type == 'guest' %}
+            <div class="flex items-center">
+                <svg class="h-5 w-5 text-yellow-500" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd" />
+                </svg>
+                <span class="ml-1 text-yellow-700 font-medium">匿名</span>
+            </div>
+            {% elif not token.is_enabled %}
+            <div class="flex items-center">
+                <svg class="h-5 w-5 text-gray-500" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M13.477 14.89A6 6 0 015.11 6.524l8.367 8.368zm1.414-1.414L6.524 5.11a6 6 0 018.367 8.367zM18 10a8 8 0 11-16 0 8 8 0 0116 0z" clip-rule="evenodd" />
+                </svg>
+                <span class="ml-1 text-gray-700 font-medium">已禁用</span>
+            </div>
+            {% else %}
+            <div class="flex items-center">
+                <svg class="h-5 w-5 text-red-500" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z" clip-rule="evenodd" />
+                </svg>
+                <span class="ml-1 text-red-700 font-medium">不健康</span>
+            </div>
+            {% endif %}
+        </div>
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm">
+        <button hx-post="/admin/api/tokens/toggle/{{ token.id }}?enabled={{ 'false' if token.is_enabled else 'true' }}"
+                hx-swap="outerHTML"
+                class="inline-flex items-center px-2.5 py-0.5 text-xs font-semibold rounded-full transition-colors {{ 'bg-green-100 text-green-800 hover:bg-green-200' if token.is_enabled else 'bg-red-100 text-red-800 hover:bg-red-200' }}">
+            <span class="h-2 w-2 rounded-full mr-1.5 {{ 'bg-green-500' if token.is_enabled else 'bg-red-500' }}"></span>
+            {{ '已启用' if token.is_enabled else '已禁用' }}
+        </button>
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+        {% if token.total_requests %}
+        <div class="space-y-1">
+            <div class="flex items-center justify-between">
+                <span class="text-xs text-gray-600">成功:</span>
+                <span class="font-medium text-green-600">{{ token.successful_requests }}</span>
+            </div>
+            <div class="flex items-center justify-between">
+                <span class="text-xs text-gray-600">失败:</span>
+                <span class="font-medium text-red-600">{{ token.failed_requests }}</span>
+            </div>
+            <div class="flex items-center justify-between">
+                <span class="text-xs text-gray-600">成功率:</span>
+                <span class="font-medium {{ 'text-green-600' if success_rate >= 50 else 'text-red-600' }}">
+                    {{ "%.1f"|format(success_rate) }}%
+                </span>
+            </div>
+            <!-- 成功率进度条 -->
+            <div class="w-full bg-gray-200 rounded-full h-1.5 mt-1">
+                <div class="h-1.5 rounded-full transition-all {{ 'bg-green-500' if success_rate >= 50 else 'bg-red-500' }}"
+                     style="width: {{ success_rate }}%"></div>
+            </div>
+        </div>
+        {% else %}
+        <span class="text-gray-400 text-xs">未使用</span>
+        {% endif %}
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+        <div class="flex flex-col space-y-1">
+            <span class="text-xs">{{ token.created_at[:10] if token.created_at else 'N/A' }}</span>
+            <span class="text-xs text-gray-400">{{ token.created_at[11:19] if token.created_at else '' }}</span>
+        </div>
+    </td>
+    <td class="px-6 py-4 whitespace-nowrap text-sm font-medium">
+        <div class="flex items-center space-x-3">
+            <!-- 验证按钮 -->
+            <button hx-post="/admin/api/tokens/validate-single/{{ token.id }}"
+                    hx-target="#token-row-{{ token.id }}"
+                    hx-swap="outerHTML"
+                    hx-indicator="#validate-spinner-{{ token.id }}"
+                    class="text-blue-600 hover:text-blue-900 transition-colors relative validate-token-btn"
+                    title="验证 Token"
+                    data-token-id="{{ token.id }}">
+                <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                </svg>
+                <!-- 加载指示器 -->
+                <svg id="validate-spinner-{{ token.id }}" class="htmx-indicator absolute inset-0 h-4 w-4 animate-spin text-blue-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                </svg>
+            </button>
+            <!-- 删除按钮 -->
+            <button hx-delete="/admin/api/tokens/delete/{{ token.id }}"
+                    hx-target="#token-row-{{ token.id }}"
+                    hx-swap="outerHTML swap:1s"
+                    hx-on::after-request="if (event.detail.successful) { htmx.trigger(document.body, 'tokenListRefresh'); htmx.trigger(document.body, 'statsRefresh'); }"
+                    hx-confirm="确定要删除这个 Token 吗？"
+                    class="text-red-600 hover:text-red-900 transition-colors"
+                    title="删除 Token">
+                <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
+                </svg>
+            </button>
+        </div>
+    </td>
+</tr>

app/templates/components/token_stats.html

@@ -0,0 +1,125 @@
+<!-- Token 统计面板 -->
+<div class="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-4">
+    <!-- 总数 -->
+    <div class="bg-white overflow-hidden shadow rounded-lg">
+        <div class="p-5">
+            <div class="flex items-center">
+                <div class="flex-shrink-0">
+                    <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 21a4 4 0 01-4-4V5a2 2 0 012-2h4a2 2 0 012 2v12a4 4 0 01-4 4zm0 0h12a2 2 0 002-2v-4a2 2 0 00-2-2h-2.343M11 7.343l1.657-1.657a2 2 0 012.828 0l2.829 2.829a2 2 0 010 2.828l-8.486 8.485M7 17h.01" />
+                    </svg>
+                </div>
+                <div class="ml-5 w-0 flex-1">
+                    <dl>
+                        <dt class="text-sm font-medium text-gray-500 truncate">Token 总数</dt>
+                        <dd class="text-2xl font-bold text-gray-900">{{ stats.total_tokens }}</dd>
+                    </dl>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- 已启用 -->
+    <div class="bg-white overflow-hidden shadow rounded-lg">
+        <div class="p-5">
+            <div class="flex items-center">
+                <div class="flex-shrink-0">
+                    <svg class="h-6 w-6 text-green-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                </div>
+                <div class="ml-5 w-0 flex-1">
+                    <dl>
+                        <dt class="text-sm font-medium text-gray-500 truncate">已启用</dt>
+                        <dd class="flex items-baseline">
+                            <div class="text-2xl font-bold text-green-600">{{ stats.enabled_tokens }}</div>
+                            {% if stats.total_tokens > 0 %}
+                            <div class="ml-2 flex items-baseline text-sm font-semibold text-green-600">
+                                {{ "%.0f"|format(stats.enabled_tokens / stats.total_tokens * 100) }}%
+                            </div>
+                            {% endif %}
+                        </dd>
+                    </dl>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- 认证用户 -->
+    <div class="bg-white overflow-hidden shadow rounded-lg">
+        <div class="p-5">
+            <div class="flex items-center">
+                <div class="flex-shrink-0">
+                    <svg class="h-6 w-6 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+                    </svg>
+                </div>
+                <div class="ml-5 w-0 flex-1">
+                    <dl>
+                        <dt class="text-sm font-medium text-gray-500 truncate">认证用户</dt>
+                        <dd class="flex items-baseline">
+                            <div class="text-2xl font-bold text-blue-600">{{ stats.user_tokens }}</div>
+                            {% if stats.guest_tokens > 0 %}
+                            <div class="ml-2 flex items-baseline text-sm font-semibold text-yellow-600">
+                                <svg class="h-4 w-4 mr-0.5" fill="currentColor" viewBox="0 0 20 20">
+                                    <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd" />
+                                </svg>
+                                {{ stats.guest_tokens }} 个匿名
+                            </div>
+                            {% endif %}
+                        </dd>
+                    </dl>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- 成功率 -->
+    <div class="bg-white overflow-hidden shadow rounded-lg">
+        <div class="p-5">
+            <div class="flex items-center">
+                <div class="flex-shrink-0">
+                    {% if stats.total_requests > 0 %}
+                        {% set success_rate = (stats.successful_requests / stats.total_requests * 100) %}
+                        {% if success_rate >= 80 %}
+                        <svg class="h-6 w-6 text-green-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7h8m0 0v8m0-8l-8 8-4-4-6 6" />
+                        </svg>
+                        {% elif success_rate >= 50 %}
+                        <svg class="h-6 w-6 text-yellow-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7h8m0 0v8m0-8l-8 8-4-4-6 6" />
+                        </svg>
+                        {% else %}
+                        <svg class="h-6 w-6 text-red-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 17h8m0 0v-8m0 8l-8-8-4 4-6-6" />
+                        </svg>
+                        {% endif %}
+                    {% else %}
+                    <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
+                    </svg>
+                    {% endif %}
+                </div>
+                <div class="ml-5 w-0 flex-1">
+                    <dl>
+                        <dt class="text-sm font-medium text-gray-500 truncate">总成功率</dt>
+                        <dd>
+                            {% if stats.total_requests > 0 %}
+                                {% set success_rate = (stats.successful_requests / stats.total_requests * 100) %}
+                                <div class="text-2xl font-bold {{ 'text-green-600' if success_rate >= 80 else ('text-yellow-600' if success_rate >= 50 else 'text-red-600') }}">
+                                    {{ "%.1f"|format(success_rate) }}%
+                                </div>
+                                <div class="mt-1 text-xs text-gray-500">
+                                    {{ stats.successful_requests }} / {{ stats.total_requests }} 请求
+                                </div>
+                            {% else %}
+                                <div class="text-2xl font-bold text-gray-400">N/A</div>
+                                <div class="mt-1 text-xs text-gray-500">暂无请求</div>
+                            {% endif %}
+                        </dd>
+                    </dl>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>

app/templates/config.html

@@ -0,0 +1,344 @@
+{% extends "base.html" %}
+
+{% block title %}配置管理{% endblock %}
+
+{% block extra_head %}
+<style>
+    [x-cloak] {
+        display: none !important;
+    }
+    .config-grid {
+        grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+    }
+</style>
+{% endblock %}
+
+{% macro section_link(section) -%}
+<button
+    type="button"
+    @click.prevent="document.getElementById('{{ section.id }}')?.scrollIntoView({ behavior: 'smooth', block: 'start' })"
+    class="inline-flex items-center rounded-full border border-slate-200 bg-white px-3 py-1.5 text-sm font-medium text-slate-700 transition hover:border-indigo-300 hover:text-indigo-700">
+    {{ section.title }}
+</button>
+{%- endmacro %}
+
+{% macro render_field(field) -%}
+<div class="{{ 'md:col-span-2' if field.wide else '' }} rounded-2xl border border-slate-200 bg-slate-50/70 p-4 shadow-sm">
+    {% if field.value_type == 'bool' %}
+    <label class="flex min-h-[44px] cursor-pointer items-start gap-3">
+        <input
+            type="checkbox"
+            name="{{ field.key }}"
+            class="mt-1 h-4 w-4 rounded border-slate-300 text-indigo-600 focus:ring-indigo-500"
+            {{ 'checked' if field.value else '' }}>
+        <span class="flex-1">
+            <span class="block text-sm font-semibold text-slate-900">{{ field.label }}</span>
+            <span class="mt-1 block text-sm leading-6 text-slate-600">{{ field.description }}</span>
+        </span>
+    </label>
+    {% else %}
+    <div {% if field.sensitive %}x-data="{ reveal: false }"{% endif %}>
+        <div class="flex items-start justify-between gap-3">
+            <label for="{{ field.key }}" class="block text-sm font-semibold text-slate-900">
+                {{ field.label }}
+            </label>
+            {% if field.sensitive %}
+            <button
+                type="button"
+                @click="reveal = !reveal"
+                class="inline-flex items-center rounded-full border border-slate-200 bg-white px-2.5 py-1 text-xs font-medium text-slate-600 transition hover:border-indigo-300 hover:text-indigo-700">
+                <span x-text="reveal ? '隐藏' : '显示'"></span>
+            </button>
+            {% endif %}
+        </div>
+        <p class="mt-1 text-sm leading-6 text-slate-600">{{ field.description }}</p>
+        <input
+            id="{{ field.key }}"
+            name="{{ field.key }}"
+            {% if field.sensitive %}
+            :type="reveal ? 'text' : '{{ field.input_type }}'"
+            {% else %}
+            type="{{ field.input_type }}"
+            {% endif %}
+            value="{{ field.value }}"
+            placeholder="{{ field.placeholder }}"
+            {% if field.required %}required{% endif %}
+            {% if field.min_value is not none %}min="{{ field.min_value }}"{% endif %}
+            {% if field.max_value is not none %}max="{{ field.max_value }}"{% endif %}
+            class="mt-3 block w-full rounded-xl border-slate-300 bg-white px-3 py-2.5 text-sm text-slate-900 shadow-sm focus:border-indigo-500 focus:ring-indigo-500">
+    </div>
+    {% endif %}
+
+    <div class="mt-3 flex flex-wrap gap-2 text-xs">
+        <span class="inline-flex items-center rounded-full px-2.5 py-1 font-medium ring-1 ring-inset {{ field.source_badge_class }}">
+            {{ field.source_label }}
+        </span>
+        {% if field.restart_required %}
+        <span class="inline-flex items-center rounded-full bg-amber-50 px-2.5 py-1 font-medium text-amber-700 ring-1 ring-inset ring-amber-200">
+            需重启
+        </span>
+        {% endif %}
+        {% if field.sensitive %}
+        <span class="inline-flex items-center rounded-full bg-rose-50 px-2.5 py-1 font-medium text-rose-700 ring-1 ring-inset ring-rose-200">
+            敏感字段
+        </span>
+        {% endif %}
+    </div>
+</div>
+{%- endmacro %}
+
+{% block content %}
+<div x-data="configPage()" class="space-y-6">
+    <div class="overflow-hidden rounded-3xl bg-slate-900 shadow-2xl">
+        <div class="bg-[radial-gradient(circle_at_top_right,_rgba(99,102,241,0.35),_transparent_35%),linear-gradient(135deg,_#0f172a,_#1e293b_55%,_#172554)] px-6 py-8 sm:px-8">
+            <div class="flex flex-col gap-6 lg:flex-row lg:items-end lg:justify-between">
+                <div class="max-w-3xl">
+                    <p class="text-sm font-semibold uppercase tracking-[0.2em] text-indigo-200">Admin Config Center</p>
+                    <h2 class="mt-3 text-3xl font-bold text-white sm:text-4xl">集中管理运行参数，并支持直接编辑 `.env` 源文件</h2>
+                    <p class="mt-3 max-w-2xl text-sm leading-6 text-slate-300 sm:text-base">
+                        结构化表单适合日常操作，源文件模式适合批量调整、复制完整配置或保留注释。两种模式都会在保存后立即热重载。
+                    </p>
+                </div>
+
+                <div class="flex flex-wrap items-center gap-3">
+                    <button
+                        type="button"
+                        @click="setView('form')"
+                        :class="activeView === 'form'
+                            ? 'bg-white text-slate-900 shadow-lg'
+                            : 'bg-white/10 text-white hover:bg-white/20'"
+                        class="inline-flex min-h-[44px] items-center rounded-2xl px-4 py-2 text-sm font-semibold transition">
+                        结构化表单
+                    </button>
+                    <button
+                        type="button"
+                        @click="setView('source')"
+                        :class="activeView === 'source'
+                            ? 'bg-white text-slate-900 shadow-lg'
+                            : 'bg-white/10 text-white hover:bg-white/20'"
+                        class="inline-flex min-h-[44px] items-center rounded-2xl px-4 py-2 text-sm font-semibold transition">
+                        源文件编辑
+                    </button>
+                    <button
+                        type="button"
+                        hx-post="/admin/api/config/reset"
+                        hx-target="#config-feedback"
+                        hx-swap="innerHTML"
+                        hx-confirm="确定要用 .env.example 覆盖当前 .env 吗？"
+                        class="inline-flex min-h-[44px] items-center rounded-2xl border border-white/15 bg-white/5 px-4 py-2 text-sm font-semibold text-white transition hover:bg-white/15">
+                        重置为示例配置
+                    </button>
+                </div>
+            </div>
+
+            <div class="config-grid mt-8 grid gap-3">
+                <div class="rounded-2xl border border-white/10 bg-white/10 p-4 backdrop-blur">
+                    <p class="text-xs uppercase tracking-[0.2em] text-indigo-200">受管字段</p>
+                    <p class="mt-2 text-3xl font-bold text-white">{{ overview.total_fields }}</p>
+                    <p class="mt-1 text-sm text-slate-300">{{ overview.total_sections }} 个分组</p>
+                </div>
+                <div class="rounded-2xl border border-white/10 bg-white/10 p-4 backdrop-blur">
+                    <p class="text-xs uppercase tracking-[0.2em] text-indigo-200">.env 覆写</p>
+                    <p class="mt-2 text-3xl font-bold text-white">{{ overview.overridden_fields }}</p>
+                    <p class="mt-1 text-sm text-slate-300">{{ overview.default_fields }} 个字段仍在使用默认值</p>
+                </div>
+                <div class="rounded-2xl border border-white/10 bg-white/10 p-4 backdrop-blur">
+                    <p class="text-xs uppercase tracking-[0.2em] text-indigo-200">敏感字段</p>
+                    <p class="mt-2 text-3xl font-bold text-white">{{ overview.sensitive_fields }}</p>
+                    <p class="mt-1 text-sm text-slate-300">{{ overview.restart_required_fields }} 个字段修改后建议重启</p>
+                </div>
+                <div class="rounded-2xl border border-white/10 bg-white/10 p-4 backdrop-blur">
+                    <p class="text-xs uppercase tracking-[0.2em] text-indigo-200">源文件状态</p>
+                    <p class="mt-2 text-lg font-bold text-white">{{ '.env 已存在' if overview.env_exists else '.env 尚未创建' }}</p>
+                    <p class="mt-1 text-sm text-slate-300">{{ overview.env_line_count }} 行，{{ '.env.example 可用' if overview.example_exists else '缺少 .env.example' }}</p>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <div id="config-feedback"></div>
+
+    {% if not overview.env_exists %}
+    <div class="rounded-2xl border border-amber-200 bg-amber-50 px-5 py-4 text-sm text-amber-900">
+        当前工作目录中尚未找到 `.env` 文件。你可以直接保存表单或源文件，系统会自动创建它。
+    </div>
+    {% endif %}
+
+    <div class="grid gap-6 xl:grid-cols-[280px,minmax(0,1fr)]">
+        <aside class="space-y-4">
+            <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+                <div class="flex items-center justify-between">
+                    <h3 class="text-base font-semibold text-slate-900">工作区</h3>
+                </div>
+                <div class="mt-3 rounded-2xl bg-slate-100 px-3 py-2 text-[11px] leading-5 text-slate-600 break-all">
+                    {{ overview.env_path }}
+                </div>
+                <div class="mt-4 space-y-3 text-sm text-slate-600">
+                    <p>表单模式会只更新受管字段，并保留 `.env` 中未知配置和注释顺序。</p>
+                    <p>源文件模式会直接覆盖整个 `.env`，适合批量调整和粘贴完整配置。</p>
+                </div>
+            </div>
+
+            <div x-show="activeView === 'form'" x-cloak class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+                <h3 class="text-base font-semibold text-slate-900">分组导航</h3>
+                <div class="mt-4 flex flex-wrap gap-2">
+                    {% for section in sections %}
+                    {{ section_link(section) }}
+                    {% endfor %}
+                </div>
+            </div>
+
+            <div x-show="activeView === 'source'" x-cloak class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+                <h3 class="text-base font-semibold text-slate-900">源文件提示</h3>
+                <div class="mt-4 space-y-3 text-sm leading-6 text-slate-600">
+                    <p>每一行应遵循 `KEY=VALUE` 格式，空行和以 `#` 开头的注释会被保留。</p>
+                    <p>直接修改源文件时，结构化表单不会实时同步，保存后页面会自动刷新到当前视图。</p>
+                    <p>如果你需要保留完整注释、顺序或复制整套配置，优先使用这一模式。</p>
+                </div>
+            </div>
+
+            <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+                <h3 class="text-base font-semibold text-slate-900">热重载说明</h3>
+                <div class="mt-4 space-y-3 text-sm leading-6 text-slate-600">
+                    <p>大多数字段保存后会立即生效。</p>
+                    <p>标记为“需重启”的字段涉及监听端口、进程名称或底层持久化路径，建议手动重启服务。</p>
+                    <p>修改后台密码或会话密钥后，建议重新登录后台验证新配置已生效。</p>
+                </div>
+            </div>
+        </aside>
+
+        <div class="space-y-6">
+            <form
+                x-show="activeView === 'form'"
+                x-cloak
+                hx-post="/admin/api/config/save"
+                hx-target="#config-feedback"
+                hx-swap="innerHTML"
+                class="space-y-6">
+                {% for section in sections %}
+                <section id="{{ section.id }}" class="overflow-hidden rounded-3xl bg-white shadow-sm ring-1 ring-slate-200">
+                    <div class="border-b border-slate-200 bg-slate-50/70 px-6 py-5">
+                        <div class="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+                            <div>
+                                <h3 class="text-lg font-semibold text-slate-900">{{ section.title }}</h3>
+                                <p class="mt-1 text-sm leading-6 text-slate-600">{{ section.description }}</p>
+                            </div>
+                            <span class="inline-flex items-center rounded-full bg-slate-900 px-3 py-1 text-xs font-semibold text-white">
+                                {{ section.field_count }} 个字段
+                            </span>
+                        </div>
+                    </div>
+                    <div class="grid gap-4 p-6 md:grid-cols-2">
+                        {% for field in section.fields %}
+                        {{ render_field(field) }}
+                        {% endfor %}
+                    </div>
+                </section>
+                {% endfor %}
+
+                <div class="sticky bottom-4 z-10 rounded-3xl border border-slate-200 bg-white/95 p-4 shadow-2xl backdrop-blur">
+                    <div class="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+                        <p class="text-sm text-slate-600">
+                            表单模式会保留未知配置，只更新当前页面管理的字段。
+                        </p>
+                        <div class="flex flex-wrap gap-3">
+                            <button
+                                type="button"
+                                @click="setView('source')"
+                                class="inline-flex min-h-[44px] items-center rounded-2xl border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 transition hover:border-indigo-300 hover:text-indigo-700">
+                                切换到源文件编辑
+                            </button>
+                            <button
+                                type="submit"
+                                class="inline-flex min-h-[44px] items-center rounded-2xl bg-indigo-600 px-5 py-2 text-sm font-semibold text-white shadow-lg shadow-indigo-600/20 transition hover:bg-indigo-700">
+                                保存表单并热重载
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            </form>
+
+            <form
+                x-show="activeView === 'source'"
+                x-cloak
+                hx-post="/admin/api/config/source"
+                hx-target="#config-feedback"
+                hx-swap="innerHTML"
+                class="space-y-6">
+                <section class="overflow-hidden rounded-3xl bg-white shadow-sm ring-1 ring-slate-200">
+                    <div class="border-b border-slate-200 bg-slate-50/70 px-6 py-5">
+                        <div class="flex flex-col gap-4 lg:flex-row lg:items-center lg:justify-between">
+                            <div>
+                                <h3 class="text-lg font-semibold text-slate-900">`.env` 源文件编辑器</h3>
+                                <p class="mt-1 text-sm leading-6 text-slate-600">
+                                    直接编辑源文件内容。该模式会原样覆盖整个 `.env`，适合保留注释、批量调整和整体替换。
+                                </p>
+                            </div>
+                            <span class="inline-flex max-w-full items-center rounded-2xl bg-slate-100 px-3 py-2 text-xs font-medium leading-5 text-slate-700 break-all">
+                                {{ overview.env_path }}
+                            </span>
+                        </div>
+                    </div>
+                    <div class="space-y-4 p-6">
+                        <div class="rounded-2xl border border-indigo-100 bg-indigo-50 px-4 py-3 text-sm leading-6 text-indigo-900">
+                            保存前会进行基础语法检查，确保每一行是合法的 `KEY=VALUE` 结构；如果热重载失败，系统会自动回滚到原来的 `.env`。
+                        </div>
+                        <textarea
+                            name="env_content"
+                            rows="28"
+                            spellcheck="false"
+                            class="block min-h-[560px] w-full rounded-2xl border border-slate-300 bg-slate-950 px-4 py-4 font-mono text-sm leading-6 text-slate-100 shadow-inner focus:border-indigo-500 focus:ring-indigo-500">{{ env_content }}</textarea>
+                    </div>
+                </section>
+
+                <div class="sticky bottom-4 z-10 rounded-3xl border border-slate-200 bg-white/95 p-4 shadow-2xl backdrop-blur">
+                    <div class="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+                        <p class="text-sm text-slate-600">
+                            源文件模式会直接覆盖整个 `.env`。保存后会自动刷新页面并保留当前视图。
+                        </p>
+                        <div class="flex flex-wrap gap-3">
+                            <button
+                                type="button"
+                                @click="setView('form')"
+                                class="inline-flex min-h-[44px] items-center rounded-2xl border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 transition hover:border-indigo-300 hover:text-indigo-700">
+                                返回表单视图
+                            </button>
+                            <button
+                                type="submit"
+                                class="inline-flex min-h-[44px] items-center rounded-2xl bg-slate-900 px-5 py-2 text-sm font-semibold text-white shadow-lg transition hover:bg-slate-800">
+                                保存源文件并热重载
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            </form>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+    function configPage() {
+        return {
+            activeView: localStorage.getItem('admin-config-active-view') || 'form',
+            setView(view) {
+                this.activeView = view;
+                localStorage.setItem('admin-config-active-view', view);
+            }
+        };
+    }
+
+    document.body.addEventListener('admin-config-refresh', () => {
+        setTimeout(() => {
+            window.location.reload();
+        }, 450);
+    });
+
+    document.body.addEventListener('htmx:afterSwap', function(evt) {
+        if (evt.detail.target.id === 'config-feedback') {
+            window.scrollTo({ top: 0, behavior: 'smooth' });
+        }
+    });
+</script>
+{% endblock %}

app/templates/index.html

@@ -0,0 +1,588 @@
+{% extends "base.html" %}
+
+{% block title %}仪表盘{% endblock %}
+
+{% block content %}
+<div class="space-y-6">
+    <div class="overflow-hidden rounded-3xl bg-slate-900 shadow-2xl">
+        <div class="bg-[radial-gradient(circle_at_top_right,_rgba(45,212,191,0.22),_transparent_30%),radial-gradient(circle_at_left,_rgba(59,130,246,0.18),_transparent_28%),linear-gradient(135deg,_#0f172a,_#111827_58%,_#1e293b)] px-6 py-7 sm:px-8">
+            <div class="flex flex-col gap-5 lg:flex-row lg:items-end lg:justify-between">
+                <div class="max-w-3xl">
+                    <p class="text-sm font-semibold uppercase tracking-[0.2em] text-cyan-200">Usage Dashboard</p>
+                    <h2 class="mt-3 text-3xl font-bold text-white sm:text-4xl">查看请求消耗、缓存效果、延迟表现和使用趋势</h2>
+                    <p class="mt-3 text-sm leading-6 text-slate-300 sm:text-base">
+                        统计来源于请求日志数据库，覆盖输入输出 Token、缓存创建与命中、成功率、平均延迟，以及最近 24 小时、7 天、30 天的使用趋势。
+                    </p>
+                </div>
+                <div class="rounded-2xl border border-white/10 bg-white/10 px-5 py-4 backdrop-blur">
+                    <p class="text-xs uppercase tracking-[0.2em] text-cyan-200">Last Update</p>
+                    <p id="last-update" class="mt-2 text-lg font-semibold text-white">{{ current_time }}</p>
+                    <p class="mt-1 text-sm text-slate-300">运行时间 {{ stats.uptime }}</p>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <div class="grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-4">
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">总请求数</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.total_requests }}</p>
+                </div>
+                <span class="rounded-2xl bg-slate-100 p-3 text-slate-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">成功 {{ stats.successful_requests }} / 失败 {{ stats.failed_requests }}</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">总消耗 Token 数</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.total_consumed_tokens_display }}</p>
+                </div>
+                <span class="rounded-2xl bg-emerald-50 p-3 text-emerald-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8c-1.657 0-3 1.343-3 3v6h6v-6c0-1.657-1.343-3-3-3zm0 0V5m0 3a4 4 0 00-4 4v5h8v-5a4 4 0 00-4-4z" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">累计 {{ stats.total_consumed_tokens }} Tokens</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">缓存 Token</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.total_cache_tokens_display }}</p>
+                </div>
+                <span class="rounded-2xl bg-amber-50 p-3 text-amber-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 7h16M4 12h10m-10 5h16" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">创建 {{ stats.cache_creation_tokens }} / 命中 {{ stats.cache_read_tokens }}</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">成功率</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.success_rate }}%</p>
+                </div>
+                <span class="rounded-2xl bg-sky-50 p-3 text-sky-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7h8m0 0v8m0-8l-8 8-4-4-6 6" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">图表支持切换 24 小时 / 7 天 / 30 天</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">输入 Token</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.input_tokens_display }}</p>
+                </div>
+                <span class="rounded-2xl bg-violet-50 p-3 text-violet-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20 12H4m0 0l6-6m-6 6l6 6" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">累计 {{ stats.input_tokens }} Tokens</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">输出 Token</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.output_tokens_display }}</p>
+                </div>
+                <span class="rounded-2xl bg-rose-50 p-3 text-rose-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 12h16m0 0l-6-6m6 6l-6 6" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">累计 {{ stats.output_tokens }} Tokens</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">平均延迟</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ "%.2f"|format(stats.average_latency) }}s</p>
+                </div>
+                <span class="rounded-2xl bg-orange-50 p-3 text-orange-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">平均首字延迟 {{ "%.2f"|format(stats.average_first_token_latency) }}s</p>
+        </div>
+
+        <div class="rounded-2xl bg-white p-5 shadow-sm ring-1 ring-slate-200">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <p class="text-sm font-medium text-slate-500">Token 池健康度</p>
+                    <p class="mt-2 text-3xl font-bold text-slate-900">{{ stats.healthy_tokens }}/{{ stats.pool_total_tokens }}</p>
+                </div>
+                <span class="rounded-2xl {% if stats.pool_total_tokens == 0 %}bg-slate-100 text-slate-500{% elif stats.healthy_tokens >= stats.pool_total_tokens * 0.8 %}bg-emerald-50 text-emerald-600{% elif stats.healthy_tokens >= stats.pool_total_tokens * 0.5 %}bg-amber-50 text-amber-600{% else %}bg-red-50 text-red-600{% endif %} p-3">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                </span>
+            </div>
+            <p class="mt-3 text-sm text-slate-500">可用 {{ stats.available_tokens }} / 已启用 {{ stats.enabled_tokens }} / 认证 {{ stats.user_tokens }}</p>
+        </div>
+    </div>
+
+    <div class="grid grid-cols-1 gap-6 xl:grid-cols-3">
+        <section class="rounded-3xl bg-white p-6 shadow-sm ring-1 ring-slate-200 xl:col-span-2">
+            <div class="flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
+                <div>
+                    <h3 class="text-lg font-semibold text-slate-900">使用趋势图</h3>
+                    <p
+                        id="usage-trend-description"
+                        class="mt-1 text-sm text-slate-600"
+                    >
+                        最近 7 天按天聚合的请求量、输入输出与缓存变化。
+                    </p>
+                </div>
+                <div
+                    id="usage-trend-window-switcher"
+                    class="flex flex-wrap gap-2"
+                >
+                    {% set trend_window_options = trend_windows if trend_windows is defined and trend_windows else [
+                        {'key': '24h', 'label': '24 小时'},
+                        {'key': '7d', 'label': '7 天'},
+                        {'key': '30d', 'label': '30 天'}
+                    ] %}
+                    {% for option in trend_window_options %}
+                    <button
+                        type="button"
+                        data-trend-window="{{ option.key }}"
+                        class="inline-flex items-center rounded-full border border-slate-200 bg-white px-3 py-1.5 text-sm font-medium text-slate-600 transition-colors hover:border-sky-300 hover:text-sky-700"
+                    >
+                        {{ option.label }}
+                    </button>
+                    {% endfor %}
+                </div>
+            </div>
+            <div class="mt-4 flex flex-wrap gap-2 text-xs">
+                <span class="inline-flex items-center rounded-full bg-slate-100 px-3 py-1 font-medium text-slate-600">蓝柱: 请求量</span>
+                <span class="inline-flex items-center rounded-full bg-violet-50 px-3 py-1 font-medium text-violet-700">紫线: 输入</span>
+                <span class="inline-flex items-center rounded-full bg-rose-50 px-3 py-1 font-medium text-rose-700">红线: 输出</span>
+                <span class="inline-flex items-center rounded-full bg-emerald-50 px-3 py-1 font-medium text-emerald-700">绿线: 缓存创建</span>
+                <span class="inline-flex items-center rounded-full bg-amber-50 px-3 py-1 font-medium text-amber-700">黄线: 缓存命中</span>
+            </div>
+            <div class="mt-6 h-[320px]">
+                <canvas id="usage-trend-chart"></canvas>
+            </div>
+            <p
+                id="usage-trend-error"
+                class="mt-3 hidden rounded-2xl border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700"
+            ></p>
+        </section>
+
+        <div class="space-y-6">
+            <section class="rounded-3xl bg-white p-6 shadow-sm ring-1 ring-slate-200">
+                <h3 class="text-lg font-semibold text-slate-900">缓存创建 / 命中</h3>
+                <p class="mt-1 text-sm text-slate-600">按请求次数和 Token 数量查看缓存是否真的生效。</p>
+                <div class="mt-5 grid grid-cols-1 gap-4">
+                    <div class="rounded-2xl border border-emerald-100 bg-emerald-50 p-4">
+                        <p class="text-sm font-medium text-emerald-700">缓存创建</p>
+                        <p class="mt-2 text-2xl font-bold text-emerald-900">{{ stats.cache_creation_requests }}</p>
+                        <p class="mt-1 text-sm text-emerald-700">共创建 {{ stats.cache_creation_tokens }} Tokens</p>
+                    </div>
+                    <div class="rounded-2xl border border-amber-100 bg-amber-50 p-4">
+                        <p class="text-sm font-medium text-amber-700">缓存命中</p>
+                        <p class="mt-2 text-2xl font-bold text-amber-900">{{ stats.cache_hit_requests }}</p>
+                        <p class="mt-1 text-sm text-amber-700">共命中 {{ stats.cache_read_tokens }} Tokens</p>
+                    </div>
+                </div>
+            </section>
+
+            <section class="rounded-3xl bg-white p-6 shadow-sm ring-1 ring-slate-200">
+                <h3 class="text-lg font-semibold text-slate-900">输入 / 输出画像</h3>
+                <p class="mt-1 text-sm text-slate-600">对比 Prompt 与 Completion 的消耗分布。</p>
+                {% set usage_total = stats.input_tokens + stats.output_tokens %}
+                {% set input_ratio = (stats.input_tokens / usage_total * 100) if usage_total > 0 else 0 %}
+                {% set output_ratio = (stats.output_tokens / usage_total * 100) if usage_total > 0 else 0 %}
+                <div class="mt-5 space-y-4">
+                    <div>
+                        <div class="flex items-center justify-between text-sm">
+                            <span class="font-medium text-slate-700">输入 Token</span>
+                            <span class="text-slate-500">{{ "%.1f"|format(input_ratio) }}%</span>
+                        </div>
+                        <div class="mt-2 h-2 rounded-full bg-slate-100">
+                            <div class="h-2 rounded-full bg-violet-500" style="width: {{ input_ratio }}%"></div>
+                        </div>
+                        <p class="mt-2 text-sm text-slate-500">{{ stats.input_tokens }} Tokens</p>
+                    </div>
+                    <div>
+                        <div class="flex items-center justify-between text-sm">
+                            <span class="font-medium text-slate-700">输出 Token</span>
+                            <span class="text-slate-500">{{ "%.1f"|format(output_ratio) }}%</span>
+                        </div>
+                        <div class="mt-2 h-2 rounded-full bg-slate-100">
+                            <div class="h-2 rounded-full bg-rose-500" style="width: {{ output_ratio }}%"></div>
+                        </div>
+                        <p class="mt-2 text-sm text-slate-500">{{ stats.output_tokens }} Tokens</p>
+                    </div>
+                </div>
+            </section>
+        </div>
+    </div>
+
+    <div class="bg-white shadow rounded-lg">
+        <div class="px-6 py-4 border-b border-gray-200 flex items-center justify-between">
+            <h3 class="text-lg font-medium text-gray-900">最近请求日志</h3>
+            <div class="flex items-center space-x-2">
+                <label class="flex items-center cursor-pointer">
+                    <input id="recent-logs-auto-refresh" type="checkbox" checked class="form-checkbox h-4 w-4 text-indigo-600">
+                    <span class="ml-2 text-sm text-gray-600">自动刷新</span>
+                </label>
+            </div>
+        </div>
+        <div class="p-6">
+            <div
+                id="recent-logs"
+                hx-get="/admin/api/recent-logs?page=1&page_size=12"
+                hx-trigger="load"
+                hx-swap="innerHTML">
+                <div class="flex justify-center items-center py-12">
+                    <svg class="animate-spin h-8 w-8 text-indigo-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                        <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                        <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                    </svg>
+                    <span class="ml-3 text-gray-500">加载中...</span>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+    window.dashboardRecentLogsPage = 1;
+    window.dashboardRecentLogsPageSize = 12;
+    window.dashboardTrendWindow = {{ stats.get('trend_window', '7d') | tojson }};
+    window.dashboardTrendData = {{ stats.get('usage_trend', []) | tojson }};
+    window.dashboardTrendChart = null;
+
+    const trendWindowDescriptions = {
+        '24h': '最近 24 小时按小时聚合的请求量、输入输出与缓存变化。',
+        '7d': '最近 7 天按天聚合的请求量、输入输出与缓存变化。',
+        '30d': '最近 30 天按天聚合的请求量、输入输出与缓存变化。'
+    };
+
+    function loadRecentLogsPage(page) {
+        const nextPage = Math.max(1, Number(page) || 1);
+        window.dashboardRecentLogsPage = nextPage;
+        const url = `/admin/api/recent-logs?page=${nextPage}&page_size=${window.dashboardRecentLogsPageSize}`;
+        htmx.ajax('GET', url, {
+            target: '#recent-logs',
+            swap: 'innerHTML'
+        });
+    }
+
+    function updateTime() {
+        const now = new Date();
+        document.getElementById('last-update').textContent = now.toLocaleString('zh-CN');
+    }
+
+    function updateTrendDescription() {
+        const description = document.getElementById('usage-trend-description');
+        if (!description) {
+            return;
+        }
+        description.textContent = (
+            trendWindowDescriptions[window.dashboardTrendWindow]
+            || trendWindowDescriptions['7d']
+        );
+    }
+
+    function updateTrendWindowButtons() {
+        document
+            .querySelectorAll('[data-trend-window]')
+            .forEach((button) => {
+                const isActive = (
+                    button.dataset.trendWindow === window.dashboardTrendWindow
+                );
+                button.disabled = false;
+                button.classList.toggle('bg-sky-600', isActive);
+                button.classList.toggle('border-sky-600', isActive);
+                button.classList.toggle('text-white', isActive);
+                button.classList.toggle('shadow-sm', isActive);
+                button.classList.toggle('bg-white', !isActive);
+                button.classList.toggle('border-slate-200', !isActive);
+                button.classList.toggle('text-slate-600', !isActive);
+            });
+    }
+
+    function setTrendLoadingState(isLoading) {
+        document
+            .querySelectorAll('[data-trend-window]')
+            .forEach((button) => {
+                button.disabled = isLoading;
+                button.classList.toggle('opacity-60', isLoading);
+                button.classList.toggle('cursor-not-allowed', isLoading);
+            });
+    }
+
+    function showTrendError(message) {
+        const errorBox = document.getElementById('usage-trend-error');
+        if (!errorBox) {
+            return;
+        }
+        if (!message) {
+            errorBox.classList.add('hidden');
+            errorBox.textContent = '';
+            return;
+        }
+        errorBox.textContent = message;
+        errorBox.classList.remove('hidden');
+    }
+
+    function renderUsageTrendChart() {
+        const canvas = document.getElementById('usage-trend-chart');
+        if (!canvas) {
+            return;
+        }
+
+        const usageTrend = window.dashboardTrendData || [];
+        const labels = usageTrend.map((item) => item.label);
+        const requestSeries = usageTrend.map((item) => item.total_requests);
+        const inputSeries = usageTrend.map((item) => item.input_tokens);
+        const outputSeries = usageTrend.map((item) => item.output_tokens);
+        const cacheCreationSeries = usageTrend.map(
+            (item) => item.cache_creation_tokens
+        );
+        const cacheReadSeries = usageTrend.map(
+            (item) => item.cache_read_tokens
+        );
+
+        if (window.dashboardTrendChart) {
+            window.dashboardTrendChart.destroy();
+        }
+
+        window.dashboardTrendChart = new Chart(canvas, {
+            type: 'bar',
+            data: {
+                labels,
+                datasets: [
+                    {
+                        type: 'bar',
+                        label: '请求量',
+                        data: requestSeries,
+                        yAxisID: 'yRequests',
+                        backgroundColor: 'rgba(59, 130, 246, 0.18)',
+                        borderColor: 'rgba(59, 130, 246, 0.85)',
+                        borderWidth: 1.5,
+                        borderRadius: 10
+                    },
+                    {
+                        type: 'line',
+                        label: '输入 Token',
+                        data: inputSeries,
+                        yAxisID: 'yTokens',
+                        borderColor: '#8b5cf6',
+                        backgroundColor: 'rgba(139, 92, 246, 0.16)',
+                        borderWidth: 3,
+                        tension: 0.35,
+                        pointRadius: 3,
+                        pointHoverRadius: 5,
+                        fill: false
+                    },
+                    {
+                        type: 'line',
+                        label: '输出 Token',
+                        data: outputSeries,
+                        yAxisID: 'yTokens',
+                        borderColor: '#f43f5e',
+                        backgroundColor: 'rgba(244, 63, 94, 0.16)',
+                        borderWidth: 3,
+                        tension: 0.35,
+                        pointRadius: 3,
+                        pointHoverRadius: 5,
+                        fill: false
+                    },
+                    {
+                        type: 'line',
+                        label: '缓存创建',
+                        data: cacheCreationSeries,
+                        yAxisID: 'yTokens',
+                        borderColor: '#10b981',
+                        backgroundColor: 'rgba(16, 185, 129, 0.16)',
+                        borderWidth: 2,
+                        borderDash: [6, 4],
+                        tension: 0.35,
+                        pointRadius: 2,
+                        pointHoverRadius: 4,
+                        fill: false
+                    },
+                    {
+                        type: 'line',
+                        label: '缓存命中',
+                        data: cacheReadSeries,
+                        yAxisID: 'yTokens',
+                        borderColor: '#f59e0b',
+                        backgroundColor: 'rgba(245, 158, 11, 0.15)',
+                        borderWidth: 2,
+                        borderDash: [3, 4],
+                        tension: 0.35,
+                        pointRadius: 2,
+                        pointHoverRadius: 4,
+                        fill: false
+                    }
+                ]
+            },
+            options: {
+                maintainAspectRatio: false,
+                interaction: {
+                    mode: 'index',
+                    intersect: false
+                },
+                plugins: {
+                    legend: {
+                        position: 'bottom',
+                        labels: {
+                            usePointStyle: true,
+                            boxWidth: 10,
+                            color: '#475569'
+                        }
+                    },
+                    tooltip: {
+                        callbacks: {
+                            title(context) {
+                                const index = context[0]?.dataIndex ?? 0;
+                                return (
+                                    usageTrend[index]?.tooltip_label
+                                    || usageTrend[index]?.label
+                                    || ''
+                                );
+                            },
+                            label(context) {
+                                const value = Number(context.parsed.y || 0);
+                                if (context.dataset.label === '请求量') {
+                                    return `${context.dataset.label}: ${value} 次`;
+                                }
+                                return (
+                                    `${context.dataset.label}: `
+                                    + `${value.toLocaleString('zh-CN')} Tokens`
+                                );
+                            }
+                        }
+                    }
+                },
+                scales: {
+                    x: {
+                        grid: {
+                            display: false
+                        }
+                    },
+                    yRequests: {
+                        position: 'left',
+                        beginAtZero: true,
+                        ticks: {
+                            precision: 0
+                        },
+                        grid: {
+                            color: 'rgba(148, 163, 184, 0.14)'
+                        }
+                    },
+                    yTokens: {
+                        position: 'right',
+                        beginAtZero: true,
+                        grid: {
+                            drawOnChartArea: false
+                        },
+                        ticks: {
+                            callback(value) {
+                                return Number(value).toLocaleString('zh-CN');
+                            }
+                        }
+                    }
+                }
+            }
+        });
+
+        updateTrendDescription();
+        updateTrendWindowButtons();
+    }
+
+    async function loadUsageTrend(windowKey) {
+        const nextWindow = String(windowKey || '').trim();
+        if (!nextWindow) {
+            return;
+        }
+
+        setTrendLoadingState(true);
+        showTrendError('');
+
+        try {
+            const response = await fetch(
+                `/admin/api/dashboard/usage-trend?window=${encodeURIComponent(nextWindow)}`,
+                {
+                    headers: {
+                        'X-Requested-With': 'XMLHttpRequest'
+                    }
+                }
+            );
+
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+
+            const payload = await response.json();
+            window.dashboardTrendWindow = payload.window || '7d';
+            window.dashboardTrendData = payload.points || [];
+            renderUsageTrendChart();
+        } catch (error) {
+            showTrendError('趋势图加载失败，请稍后重试。');
+            console.error('Failed to load dashboard trend:', error);
+        } finally {
+            setTrendLoadingState(false);
+        }
+    }
+
+    function initTrendWindowSwitcher() {
+        updateTrendDescription();
+        updateTrendWindowButtons();
+
+        document
+            .querySelectorAll('[data-trend-window]')
+            .forEach((button) => {
+                button.addEventListener('click', () => {
+                    const nextWindow = button.dataset.trendWindow;
+                    if (nextWindow === window.dashboardTrendWindow) {
+                        return;
+                    }
+                    loadUsageTrend(nextWindow);
+                });
+            });
+    }
+
+    updateTime();
+    initTrendWindowSwitcher();
+    renderUsageTrendChart();
+    setInterval(updateTime, 1000);
+
+    setInterval(() => {
+        const checkbox = document.getElementById('recent-logs-auto-refresh');
+        if (checkbox && checkbox.checked) {
+            loadRecentLogsPage(window.dashboardRecentLogsPage || 1);
+        }
+    }, 3000);
+</script>
+{% endblock %}

app/templates/login.html

@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html lang="zh-CN" class="h-full bg-gray-50">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>登录 - API 控制台</title>
+
+    <!-- Tailwind CSS (CDN) -->
+    <script src="https://cdn.tailwindcss.com"></script>
+
+    <!-- Alpine.js (CDN) -->
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+
+    <style>
+        .gradient-bg {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        }
+    </style>
+</head>
+<body class="h-full">
+    <div class="min-h-full flex items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
+        <div class="max-w-md w-full space-y-8">
+            <!-- Logo 和标题 -->
+            <div>
+                <div class="mx-auto h-16 w-16 flex items-center justify-center rounded-full gradient-bg">
+                    <svg class="h-10 w-10 text-white" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
+                    </svg>
+                </div>
+                <h2 class="mt-6 text-center text-3xl font-extrabold text-gray-900">
+                    API 管理后台
+                </h2>
+                <p class="mt-2 text-center text-sm text-gray-600">
+                    请输入管理密码以继续
+                </p>
+            </div>
+
+            <!-- 登录表单 -->
+            <div class="mt-8 space-y-6"
+                 x-data="{
+                     password: '',
+                     loading: false,
+                     error: '',
+                     async login() {
+                         if (!this.password) {
+                             this.error = '请输入密码';
+                             return;
+                         }
+
+                         this.loading = true;
+                         this.error = '';
+
+                         try {
+                             const response = await fetch('/admin/api/login', {
+                                 method: 'POST',
+                                 headers: {
+                                     'Content-Type': 'application/json',
+                                 },
+                                 body: JSON.stringify({ password: this.password })
+                             });
+
+                             const data = await response.json();
+
+                             if (response.ok && data.success) {
+                                 window.location.href = '/admin';
+                             } else {
+                                 this.error = data.message || '密码错误，请重试';
+                             }
+                         } catch (err) {
+                             this.error = '登录失败，请稍后重试';
+                         } finally {
+                             this.loading = false;
+                         }
+                     }
+                 }">
+
+                <!-- 错误提示 -->
+                <div x-show="error"
+                     x-transition
+                     class="bg-red-50 border-l-4 border-red-400 p-4">
+                    <div class="flex">
+                        <div class="flex-shrink-0">
+                            <svg class="h-5 w-5 text-red-400" viewBox="0 0 20 20" fill="currentColor">
+                                <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z" clip-rule="evenodd" />
+                            </svg>
+                        </div>
+                        <div class="ml-3">
+                            <p class="text-sm text-red-700" x-text="error"></p>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- 登录表单 -->
+                <form @submit.prevent="login" class="mt-8 space-y-6">
+                    <div class="rounded-md shadow-sm -space-y-px">
+                        <div>
+                            <label for="password" class="sr-only">密码</label>
+                            <input
+                                id="password"
+                                name="password"
+                                type="password"
+                                autocomplete="current-password"
+                                required
+                                x-model="password"
+                                class="appearance-none rounded-md relative block w-full px-3 py-3 border border-gray-300 placeholder-gray-500 text-gray-900 focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
+                                placeholder="请输入管理密码"
+                                @keydown.enter="login">
+                        </div>
+                    </div>
+
+                    <div>
+                        <button
+                            type="submit"
+                            :disabled="loading"
+                            class="group relative w-full flex justify-center py-3 px-4 border border-transparent text-sm font-medium rounded-md text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
+                            <span class="absolute left-0 inset-y-0 flex items-center pl-3">
+                                <svg class="h-5 w-5 text-indigo-500 group-hover:text-indigo-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                                    <path fill-rule="evenodd" d="M10 1a4.5 4.5 0 00-4.5 4.5V9H5a2 2 0 00-2 2v6a2 2 0 002 2h10a2 2 0 002-2v-6a2 2 0 00-2-2h-.5V5.5A4.5 4.5 0 0010 1zm3 8V5.5a3 3 0 10-6 0V9h6z" clip-rule="evenodd" />
+                                </svg>
+                            </span>
+                            <span x-show="!loading">登录</span>
+                            <span x-show="loading" class="flex items-center">
+                                <svg class="animate-spin -ml-1 mr-3 h-5 w-5 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                                </svg>
+                                登录中...
+                            </span>
+                        </button>
+                    </div>
+                </form>
+
+                <!-- 提示信息 -->
+                <div class="text-center">
+                    <p class="text-xs text-gray-500">
+                        默认密码：admin123（请在 .env 中修改 ADMIN_PASSWORD）
+                    </p>
+                </div>
+            </div>
+        </div>
+    </div>
+</body>
+</html>

app/templates/logs.html

@@ -0,0 +1,59 @@
+{% extends "base.html" %}
+
+{% block title %}实时日志{% endblock %}
+
+{% block content %}
+<div class="space-y-6">
+    <div class="flex items-center justify-between">
+        <div>
+            <h2 class="text-3xl font-bold text-gray-900">实时日志</h2>
+            <p class="mt-1 text-sm text-gray-600">滚动查看服务当前输出的最新日志</p>
+        </div>
+        <div class="flex items-center space-x-3">
+            <button
+                onclick="window.location.reload()"
+                class="px-4 py-2 bg-indigo-600 text-white rounded-lg hover:bg-indigo-700 transition-colors">
+                刷新页面
+            </button>
+        </div>
+    </div>
+
+    <div class="bg-white shadow rounded-lg">
+        <div class="px-6 py-4 border-b border-gray-200 flex items-center justify-between">
+            <h3 class="text-lg font-medium text-gray-900">日志流</h3>
+            <div class="flex space-x-2">
+                <button
+                    onclick="document.getElementById('live-logs').innerHTML = '<div class=\'text-center text-gray-500 py-4\'>日志已清空</div>'"
+                    class="px-3 py-1 text-sm bg-gray-200 hover:bg-gray-300 rounded-md transition-colors">
+                    清空
+                </button>
+            </div>
+        </div>
+        <div class="p-6">
+            <div
+                id="live-logs"
+                hx-get="/admin/api/live-logs"
+                hx-trigger="load, every 3s"
+                hx-swap="innerHTML scroll:bottom"
+                class="bg-gray-900 text-gray-100 p-4 rounded-md font-mono text-sm overflow-y-auto"
+                style="max-height: 600px;">
+                <div class="flex justify-center items-center py-8">
+                    <span class="text-gray-500">加载中...</span>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+    const logsContainer = document.getElementById('live-logs');
+
+    document.body.addEventListener('htmx:afterSwap', function(event) {
+        if (event.detail.target.id === 'live-logs') {
+            logsContainer.scrollTop = logsContainer.scrollHeight;
+        }
+    });
+</script>
+{% endblock %}

app/templates/tokens.html

@@ -0,0 +1,487 @@
+{% extends "base.html" %}
+
+{% block title %}Token 管理{% endblock %}
+
+{% block content %}
+<div class="space-y-6" x-data='{
+    showAddModal: false,
+    showValidateModal: false,
+    newToken: "",
+    bulkTokens: "",
+    hasImportSourceDir: {{ "true" if automation.has_import_source_dir else "false" }},
+    hasMaintenanceActions: {{ "true" if automation.has_maintenance_actions else "false" }},
+    isImporting: false,
+    isRunningMaintenance: false,
+    isValidating: false
+}'>
+    <!-- 页面标题 -->
+    <div class="flex items-center justify-between">
+        <div>
+            <h2 class="text-3xl font-bold text-gray-900">Token 管理</h2>
+            <p class="mt-1 text-sm text-gray-600">管理和维护当前服务使用的 Token</p>
+        </div>
+        <div class="flex flex-wrap gap-3">
+            <a href="{{ automation.config_url }}"
+               class="px-4 py-2 bg-slate-900 text-white rounded-md text-sm font-medium hover:bg-slate-800 flex items-center">
+                <svg class="h-5 w-5 mr-1" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+                </svg>
+                打开配置中心
+            </a>
+            <button @click="showValidateModal = true"
+                    class="px-4 py-2 bg-blue-600 text-white rounded-md text-sm font-medium hover:bg-blue-700 flex items-center">
+                <svg class="h-5 w-5 mr-1" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                </svg>
+                批量验证
+            </button>
+            <button @click="showAddModal = true"
+                    class="px-4 py-2 bg-indigo-600 text-white rounded-md text-sm font-medium hover:bg-indigo-700 flex items-center">
+                <svg class="h-5 w-5 mr-1" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+                </svg>
+                添加 Token
+            </button>
+        </div>
+    </div>
+
+    <!-- 统计面板 -->
+    <div id="token-stats"
+         hx-get="/admin/api/tokens/stats"
+         hx-trigger="load, statsRefresh from:body"
+         hx-swap="innerHTML">
+        <!-- 加载中 -->
+        <div class="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-4">
+            <div class="bg-white overflow-hidden shadow rounded-lg animate-pulse">
+                <div class="p-5">
+                    <div class="h-4 bg-gray-200 rounded w-1/2 mb-2"></div>
+                    <div class="h-8 bg-gray-200 rounded w-1/3"></div>
+                </div>
+            </div>
+            <div class="bg-white overflow-hidden shadow rounded-lg animate-pulse">
+                <div class="p-5">
+                    <div class="h-4 bg-gray-200 rounded w-1/2 mb-2"></div>
+                    <div class="h-8 bg-gray-200 rounded w-1/3"></div>
+                </div>
+            </div>
+            <div class="bg-white overflow-hidden shadow rounded-lg animate-pulse">
+                <div class="p-5">
+                    <div class="h-4 bg-gray-200 rounded w-1/2 mb-2"></div>
+                    <div class="h-8 bg-gray-200 rounded w-1/3"></div>
+                </div>
+            </div>
+            <div class="bg-white overflow-hidden shadow rounded-lg animate-pulse">
+                <div class="p-5">
+                    <div class="h-4 bg-gray-200 rounded w-1/2 mb-2"></div>
+                    <div class="h-8 bg-gray-200 rounded w-1/3"></div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- 自动目录导入与维护 -->
+    <div id="token-automation" class="grid grid-cols-1 gap-6 xl:grid-cols-2">
+        <section class="bg-white shadow rounded-lg p-6 space-y-5">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <h3 class="text-lg font-medium text-gray-900">目录导入策略</h3>
+                    <p class="mt-1 text-sm text-gray-600">
+                        配置入口已迁移到配置管理页。这里仅展示当前策略，并允许立即执行一次导入。
+                    </p>
+                </div>
+                <span class="inline-flex items-center rounded-full px-3 py-1 text-xs font-semibold {% if automation.import_enabled %}bg-emerald-100 text-emerald-700{% else %}bg-gray-100 text-gray-600{% endif %}">
+                    {{ '定时已开启' if automation.import_enabled else '定时已关闭' }}
+                </span>
+            </div>
+
+            {% if automation.has_import_source_dir %}
+            <div class="rounded-lg border border-emerald-100 bg-emerald-50 p-4 text-sm text-emerald-700">
+                手动导入会复用当前配置的目录和验证逻辑，重复 Token 会自动跳过。
+            </div>
+            {% else %}
+            <div class="rounded-lg border border-amber-100 bg-amber-50 p-4 text-sm text-amber-700">
+                还没有配置导入目录，无法执行手动导入。请先到配置管理页设置 `TOKEN_AUTO_IMPORT_SOURCE_DIR`。
+            </div>
+            {% endif %}
+
+            <dl class="space-y-4 text-sm">
+                <div class="rounded-lg border border-gray-200 p-4">
+                    <dt class="font-medium text-gray-700">Token 目录</dt>
+                    <dd class="mt-2 rounded-md bg-gray-50 px-3 py-2 font-mono text-xs text-gray-700 break-all">
+                        {{ automation.import_source_dir or '未配置' }}
+                    </dd>
+                </div>
+                <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                    <div class="rounded-lg border border-gray-200 p-4">
+                        <dt class="font-medium text-gray-700">扫描间隔</dt>
+                        <dd class="mt-2 text-gray-900">{{ automation.import_interval }} 秒</dd>
+                    </div>
+                    <div class="rounded-lg border border-gray-200 p-4">
+                        <dt class="font-medium text-gray-700">配置位置</dt>
+                        <dd class="mt-2 text-gray-900">配置管理 / Token 池策略</dd>
+                    </div>
+                </div>
+            </dl>
+
+            <div class="flex flex-wrap gap-3 pt-2">
+                <a href="{{ automation.config_url }}"
+                   class="px-4 py-2 border border-emerald-200 text-emerald-700 rounded-md text-sm font-medium hover:bg-emerald-50">
+                    去配置中心修改
+                </a>
+                <button type="button"
+                        hx-post="/admin/api/tokens/import-directory"
+                        hx-target="#notification"
+                        @htmx:before-request="isImporting = true"
+                        @htmx:after-request="isImporting = false; if ($event.detail.successful) { htmx.trigger('body', 'tokenListRefresh'); htmx.trigger('body', 'statsRefresh'); }"
+                        :disabled="isImporting || !hasImportSourceDir"
+                        class="px-4 py-2 bg-emerald-600 text-white rounded-md text-sm font-medium hover:bg-emerald-700 disabled:opacity-50 disabled:cursor-not-allowed">
+                    立即导入当前目录
+                </button>
+            </div>
+        </section>
+
+        <section class="bg-white shadow rounded-lg p-6 space-y-5">
+            <div class="flex items-start justify-between gap-4">
+                <div>
+                    <h3 class="text-lg font-medium text-gray-900">自动维护策略</h3>
+                    <p class="mt-1 text-sm text-gray-600">
+                        维护动作和定时间隔统一在配置管理页设置。这里仅执行当前已配置的维护策略。
+                    </p>
+                </div>
+                <span class="inline-flex items-center rounded-full px-3 py-1 text-xs font-semibold {% if automation.maintenance_enabled %}bg-blue-100 text-blue-700{% else %}bg-gray-100 text-gray-600{% endif %}">
+                    {{ '定时已开启' if automation.maintenance_enabled else '定时已关闭' }}
+                </span>
+            </div>
+
+            {% if automation.has_maintenance_actions %}
+            <div class="rounded-lg border border-blue-100 bg-blue-50 p-4 text-sm text-blue-700">
+                手动维护会按当前配置顺序执行去重、测活和失效清理，不再在本页单独维护另一套选项。
+            </div>
+            {% else %}
+            <div class="rounded-lg border border-amber-100 bg-amber-50 p-4 text-sm text-amber-700">
+                当前没有配置任何维护动作。请先到配置管理页勾选至少一个维护动作。
+            </div>
+            {% endif %}
+
+            <dl class="space-y-4 text-sm">
+                <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                    <div class="rounded-lg border border-gray-200 p-4">
+                        <dt class="font-medium text-gray-700">维护间隔</dt>
+                        <dd class="mt-2 text-gray-900">{{ automation.maintenance_interval }} 秒</dd>
+                    </div>
+                    <div class="rounded-lg border border-gray-200 p-4">
+                        <dt class="font-medium text-gray-700">配置位置</dt>
+                        <dd class="mt-2 text-gray-900">配置管理 / Token 池策略</dd>
+                    </div>
+                </div>
+                <div class="rounded-lg border border-gray-200 p-4">
+                    <dt class="font-medium text-gray-700">当前维护动作</dt>
+                    <dd class="mt-2 flex flex-wrap gap-2">
+                        {% if automation.maintenance_actions %}
+                        {% for action in automation.maintenance_actions %}
+                        <span class="inline-flex items-center rounded-full bg-blue-50 px-3 py-1 text-xs font-semibold text-blue-700">{{ action }}</span>
+                        {% endfor %}
+                        {% else %}
+                        <span class="text-gray-500">未配置</span>
+                        {% endif %}
+                    </dd>
+                </div>
+            </dl>
+
+            <div class="flex flex-wrap gap-3 pt-2">
+                <a href="{{ automation.config_url }}"
+                   class="px-4 py-2 border border-blue-200 text-blue-700 rounded-md text-sm font-medium hover:bg-blue-50">
+                    去配置中心修改
+                </a>
+                <button type="button"
+                        hx-post="/admin/api/tokens/maintenance/run"
+                        hx-target="#notification"
+                        @htmx:before-request="isRunningMaintenance = true"
+                        @htmx:after-request="isRunningMaintenance = false; if ($event.detail.successful) { htmx.trigger('body', 'tokenListRefresh'); htmx.trigger('body', 'statsRefresh'); }"
+                        :disabled="isRunningMaintenance || !hasMaintenanceActions"
+                        class="px-4 py-2 bg-blue-600 text-white rounded-md text-sm font-medium hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed">
+                    执行当前维护策略
+                </button>
+            </div>
+        </section>
+    </div>
+
+    <!-- Token 列表 -->
+    <div class="bg-white shadow rounded-lg">
+        <div class="px-6 py-4 border-b border-gray-200 flex items-center justify-between">
+            <h3 class="text-lg font-medium text-gray-900 flex items-center">
+                Token 列表
+                <span class="ml-2 text-sm font-normal text-gray-500" id="token-count"></span>
+            </h3>
+            <div class="flex items-center space-x-2">
+                <button hx-post="/admin/api/tokens/sync-pool"
+                        hx-target="#notification"
+                        class="text-sm text-purple-600 hover:text-purple-700 flex items-center">
+                    <svg class="h-4 w-4 mr-1" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
+                    </svg>
+                    同步 Token 池
+                </button>
+                <button hx-post="/admin/api/tokens/health-check"
+                        hx-target="#notification"
+                        class="text-sm text-blue-600 hover:text-blue-700 flex items-center">
+                    <svg class="h-4 w-4 mr-1" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                    健康检查
+                </button>
+            </div>
+        </div>
+        <div id="token-list"
+             hx-get="/admin/api/tokens/list?page=1&page_size=20"
+             hx-trigger="load"
+             hx-swap="innerHTML">
+            <!-- Token 列表内容 -->
+            <div class="flex justify-center items-center py-12">
+                <svg class="animate-spin h-8 w-8 text-indigo-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                </svg>
+            </div>
+        </div>
+    </div>
+
+    <!-- 添加 Token 弹窗 -->
+    <div x-show="showAddModal"
+         x-transition:enter="transition ease-out duration-300"
+         x-transition:enter-start="opacity-0"
+         x-transition:enter-end="opacity-100"
+         class="fixed inset-0 bg-gray-600 bg-opacity-50 overflow-y-auto h-full w-full z-50"
+         @click.self="showAddModal = false"
+         style="display: none;">
+        <div class="relative top-20 mx-auto p-5 border w-full max-w-2xl shadow-lg rounded-md bg-white">
+            <div class="flex items-center justify-between pb-3 border-b">
+                <h3 class="text-lg font-medium">添加 Token</h3>
+                <button @click="showAddModal = false" class="text-gray-400 hover:text-gray-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                </button>
+            </div>
+
+            <div class="mt-4 space-y-4">
+                <!-- 提示信息 -->
+                <div class="bg-blue-50 border-l-4 border-blue-400 p-4">
+                    <div class="flex">
+                        <div class="flex-shrink-0">
+                            <svg class="h-5 w-5 text-blue-400" fill="currentColor" viewBox="0 0 20 20">
+                                <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z" clip-rule="evenodd" />
+                            </svg>
+                        </div>
+                        <div class="ml-3">
+                            <p class="text-sm text-blue-700">
+                                <strong>Token 验证：</strong>添加时将自动验证 Token 有效性，
+                                <span class="font-semibold">匿名用户 Token (guest) 将被拒绝</span>。
+                            </p>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- 单个 Token -->
+                <div>
+                    <label class="block text-sm font-medium text-gray-700">单个 Token</label>
+                    <input type="text"
+                           x-model="newToken"
+                           placeholder="输入 Token（以 eyJ 开头的 JWT）"
+                           class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 sm:text-sm">
+                </div>
+
+                <!-- 批量导入 -->
+                <div>
+                    <label class="block text-sm font-medium text-gray-700">批量导入（每行一个）</label>
+                    <textarea x-model="bulkTokens"
+                              rows="6"
+                              placeholder="每行一个 Token，支持逗号分隔&#10;eyJhbGc...&#10;eyJhbGc...&#10;或: token1, token2, token3"
+                              class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 sm:text-sm font-mono text-xs"></textarea>
+                    <p class="mt-1 text-sm text-gray-500">支持格式：每行一个 Token，或使用逗号分隔</p>
+                </div>
+
+                <!-- 提交按钮 -->
+                <div class="flex justify-end space-x-3 pt-4 border-t">
+                    <button @click="showAddModal = false"
+                            class="px-4 py-2 border border-gray-300 rounded-md text-sm font-medium text-gray-700 bg-white hover:bg-gray-50">
+                        取消
+                    </button>
+                    <button hx-post="/admin/api/tokens/add"
+                            :hx-vals="JSON.stringify({
+                                single_token: newToken,
+                                bulk_tokens: bulkTokens
+                            })"
+                            hx-target="#notification"
+                            @htmx:after-request="showAddModal = false; newToken = ''; bulkTokens = ''; htmx.trigger('body', 'tokenListRefresh'); htmx.trigger('body', 'statsRefresh')"
+                            class="px-4 py-2 bg-indigo-600 text-white rounded-md text-sm font-medium hover:bg-indigo-700">
+                        添加
+                    </button>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- 批量验证弹窗 -->
+    <div x-show="showValidateModal"
+         x-transition:enter="transition ease-out duration-300"
+         x-transition:enter-start="opacity-0"
+         x-transition:enter-end="opacity-100"
+         class="fixed inset-0 bg-gray-600 bg-opacity-50 overflow-y-auto h-full w-full z-50"
+         @click.self="showValidateModal = false"
+         style="display: none;">
+        <div class="relative top-20 mx-auto p-5 border w-full max-w-lg shadow-lg rounded-md bg-white">
+            <div class="flex items-center justify-between pb-3 border-b">
+                <h3 class="text-lg font-medium">批量验证 Token</h3>
+                <button @click="showValidateModal = false" class="text-gray-400 hover:text-gray-600">
+                    <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                </button>
+            </div>
+
+            <div class="mt-4 space-y-4">
+                <!-- 警告信息 -->
+                <div class="bg-yellow-50 border-l-4 border-yellow-400 p-4">
+                    <div class="flex">
+                        <div class="flex-shrink-0">
+                            <svg class="h-5 w-5 text-yellow-400" fill="currentColor" viewBox="0 0 20 20">
+                                <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd" />
+                            </svg>
+                        </div>
+                        <div class="ml-3">
+                            <p class="text-sm text-yellow-700">
+                                将验证当前通道的所有 Token 的有效性。
+                                <br>此操作可能需要较长时间，请耐心等待。
+                            </p>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- 验证说明 -->
+                <div class="text-sm text-gray-600 space-y-2">
+                    <p><strong>验证内容：</strong></p>
+                    <ul class="list-disc list-inside space-y-1 ml-4">
+                        <li>检查 Token 是否有效</li>
+                        <li>识别 Token 类型（认证用户 / 匿名用户）</li>
+                        <li>更新数据库中的 Token 类型</li>
+                        <li>匿名用户 Token 将被标记为不健康</li>
+                    </ul>
+                </div>
+
+                <!-- 进度显示 -->
+                <div id="validate-progress" class="hidden">
+                    <div class="flex items-center justify-center py-4">
+                        <svg class="animate-spin h-8 w-8 text-indigo-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                            <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                            <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                        </svg>
+                        <span class="ml-3 text-gray-700">验证中...</span>
+                    </div>
+                </div>
+
+                <!-- 提交按钮 -->
+                <div class="flex justify-end space-x-3 pt-4 border-t">
+                    <button @click="showValidateModal = false"
+                            :disabled="isValidating"
+                            class="px-4 py-2 border border-gray-300 rounded-md text-sm font-medium text-gray-700 bg-white hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed">
+                        取消
+                    </button>
+                    <button hx-post="/admin/api/tokens/validate"
+                            hx-target="#notification"
+                            @htmx:before-request="isValidating = true; document.getElementById('validate-progress').classList.remove('hidden')"
+                            @htmx:after-request="isValidating = false; showValidateModal = false; document.getElementById('validate-progress').classList.add('hidden'); htmx.trigger('body', 'tokenListRefresh'); htmx.trigger('body', 'statsRefresh')"
+                            :disabled="isValidating"
+                            class="px-4 py-2 bg-blue-600 text-white rounded-md text-sm font-medium hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed">
+                        开始验证
+                    </button>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+window.tokenListPage = 1;
+window.tokenListPageSize = 20;
+
+function loadTokenListPage(page) {
+    const nextPage = Math.max(1, Number(page) || 1);
+    window.tokenListPage = nextPage;
+    const url = `/admin/api/tokens/list?page=${nextPage}&page_size=${window.tokenListPageSize}`;
+    htmx.ajax('GET', url, {
+        target: '#token-list',
+        swap: 'innerHTML'
+    });
+}
+
+// 全局通知函数
+function showNotification(message, type = 'success') {
+    const notification = document.createElement('div');
+    const bgColor = type === 'success' ? 'bg-green-500' : type === 'error' ? 'bg-red-500' : 'bg-blue-500';
+    notification.className = `fixed top-4 right-4 ${bgColor} text-white px-6 py-3 rounded-lg shadow-lg z-50 transition-all transform`;
+    notification.style.animation = 'slideInRight 0.3s ease-out';
+    notification.innerHTML = `
+        <div class="flex items-center space-x-2">
+            <svg class="h-5 w-5" fill="currentColor" viewBox="0 0 20 20">
+                <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
+            </svg>
+            <span class="font-medium">${message}</span>
+        </div>
+    `;
+
+    document.body.appendChild(notification);
+
+    // 3秒后自动消失
+    setTimeout(() => {
+        notification.style.opacity = '0';
+        notification.style.transform = 'translateX(100%)';
+        setTimeout(() => notification.remove(), 300);
+    }, 3000);
+}
+
+// 添加动画样式
+if (!document.getElementById('notification-styles')) {
+    const style = document.createElement('style');
+    style.id = 'notification-styles';
+    style.textContent = `
+        @keyframes slideInRight {
+            from {
+                opacity: 0;
+                transform: translateX(100%);
+            }
+            to {
+                opacity: 1;
+                transform: translateX(0);
+            }
+        }
+    `;
+    document.head.appendChild(style);
+}
+
+// 监听验证按钮的完成事件
+document.body.addEventListener('htmx:afterSwap', function(evt) {
+    // 检查是否是验证按钮触发的事件
+    if (evt.detail.target && evt.detail.target.id && evt.detail.target.id.startsWith('token-row-')) {
+        // 从目标元素提取 token ID
+        const tokenId = evt.detail.target.id.replace('token-row-', '');
+
+        // 检查是否是验证操作（通过查看触发元素）
+        const triggerElt = evt.detail.requestConfig?.elt;
+        if (triggerElt && triggerElt.classList.contains('validate-token-btn')) {
+            showNotification(`✓ Token ID ${tokenId} 验证完成`, 'success');
+
+            // 同时刷新统计数据
+            htmx.trigger('body', 'statsRefresh');
+        }
+    }
+});
+
+document.body.addEventListener('tokenListRefresh', function() {
+    loadTokenListPage(window.tokenListPage || 1);
+});
+</script>
+{% endblock %}

app/utils/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from app.utils import reload_config, logger
+
+__all__ = ["reload_config", "logger"]

app/utils/env_file.py

@@ -0,0 +1,59 @@
+"""Helpers for updating .env files without dropping unrelated settings."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping
+
+_ENV_KEY_PATTERN = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=")
+
+
+def _serialize_env_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    text = "" if value is None else str(value)
+    if not text:
+        return ""
+
+    if any(char.isspace() for char in text) or any(
+        char in text for char in ["#", '"', "\\", "'"]
+    ):
+        if "'" not in text:
+            return f"'{text}'"
+
+        escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+
+    return text
+
+
+def update_env_file(
+    updates: Mapping[str, object],
+    env_path: str | Path = ".env",
+) -> None:
+    """Update selected keys inside a .env file while preserving other lines."""
+    path = Path(env_path)
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    remaining_updates = {key: _serialize_env_value(value) for key, value in updates.items()}
+
+    for index, line in enumerate(lines):
+        match = _ENV_KEY_PATTERN.match(line)
+        if not match:
+            continue
+
+        key = match.group(1)
+        if key not in remaining_updates:
+            continue
+
+        lines[index] = f"{key}={remaining_updates.pop(key)}"
+
+    if remaining_updates:
+        if lines and lines[-1].strip():
+            lines.append("")
+        for key, value in remaining_updates.items():
+            lines.append(f"{key}={value}")
+
+    content = "\n".join(lines).rstrip()
+    path.write_text(f"{content}\n" if content else "", encoding="utf-8")

app/utils/fe_version.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Utility helpers for resolving the latest X-FE-Version value from chat.z.ai.
+
+The upstream service embeds the current front-end release identifier inside
+its landing page static asset URLs (e.g. `prod-fe-1.0.107`). The helpers in
+this module fetch the landing page, extract the version string, and cache it
+with a configurable TTL so the expensive network fetch only happens when
+necessary.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Optional
+
+import httpx
+
+from app.utils.logger import get_logger
+from app.utils.user_agent import get_random_user_agent
+
+# Base URL to probe for the version string.
+FE_VERSION_SOURCE_URL = "https://chat.z.ai"
+
+# Cache TTL in seconds (default: 30 minutes).
+CACHE_TTL_SECONDS = 1800
+
+_logger = get_logger()
+_version_pattern = re.compile(r"prod-fe-\d+\.\d+\.\d+")
+
+_cached_version: str = ""
+_cached_at: float = 0.0
+
+
+def _extract_version(page_content: str) -> Optional[str]:
+    """Extract the version string from the page content."""
+    if not page_content:
+        return None
+
+    matches = _version_pattern.findall(page_content)
+    if not matches:
+        return None
+
+    # Choose the highest lexical value to guard against mixed versions.
+    return max(matches)
+
+
+
+
+def _should_use_cache(force_refresh: bool) -> bool:
+    """Determine whether the cached value can be reused."""
+    if force_refresh:
+        return False
+    if not _cached_version:
+        return False
+    if _cached_at <= 0:
+        return False
+    return (time.time() - _cached_at) < CACHE_TTL_SECONDS
+
+
+def get_latest_fe_version(force_refresh: bool = False) -> str:
+    """
+    Resolve the latest X-FE-Version value from chat.z.ai.
+
+    The lookup order is:
+        1. Cached value within TTL.
+        2. Remote fetch from chat.z.ai.
+    
+    Raises:
+        Exception: If unable to fetch the version from the remote source.
+    """
+    global _cached_version, _cached_at
+
+    if _should_use_cache(force_refresh):
+        return _cached_version
+
+    try:
+        headers = {"User-Agent": get_random_user_agent("chrome")}
+    except Exception:
+        headers = {
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/120.0.0.0 Safari/537.36"
+            )
+        }
+
+    try:
+        with httpx.Client(timeout=10.0, follow_redirects=True) as client:
+            response = client.get(FE_VERSION_SOURCE_URL, headers=headers)
+            response.raise_for_status()
+            version = _extract_version(response.text)
+            if version:
+                if version != _cached_version:
+                    _logger.info(f"[Z.AI] Detected X-FE-Version update: {version}")
+                _cached_version = version
+                _cached_at = time.time()
+                return version
+
+            _logger.error("[Z.AI] Unable to locate X-FE-Version in landing page")
+            raise Exception("Unable to locate X-FE-Version in landing page")
+    except Exception as exc:
+        _logger.error(f"[Z.AI] Failed to fetch X-FE-Version from {FE_VERSION_SOURCE_URL}: {exc}")
+        raise Exception(f"Failed to fetch X-FE-Version: {exc}")
+
+
+def refresh_fe_version() -> str:
+    """Force refresh the cached version by bypassing the TTL."""
+    return get_latest_fe_version(force_refresh=True)

app/utils/guest_session_pool.py

@@ -0,0 +1,646 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""匿名访客会话池。"""
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Dict, List, Optional, Set
+
+import httpx
+
+from app.core.config import settings
+from app.utils.fe_version import get_latest_fe_version
+from app.utils.logger import logger
+from app.utils.user_agent import get_random_user_agent
+
+AUTH_URL = "https://chat.z.ai/api/v1/auths/"
+CHATS_URL = "https://chat.z.ai/api/v1/chats/"
+AUTH_HTTP_MAX_KEEPALIVE_CONNECTIONS = 20
+AUTH_HTTP_MAX_CONNECTIONS = 50
+GUEST_SESSION_TTL_SECONDS = 480
+GUEST_SESSION_TTL_JITTER_SECONDS = 60
+GUEST_SESSION_MIN_TTL_SECONDS = 180
+GUEST_POOL_MAINTENANCE_INTERVAL_SECONDS = 30
+GUEST_CLEANUP_PARALLELISM = 4
+CAPACITY_FILL_ATTEMPT_MULTIPLIER = 3
+CAPACITY_FILL_MIN_ATTEMPTS = 3
+MAX_DUPLICATE_LOG_USER_IDS = 3
+
+
+def _get_proxy_config() -> Optional[str]:
+    """获取代理配置。"""
+    if settings.HTTPS_PROXY:
+        return settings.HTTPS_PROXY
+    if settings.HTTP_PROXY:
+        return settings.HTTP_PROXY
+    if settings.SOCKS5_PROXY:
+        return settings.SOCKS5_PROXY
+    return None
+
+
+def _build_timeout(read_timeout: float = 30.0) -> httpx.Timeout:
+    """构建访客会话相关请求超时。"""
+    return httpx.Timeout(
+        connect=5.0,
+        read=read_timeout,
+        write=10.0,
+        pool=5.0,
+    )
+
+
+def _build_limits() -> httpx.Limits:
+    """构建访客会话相关连接池限制。"""
+    return httpx.Limits(
+        max_keepalive_connections=AUTH_HTTP_MAX_KEEPALIVE_CONNECTIONS,
+        max_connections=AUTH_HTTP_MAX_CONNECTIONS,
+    )
+
+
+def _build_async_client(read_timeout: float = 30.0) -> httpx.AsyncClient:
+    """构建访客会话相关 HTTP 客户端。"""
+    return httpx.AsyncClient(
+        timeout=_build_timeout(read_timeout),
+        follow_redirects=True,
+        limits=_build_limits(),
+        proxy=_get_proxy_config(),
+    )
+
+
+def _build_dynamic_headers(chat_id: str = "") -> Dict[str, str]:
+    """生成匿名访客鉴权所需浏览器请求头。"""
+    browser_choices = [
+        "chrome",
+        "chrome",
+        "chrome",
+        "edge",
+        "edge",
+        "firefox",
+        "safari",
+    ]
+    browser_type = random.choice(browser_choices)
+    user_agent = get_random_user_agent(browser_type)
+    fe_version = get_latest_fe_version()
+
+    chrome_version = "139"
+    edge_version = "139"
+
+    if "Chrome/" in user_agent:
+        try:
+            chrome_version = user_agent.split("Chrome/")[1].split(".")[0]
+        except Exception:
+            pass
+
+    if "Edg/" in user_agent:
+        try:
+            edge_version = user_agent.split("Edg/")[1].split(".")[0]
+            sec_ch_ua = (
+                f'"Microsoft Edge";v="{edge_version}", '
+                f'"Chromium";v="{chrome_version}", "Not_A Brand";v="24"'
+            )
+        except Exception:
+            sec_ch_ua = (
+                f'"Not_A Brand";v="8", "Chromium";v="{chrome_version}", '
+                f'"Google Chrome";v="{chrome_version}"'
+            )
+    elif "Firefox/" in user_agent:
+        sec_ch_ua = None
+    else:
+        sec_ch_ua = (
+            f'"Not_A Brand";v="8", "Chromium";v="{chrome_version}", '
+            f'"Google Chrome";v="{chrome_version}"'
+        )
+
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        "Connection": "keep-alive",
+        "Cache-Control": "no-cache",
+        "User-Agent": user_agent,
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "X-FE-Version": fe_version,
+        "Origin": "https://chat.z.ai",
+    }
+
+    if sec_ch_ua:
+        headers["sec-ch-ua"] = sec_ch_ua
+        headers["sec-ch-ua-mobile"] = "?0"
+        headers["sec-ch-ua-platform"] = '"Windows"'
+
+    if chat_id:
+        headers["Referer"] = f"https://chat.z.ai/c/{chat_id}"
+    else:
+        headers["Referer"] = "https://chat.z.ai/"
+
+    return headers
+
+
+def _build_session_expiry() -> float:
+    """为新会话分配带抖动的过期时间，避免整池同时失效。"""
+    jitter = random.uniform(
+        -GUEST_SESSION_TTL_JITTER_SECONDS,
+        GUEST_SESSION_TTL_JITTER_SECONDS,
+    )
+    ttl_seconds = max(
+        GUEST_SESSION_MIN_TTL_SECONDS,
+        GUEST_SESSION_TTL_SECONDS + jitter,
+    )
+    return time.time() + ttl_seconds
+
+
+@dataclass
+class GuestSession:
+    """单个匿名访客会话。"""
+
+    token: str
+    user_id: str
+    username: str
+    created_at: float = field(default_factory=time.time)
+    expires_at: float = field(default_factory=_build_session_expiry)
+    active_requests: int = 0
+    valid: bool = True
+    failure_count: int = 0
+    last_failure_time: float = 0.0
+
+    @property
+    def age(self) -> float:
+        """会话存活时间。"""
+        return time.time() - self.created_at
+
+    @property
+    def is_expired(self) -> bool:
+        """判断会话是否��过期。"""
+        return time.time() >= self.expires_at
+
+    def snapshot(self) -> Dict[str, str]:
+        """获取当前会话快照。"""
+        return {
+            "token": self.token,
+            "user_id": self.user_id,
+            "username": self.username,
+        }
+
+
+class GuestSessionPool:
+    """匿名访客会话池，支持最小负载获取与失败替换。"""
+
+    def __init__(self, pool_size: int = 3):
+        self.pool_size = max(1, pool_size)
+        self._lock = Lock()
+        self._sessions: Dict[str, GuestSession] = {}
+        self._maintenance_task: Optional[asyncio.Task] = None
+        self._http_client: Optional[httpx.AsyncClient] = None
+        self._client_lock = asyncio.Lock()
+        self._capacity_lock = asyncio.Lock()
+        self._background_tasks: Set[asyncio.Task] = set()
+        self._cleanup_parallelism = GUEST_CLEANUP_PARALLELISM
+        self._maintenance_interval = GUEST_POOL_MAINTENANCE_INTERVAL_SECONDS
+
+    async def _get_http_client(self) -> httpx.AsyncClient:
+        """获取可复用的 HTTP 客户端，减少频繁建连开销。"""
+        if self._http_client is not None:
+            return self._http_client
+
+        async with self._client_lock:
+            if self._http_client is None:
+                self._http_client = _build_async_client()
+        return self._http_client
+
+    async def _close_http_client(self):
+        """关闭可复用的 HTTP 客户端。"""
+        async with self._client_lock:
+            client = self._http_client
+            self._http_client = None
+
+        if client is not None:
+            await client.aclose()
+
+    def _track_background_task(self, coro) -> asyncio.Task:
+        """跟踪后台任务，避免清理阻塞前台重试路径。"""
+        task = asyncio.create_task(coro)
+        self._background_tasks.add(task)
+
+        def _on_done(done_task: asyncio.Task):
+            self._background_tasks.discard(done_task)
+            try:
+                done_task.result()
+            except asyncio.CancelledError:
+                pass
+            except Exception as exc:
+                logger.warning(f"⚠️ 匿名会话后台任务异常: {exc}")
+
+        task.add_done_callback(_on_done)
+        return task
+
+    async def _wait_background_tasks(self):
+        """等待当前已注册的后台任务结束。"""
+        pending = list(self._background_tasks)
+        if pending:
+            await asyncio.gather(*pending, return_exceptions=True)
+
+    async def _delete_sessions_concurrently(self, sessions: List[GuestSession]):
+        """并发清理多枚匿名会话，加快池维护速度。"""
+        if not sessions:
+            return
+
+        semaphore = asyncio.Semaphore(self._cleanup_parallelism)
+
+        async def _cleanup(session: GuestSession):
+            async with semaphore:
+                await self._delete_all_chats(session)
+
+        await asyncio.gather(*(_cleanup(session) for session in sessions))
+
+    async def _create_session(self) -> GuestSession:
+        """创建一个新的匿名访客会话。"""
+        headers = _build_dynamic_headers()
+
+        # 访客鉴权会写入 cookie，复用同一个 client 会把“新建会话”粘回旧访客身份。
+        async with _build_async_client() as auth_client:
+            response = await auth_client.get(AUTH_URL, headers=headers)
+
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"匿名会话创建失败: HTTP {response.status_code} {response.text[:200]}"
+            )
+
+        data = response.json()
+        token = str(data.get("token") or "").strip()
+        user_id = str(
+            data.get("id") or data.get("user_id") or data.get("uid") or ""
+        ).strip()
+        username = str(
+            data.get("name")
+            or str(data.get("email") or "").split("@")[0]
+            or f"guest-{user_id[:8] or 'session'}"
+        ).strip()
+
+        if not token:
+            raise RuntimeError(f"匿名会话创建失败: 未返回 token {data}")
+        if not user_id:
+            user_id = f"guest-{token[:12]}"
+
+        logger.info(
+            f"🫥 创建匿名会话成功: user_id={user_id}, username={username or 'Guest'}"
+        )
+        return GuestSession(
+            token=token,
+            user_id=user_id,
+            username=username or "Guest",
+        )
+
+    async def _delete_all_chats(self, session: GuestSession) -> bool:
+        """删除匿名会话的全部对话，尽量释放并发占用。"""
+        headers = _build_dynamic_headers()
+        headers.update(
+            {
+                "Authorization": f"Bearer {session.token}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+        try:
+            client = await self._get_http_client()
+            response = await client.delete(CHATS_URL, headers=headers)
+
+            if response.status_code == 200:
+                logger.info(f"🧹 已���理匿名会话聊天记录: {session.user_id}")
+                return True
+
+            logger.warning(
+                f"⚠️ 清理匿名会话聊天记录失败: {session.user_id}, "
+                f"HTTP {response.status_code}, body={response.text[:200]}"
+            )
+        except Exception as exc:
+            logger.warning(f"⚠️ 清理匿名会话聊天记录异常: {session.user_id}, {exc}")
+
+        return False
+
+    def _list_valid_sessions(
+        self,
+        exclude_user_ids: Optional[Set[str]] = None,
+    ) -> List[GuestSession]:
+        """获取有效匿名会话列表。"""
+        excluded = exclude_user_ids or set()
+        with self._lock:
+            return [
+                session
+                for session in self._sessions.values()
+                if self._is_session_usable(session)
+                and session.user_id not in excluded
+            ]
+
+    def _is_session_usable(self, session: GuestSession) -> bool:
+        """判断会话当前是否还能继续分配。"""
+        return session.valid and not session.is_expired
+
+    def _should_retire_session(self, session: GuestSession) -> bool:
+        """判断会话是否应当从池中回收。"""
+        return session.active_requests == 0 and not self._is_session_usable(session)
+
+    def _can_replace_session(self, session: GuestSession) -> bool:
+        """判断当前池内会话是否允许被新的同 user_id 会话替换。"""
+        return self._should_retire_session(session)
+
+    def _store_session(self, session: GuestSession) -> bool:
+        """仅在会话唯一或旧会话已过期时写入会话池。"""
+        with self._lock:
+            existing = self._sessions.get(session.user_id)
+            if existing and not self._can_replace_session(existing):
+                return False
+            self._sessions[session.user_id] = session
+            return True
+
+    def _log_duplicate_sessions(self, action: str, user_ids: List[str]):
+        """记录重复会话，避免补池时静默覆盖。"""
+        if not user_ids:
+            return
+
+        sample = ", ".join(user_ids[:MAX_DUPLICATE_LOG_USER_IDS])
+        logger.warning(
+            f"⚠️ 匿名会话池{action}收到重复会话，已忽略: "
+            f"count={len(user_ids)}, user_ids={sample}"
+        )
+
+    def _register_create_results(self, action: str, results: List[object]) -> int:
+        """写入新创建的会话，并显式忽略重复 user_id。"""
+        created = 0
+        duplicate_user_ids: List[str] = []
+
+        for result in results:
+            if isinstance(result, GuestSession):
+                if self._store_session(result):
+                    created += 1
+                else:
+                    duplicate_user_ids.append(result.user_id)
+                continue
+
+            if isinstance(result, Exception):
+                logger.warning(f"⚠️ 匿名会话池{action}失败: {result}")
+
+        self._log_duplicate_sessions(action, duplicate_user_ids)
+        return created
+
+    def _get_fill_attempt_budget(self, missing_count: int) -> int:
+        """为补池/获取会话计算显式尝试上限，避免重复会话导致死循环。"""
+        scaled_budget = max(1, missing_count) * CAPACITY_FILL_ATTEMPT_MULTIPLIER
+        minimum_budget = max(1, missing_count) + CAPACITY_FILL_MIN_ATTEMPTS
+        return max(scaled_budget, minimum_budget)
+
+    def _pop_retired_sessions(self) -> List[GuestSession]:
+        """移除当前所有可回收的失效会话。"""
+        retired_sessions: List[GuestSession] = []
+
+        with self._lock:
+            for user_id, session in list(self._sessions.items()):
+                if self._should_retire_session(session):
+                    retired_sessions.append(self._sessions.pop(user_id))
+
+        return retired_sessions
+
+    async def _ensure_capacity(self):
+        """补齐匿名会话池容量。"""
+        async with self._capacity_lock:
+            attempts_left = self._get_fill_attempt_budget(
+                self.pool_size - len(self._list_valid_sessions())
+            )
+
+            while attempts_left > 0:
+                need = self.pool_size - len(self._list_valid_sessions())
+                if need <= 0:
+                    return
+
+                batch_size = min(need, attempts_left)
+                results = await asyncio.gather(
+                    *[self._create_session() for _ in range(batch_size)],
+                    return_exceptions=True,
+                )
+                attempts_left -= batch_size
+
+                created = self._register_create_results("补齐", results)
+                if created == 0 and attempts_left == 0:
+                    break
+
+            remaining = self.pool_size - len(self._list_valid_sessions())
+            if remaining > 0:
+                logger.warning(
+                    "⚠️ 匿名会话池补齐未达到目标容量: "
+                    f"missing={remaining}, current={len(self._list_valid_sessions())}"
+                )
+
+    async def _maintenance_loop(self):
+        """后台维护：回收过期/失效会话，并补齐池容量。"""
+        while True:
+            try:
+                await asyncio.sleep(self._maintenance_interval)
+                retired_sessions = self._pop_retired_sessions()
+                await self._delete_sessions_concurrently(retired_sessions)
+
+                await self._ensure_capacity()
+            except asyncio.CancelledError:
+                return
+            except Exception as exc:
+                logger.warning(f"⚠️ 匿名会话池后台维护异常: {exc}")
+
+    async def initialize(self):
+        """初始化匿名会话池。"""
+        if self._maintenance_task:
+            return
+
+        await self._ensure_capacity()
+        created = len(self._list_valid_sessions())
+
+        if created == 0:
+            fallback = await self._create_session()
+            if not self._store_session(fallback):
+                raise RuntimeError(
+                    "匿名会话池初始化失败: 无法写入唯一匿名会话"
+                )
+            created = len(self._list_valid_sessions())
+
+        logger.info(f"✅ 匿名会话池初始化完成: {created} 个会话")
+        self._maintenance_task = asyncio.create_task(self._maintenance_loop())
+
+    async def close(self):
+        """关闭匿名会话池。"""
+        if self._maintenance_task:
+            self._maintenance_task.cancel()
+            try:
+                await self._maintenance_task
+            except asyncio.CancelledError:
+                pass
+            self._maintenance_task = None
+
+        with self._lock:
+            sessions = list(self._sessions.values())
+            self._sessions.clear()
+
+        await self._wait_background_tasks()
+        idle_sessions = [
+            session for session in sessions if session.active_requests == 0
+        ]
+        await self._delete_sessions_concurrently(idle_sessions)
+        await self._close_http_client()
+
+    async def acquire(
+        self,
+        exclude_user_ids: Optional[Set[str]] = None,
+    ) -> GuestSession:
+        """按最小忙碌度获取一个可用匿名会话。"""
+        excluded = exclude_user_ids or set()
+        attempts_left = self._get_fill_attempt_budget(len(excluded) + 1)
+
+        while attempts_left > 0:
+            candidates = self._list_valid_sessions(exclude_user_ids=excluded)
+            if candidates:
+                session = min(
+                    candidates,
+                    key=lambda item: (item.active_requests, item.created_at),
+                )
+                with self._lock:
+                    current = self._sessions.get(session.user_id)
+                    if (
+                        current
+                        and self._is_session_usable(current)
+                        and current.user_id not in excluded
+                    ):
+                        current.active_requests += 1
+                        return current
+
+            new_session = await self._create_session()
+            attempts_left -= 1
+            if new_session.user_id in excluded:
+                logger.warning(
+                    "⚠️ 获取匿名会话时命中排除 user_id，已忽略: "
+                    f"{new_session.user_id}"
+                )
+                continue
+
+            if not self._store_session(new_session):
+                logger.warning(
+                    "⚠️ 获取匿名会话时命中重复 user_id，已重试: "
+                    f"{new_session.user_id}"
+                )
+                continue
+
+            with self._lock:
+                current = self._sessions.get(new_session.user_id)
+                if current and self._is_session_usable(current):
+                    current.active_requests += 1
+                    return current
+
+        raise RuntimeError("匿名会话池获取失败: 未能创建唯一匿名会话")
+
+    def release(self, user_id: str):
+        """释放一个匿名会话占用。"""
+        retired_session: Optional[GuestSession] = None
+
+        with self._lock:
+            session = self._sessions.get(user_id)
+            if session:
+                session.active_requests = max(0, session.active_requests - 1)
+                if self._should_retire_session(session):
+                    retired_session = self._sessions.pop(user_id)
+
+        if retired_session:
+            logger.info(f"🧹 已回收过期匿名会话: {retired_session.user_id}")
+            self._track_background_task(self._delete_all_chats(retired_session))
+            self._track_background_task(self._ensure_capacity())
+
+    async def report_failure(self, user_id: Optional[str] = None):
+        """标记匿名会话失效，并尝试补一个新会话。"""
+        session: Optional[GuestSession] = None
+
+        if user_id:
+            with self._lock:
+                session = self._sessions.pop(user_id, None)
+                if session:
+                    session.valid = False
+                    session.failure_count += 1
+                    session.last_failure_time = time.time()
+                    session.active_requests = 0
+
+        if session:
+            self._track_background_task(self._delete_all_chats(session))
+            logger.warning(f"⚠️ 已淘汰匿名会话: {session.user_id}")
+
+        await self._ensure_capacity()
+
+    async def refresh_auth(self, failed_user_id: Optional[str] = None):
+        """兼容 glm-demo 命名：刷新匿名会话。"""
+        await self.report_failure(failed_user_id)
+
+    async def cleanup_idle_chats(self):
+        """清理当前空闲匿名会话的聊天记录。"""
+        with self._lock:
+            idle_sessions = [
+                session
+                for session in self._sessions.values()
+                if self._is_session_usable(session) and session.active_requests == 0
+            ]
+
+        await self._delete_sessions_concurrently(idle_sessions)
+
+    def get_pool_status(self) -> Dict[str, int]:
+        """获取匿名会话池状态。"""
+        with self._lock:
+            sessions = list(self._sessions.values())
+
+        valid_sessions = [
+            session for session in sessions if self._is_session_usable(session)
+        ]
+        busy_sessions = [
+            session for session in valid_sessions if session.active_requests > 0
+        ]
+
+        return {
+            "total_sessions": len(sessions),
+            "valid_sessions": len(valid_sessions),
+            "available_sessions": len(
+                [session for session in valid_sessions if session.active_requests == 0]
+            ),
+            "busy_sessions": len(busy_sessions),
+            "expired_sessions": len(
+                [session for session in sessions if session.is_expired]
+            ),
+        }
+
+
+_guest_session_pool: Optional[GuestSessionPool] = None
+_guest_pool_lock = Lock()
+
+
+def get_guest_session_pool() -> Optional[GuestSessionPool]:
+    """获取全局匿名会话池。"""
+    return _guest_session_pool
+
+
+async def initialize_guest_session_pool(
+    pool_size: int = 3,
+) -> GuestSessionPool:
+    """初始化全局匿名会话池。"""
+    global _guest_session_pool
+
+    with _guest_pool_lock:
+        if _guest_session_pool is None:
+            _guest_session_pool = GuestSessionPool(pool_size=pool_size)
+        pool = _guest_session_pool
+
+    await pool.initialize()
+    return pool
+
+
+async def close_guest_session_pool():
+    """关闭全局匿名会话池。"""
+    global _guest_session_pool
+
+    with _guest_pool_lock:
+        pool = _guest_session_pool
+        _guest_session_pool = None
+
+    if pool:
+        await pool.close()

app/utils/logger.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import sys
+from pathlib import Path
+from loguru import logger
+
+# Global logger instance
+app_logger = None
+
+
+def setup_logger(log_dir, log_retention_days=7, log_rotation="1 day", debug_mode=False):
+    """
+    Create a logger instance
+
+    Parameters:
+        log_dir (str): 日志目录
+        log_retention_days (int): 日志保留天数
+        log_rotation (str): 日志轮转间隔
+        debug_mode (bool): 是否开启调试模式
+    """
+    global app_logger
+
+    # 移除所有现有的日志处理器（支持热重载）
+    logger.remove()
+
+    log_level = "DEBUG" if debug_mode else "INFO"
+
+    console_format = (
+        "<green>{time:HH:mm:ss}</green> | <level>{level: <8}</level> | <level>{message}</level>"
+        if not debug_mode
+        else "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | "
+        "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | <level>{message}</level>"
+    )
+
+    # 添加控制台输出（根据 debug_mode 设置级别）
+    logger.add(sys.stderr, level=log_level, format=console_format, colorize=True)
+
+    # 只有在 debug_mode 时才添加文件输出
+    if debug_mode:
+        try:
+            log_path = Path(log_dir)
+            log_path.mkdir(parents=True, exist_ok=True)
+
+            log_file = log_path / "{time:YYYY-MM-DD}.log"
+            file_format = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level: <8} | {name}:{function}:{line} | {message}"
+
+            logger.add(
+                str(log_file),
+                level=log_level,
+                format=file_format,
+                rotation=log_rotation,
+                retention=f"{log_retention_days} days",
+                encoding="utf-8",
+                compression="zip",
+                enqueue=True,
+                catch=True,
+            )
+        except (PermissionError, OSError) as e:
+            # 如果无法创建日志目录或文件，降级为仅控制台输出
+            logger.warning(f"⚠️ 无法创建日志文件 ({e})，将仅使用控制台输出")
+
+    app_logger = logger
+
+    return logger
+
+
+def get_logger():
+    """Get the logger instance"""
+    global app_logger
+    if app_logger is None:
+        # 如果没有设置过logger，使用默认配置
+        logger.remove()  # 移除所有现有处理器
+        logger.add(sys.stderr, level="INFO", format="<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | <level>{message}</level>")
+        app_logger = logger
+    return app_logger
+
+
+if __name__ == "__main__":
+    """Test the logger"""
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        try:
+            setup_logger(temp_dir, debug_mode=True)
+
+            logger.debug("这是一条调试日志")
+            logger.info("这是一条信息日志")
+            logger.warning("这是一条警告日志")
+            logger.error("这是一条错误日志")
+            logger.critical("这是一条严重日志")
+
+            try:
+                1 / 0
+            except ZeroDivisionError:
+                logger.exception("发生了除零异常")
+
+            print("✅ 日志测试完成")
+
+            logger.remove()
+
+        except Exception as e:
+            print(f"❌ 日志测试失败: {e}")
+            logger.remove()
+            raise

app/utils/reload_config.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+热重载配置模块
+定义 Granian 服务器热重载时需要忽略的目录和文件模式
+"""
+
+# 忽略的目录列表
+RELOAD_IGNORE_DIRS = [
+    "logs",  # 忽略日志目录
+    "storage",  # 忽略存储目录
+    "__pycache__",  # 忽略 Python 缓存
+    ".git",  # 忽略 git 目录
+    ".github",  # 忽略 GitHub 相关目录
+    ".vscode",  # 忽略 VSCode 配置目录
+    "deploy",  # 忽略部署相关目录
+    ".idea",  # 忽略 IntelliJ IDEA 配置目录
+    "node_modules",  # 忽略 node_modules
+    "migrations",  # 忽略数据库迁移目录
+    ".pytest_cache",  # 忽略 pytest 缓存
+    ".venv",  # 忽略虚拟环境
+    "venv",  # 忽略虚拟环境
+    "env",  # 忽略环境目录
+    ".mypy_cache",  # 忽略 mypy 缓存
+    ".ruff_cache",  # 忽略 ruff 缓存
+    "dist",  # 忽略构建分发目录
+    "build",  # 忽略构建目录
+    ".coverage",  # 忽略测试覆盖率文件
+    "htmlcov",  # 忽略覆盖率报告目录
+    "tests",  # 忽略测试目录
+    "z-ai2api-server.pid",  # 忽略 PID 文件
+    "app\\templates" # 忽略模板目录
+]
+
+# 忽略的文件模式（正则表达式）
+RELOAD_IGNORE_PATTERNS = [
+    # 日志文件
+    r".*\.log$",
+    r".*\.log\.\d+$",
+    # 数据库文件
+    r".*\.sqlite3.*",
+    r".*\.db$",
+    r".*\.db-.*$",
+    # Python 相关
+    r".*\.pyc$",
+    r".*\.pyo$",
+    r".*\.pyd$",
+    # 临时文件
+    r".*\.tmp$",
+    r".*\.temp$",
+    r".*\.swp$",
+    r".*\.swo$",
+    r".*~$",
+    # 系统文件
+    r".*\.DS_Store$",
+    r".*Thumbs\.db$",
+    r".*\.directory$",
+    # 编辑器文件
+    r".*\.vscode.*",
+    r".*\.idea.*",
+    # 测试和覆盖率
+    r".*\.coverage$",
+    r".*\.pytest_cache.*",
+    # 构建文件
+    r".*\.egg-info.*",
+    r".*\.wheel$",
+    r".*\.whl$",
+    # 版本控制
+    r".*\.git.*",
+    r".*\.gitignore$",
+    r".*\.gitkeep$",
+    # 配置文件备份
+    r".*\.bak$",
+    r".*\.backup$",
+    r".*\.orig$",
+    # 锁文件
+    r".*\.lock$",
+    r".*\.pid$",
+]
+
+# 监视的路径（只监视应用相关代码）
+RELOAD_WATCH_PATHS = [
+    "app",  # 应用主目录
+    "main.py",  # 主入口文件
+]
+
+# 热重载配置
+RELOAD_CONFIG = {
+    "reload_ignore_dirs": RELOAD_IGNORE_DIRS,
+    "reload_ignore_patterns": RELOAD_IGNORE_PATTERNS,
+    "reload_paths": RELOAD_WATCH_PATHS,
+    "reload_tick": 500,  # 监视频率（毫秒）
+}

app/utils/request_logging.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""请求日志写库与流式日志包装。"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, AsyncGenerator, Dict, Optional
+
+from app.services.request_log_dao import get_request_log_dao
+from app.utils.logger import get_logger
+from app.utils.request_source import RequestSourceInfo
+
+logger = get_logger()
+
+
+def _coerce_int(value: Any) -> int:
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _merge_usage(
+    current: Dict[str, int],
+    update: Dict[str, int],
+    *,
+    include_cache_in_total: bool,
+) -> Dict[str, int]:
+    merged = dict(current)
+
+    for key in (
+        "input_tokens",
+        "output_tokens",
+        "cache_creation_tokens",
+        "cache_read_tokens",
+    ):
+        value = _coerce_int(update.get(key))
+        if value > 0:
+            merged[key] = value
+
+    total_tokens = _coerce_int(update.get("total_tokens"))
+    if total_tokens > 0:
+        merged["total_tokens"] = total_tokens
+        return merged
+
+    merged["total_tokens"] = (
+        merged["input_tokens"] + merged["output_tokens"]
+    )
+    if include_cache_in_total:
+        merged["total_tokens"] += (
+            merged["cache_creation_tokens"] + merged["cache_read_tokens"]
+        )
+
+    return merged
+
+
+def extract_openai_usage(response: Dict[str, Any]) -> Dict[str, int]:
+    """Extract usage from an OpenAI-compatible response payload."""
+    usage = response.get("usage") or {}
+    prompt_details = usage.get("prompt_tokens_details") or {}
+    input_details = usage.get("input_token_details") or {}
+
+    input_tokens = _coerce_int(
+        usage.get("prompt_tokens") or usage.get("input_tokens")
+    )
+    output_tokens = _coerce_int(
+        usage.get("completion_tokens") or usage.get("output_tokens")
+    )
+    cache_creation_tokens = _coerce_int(
+        usage.get("cache_creation_input_tokens")
+        or prompt_details.get("cache_creation_tokens")
+        or input_details.get("cache_creation_input_tokens")
+        or input_details.get("cache_creation_tokens")
+    )
+    cache_read_tokens = _coerce_int(
+        usage.get("cache_read_input_tokens")
+        or prompt_details.get("cached_tokens")
+        or prompt_details.get("cache_read_tokens")
+        or input_details.get("cached_tokens")
+        or input_details.get("cache_read_input_tokens")
+        or input_details.get("cache_read_tokens")
+    )
+    total_tokens = _coerce_int(usage.get("total_tokens"))
+    if total_tokens <= 0:
+        total_tokens = input_tokens + output_tokens
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cache_creation_tokens": cache_creation_tokens,
+        "cache_read_tokens": cache_read_tokens,
+        "total_tokens": total_tokens,
+    }
+
+
+def extract_claude_usage(response: Dict[str, Any]) -> Dict[str, int]:
+    """Extract usage from a Claude-compatible response payload."""
+    usage = response.get("usage") or {}
+    input_tokens = _coerce_int(
+        usage.get("input_tokens") or usage.get("prompt_tokens")
+    )
+    output_tokens = _coerce_int(
+        usage.get("output_tokens") or usage.get("completion_tokens")
+    )
+    cache_creation_tokens = _coerce_int(
+        usage.get("cache_creation_input_tokens")
+        or usage.get("cache_creation_tokens")
+    )
+    cache_read_tokens = _coerce_int(
+        usage.get("cache_read_input_tokens")
+        or usage.get("cached_tokens")
+        or usage.get("cache_read_tokens")
+    )
+    total_tokens = _coerce_int(usage.get("total_tokens"))
+    if total_tokens <= 0:
+        total_tokens = (
+            input_tokens
+            + output_tokens
+            + cache_creation_tokens
+            + cache_read_tokens
+        )
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cache_creation_tokens": cache_creation_tokens,
+        "cache_read_tokens": cache_read_tokens,
+        "total_tokens": total_tokens,
+    }
+
+
+async def write_request_log(
+    *,
+    provider: str,
+    model: str,
+    source_info: RequestSourceInfo,
+    success: bool,
+    started_at: float,
+    status_code: int = 200,
+    first_token_time: float = 0.0,
+    input_tokens: int = 0,
+    output_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+    cache_read_tokens: int = 0,
+    total_tokens: Optional[int] = None,
+    error_message: Optional[str] = None,
+) -> None:
+    """Persist a request log entry without breaking request handling."""
+    duration = max(0.0, time.perf_counter() - started_at)
+    try:
+        dao = get_request_log_dao()
+        await dao.add_log(
+            provider=provider,
+            endpoint=source_info.endpoint,
+            source=source_info.source,
+            protocol=source_info.protocol,
+            client_name=source_info.client_name,
+            model=model,
+            status_code=status_code,
+            success=success,
+            duration=duration,
+            first_token_time=first_token_time,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cache_read_tokens=cache_read_tokens,
+            total_tokens=total_tokens,
+            error_message=error_message,
+        )
+    except Exception as exc:
+        logger.error(f"写入请求日志失败: {exc}")
+
+
+def _openai_payload_has_output(payload: Dict[str, Any]) -> bool:
+    choice = ((payload.get("choices") or [{}])[0]) if isinstance(payload, dict) else {}
+    delta = choice.get("delta") or {}
+    return bool(
+        delta.get("content")
+        or delta.get("reasoning_content")
+        or delta.get("tool_calls")
+    )
+
+
+async def wrap_openai_stream_with_logging(
+    stream: AsyncGenerator[str, None],
+    *,
+    provider: str,
+    model: str,
+    source_info: RequestSourceInfo,
+    started_at: float,
+) -> AsyncGenerator[str, None]:
+    """Wrap OpenAI SSE stream and persist completion metadata."""
+    success = True
+    status_code = 200
+    error_message: Optional[str] = None
+    first_token_time = 0.0
+    usage = {
+        "input_tokens": 0,
+        "output_tokens": 0,
+        "cache_creation_tokens": 0,
+        "cache_read_tokens": 0,
+        "total_tokens": 0,
+    }
+
+    try:
+        async for chunk in stream:
+            if chunk.startswith("data: "):
+                payload_text = chunk[6:].strip()
+                if payload_text and payload_text != "[DONE]":
+                    try:
+                        payload = json.loads(payload_text)
+                    except json.JSONDecodeError:
+                        payload = None
+
+                    if isinstance(payload, dict):
+                        if "error" in payload:
+                            success = False
+                            error = payload.get("error") or {}
+                            error_message = (
+                                error.get("message")
+                                or "Unknown stream error"
+                            )
+                            status_code = int(error.get("code") or 500)
+                        else:
+                            if (
+                                not first_token_time
+                                and _openai_payload_has_output(payload)
+                            ):
+                                first_token_time = max(
+                                    0.0,
+                                    time.perf_counter() - started_at,
+                                )
+                            if payload.get("usage"):
+                                usage = _merge_usage(
+                                    usage,
+                                    extract_openai_usage(payload),
+                                    include_cache_in_total=False,
+                                )
+
+            yield chunk
+    except Exception as exc:
+        success = False
+        status_code = 500
+        error_message = str(exc)
+        raise
+    finally:
+        await write_request_log(
+            provider=provider,
+            model=model,
+            source_info=source_info,
+            success=success,
+            started_at=started_at,
+            status_code=status_code,
+            first_token_time=first_token_time,
+            input_tokens=usage["input_tokens"],
+            output_tokens=usage["output_tokens"],
+            cache_creation_tokens=usage["cache_creation_tokens"],
+            cache_read_tokens=usage["cache_read_tokens"],
+            total_tokens=usage["total_tokens"],
+            error_message=error_message,
+        )
+
+
+async def wrap_claude_stream_with_logging(
+    stream: AsyncGenerator[str, None],
+    *,
+    provider: str,
+    model: str,
+    source_info: RequestSourceInfo,
+    started_at: float,
+    input_tokens: int,
+) -> AsyncGenerator[str, None]:
+    """Wrap Claude SSE stream and persist completion metadata."""
+    success = True
+    status_code = 200
+    error_message: Optional[str] = None
+    first_token_time = 0.0
+    usage = {
+        "input_tokens": input_tokens,
+        "output_tokens": 0,
+        "cache_creation_tokens": 0,
+        "cache_read_tokens": 0,
+        "total_tokens": input_tokens,
+    }
+    current_event: Optional[str] = None
+
+    try:
+        async for chunk in stream:
+            if chunk.startswith("event: "):
+                current_event = chunk[7:].strip()
+            elif chunk.startswith("data: "):
+                payload_text = chunk[6:].strip()
+                try:
+                    payload = json.loads(payload_text)
+                except json.JSONDecodeError:
+                    payload = None
+
+                if isinstance(payload, dict):
+                    if current_event == "content_block_delta" and not first_token_time:
+                        first_token_time = max(0.0, time.perf_counter() - started_at)
+                    if payload.get("usage"):
+                        usage = _merge_usage(
+                            usage,
+                            extract_claude_usage(payload),
+                            include_cache_in_total=True,
+                        )
+                    elif current_event == "error":
+                        success = False
+                        status_code = 500
+                        error = payload.get("error") or {}
+                        error_message = error.get("message") or "Claude stream error"
+
+            yield chunk
+    except Exception as exc:
+        success = False
+        status_code = 500
+        error_message = str(exc)
+        raise
+    finally:
+        await write_request_log(
+            provider=provider,
+            model=model,
+            source_info=source_info,
+            success=success,
+            started_at=started_at,
+            status_code=status_code,
+            first_token_time=first_token_time,
+            input_tokens=usage["input_tokens"],
+            output_tokens=usage["output_tokens"],
+            cache_creation_tokens=usage["cache_creation_tokens"],
+            cache_read_tokens=usage["cache_read_tokens"],
+            total_tokens=usage["total_tokens"],
+            error_message=error_message,
+        )

app/utils/request_source.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""请求来源识别辅助函数。"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from fastapi import Request
+
+
+ANTHROPIC_MODEL_PREFIXES = (
+    "claude-",
+    "claude.",
+)
+ANTHROPIC_MODEL_ALIASES = {
+    "sonnet",
+    "opus",
+    "haiku",
+    "opusplan",
+}
+
+
+@dataclass(frozen=True)
+class RequestSourceInfo:
+    """Normalized request-source metadata for logging."""
+
+    source: str
+    protocol: str
+    client_name: str
+    endpoint: str
+    user_agent: str
+
+
+def _normalize_source_name(value: str) -> str:
+    normalized = re.sub(r"[^a-zA-Z0-9._-]+", "_", value.strip().lower())
+    return normalized.strip("_") or "unknown"
+
+
+def _looks_like_anthropic_model(model_hint: Optional[str]) -> bool:
+    if not isinstance(model_hint, str):
+        return False
+
+    normalized = model_hint.strip().casefold()
+    if normalized in ANTHROPIC_MODEL_ALIASES:
+        return True
+
+    return normalized.startswith(ANTHROPIC_MODEL_PREFIXES)
+
+
+def detect_request_source(
+    request: Request,
+    protocol_hint: Optional[str] = None,
+    model_hint: Optional[str] = None,
+) -> RequestSourceInfo:
+    """Detect the request source from headers, path, and model hints."""
+    headers = request.headers
+    endpoint = request.url.path
+    user_agent = (headers.get("user-agent") or "").strip()
+    user_agent_normalized = user_agent.casefold()
+
+    protocol = (protocol_hint or "").strip().lower()
+    if not protocol:
+        if headers.get("anthropic-version") or "/messages" in endpoint:
+            protocol = "anthropic"
+        elif "/chat/completions" in endpoint:
+            protocol = "openai"
+        else:
+            protocol = "unknown"
+
+    explicit_source = headers.get("x-request-source") or headers.get("x-client-source")
+    if explicit_source:
+        source = _normalize_source_name(explicit_source)
+        return RequestSourceInfo(
+            source=source,
+            protocol=protocol,
+            client_name=explicit_source.strip(),
+            endpoint=endpoint,
+            user_agent=user_agent,
+        )
+
+    if any(token in user_agent_normalized for token in ("claude-code", "claude code", "claude-cli", "claude/")):
+        source = "claude_code"
+        client_name = "Claude Code"
+    elif "anthropic" in user_agent_normalized:
+        source = "anthropic_sdk"
+        client_name = "Anthropic SDK"
+    elif "openai" in user_agent_normalized:
+        source = "openai_sdk"
+        client_name = "OpenAI SDK"
+    elif "curl/" in user_agent_normalized:
+        source = "curl"
+        client_name = "curl"
+    elif any(token in user_agent_normalized for token in ("python-httpx", "httpx/", "python-requests", "requests/")):
+        source = "custom_http_client"
+        client_name = "HTTP Client"
+    elif "mozilla/" in user_agent_normalized:
+        source = "browser"
+        client_name = "Browser"
+    elif protocol == "anthropic":
+        source = "claude_family" if _looks_like_anthropic_model(model_hint) else "anthropic_compatible"
+        client_name = "Claude/Anthropic Compatible"
+    elif protocol == "openai":
+        source = "openai_compatible"
+        client_name = "OpenAI Compatible"
+    else:
+        source = "unknown"
+        client_name = "Unknown"
+
+    return RequestSourceInfo(
+        source=source,
+        protocol=protocol,
+        client_name=client_name,
+        endpoint=endpoint,
+        user_agent=user_agent,
+    )
+
+
+def format_request_source(info: RequestSourceInfo) -> str:
+    """Render request-source metadata into a compact log prefix."""
+    return (
+        f"[source={info.source}]"
+        f"[protocol={info.protocol}]"
+        f"[client={info.client_name}]"
+        f"[endpoint={info.endpoint}]"
+    )

app/utils/signature.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Z.AI 签名工具模块
+"""
+
+import hmac
+import hashlib
+import base64
+from typing import Dict
+
+
+def generate_signature(e: str, t: str, s: int) -> dict:
+    """Generate signature matching JavaScript zs function.
+
+    Args:
+        e: canonical metadata string, e.g. "requestId,<uuid>,timestamp,<ms>,user_id,<id>"
+        t: latest user message text that feeds into the signature prompt (may be empty)
+        s: timestamp in milliseconds
+    
+    Returns:
+        Dictionary with signature and timestamp
+    """
+    # r = Number(s) - convert to number (already a number in Python)
+    r = s
+    # i = s - timestamp as string
+    i = str(s)
+    
+    # n = new TextEncoder
+    # a = n.encode(t)
+    a = t.encode('utf-8')
+    
+    # w = btoa(String.fromCharCode(...a))
+    # This is equivalent to base64 encoding the UTF-8 bytes
+    w = base64.b64encode(a).decode('ascii')
+    
+    # c = `${e}|${w}|${i}`
+    c = f"{e}|{w}|{i}"
+    
+    # E = Math.floor(r / (5 * 60 * 1e3))
+    E = r // (5 * 60 * 1000)
+    
+    # A = CryptoJS.HmacSHA256(`${E}`, "key-@@@@)))()((9))-xxxx&&&%%%%%")
+    secret = "key-@@@@)))()((9))-xxxx&&&%%%%%"
+    A = hmac.new(secret.encode('utf-8'), str(E).encode('utf-8'), hashlib.sha256).hexdigest()
+    
+    # k = CryptoJS.HmacSHA256(c, A).toString()
+    k = hmac.new(A.encode('utf-8'), c.encode('utf-8'), hashlib.sha256).hexdigest()
+    
+    # return n.encode(c), { signature: k, timestamp: i }
+    # Note: n.encode(c) is not used in the return value, so we ignore it
+    return {
+        "signature": k,
+        "timestamp": i
+    }