272 lines
13 KiB
Markdown
272 lines
13 KiB
Markdown
# 两天流程复盘 · 大白话版
|
||
|
||
> 目的：把 2026-11-04 ~ 11-05 这两天做的事，用**不懂技术也能看懂**的方式讲清楚。
|
||
> 读完你应该能回答：我搭了什么？每一块是干嘛的？哪些是 AI 替我做的？出问题我该看哪里？
|
||
|
||
---
|
||
|
||
## 〇、先用一个比喻把整件事说清
|
||
|
||
把这件事想象成**"把一张只能在自家店里刷的会员卡，改造成任何 ATM 都能取钱的银行卡"**：
|
||
|
||
| 现实世界 | 我们的系统 |
|
||
|---|---|
|
||
| 你的 Google AI Pro 会员卡 | Google 订阅账号（有额度，但只能在 Google 自己店里用） |
|
||
| **改装刷卡机** | **CPA** —— 让这张会员卡能在任何地方被"读" |
|
||
| **自家开的银行柜台** | **New API** —— 统一对外、记账、发副卡给你各个工具 |
|
||
| 银行门口的正式管道 | 你的域名 `api.trivoo.website`（HTTPS 加密） |
|
||
| 你家里的水龙头 | Codex / Claude Code（只会用标准接口） |
|
||
| 临时挖的运钞暗道 | `tunnel.bat`（SSH 隧道，只在需要时打开） |
|
||
|
||
一句话总结：**你花钱买的 Google 订阅，被改造成了"标准 API"，现在你的编程工具能直接白嫖它。**
|
||
|
||
---
|
||
|
||
## 一、起点 vs 终点
|
||
|
||
### 起点（11月4日之前）
|
||
- ✅ 有一台腾讯云新加坡服务器（Ubuntu 24.04，43.156.118.130）
|
||
- ✅ 上面已经跑着 New API 网关（域名 `api.trivoo.website`，能调 DeepSeek 等）
|
||
- ❌ 有一个 Google AI Pro 订阅，**但只能在网页上用，编程工具调不了**
|
||
|
||
### 终点（11月5日之后）
|
||
- ✅ 同一个域名、同一把钥匙，**现在多了 Google 的 Gemini / Claude 模型可用**
|
||
- ✅ Codex、Claude Code 换一下配置就能用上
|
||
- ✅ 全部跑在你自己的服务器上，数据不经过任何第三方
|
||
|
||
---
|
||
|
||
## 二、7 个关键名词，一句话一个
|
||
|
||
| 名词 | 一句话解释 | 生活比喻 |
|
||
|---|---|---|
|
||
| **反代** | 用你的账号凭证，伪装成官方客户端去调上游，对外输出标准 API | 改装刷卡机 |
|
||
| **CPA**（CLIProxyAPI） | 一个开源软件，专门干上面这件事（支持 Google/Claude/Codex/Grok/Kimi/Meta 等） | 那台改装机的品牌型号 |
|
||
| **New API** | 一个网关软件：统一入口、发钥匙、记账、看日志 | 银行柜台 |
|
||
| **Docker / 容器** | 把软件连它的环境一起打包成"盒子"，跑起来互不干扰 | 一个个集装箱 |
|
||
| **SSH 隧道** | 在你电脑和服务器之间临时架一条加密通道，让本地能访问服务器内部服务 | 运钞暗道 |
|
||
| **OAuth** | "用 Google 账号授权"，**不交出密码**，只给一张有期限的通行证 | 刷脸进店，不给家里钥匙 |
|
||
| **API Key / 令牌** | 一串密码字符串，证明"你有权调用" | 银行卡 + 密码 |
|
||
|
||
---
|
||
|
||
## 三、三把钥匙别搞混（最容易糊的地方）
|
||
|
||
你的系统里现在有**三把不同的钥匙**，用途完全不同：
|
||
|
||
| 钥匙 | 长什么样 | 谁用它 | 用来干什么 |
|
||
|---|---|---|---|
|
||
| **① New API 令牌** | `sk-xxxxxx` | 你的 Codex / ccswitch | 客户端 → 连你的银行柜台（New API） |
|
||
| **② CPA_API_KEY** | `sk-cpa-xxxxxx` | New API | 银行柜台 → 连改装机（CPA） |
|
||
| **③ MGMT_KEY** | 一串随机字符 | 你本人（浏览器） | 登录 CPA 管理面板，改配置、看凭证 |
|
||
|
||
**打款路径就是**：
|
||
```
|
||
Codex（拿①）→ New API（拿②）→ CPA → Google（用 OAuth 通行证）
|
||
```
|
||
|
||
① 和 ② 都存在服务器上（`/opt/cpa/KEYS.txt` 里是 ② 和 ③），① 在 New API 后台建。
|
||
|
||
---
|
||
|
||
## 四、这两天实际发生了什么（时间线）
|
||
|
||
### 【第 1 天 · 11月4日】搞清楚 + 做准备
|
||
|
||
| 时间 | 发生了什么 |
|
||
|---|---|
|
||
| 上午 | 你贴了和茨米的聊天记录，我帮你按时间重排整理 |
|
||
| 上午 | 明确"反代"是什么、和 CPA 什么关系、三层生态（账号层 / 网关层 / 中转站层） |
|
||
| 上午 | 你问"反代和 CPA 是不是同一个东西"——结论：反代是**概念**，CPA 是**软件** |
|
||
| 中午 | 读了你自己的《NewAPI 实战指南》，把你的现状对号入座 |
|
||
| 下午 | **明确目标**：Gemini Pro 账号 → API → 给 Claude Code 用，装在乌班图（新加坡服务器） |
|
||
| 下午 | 我先做了一版"我远程全自动部署"方案，**你拒绝了权限**（很对，服务器是你的） |
|
||
| 傍晚 | 改成"我出脚本、你动手"模式 |
|
||
| 傍晚 | 查官方文档，确认 CPA 的镜像、端口、面板地址、登录命令 |
|
||
| 晚上 | **产出部署包**：`deploy-cpa.sh`（部署脚本）+ `tunnel.bat`（隧道）+ `01-部署操作手册.md` |
|
||
|
||
### 【第 2 天 · 11月5日】部署 + 踩坑 + 跑通
|
||
|
||
| 时间 | 发生了什么 | 结果 |
|
||
|---|---|---|
|
||
| 08:31 | 你要操作步骤，我给了完整 6 步 | — |
|
||
| 08:47 | 你跑完脚本，打开面板 | ❌ 报 403 |
|
||
| 08:50 | 我诊断：`allow-remote: false` 把管理 API 关了 | 给你两条命令改掉 |
|
||
| 09:10 | 改完重启，面板登录成功 | ✅ |
|
||
| 09:26 | OAuth 登录 Google 账号（Antigravity 渠道） | ✅ 凭证落盘，模型列表出来 |
|
||
| 10:12 | New API 加渠道、拉模型、测速 | ✅ 全链路通 |
|
||
| 10:52 | 你确认跑通，我做了复盘对比 | ✅ |
|
||
| 11:05 | 你想试 Meta Muse | 查文档确认支持 |
|
||
| 11:19 | 走到 Meta 绑卡页面：**要按 token 付费，无免费层** | ❌ 放弃 |
|
||
| 11:41 | 检查 Meta 账号有没有社交资产（担心封号连坐） | 干净，但已无必要 |
|
||
|
||
---
|
||
|
||
## 五、"AI 帮你做的" 到底做了什么（消除黑箱感）
|
||
|
||
你说"有些都是 AI 帮我实现"——下面把它们全部拆开，白纸黑字，随时可查：
|
||
|
||
### 1️⃣ `deploy-cpa.sh`（部署脚本）做了 7 件事
|
||
|
||
| 段落 | 干了什么 |
|
||
|---|---|
|
||
| [1] 预检 | 确认是 root 权限、列出当前容器 |
|
||
| [2] 建目录 | 新建 `/opt/cpa/`（含 auths=存凭证 / logs=日志 / plugins=插件） |
|
||
| [3] 生成配置 | 用 `openssl rand` 随机生成两把钥匙，写进 `config.yaml` + `KEYS.txt` |
|
||
| [4] 写 compose | 定义"用哪个镜像、开哪些端口、挂哪些目录" |
|
||
| [5] 建网络 | 建 `ai-net` 内网，把已有的 new-api 容器拉进来 |
|
||
| [6] 启动 | `docker compose up -d` 把容器跑起来 |
|
||
| [7] 自检 | 不带钥匙应得 401、带钥匙应得 200、测容器互通、打印钥匙 |
|
||
|
||
**它没做的事（很重要）**：没碰你的 new-api 文件、没碰 nginx、没碰 Xray、没在防火墙开任何端口。
|
||
|
||
### 2️⃣ `tunnel.bat`（隧道）就是一条命令
|
||
|
||
```bat
|
||
ssh -N -L 8317:127.0.0.1:8317 ... ubuntu@43.156.118.130
|
||
```
|
||
|
||
拆开看：
|
||
- `ssh` = 连到服务器
|
||
- `-N` = 只做端口转发，不执行远程命令
|
||
- `-L 8317:127.0.0.1:8317` = "把我本地的 8317 端口，接到服务器的 8317 端口"
|
||
|
||
**为什么要它**：CPA 的面板和授权回调端口**只对服务器自己开放**（安全设计），你本地浏览器想访问，就得有这么一条通道。就像银行金库不对大街开门，但给你留了条内部通道。
|
||
|
||
### 3️⃣ 那两条排障命令
|
||
|
||
```bash
|
||
sed -i 's/allow-remote: false/allow-remote: true/' /opt/cpa/config.yaml # 改一个开关
|
||
docker compose restart # 重启生效
|
||
```
|
||
|
||
为什么必须改：原本关掉远程管理是出于安全，但请求经过 Docker 内部转发后，CPA 把来源 IP 看成内网地址，误判为"远程访问"而拦截。因为端口本来就绑死 `127.0.0.1`（公网根本进不来），所以打开这个开关**不降低安全性**。
|
||
|
||
### 4️⃣ New API 里点的那几下
|
||
|
||
你在界面里做的操作，本质是往数据库里写了一条记录：
|
||
> "有一个叫 `CPA-Gemini-OpenAI` 的上游，地址是 `http://cli-proxy-api:8317`，钥匙是 `sk-cpa-xxx`，它支持这些模型：gemini-3-flash…"
|
||
|
||
以后任何客户端拿着 New API 的令牌来，New API 就按这条记录转发给 CPA。
|
||
|
||
---
|
||
|
||
## 六、现在的系统长什么样（数据怎么流）
|
||
|
||
```
|
||
【你的 Windows 电脑】
|
||
Codex / Claude Code / ccswitch
|
||
│ ① 用 New API 令牌（sk-xxx）
|
||
│ ② HTTPS 加密
|
||
▼
|
||
【腾讯云新加坡服务器 · Ubuntu 24.04】
|
||
┌─────────────────────────────────────────┐
|
||
│ Nginx（已有）：管 HTTPS 证书、转发 │
|
||
│ ▼ │
|
||
│ New API 容器（已有）：发钥匙、记账、看日志 │
|
||
│ │ 用 CPA_API_KEY（sk-cpa-xxx） │
|
||
│ │ 走 Docker 内部网络 ai-net │
|
||
│ ▼ │
|
||
│ CPA 容器（新装）：账号→API 转换 │
|
||
│ │ OAuth 通行证（存在 auths/ 里） │
|
||
└────────┼────────────────────────────────┘
|
||
▼
|
||
Google（Gemini 模型 + 反重力渠道的 Claude 模型）
|
||
```
|
||
|
||
**一次请求的完整旅程**（跟着数据走一遍）：
|
||
|
||
1. 你在 Codex 里输入一句话
|
||
2. Codex 拿 New API 令牌，把请求发到 `https://api.trivoo.website`
|
||
3. Nginx 解密 HTTPS，转给 New API 容器
|
||
4. New API 查令牌 → 合法 → 查模型 → 找到 `CPA-Gemini-OpenAI` 渠道
|
||
5. New API 拿 CPA_API_KEY，通过内网发给 CPA
|
||
6. CPA 从 `auths/` 里挑一个 Google 凭证，把 OpenAI 格式的请求翻译成 Google 能懂的格式
|
||
7. Google 返回结果，CPA 再翻译回标准格式，原路返回
|
||
8. Codex 显示回答；同时 New API 记了一笔账（模型、token、耗时）
|
||
|
||
---
|
||
|
||
## 七、为什么这么设计（每个决定的理由）
|
||
|
||
| 决定 | 理由 |
|
||
|---|---|
|
||
| 为什么不装在你本地电脑 | ① Google 对中国大陆 IP 有风控 ② 你的电脑不会 24 小时开机 ③ 服务器出口是新加坡，天然绕开限制 |
|
||
| 为什么端口只绑 `127.0.0.1` | 让服务"只有服务器自己能用"，公网谁都摸不到，连防火墙规则都不用改 |
|
||
| 为什么用隧道而不是把面板开放到公网 | 面板能改配置、看凭证，等于系统总闸，绝不能暴露 |
|
||
| 为什么还要过一层 New API | 统一入口（所有工具记一个地址）、记账、看日志、方便以后加别的上游 |
|
||
| 为什么不直连 CPA 就完事 | 直连也行（少一跳、延迟低），但需要一直开着隧道；两条路可以并存 |
|
||
| 为什么要两把钥匙 | 分离权限：管理钥匙只给你本人，API 钥匙只给程序，泄一个不牵连另一个 |
|
||
|
||
---
|
||
|
||
## 八、日常你自己能做的事（速查）
|
||
|
||
在 OrcaTerm 里（或 SSH 上去）：
|
||
|
||
```bash
|
||
# 看 CPA 活着没
|
||
sudo docker ps | grep cli-proxy-api
|
||
|
||
# 看 CPA 日志（实时）
|
||
cd /opt/cpa && sudo docker compose logs -f --tail=50
|
||
|
||
# 重启 CPA（改完配置必须重启）
|
||
cd /opt/cpa && sudo docker compose restart
|
||
|
||
# 看两把钥匙
|
||
sudo cat /opt/cpa/KEYS.txt
|
||
|
||
# 看已登录的账号凭证
|
||
sudo ls /opt/cpa/auths
|
||
|
||
# 看 CPA 当前提供哪些模型
|
||
curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer $(sudo grep -oE 'sk-cpa-[0-9a-f]+' /opt/cpa/config.yaml | head -1)"
|
||
```
|
||
|
||
**铁律两条**：
|
||
1. 改了 `/opt/cpa/config.yaml` → 一定要 `docker compose restart`
|
||
2. 如果哪天重建了 new-api 容器 → 补一句 `sudo docker network connect ai-net new-api`
|
||
|
||
---
|
||
|
||
## 九、出问题看哪里（排错路线图）
|
||
|
||
| 现象 | 先看这里 |
|
||
|---|---|
|
||
| Codex 报 404 | 模型名对不对（去 New API 渠道里重新拉列表） |
|
||
| 报 401 | 令牌对不对（Codex 里的 sk-xxx / New API 里的 sk-cpa-xxx） |
|
||
| 报 429 | Google 限流，等几分钟，不是坏了 |
|
||
| 面板打不开 | tunnel.bat 窗口是不是关了 |
|
||
| New API 渠道测试失败 | `docker logs --tail=50 cli-proxy-api` 看 CPA 说什么 |
|
||
| 模型列表是空的 | `sudo ls /opt/cpa/auths` 有没有凭证，没有就重新 OAuth 登录 |
|
||
| 全部都不对 | 从上往下查：容器活着吗 → 面板能进吗 → 凭证在吗 → 渠道测速过吗 |
|
||
|
||
---
|
||
|
||
## 十、术语中英对照（以后搜索用）
|
||
|
||
| 中文 | 英文 | 说明 |
|
||
|---|---|---|
|
||
| 反代 | reverse proxy | 转发/转换请求的中间服务 |
|
||
| 上游 | upstream | 最终提供模型的一方（这里是 Google） |
|
||
| 渠道 | channel | New API 里的一条上游配置 |
|
||
| 凭证 / 认证文件 | auth / auth file | OAuth 登录后存下来的通行证 |
|
||
| 令牌 | token / API key | 调用凭证 |
|
||
| 管理密钥 | management key | 管理面板登录用 |
|
||
| 限流 | rate limit / 429 | 请求太快的临时拒绝 |
|
||
| 容器 | container | Docker 里的运行单元 |
|
||
|
||
---
|
||
|
||
## 十一、最后一句话总结
|
||
|
||
**你这两天做的事情，本质是给自己的 AI 工具链加了一条"免费高速通道"**：
|
||
|
||
- 过去：Google 订阅只能在网页用 → 浪费
|
||
- 现在：同一个订阅变身 API → Codex / Claude Code 都能用
|
||
- 全程：数据在你自己的服务器上跑，不经过任何第三方中转
|
||
- 成本：只花服务器钱（本来就在付），模型额度用的是你已付费的订阅
|
||
|
||
**唯一的代价**：这是一条"非官方"路径（属于灰色地带），上游随时可能调整。所以随时记住——**这套东西是可拆的、可放弃的**，不会绑架你。
|