%E5%8F%8D%E4%BB%A3%E7%A0%94%E7%A9%B6%E7%AC%94%E8%AE%B0.md

# AI API 反代（反向代理）研究笔记

> 整理日期：2026-11-04
> 资料来源：CLIProxyAPI / new-api / sub2api / one-api / workbuddy2api-panel 官方 README（一手抓取）
> 目标：搞清楚"反代"到底是什么、CPA / new-api / sub2api / workbuddy2api 各是什么角色、"20x 这类中转站"的真相

---

## 0. 一句话理解

**反代 = 自己跑一个程序，拿着你"网页版/订阅版账号"的登录凭证，伪装成官方客户端去调上游接口，对外暴露成一个标准 OpenAI 兼容 API。**

客户端（Cherry Studio、ChatBox、Claude Code……）只认标准 API，根本不知道背后是白嫖的网页/订阅账号。

---

## 1. 先分清两种"反代"

| | 传统反代（Nginx/Caddy） | AI 圈说的反代 |
|---|---|---|
| 干什么 | 转发 HTTP 请求、隐藏源站、负载均衡 | **把账号变成 API**（协议转换 + 账号池） |
| 谁在用 | 运维 | 白嫖党 / 中转站站长 |
| 难点 | 配置 | 逆向上游协议 + 对抗风控 |

底层都是"代理转发"，但 AI 圈反代的核心价值是**协议转换**：上游根本没有开放 API（或 API 按 token 收钱），反代硬是用你的网页/订阅账号造出一个 API 来。

---

## 2. 动机：为什么要反代

- **Gemini**：网页版 / AI Studio 免费，官方 API 按 token 计费 → 账号反代 = 免费用
- **Claude / GPT 订阅**：Claude Pro、ChatGPT Plus 包月，API 另收费 → 订阅反代成 API，包月费摊进 API 调用
- **CodeBuddy(WorkBuddy)**：只有客户端、没有开放 API → workbuddy2api 硬造一个
- **统一格式**：背后无论哪家，客户端只写一套 OpenAI 格式

---

## 3. 原理拆解：一次请求的完整旅程

以 CPA（CLIProxyAPI）+ Gemini 为例：

```
你的电脑
┌──────────────────────────────────────────────────────┐
│  客户端 (Cherry Studio 等)                             │
│    │ ① POST /v1/chat/completions                     │
│    │    Authorization: Bearer sk-你自己设的key         │
│    ▼                                                 │
│  反代网关 (CPA, 本地 127.0.0.1:8317)                   │
│    ② 验 key → ③ 账号池选号 → ④ 协议转换                │
│    │ ⑤ 用该账号的 OAuth token，伪装成 Gemini CLI       │
└────┼─────────────────────────────────────────────────┘
     ▼ （出站走代理 / 外国 IP）
  Google 内部接口
     │ ⑥ SSE 流式返回
     ▼
  网关把流转成 OpenAI 格式 → 客户端收到标准响应
```

四个关键部件：

1. **凭证（auths）**：OAuth 登录拿到的 accessToken / refreshToken，存本地文件（`auths/*.json`），程序自动刷新。这就是"你的账号"本体。
2. **协议转换**：OpenAI `chat/completions` ↔ 上游私有格式（Gemini internal、Claude Messages、CodeBuddy SSE……）双向翻译，流式 SSE 逐帧转换。
3. **账号池治理**（工程量最大的部分）：
   - 轮询 / 加权选号（快过期额度优先消耗）
   - 429 限流 → 软冷却 + 指数退避；402 余额耗尽 → 硬冷却到次日
   - 熔断、会话粘性（同一会话固定同号，保证多轮上下文不跳号）
4. **自签发 key**：网关对外发自己的 `sk-xxx`，客户端拿它调用，真实凭证永远不离开你的机器。

---

## 4. 为什么必须外国 IP

- Google / OpenAI / Anthropic 对中国大陆 IP 有地区限制或风控，**OAuth 登录这一步就过不去**
- 即使登录成功，国内 IP 直连调用风控打分高 → 容易封号
- 所以两条路：本地部署 + 网关出站挂梯子；或直接部署在国外服务器

---

## 5. 生态地图：三层结构

