docs: document postgresql redis storage target

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
zyycn
2026-07-09 22:39:22 +08:00
co-authored by Codex
parent 108ad96e91
commit 28b0907594
2 changed files with 488 additions and 551 deletions
+74 -59
View File
@@ -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 事件的逐字段兼容性。
+414 -492
View File
File diff suppressed because it is too large Load Diff