llm-simple-router 0.3.6 → 0.4.0

package/README.md

@@ -9,23 +9,18 @@
 
 个人使用 Claude Code 配合国产模型时的实际痛点：
 
-- **自动重试** — 国产模型限流、网络错误频繁，对可恢复错误（429/500/网络超时）自动指数退避重试
-- **多供应商模型映射** — 高峰期主模型不可用时，将 claude-opus 映射到 GLM，claude-sonnet 映射到 Kimi 等，低谷期再切回来
-- **多密钥隔离** — 为不同使用方分配独立密钥，按密钥筛选日志和性能指标
+- **自动重试** — 国产模型限流、网络错误频繁，对可恢复错误（429/400/网络超时）自动指数退避重试。默认已经针对智谱模型进行了配置，开箱即用。
+- **多供应商支持** — 支持智谱、Moonshot、Minimax、火山引擎、阿里云、腾讯云等，Coding Plan 选择后会自动填写，只需要配置 API Key。也可以完全自定义。
+- **模型分时段映射** — 可以每天分时段自动切换模型。以我自己使用体验来说，平时将 sonnet 映射到 glm-5.1 ，14-18点将 sonnet 映射到 kimi ，减少智谱高峰期限流错误和三倍消耗。
+- **并发队列等待** — 不同 Provider 可以配置并发数限制，超过限制的请求会进入队列等待。解决 Claude Code 多个subagent并行执行时经常触发限流失败的问题。不过需要配置 claude code 的 API_TIMEOUT_MS 为一个比较大的值。这个功能可以让使用 Claude Code 体验更好，但不能根本性解决限流问题。
+- **实时请求监控** — 实时监控活跃请求、队列情况，可以实时查看流式请求的输出并结构化展示（目前仅支持 Claude Code ）。
 
-## 功能
+## 其他功能
 
 | 功能 | 说明 |
 |------|------|
-| 模型映射 | 客户端模型名 -> 后端模型名 + 供应商，支持分组和优先级 |
-| 自动重试 | 429/500/网络错误自动重试，指数退避，可配置次数和间隔 |
-| 多供应商 | 配置多个后端供应商，按模型映射路由 |
-| 多密钥 (Router Keys) | 为不同使用方创建独立密钥，支持模型白名单 |
-| 流式代理 | 完整支持 SSE 流式和非流式请求 |
-| 供应商并发控制 | 按 Provider 维度限制并发数、队列长度和超时，防止单一供应商过载 |
-| 实时监控 | SSE 推送活跃请求、延迟热力图、Token 吞吐、运行时资源指标 |
-| 代理增强 (实验性) | 注入系统指令、会话记忆、模型锁定等增强功能 |
-| 管理后台 | Vue 3 + shadcn-vue Web UI，管理供应商、映射、密钥 |
+| 多密钥 | 为不同使用方创建独立密钥，支持模型白名单 |
+| 代理增强 (实验性) | 支持通过 Claude Code 发送select-model指令直接变更 router 的模型，不经过 LLM 请求（实验中，可能有bug） |
 | 请求日志 | 结构化展示完整四阶段链路（客户端请求/上游请求/上游响应/客户端响应），适配 Claude Code 请求格式 |
 | 性能指标 | TTFT、吞吐量、Token 用量、缓存命中率，支持按模型/密钥筛选 |
 
@@ -33,39 +28,89 @@
 
 ## 管理后台预览
 
-| Dashboard | Provider 管理 |
-|-----------|-------------|
-| ![Dashboard](docs/screenshot/dashboard.png) | ![Provider](docs/screenshot/provider.png) |
+| Provider 管理和并发控制 |
+|-----------|
+| ![Provider Concurrency](docs/screenshot/provider_concurrency.png) |
 
-| 供应商并发控制 | 实时监控 |
+| 实时监控 |
+|-----------------|
+| ![Monitor](docs/screenshot/monitor.png) |
+
+| 模型映射 |
+|---------|
+| ![Model Mapping](docs/screenshot/model_mapping.png) |
+
+| 重试规则 |
+|---------|
+| ![Retry](docs/screenshot/retry.png) |
+
+| Dashboard | 请求日志 |
 |--------------|---------|
-| ![Provider Concurrency](docs/screenshot/provider_concurrency.png) | ![Monitor](docs/screenshot/monitor.png) |
+| ![Dashboard](docs/screenshot/dashboard.png) | ![Logs](docs/screenshot/log.png) |
 
 | 代理增强 (实验性) |
 |-----------------|
 | ![Proxy Enhancement](docs/screenshot/proxy_enhance.png) |
 