```
第 1 层：账号 → API（协议转换层）
   CLIProxyAPI、sub2api、workbuddy2api
   输入：OAuth 账号 / 订阅 / API key
   输出：OpenAI 兼容 API
         │
         ▼
第 2 层：网关 / 分发（管理层）
   one-api、new-api
   输入：各种"渠道"（官方 key、反代端点、中转站 key）
   输出：统一 API + 用户 / 额度 / 计费 / 负载均衡
         │
         ▼
第 3 层：商业中转站（别人替你搭好的第 1+2 层）
   PackyCode、APIKEY.FUN……（CPA README 赞助商列表一大排）
   直接卖 key 给你 —— 之前用的 20x 就是这类
```

**20x 的真相**：站长在自己服务器上跑账号池（批量注册/收购的账号）+ 网关，把白嫖额度包装成 key 卖给你。所以价格能压到官方一折以下——因为上游根本不是官方 API。这也解释了朋友那句"不然哪里有那么多 api 可以用"。

典型自建组合：**CPA（白嫖账号）→ new-api（统一分发、记用量）→ 各客户端**

同类思路的其他出口：MCP（chat-on-steroids、MCPod 把网页版 GPT 接成 MCP 工具）——同一套逆向，换个协议出口而已。

---

## 6. 五个工具横评

| 工具 | 定位 | 吃什么账号 | 吐什么 | 部署 | 状态 |
|---|---|---|---|---|---|
| **CLIProxyAPI (CPA)** | 账号→API | Gemini / Codex / Claude / Grok / Kimi / Meta 等的 OAuth 或 key | OpenAI / Claude / Gemini / Codex / Grok 全兼容 | 单文件 / Docker / **桌面版 EasyCLIProxyAPI** | ✅ 活跃，中文文档 help.router-for.me |
| **sub2api** | 账号→API + 计费分发 | Claude / Codex / Grok / Antigravity 等订阅号 | OpenAI / Anthropic 兼容 + 用户/额度/支付系统 | Docker Compose（Go + Vue + PG + Redis） | ✅ 活跃，README 顶部明确警告 ToS 风险 |
| **workbuddy2api-panel** | 账号→API | 腾讯 CodeBuddy / WorkBuddy | OpenAI 兼容 | Docker / Windows 单文件 exe | ⚠️ **2026-10-21 已停止维护** |
| **one-api** | 网关分发 | 各种官方 API key 渠道 | OpenAI 格式统一出口 | Docker，初始 root/123456 | ✅ 老牌"祖师爷"（MIT） |
| **new-api** | 网关分发 | 渠道（可挂反代端点/中转站 key） | OpenAI / Claude / Gemini + 用户/计费/插件市场 | Docker 一条命令起 | ✅ 活跃（one-api 二开，功能更多） |

选型直觉：

- 只想**用自己账号白嫖 Gemini/Claude** → CPA（新手直接上桌面版）
- 想**管一堆渠道、分发给团队** → new-api
- 想**搞订阅账号池运营**（站长向）→ sub2api
- workbuddy2api → 别再投入时间（见下节）

---

## 7. 重要情报：workbuddy2api 已死

朋友 10/17 还在推荐它，但 **10/21 官方宣布停止维护**，README 给出三个原因：

1. **上游已开始禁用反代**——WorkBuddy 对非官方客户端的识别与拦截正在收紧（通道校验、账号限制），反代通道存活周期不可控
2. 个人精力有限，无力长期跟进协议变化与风控对抗
3. 非法转卖泛滥（批量小号、卡密售卖），与项目初衷相悖

这件事本身就是最好的教材：**反代是猫鼠游戏，上游一收紧，工具随时死**。sub2api 的 README 同样把"ToS 风险、封号自负"写在最顶上。

---

## 8. 风险清单（研究归研究，心里要有数）

| 风险 | 说明 |
|---|---|
| 封号 | 违反上游 ToS 是明确的；轻则限流重则封号（WorkBuddy 已动手） |
| 随时失效 | 上游改协议 / 收紧风控 → 工具停更（活例：workbuddy2api） |
| 中转站不可信 | 你的**全部对话内容和 key** 都过别人服务器；跑路、泄露、掺水（偷换便宜模型）都常见 |
| 法律合规 | one-api README 特别提醒《生成式AI服务管理暂行办法》：国内对公众提供未备案生成式 AI 服务违规。自用没问题，**别搞成对外服务** |
| 凭证安全 | auths/ 里是明文 token；来路不明的"收费版/卡密版"可能直接偷号 |

