01-overview

01. 概念与整体架构 §

CPA 是做什么的 §

CLIProxyAPI（以下简称 CPA）把多个原本只能在本地交互登录的 AI CLI（Gemini CLI、ChatGPT Codex CLI、Claude Code、Antigravity 等）封装成一个长期运行的 HTTP API 服务，对外暴露 OpenAI / Gemini / Claude / Codex 兼容协议。

它的核心价值：

• 用 OAuth 免费额度调高级模型：比如 ChatGPT 的 Plus/Pro 账号、Google 的 Gemini 免费额度、Claude Code 订阅，原本只能在 IDE/CLI 里用，CPA 让你可以用任何兼容客户端调用。
• 多账号池化：可以挂多个 OAuth 账号 + 多个 API key，自动轮询、配额耗尽自动切换。
• 协议转换：客户端用 OpenAI 协议来，CPA 内部转成 Codex/Gemini/Claude 协议去上游。

架构（这次部署的实际样子） §

                                    ┌──────────────┐
[ 你的电脑 ]                        │  腾讯云 VPS   │
   │                                │              │
   │ 1) HTTPS → :8317               │  ┌────────┐  │
   ├───────────────────────────────►│  │  CPA   │  │  容器 cli-proxy-api (bridge: cliproxyapi_default)
   │   /v1/chat/completions         │  │ :8317  │  │  Auth: /root/CLIProxyAPI/auths/codex-*.json
   │   /v1/models                   │  └───┬────┘  │  Config: /root/CLIProxyAPI/config.yaml
   │   /management.html             │      │       │
   │                                │      │ HTTP_PROXY=http://172.18.0.1:7890
   │                                │      ▼       │
   │                                │  ┌────────┐  │  容器 mihomo (network: host)
   │                                │  │ mihomo │  │  订阅 → 美国节点
   │                                │  │ :7890  │  │
   │                                │  │ :9090  │  │  RESTful 控制（切节点）
   │                                │  └───┬────┘  │
   │                                │      │       │
   └────────────────────────────────┴──────┼───────┘
   2) SSH 隧道 -L 1455:127.0.0.1:1455      │
      （仅 OAuth 登录时用）                ▼
                              [ChatGPT / Google / Anthropic / Cloudflare]

端口规划 §

CPA 容器默认暴露的几个端口（实际由你的 docker run/compose 决定）：

端口	用途	是否需要外网开放
8317	主 API 端口（也是管理面板挂载点）	需要（建议白名单）
1455	Codex/ChatGPT OAuth 回调	仅登录瞬间需要，建议走 SSH 隧道
8085	Gemini OAuth 回调	仅登录瞬间需要，同上
54545 / 51121 / 11451	Claude / 其它 OAuth 回调	仅登录瞬间需要，同上

mihomo 容器（host 网络）：

端口	用途
7890	mixed-port（http + socks5）
9090	external-controller（API + 面板）
1053	DNS（自定义，避免和 systemd-resolved 53 冲突）

目录约定 §

整篇笔记里假定的服务器路径：

/root/CLIProxyAPI/
├── config.yaml          # 主配置（挂进容器 /CLIProxyAPI/config.yaml）
├── auths/               # OAuth 凭据（挂进容器 /root/.cli-proxy-api）
└── logs/                # 日志（挂进容器 /CLIProxyAPI/logs）

/root/mihomo/
├── config.yaml          # 订阅生成的 clash 配置
└── docker-compose.yml   # mihomo 启动脚本

工作模式 §

启动后 CPA 会做这几件事：

1. 加载 config.yaml → 注册 OpenAI/Gemini/Claude 兼容路由
2. 扫描 auth-dir（默认 ~/.cli-proxy-api）下的 *.json，每一个对应一个 OAuth 凭据
3. 起 file watcher，配置或凭据变化自动热加载（不需要 restart 容器）
4. 周期性刷新模型列表、Antigravity 版本号等元信息
5. 注册管理路由 /v0/management/* 和面板 /management.html（要求设置了 secret-key）

接下来按 02-server-prep.md 准备服务器环境。