-| 模型映射 | 重试规则 |
-|---------|--------|
-| ![Model Mapping](docs/screenshot/model_mapping.png) | ![Retry](docs/screenshot/retry.png) |
-
-| 请求日志 |
-|---------|
-| ![Logs](docs/screenshot/log.png) |
-
 ## 工作原理
 
 ```
-Claude Code -> Router (模型映射 + 自动重试) -> 智谱 GLM / Kimi / 其他供应商
+Claude Code -> Router (模型映射 + 自动重试 + 并发控制) -> 智谱 GLM / Kimi / 其他供应商
 ```
 
 Router 根据模型映射找到后端供应商 -> 转发请求 -> 自动重试失败请求 -> 记录日志和性能指标 -> 返回响应。
 
-## 典型使用场景
+### 架构图
+
+**系统上下文**（[详细说明](docs/system-context.md)）：
+
+```mermaid
+graph LR
+    Clients["Claude Code / Cursor / 其他客户端"]
+    Admin["管理员"]
+    Router>"LLM Simple Router"]
+    Providers>"智谱 / Moonshot / OpenAI / Anthropic / ..."]
+
+    Clients -->|"API 请求<br/>Bearer Token"| Router
+    Admin -->|"管理后台<br/>/admin/"| Router
+    Router -->|"转发请求<br/>SSE 流式"| Providers
+```
 
-### Claude Code 配置
+**请求处理流水线**（[详细说明](docs/request-pipeline.md)）：
 
-通过环境变量将 Claude Code 指向 Router：
+```mermaid
+flowchart LR
+    A[客户端请求] --> B[认证]
+    B --> C[模型映射<br/>+ 路由策略]
+    C --> D[并发排队]
+    D --> E[调用上游<br/>失败自动重试]
+    E --> F[记录日志<br/>+ 指标]
+    F --> G[返回响应]
+
+    E -.->|失败| C
+```
+Router 收到请求后：认证 → 按映射规则找到后端 Provider → 排队控制并发 → 转发到上游（失败自动重试，Failover 策略下会切换 Provider）→ 记录日志和指标 → 返回响应。
+
+## 快速开始
+
+### npx 启动
+```bash
+# 一行命令启动
+npx llm-simple-router
+# 访问 http://localhost:9981/admin
+# 首次访问会进入 Setup 页面设置管理员密码
+```
+
+无需任何环境变量。数据默认存储在 `~/.llm-simple-router/`。
+
+### Docker 部署
+
+```bash
+docker compose up -d
+```
+### 创建 Router API 密钥
+
+在管理后台创建一个 API 密钥，原先 Claude Code 密钥替换为 Router 密钥。
 
 **方式一：shell alias（推荐）**
 
