1愿景与定位
我们要造一个自托管的 LLM 网关引擎：对内部各产品（解梦、GEO 审计、programmatic-SEO、prospecting……）提供"统一接入 + 智能路由 + 自动回退 + 缓存 + Batch + 计费记账"，对外暴露 OpenAI 兼容 API。它不是对外售卖的产品，而是路线 C 里所有产品共享的 COGS 降本引擎——把每个产品的 token 成本压到收入的 10~25%，支撑 50~70% 毛利（见 11）。
2范围（In / Out）
✅范围内（MVP）
- OpenAI 兼容端点：
/v1/chat/completions（流式+非流式）、/v1/embeddings、/v1/models - 内部产品 API key 签发/校验/吊销，按产品隔离
- 渠道（Channel）：OpenRouter、Cloudflare Workers AI、DeepSeek 直采、Groq 直采、官方免费层
- 分层路由 + 429/5xx 自动回退 + 权重负载均衡
- 响应缓存（KV）+ prompt 缓存透传
- 令牌桶限流（每 key RPM/并发）
- 计费记账：每请求 model/tokens/cost/latency 落 D1；倍率与配额
- 声明式渠道/路由配置；可观测（Analytics Engine/日志）
3里程碑 M0–M3
M0第 0 周 · 脚手架
monorepo + Workers 脚手架 + wrangler bindings + D1 迁移骨架 + CI 跑通（lint/typecheck/test/deploy preview）。产出：能部署一个返回 200 的空网关。
M1第 1–2 周 · 直通 + 记账
/v1/chat/completions 经单一渠道（OpenRouter）直通；API key 校验；每请求记账落 D1；基础限流。产出：内部产品可用一个 key 调通并看到用量。M2第 3–4 周 · 路由 + 缓存 + 多渠道
分层路由 + 回退 + 权重；接入 DeepSeek/Groq 直采与 Workers AI；响应缓存 + prompt 缓存透传；倍率与配额。产出：同一请求自动选最划算模型、命中缓存零成本、超配额拒绝。
M3第 5–6 周 · Batch + 可观测 + 硬化
Batch 异步路径（Queues）端到端；Analytics Engine 看板 + 告警；安全硬化（密钥保险库、零信任、速率防护）；压测与回滚演练。产出：生产可用、可观测、可回滚。
4角色分工（最小团队）
| 角色 | 职责 | 关键文档 |
|---|---|---|
| 技术负责人 / 全栈 | 架构、路由/计费核心、CI/CD、上线 | 21 / 23 / 25 |
| 后端工程师 | API 端点、渠道适配、数据层、限流 | 22 / 23 |
| 数据/计费 | 记账 schema、用量报表、成本对账 | 22 / 23 |
| SRE / DevOps（可兼） | 环境、密钥、监控、回滚 | 25 / 26 |
| 产品/合规（兼） | 验收标准、红线把关、对接内部产品方 | 20 / 26 |
MVP 可由 1–2 名全栈完成；角色为职责划分而非必须独立人头。
5关键架构决策（ADR）
| # | 决策 | 选择 | 理由 / 取舍 |
|---|---|---|---|
| ADR-1 | 自建 Workers 网关 vs 直接用 New API/LiteLLM | 自建（薄）+ 前置 OpenRouter | 自建薄网关掌控路由/计费/记账与红线；OpenRouter 作统一接入省去逐家适配。New API/LiteLLM 重且 New API 为 AGPL（见 04），不作核心。后期如需企业治理可再评估 LiteLLM。 |
| ADR-2 | 运行时 | Cloudflare Workers | 边缘、免费层友好、与 D1/KV/Queues/AI Gateway 同栈、零 egress（见 05/17）。 |
| ADR-3 | Web 框架 | Hono | Workers 原生、轻、TS 友好、中间件齐全。 |
| ADR-4 | 数据层 | D1（记账/配置）+ KV（缓存/计数）+ DO（强一致限流） | D1 关系型适合记账与配置；KV 适合缓存与软计数；Durable Objects 用于需要强一致的令牌桶。 |
| ADR-5 | 校验 | Zod | API I/O 与配置 schema 运行时校验，类型与校验同源。 |
| ADR-6 | 仓库形态 | pnpm workspaces monorepo | 引擎 + 共享 packages（core/db/config）+ 未来产品同仓复用。 |
| ADR-7 | 缓存前置 | Cloudflare AI Gateway 前置 + 自建 KV 响应缓存 | AI Gateway 免费提供缓存/可观测/重试；自建 KV 缓存覆盖业务级 key。 |
ADR 为可演进决策；变更需在本表追加新条目并注明取代关系。
6风险登记
| 风险 | 影响 | 缓解 |
|---|---|---|
| 供应商限额/价格变动 | 成本与可用性波动 | 多渠道路由 + 回退；配置化定价；定期复核（见 16/17） |
| 免费层 429 频繁 | 免费档体验下降 | 免费层仅低 SLA；超限降级到便宜付费模型 |
| 密钥泄露 | 被盗刷、成本爆炸 | 密钥保险库 + 不下发客户端 + 定期轮换 + 用量异常告警 |
| Workers CPU/时长限制 | 长请求/流式中断 | 流式透传；超重任务走 Batch/Queues；必要时小 VPS 兜底（见 05） |
| 记账与厂商账单对不上 | 毛利失真 | 以厂商返回 usage 为准记账 + 月度对账 |
| 合规红线被无意突破 | 法律/支付风险 | 渠道准入清单 + CI 红线检查（见 26） |
7完成标准（Definition of Done）
- 功能：内部产品用一个 Base URL + key，可流式/非流式调用，自动路由+回退+缓存，超配额被拒。
- 记账：每请求 model/tokens/cost/latency 入库，可按产品/模型/日聚合查询。
- 质量：核心路径单测覆盖 ≥ 80%；CI 全绿（lint/typecheck/test）；关键路径有集成测试（Miniflare）。
- 可观测：有用量/成本/错误率/延迟看板与基础告警。
- 安全：密钥不入仓、不下发；限流生效；红线检查通过。
- 可运维：一键部署、可回滚、有 runbook（见 25）。