docs(architecture): 整体架构总览 + 请求生命周期(#167 Phase 2 第三批)#180
Merged
Conversation
完成 issue #167 Phase 2 第一批最后两篇: - `docs/guide/architecture/overview.md` 整体架构总览:进程拓扑、目录分层、`src/lib/services/` 服务模块清单(按 9 个职责域归类)、20 张数据库表汇总、对外入口边界、i18n 路由结构、关键依赖版本、Docker 与 GHA 入口 - `docs/guide/architecture/request-lifecycle.md` 请求生命周期:把 `POST /api/proxy/v1/chat/completions` 的内部流程拆为 7 个阶段(HTTP 分发 / CORS / 鉴权 / 路由能力解析 / 候选过滤与选路 / 转发与流式 / 日志计费响应),每个阶段挂上 `src/...:line` 引用 同时修订 `docs/guide/usage/invoke-models.md` 中一处事实错误: - 旧文档声称代理层「追加 AutoRouter 自身的请求 ID 与命中上游 ID」响应头;实际 `route.ts:3192` 之后未注入任何 `X-AutoRouter-*` 自定义头,仅 SSE 时强制写入 `Content-Type` / `Cache-Control` / `Connection`。请求 ID 与命中上游 ID 只通过管理后台「请求日志」回查
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #180 +/- ##
=======================================
Coverage 74.13% 74.13%
=======================================
Files 145 145
Lines 11043 11043
Branches 3832 3832
=======================================
Hits 8187 8187
Misses 1657 1657
Partials 1199 1199
🚀 New features to boost your workflow:
|
按 review 反馈逐条核对源码并修正: - [P2] request-lifecycle.md 阶段二「CORS 与 OPTIONS」: grep `Access-Control-Allow` 全仓无匹配,`corsOrigins` 字段只在 `src/lib/utils/config.ts` 被读,没有任何代码读取后输出 CORS 响应头。 把「需要把对应 origin 加入 CORS_ORIGINS」的旧描述修订为 「CORS_ORIGINS 在当前实现中没有运行期效果,浏览器侧直连需要前置反向代理」。 overview.md `CORS_ORIGINS` 字段说明与时序总览同步修订。 - [P2] invoke-models.md「响应行为:透传 + 改写」与 request-lifecycle.md 阶段七: 代理层并非 1:1 复制上游 header。`proxy-client.ts:216` 的 filterHeaders 会去 hop-by-hop header,`proxy-client.ts:1157-1159` 在 undici 已解压响应体时 额外删除 `content-encoding` 与 `content-length`。修订两处文档统一口径。 - [P3] request-lifecycle.md 阶段四「模型提取」结尾: `filterCandidatesByModelRules`(`route.ts:591-600`)在 originalModel 为 null 时返回全部候选,请求会被转发到上游而非本地被拒绝。把「模型名缺失或无法解析 直接返回 400」修订为说明 model 为 null 时仍会进入选路、400 来自上游。 - [P3] overview.md 首段持久化范围: `recordTrafficFixture`(`traffic-recorder.ts:517`、`:529-530`)把 fixture JSON 写到磁盘(默认 `data/traffic-recordings`,可由 `RECORDER_FIXTURES_DIR` 覆盖); 数据库 `trafficRecordings` 表仅保存 `fixture_path` 等索引。修订首段说明 录制功能的持久化分两处,并提醒备份规划要同时覆盖数据库与该磁盘目录。 env-reference.md:80 中 `CORS_ORIGINS` 的描述与同类问题为先前文档遗留,不在 本 PR 范围内,留待后续单独修订。
- [P2] request-lifecycle.md 阶段六「失败转移」 + invoke-models.md「failover 对调用方无感」: 原文笼统说「转发或流读取过程中重新选下一条候选」与「failover 对调用方 无感」,与流式实现不符。`forwardWithFailover`(`route.ts:1289`)一旦 `result.isStream === true` 就直接 `return` 包装好的流(`route.ts:1651`), 中途读流失败由 `wrapStreamWithConnectionTracking` 的回调(`route.ts:1618-1649`) 交给 `settleStreamRuntimeFailureForCircuitBreaker` 处理——只记录日志与 熔断失败,不会回到选路阶段。修订两处文档显式区分「首字节前的失败(可重试)」 与「流开始后的中断(不可重试)」,并说明调用方需要自行处理「上游 stream 中断」错误。 - [P3] invoke-models.md「响应行为」与 request-lifecycle.md 阶段七的响应 header 描述: 上一轮修订错把响应头过滤指到 `proxy-client.ts:216` / `:995` 的 filterHeaders。 实际上那里处理的是请求侧 inbound header;响应头由 `proxy-client.ts:1147-1153` 的 inline 循环按 `HOP_BY_HOP_HEADERS` 过滤。修订两处文档指向正确代码位置, 并显式标注「与请求侧 filterHeaders 不是同一段代码」避免读者再混淆。
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
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.
Summary
完成 issue #167 Phase 2 第一批最后两篇架构文档:
docs/guide/architecture/overview.md整体架构总览:单进程拓扑示意、目录分层、src/lib/services/服务模块按 9 个职责域归类、20 张数据库表汇总、对外入口边界、i18n 路由结构、关键依赖版本、Docker 与 GitHub Actions 入口docs/guide/architecture/request-lifecycle.md请求生命周期:把POST /api/proxy/v1/chat/completions拆为 7 个阶段(HTTP 分发 / CORS / 鉴权 / 路由能力解析 / 候选过滤与选路 / 转发与流式 / 日志计费响应),每一阶段挂上src/...:line引用同时修订
docs/guide/usage/invoke-models.md一处事实错误:src/app/api/proxy/v1/[...path]/route.ts:3192之后未注入任何X-AutoRouter-*自定义头,仅 SSE 时强制写入Content-Type/Cache-Control/Connection三个标准头事实校验
两篇正文里出现的所有
src/...:line引用、函数名、RouteCapability枚举、表名、依赖版本均由 Explore 子代理直接读源码采证。wrapStreamWithConnectionTracking行号、handleProxy入口、failoverHistory写入点、shouldRecordFixture决策点、requestBillingSnapshotsupsert 等关键事实均与master当前代码一致。Phase 2 进度
本 PR 合入后,issue #167 Phase 2 第一批 10 篇全部到位。
Test plan
pnpm docs:build通过(无新增警告,既有 vueuse#__PURE__与env高亮回退 warning 已在以前的批次中存在)pnpm format:check通过