---

## 9. 上手路线（Windows + F:\AI\docker + 梯子）

**第一步（零门槛，跑通"账号→API"流程）**
装 EasyCLIProxyAPI（CPA 官方桌面客户端，图形界面、一键启停），OAuth 登录一个 Google 账号，本地就有 `127.0.0.1:8317/v1` 可调，用 curl 或 Cherry Studio 打一发。

**第二步（练 Docker，理解"分发层"）**
`docker run` 起 new-api（不需要任何 AI 账号，纯看网关概念：渠道/令牌/负载均衡），再把第一步 CPA 的端点作为一个"渠道"挂进去——这正是聊天记录里"放在 CPA 里面用"的玩法：CPA 做上游，new-api 做分发。

**第三步（可选，网络进阶）**
整套 compose 化，跑通"本地容器 + 梯子出站"：容器内访问宿主机代理用 `host.docker.internal:7890`（按梯子实际端口改），CPA 也在配置里支持出站代理。

不建议再花时间研究 workbuddy2api。

---

## 10. 参考链接

- CLIProxyAPI（CPA）：https://github.com/router-for-me/CLIProxyAPI （中文文档 https://help.router-for.me/cn/ ）
- CPA 桌面客户端：https://github.com/router-for-me/EasyCLIProxyAPI
- new-api：https://github.com/QuantumNous/new-api （文档 https://docs.newapi.ai ）
- one-api：https://github.com/songquanpeng/one-api
- sub2api：https://github.com/Wei-Shaw/sub2api
- workbuddy2api-panel（已停维护）：https://github.com/linguo2625469/workbuddy2api-panel
- MCP 方向：https://github.com/totec448-spec/chat-on-steroids 、https://github.com/fb0sh/MCPod

---

## 11. 结合我自己的 NewAPI 实战架构再理解一遍

> 参照：《NewAPI搭建与上线完整实战指南》（F:\AI\Obsidian\工具相关\）
> 实战环境：腾讯云新加坡 2C2G + Xray 共存，域名 api.trivoo.website

已上线的栈，按三层模型对号入座：

```
Cline / Cherry Studio
   │ HTTPS 443
   ▼
Nginx 反向代理            ← 「字面意义的反代」：转发 + TLS + 隐藏后端（指南第五阶段）
   │ 127.0.0.1:3000
   ▼
New API 容器              ← 第2层 网关分发：渠道/令牌/计费/负载均衡
   ├─→ 渠道1：DeepSeek 官方 API    （正规军，按量付费）
   └─→ 渠道2：apikey.fan           ← 第3层 商业中转站（背后是站长搭的第1层账号池）
```

四条结论：

1. **同一套架构里同时存在两种"反代"**：Nginx（字面意义的反向代理）+ New API（广义的转发/中继，源码模块就叫 relay）。而 AI 圈黑话里的"反代"特指**第 1 层：账号→API 协议转换**。
2. **反代是概念，CPA 是软件**。"反代和 CPA 是不是一回事" ≈ "数据库和 MySQL 是不是一回事"。CPA 是黑话意义上"反代"的最主流实现之一。
3. 现状 = 自建第 2 层（new-api）+ 买第 3 层（apikey.fan 渠道）。补上 CPA（第 1 层）即完整闭环：**账号 → CPA → 挂成 new-api 渠道 → api.trivoo.website 统一分发**。
4. 新加坡服务器本身就是外国 IP，CPA 放这台机器上出站不需要梯子；唯一要浏览器的是 OAuth 授权那一步，常规做法是本地登录后把 `auths/*.json` 凭证传上服务器（或用支持远程 OAuth 的管理面板）。

一个佐证细节：apikey.fan 正好出现在 CPA 和 sub2api 官方 README 的赞助商列表里（"价格低至官方原价的 7%"）——第 3 层中转站的本质一眼见底。