docs: 建立文档体系（34 篇 + VitePress 静态站 + UI 内嵌指南）

[g1331]

背景

当前文档体系存在三个明显空缺，导致不熟悉项目的访客难以独立部署成功：

1. README.md / README_EN.md 未提及 CLIProxyAPI 集成、docker-compose.cliproxy.yml、sidecar 形态等内容，GitHub 首页访客无法感知项目支持 Codex / Claude / Gemini OAuth 上游。
2. docs/cliproxy-deployment.md 默认读者是「拉源码 + 双 -f compose」的运维形态，未覆盖 deploy-personal.yml 这条 CI + 远端 SSH 的轻量部署路径。CI 部署完成后管理页为空，没有任何文档指引手工补 sidecar 的具体步骤。
3. 「容器服务名 vs localhost」陷阱在字段提示、文档说明、连通性检测错误信息三处均未覆盖。最近一次真实部署中就因为代理地址填了 http://localhost:8317 而非 http://cliproxyapi:8317 直接踩坑。

继续向 README 堆内容会让首页膨胀，需要一套可扩展的文档体系。

文档内容清单

按「部署 / 使用 / 架构」三大类组织，合计 34 篇。

一、部署指南（10 篇）

读者：拿到这个项目准备搭建的运维或个人。

文档	一句话说明
部署形态总览	解释「源码 + docker compose」「CI + 远端 SSH」两条主路径的差别，以及何时引入 docker-compose.cliproxy.yml 叠加文件
快速开始（源码 docker compose）	5 分钟版：克隆仓库、配置 .env、docker compose up -d、登录管理后台
环境变量参考	把 .env.example 的每个字段一一展开：用途、默认值、生成方式、修改后是否需要重启
GitHub Actions CI 部署	release.yml（打 tag → 构建镜像 → ghcr） + deploy-personal.yml（workflow_dispatch SSH 部署）两个流程的触发方式、Secrets 清单、首次配置步骤
CI 部署后追加 CLIProxyAPI sidecar	沉淀本次踩过的路径：curl 拉叠加文件与 cliproxy 目录、追加 .env 段、双 -f up -d
数据库选型与初始化	PostgreSQL（默认）vs SQLite（轻量场景）、db:push / db:migrate 选用、首次初始化命令
HTTPS 与反向代理	在 Nginx / Caddy / 1Panel 等场景下把 AutoRouter 暴露到公网的方式、CORS 配置
数据持久化与备份	命名卷 cliproxy-auth cliproxy-logs 与 PostgreSQL 卷的备份恢复样例、bind mount 变体
升级与回滚	版本切换流程、AUTOROUTER_IMAGE 替换、出问题时回退到上一个 tag
常见部署问题排查	容器无法启动、healthcheck 失败、localhost vs 服务名陷阱、ENCRYPTION_KEY 丢失的影响

二、使用指南（13 篇）

读者：已经把 AutoRouter 部署起来、登录到管理后台准备配置的人。

文档	一句话说明
管理后台导览	各侧边项的职责：仪表盘、密钥、上游、CLIProxyAPI、熔断器、请求日志、统计、请求录制
添加第一个上游	用 OpenAI 兼容 API 走一遍完整流程：填 base_url、API Key、模型路由能力、保存、连通性测试
创建客户端 API Key	受限模式 vs 全量模式、绑定上游、密钥揭示策略（ALLOW_KEY_REVEAL）
通过 AutoRouter 调用模型	Authorization: Bearer <key> + OpenAI 兼容协议示例（cURL、OpenAI SDK Python/JS、Anthropic SDK），含流式与非流式
模型路由规则	gpt-* → openai 组、claude-* → anthropic 组、gemini-* → gemini 组等模型前缀映射逻辑、覆盖与扩展方式
负载均衡与权重	weight priority 字段的语义、相同组内多上游的调度策略
熔断器配置	CLOSED / OPEN / HALF_OPEN 状态机解释、阈值配置、Admin 强制开关的使用场景
CLIProxyAPI：首次使用指南	从零到能用完整链路：登记实例 → OAuth 登录账号 → 创建池上游 → 客户端调用 Codex / Claude / Gemini
CLIProxyAPI：外部 vs sidecar 选择	两种模式各自的适用场景、运维差异、字段填写差异
CLIProxyAPI：出站代理配置	受限网络下 CLIPROXY_PROXY_URL 的使用、生效方式、验证流程
请求日志与统计	查看日志的方式、过滤条件、LOG_RETENTION_DAYS 与请求录制的关系
请求录制	录制规则配置、敏感字段脱敏开关（RECORDER_REDACT_SENSITIVE）、用途
故障排查手册	常见错误码、上游 5xx、SSE 中断、计费异常等场景的排查路径

