From 28b09075947766d768b6bc41d659ec9e69d14dff Mon Sep 17 00:00:00 2001 From: zyycn Date: Thu, 9 Jul 2026 22:39:22 +0800 Subject: [PATCH] docs: document postgresql redis storage target Co-authored-by: Codex --- docs/architecture.md | 133 ++++--- docs/database.md | 906 ++++++++++++++++++++----------------------- 2 files changed, 488 insertions(+), 551 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 074dc3683..8dbba0960 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,15 +2,15 @@ 本文档是 Codex Proxy RS 的**唯一**架构权威文档:分层模型、依赖规则、目录与文件命名规范、模块约束、现状审计结论、旧→新完整映射与分阶段执行方案。 -- 数据库 schema、口径与迁移见 [database.md](database.md);本文不重复。 +- 存储 schema、Redis 键契约、口径与搬迁见 [database.md](database.md)(2026-07-09 起为 **PostgreSQL + Redis 终态**);本文不重复。 - 基线:2026-07-08,`backend/src` 共 160 个 `.rs` 文件、约 41k 行。 -- 本文的目标结构与 database.md 的 v4 改造**共用同一个改造窗口**:遥测域(usage/ops/buckets)的文件本来就要因 schema v4 重写,搬家与重写一次完成,不做两遍。 +- 存储终态切换(SQLite → PG + Redis,含 v4 语义)触及**所有** store 文件,无法按域切片——它作为 **PR0** 先行完成(§8);此后本文的搬家 PR 全部回到"零行为变更"原则。原先"遥测域与 schema v4 同窗口重写"的约定由 PR0 吸收。 --- ## 1. 系统总览 -单进程:Rust/Axum 同时承载 OpenAI Responses 兼容代理、管理端 API、SQLite 持久化、后台任务、静态 SPA 托管与在线更新。Vue 3 管理端由同一进程托管。 +单二进制:Rust/Axum 同时承载 OpenAI Responses 兼容代理、管理端 API、后台任务、静态 SPA 托管与在线更新。Vue 3 管理端由同一进程托管。持久数据在 PostgreSQL,运行态与缓存在 Redis(分界与丢失语义见 database.md §1);**单实例部署,不考虑多实例**(database.md §8"明确不做"),选择外置存储是运维形态决策——原生 TTL、在线备份、容器内无本地数据文件。 ```text 客户端 SDK ──/v1/*──┐ ┌── ChatGPT / Codex backend @@ -20,13 +20,13 @@ │ │ telemetry / keys / auth / settings / update │ - infra(SQLite / 日志 / 时间) + infra(PostgreSQL / Redis / 日志 / 时间) ``` -核心原则(不变): +核心原则(第 2 条随存储终态修订,其余不变): -1. 启动配置只含进程启动必需项;其余全部在 SQLite 热更新。 -2. 代理热路径只依赖内存态服务;持久化写入在请求完成、后台任务或设置更新时发生。 +1. 启动配置只含进程启动必需项;其余全部在 PostgreSQL(`runtime_settings`)热更新。 +2. 代理热路径的存储访问只有两类:PG unique 索引点查(client key 鉴权)与 Redis 运行态读写(亲和、租约,亚毫秒);事实与聚合的 PG 写入发生在请求完成时,重查询只存在于管理端。 3. 上游请求统一经过账号池、session affinity、quota、fingerprint 与 transport。 --- @@ -37,11 +37,11 @@ | 层 | 模块 | 职责 | 禁止 | | --- | --- | --- | --- | -| L0 | `infra` | SQLite 连接/迁移、时间、JSON、日志、身份生成、路径、格式化 | 出现任何业务概念 | +| L0 | `infra` | PostgreSQL 连接/迁移、Redis 连接/键前缀、时间、JSON、日志、身份生成、路径、格式化 | 出现任何业务概念 | | L1 | `upstream` | 纯上游客户端:协议编解码、HTTP/SSE/WebSocket 传输、指纹、OAuth token client。**每家 provider 一个子目录**(`openai/`,规划中 `cloudflare/`) | 依赖任何领域模块;出现账号池/调度/遥测概念 | | L1 | `telemetry` | 遥测域:usage_records / ops_error_logs / request_time_buckets / account_usage 的**写入与查询**、billing、dashboard 聚合、rebuild | 被冠以 admin 语义;HTTP handler | | L1 | `keys` | 客户端 API key 域:store、内存缓存、鉴权校验、管理操作 | — | -| L1 | `auth` | 管理端认证域:admin 用户、会话(token_hash) | 客户端 key 概念(那是 `keys`) | +| L1 | `auth` | 管理端认证域:admin 用户(PG)、会话(Redis,token_hash 键,database.md §4B.1) | 客户端 key 概念(那是 `keys`) | | L1 | `settings` | 运行时设置域:持久化、快照、变更广播(watch)、admin API key 校验 | 直接调用上层服务推送变更(§2.3) | | L1 | `update` | 自更新域:release 查询、下载、校验、解压、替换、状态 | — | | L2 | `accounts` | 账号域:实体、池、调度器、store、quota、token 刷新、Cookie、导入导出、管理操作 | — | @@ -64,7 +64,7 @@ - L1–L3 任何模块 import `crate::api` / `crate::bootstrap`。 - `dispatch`、`accounts`、`telemetry` 等领域模块 import `axum`。 -- `api` 下出现 `sqlx`(SQL 只允许在各域的 `store` 文件里)。 +- `api` 下出现 `sqlx` 或 `redis`(SQL 与 Redis 命令都只允许在各域的 `store` 文件里,§5.2)。 - `upstream` import `crate::{accounts, dispatch, telemetry, keys, auth, settings, update, models}`。 - 任何模块 import 旧路径 `crate::admin` / `crate::proxy` / `crate::runtime` / `crate::web` / `crate::http` / `crate::config`(改造完成后这些模块不存在)。 @@ -79,12 +79,13 @@ ```text backend/src/ -├── main.rs +├── main.rs # 子命令入口:serve(默认)/ import-sqlite / rebuild-buckets ├── lib.rs ├── infra/ # L0 │ ├── mod.rs -│ ├── database.rs # 连接、pragma、迁移框架(含 Rust post 钩子,database.md §6.1) -│ ├── migrations/ # *.sql +│ ├── database.rs # PgPool 连接/池参数、迁移框架(PG 谱系 0001 终态基线)、ping +│ ├── redis.rs # Redis ConnectionManager、键前缀、ping(database.md §1) +│ ├── migrations/ # *.sql(PG) │ ├── identity.rs time.rs json.rs format.rs logging.rs paths.rs ├── upstream/ # L1 纯上游客户端(每家 provider 一个子目录) │ ├── mod.rs # 第二家 provider 出现时,UpstreamClient trait 落此 @@ -101,22 +102,23 @@ backend/src/ │ ├── mod.rs types.rs store.rs runtime.rs updater.rs ├── telemetry/ # L1 遥测域(原 admin/monitoring + proxy/dispatch/usage_events) │ ├── mod.rs -│ ├── recorder.rs # 唯一写入口:成功/失败两条事务(database.md §5.2) +│ ├── recorder.rs # 唯一写入口:成功/失败两条 PG 事务(database.md §5.2) │ ├── billing.rs -│ ├── rebuild.rs # rebuild-derived(database.md §7.6) -│ ├── dashboard.rs # Dashboard 聚合查询(无 HTTP) +│ ├── rebuild.rs # rebuild-buckets(database.md §7) +│ ├── dashboard.rs # Dashboard 聚合查询(无 HTTP;口径 database.md §5.3) │ ├── usage/ # usage_records │ │ ├── mod.rs types.rs store.rs query.rs -│ ├── ops/ # ops_error_logs +│ ├── ops/ # ops_error_logs(含 /api/admin/ops/errors 的查询面) │ │ ├── mod.rs types.rs store.rs query.rs │ ├── buckets/ # request_time_buckets │ │ ├── mod.rs store.rs query.rs │ └── account_usage/ # account_usage / account_model_usage │ ├── mod.rs store.rs query.rs ├── keys/ # L1 客户端 key 域(原 admin/keys/service.rs 拆分) -│ ├── mod.rs types.rs store.rs cache.rs service.rs manage.rs +│ ├── mod.rs types.rs store.rs service.rs manage.rs +│ │ # 鉴权 = SHA-256 → PG 点查(database.md §4.3),无内存明文缓存文件 ├── auth/ # L1 管理端认证域(原 admin/auth/service.rs) -│ ├── mod.rs types.rs store.rs service.rs +│ ├── mod.rs types.rs store.rs service.rs # store = PG admin_users + Redis 会话键(§4B.1) ├── settings/ # L1 运行时设置域(原 config/settings.rs) │ ├── mod.rs types.rs store.rs service.rs # service 持 watch 广播 ├── update/ # L1 自更新域(原 admin/system/*) @@ -131,13 +133,13 @@ backend/src/ │ │ ├── candidates.rs feedback.rs │ │ └── strategy/ │ │ ├── mod.rs smart.rs quota_reset.rs round_robin.rs sticky.rs -│ ├── store.rs # AccountStore trait + Sqlite 门面 +│ ├── store.rs # AccountStore trait + PG 门面 │ ├── store/ │ │ ├── queries.rs rows.rs │ ├── quota/ │ │ ├── mod.rs service.rs runtime.rs │ ├── refresh/ # 原 token_refresh -│ │ ├── mod.rs policy.rs lease.rs service.rs +│ │ ├── mod.rs policy.rs lease.rs service.rs # lease = Redis SET NX PX(§4B.2) │ ├── cookies/ │ │ ├── mod.rs store.rs │ ├── import.rs # 导入 payload 解析(原 upstream/accounts/importing.rs) @@ -145,7 +147,7 @@ backend/src/ │ ├── mod.rs types.rs service.rs lifecycle.rs │ ├── import.rs export.rs oauth.rs probe.rs quota.rs quota_view.rs ├── models/ # L2 模型目录域 -│ ├── mod.rs types.rs catalog.rs service.rs store.rs +│ ├── mod.rs types.rs catalog.rs service.rs store.rs # store = Redis 快照 HASH(§4B.4) ├── dispatch/ # L3 请求编排域(原 proxy/dispatch) │ ├── mod.rs │ ├── service.rs # 编排入口(原 responses/service.rs,按 §5.4 拆分) @@ -153,7 +155,7 @@ backend/src/ │ ├── errors.rs # 原 dispatch/errors.rs + responses/errors.rs 合并 │ ├── recording.rs # 原 responses/event_recording.rs,调 telemetry::recorder │ ├── affinity/ # 原 session_affinity.rs(683 行三合一)+ responses/affinity.rs -│ │ ├── mod.rs types.rs store.rs service.rs resolve.rs +│ │ ├── mod.rs types.rs store.rs service.rs resolve.rs # store = Redis 键 + 二级索引(§4B.3),无内存映射副本 │ ├── recovery/ │ │ ├── mod.rs auth.rs cloudflare.rs exhaustion.rs │ │ ├── implicit_resume.rs reasoning_replay.rs @@ -161,7 +163,7 @@ backend/src/ │ ├── mod.rs live.rs lifecycle.rs prefetch.rs sse_failure.rs trace.rs ├── api/ # L4 全部入站 HTTP(原 http + web + proxy 入口 + admin routes) │ ├── mod.rs -│ ├── router.rs # 总路由 + healthz(经 infra 的 db ping,不穿透到具体 store 的 pool) +│ ├── router.rs # 总路由 + healthz(infra 的 PG ping + Redis ping,任一失败 503) │ ├── assets.rs # SPA 静态资源(原 web/assets.rs) │ ├── middleware/ │ │ ├── mod.rs request_id.rs trace.rs @@ -172,16 +174,18 @@ backend/src/ │ ├── mod.rs router.rs response.rs session.rs # session = 鉴权提取器/中间件 │ ├── auth_routes.rs settings_routes.rs system_routes.rs │ ├── accounts_routes.rs keys_routes.rs -│ ├── usage_routes.rs dashboard_routes.rs +│ ├── usage_routes.rs ops_routes.rs dashboard_routes.rs # ops_routes = /api/admin/ops/errors └── bootstrap/ # L5 进程装配(原 runtime + config/schema,loader) ├── mod.rs - ├── config.rs # 启动配置 schema + loader(原 config/schema.rs + loader.rs) + ├── config.rs # 启动配置 schema + loader(原 config/schema.rs + loader.rs;含 redis.url) ├── services.rs state.rs shutdown.rs + ├── import_sqlite.rs # 一次性 SQLite v3 → PG 导入命令(database.md §6;§5.5 的唯一跨域写豁免) └── tasks/ ├── mod.rs coordinator.rs periodic.rs cleanup.rs - ├── cookie_cleanup.rs session_cleanup.rs session_affinity_cleanup.rs + ├── cookie_cleanup.rs retention_trim.rs # retention_trim 新增(database.md §7) ├── model_refresh.rs token_refresh.rs quota_refresh.rs - ├── fingerprint_update.rs retention_trim.rs # retention_trim 新增(database.md §7.7) + ├── fingerprint_update.rs + # session_cleanup / session_affinity_cleanup 不复存在:Redis TTL 接管(database.md §4B) ``` `backend/tests/` 目录结构**镜像 `src/`**:模块搬家时测试目录同步搬家,`fixtures/`、`support/` 不动。 @@ -205,8 +209,8 @@ backend/src/ | --- | --- | --- | | `router.rs` | 路由组合 | 只 merge/nest,不写 handler | | `*_routes.rs` / `routes.rs` | HTTP handler + 请求/响应 DTO | 不写 SQL、不含领域规则 | -| `service.rs` | 领域服务(该域对外门面) | 不含 SQL 文本 | -| `store.rs` | SQLite 持久化 | SQL 只允许出现在这里;类型名 `Sqlite*Store` | +| `service.rs` | 领域服务(该域对外门面) | 不含 SQL 文本与 Redis 命令 | +| `store.rs` | 持久化/运行态存取(PG SQL 或 Redis 命令) | SQL 与 Redis 命令只允许出现在这里;类型名 `Pg*Store` / `Redis*Store` | | `cache.rs` | 内存缓存/运行时快照 | 类型名 `Runtime*` | | `query.rs` | 复杂只读查询(列表/聚合/分页) | 与写路径分文件 | | `types.rs` | 该域跨文件共享的实体/值类型 | 无 IO | @@ -223,12 +227,13 @@ backend/src/ | 前缀/形态 | 保留给 | 示例 | | --- | --- | --- | -| `Sqlite*Store` | store 实现 | `SqliteAccountStore` | -| `Runtime*` | 内存缓存/快照服务 | `RuntimeClientKeyCache` | +| `Pg*Store` | PostgreSQL store 实现 | `PgAccountStore` | +| `Redis*Store` | Redis store 实现 | `RedisSessionAffinityStore` | +| `Runtime*` | 内存缓存/快照服务 | `RuntimeAccountPoolService`、`RuntimeFingerprint` | | `Admin*` | **仅** `api/admin` 下的 DTO/提取器 | `AdminAccountPayload` | | 无前缀 | 领域服务与实体 | `Recorder`、`AccountScheduler`、`SettingsService` | -由此更名(现状 → 终态):`AdminUsageRecordService` → `telemetry::usage::UsageQueryService`(读)+ `telemetry::Recorder`(写);`AdminOpsErrorLogService` → `telemetry::ops` 同拆;`AdminUsageService`(实际管 account_usage)→ `telemetry::account_usage::AccountUsageQueryService`;`AdminSessionService` → `auth::SessionService`;`AdminClientKeyService` → `keys::KeyManageService`;`ClientKeyService` → `keys::KeyVerifier`。**类型名与文件名对不上的历史包袱全部在搬家时清算,不留别名 re-export。** +由此更名(现状 → 终态):`Sqlite*Store` 全系 → `Pg*Store` 或 `Redis*Store`(按 database.md 的归属,引擎切换 PR0 完成);`AdminUsageRecordService` → `telemetry::usage::UsageQueryService`(读)+ `telemetry::Recorder`(写);`AdminOpsErrorLogService` → `telemetry::ops` 同拆;`AdminUsageService`(实际管 account_usage)→ `telemetry::account_usage::AccountUsageQueryService`;`AdminSessionService` → `auth::SessionService`;`AdminClientKeyService` → `keys::KeyManageService`;`ClientKeyService` → `keys::KeyVerifier`(SHA-256 → PG 点查,`RuntimeClientKeyStore` 内存明文表随哈希化消亡)。**类型名与文件名对不上的历史包袱全部在搬家时清算,不留别名 re-export。** 禁止无意义别名导入:`use std::sync::Arc as StdArc` 这类一律 `use std::sync::Arc`。 @@ -240,9 +245,9 @@ backend/src/ `mod.rs` 只做 `pub mod` 声明与 `pub use` 门面导出,≤ 50 行。现状违规(`accounts/store/mod.rs` 1126 行、`token_refresh/mod.rs` 495 行、`quota/mod.rs` 419 行、`updater/mod.rs` 811 行、`scheduler/mod.rs` 含门面类型)全部在搬家时把实现移入具名文件。 -### 5.2 SQL 边界 +### 5.2 存储边界(SQL 与 Redis 同规) -SQL 文本只允许出现在 `store.rs` / `store/` / `query.rs`。`api` 层与 `service.rs` 出现 `sqlx::query` 即为违规(现状 `http/router.rs` 的 healthz 直接拿某个 store 的连接池执行 SQL——终态 `infra::database` 提供 `ping(pool)`,router 调它)。 +SQL 文本与 Redis 命令只允许出现在 `store.rs` / `store/` / `query.rs`。`api` 层与 `service.rs` 出现 `sqlx::query` 或 `redis::` 调用即为违规(现状 `http/router.rs` 的 healthz 直接拿某个 store 的连接池执行裸 SQL——终态 `infra::database` 提供 `ping(pool)`、`infra::redis` 提供 `ping(conn)`,router 只调它们)。 ### 5.3 HTTP 边界 @@ -261,7 +266,7 @@ axum/tower 类型只允许出现在 `api` 与 `bootstrap`。领域函数签名 | `upstream/accounts/pool.rs` | 1420 | → `accounts/pool.rs`(门面)+ `pool/state.rs`(槽位/在途)+ `pool/filters.rs` | | `upstream/transport/client.rs` | 1251 | → `client.rs` + `client_sse.rs`(SSE 请求路径) | | `upstream/accounts/store/mod.rs` | 1126 | → `store.rs` 门面 + `store/queries.rs` 按读写再分 | -| `admin/monitoring/usage_record_store.rs` | 1114 | v4 重写时天然拆为 `telemetry/usage/{store,query}.rs` | +| `admin/monitoring/usage_record_store.rs` | 1114 | PR0 原地重写(拆表后 metadata 聚合全数删除,行数大减),PR1 搬家时拆 `telemetry/usage/{store,query}.rs` | | `admin/monitoring/dashboard.rs` | 1080 | → `telemetry/dashboard.rs`(聚合)+ `api/admin/dashboard_routes.rs`(HTTP) | | `upstream/protocol/websocket.rs` | 1033 | → `websocket.rs`(事件转换)+ `websocket_errors.rs`(错误帧解析) | | `upstream/accounts/token_refresh/runtime.rs` | 953 | → `accounts/refresh/{service,lease,policy}.rs` | @@ -269,21 +274,26 @@ axum/tower 类型只允许出现在 `api` 与 `bootstrap`。领域函数签名 ### 5.5 一域一账本 -每张数据库表恰好属于一个域,只有该域的 store 可以写它: +每张 PG 表 / 每个 Redis 键空间恰好属于一个域,只有该域的 store 可以写它: -| 表(database.md v4) | 属主域 | +| PG 表(database.md §4) | 属主域 | | --- | --- | | usage_records / ops_error_logs / request_time_buckets / account_usage / account_model_usage | `telemetry` | -| accounts / account_refresh_leases / account_cookies | `accounts` | -| model_plan_snapshots | `models` | +| accounts / account_cookies | `accounts` | | client_api_keys | `keys` | -| admin_users / admin_sessions | `auth` | +| admin_users | `auth` | | runtime_settings | `settings` | -| session_affinities | `dispatch`(affinity/store.rs) | | fingerprints / fingerprint_update_history | `upstream`(fingerprint/store.rs) | | schema_migrations | `infra` | -跨域读通过属主域的 query/service 方法,不直接跨域写 SQL。 +| Redis 键空间(database.md §4B) | 属主域 | +| --- | --- | +| `cpr:admin:session:*` | `auth` | +| `cpr:lease:refresh:*` | `accounts`(refresh/lease.rs) | +| `cpr:affinity:*` | `dispatch`(affinity/store.rs) | +| `cpr:models:plan_snapshots` | `models` | + +跨域读通过属主域的 query/service 方法,不直接跨域写。**唯一豁免**:`bootstrap/import_sqlite.rs`(一次性导入命令,database.md §6)按依赖序直写全部 PG 表;v3 源库退役后该文件可删。 --- @@ -328,10 +338,12 @@ axum/tower 类型只允许出现在 `api` 与 `bootstrap`。领域函数签名 | 现路径 | 终态路径 | | --- | --- | -| `config/schema.rs` + `config/loader.rs` | `bootstrap/config.rs` | +| `config/schema.rs` + `config/loader.rs` | `bootstrap/config.rs`(新增 `redis.url`,database.md §7) | | `config/settings.rs` | `settings/{types,store,service}.rs` † | | `runtime/{bootstrap,services,state,shutdown}.rs` | `bootstrap/` 同名 | -| `runtime/tasks/*` | `bootstrap/tasks/*`(新增 `retention_trim.rs`) | +| `runtime/tasks/*` | `bootstrap/tasks/*`(新增 `retention_trim.rs`;删除 `session_cleanup.rs`、`session_affinity_cleanup.rs`——Redis TTL 接管) | +| —(新增) | `infra/redis.rs`(连接、键前缀、ping) | +| —(新增) | `bootstrap/import_sqlite.rs`(SQLite v3 → PG 导入命令,吸收原 0004 迁移草案) | | `http/router.rs` | `api/router.rs` | | `http/middleware/*` | `api/middleware/*` | | `web/assets.rs` | `api/assets.rs` | @@ -345,16 +357,16 @@ axum/tower 类型只允许出现在 `api` 与 `bootstrap`。领域函数签名 | `proxy/dispatch/responses/errors.rs` + `proxy/dispatch/errors.rs` | `dispatch/errors.rs` † | | `proxy/dispatch/{auth_recovery,cloudflare,exhaustion,implicit_resume,reasoning_replay}.rs` | `dispatch/recovery/{auth,cloudflare,exhaustion,implicit_resume,reasoning_replay}.rs` | | `proxy/dispatch/upstream.rs` | `dispatch/upstream_call.rs` | -| `admin/monitoring/usage_record_{model,store,service}.rs` | `telemetry/usage/{types,store,query}.rs` †(v4 重写同窗口) | +| `admin/monitoring/usage_record_{model,store,service}.rs` | `telemetry/usage/{types,store,query}.rs` †(重写已在 PR0 完成,此处纯搬家) | | `admin/monitoring/ops_error_{model,store,service}.rs` | `telemetry/ops/{types,store,query}.rs` † | | `admin/monitoring/account_usage_{store,service}.rs` | `telemetry/account_usage/{store,query}.rs` † | | `admin/monitoring/billing.rs` | `telemetry/billing.rs` | | `admin/monitoring/dashboard.rs` | `telemetry/dashboard.rs` + `api/admin/dashboard_routes.rs` † | | `admin/monitoring/diagnostics.rs` | `telemetry/diagnostics.rs` | | `admin/monitoring/usage_record_routes.rs` | `api/admin/usage_routes.rs` | -| `admin/keys/service.rs` | `keys/{types,store,cache,service,manage}.rs` † | +| `admin/keys/service.rs` | `keys/{types,store,service,manage}.rs` †(明文内存缓存消亡,database.md §4.3) | | `admin/keys/routes.rs` | `api/admin/keys_routes.rs` | -| `admin/auth/service.rs` | `auth/{types,store,service}.rs` † | +| `admin/auth/service.rs` | `auth/{types,store,service}.rs` †(会话改 Redis,database.md §4B.1) | | `admin/auth/session.rs` | `api/admin/session.rs` | | `admin/accounts/routes.rs` | `api/admin/accounts_routes.rs` †(按子资源拆) | | `admin/accounts/quota_view.rs` | `accounts/manage/quota_view.rs` | @@ -380,20 +392,21 @@ axum/tower 类型只允许出现在 `api` 与 `bootstrap`。领域函数签名 --- -## 8. 执行计划(六个顺序 PR,每个独立编译绿、测试绿) +## 8. 执行计划(PR0 + 六个顺序搬家 PR,每个独立编译绿、测试绿) -每个 PR 的固定验收:`cargo fmt --check`、`cargo clippy -- -D warnings`、`cargo test`、`backend/scripts/check_architecture.sh`(§9,随 PR 逐步启用对应规则)、`backend/tests` 镜像目录同步搬移。**搬家 PR 原则上零行为变更**(更名与移动,不改逻辑);唯一例外是 PR1 与 database.md v4 的联动重写。 +每个 PR 的固定验收:`cargo fmt --check`、`cargo clippy -- -D warnings`、`cargo test`、`backend/scripts/check_architecture.sh`(§9,随 PR 逐步启用对应规则)、`backend/tests` 镜像目录同步搬移。**PR0 是唯一的行为变更 PR**(存储引擎与 schema 语义一次到位);PR1 起全部为零行为搬家(更名与移动,不改逻辑)。 | PR | 内容 | 关键动作 | | --- | --- | --- | -| **PR1** | `telemetry` 域成立(与 database.md 0004 + §7 代码改造同窗口) | monitoring 全部迁出 admin;`usage_events.rs` → `recorder.rs`;Admin* 遥测类型按 §4.3 更名;dispatch/api 改依赖 telemetry;启用"禁止 `crate::admin::monitoring`"检查 | -| **PR2** | `keys` / `auth` / `settings` / `update` 域成立 | 四个域从 admin/config 拆出;settings 改 watch 广播(§2.3);admin API key / session token 哈希化(database.md)落在此处;config 只剩 schema+loader | +| **PR0** | **存储终态切换**(database.md §7 全部 12 条,在现有目录结构内完成) | Cargo:sqlx 加 postgres、新增 redis;`infra/database.rs` 改 PG + 0001 终态基线、新增 `infra/redis.rs`;全部 store 换 PG 方言 / 运行态四键空间改 Redis;成功/失败事实拆表 + provider 维度 + 两条写入事务;key/session/admin-key 哈希化 + `client_api_key_id` 归因贯通;Dashboard 口径换源;trim 周期任务化;`import-sqlite` / `rebuild-buckets` 子命令;tests support 换 PG+Redis;deploy compose 加双服务。验收对齐 database.md §6.4 | +| **PR1** | `telemetry` 域成立 | monitoring 全部迁出 admin;`usage_events.rs` → `recorder.rs`;Admin* 遥测类型按 §4.3 更名;dispatch/api 改依赖 telemetry;启用"禁止 `crate::admin::monitoring`"检查 | +| **PR2** | `keys` / `auth` / `settings` / `update` 域成立 | 四个域从 admin/config 拆出;settings 改 watch 广播(§2.3);config 只剩 schema+loader | | **PR3** | `accounts` / `models` 域成立 | `upstream/accounts`、`upstream/scheduler`、`admin/accounts/service` 三处合并为 `accounts`;`upstream` 缩为纯客户端并落成 `openai/` 子目录;动名词文件更名;Repository→Store | | **PR4** | `dispatch` 域成立 | proxy/dispatch 整体迁出并按目标树重组;affinity store 独立成文件;`proxy` 只剩 api/client 的料 | | **PR5** | `api` / `bootstrap` 壳成立 | http + web + proxy 入口 + admin routes 合并为 `api`;runtime + config 装配部分改名 `bootstrap`;删除 `crate::{admin,proxy,runtime,web,http,config}` 六个旧根模块;启用全部依赖检查 | | **PR6** | 行数预算清账 | §5.4 清单内 11 个文件拆到硬线以下;启用行数预算 CI 警告 | -顺序依据:PR1 与数据库改造互锁必须最先;PR2–4 自底向上消除旧模块的存在必要;PR5 收壳;PR6 纯内部拆分无跨域影响。 +顺序依据:存储切换触及所有 store、无法按域切片,必须整体先行(PR0)——先切引擎再搬家,每个 store 文件只被"重写"一次、"移动"一次,不叠加;PR1–4 自底向上消除旧模块的存在必要;PR5 收壳;PR6 纯内部拆分无跨域影响。原"PR1 与数据库改造互锁"的约定由 PR0 替代,PR2 中的哈希化条目亦已并入 PR0。 --- @@ -423,9 +436,11 @@ deny "upstream -> domain" 'crate::(accounts|dispatch|telemetry|keys|auth|setting deny "axum outside api" '\baxum(::|\b)' \ src/infra src/upstream src/telemetry src/keys src/auth src/settings src/update \ src/accounts src/models src/dispatch -# SQL 只在 store / query +# SQL 与 Redis 命令只在 store / query deny "sqlx outside store/query" 'sqlx::query' \ $(find src/api -name '*.rs') +deny "redis outside store" '\bredis::' \ + $(find src/api -name '*.rs') # 旧模块根不得复活 deny "legacy module path" 'crate::(admin|proxy|runtime|web|http|config)::' src # 禁用文件名 @@ -451,10 +466,10 @@ exit $fail ## 10. 仓库级约定 -- `backend/tests/` 镜像 `src/`,不在 `src/` 写测试模块。 +- `backend/tests/` 镜像 `src/`,不在 `src/` 写测试模块。测试依赖本机(或 CI 服务容器)的 PostgreSQL 与 Redis:`CPR_TEST_DATABASE_URL` 下每测试建独立数据库、`CPR_TEST_REDIS_URL` 下每测试随机键前缀(database.md §7)。 - `docs/` 只保留权威文档:`architecture.md`(本文)、`database.md`。行为细节(调度策略、WS 池、更新流程等)以模块文档注释为准(`scheduler/mod.rs` 是范本),不再在 docs 里维护第二份会腐化的副本。 -- `deploy/`、`release/`、`skills/` 现状合格,不动。 -- 前端改动仅一处联动:keys 列表不再返回完整 key(database.md §7.8)。 +- `deploy/` 随 PR0 扩容(compose 增 postgres/redis 服务与健康检查依赖);`release/`、`skills/` 现状合格,不动。 +- 前端联动(全部随 PR0):keys 列表不再返回完整 key(只余 `prefix`);admin API key 状态不再有脱敏值(哈希不可逆,只余"已启用");成功记录响应不再有 `level` 字段;错误明细/筛选改走 `/api/admin/ops/errors`;Dashboard "总请求/总 token" 卡片改为 account_usage 来源并标注"成功累计"。 --- @@ -468,7 +483,7 @@ exit $fail | `models` | catalog 收录 `@cf/...` 命名空间;别名映射升级为"客户端名 → (provider, 上游名)";**models 域是"模型 → provider"的路由枢纽**,dispatch 据此选池 | | `accounts` | `scheduler/candidates` 加 provider 硬过滤(单池 + 过滤,不按 provider 拆池);`manage/{oauth,import}` 按 provider 分实现(CF 导入格式 = `(account_id, api_token)`);refresh/租约对 CF 账号整体跳过(`refresh_token` NULL 语义已覆盖) | | `dispatch` | `affinity` / `recovery` 按 provider 策略分发:CF 无会话语义 → 跳过 affinity;恢复只剩朴素 429/5xx 重试 | -| `telemetry` | 无结构改动——provider 归因维度已随 schema v4 就位(database.md §4.10–4.12);billing 单价查找加 provider 参数 | +| `telemetry` | 无结构改动——provider 归因维度已随存储终态就位(database.md §4.8–4.10);billing 单价查找加 provider 参数 | | 不动 | `api/client`(入站永远是 OpenAI 兼容协议)、`keys`、`auth`、`settings`、`update`、`infra` | -DB 侧一次性迁移(accounts 加 provider、身份列更名、快照表 PK 加维度)见 database.md §8。动工当天需实测验证三点:`cfk_` 老式 authkey 对 OpenAI 兼容端点的鉴权方式(`X-Auth-Email`/`X-Auth-Key` 还是 Bearer)、GLM 类模型是否支持上游 Responses 端点(决定适配器能否对部分模型直通)、SSE 分块与 OpenAI delta 事件的逐字段兼容性。 +DB 侧一次性迁移(accounts 加 provider、身份列更名、模型缓存 HASH field 加 provider 前缀)见 database.md §8。动工当天需实测验证三点:`cfk_` 老式 authkey 对 OpenAI 兼容端点的鉴权方式(`X-Auth-Email`/`X-Auth-Key` 还是 Bearer)、GLM 类模型是否支持上游 Responses 端点(决定适配器能否对部分模型直通)、SSE 分块与 OpenAI delta 事件的逐字段兼容性。 diff --git a/docs/database.md b/docs/database.md index 4fed6e16f..63bc2b99b 100644 --- a/docs/database.md +++ b/docs/database.md @@ -1,26 +1,35 @@ # Database —— 唯一权威文档 -本文档是 Codex Proxy RS 数据库的**唯一**权威文档:终态 Schema 全量定义、全局纪律、统计口径、一次到位的迁移方案(v3 → v4)与代码改造清单。 +本文档是 Codex Proxy RS 存储层的**唯一**权威文档:终态形态为 **PostgreSQL(持久层)+ Redis(运行态/缓存)**。全量定义 PG Schema、Redis 键契约、全局纪律、统计口径、SQLite → PG 的一次性搬迁方案与代码改造清单。 -- 取代并合并旧的三份文档(database-design.md / database-audit.md / database-schema.md),旧文档一律作废删除。 -- 基线:2026-07-08,生产库 schema v3(`backend/src/infra/database.rs`)。 -- 策略:**一次破坏性迁移直达终态,不做兼容层**。没有双写期、没有回填过渡期、没有查询层兼容过滤;不满足终态契约的历史数据按 §6.3 的规则迁移或丢弃,丢弃项全部显式列出。 +- 取代 2026-07-08 版(SQLite 单进程形态 + 0004 迁移草案)。旧版描述的 v4 终态 Schema 语义**全部保留**,宿主引擎由 SQLite 换为 PG + Redis,0004 迁移方案改由导入命令吸收。 +- 基线:生产 SQLite 库 schema v3(读侧,只读打开);PG 库从 0001 终态基线全新建立(写侧)。 +- 策略:**一次破坏性切换直达终态,不做兼容层**。没有双写期、没有 SQLite 回退路径、没有查询层兼容过滤;不满足终态契约的历史数据按 §6.3 规则导入或丢弃,丢弃项全部显式列出。 --- ## 1. 运行形态 -单进程 SQLite。这是刻意选择:自托管代理、单实例部署,SQLite 免去外部依赖且性能远超需求。多实例是明确的未来触发条件而非当前需求(§8)。 +**单实例部署;PostgreSQL 承载一切持久数据,Redis 承载一切运行态与缓存。** 选择外置存储是运维形态决策,不以多实例为目标(**不考虑多实例部署**): -连接参数(`database.rs` 连接期设置,全部显式): +- PG:真正的数据库服务器——在线备份、成熟工具链、管理端重查询与热路径写入不再争抢单写者;容器内不再有本地数据文件。 +- Redis:运行态的原生 TTL 语义——会话/租约/亲和的过期由存储自身表达,三个清理任务与"重启恢复"步骤整体消失。 -| Pragma | 值 | 理由 | +| 存储 | 承载 | 丢失语义 | | --- | --- | --- | -| `journal_mode` | WAL | 读写不互斥,单写多读的正确形态 | -| `synchronous` | NORMAL | WAL 下的标准取舍:掉电最多丢最后一次 checkpoint 后的事务,不损坏库。FULL 的额外 fsync 对本系统无意义 | -| `foreign_keys` | ON | 级联删除是业务语义的一部分 | -| `busy_timeout` | 5s | 单写者下的排队上限 | -| `auto_vacuum` | INCREMENTAL | 三张增长表按保留期批量删除,必须有空间回收路径;trim 任务后执行 `pragma incremental_vacuum`(§7.7)。对已存在的库,该设置在 0004 迁移后的一次 `vacuum` 时生效 | +| PostgreSQL | 元数据、配置、接入凭据、账号、事实、派生聚合 | 不可丢失,常规备份 | +| Redis | 管理会话、刷新租约、会话亲和、模型清单缓存 | 可丢失:会话重登、租约自愈、亲和退化为重新调度、缓存重拉 | + +连接参数(`infra/database.rs` / `infra/redis.rs`,全部显式): + +| 参数 | 值 | 理由 | +| --- | --- | --- | +| PG 池 `max_connections` | 10 | 自托管代理的写并发远低于此 | +| PG 池 `acquire_timeout` | 5s | 排队上限,接替 SQLite `busy_timeout` 的角色 | +| Redis 连接 | 单条多路复用连接(ConnectionManager,自动重连) | 命令全部为 O(1)/O(logN) 小操作,无需连接池 | +| Redis 键前缀 | `cpr:` | 与共用实例的其他应用隔离;测试用随机前缀隔离 | + +**明确不做**:PG 侧不用 LISTEN/NOTIFY、不用 advisory lock(互斥一律走 Redis 租约);Redis 侧不开键空间通知、不承载任何"不可丢失"数据。 --- @@ -30,183 +39,181 @@ | 对象 | 规则 | 示例 | | --- | --- | --- | -| 表名 | snake_case;实体集合复数;子表 `<父实体单数>_<内容>` | `accounts`、`account_cookies` | -| 表名后缀 | 事实 `_records`/`_logs`;聚合 `_buckets`;缓存 `_snapshots`;运行态 `_leases`/`_affinities`;审计 `_history` | `usage_records` | -| 列名 | snake_case,全库同义同名 | `account_id` 处处一致 | -| 时间戳 | `*_at`,TEXT,RFC3339 UTC | `created_at` | -| 时长 | `*_seconds` / `*_ms`,INTEGER | `latency_ms` | -| 计数 | `*_count`,INTEGER,`check >= 0` | `request_count` | -| JSON | `*_json`,TEXT | `metadata_json` | -| 布尔 | 裸形容词/过去式,INTEGER,`check in (0,1)` | `enabled` | +| 表名 | snake_case;实体集合复数;子表 `<父实体单数>_<内容>` | `accounts`、`account_cookies` | +| 表名后缀 | 事实 `_records`/`_logs`;聚合 `_buckets`;审计 `_history` | `usage_records` | +| 列名 | snake_case,全库同义同名 | `account_id` 处处一致 | +| 时间戳 | `*_at`,**timestamptz** | `created_at` | +| 时长 | `*_seconds` / `*_ms`,bigint | `latency_ms` | +| 计数 | `*_count`,bigint,`check >= 0` | `request_count` | +| JSON | `*_json`,**jsonb** | `metadata_json` | +| 布尔 | 裸形容词/过去式,**boolean** | `enabled` | | 外键/逻辑引用列 | `<被引用实体单数>_id` | `client_api_key_id` | -| 凭据哈希 | `*_hash`,明文永不落库(§2.6) | `key_hash`、`token_hash` | -| 主键 | `id`,除非自然复合键或哈希键 | — | +| 凭据哈希 | `*_hash`,明文永不落库(§2.6) | `key_hash`、`token_hash` | +| 主键 | `id`,除非自然复合键或哈希键 | — | | 普通/唯一索引 | `idx_<表>_<列摘要>` / `ux_<表>_<列摘要>` | `ux_accounts_chatgpt_identity` | | 双端状态码 | 视角前缀 | `status_code` / `client_status_code` / `upstream_status_code` | | 模型归因 | 来源前缀 | `model` / `requested_model` / `upstream_model` | +| Redis 键 | `cpr:<域>:<实体>:<键值>`,冒号分层 | `cpr:lease:refresh:` | ### 2.2 类型 -只用两种存储类型表达业务数据: - -| 用途 | 类型 | 约定 | +| 用途 | PG 类型 | 约定 | | --- | --- | --- | -| ID、名称、枚举、时间戳、JSON、哈希 | TEXT | 枚举加 `check in (...)` | -| 计数、时长、布尔、状态码 | INTEGER | 计数 `>= 0`;布尔 `in (0,1)` | +| ID、名称、枚举、哈希 | text | 枚举加 `check in (...)` | +| 时间戳 | timestamptz | 库内一律 UTC 时刻 | +| 计数、时长 | bigint | 计数 `>= 0` | +| 状态码 | integer | `between` check | +| 布尔 | boolean | — | +| 快照/模板/调试 JSON | jsonb | 见 §2.7 | -**不使用 REAL,不存储金额**。成本一律查询期由 token × 单价计算(`admin/monitoring/billing.rs`):单价会变、需追溯重算,落库的浮点成本既漂移又过期。 +**枚举用 text + check,不用 PG 原生 enum**(有意修订旧文档 §8 的一句话设想):原生 enum 增删值要 `alter type` 且值永远无法删除;check 约束换一条 `drop/add constraint` 即完成枚举演进(SQLite 0002 改名先例证明枚举确实会变)。**不使用 real/double 存业务数据,不存储金额**。成本一律查询期由 token × 单价计算(`admin/monitoring/billing.rs`):单价会变、需追溯重算,落库的浮点成本既漂移又过期。 ### 2.3 时间戳 -- 库内一律 UTC,统一经 `chrono::DateTime::to_rfc3339()` 写入(`+00:00` 后缀)。RFC3339 UTC 文本的字典序 = 时间序,TEXT 时间戳因此可直接做范围查询与排序索引。 -- 时区换算(中国时区展示、15 分钟槽对齐)只在代码层(`infra/time.rs` 的 `china_*` 系列),数据库不感知时区。 -- **禁止**在同一张做范围比较的表里混用 `strftime('…Z')` 与 `to_rfc3339()`。唯一例外:`schema_migrations.applied_at` 用 `strftime`(不做范围比较)。 +- 库内一律 timestamptz;代码层统一 `chrono::DateTime` 直接绑定,**不再经 RFC3339 文本中转**。 +- RFC3339 文本只存在于两处边界:API 响应序列化、keyset 分页游标(游标文本解码回 `DateTime` 后再进 SQL,比较发生在 timestamptz 域)。 +- 时区换算(中国时区展示、15 分钟槽对齐)只在代码层(`infra/time.rs` 的 `china_*` 系列),数据库不感知时区。+08:00 是整小时偏移,15 分钟槽在 UTC 与中国时区下对齐结果相同,SQL 侧重算桶可直接 `to_timestamp(floor(extract(epoch from t) / 900) * 900)`。 ### 2.4 ID -主键一律 TEXT 随机 ID(`infra/identity.rs` 生成):无中心分配、写入前可生成、跨表无碰撞。例外:`schema_migrations.version`(天然有序整数)、`runtime_settings.id`(单例锚点)、凭据表以哈希为键(§2.6)。 +主键一律 text 随机 ID(`infra/identity.rs` 生成):无中心分配、写入前可生成、跨表无碰撞。例外:`schema_migrations.version`(天然有序整数)、`runtime_settings.id`(单例锚点)、凭据存储以哈希为键(§2.6)。**不用 serial/identity/uuid 列类型**——ID 是业务字符串,不是数据库生成物。 ### 2.5 NULL 与 sentinel -- "无值 / 未观测"一律 NULL;**禁止** 0、空字符串做哨兵。NULL 与 0 语义不同(`input_tokens` NULL = 上游未报告,0 = 确认为零)。 -- 聚合维度列不可空时,未知值用 `__unknown__`;预聚合汇总行(预留)用 `__all__`。 -- 唯一例外:`ux_accounts_chatgpt_identity` 的索引表达式 `coalesce(chatgpt_user_id, '')`——空串只存在于索引表达式,不是存储值,不构成先例。 +- "无值 / 未观测"一律 NULL;**禁止** 0、空字符串做哨兵。NULL 与 0 语义不同(`input_tokens` NULL = 上游未报告,0 = 确认为零)。 +- 聚合维度列不可空时,未知值用 `__unknown__`;预聚合汇总行(预留)用 `__all__`。 +- 唯一例外:`ux_accounts_chatgpt_identity` 的索引表达式 `coalesce(chatgpt_user_id, '')`——空串只存在于索引表达式,不是存储值,不构成先例。 -### 2.6 Secret 纪律(无例外) +### 2.6 Secret 纪律(无例外) -凡是"出示即获得权限"的值都是凭据,**明文一律不落库**: +凡是"出示即获得权限"的值都是凭据,**明文一律不落库(PG 与 Redis 同等适用)**: | 凭据 | 存储 | 哈希类型 | 理由 | | --- | --- | --- | --- | -| 管理员密码 | `admin_users.password_hash` | 慢哈希(argon2/bcrypt) | 低熵人类输入,必须抗字典攻击 | -| 客户端 API key | `client_api_keys.key_hash` | SHA-256 | 高熵随机串无字典攻击面,快哈希保住 unique 索引 O(log n) 查找;明文只在创建响应出现一次,`prefix` 供事后定位 | -| 管理端 session token | `admin_sessions.token_hash` | SHA-256 | 同上。库文件/备份泄露不再等于会话劫持 | -| 管理 API key | `runtime_settings.admin_api_key_hash` | SHA-256 | 同上;校验 = 哈希后 `ct_eq` | -| 上游 access/refresh token、Cookie value | 明文列,标记 secret | —(功能上必须可逆) | 不进日志、不进列表 API;静态加密的触发条件见 §8 | +| 管理员密码 | PG `admin_users.password_hash` | 慢哈希(argon2) | 低熵人类输入,必须抗字典攻击 | +| 客户端 API key | PG `client_api_keys.key_hash` | SHA-256 | 高熵随机串无字典攻击面,快哈希保住 unique 索引查找;明文只在创建响应出现一次,`prefix` 供事后定位 | +| 管理端 session token | Redis `cpr:admin:session:` | SHA-256 | 键即哈希。Redis RDB/AOF 或内存转储泄露不再等于会话劫持 | +| 管理 API key | PG `runtime_settings.admin_api_key_hash` | SHA-256 | 校验 = 哈希后 `ct_eq`;哈希不可脱敏展示,状态 API 只回答"是否已启用" | +| 上游 access/refresh token、Cookie value | PG 明文列,标记 secret | —(功能上必须可逆) | 不进日志、不进列表 API;静态加密的触发条件见 §8 | ### 2.7 JSON 边界 -`*_json` 列只允许三类内容:① 上游原样快照(`quota_json`、`models_json`、`manifest_json`);② 结构化模板(`default_headers_json`、`header_order_json`);③ 调试细节(`metadata_json`)。**凡进入 WHERE / GROUP BY / 告警的字段必须是一等列**;列一旦提升即为唯一可查询真相,JSON 内同名字段仅供人工排查,写入时不再往 metadata 双写已提升字段。 +`*_json` 列(jsonb)只允许三类内容:① 上游原样快照(`quota_json`、`manifest_json`);② 结构化模板(`default_headers_json`、`header_order_json`);③ 调试细节(`metadata_json`)。**凡进入 WHERE / GROUP BY / 告警的字段必须是一等列**;列一旦提升即为唯一可查询真相,写入时不再往 metadata 双写已提升字段,查询路径禁止出现 `->>` 聚合。 ### 2.8 索引 -1. 每个索引对应一条真实查询;unique 约束已覆盖的等值查找不再建索引。 -2. 列表分页统一 keyset 模式,配 `(排序时间 desc, id desc)` 复合索引。 +1. 每个索引对应一条真实查询;unique 约束已覆盖的等值查找不再建索引。 +2. 列表分页统一 keyset 模式,配 `(排序时间 desc, id desc)` 复合索引。 3. 可空列上的筛选索引一律部分索引 `where is not null`。 -4. FK 子表必须有以 FK 列开头的索引(SQLite 级联删除在子表无索引时对父表每行全扫)。免除条件必须注明(如 `admin_sessions`:行数个位数)。 -5. 高频写入表的索引总数进 code review,新增需说明查询来源。 +4. FK 子表必须有以 FK 列开头的索引(PG 级联删除同样会在子表无索引时全扫)。免除条件必须注明。 +5. 高频写入表的索引总数进 code review,新增需说明查询来源。 -### 2.9 保留与可重建性(诚实边界) +### 2.9 Redis 纪律 -| 表 | 保留 | 配置 | +1. **每个键有确定的过期路径**:TTL(会话、租约、亲和)或"最新态覆盖"(缓存 HASH)。禁止只增不减的键空间。 +2. **可丢弃性是准入条件**:FLUSHALL 之后系统必须无数据损失地继续运行(会话重登、租约重竞争、亲和退化为普通调度、缓存重拉)。不满足即不属于 Redis。 +3. **互斥必须原子**:获取用 `SET NX PX`,续约/释放用 Lua 比较 owner 后操作,禁止 GET-判断-SET 三段式。 +4. 二级索引(亲和的 conversation ZSET / account SET)由写入方维护,读取方容忍成员悬垂(主键已过期),遇悬垂惰性清理。 +5. 值统一 JSON 文本;不用 Redis Hash 拆业务对象字段(整读整写,无字段级更新需求)。 + +### 2.10 保留与可重建性(诚实边界) + +| 数据 | 保留 | 配置/机制 | | --- | --- | --- | -| `usage_records` | 30 天(默认) | `runtime_settings.usage_retention_days` | -| `ops_error_logs` | 30 天(默认) | `runtime_settings.ops_error_retention_days` | -| `request_time_buckets` | 90 天(默认) | `runtime_settings.bucket_retention_days` | -| `admin_sessions` / `account_cookies` / `session_affinities` | 按 `expires_at` 清理 | 定时任务 | -| 其余 | 常量级增长 | — | +| `usage_records` | 30 天(默认) | `runtime_settings.usage_retention_days`,周期 trim 任务 | +| `ops_error_logs` | 30 天(默认) | `runtime_settings.ops_error_retention_days`,同上 | +| `request_time_buckets` | 90 天(默认) | `runtime_settings.bucket_retention_days`,同上 | +| `account_cookies` | 按 `expires_at` 清理 | 周期任务(PG) | +| Redis 会话/租约/亲和 | TTL 自然过期 | 无清理任务 | +| 其余 PG 表 | 常量级增长 | — | -**可重建性以事实保留期为界,不夸大**: - -- `request_time_buckets` 在事实保留期内可由两张事实表重算(`rebuild-derived` 命令,§7.6);超出事实保留期的桶是**因事实过期而升格的一级数据**,写入纪律 + 同事务写入(§5.2)是它们的唯一保障。 -- `account_usage` / `account_model_usage` 的累计列**不可重建**(事实早已过期),同样只受事务保护。文档不再声称"一切派生皆可重算"。 -- `window_*` 列是运行态(窗口边界来自上游),不可重建,可丢弃。 +- trim 是**周期后台任务**(每轮读 `runtime_settings` 三列),不再在每次写入后内联执行——v3 的"每写一次 delete 一次"是已知的写放大缺陷,终态修复。 +- `request_time_buckets` 在事实保留期内可由两张事实表重算(`rebuild-buckets` 命令,§7);超出事实保留期的桶是**因事实过期而升格的一级数据**,写入纪律 + 同事务写入(§5.2)是它们的唯一保障。 +- `account_usage` / `account_model_usage` 的累计列**不可重建**(事实早已过期),同样只受写入纪律保护。本文档不声称"一切派生皆可重算"。 +- `window_*` 列是运行态(窗口边界来自上游),不可重建,可丢弃。 --- ## 3. 架构分层与关系 ```text -┌─ 元数据 ──────────────────────────────────────────────┐ -│ schema_migrations │ -├─ 配置 ────────────────────────────────────────────────┤ -│ runtime_settings(单例热配置) │ -├─ 接入 ────────────────────────────────────────────────┤ -│ admin_users · admin_sessions · client_api_keys │ -├─ 账号 ────────────────────────────────────────────────┤ -│ accounts · account_cookies · fingerprints │ -│ fingerprint_update_history · model_plan_snapshots │ -├─ 事实(不可替代的业务事件)────────────────────────────┤ -│ usage_records(成功) · ops_error_logs(失败/运维) │ -├─ 派生(口径见 §2.9)──────────────────────────────────┤ -│ request_time_buckets · account_usage │ -│ account_model_usage │ -└─ 运行态(临时协调,可丢弃)───────────────────────────┤ - session_affinities · account_refresh_leases │ +┌─ PostgreSQL ──────────────────────────────────────────┐ +│ ┌─ 元数据 ────────────────────────────────────────┐ │ +│ │ schema_migrations │ │ +│ ├─ 配置 ──────────────────────────────────────────┤ │ +│ │ runtime_settings(单例热配置) │ │ +│ ├─ 接入 ──────────────────────────────────────────┤ │ +│ │ admin_users · client_api_keys │ │ +│ ├─ 账号 ──────────────────────────────────────────┤ │ +│ │ accounts · account_cookies · fingerprints │ │ +│ │ fingerprint_update_history │ │ +│ ├─ 事实(不可替代的业务事件)──────────────────────┤ │ +│ │ usage_records(成功) · ops_error_logs(失败) │ │ +│ └─ 派生(口径见 §2.10)──────────────────────────┘ │ +│ request_time_buckets · account_usage │ +│ account_model_usage │ +└─────────────────────────────────────────────────────┘ +┌─ Redis(运行态/缓存,可丢弃)─────────────────────────┐ +│ cpr:admin:session:* 管理端会话(TTL) │ +│ cpr:lease:refresh:* token 刷新互斥租约(TTL) │ +│ cpr:affinity:* 会话亲和 + 二级索引(TTL) │ +│ cpr:models:plan_snapshots 套餐→模型清单缓存(HASH) │ +└─────────────────────────────────────────────────────┘ ``` ```text -admin_users 1──< admin_sessions FK cascade(索引免除:行数个位数) -accounts 1──1 account_usage FK cascade(PK=FK) -accounts 1──1 account_refresh_leases FK cascade(PK=FK) -accounts 1──< account_model_usage FK cascade(复合 PK 前缀) -accounts 1──< account_cookies FK cascade(account_domain 前缀) -accounts 1──< session_affinities FK cascade(idx_…_account) -fingerprints 1──< fingerprint_update_history FK cascade(idx_…_fingerprint) +accounts 1──1 account_usage FK cascade(PK=FK) +accounts 1──< account_model_usage FK cascade(复合 PK 前缀) +accounts 1──< account_cookies FK cascade(account_domain 前缀) +fingerprints 1──< fingerprint_update_history FK cascade(idx_…_fingerprint) -usage_records.{account_id, client_api_key_id} → 逻辑引用,无 FK -ops_error_logs.{account_id, client_api_key_id} → 逻辑引用,无 FK -request_time_buckets.account_id → 逻辑维度,无 FK +usage_records.{account_id, client_api_key_id} → 逻辑引用,无 FK +ops_error_logs.{account_id, client_api_key_id} → 逻辑引用,无 FK +request_time_buckets.account_id → 逻辑维度,无 FK + +Redis 亲和.account_id → 账号删除时经 cpr:affinity:account: 索引显式清理(§4B.3) +Redis 租约.account_id → 不清理,TTL(分钟级)自然过期 ``` -**事实表/聚合表不建 FK 是有意为之**:审计事实的生命周期必须独立于账号与 key——删除账号或 key 不得抹掉历史用量和错误记录。运行态表相反:账号没了亲和/租约就失去意义,级联删除是正确语义。 +**事实表/聚合表不建 FK 是有意为之**:审计事实的生命周期必须独立于账号与 key——删除账号或 key 不得抹掉历史用量和错误记录。运行态相反:账号没了亲和/租约就失去意义,v3 的 FK 级联在 Redis 中由"显式清理(亲和)+ TTL 自愈(租约)"等价实现。 + +`admin_users` 与 Redis 会话之间不存在级联:单管理员模型下删除用户无入口;未来多管理员需要"删用户踢会话"时,增加 `cpr:admin:user_sessions:` SET 索引(§8)。 --- -## 4. 表设计(终态 DDL) +## 4. PostgreSQL 表设计(终态 DDL) + +以下 DDL 即 `infra/migrations/0001_initial.sql`(PG 基线)。PG 库从此基线全新建立;历史数据经导入命令进入(§6),不存在 SQLite → PG 的迁移链。 ### 4.1 schema_migrations -迁移版本的唯一事实来源。由 `database.rs` 建库时创建,不走迁移文件。只增不改;已发布迁移永不修改;`CURRENT_SCHEMA_VERSION` 与迁移列表同步提交。 +迁移版本的唯一事实来源。由 `database.rs` 建库时创建,不走迁移文件。只增不改;已发布迁移永不修改;`CURRENT_SCHEMA_VERSION` 与迁移列表同步提交。PG 谱系从 1 重新编号,与 SQLite 谱系(止于 3)无延续关系。 ```sql create table schema_migrations ( - version integer not null check (version > 0), + version bigint not null check (version > 0), name text not null, - applied_at text not null, + applied_at timestamptz not null default now(), primary key (version) ); ``` ### 4.2 admin_users -单管理员模型的登录凭据。不预建 `username`/`email`/`role` 死列;多管理员的扩展路径见 §8。 +单管理员模型的登录凭据。不预建 `username`/`email`/`role` 死列;多管理员的扩展路径见 §8。会话不在 PG(§4B.1)。 ```sql create table admin_users ( id text primary key, password_hash text not null, - created_at text not null, - updated_at text not null + created_at timestamptz not null, + updated_at timestamptz not null ); ``` -### 4.3 admin_sessions +### 4.3 client_api_keys -管理端会话的服务端状态。session 存库(而非 JWT)使"登出即失效、改密码踢会话、重启不掉线"都是一条 SQL。 - -```sql -create table admin_sessions ( - token_hash text primary key, - user_id text not null references admin_users(id) on delete cascade, - expires_at text not null, - created_at text not null -); - -create index idx_admin_sessions_expires on admin_sessions(expires_at); -``` - -| 字段 | 说明 | -| --- | --- | -| `token_hash` | `SHA-256(session token)`。客户端持有明文 token,鉴权时哈希后按 PK 等值查找。**明文 token 不落库**(§2.6) | -| `user_id` | FK cascade,删用户即踢会话 | -| `expires_at` | 鉴权比较 + 清理任务扫描(`idx_admin_sessions_expires`) | - -`user_id` 不建索引是注明的免除:单管理员下行数个位数。IP/UA 审计不进本表;需要时新建 `admin_login_events`。 - -### 4.4 client_api_keys - -客户端调用 `/v1/*` 的凭据。key 与上游账号解耦,客户端不感知账号池。 +客户端调用 `/v1/*` 的凭据。key 与上游账号解耦,客户端不感知账号池。 ```sql create table client_api_keys ( @@ -215,9 +222,9 @@ create table client_api_keys ( prefix text not null, key_hash text not null unique, label text, - enabled integer not null default 1 check (enabled in (0, 1)), - created_at text not null, - last_used_at text + enabled boolean not null default true, + created_at timestamptz not null, + last_used_at timestamptz ); create index idx_client_api_keys_created_id on client_api_keys(created_at desc, id desc); @@ -225,47 +232,47 @@ create index idx_client_api_keys_created_id on client_api_keys(created_at desc, | 字段 | 说明 | | --- | --- | -| `id` | 稳定标识;管理操作与事实归因(`usage_records.client_api_key_id`)都引用 id,key 轮换不影响引用 | -| `name` / `label` | `name` 必填主展示,`label` 可选注记 | -| `prefix` | 明文前几位(`sk-abc1…`),明文销毁后定位 key 的唯一手段 | -| `key_hash` | `SHA-256(key)`,unique 索引即鉴权查找路径。明文只在创建响应出现一次,**管理端列表 API 永不回显完整 key** | -| `enabled` | 软开关;刻意不建索引(低基数布尔) | -| `last_used_at` | 鉴权成功后异步更新,不在请求关键路径强一致 | +| `id` | 稳定标识;管理操作与事实归因(`usage_records.client_api_key_id`)都引用 id,key 轮换不影响引用 | +| `name` / `label` | `name` 必填主展示,`label` 可选注记 | +| `prefix` | 明文前几位(`sk_abc1…`),明文销毁后定位 key 的唯一手段 | +| `key_hash` | `SHA-256(key)` hex,unique 索引即鉴权查找路径。明文只在创建响应出现一次,**管理端列表 API 永不回显完整 key** | +| `enabled` | 软开关;刻意不建索引(低基数布尔) | +| `last_used_at` | 鉴权成功后延迟批量更新(1s 去抖),不在请求关键路径强一致 | -每 key 配额/限流不进本表——未来 `client_api_key_policies` 附属表(§8),归因数据已由事实表的 `client_api_key_id` 备好。 +**鉴权路径**:`SHA-256(来键)` → `where key_hash = $1 and enabled` 单点查询,**删除进程内明文鉴权表**——单一代码路径、禁用即刻生效、无缓存同步逻辑;一次 unique 索引点查的代价可忽略。每 key 配额/限流不进本表(§8)。 -### 4.5 runtime_settings +### 4.4 runtime_settings -热更新全局配置,单行表,`check (id = 1)` 约束层面保证单例。选宽表不选 KV:列级类型与 check 是 KV 给不了的;加配置要加列,恰好强迫走迁移评审。只放小型标量配置,禁塞大 JSON 状态。 +热更新全局配置,单行表,`check (id = 1)` 约束层面保证单例。选宽表不选 KV:列级类型与 check 是 KV 给不了的;加配置要加列,恰好强迫走迁移评审。只放小型标量配置,禁塞大 JSON 状态。 ```sql create table runtime_settings ( - id integer primary key check (id = 1), - model_aliases_json text not null default '{}', - refresh_margin_seconds integer not null check (refresh_margin_seconds > 0), - refresh_concurrency integer not null check (refresh_concurrency > 0), - max_concurrent_per_account integer not null check (max_concurrent_per_account > 0), - request_interval_ms integer not null check (request_interval_ms >= 0), + id bigint primary key check (id = 1), + model_aliases_json jsonb not null default '{}', + refresh_margin_seconds bigint not null check (refresh_margin_seconds > 0), + refresh_concurrency bigint not null check (refresh_concurrency > 0), + max_concurrent_per_account bigint not null check (max_concurrent_per_account > 0), + request_interval_ms bigint not null check (request_interval_ms >= 0), rotation_strategy text not null check (rotation_strategy in ('smart', 'quota_reset_priority', 'round_robin', 'sticky')), admin_api_key_hash text, - usage_retention_days integer not null default 30 check (usage_retention_days > 0), - ops_error_retention_days integer not null default 30 check (ops_error_retention_days > 0), - bucket_retention_days integer not null default 90 check (bucket_retention_days > 0), - updated_at text not null + usage_retention_days bigint not null default 30 check (usage_retention_days > 0), + ops_error_retention_days bigint not null default 30 check (ops_error_retention_days > 0), + bucket_retention_days bigint not null default 90 check (bucket_retention_days > 0), + updated_at timestamptz not null ); ``` | 字段 | 说明 | | --- | --- | -| `model_aliases_json` | 客户端模型名 → 上游模型名映射。JSON 合规:整体读写、不按别名查询 | +| `model_aliases_json` | 客户端模型名 → 上游模型名映射。JSON 合规:整体读写、不按别名查询 | | `refresh_*` / `max_concurrent_per_account` / `request_interval_ms` | 刷新与调度参数 | -| `rotation_strategy` | 枚举 check;枚举值变更必须走迁移(0002 先例),库内无死值 | -| `admin_api_key_hash` | 管理 API 机器凭据的 SHA-256。NULL = 未启用。校验 = 对来键哈希后 `ct_eq` 比较 | -| `*_retention_days` 三列 | 三张增长表各自独立的保留天数。bucket 默认更长:趋势比明细有更长查询价值 | +| `rotation_strategy` | 枚举 check;枚举值变更必须走迁移(SQLite 0002 先例),库内无死值 | +| `admin_api_key_hash` | 管理 API 机器凭据的 SHA-256。NULL = 未启用。校验 = 对来键哈希后 `ct_eq`。哈希不可脱敏,状态 API 只回答存在性 | +| `*_retention_days` 三列 | 三张增长表各自独立的保留天数,trim 任务每轮读取。bucket 默认更长:趋势比明细有更长查询价值 | -### 4.6 accounts +### 4.5 accounts -上游账号的身份、凭据、调度状态与 quota 快照。**保持单表是当前正确决策**:调度器每次决策同时读身份+状态+冷却,拆表只增加 join 与事务面;拆分触发条件明确(§8)。 +上游账号的身份、凭据、调度状态与 quota 快照。**保持单表是当前正确决策**:调度器每次决策同时读身份+状态+冷却,拆表只增加 join 与事务面;拆分触发条件明确(§8)。 ```sql create table accounts ( @@ -277,17 +284,17 @@ create table accounts ( plan_type text, access_token text not null, refresh_token text, - access_token_expires_at text, - next_refresh_at text, + access_token_expires_at timestamptz, + next_refresh_at timestamptz, status text not null check (status in ('active', 'expired', 'quota_exhausted', 'disabled', 'banned')), - quota_json text, - quota_fetched_at text, - quota_limit_reached integer not null default 0 check (quota_limit_reached in (0, 1)), - quota_verify_required integer not null default 0 check (quota_verify_required in (0, 1)), - quota_cooldown_until text, - cloudflare_cooldown_until text, - added_at text not null, - updated_at text not null + quota_json jsonb, + quota_fetched_at timestamptz, + quota_limit_reached boolean not null default false, + quota_verify_required boolean not null default false, + quota_cooldown_until timestamptz, + cloudflare_cooldown_until timestamptz, + added_at timestamptz not null, + updated_at timestamptz not null ); create index idx_accounts_status on accounts(status); @@ -297,60 +304,44 @@ create unique index ux_accounts_chatgpt_identity where chatgpt_account_id is not null; ``` -要点: +要点: -- **身份**:`id` 与上游 ID 解耦(导入半成品账号仍可运转);`chatgpt_account_id` + `chatgpt_user_id` 复合唯一防重复导入,身份未知的账号不参与去重(部分索引)。`plan_type` 不加枚举 check:取值由上游定义。 -- **凭据(secret)**:`access_token` not null 是账号存在的最低要求;`refresh_token` NULL = 不可续期,到期即 `expired`。不进日志、不进列表 API。 -- **状态**:单列业务状态机 + 布尔/冷却补充列,避免状态爆炸。`refreshing` 不落 `accounts.status`,由 `account_refresh_leases` / 进程内 in-flight 派生为运行时展示态。冷却用时间而非布尔:自然过期无需回写。quota 与 CF 冷却分列:成因、时长、解除策略都不同。 -- **快照**:`quota_json` 上游原样快照(JSON 合规);`added_at` 语义化命名——账号是"被添加进池子"的。 +- **身份**:`id` 与上游 ID 解耦(导入半成品账号仍可运转);`chatgpt_account_id` + `chatgpt_user_id` 复合唯一防重复导入,身份未知的账号不参与去重(部分索引)。`plan_type` 不加枚举 check:取值由上游定义。 +- **凭据(secret)**:`access_token` not null 是账号存在的最低要求;`refresh_token` NULL = 不可续期,到期即 `expired`。不进日志、不进列表 API。 +- **状态**:单列业务状态机 + 布尔/冷却补充列,避免状态爆炸。`refreshing` 不落 `accounts.status`,由 Redis 刷新租约 / 进程内 in-flight 派生为运行时展示态。冷却用时间而非布尔:自然过期无需回写。quota 与 CF 冷却分列:成因、时长、解除策略都不同。 +- **快照**:`quota_json` 上游原样快照(JSON 合规);`added_at` 语义化命名——账号是"被添加进池子"的。 +- 池加载顺序 = `added_at asc, id asc`(替代 SQLite 隐式 rowid 序,语义相同且跨引擎稳定)。 -### 4.7 account_refresh_leases +### 4.6 account_usage -token 刷新互斥租约。租约(owner + 到期)是最小充分的互斥原语:持有者崩溃后自然失效,无需显式释放;天然支持未来多实例竞争。运行态表,不承载历史(需要时另建 `account_refresh_events`)。 - -```sql -create table account_refresh_leases ( - account_id text primary key references accounts(id) on delete cascade, - owner text not null, - expires_at text not null, - updated_at text not null -); - -create index idx_account_refresh_leases_expires on account_refresh_leases(expires_at); -``` - -PK=FK 的 1:1 建模把"每账号至多一个持有者"变成主键约束。`owner` 在续约/释放时校验,防误释放他人租约。 - -### 4.8 account_usage - -账号维度两组计数:① 生命周期累计(列表展示,**不可重建**,§2.9);② 当前 quota 窗口计数(调度限流输入,运行态)。1:1 派生表,不与 accounts 合并:更新频率差多个数量级,合表会让高频计数写污染低频实体行。 +账号维度两组计数:① 生命周期累计(列表展示,**不可重建**,§2.10);② 当前 quota 窗口计数(调度限流输入,运行态)。1:1 派生表,不与 accounts 合并:更新频率差多个数量级,合表会让高频计数写污染低频实体行。 ```sql create table account_usage ( account_id text primary key references accounts(id) on delete cascade, - request_count integer not null default 0 check (request_count >= 0), - empty_response_count integer not null default 0 check (empty_response_count >= 0), - input_tokens integer not null default 0 check (input_tokens >= 0), - output_tokens integer not null default 0 check (output_tokens >= 0), - cached_tokens integer not null default 0 check (cached_tokens >= 0), - reasoning_tokens integer not null default 0 check (reasoning_tokens >= 0), - total_tokens integer not null default 0 check (total_tokens >= 0), - image_input_tokens integer not null default 0 check (image_input_tokens >= 0), - image_output_tokens integer not null default 0 check (image_output_tokens >= 0), - image_request_count integer not null default 0 check (image_request_count >= 0), - image_request_failed_count integer not null default 0 check (image_request_failed_count >= 0), - window_request_count integer not null default 0 check (window_request_count >= 0), - window_input_tokens integer not null default 0 check (window_input_tokens >= 0), - window_output_tokens integer not null default 0 check (window_output_tokens >= 0), - window_cached_tokens integer not null default 0 check (window_cached_tokens >= 0), - window_image_input_tokens integer not null default 0 check (window_image_input_tokens >= 0), - window_image_output_tokens integer not null default 0 check (window_image_output_tokens >= 0), - window_image_request_count integer not null default 0 check (window_image_request_count >= 0), - window_image_request_failed_count integer not null default 0 check (window_image_request_failed_count >= 0), - window_started_at text, - window_reset_at text, - limit_window_seconds integer check (limit_window_seconds is null or limit_window_seconds > 0), - last_used_at text + request_count bigint not null default 0 check (request_count >= 0), + empty_response_count bigint not null default 0 check (empty_response_count >= 0), + input_tokens bigint not null default 0 check (input_tokens >= 0), + output_tokens bigint not null default 0 check (output_tokens >= 0), + cached_tokens bigint not null default 0 check (cached_tokens >= 0), + reasoning_tokens bigint not null default 0 check (reasoning_tokens >= 0), + total_tokens bigint not null default 0 check (total_tokens >= 0), + image_input_tokens bigint not null default 0 check (image_input_tokens >= 0), + image_output_tokens bigint not null default 0 check (image_output_tokens >= 0), + image_request_count bigint not null default 0 check (image_request_count >= 0), + image_request_failed_count bigint not null default 0 check (image_request_failed_count >= 0), + window_request_count bigint not null default 0 check (window_request_count >= 0), + window_input_tokens bigint not null default 0 check (window_input_tokens >= 0), + window_output_tokens bigint not null default 0 check (window_output_tokens >= 0), + window_cached_tokens bigint not null default 0 check (window_cached_tokens >= 0), + window_image_input_tokens bigint not null default 0 check (window_image_input_tokens >= 0), + window_image_output_tokens bigint not null default 0 check (window_image_output_tokens >= 0), + window_image_request_count bigint not null default 0 check (window_image_request_count >= 0), + window_image_request_failed_count bigint not null default 0 check (window_image_request_failed_count >= 0), + window_started_at timestamptz, + window_reset_at timestamptz, + limit_window_seconds bigint check (limit_window_seconds is null or limit_window_seconds > 0), + last_used_at timestamptz ); create index idx_account_usage_last_used_account @@ -359,26 +350,26 @@ create index idx_account_usage_last_used_account | 组 | 说明 | | --- | --- | -| 累计 | 口径 = usage_records 成功事实;失败率不得由本表推断。`total_tokens` 是已知的"有偿冗余"(列表排序高频),与分量列同一 upsert 内更新,事务保证一致 | -| 窗口 | 当前 quota 窗口内计数,窗口重置清零。**窗口组刻意不含 `reasoning_tokens`/`total_tokens`**:窗口列只镜像上游 quota 核算维度,reasoning 不参与上游窗口计数;累计组是展示口径,两组不对称是设计而非遗漏 | -| 边界 | `window_started_at` / `window_reset_at` / `limit_window_seconds` 来自上游 rate-limit 响应,NULL = 未知 | +| 累计 | 口径 = usage_records 成功事实;失败率不得由本表推断。`total_tokens` 是已知的"有偿冗余"(列表排序高频),与分量列同一 upsert 内更新 | +| 窗口 | 当前 quota 窗口内计数,窗口重置清零。**窗口组刻意不含 `reasoning_tokens`/`total_tokens`**:窗口列只镜像上游 quota 核算维度,累计组是展示口径,两组不对称是设计而非遗漏 | +| 边界 | `window_started_at` / `window_reset_at` / `limit_window_seconds` 来自上游 rate-limit 响应,NULL = 未知 | -宽表(20 计数列)而非 EAV `(account_id, metric, value)`:计数种类是代码常量,宽表一次 upsert 全更新、check 逐列可写;EAV 只换来动态 SQL 和类型丢失。 +宽表(20 计数列)而非 EAV:计数种类是代码常量,宽表一次 upsert 全更新、check 逐列可写;EAV 只换来动态 SQL 和类型丢失。 -### 4.9 account_model_usage +### 4.7 account_model_usage -账号 × 模型分布,服务账号详情页与调度辅助。自然复合键,不引入代理 id。 +账号 × 模型分布,服务账号详情页与调度辅助。自然复合键,不引入代理 id。 ```sql create table account_model_usage ( account_id text not null references accounts(id) on delete cascade, model text not null, - request_count integer not null default 0 check (request_count >= 0), - error_count integer not null default 0 check (error_count >= 0), - input_tokens integer not null default 0 check (input_tokens >= 0), - output_tokens integer not null default 0 check (output_tokens >= 0), - cached_tokens integer not null default 0 check (cached_tokens >= 0), - last_used_at text, + request_count bigint not null default 0 check (request_count >= 0), + error_count bigint not null default 0 check (error_count >= 0), + input_tokens bigint not null default 0 check (input_tokens >= 0), + output_tokens bigint not null default 0 check (output_tokens >= 0), + cached_tokens bigint not null default 0 check (cached_tokens >= 0), + last_used_at timestamptz, primary key (account_id, model) ); @@ -386,11 +377,11 @@ create index idx_account_model_usage_last_used on account_model_usage(last_used_at desc, account_id, model); ``` -`error_count` 是**收窄口径**:仅统计已归属到账号+模型之后的失败,用作调度回避信号(频繁失败 → 降权)。这是全库唯一允许的口径重叠(与 ops_error_logs),因为用途不同(调度局部信号 vs 全局错误事实);Dashboard 错误率禁止取自本列。 +`error_count` 是**收窄口径**:仅统计已归属到账号+模型之后的失败,用作调度回避信号(频繁失败 → 降权)。这是全库唯一允许的口径重叠(与 ops_error_logs),因为用途不同(调度局部信号 vs 全局错误事实);Dashboard 错误率禁止取自本列。 -### 4.10 usage_records ★ +### 4.8 usage_records ★ -**每个成功的客户端请求恰好一行**。用量、token、成本、账号与调用方归因的唯一事实来源。这是系统的账本;"只收成功"的边界由 DB 约束兜底,不再只靠 service 层。 +**每个成功的客户端请求恰好一行**。用量、token、成本、账号与调用方归因的唯一事实来源。这是系统的账本;"只收成功"的边界由 DB 约束兜底,不再只靠 service 层。 ```sql create table usage_records ( @@ -407,18 +398,18 @@ create table usage_records ( service_tier text, status_code integer not null check (status_code between 200 and 399), transport text, - attempt_index integer check (attempt_index is null or attempt_index >= 0), + attempt_index bigint check (attempt_index is null or attempt_index >= 0), response_id text, upstream_request_id text, - latency_ms integer check (latency_ms is null or latency_ms >= 0), - first_token_ms integer check (first_token_ms is null or first_token_ms >= 0), - input_tokens integer check (input_tokens is null or input_tokens >= 0), - output_tokens integer check (output_tokens is null or output_tokens >= 0), - cached_tokens integer check (cached_tokens is null or cached_tokens >= 0), - reasoning_tokens integer check (reasoning_tokens is null or reasoning_tokens >= 0), + latency_ms bigint check (latency_ms is null or latency_ms >= 0), + first_token_ms bigint check (first_token_ms is null or first_token_ms >= 0), + input_tokens bigint check (input_tokens is null or input_tokens >= 0), + output_tokens bigint check (output_tokens is null or output_tokens >= 0), + cached_tokens bigint check (cached_tokens is null or cached_tokens >= 0), + reasoning_tokens bigint check (reasoning_tokens is null or reasoning_tokens >= 0), message text not null, - metadata_json text not null, - created_at text not null + metadata_json jsonb not null, + created_at timestamptz not null ); create index idx_usage_records_created_id on usage_records(created_at desc, id desc); @@ -433,27 +424,29 @@ create index idx_usage_records_upstream_request_id on usage_records(upstream_req | 字段 | 说明 | | --- | --- | -| `request_id` | 请求链路 ID,与 ops 表同域——跨两表串起一次请求的完整故事(成功前的失败尝试在 ops 表) | -| `client_api_key_id` | **调用方归因**(逻辑引用 client_api_keys.id,无 FK)。可空:管理端代发/内部探测请求无 key。归因列是事实字段,错过不可回补——按 key 用量、未来按 key 配额核算都依赖它 | -| `kind` / `route` | kind 是稳定事件族(`v1.response`),route 是原始 HTTP 事实;route 变体收敛到同一 kind,历史统计不断裂。映射只允许存在于 `event_kind()` 一处 | -| `provider` | **上游 provider 归属**(`'openai'`,规划中 `'cloudflare'`)。not null:成功请求必知上游。事实必须自包含——账号可删除、模型别名可重映射,provider 不能靠 join 推导。开放取值不加 check(SQLite 改 check 要重建大表,新 provider 只应是新增取值)。低基数列刻意不建索引 | -| `account_id` | **not null**:成功请求必有归属。无 FK(§3) | -| `model` / `requested_model` / `upstream_model` | 展示归因(计费默认)/ 客户端原始请求(别名映射前)/ 上游实际执行。三列语义互不混用 | +| `request_id` | 请求链路 ID,与 ops 表同域——跨两表串起一次请求的完整故事(成功前的失败尝试在 ops 表) | +| `client_api_key_id` | **调用方归因**(逻辑引用 client_api_keys.id,无 FK)。可空:管理端代发/内部探测请求无 key。归因列是事实字段,错过不可回补——按 key 用量、未来按 key 配额核算都依赖它 | +| `kind` / `route` | kind 是稳定事件族(`v1.response`),route 是原始 HTTP 事实;route 变体收敛到同一 kind,历史统计不断裂。映射只允许存在于 `event_kind()` 一处 | +| `provider` | **上游 provider 归属**(`'openai'`,规划中 `'cloudflare'`)。not null:成功请求必知上游。事实必须自包含——账号可删除、模型别名可重映射,provider 不能靠 join 推导。开放取值不加 check(新 provider 只应是新增取值)。低基数列刻意不建索引 | +| `account_id` | **not null**:成功请求必有归属。无 FK(§3) | +| `model` / `requested_model` / `upstream_model` | 展示归因(计费默认)/ 客户端原始请求(别名映射前)/ 上游实际执行。三列语义互不混用 | | `service_tier` | 计费单价第二维度 | -| `status_code` | **`between 200 and 399`**:终态响应码 + 只收成功,数据库层兜底。1xx 非终态,4xx/5xx 属 ops 表 | -| `transport` / `attempt_index` | 传输方式与成功发生在第几次尝试(>0 意味着此前有失败,记录在 ops 表) | -| `latency_ms` / `first_token_ms` | 端到端完成延迟 / 首 token 延迟。NULL = 未测得,区别于 0 | -| `input/output/cached/reasoning_tokens` | 一等列(§2.7)。NULL = 上游未报告,与 0 语义不同——因此不用 `not null default 0` | -| `message` | 一行人类可读摘要,必须脱敏 | -| `metadata_json` | 仅调试细节;已提升为列的字段不再写入 metadata | +| `status_code` | **`between 200 and 399`**:终态响应码 + 只收成功,数据库层兜底。1xx 非终态,4xx/5xx 属 ops 表 | +| `transport` / `attempt_index` | 传输方式与成功发生在第几次尝试(>0 意味着此前有失败,记录在 ops 表) | +| `latency_ms` / `first_token_ms` | 端到端完成延迟 / 首 token 延迟。NULL = 未测得,区别于 0 | +| `input/output/cached/reasoning_tokens` | 一等列(§2.7)。NULL = 上游未报告,与 0 语义不同——因此不用 `not null default 0` | +| `message` | 一行人类可读摘要,必须脱敏 | +| `metadata_json` | 仅调试细节;已提升为列的字段不再写入 metadata | -8 个索引全部对应真实查询:keyset 分页 / 链路排查 / 事件族过滤 / 账号维度 / 模型维度 / 调用方维度 / response 续写排查 / 上游报障对账。每行 8 索引是全库最高写放大,是明细可查性的直接代价;量级失控的出路是缩短保留期(配置已就位),不是删索引。 +8 个索引全部对应真实查询:keyset 分页 / 链路排查 / 事件族过滤 / 账号维度 / 模型维度 / 调用方维度 / response 续写排查 / 上游报障对账。每行 8 索引是全库最高写放大,是明细可查性的直接代价;量级失控的出路是缩短保留期(配置已就位),不是删索引。 -**禁止**:写入失败事件;token 写回 metadata 当真相;加任何兼容过滤查询历史数据。 +**搜索边界**:列表 API 的 `search` 参数只匹配 `message ilike` 与 request_id/response_id 精确等值;**禁止**对 `metadata_json` 做任何 contains 扫描——metadata 是调试细节,不是查询面。 -### 4.11 ops_error_logs ★ +**禁止**:写入失败事件;token 写回 metadata 当真相;加任何兼容过滤查询历史数据。 -**每个失败请求/运维错误恰好一行**。与 usage_records 互斥:一次请求终态只进一张表。失败与成功的查询维度完全不同(阶段/分类/归责 vs token/成本),拆表让两边 schema 各自朝自己的查询模型演进。 +### 4.9 ops_error_logs ★ + +**每个失败请求/运维错误恰好一行**。与 usage_records 互斥:一次请求终态只进一张表。失败与成功的查询维度完全不同(阶段/分类/归责 vs token/成本),拆表让两边 schema 各自朝自己的查询模型演进。 ```sql create table ops_error_logs ( @@ -469,14 +462,14 @@ create table ops_error_logs ( client_status_code integer check (client_status_code is null or (client_status_code between 100 and 599)), upstream_status_code integer check (upstream_status_code is null or (upstream_status_code between 100 and 599)), transport text, - attempt_index integer check (attempt_index is null or attempt_index >= 0), + attempt_index bigint check (attempt_index is null or attempt_index >= 0), failure_class text, response_id text, upstream_request_id text, - latency_ms integer check (latency_ms is null or latency_ms >= 0), + latency_ms bigint check (latency_ms is null or latency_ms >= 0), message text not null, - metadata_json text not null, - created_at text not null + metadata_json jsonb not null, + created_at timestamptz not null ); create index idx_ops_error_logs_created_id on ops_error_logs(created_at desc, id desc); @@ -494,40 +487,40 @@ create index idx_ops_error_logs_upstream_request_id on ops_error_logs(upstream_r | 字段 | 说明 | | --- | --- | -| `client_api_key_id` | 调用方归因,可空(鉴权前失败、后台任务无 key) | -| `provider` | 上游 provider 归属,可空:模型解析前失败(鉴权失败、路由失败)时上游未定。与 `account_id` 同为"失败可以不知道,成功必须知道"的口径差异 | -| `account_id` | **可空是本表的关键差异**:调度前失败(无可用账号、模型不可用)天然无归属——这正是这类事件进不了 usage_records 的原因 | -| 三视角状态码 | `status_code`(事件主视角)/ `client_status_code`(用户看到什么)/ `upstream_status_code`(上游返回什么)。错误排查的第一个问题永远是"哪一层出的错" | -| `failure_class` | 开放取值不加 check:分类法仍在演进 | -| `metadata_json` | **禁止**存长请求/响应体(capture body 开启也必须截断脱敏);**禁止**存计费 token——失败不是计费事实,将来统计失败中观测到的 token 必须用 `observed_` 前缀新列 | +| `client_api_key_id` | 调用方归因,可空(鉴权前失败、后台任务无 key) | +| `provider` | 上游 provider 归属,可空:模型解析前失败(鉴权失败、路由失败)时上游未定。与 `account_id` 同为"失败可以不知道,成功必须知道"的口径差异 | +| `account_id` | **可空是本表的关键差异**:调度前失败(无可用账号、模型不可用)天然无归属——这正是这类事件进不了 usage_records 的原因 | +| 三视角状态码 | `status_code`(事件主视角)/ `client_status_code`(用户看到什么)/ `upstream_status_code`(上游返回什么)。错误排查的第一个问题永远是"哪一层出的错" | +| `failure_class` | 开放取值不加 check:分类法仍在演进 | +| `metadata_json` | **禁止**存长请求/响应体(capture body 开启也必须截断脱敏);**禁止**存计费 token——失败不是计费事实,将来统计失败中观测到的 token 必须用 `observed_` 前缀新列 | -11 个索引全部对应错误排查的真实切片;可空维度全部部分索引;错误表写入频率远低于成功表,写放大可承受。 +错误明细的管理端查询面(`/api/admin/ops/errors`)直接读本表;成功事件列表不再混排错误行。11 个索引全部对应错误排查的真实切片;可空维度全部部分索引;错误表写入频率远低于成功表,写放大可承受。 -**预留演进列(有 UI/告警需求时增列,刻意不预建,本清单为唯一权威版本)**:`surface`(client_api/admin/system)、`error_phase`(auth/dispatch/upstream/stream/parse/internal)、`error_type`(稳定错误类型)、`severity`(P1–P3)、`requested_model` / `upstream_model` / `service_tier`、`client_ip` / `user_agent`、`error_source` / `error_owner`、`is_retryable` / `retry_count`。原则:字段跟着真实查询需求走,不照搬外部项目全集。 +**预留演进列(有 UI/告警需求时增列,刻意不预建,本清单为唯一权威版本)**:`surface`、`error_phase`、`error_type`、`severity`、`requested_model` / `upstream_model` / `service_tier`、`client_ip` / `user_agent`、`error_source` / `error_owner`、`is_retryable` / `retry_count`。原则:字段跟着真实查询需求走,不照搬外部项目全集。 -### 4.12 request_time_buckets ★ +### 4.10 request_time_buckets ★ -15 分钟 × provider × 账号 × 模型 × service_tier 预聚合,Dashboard 趋势与流量卡片的唯一数据源。**单表同时服务两种口径**:traffic(success + error)与 usage(token,仅成功)。曾有双表方案,已否决:每请求两次 upsert 的写放大不值得;分列 + 写入纪律已同时提供两种口径,rebuild 命令兜底(保留期内,§2.9)。 +15 分钟 × provider × 账号 × 模型 × service_tier 预聚合,Dashboard 趋势与流量卡片的唯一数据源。**单表同时服务两种口径**:traffic(success + error)与 usage(token,仅成功)。曾有双表方案,已否决:每请求两次 upsert 的写放大不值得;分列 + 写入纪律已同时提供两种口径,rebuild 命令兜底(保留期内,§2.10)。 ```sql create table request_time_buckets ( - bucket_start text not null, + bucket_start timestamptz not null, provider text not null default '__unknown__', account_id text not null default '__unknown__', model text not null default '__unknown__', service_tier text not null default '__unknown__', - success_count integer not null default 0 check (success_count >= 0), - error_count integer not null default 0 check (error_count >= 0), - input_tokens integer not null default 0 check (input_tokens >= 0), - output_tokens integer not null default 0 check (output_tokens >= 0), - cached_tokens integer not null default 0 check (cached_tokens >= 0), - first_token_latency_sum integer not null default 0 check (first_token_latency_sum >= 0), - first_token_latency_count integer not null default 0 check (first_token_latency_count >= 0), - latency_sum integer not null default 0 check (latency_sum >= 0), - latency_count integer not null default 0 check (latency_count >= 0), - max_latency_ms integer not null default 0 check (max_latency_ms >= 0), - min_latency_ms integer check (min_latency_ms is null or min_latency_ms >= 0), - updated_at text not null, + success_count bigint not null default 0 check (success_count >= 0), + error_count bigint not null default 0 check (error_count >= 0), + input_tokens bigint not null default 0 check (input_tokens >= 0), + output_tokens bigint not null default 0 check (output_tokens >= 0), + cached_tokens bigint not null default 0 check (cached_tokens >= 0), + first_token_latency_sum bigint not null default 0 check (first_token_latency_sum >= 0), + first_token_latency_count bigint not null default 0 check (first_token_latency_count >= 0), + latency_sum bigint not null default 0 check (latency_sum >= 0), + latency_count bigint not null default 0 check (latency_count >= 0), + max_latency_ms bigint not null default 0 check (max_latency_ms >= 0), + min_latency_ms bigint check (min_latency_ms is null or min_latency_ms >= 0), + updated_at timestamptz not null, primary key (bucket_start, provider, account_id, model, service_tier) ); @@ -536,20 +529,20 @@ create index idx_request_time_buckets_model on request_time_buckets(model, bucke | 字段 | 说明 | | --- | --- | -| `bucket_start` | UTC 时刻,按中国时区 15 分钟槽对齐(`china_quarter_hour_start`)。对齐规则只活在代码层 | -| 维度四列(provider / account_id / model / service_tier) | 不可空 + `__unknown__` sentinel(§2.5)。provider 由两条写入路径显式给值(成功/失败路径都知道自己在打哪家),`__unknown__` 仅兜底 | -| `success_count` / `error_count` | 分别由 usage / ops 写入路径 +1。**`request_count` 不落库**,恒等于两者之和,查询期推导——存储恒等式必然漂移 | -| token 三列 | **仅成功路径写入**;错误路径只 +1 `error_count`,不得触碰 token 与延迟列 | -| latency sum/count 对 | 平均值不可再聚合,sum/count 才能跨桶合并、跨维度上卷。**口径 = 仅成功**(失败延迟混入会让"变慢"和"在报错"互相污染) | -| `max_latency_ms` / `min_latency_ms` | 可单调合并的极值。min 可空:NULL = 无样本,`min()` 天然忽略 NULL。**check 是 `>= 0`**——0ms 是合法样本(缓存命中/本地短路),与 `latency_ms >= 0` 的合法域一致;`> 0` 会让 0ms 样本在同事务写入中炸掉整笔成功事实 | +| `bucket_start` | 15 分钟槽起点(UTC 槽与中国时区槽对齐结果相同,§2.3) | +| 维度四列 | 不可空 + `__unknown__` sentinel(§2.5)。provider 由两条写入路径显式给值(成功/失败路径都知道自己在打哪家),`__unknown__` 仅兜底 | +| `success_count` / `error_count` | 分别由成功/失败事务 +1。**`request_count` 不落库**,恒等于两者之和,查询期推导——存储恒等式必然漂移 | +| token 三列 | **仅成功路径写入**;错误路径只 +1 `error_count`,不得触碰 token 与延迟列 | +| latency sum/count 对 | 平均值不可再聚合,sum/count 才能跨桶合并、跨维度上卷。**口径 = 仅成功**(失败延迟混入会让"变慢"和"在报错"互相污染) | +| `max_latency_ms` / `min_latency_ms` | 可单调合并的极值(`greatest()`/`least()`)。min 可空:NULL = 无样本,`min()` 天然忽略 NULL。**check 是 `>= 0`**——0ms 是合法样本(缓存命中/本地短路),`> 0` 会让 0ms 样本在同事务写入中炸掉整笔成功事实 | -**写入事务纪律**:事实 insert 与桶 upsert 必须同事务(§5.2)。 +**写入事务纪律**:事实 insert 与桶 upsert 必须同事务(§5.2)。 -**禁止**:错误路径写 token/延迟列;落库 `request_count`;空字符串维度。 +**禁止**:错误路径写 token/延迟列;落库 `request_count`;空字符串维度。 -### 4.13 account_cookies +### 4.11 account_cookies -账号维度上游 Cookie(部分上游流程需要浏览器态凭据)。语义直接采用 RFC 6265 模型;unique 约束 = RFC 替换语义,upsert 依据。 +账号维度上游 Cookie(部分上游流程需要浏览器态凭据)。语义直接采用 RFC 6265 模型;unique 约束 = RFC 替换语义,upsert 依据。 ```sql create table account_cookies ( @@ -559,8 +552,8 @@ create table account_cookies ( name text not null, value text not null, path text not null default '/', - expires_at text, - updated_at text not null, + expires_at timestamptz, + updated_at timestamptz not null, unique(account_id, domain, name, path) ); @@ -568,11 +561,11 @@ create index idx_account_cookies_account_domain on account_cookies(account_id, d create index idx_account_cookies_expires on account_cookies(expires_at) where expires_at is not null; ``` -`value` 是 secret(§2.6)。`expires_at` NULL = 会话 Cookie,不参与清理。v3 单独的 `idx_account_cookies_account` 被 `account_domain` 前缀覆盖,终态不保留。 +`value` 是 secret(§2.6)。`expires_at` NULL = 会话 Cookie,不参与清理。**过期时间在捕获时解析为 timestamptz**(RFC2822/RFC3339 均接受,解析失败按会话 Cookie 落 NULL)——v3 存原始字符串再做字典序比较是已知缺陷,终态修复。 -### 4.14 fingerprints +### 4.12 fingerprints -设备指纹模板(UA、header 集合与顺序——顺序本身是指纹的一部分)。行数常量级、按 PK 取用,**无二级索引**。版本三元组用 TEXT:版本号不是数字(`1.2.3-beta`)。 +设备指纹模板(UA、header 集合与顺序——顺序本身是指纹的一部分)。行数常量级、按 PK 取用,**无二级索引**。版本三元组用 text:版本号不是数字(`1.2.3-beta`)。 ```sql create table fingerprints ( @@ -584,17 +577,17 @@ create table fingerprints ( arch text not null, chromium_version text not null, user_agent_template text not null, - default_headers_json text not null, - header_order_json text not null, + default_headers_json jsonb not null, + header_order_json jsonb not null, source text not null, - created_at text not null, - updated_at text not null + created_at timestamptz not null, + updated_at timestamptz not null ); ``` -### 4.15 fingerprint_update_history +### 4.13 fingerprint_update_history -指纹更新审计。版本快照列固化"当时更新到了什么"——不能只存 FK,指纹行会被后续更新覆写。级联删除可接受:指纹本体删除后其历史无独立价值。 +指纹更新审计。版本快照列固化"当时更新到了什么"——不能只存 FK,指纹行会被后续更新覆写。级联删除可接受:指纹本体删除后其历史无独立价值。 ```sql create table fingerprint_update_history ( @@ -604,8 +597,8 @@ create table fingerprint_update_history ( build_number text not null, chromium_version text, source text not null, - manifest_json text, - created_at text not null + manifest_json jsonb, + created_at timestamptz not null ); create index idx_fingerprint_update_history_created_id @@ -614,267 +607,196 @@ create index idx_fingerprint_update_history_fingerprint on fingerprint_update_history(current_fingerprint_id); ``` -### 4.16 model_plan_snapshots +--- -套餐 → 可用模型清单缓存。刻意"最新态覆盖"而非追加历史——缓存表的正确形态,可随时清空重建。**禁止**当模型目录事实表用;需要 diff/审计时新建历史表。 +## 4B. Redis 键契约(终态) -```sql -create table model_plan_snapshots ( - plan_type text primary key, - models_json text not null, - fetched_at text not null -); +运行态与缓存的唯一权威定义。所有键带 `cpr:` 前缀(测试环境随机前缀隔离)。值为 JSON 文本(§2.9)。 + +### 4B.1 管理端会话 + +```text +键 cpr:admin:session: token_hash = SHA-256(session token) hex +值 {"userId":"...","createdAt":"..."} +TTL session_ttl_minutes(创建时一次性设定) ``` -### 4.17 session_affinities +- 客户端持有明文 token(`sess_` + 256bit 随机),鉴权时哈希后 GET,存在即有效——过期由 TTL 表达,不再有 `expires_at` 比较,**清理任务消失**。 +- 登出 = DEL;"重启不掉线"由 Redis 持久化(RDB/AOF)提供;Redis 冷启丢失 = 管理员重登,可接受(§2.9)。 +- IP/UA 审计不进会话值;需要时新建 PG `admin_login_events`(§8)。 -`response_id` → 账号/会话上下文映射,保证续写请求路由回同一账号(上游 response 链只在原账号内有效)。纯运行态:全表清空只影响路由优化,不损失事实。**禁止**承载会话历史/审计。 +### 4B.2 token 刷新互斥租约 -```sql -create table session_affinities ( - response_id text primary key, - account_id text not null references accounts(id) on delete cascade, - conversation_id text not null, - turn_state text, - instructions_hash text, - input_tokens integer check (input_tokens is null or input_tokens >= 0), - function_call_ids_json text not null default '[]', - variant_hash text, - expires_at text not null, - created_at text not null -); - -create index idx_session_affinities_conversation on session_affinities(conversation_id, created_at desc); -create index idx_session_affinities_active_order on session_affinities(expires_at, created_at, response_id); -create index idx_session_affinities_account on session_affinities(account_id); +```text +键 cpr:lease:refresh: +值 owner(实例/任务标识,不透明字符串) +TTL 租约时长(acquire 时以 PX 设定) ``` -`instructions_hash` / `variant_hash` 共同约束隐式续写安全(指令或参数变了就不能隐式续写);存哈希不存原文。`active_order` 同时服务过期清理(前缀)与活跃排序;v3 单独的 `expires` 索引是其前缀,终态删除。`account` 索引是 FK 子表索引(级联删除路径)。 +- 获取:`SET key owner NX PX ttl`;失败后允许**同 owner 重入续约**(Lua:GET == owner 则 `SET PX` 刷新)。 +- 释放:Lua 比较 owner 后 DEL,防误释放他人租约。 +- 活跃租约批查(运行时展示 refreshing):`MGET` 一批键,非空即持有。 +- 持有者崩溃 → TTL 自然失效,无需清理任务。历史不承载(需要时另建 PG `account_refresh_events`)。 + +### 4B.3 会话亲和 + +```text +主键 cpr:affinity:resp: +值 {"accountId","conversationId","turnState","instructionsHash", + "inputTokens","functionCallIds":[…],"variantHash","createdAt"} +TTL 亲和 TTL(默认 4h),EXPIREAT createdAt+ttl + +索引 cpr:affinity:conv: ZSET member=response_id score=createdAt(epoch ms) +索引 cpr:affinity:account: SET member=response_id +``` + +- 写入(记录一次成功响应):MULTI 内 `SET resp EXAT` + `ZADD conv` + `EXPIRE conv ttl` + `SADD account` + `EXPIRE account ttl`,并顺手 `ZREMRANGEBYSCORE conv -inf now-ttl` 惰性剪枝。 +- 按 response_id 查:GET 主键。按 conversation 查最新:`ZREVRANGE conv` 取候选 → GET 主键过滤 variant_hash / max_age → 第一个存活者;悬垂成员(主键已过期)当场 ZREM。 +- forget(response_id):GET 后 DEL 主键 + ZREM conv + SREM account。 +- **账号删除的级联**:SMEMBERS `cpr:affinity:account:` → 逐个 forget。等价于 v3 的 FK cascade + `idx_session_affinities_account`。 +- **进程内不再维护亲和映射副本**:Redis 本身就是快存,进程内再留一份只换来双写同步与重启恢复逻辑;亲和查找相对上游请求(百 ms 级)是 <1ms 的往返,可忽略。v3 的"重启恢复"步骤随之消失。 +- **禁止**承载会话历史/审计;全部键被清空只影响路由优化,不损失事实。 + +### 4B.4 模型清单缓存 + +```text +键 cpr:models:plan_snapshots HASH field= +值 {"models":[…],"fetchedAt":"..."} +TTL 无(最新态覆盖,HSET 即替换) +``` + +缓存的正确形态,可随时清空重建(丢失 = 下次按需重拉)。**禁止**当模型目录事实表用;需要 diff/审计时新建 PG 历史表。 --- -## 5. 统计口径(全系统唯一定义) +## 5. 统计口径(全系统唯一定义) ### 5.1 口径恒等式 -任何 UI 卡片不得自创口径: +任何 UI 卡片不得自创口径: ```text -traffic: request_count = success_count + error_count ← request_time_buckets(查询期推导) -usage: token / 成本 ← usage_records 列(明细)、bucket token 列(趋势,仅成功) +traffic: request_count = success_count + error_count ← request_time_buckets(查询期推导) +usage: token / 成本 ← usage_records 列(明细)、bucket token 列(趋势,仅成功) errors: 错误分布 / 排查 ← ops_error_logs 按 key: 调用方用量 / 失败 ← usage_records / ops_error_logs 的 client_api_key_id -调度负载: account_usage / account_model_usage ← 派生累计,事务保护,不可重建(§2.9) +调度负载: account_usage / account_model_usage ← 派生累计,不可重建(§2.10) ``` ### 5.2 写入路径与事务 ```text 请求成功 ─┬─ usage_records insert - ├─ request_time_buckets upsert(success_count+1,token、延迟列) - ├─ account_usage upsert(累计 + 窗口) - └─ account_model_usage upsert - 全部在同一个事务(pool.begin() … commit) + └─ request_time_buckets upsert(success_count+1,token、延迟列) + 同一个 PG 事务(pool.begin() … commit) 请求失败 ─┬─ ops_error_logs insert - └─ request_time_buckets upsert(error_count+1,仅此一列) - 同一个事务 + └─ request_time_buckets upsert(error_count+1,仅此一列) + 同一个 PG 事务 ``` -### 5.3 Dashboard 口径决策(钉死) +`account_usage` / `account_model_usage` 的 upsert **不在**上述事务内:它们由调度器在槽位释放 / 用量观测时点独立写入(与事实写入不在同一代码时刻),每笔 upsert 自身原子。这是对旧文档"四表同事务"的**显式修订**:强行合并需要把调度器的持久化时点搬进 dispatch 事务,复杂度换不来对账收益——两边口径本就允许亚秒级漂移,对账以事实表为准。 -- 所有 traffic 卡片(今日请求、区间请求、错误率、QPS 趋势)**一律来自 request_time_buckets**,语义为"bucket 保留期内"。卡片文案如实标注区间,**不提供也不暗示"历史总量"**——bucket 有 90 天保留期,任何"total"字样都是口径谎言。 -- 生命周期累计仅有一处合法来源:`account_usage` 累计列(成功口径),使用时必须标注"成功累计"。 -- 同一张卡片禁止混排两种口径的数字(v3 的 `todayRequests` 来自 bucket、`totalRequests` 来自 usage summary 就是这个病)。 -- 真正的长期趋势需求 → 日粒度归档表 `request_day_buckets`(§8),不是延长 15 分钟桶保留期。 +### 5.3 Dashboard 口径决策(钉死) + +- 所有 traffic 卡片(今日请求、区间请求、错误率、QPS 趋势)**一律来自 request_time_buckets**,语义为"bucket 保留期内"。卡片文案如实标注区间,**不提供也不暗示"历史总量"**——bucket 有 90 天保留期,任何"total"字样都是口径谎言。 +- 生命周期累计仅有一处合法来源:`account_usage` 累计列(成功口径),使用时必须标注"成功累计"。 +- 同一张卡片禁止混排两种口径的数字(v3 的 `todayRequests` 来自 bucket、`totalRequests` 来自 usage_records 全表扫描就是这个病)。 +- 错误明细与错误分布来自 ops_error_logs;成功事件列表不再混排错误行。 +- 真正的长期趋势需求 → 日粒度归档表 `request_day_buckets`(§8),不是延长 15 分钟桶保留期。 --- -## 6. 迁移 0004:一次到位(v3 → v4) +## 6. SQLite v3 → PG 一次性搬迁 -### 6.1 前置:迁移框架支持 Rust 步骤 +引擎切换,不存在就地迁移:PG 库由 0001 基线全新建立,历史数据经**导入命令**搬入。旧文档的 0004 迁移草案(数据决策 1–4 与哈希回填)全部由导入命令吸收,SQLite 侧不再演进(v3 即其终版)。 -SQL 无法计算 SHA-256,0004 需要一个事务内的 Rust 钩子。改造 `database.rs`: +### 6.1 导入命令 -```rust -struct Migration { - version: i64, - name: &'static str, - sql: &'static str, - /// SQL 之后、同一事务内执行的 Rust 步骤(哈希回填等 SQL 做不到的事)。 - post: Option) -> BoxFuture<'_, Result<(), sqlx::Error>>>, -} +```text +codex-proxy-rs import-sqlite <旧库路径.sqlite> ``` -应用顺序不变:`raw_sql(migration.sql)` → `post`(若有)→ `record_migration`,全程同一事务。当前 `CURRENT_SCHEMA_VERSION = 3`;本节 0004 为目标迁移草案,落地时再提升版本。 +- 前置:目标 PG 为空库(仅 0001 基线,无业务行),否则拒绝执行——导入是一次性动作,不做增量合并。 +- 源库校验:`schema_migrations` 最高版本必须为 3,否则拒绝(未知谱系不猜)。 +- 全程单个 PG 事务:要么全部导入,要么全部回滚。源库只读打开。 +- Redis 不参与导入:v3 的运行态数据按 §6.3 显式丢弃。 +- 结束打印逐表行数与丢弃计数报告。 -### 6.2 0004_final_schema.sql(SQL 部分) +### 6.2 逐表规则 -```sql --- ===== admin_sessions:清空重建(哈希键) ===== --- 数据决策:现存会话全部作废,管理员重新登录。会话是运行态,无保留价值。 -drop table admin_sessions; -create table admin_sessions ( … §4.3 DDL … ); +| v3 源表 | 终态去向 | 变换 | +| --- | --- | --- | +| `admin_users` | PG 原样 | 时间戳 text→timestamptz | +| `client_api_keys` | PG | `key` 明文 → SHA-256 落 `key_hash`;明文自此不存在于任何存储 | +| `runtime_settings` | PG | `admin_api_key` 明文 → 哈希落 `admin_api_key_hash`;三个 retention 列取默认值 | +| `accounts` | PG 原样 | 布尔 0/1→boolean,时间戳→timestamptz | +| `account_usage` / `account_model_usage` | PG 原样 | 同上 | +| `account_cookies` | PG | `expires_at` 字符串解析为 timestamptz(RFC2822/RFC3339);解析失败 → NULL(降级为会话 Cookie)并计数报告 | +| `fingerprints` / `fingerprint_update_history` | PG 原样 | JSON text→jsonb | +| `usage_records`(v3 混合表) | **拆分**,见 §6.3 | — | +| `usage_time_buckets` | `request_time_buckets` | `provider='openai'`;空串维度→`__unknown__`;`success_count=max(request_count-error_count,0)`;`min_latency_ms` 0→NULL | +| `ops_error_logs`(v3) | PG | 增列 `client_api_key_id=NULL`、`provider='openai'` | +| `admin_sessions` / `session_affinities` / `account_refresh_leases` / `model_plan_snapshots` | **不导入** | 运行态/缓存,§6.3 损失清单 | --- ===== client_api_keys:改名暂存,Rust 步骤哈希回填 ===== -alter table client_api_keys rename to client_api_keys_v3; -drop index if exists idx_client_api_keys_key_enabled; -drop index if exists idx_client_api_keys_created_id; -create table client_api_keys ( … §4.4 DDL … ); -create index idx_client_api_keys_created_id on client_api_keys(created_at desc, id desc); +### 6.3 v3 usage_records 的拆分决策(原 0004 数据决策) --- ===== runtime_settings:重建(admin_api_key → 暂存,Rust 哈希) ===== -create table _migration_admin_key as select admin_api_key as value from runtime_settings; -alter table runtime_settings rename to runtime_settings_v3; -create table runtime_settings ( … §4.5 DDL … ); -insert into runtime_settings (id, model_aliases_json, refresh_margin_seconds, refresh_concurrency, - max_concurrent_per_account, request_interval_ms, rotation_strategy, admin_api_key_hash, updated_at) -select id, model_aliases_json, refresh_margin_seconds, refresh_concurrency, - max_concurrent_per_account, request_interval_ms, rotation_strategy, null, updated_at -from runtime_settings_v3; -drop table runtime_settings_v3; +1. **成功契约行迁入 usage_records**:`level <> 'error'` 且 `account_id`/`model` 非空 且 `status_code` 200–399。token、`requested_model`/`upstream_model`/`service_tier`/`first_token_ms` 从 metadata 提升为列(`usage.*` 优先、顶层回退),此后不再回读 metadata;`provider='openai'`;`client_api_key_id=NULL`(v3 未归因,错过不可回补——这正是归因列必须尽早存在的证明)。 +2. **`level = 'error'` 行迁入 ops_error_logs**(列同构映射,`client_status_code=NULL`)。 +3. **既非成功契约也非 error 的行**(无账号/无模型/无终态状态码的历史噪音)**不迁移**,计数后随源库废弃。 --- ===== ops_error_logs:先增列(下方 usage_records 迁移要写入这些列) ===== -alter table ops_error_logs add column client_api_key_id text; -alter table ops_error_logs add column provider text; -update ops_error_logs set provider = 'openai'; -create index idx_ops_error_logs_key_created on ops_error_logs(client_api_key_id, created_at desc) where client_api_key_id is not null; +**显式数据损失清单**(接受即执行,不做挽留方案): --- ===== usage_records:重建为成功事实表 ===== -alter table usage_records rename to usage_records_v3; -create table usage_records ( … §4.10 DDL 与全部索引 … ); - --- 数据决策 1:满足成功契约的行迁入,token 等列从 metadata 提升(此后不再回读 metadata)。 -insert into usage_records ( - id, request_id, client_api_key_id, kind, route, provider, account_id, model, - requested_model, upstream_model, service_tier, status_code, transport, attempt_index, - response_id, upstream_request_id, latency_ms, first_token_ms, - input_tokens, output_tokens, cached_tokens, reasoning_tokens, - message, metadata_json, created_at) -select - id, request_id, null, kind, route, 'openai', account_id, model, - nullif(trim(json_extract(metadata_json, '$.requestedModel')), ''), - nullif(trim(json_extract(metadata_json, '$.upstreamModel')), ''), - nullif(trim(json_extract(metadata_json, '$.serviceTier')), ''), - status_code, transport, attempt_index, - response_id, upstream_request_id, latency_ms, - coalesce(cast(json_extract(metadata_json, '$.firstTokenMs') as integer), - cast(json_extract(metadata_json, '$.usage.firstTokenMs') as integer)), - coalesce(cast(json_extract(metadata_json, '$.usage.inputTokens') as integer), - cast(json_extract(metadata_json, '$.inputTokens') as integer)), - coalesce(cast(json_extract(metadata_json, '$.usage.outputTokens') as integer), - cast(json_extract(metadata_json, '$.outputTokens') as integer)), - coalesce(cast(json_extract(metadata_json, '$.usage.cachedTokens') as integer), - cast(json_extract(metadata_json, '$.cachedTokens') as integer)), - coalesce(cast(json_extract(metadata_json, '$.usage.reasoningTokens') as integer), - cast(json_extract(metadata_json, '$.reasoningTokens') as integer)), - message, metadata_json, created_at -from usage_records_v3 -where level <> 'error' - and account_id is not null and trim(account_id) <> '' - and model is not null and trim(model) <> '' - and status_code between 200 and 399; - --- 数据决策 2:历史错误行迁入 ops_error_logs(列同构)。 -insert into ops_error_logs ( - id, request_id, client_api_key_id, kind, provider, account_id, route, model, - status_code, client_status_code, upstream_status_code, transport, attempt_index, - failure_class, response_id, upstream_request_id, latency_ms, message, metadata_json, created_at) -select - id, request_id, null, kind, 'openai', account_id, route, model, - status_code, null, upstream_status_code, transport, attempt_index, - failure_class, response_id, upstream_request_id, latency_ms, message, metadata_json, created_at -from usage_records_v3 -where level = 'error'; - --- 数据决策 3:既非成功契约也非 error 的行(无账号/无模型/无终态状态码的历史噪音)不迁移,随 v3 表一起删除。 -drop table usage_records_v3; - --- ===== usage_time_buckets → request_time_buckets ===== -create table request_time_buckets ( … §4.12 DDL … ); -create index idx_request_time_buckets_model on request_time_buckets(model, bucket_start); - --- 数据决策 4:历史桶迁入(sentinel 归一、success 推导、0-sentinel 转 NULL)。 --- 历史桶的 token 列含 v3 错误路径污染,按旧口径保留展示;事实保留期内的窗口 --- 随后由 rebuild-derived 用新口径重算覆盖(§6.4 验收第 4 步)。 -insert into request_time_buckets ( - bucket_start, provider, account_id, model, service_tier, - success_count, error_count, input_tokens, output_tokens, cached_tokens, - first_token_latency_sum, first_token_latency_count, - latency_sum, latency_count, max_latency_ms, min_latency_ms, updated_at) -select - bucket_start, - 'openai', - case when account_id = '' then '__unknown__' else account_id end, - case when model = '' then '__unknown__' else model end, - case when service_tier = '' then '__unknown__' else service_tier end, - max(request_count - error_count, 0), error_count, - input_tokens, output_tokens, cached_tokens, - first_token_latency_sum, first_token_latency_count, - latency_sum, latency_count, max_latency_ms, - nullif(min_latency_ms, 0), updated_at -from usage_time_buckets; - -drop table usage_time_buckets; - --- ===== 索引修正(其余表) ===== -drop index if exists idx_session_affinities_expires; -create index idx_session_affinities_account on session_affinities(account_id); -create index idx_fingerprint_update_history_fingerprint on fingerprint_update_history(current_fingerprint_id); -drop index if exists idx_account_cookies_account; -``` - -### 6.3 0004 的 Rust 步骤(`post` 钩子,同一事务) - -1. **client key 哈希搬迁**:读 `client_api_keys_v3` 全部行 → 每行计算 `SHA-256(key)` → insert 进新表(`key_hash` = 哈希,其余列原样)→ `drop table client_api_keys_v3`。明文自此不存在于库中。 -2. **admin API key 哈希**:读 `_migration_admin_key.value`,非空则 `update runtime_settings set admin_api_key_hash = `;`drop table _migration_admin_key`。 +- 全部管理端会话(重新登录)、会话亲和(退化为重新调度)、刷新租约(自愈)、模型清单快照(按需重拉)——运行态按 §2.9 本就可丢弃; +- v3 usage_records 中的噪音行(决策 3); +- 历史桶中错误路径污染的 token 按旧口径保留展示、不追溯清洗;事实保留期内的窗口随后由 `rebuild-buckets` 用新口径重算覆盖。 ### 6.4 迁移后动作与验收 | # | 动作 | 验收 | | --- | --- | --- | -| 1 | 事务提交后执行一次 `vacuum`(使 `auto_vacuum = incremental` 对旧库生效;vacuum 不能在事务内) | `pragma auto_vacuum` 返回 2 | -| 2 | 管理员重新登录(会话已清空) | 登录成功,新会话 `token_hash` 长度 64 | -| 3 | 抽查 `select count(*) from client_api_keys where length(key_hash) <> 64` = 0 | 明文 key 消失,鉴权仍通过 | -| 4 | 执行 `rebuild-derived`(§7.6),用新口径重算事实保留期内的桶 | 保留期内桶 token 列 = usage_records 聚合值 | -| 5 | 核对 Dashboard 卡片全部走 bucket 口径 | 同卡片无混合口径数字 | - -**显式数据损失清单**(接受即执行,不做挽留方案):全部管理端会话;v3 usage_records 中既非成功契约也非 error 的噪音行;历史桶中错误路径污染的 token 按旧口径保留、不追溯清洗(保留期内被 rebuild 覆盖为新口径)。 +| 1 | 服务指向 PG+Redis 启动 | `/healthz` 204(PG `select 1` + Redis `PING` 双活) | +| 2 | 管理员重新登录 | 登录成功;Redis 出现 `cpr:admin:session:*`,TTL ≈ session_ttl | +| 3 | 抽查 `select count(*) from client_api_keys where length(key_hash) <> 64` = 0 | 明文 key 消失,旧 key 鉴权仍通过 | +| 4 | 执行 `rebuild-buckets`(§7),用新口径重算事实保留期内的桶 | 保留期内桶 token 列 = usage_records 聚合值 | +| 5 | 核对 Dashboard 卡片全部走 bucket 口径,生命周期数字标注"成功累计" | 同卡片无混合口径数字 | --- -## 7. 代码改造清单 +## 7. 代码改造清单(本次交付) -与 0004 同一 PR 交付,按依赖顺序: +与导入命令同一 PR 交付,按依赖顺序: -1. **迁移框架**(`infra/database.rs`):`Migration.post` 钩子;连接参数补 `synchronous(Normal)`、`auto_vacuum(Incremental)`;目标迁移落地时再提升 `CURRENT_SCHEMA_VERSION`。 -2. **鉴权归因**(`proxy/auth.rs`):`authorize_client_api_key_result` 改为返回 key 的 `id`(现在验完即弃);SHA-256 后查 `key_hash`。调用链把 `client_api_key_id` 装进请求上下文。 -3. **事件结构**(`proxy/dispatch/usage_events.rs`、`proxy/dispatch/responses/event_recording.rs`):成功/失败事件携带 `client_api_key_id`;token、requested/upstream_model、service_tier、first_token_ms 从 metadata 移到一等字段;metadata 不再写已提升字段。 -4. **写入路径**(`admin/monitoring/usage_record_store.rs`、ops error store):§5.2 的两条事务;错误路径对桶只 `error_count + 1`;`__unknown__` sentinel;min/max 延迟直接 `min()`/`max()`(无 0-sentinel 分支)。 -5. **查询路径**(`usage_record_service.rs`、`dashboard.rs`、`account_usage_service.rs`):summary/分布/趋势全部走列,删除所有 `json_extract` 聚合与 `like '%…%'` 搜索;Dashboard 按 §5.3 口径改卡片来源与文案。 -6. **维护命令**:管理端 `rebuild-derived`——删除事实保留期内的桶并从两张事实表重算;保留期外只读不动。范围明确**不含** `account_usage` / `account_model_usage`(§2.9,不可重建)。 -7. **清理任务**:三个 trim 任务改读 `runtime_settings` 三列;新增 bucket trim;每轮 trim 后 `pragma incremental_vacuum`。 -8. **管理端 API**(`admin/auth/service.rs`、`config/settings.rs`、keys 路由):session 创建/校验走 `token_hash`;`verify_admin_api_key` 对来键哈希后 `ct_eq`;key 列表响应删除完整 key 字段(只余 `prefix`)——**前端同步移除完整 key 展示**。 -9. **测试**(`backend/tests/infra/storage_schema/`):断言终态 DDL、迁移数据规则(成功行迁入 / error 行转 ops / 噪音行丢弃)、两条写入事务的原子性、0ms 延迟样本可入桶。 +1. **连接层**(`infra/database.rs` + 新增 `infra/redis.rs`):PgPool(参数见 §1)+ 迁移框架(PG 谱系 0001 起);Redis ConnectionManager + 键前缀 + `PING` 健康检查。`Cargo.toml`:sqlx 加 `postgres`(保留 `sqlite` 仅供导入命令读源库),新增 `redis` crate。 +2. **配置**(`config/schema.rs`、`deploy/config.example.yaml`):`database.url` 改 `postgres://…`,新增 `redis.url`。 +3. **鉴权归因**(`admin/keys/service.rs`、`proxy/auth.rs`):key 创建落 `key_hash`;鉴权 = SHA-256 后 PG 点查(删除进程内明文鉴权表);`authorize_client_api_key_result` 返回 key `id`,调用链把 `client_api_key_id` 装进请求上下文直至事件写入。key 列表响应删除完整 key 字段(只余 `prefix`)——**前端同步移除完整 key 展示**。 +4. **事件结构**(`usage_record_model.rs`、`ops_error_model.rs`、`usage_events.rs`、`event_recording.rs`):成功/失败事件携带 `client_api_key_id` 与 `provider`;token、requested/upstream_model、service_tier、first_token_ms 从 metadata 移到一等字段;metadata 不再写已提升字段;UsageRecord 删除 `level`(成功事实无等级)。 +5. **写入路径**(usage record store、ops error store):§5.2 的两条 PG 事务;错误路径对桶只 `error_count + 1`;`__unknown__` sentinel;min/max 延迟直接 `least()`/`greatest()`(无 0-sentinel 分支);内联 trim 移除。 +6. **查询路径**(`usage_record_store/service/routes`、`dashboard.rs`、`account_usage_store.rs`、`admin/accounts/routes.rs`):summary/分布/趋势全部走列,删除所有 `->>` 聚合与 metadata LIKE;新增 `/api/admin/ops/errors` 错误明细查询面;Dashboard 按 §5.3 改卡片来源与文案。 +7. **运行态改 Redis**(`admin/auth/service.rs` 会话、`token_refresh` 租约、`session_affinity.rs`、`models/snapshot_store.rs`):按 §4B 契约实现;删除 admin 会话/亲和清理任务与亲和重启恢复;账号删除路径挂 Redis 亲和级联(§4B.3)。 +8. **维护命令**(`main.rs` CLI):`import-sqlite `(§6);`rebuild-buckets`——删除事实保留期内的桶并从两张事实表重算(15 分钟槽对齐在 SQL 侧 `floor(epoch/900)*900`,§2.3);保留期外只读不动。范围明确**不含** `account_usage` / `account_model_usage`(§2.10,不可重建)。 +9. **清理任务**(`runtime/tasks/`):三张增长表的周期 trim(读 `runtime_settings` 三列);cookie 清理保留;admin 会话与亲和清理任务删除(TTL 接管)。 +10. **健康检查**(`http/router.rs`):PG `select 1` + Redis `PING`,任一失败即 503。 +11. **测试**(`backend/tests/`):support 换 PG(每测试独立数据库,`CPR_TEST_DATABASE_URL` 指定服务端)+ Redis(每测试随机键前缀,`CPR_TEST_REDIS_URL`);storage 测试断言终态 DDL、导入拆分规则(成功行迁入 / error 行转 ops / 噪音行丢弃)、两条写入事务的原子性、0ms 延迟样本可入桶、租约原子性。 +12. **部署**(`deploy/docker-compose.yml`):新增 postgres、redis 服务与健康检查依赖。 --- ## 8. 扩展路径与明确不做 -每个可预见的增长方向都有"只加不改"的路径: +每个可预见的增长方向都有"只加不改"的路径: | 未来需求 | 扩展方式 | | --- | --- | -| 多管理员 | `admin_users` 加 `username`/`role` + 新表 `admin_login_events` | -| 按 key 限流/配额 | 新表 `client_api_key_policies (key_id FK, …)`;归因数据已在事实表就位 | -| 错误运维大盘 | `ops_error_logs` 按 §4.11 预留清单增列 | -| 长期趋势/年度账务 | 新表 `request_day_buckets`(由 15 分钟桶降采样归档),Dashboard 才允许出现"历史总量" | +| 多管理员 | `admin_users` 加 `username`/`role` + PG `admin_login_events` + Redis `cpr:admin:user_sessions:` SET(踢会话索引) | +| 按 key 限流/配额 | 新表 `client_api_key_policies (key_id FK, …)`;归因数据已在事实表就位;运行态计数走 Redis | +| 错误运维大盘 | `ops_error_logs` 按 §4.9 预留清单增列 | +| 长期趋势/年度账务 | 新表 `request_day_buckets`(由 15 分钟桶降采样归档),Dashboard 才允许出现"历史总量" | | 刷新历史分析 | 新表 `account_refresh_events` | | 模型别名审计 | `model_aliases_json` 拆 `model_aliases` 表 | -| 凭据静态加密 / 合规 | `accounts` 拆 `account_credentials`(1:1,PK=FK),集中一个破坏窗口 | -| 接入第二上游 provider(已规划:Cloudflare Workers AI) | 事实表与桶的 `provider` 维度已在 v4 就位(§4.10–4.12),CF 首条请求落库前无需再动事实表。届时一个迁移完成:`accounts` 加 `provider` + `chatgpt_account_id/user_id` 更名 `upstream_account_id/upstream_user_id` + 唯一索引加 provider 维度;`model_plan_snapshots` PK 改 `(provider, plan_type)`;billing 单价查找加 provider 参数。回填全部确定为 `'openai'` | -| 多实例部署 | SQLite → Postgres:TEXT 时间戳 → timestamptz、`check in` → enum、upsert 语法兼容;租约表天然支持竞争 | +| 凭据静态加密 / 合规 | `accounts` 拆 `account_credentials`(1:1,PK=FK),集中一个破坏窗口 | +| 接入第二上游 provider(已规划:Cloudflare Workers AI) | 事实表与桶的 `provider` 维度已就位(§4.8–4.10),CF 首条请求落库前无需再动事实表。届时一个迁移完成:`accounts` 加 `provider` + `chatgpt_account_id/user_id` 更名 `upstream_account_id/upstream_user_id` + 唯一索引加 provider 维度;模型缓存 HASH field 改 `:`;billing 单价查找加 provider 参数。回填全部确定为 `'openai'` | -Cloudflare 账号对现有 schema 的适配(无需新列):静态 API key = `access_token`,`refresh_token`/`access_token_expires_at` NULL(永不过期,语义已覆盖);无套餐配额窗口 → `account_usage.window_*` 恒为初始值、窗口边界 NULL;`account_cookies` 对 CF 账号空置。**硬规则**:任何新 provider 的第一条请求落库之前,其事实行必须已携带 provider 归因——v4 之后这条自动满足。 +Cloudflare 账号对现有 schema 的适配(无需新列):静态 API key = `access_token`,`refresh_token`/`access_token_expires_at` NULL(永不过期,语义已覆盖);无套餐配额窗口 → `account_usage.window_*` 恒为初始值、窗口边界 NULL;`account_cookies` 对 CF 账号空置。**硬规则**:任何新 provider 的第一条请求落库之前,其事实行必须已携带 provider 归因——终态之后这条自动满足。 -**明确不做**:无多实例需求前不引入外部数据库/缓存;不为历史数据加任何兼容过滤;不预建"可能有用"的列——每一列都必须有当前的真实读者;不照搬外部项目的字段全集。 +**明确不做**:**不考虑多实例部署**——调度器、登录限速、`last_used_at` 去抖、CF 风控跟踪均为单进程语义,PG/Redis 的选择不以横向扩容为目标;不保留 SQLite 运行路径(源库只被导入命令只读打开);不为历史数据加任何兼容过滤;不预建"可能有用"的列——每一列都必须有当前的真实读者;不照搬外部项目的字段全集;Redis 不承载任何不可丢失数据。