@@ -85,7 +130,9 @@ alias clodedev='ANTHROPIC_AUTH_TOKEN="<your-router-key>" ANTHROPIC_BASE_URL="htt
 }
 ```
 
-将 `<your-router-key>` 替换为管理后台中创建的 Router Key。
+### 管理后台配置 Provider
+
+Provider 支持快速配置，目前支持智谱、Moonshot、Minimax、火山引擎、阿里云、腾讯云等，Coding Plan 选择后会自动填写，只需要配置 API Key。
 
 ### 管理后台配置模型映射
 
@@ -96,24 +143,9 @@ alias clodedev='ANTHROPIC_AUTH_TOKEN="<your-router-key>" ANTHROPIC_BASE_URL="htt
 | sonnet | kimi-for-coding | Moonshot | 14:00-18:00 |
 | sonnet | glm-5-turbo | 智谱 | / |
 
-高峰期 GLM 3倍用量，且频繁超限时，将 sonnet 切到 Kimi；低谷期切回 GLM。
-
-## 快速开始
-
-```bash
-# 一行命令启动
-npx llm-simple-router
-# 访问 http://localhost:9981/admin
-# 首次访问会进入 Setup 页面设置管理员密码
-```
-
-无需任何环境变量。数据默认存储在 `~/.llm-simple-router/`。
-
-## Docker 部署
-
-```bash
-docker compose up -d
-```
+客户端模型是指 Claude Code 实际请求发出的模型名。
+如果你配置了 ANTHROPIC_MODEL 等变量，那应该以该变量为准。
+个人的配置：高峰期 GLM 3倍用量，且频繁超限时，将 sonnet 切到 Kimi；低谷期切回 GLM。
 
 ## 环境变量
 

package/dist/admin/constants.d.ts

@@ -1,10 +1,3 @@
 import type { FastifyReply } from "fastify";
-export declare const HTTP_BAD_REQUEST = 400;
-export declare const HTTP_CREATED = 201;
-export declare const HTTP_FORBIDDEN = 403;
-export declare const HTTP_NOT_FOUND = 404;
-export declare const HTTP_CONFLICT = 409;
-export declare const HTTP_INTERNAL_ERROR = 500;
-export declare const HTTP_BAD_GATEWAY = 502;
-export declare const HTTP_SERVICE_UNAVAILABLE = 503;
+export { HTTP_BAD_REQUEST, HTTP_CREATED, HTTP_FORBIDDEN, HTTP_NOT_FOUND, HTTP_CONFLICT, HTTP_INTERNAL_ERROR, HTTP_BAD_GATEWAY, HTTP_SERVICE_UNAVAILABLE, } from "../constants.js";
 export declare function sendErrorResponse(reply: FastifyReply, statusCode: number, message: string): FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;

package/dist/admin/constants.js

@@ -1,11 +1,5 @@
-export const HTTP_BAD_REQUEST = 400;
-export const HTTP_CREATED = 201;
-export const HTTP_FORBIDDEN = 403;
-export const HTTP_NOT_FOUND = 404;
-export const HTTP_CONFLICT = 409;
-export const HTTP_INTERNAL_ERROR = 500;
-export const HTTP_BAD_GATEWAY = 502;
-export const HTTP_SERVICE_UNAVAILABLE = 503;
+// HTTP 状态码统一从 src/constants.ts 导入，避免重复定义
+export { HTTP_BAD_REQUEST, HTTP_CREATED, HTTP_FORBIDDEN, HTTP_NOT_FOUND, HTTP_CONFLICT, HTTP_INTERNAL_ERROR, HTTP_BAD_GATEWAY, HTTP_SERVICE_UNAVAILABLE, } from "../constants.js";
 export function sendErrorResponse(reply, statusCode, message) {
     return reply.code(statusCode).send({ error: { message } });
 }

package/dist/admin/logs.js

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import { getRequestLogs, getRequestLogById, deleteLogsBefore } from "../db/index.js";
+import { getRequestLogs, getRequestLogsGrouped, getRequestLogById, getRequestLogChildren, deleteLogsBefore } from "../db/index.js";
 import { HTTP_NOT_FOUND } from "./constants.js";
 const LogQuerySchema = Type.Object({
     page: Type.Optional(Type.String()),
@@ -7,23 +7,29 @@ const LogQuerySchema = Type.Object({
     api_type: Type.Optional(Type.String()),
     model: Type.Optional(Type.String()),
     router_key_id: Type.Optional(Type.String()),
+    view: Type.Optional(Type.Literal("grouped")),
 });
 const DeleteLogsBeforeSchema = Type.Object({
     before: Type.String({ minLength: 1 }),
 });
+const DEFAULT_LOG_VIEW = "flat";
 export const adminLogRoutes = (app, options, done) => {
     const { db } = options;
     app.get("/admin/api/logs", { schema: { querystring: LogQuerySchema } }, async (request, reply) => {
         const query = request.query;
         const page = parseInt(query.page || "1", 10);
         const limit = parseInt(query.limit || "20", 10);
-        const result = getRequestLogs(db, {
+        const view = query.view || DEFAULT_LOG_VIEW;
+        const listOptions = {
             page,
             limit,
             api_type: query.api_type || undefined,
             model: query.model || undefined,
             router_key_id: query.router_key_id || undefined,
-        });
+        };
+        const result = view === "grouped"
+            ? getRequestLogsGrouped(db, listOptions)
+            : getRequestLogs(db, listOptions);
         return reply.send({ ...result, page, limit });
     });
     app.get("/admin/api/logs/:id", async (request, reply) => {
@@ -34,6 +40,15 @@ export const adminLogRoutes = (app, options, done) => {
         }
         return reply.send(log);
     });
+    app.get("/admin/api/logs/:id/children", async (request, reply) => {
+        const params = request.params;
+        const parent = getRequestLogById(db, params.id);
+        if (!parent) {
+            return reply.code(HTTP_NOT_FOUND).send({ error: { message: "Log not found" } });
+        }
+        const rows = getRequestLogChildren(db, params.id);
+        return reply.send({ data: rows });
+    });
     app.delete("/admin/api/logs/before", { schema: { body: DeleteLogsBeforeSchema } }, async (request, reply) => {
         const body = request.body;
         const deleted = deleteLogsBefore(db, body.before);

package/dist/admin/router-keys.js

@@ -3,8 +3,7 @@ import { Type } from "@sinclair/typebox";
 import { encrypt, decrypt } from "../utils/crypto.js";
 import { getAllRouterKeys, getRouterKeyById, createRouterKey, updateRouterKey, deleteRouterKey, getAvailableModels, } from "../db/index.js";
 import { getSetting } from "../db/settings.js";
-const HTTP_CREATED = 201;
-const HTTP_NOT_FOUND = 404;
+import { HTTP_CREATED, HTTP_NOT_FOUND } from "./constants.js";
 const KEY_RANDOM_BYTES = 32;
 const KEY_PREFIX_LENGTH = 8;
 /** 归一化 allowed_models：null/空数组/仅含空字符串 → null（允许所有模型） */

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const HTTP_BAD_REQUEST = 400;
+export declare const HTTP_CREATED = 201;
+export declare const HTTP_FORBIDDEN = 403;
+export declare const HTTP_NOT_FOUND = 404;
+export declare const HTTP_CONFLICT = 409;
+export declare const HTTP_INTERNAL_ERROR = 500;
+export declare const HTTP_BAD_GATEWAY = 502;
+export declare const HTTP_SERVICE_UNAVAILABLE = 503;

package/dist/constants.js

@@ -0,0 +1,9 @@
+// HTTP 状态码常量 — 全局唯一来源
+export const HTTP_BAD_REQUEST = 400;
+export const HTTP_CREATED = 201;
+export const HTTP_FORBIDDEN = 403;
+export const HTTP_NOT_FOUND = 404;
+export const HTTP_CONFLICT = 409;
+export const HTTP_INTERNAL_ERROR = 500;
+export const HTTP_BAD_GATEWAY = 502;
+export const HTTP_SERVICE_UNAVAILABLE = 503;

package/dist/db/index.d.ts

@@ -6,12 +6,12 @@ export { getModelMapping, getAllModelMappings, createModelMapping, updateModelMa
 export type { ModelMapping, MappingGroup, ProviderModelEntry } from "./mappings.js";
 export { getActiveRetryRules, getAllRetryRules, createRetryRule, updateRetryRule, deleteRetryRule, seedDefaultRules, } from "./retry-rules.js";
 export type { RetryRule } from "./retry-rules.js";
-export { insertRequestLog, getRequestLogs, getRequestLogById, deleteLogsBefore, insertMetrics, } from "./logs.js";
-export type { RequestLog, MetricsRow, MetricsInsert } from "./logs.js";
+export { insertRequestLog, getRequestLogs, getRequestLogById, deleteLogsBefore, getRequestLogChildren, getRequestLogsGrouped, } from "./logs.js";
+export type { RequestLog, RequestLogGroupedRow, RequestLogListRow } from "./logs.js";
 export { getRouterKeyByHash, getAllRouterKeys, getRouterKeyById, createRouterKey, updateRouterKey, deleteRouterKey, getAvailableModels, } from "./router-keys.js";
 export type { RouterKey } from "./router-keys.js";
-export { getMetricsSummary, getMetricsTimeseries } from "./metrics.js";
-export type { MetricsSummaryRow, MetricsTimeseriesRow, MetricsPeriod, MetricsMetric } from "./metrics.js";
+export { getMetricsSummary, getMetricsTimeseries, insertMetrics } from "./metrics.js";
+export type { MetricsSummaryRow, MetricsTimeseriesRow, MetricsPeriod, MetricsMetric, MetricsRow, MetricsInsert } from "./metrics.js";
 export { getStats } from "./stats.js";
 export type { Stats, StatsPeriod } from "./stats.js";
 export { getSetting, setSetting, isInitialized } from "./settings.js";

package/dist/db/index.js

@@ -39,9 +39,9 @@ export function initDatabase(dbPath) {
 export { getActiveProviders, getAllProviders, getProviderById, createProvider, updateProvider, deleteProvider, PROVIDER_CONCURRENCY_DEFAULTS, } from "./providers.js";
 export { getModelMapping, getAllModelMappings, createModelMapping, updateModelMapping, deleteModelMapping, getMappingGroup, getMappingGroupById, getAllMappingGroups, createMappingGroup, updateMappingGroup, deleteMappingGroup, getActiveProviderModels, resolveByProviderModel, } from "./mappings.js";
 export { getActiveRetryRules, getAllRetryRules, createRetryRule, updateRetryRule, deleteRetryRule, seedDefaultRules, } from "./retry-rules.js";
-export { insertRequestLog, getRequestLogs, getRequestLogById, deleteLogsBefore, insertMetrics, } from "./logs.js";
+export { insertRequestLog, getRequestLogs, getRequestLogById, deleteLogsBefore, getRequestLogChildren, getRequestLogsGrouped, } from "./logs.js";
 export { getRouterKeyByHash, getAllRouterKeys, getRouterKeyById, createRouterKey, updateRouterKey, deleteRouterKey, getAvailableModels, } from "./router-keys.js";
-export { getMetricsSummary, getMetricsTimeseries } from "./metrics.js";
+export { getMetricsSummary, getMetricsTimeseries, insertMetrics } from "./metrics.js";
 export { getStats } from "./stats.js";
 export { getSetting, setSetting, isInitialized } from "./settings.js";
 export { getSessionStates, getSessionState, getSessionHistory, upsertSessionState, insertSessionHistory, deleteSessionState, } from "./session-states.js";

package/dist/db/logs.d.ts

@@ -16,6 +16,7 @@ export interface RequestLog {
     upstream_response: string | null;
     client_response: string | null;
     is_retry: number;
+    is_failover: number;
     original_request_id: string | null;
     original_model: string | null;
 }
@@ -24,38 +25,6 @@ export interface RequestLogListRow extends RequestLog {
     backend_model: string | null;
     provider_name: string | null;
 }
-export interface MetricsRow {
-    id: string;
-    request_log_id: string;
-    provider_id: string;
-    backend_model: string;
-    api_type: string;
-    input_tokens: number | null;
-    output_tokens: number | null;
-    cache_creation_tokens: number | null;
-    cache_read_tokens: number | null;
-    ttft_ms: number | null;
-    total_duration_ms: number | null;
-    tokens_per_second: number | null;
-    stop_reason: string | null;
-    is_complete: number;
-    created_at: string;
-}
-export type MetricsInsert = {
-    request_log_id: string;
-    provider_id: string;
-    backend_model: string;
-    api_type: string;
-    input_tokens?: number | null;
-    output_tokens?: number | null;
-    cache_creation_tokens?: number | null;
-    cache_read_tokens?: number | null;
-    ttft_ms?: number | null;
-    total_duration_ms?: number | null;
-    tokens_per_second?: number | null;
-    stop_reason?: string | null;
-    is_complete?: number;
-};
 export interface RequestLogInsert {
     id: string;
     api_type: string;
@@ -73,6 +42,7 @@ export interface RequestLogInsert {
     upstream_response?: string | null;
     client_response?: string | null;
     is_retry?: number;
+    is_failover?: number;
     original_request_id?: string | null;
     router_key_id?: string | null;
     original_model?: string | null;
@@ -90,4 +60,19 @@ export declare function getRequestLogs(db: Database.Database, options: {
 };
 export declare function getRequestLogById(db: Database.Database, id: string): RequestLog | undefined;
 export declare function deleteLogsBefore(db: Database.Database, beforeDate: string): number;
-export declare function insertMetrics(db: Database.Database, m: MetricsInsert): string;
+/** 查询某条日志的子请求（retry/failover 关联），上限 100 条 */
+export declare function getRequestLogChildren(db: Database.Database, parentId: string): RequestLogListRow[];
+export interface RequestLogGroupedRow extends RequestLogListRow {
+    child_count: number;
+}
+/** 只返回根请求（original_request_id IS NULL），附带子请求数量 */
+export declare function getRequestLogsGrouped(db: Database.Database, options: {
+    page: number;
+    limit: number;
+    api_type?: string;
+    model?: string;
+    router_key_id?: string;
+}): {
+    data: RequestLogGroupedRow[];
+    total: number;
+};

package/dist/db/logs.js

@@ -1,10 +1,17 @@
-import { randomUUID } from "crypto";
+// --- request_logs ---
+/** 三处日志列表查询共享的 SELECT 列 + JOIN 子句 */
+const LOG_LIST_SELECT = `rl.id, rl.api_type, rl.model, rl.provider_id, rl.status_code, rl.latency_ms,
+            rl.is_stream, rl.error_message, rl.created_at, rl.is_retry, rl.is_failover, rl.original_request_id, rl.original_model,
+            CASE WHEN rl.provider_id = 'router' THEN rl.upstream_request ELSE NULL END AS upstream_request,
+            rm.backend_model, COALESCE(p.name, rl.provider_id) AS provider_name`;
+const LOG_LIST_JOIN = `LEFT JOIN request_metrics rm ON rm.request_log_id = rl.id
+     LEFT JOIN providers p ON p.id = rl.provider_id`;
 export function insertRequestLog(db, log) {
-    db.prepare(`INSERT INTO request_logs (id, api_type, model, provider_id, status_code, latency_ms, is_stream, error_message, created_at, request_body, response_body, client_request, upstream_request, upstream_response, client_response, is_retry, original_request_id, router_key_id, original_model)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(log.id, log.api_type, log.model, log.provider_id, log.status_code, log.latency_ms, log.is_stream, log.error_message, log.created_at, log.request_body ?? null, log.response_body ?? null, log.client_request ?? null, log.upstream_request ?? null, log.upstream_response ?? null, log.client_response ?? null, log.is_retry ?? 0, log.original_request_id ?? null, log.router_key_id ?? null, log.original_model ?? null);
+    db.prepare(`INSERT INTO request_logs (id, api_type, model, provider_id, status_code, latency_ms, is_stream, error_message, created_at, request_body, response_body, client_request, upstream_request, upstream_response, client_response, is_retry, is_failover, original_request_id, router_key_id, original_model)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(log.id, log.api_type, log.model, log.provider_id, log.status_code, log.latency_ms, log.is_stream, log.error_message, log.created_at, log.request_body ?? null, log.response_body ?? null, log.client_request ?? null, log.upstream_request ?? null, log.upstream_response ?? null, log.client_response ?? null, log.is_retry ?? 0, log.is_failover ?? 0, log.original_request_id ?? null, log.router_key_id ?? null, log.original_model ?? null);
 }
-export function getRequestLogs(db, options) {
-    let where = "1=1";
+function buildLogWhereClause(options, baseCondition) {
+    let where = baseCondition;
     const params = [];
     if (options.api_type) {
         where += " AND rl.api_type = ?";
@@ -18,16 +25,16 @@ export function getRequestLogs(db, options) {
         where += " AND rl.router_key_id = ?";
         params.push(options.router_key_id);
     }
+    return { where, params };
+}
+export function getRequestLogs(db, options) {
+    const { where, params } = buildLogWhereClause(options, "1=1");
     const total = db.prepare(`SELECT COUNT(*) as count FROM request_logs rl WHERE ${where}`).get(...params).count;
     const offset = (options.page - 1) * options.limit;
     const data = db
-        .prepare(`SELECT rl.id, rl.api_type, rl.model, rl.provider_id, rl.status_code, rl.latency_ms,
-              rl.is_stream, rl.error_message, rl.created_at, rl.is_retry, rl.original_request_id, rl.original_model,
-              CASE WHEN rl.provider_id = 'router' THEN rl.upstream_request ELSE NULL END AS upstream_request,
-              rm.backend_model, COALESCE(p.name, rl.provider_id) AS provider_name
+        .prepare(`SELECT ${LOG_LIST_SELECT}
        FROM request_logs rl
-       LEFT JOIN request_metrics rm ON rm.request_log_id = rl.id
-       LEFT JOIN providers p ON p.id = rl.provider_id
+       ${LOG_LIST_JOIN}
        WHERE ${where} ORDER BY rl.created_at DESC LIMIT ? OFFSET ?`)
         .all(...params, options.limit, offset);
     return { data, total };
@@ -38,10 +45,26 @@ export function getRequestLogById(db, id) {
 export function deleteLogsBefore(db, beforeDate) {
     return db.prepare("DELETE FROM request_logs WHERE created_at < ?").run(beforeDate).changes;
 }
-// --- request_metrics ---
-export function insertMetrics(db, m) {
-    const id = randomUUID();
-    db.prepare(`INSERT INTO request_metrics (id, request_log_id, provider_id, backend_model, api_type, input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, ttft_ms, total_duration_ms, tokens_per_second, stop_reason, is_complete)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, m.request_log_id, m.provider_id, m.backend_model, m.api_type, m.input_tokens ?? null, m.output_tokens ?? null, m.cache_creation_tokens ?? null, m.cache_read_tokens ?? null, m.ttft_ms ?? null, m.total_duration_ms ?? null, m.tokens_per_second ?? null, m.stop_reason ?? null, m.is_complete ?? 1);
-    return id;
+/** 查询某条日志的子请求（retry/failover 关联），上限 100 条 */
+export function getRequestLogChildren(db, parentId) {
+    return db.prepare(`SELECT ${LOG_LIST_SELECT}
+     FROM request_logs rl
+     ${LOG_LIST_JOIN}
+     WHERE rl.original_request_id = ?
+     ORDER BY rl.created_at ASC
+     LIMIT 100`).all(parentId);
+}
+/** 只返回根请求（original_request_id IS NULL），附带子请求数量 */
+export function getRequestLogsGrouped(db, options) {
+    const { where, params } = buildLogWhereClause(options, "rl.original_request_id IS NULL");
+    const total = db.prepare(`SELECT COUNT(*) as count FROM request_logs rl WHERE ${where}`).get(...params).count;
+    const offset = (options.page - 1) * options.limit;
+    const data = db
+        .prepare(`SELECT ${LOG_LIST_SELECT},
+              (SELECT COUNT(*) FROM request_logs c WHERE c.original_request_id = rl.id) AS child_count
+       FROM request_logs rl
+       ${LOG_LIST_JOIN}
+       WHERE ${where} ORDER BY rl.created_at DESC LIMIT ? OFFSET ?`)
+        .all(...params, options.limit, offset);
+    return { data, total };
 }

package/dist/db/metrics.d.ts

@@ -1,6 +1,39 @@
 import Database from "better-sqlite3";
 export type MetricsPeriod = "1h" | "6h" | "24h" | "7d" | "30d";
 export type MetricsMetric = "ttft" | "tps" | "tokens" | "cache_rate" | "request_count" | "input_tokens" | "output_tokens" | "cache_hit_tokens";
+export interface MetricsRow {
+    id: string;
+    request_log_id: string;
+    provider_id: string;
+    backend_model: string;
+    api_type: string;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    cache_creation_tokens: number | null;
+    cache_read_tokens: number | null;
+    ttft_ms: number | null;
+    total_duration_ms: number | null;
+    tokens_per_second: number | null;
+    stop_reason: string | null;
+    is_complete: number;
+    created_at: string;
+}
+export type MetricsInsert = {
+    request_log_id: string;
+    provider_id: string;
+    backend_model: string;
+    api_type: string;
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_creation_tokens?: number | null;
+    cache_read_tokens?: number | null;
+    ttft_ms?: number | null;
+    total_duration_ms?: number | null;
+    tokens_per_second?: number | null;
+    stop_reason?: string | null;
+    is_complete?: number;
+};
+export declare function insertMetrics(db: Database.Database, m: MetricsInsert): string;
 export interface MetricsSummaryRow {
     provider_id: string;
     provider_name: string;

package/dist/db/metrics.js

@@ -1,3 +1,10 @@
+import { randomUUID } from "crypto";
+export function insertMetrics(db, m) {
+    const id = randomUUID();
+    db.prepare(`INSERT INTO request_metrics (id, request_log_id, provider_id, backend_model, api_type, input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, ttft_ms, total_duration_ms, tokens_per_second, stop_reason, is_complete)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, m.request_log_id, m.provider_id, m.backend_model, m.api_type, m.input_tokens ?? null, m.output_tokens ?? null, m.cache_creation_tokens ?? null, m.cache_read_tokens ?? null, m.ttft_ms ?? null, m.total_duration_ms ?? null, m.tokens_per_second ?? null, m.stop_reason ?? null, m.is_complete ?? 1);
+    return id;
+}
 const PERIOD_OFFSET = {
     "1h": "-1 hours",
     "6h": "-6 hours",

package/dist/db/migrations/018_add_failover_field.sql

@@ -0,0 +1,2 @@
+ALTER TABLE request_logs ADD COLUMN is_failover INTEGER NOT NULL DEFAULT 0;
+CREATE INDEX IF NOT EXISTS idx_request_logs_original_request_id ON request_logs(original_request_id);

package/dist/db/retry-rules.d.ts

@@ -26,7 +26,7 @@ export declare function createRetryRule(db: Database.Database, rule: {
 export declare function updateRetryRule(db: Database.Database, id: string, fields: Partial<Pick<RetryRule, "name" | "status_code" | "body_pattern" | "is_active" | "retry_strategy" | "retry_delay_ms" | "max_retries" | "max_delay_ms">>): void;
 export declare function deleteRetryRule(db: Database.Database, id: string): void;
 /**
- * 首次启动时（表为空）插入默认重试规则。
- * 429/503 为通用 HTTP 重试；其余为 ZAI middleware 特定 400 响应。
+ * 启动时按名称查重插入默认重试规则。
+ * 已存在的规则不会被重复插入或覆盖。
  */
 export declare function seedDefaultRules(db: Database.Database): void;

package/dist/db/retry-rules.js

@@ -28,25 +28,38 @@ export function deleteRetryRule(db, id) {
     deleteById(db, "retry_rules", id);
 }
 // ---------- Default seed rules ----------
+const DEFAULT_RETRY_FIELDS = {
+    is_active: 1,
+    retry_strategy: "exponential",
+    retry_delay_ms: DEFAULT_RETRY_DELAY_MS,
+    max_retries: DEFAULT_MAX_RETRIES,
+    max_delay_ms: DEFAULT_MAX_DELAY_MS,
+};
 const DEFAULT_RULES = [
-    { name: "429 Too Many Requests", status_code: 429, body_pattern: ".*", is_active: 1, retry_strategy: "exponential", retry_delay_ms: 5000, max_retries: 10, max_delay_ms: 60000 },
-    { name: "503 Service Unavailable", status_code: 503, body_pattern: ".*", is_active: 1, retry_strategy: "exponential", retry_delay_ms: 5000, max_retries: 10, max_delay_ms: 60000 },
-    { name: 'ZAI 网络错误 (code 1234)', status_code: 400, body_pattern: '"type"\\s*:\\s*"error".*"code"\\s*:\\s*"1234"', is_active: 1, retry_strategy: "exponential", retry_delay_ms: 5000, max_retries: 10, max_delay_ms: 60000 },
-    { name: 'ZAI 临时不可用', status_code: 400, body_pattern: '"type"\\s*:\\s*"error".*请稍后重试', is_active: 1, retry_strategy: "exponential", retry_delay_ms: 5000, max_retries: 10, max_delay_ms: 60000 },
-    { name: 'ZAI 操作失败 (code 500)', status_code: 400, body_pattern: '"type"\\s*:\\s*"error".*"code"\\s*:\\s*"500"', is_active: 1, retry_strategy: "exponential", retry_delay_ms: 5000, max_retries: 10, max_delay_ms: 60000 },
+    { name: "429 Too Many Requests", status_code: 429, body_pattern: ".*", ...DEFAULT_RETRY_FIELDS },
+    { name: "503 Service Unavailable", status_code: 503, body_pattern: ".*", ...DEFAULT_RETRY_FIELDS },
+    { name: 'ZAI 网络错误 (code 1234)', status_code: 400, body_pattern: '"type"\\s*:\\s*"error".*"code"\\s*:\\s*"1234"', ...DEFAULT_RETRY_FIELDS },
+    { name: 'ZAI 临时不可用', status_code: 400, body_pattern: '"type"\\s*:\\s*"error".*请稍后重试', ...DEFAULT_RETRY_FIELDS },
+    { name: 'ZAI 操作失败 (code 500)', status_code: 400, body_pattern: '"type"\\s*:\\s*"error".*"code"\\s*:\\s*"500"', ...DEFAULT_RETRY_FIELDS },
+    { name: 'ZAI 速率限制 (HTTP 200, code 1302)', status_code: 200, body_pattern: '"error".*"code"\\s*:\\s*"1302"', ...DEFAULT_RETRY_FIELDS },
+    { name: 'ZAI SSE 错误 (HTTP 200, code 500)', status_code: 200, body_pattern: '"error".*"code"\\s*:\\s*"500"', ...DEFAULT_RETRY_FIELDS },
+    { name: 'ZAI SSE 错误 (HTTP 200, code 1234)', status_code: 200, body_pattern: '"error".*"code"\\s*:\\s*"1234"', ...DEFAULT_RETRY_FIELDS },
 ];
 /**
- * 首次启动时（表为空）插入默认重试规则。
- * 429/503 为通用 HTTP 重试；其余为 ZAI middleware 特定 400 响应。
+ * 启动时按名称查重插入默认重试规则。
+ * 已存在的规则不会被重复插入或覆盖。
  */
 export function seedDefaultRules(db) {
-    const count = db.prepare("SELECT COUNT(*) as c FROM retry_rules").get().c;
-    if (count > 0)
-        return;
-    const now = new Date().toISOString();
-    const insert = db.prepare(`INSERT INTO retry_rules (id, name, status_code, body_pattern, is_active, created_at, retry_strategy, retry_delay_ms, max_retries, max_delay_ms)
+    const names = DEFAULT_RULES.map(r => r.name);
+    const placeholders = names.map(() => '?').join(',');
+    const existing = db.prepare(`SELECT name FROM retry_rules WHERE name IN (${placeholders})`).all(...names);
+    const existingSet = new Set(existing.map(r => r.name));
+    const stmt = db.prepare(`INSERT INTO retry_rules (id, name, status_code, body_pattern, is_active, created_at, retry_strategy, retry_delay_ms, max_retries, max_delay_ms)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const now = new Date().toISOString();
     for (const rule of DEFAULT_RULES) {
-        insert.run(randomUUID(), rule.name, rule.status_code, rule.body_pattern, rule.is_active, now, rule.retry_strategy, rule.retry_delay_ms, rule.max_retries, rule.max_delay_ms);
+        if (!existingSet.has(rule.name)) {
+            stmt.run(randomUUID(), rule.name, rule.status_code, rule.body_pattern, rule.is_active, now, rule.retry_strategy, rule.retry_delay_ms, rule.max_retries, rule.max_delay_ms);
+        }
     }
 }

package/dist/index.js

@@ -5,9 +5,7 @@ import { existsSync } from "node:fs";
 import { randomUUID } from "crypto";
 import Fastify from "fastify";
 import { insertRequestLog } from "./db/logs.js";
-const HTTP_NOT_FOUND = 404;
-const HTTP_INTERNAL_ERROR = 500;
-const HTTP_BAD_REQUEST = 400;
+import { HTTP_NOT_FOUND, HTTP_INTERNAL_ERROR, HTTP_BAD_REQUEST } from "./constants.js";
 const PROVIDER_DEFAULT_QUEUE_TIMEOUT_MS = 5000;
 const PROVIDER_DEFAULT_MAX_QUEUE_SIZE = 100;
 // 代理路由路径 → api_type，用于在全局 hook/errorHandler 中识别代理请求
@@ -109,7 +107,7 @@ export async function buildApp(options) {
     const matcher = new RetryRuleMatcher();
     matcher.load(db);
     const semaphoreManager = new ProviderSemaphoreManager();
-    const tracker = new RequestTracker({ semaphoreManager });
+    const tracker = new RequestTracker({ semaphoreManager, logger: app.log });
     tracker.startPushInterval();
     // 从 DB 读取已有 provider 的并发配置，初始化信号量管理器和 tracker
     const allProviders = getAllProviders(db);
@@ -162,7 +160,7 @@ export async function buildApp(options) {
                 !request.url.startsWith("/admin/api")) {
                 return reply.sendFile("index.html");
             }
-            reply.code(HTTP_NOT_FOUND).send({ error: "Not Found" });
+            reply.code(HTTP_NOT_FOUND).send({ error: { message: "Not Found" } });
         });
     }
     else {