三、架构介绍（11 篇）

读者：想理解系统内部、或者准备贡献代码、或者评估架构是否符合需求的开发者。

文档	一句话说明
整体架构总览	一张图说明 Next.js fullstack 结构、前后端职责划分、各服务模块的关系
请求生命周期	一次客户端请求从 /api/proxy/v1/* 进入到上游返回的完整流转：鉴权、模型解析、上游选择、转发、日志、计费
上游模型	upstreams 表的字段含义、route_capabilities 枚举、状态机、与熔断器交互
失败转移与熔断	熔断状态机、自动 failover 决策、健康检查后台任务、决策日志
安全模型	Admin Bearer Token、客户端 API Key bcrypt 哈希、上游 Key Fernet 加密、SSRF 防护（IP/URL/DNS 三重校验）
数据库 schema	主要表的字段、关系图、drizzle/（PG）与 drizzle-sqlite/ 双 schema 的差异维护方式
CLIProxyAPI 集成位置	CPA 在整体架构中的位置、cliproxy_instances 表如何与 upstreams 表挂钩、池上游的本质
国际化机制	next-intl [locale] 路由、src/messages/ 翻译文件组织方式
测试策略	单元测试（Vitest）、tests/unit/ 与 tests/integration/ 的边界、CI 工作流
贡献指南与代码规范	提交流程、pre-commit 钩子、ESLint + Prettier、OpenSpec 提案的使用方式
版本与发布	语义化版本、alpha / beta 标签、cliff.toml 自动生成 release notes、镜像 tag 策略

第一批优先 10 篇

路人能否成功部署直接取决于这几篇，先把它们凑齐就能让陌生访客完整跑通：

1. 部署形态总览
2. 快速开始（源码 docker compose）
3. CI 部署后追加 CLIProxyAPI sidecar
4. 环境变量参考
5. 添加第一个上游
6. 创建客户端 API Key
7. 通过 AutoRouter 调用模型
8. CLIProxyAPI 首次使用指南
9. 整体架构总览
10. 请求生命周期

承载形态：B 静态站 + C UI 内嵌指南

按读者所处的部署状态切分两套载体，避免双向膨胀。

B. 静态文档站（VitePress + GitHub Pages）

承载所有 34 篇长篇文档主体。

• 读者：部署前 / 决策中 / 排障期
• 版本绑定：与 git tag 绑定，支持多版本切换
• 入口：GitHub README、搜索引擎
• 不依赖运行中的实例，部署前即可访问

不选 Nextra（绑死 Next.js，依赖耦合过重）、Docusaurus（相对偏重）、MkDocs Material（Python 栈与项目 Node 栈不匹配）。

C. 应用内 UI 嵌入式指南

不是独立文档站，而是把 B 里关键决策点的提示、在用户最容易出错的瞬间塞回 UI。具体形态：

• 实例表单字段 helper text 与示例：sidecar 模式时下方提示固定为 http://cliproxyapi:8317，外部模式时切换为「填外部 CPA 的转发地址」
• 连通性检测错误「地址不可达」扩展为「地址不可达。若 AutoRouter 与 CLIProxyAPI 同处 Docker 网络，请改用容器服务名而非 localhost」并附「了解更多」深链到 B 站点对应锚点
• 空状态文案：账号面板、上游列表、Key 列表的空状态都给出「先做什么」引导
• 关键操作的确认对话框补「会发生什么」简述

C 不再需要「开发独立 /docs 路由」，而是「在现有组件里补 helper text、空状态文案、错误提示」，可以拆成若干小改动嵌入到正常迭代中。

实施计划

Phase 1：搭建 B 静态站 + 第一批 10 篇

• 引入 VitePress（docs/.vitepress/config.ts、docs/index.md）
• 整理 docs/ 目录结构：guide/deployment/、guide/usage/、architecture/
• 撰写第一批 10 篇文档（10/10 全部合入 master 并部署到 Pages：部署 4 + 使用 5 + 架构 2，含 cliproxy-first-time 由 PR docs(usage): CLIProxy 首次使用 + 模型路由 + 负载均衡 + 熔断配置（#167 Phase 2 PR4） #181 补齐）
• CI workflow docs.yml：监听 docs/** 变更，pnpm docs:build + actions/deploy-pages@v4 部署到 GitHub Pages（实际未用 peaceiris，改用官方 Pages action）
• README.md / README_EN.md 减负：已加 Docs badge 链接到 Pages 站点（完整减负与 CPA 章节链接留待 Phase 1 收尾）
• 多语言：VitePress locales 已配 zh-CN（root）+ en（placeholder），后续翻译滚动补齐
• 可选：绑定自定义域名（CNAME）

Phase 2：补齐剩余 24 篇

按主题分批，每批一个小 PR：

• 使用指南剩余 9 篇 9/9 全部合入：cliproxy-first-time + model-routing + load-balancing + circuit-breaker-config + cliproxy-modes + cliproxy-egress-proxy + logs-stats + request-recording + troubleshooting
• 部署指南剩余 6 篇 6/6 全部合入（PR docs: fill phase 2 final 9 docs (deployment 6 + architecture 6C, #167) #188）：github-actions + database + https-proxy + persistence-backup + upgrade-rollback + troubleshooting
• 架构介绍剩余 9 篇 9/9 全部合入（6A PR docs(architecture): fill phase 2 batch 6A — core mechanism trio (#167) #184 + 6B PR docs(architecture): phase 2 batch 6B — integration & runtime trio #185 + 6C PR docs: fill phase 2 final 9 docs (deployment 6 + architecture 6C, #167) #188）：upstream-model + failover-circuit + database-schema + cliproxy-integration + security + i18n + testing + contributing + release

Phase 3：C UI 内嵌指南补强

可与 Phase 2 并行进行，按页面分批：

• CLIProxyAPI 实例表单：字段 helper text + 连通性检测错误信息扩展（PR feat(ui): phase 3 嵌入指南 — helper text、空状态与对话框文案 (#167) #189）
• 空状态文案（账号面板、上游列表、Key 列表）（PR feat(ui): phase 3 嵌入指南 — helper text、空状态与对话框文案 (#167) #189）
• 池上游对话框、OAuth 登录对话框补简短说明（PR feat(ui): phase 3 嵌入指南 — helper text、空状态与对话框文案 (#167) #189）
• 关键操作确认对话框补「会发生什么」简述（PR feat(ui): phase 3 嵌入指南 — helper text、空状态与对话框文案 (#167) #189）

防膨胀的机械约束

1. B 站点首页放显眼的「打开管理后台」入口；C 的「了解更多」一律链回 B 对应锚点。读者永远知道下一跳。
2. C 不写长篇内容，凡是超过两三行的解释一律写到 B、C 只放摘要 + 链接。
3. 每篇 B 文档撰写前先检查：是否与现有 docs/cliproxy-deployment.md、docs/circuit-breaker.md 重复，重复则合并而非新增。

验收标准

• 一个完全陌生的访客从 GitHub README 出发，能在不查阅任何对话记录的前提下，独立完成「CI 部署 → 补 sidecar → 登记 CPA 实例 → OAuth 登录 → 池上游创建 → 客户端调用成功」全流程。
• 第一批 10 篇文档全部上线、Pages 站点可访问、README 链接到位。