docs(architecture): fill phase 2 batch 6A — core mechanism trio (#167)#184
Merged
Conversation
填充三篇架构核心机制文档： - upstream-model: RouteCapability 八枚举 + provider 分组、upstreams 表关键字段、 model-router 五步路由（前缀 → provider type → 熔断过滤 → 白名单/别名 → 回退）、 load-balancer 的 tier 过滤 + 加权抽样 + session affinity，以及健康状态对路由 不直接生效的事实。 - failover-circuit: 熔断器三态状态机表格 + 默认阈值 + recordFailure/recordSuccess 转换条件、forwardWithFailover 主循环与 isFailoverableError 判定、FailureRule 屏蔽熔断计数的机制、Admin 强制 open/close、决策日志写入 request_logs 的字段。 - database-schema: 双 schema 文件（PG + SQLite）的 barrel 切换、20 张表分四组 清单（按用途）、FK 与 cascade/set null 策略汇总、JSON 列 TypeScript 类型注解 表、单列与复合索引摘要、迁移目录与最近五次 PG 迁移、客户端单例与连接池配置。 所有事实均带 file:line 引用，便于读者照着源码读。
…odex review (#167) 修正 codex 审查指出的两处材料性错误： 1. upstream-model.md - 删除「routeByModel 是第一阶段入口」的错误描述。实测全仓库 routeByModel( 零调用点（仅定义本身），生产代理路径采用的是 resolveRouteCapabilityCandidatePool + filterCandidatesByModelRules + resolvePathRoutingModelForUpstream 的三层过滤， 基于请求路径解析出的 RouteCapability 与 model_rules，与模型名前缀无关。 - 整章重写为基于真实运行期函数的五步流程（capability+授权 → model_rules 过滤 → resolvedModel 解析 → 候选 ID 交给 forwardWithFailover）。 - 修正 model_redirects 描述：仅用于 filtering / logging / billing 三件事， 不会改写转发 body。proxy-client.ts:896, 1095-1098 显示 applyModelOverride 只在 modelOverride 非空时触发，而 modelOverride 仅 CLIProxyAPI 上游路径 构造（route.ts:1513-1525, 1534），普通上游 body 原样透传。 - 补充 UpstreamModelRule 类型定义与 normalizeUpstreamModelRules 合并行为： model_rules 非空时为唯一规则源，否则降级把 allowed_models / model_redirects 转成 exact / alias 规则使用。 - 调用链表替换 routeByModel 行为新的实际函数列表。 2. failover-circuit.md - 修正 probeUpstream 描述。源码 health-checker.ts:546 显示 probeUpstream 仅调用 testUpstreamConnection 返回 boolean，零 DB 写，且全仓库 probeUpstream( 零调用点（dead export）。实际写 upstream_health 表的只有 checkUpstreamHealth （health-checker.ts:310 → updateHealthStatus）。改写为正确归因，并保留 「主动探测不改变熔断器状态」的结论。
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #184 +/- ##
=======================================
Coverage 74.13% 74.14%
=======================================
Files 145 145
Lines 11043 11043
Branches 3832 3832
=======================================
+ Hits 8187 8188 +1
Misses 1657 1657
+ Partials 1199 1198 -1
🚀 New features to boost your workflow:
|
14 tasks
g1331
added a commit
that referenced
this pull request
May 25, 2026
…卷挂载现状 (#167, #188) Self-review 抽读时发现四处与仓库现状不符的事实陈述，本次一并修正： 1. database.md / upgrade-rollback.md 关于「容器不会自动跑迁移」「需要部署人手工触发 pnpm db:migrate」的描述与 scripts/docker-entrypoint.sh 现状矛盾。 该 entrypoint 在应用启动前会自动跑一遍内嵌的 migration runner（不依赖 drizzle-kit，按文件名顺序 apply drizzle/*.sql、用 __drizzle_migrations 表去重）。改为说明自动 apply 行为，并把破坏性迁移段重写为「entrypoint 仍 forward apply，回滚必须靠 pg_dump」。 2. database.md / upgrade-rollback.md 建议的 `docker compose exec autorouter node node_modules/drizzle-kit/bin.cjs migrate` 在生产镜像内无法执行。 Dockerfile standalone runner stage 只 copy postgres 这一个 node_modules 子包，drizzle-kit 是 devDependency 不进镜像。改为推荐「重启 autorouter 让 entrypoint 重跑」或「docker run --rm --entrypoint /app/docker-entrypoint.sh ghcr.io/g1331/autorouter:vN.N.N true」这种把 entrypoint 与 server.js 解耦的临时容器写法。 3. persistence-backup.md 关于「RECORDER_FIXTURES_DIR 通常会挂入 autorouter-data named volume（如默认编排）」的描述错误。 docker-compose.yml 中 RECORDER_FIXTURES_DIR 默认值是 `tests/fixtures`，相对容器内 /app/，实际写到 /app/tests/fixtures，不在任何 named volume 上——容器重建即丢。补 ::: danger ::: 容器警告，并显式给出「显式把 RECORDER_FIXTURES_DIR 指到 /app/data/...」的修复路径。 4. contributing.md 关于「推荐用 squash merge」与仓库实际 merge commit 历史（PR #184/#185/#186 都是 Merge pull request 形态）冲突。改为陈述「近期实际历史以 merge commit 为主，cliff.toml 显式 skip 这类 commit」，把策略选择留给 reviewer。 来源对照段同步补 scripts/docker-entrypoint.sh 与 Dockerfile 两项依据。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
本 PR 是 issue #167 phase 2 架构介绍批次 6A——核心机制三篇。延续 #182 / #183 已建立的「源码佐证 + file:line 引用 + 章节互链」写作风格。
包含文档
docs/guide/architecture/upstream-model.mdRouteCapability八枚举与 provider 分组、upstreams表关键字段分组、model-router五步路由、load-balancer的 tier + 加权抽样 + session affinitydocs/guide/architecture/failover-circuit.mdforwardWithFailover主循环与可故障转移错误判定、FailureRule屏蔽熔断计数、Admin 强制 open/close、决策日志写入request_logs的字段docs/guide/architecture/database-schema.md关键事实（源码验证过）
RouteCapability共 8 个值，codex_responses是 legacy 值会被自动重映射为openai_responsesis_healthy字段是「display-only」，不参与路由判定；实际过滤由熔断器状态决定excludeStatusCodes: []，所有 4xx（含 401/403/429）都会触发故障转移recordSuccess在 CLOSED 状态下不做 DB 写入，是有意优化request_logs.failover_history/routing_decision实际存为text列而不是json，写入时JSON.stringify交叉引用
三篇互相引用，并向
usage/troubleshooting、usage/logs-stats、usage/cliproxy-modes、usage/circuit-breaker-config等已合入文档建链；从architecture/request-lifecycle与architecture/overview自然延伸。本地验证
pnpm exec vitepress build docs通过（构建时间 6.81s，仅有 cosmetic 的env语法高亮回退提示）pre-commitprettier 自动修正了表格列宽与空行，已重提交不在本 PR 范围
phase 2 剩余架构 6 篇（
cliproxy-integration/security/i18n/testing/contributing/release）与部署 6 篇按 codex 给出的批次推进，分独立 PR。