153 lines
8.6 KiB
Markdown
153 lines
8.6 KiB
Markdown
# 需求与实现流程总览 —— Gemini Pro 变 API 给 Claude Code 用
|
||
|
||
> 项目代号：CPA 上线
|
||
> 整理日期：2026-11-04
|
||
> 配套文件：`01-部署操作手册.md`（照着做的分步手册）、`deploy-cpa.sh`（部署脚本）、`tunnel.bat`（SSH 隧道）
|
||
|
||
---
|
||
|
||
## 一、需求描述（原始诉求）
|
||
|
||
**你的原话：**
|
||
|
||
> 目的是想用 gemini 的 pro 账号，通过 API 的方式给 claude 调用。要在乌班图系统上搭建，不在本地电脑。
|
||
|
||
**翻译成大白话：**
|
||
|
||
你有一个 Google 账号（国内账号），已经/即将激活 **Google AI Pro 订阅**（Gemini Pro）。你不满足于在网页里跟它聊天，而是要把它**变成一个标准 API 服务**，让你本地电脑上的 **Claude Code**（以及任何支持填 API 的工具）随时调用——把 Gemini Pro 当成 Claude Code 的"发动机"。
|
||
|
||
**约束条件：**
|
||
|
||
| # | 约束 | 说明 |
|
||
|---|---|---|
|
||
| 1 | 部署在乌班图 | 新加坡腾讯云服务器（Ubuntu 24.04，43.156.118.130），不在本地 Windows |
|
||
| 2 | 你动手我指挥 | 所有操作你自己执行（OrcaTerm + tunnel.bat），我出手册和脚本，防止搞乱 |
|
||
| 3 | 不破坏现状 | 服务器上已在跑的服务（New API、Nginx、Xray）一个都不能动 |
|
||
| 4 | 不暴露公网 | 新增服务的端口全部只绑服务器回环地址（127.0.0.1） |
|
||
|
||
**一个待验证的疑虑：** 国内 Google 账号能否挂进反代？——理论上 CPA 登录看的是出口 IP（新加坡），不看账号注册地；Pro 订阅的模型权限要登录后实测才算数。不行的备选方案：换渠道（AI Studio ↔ 反重力）或换账号。
|
||
|
||
---
|
||
|
||
## 二、为什么是这个方案（背景逻辑）
|
||
|
||
### 2.1 你的账号困局
|
||
|
||
Gemini Pro 是**订阅制**（包月），官方 API 是**按量计费**（另一笔钱）。订阅里的额度没有官方 API 入口——这就是"反代"存在的意义：**用你的订阅账号伪装成官方客户端，硬造出一个 API 来**。
|
||
|
||
### 2.2 工具选型：CPA（CLIProxyAPI）
|
||
|
||
朋友（茨米）推荐、社区最主流的"账号→API"反代，官方资料齐全：
|
||
|
||
- 官方镜像：`eceasy/cli-proxy-api:latest`（Docker Hub）
|
||
- 支持渠道：Gemini / AI Studio / **反重力(Antigravity)** / Claude / Codex / Grok / Kimi…
|
||
- 管理面板：`http://localhost:8317/management.html`（官方 Web UI）
|
||
- 反重力渠道对 Google AI Pro（非试用）订阅开放 **Claude Sonnet/Opus (thinking)** 模型——一个 Pro 账号同时供 Gemini 和 Claude 模型，正好喂 Claude Code
|
||
|
||
### 2.3 复用你已有的资产
|
||
|
||
你 10 月已经上线了 New API 网关（api.trivoo.website，Docker + Nginx + HTTPS）。CPA 不替代它，而是**作为新渠道挂进去**——所有客户端继续只认这一个域名、这一把钥匙。
|
||
|
||
---
|
||
|
||
## 三、最终架构
|
||
|
||
```
|
||
┌─ 你的 Windows 电脑 ────────────────────────────────────────────┐
|
||
│ │
|
||
│ Claude Code / Cherry Studio / 任何 OpenAI·Anthropic 客户端 │
|
||
└────────────────────────┬───────────────────────────────────────┘
|
||
│ HTTPS 443（已有域名+证书，无需新开端口）
|
||
▼
|
||
┌─ 新加坡服务器 Ubuntu 24.04 ─────────────────────────────────────┐
|
||
│ │
|
||
│ Nginx 反代（已有） │
|
||
│ │ 127.0.0.1:3000 │
|
||
│ ▼ │
|
||
│ New API 容器（已有）──── 第2层：网关分发、令牌、记账 │
|
||
│ │ 容器内网 ai-net: http://cli-proxy-api:8317 │
|
||
│ ▼ │
|
||
│ CPA 容器（本次新增）─── 第1层：账号→API、协议转换、账号池 │
|
||
│ │ OAuth 凭证（/opt/cpa/auths/） │
|
||
│ ▼ │
|
||
│ Google（Gemini 模型 + 反重力渠道的 Claude 模型） │
|
||
│ │
|
||
│ ※ CPA 全部端口只绑 127.0.0.1，公网不可达 │
|
||
│ ※ 远程管理/登录走 SSH 隧道（tunnel.bat） │
|
||
└────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**新增内容只有两样：** `/opt/cpa` 目录 + `cli-proxy-api` 容器。四条命令可彻底卸载。
|
||
|
||
---
|
||
|
||
## 四、实现流程（6 步）
|
||
|
||
| 步骤 | 在哪 | 做什么 | 用什么 | ✅ 过关标准 |
|
||
|---|---|---|---|---|
|
||
| ① 开隧道 | 本地 | 双击 `tunnel.bat` 建立到服务器的加密通道 | tunnel.bat | 窗口保持开着即可 |
|
||
| ② 部署 CPA | 服务器 | 上传并执行 `deploy-cpa.sh`：建目录、生成密钥、启容器、自检 | OrcaTerm | 输出 `cli-proxy-api Up`；无钥匙 401 / 有钥匙 200；打印两把钥匙 |
|
||
| ③ 登录账号 | 本地浏览器 | 管理面板里 OAuth 登录 Google 账号（反重力/AI Studio 渠道） | 隧道 + management.html | 凭证文件出现；`/v1/models` 列表非空 |
|
||
| ④ 挂渠道 | 浏览器 | New API 后台加 Claude 类型渠道，指向 CPA | api.trivoo.website | 渠道测速出绿色延迟 |
|
||
| ⑤ 配客户端 | 本地 | Claude Code 的 settings.json（或 CCS 加供应商）指向你的网关 | 编辑器 | — |
|
||
| ⑥ 全链路验证 | 本地 | curl 打一发 + Claude Code 实际对话 | PowerShell | 返回正常文本；New API 日志可见调用 |
|
||
|
||
> 详细操作、逐条命令、常见问题排错：见 `01-部署操作手册.md`。
|
||
|
||
### 两把钥匙（第②步生成，存于服务器 /opt/cpa/KEYS.txt）
|
||
|
||
| 钥匙 | 用在哪 |
|
||
|---|---|
|
||
| MGMT_KEY | 第③步登录管理面板 |
|
||
| CPA_API_KEY（sk-cpa-开头） | 第④步 New API 渠道的密钥 |
|
||
|
||
### Claude Code 最终配置（第⑤步）
|
||
|
||
```json
|
||
{
|
||
"env": {
|
||
"ANTHROPIC_AUTH_TOKEN": "sk-你的NewAPI令牌",
|
||
"ANTHROPIC_BASE_URL": "https://api.trivoo.website",
|
||
"API_TIMEOUT_MS": "600000",
|
||
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
|
||
},
|
||
"model": "渠道里配置的模型名"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、安全与边界设计
|
||
|
||
| 设计 | 说明 |
|
||
|---|---|
|
||
| 端口全回环 | CPA 的 6 个端口（8317 API/面板 + 5 个 OAuth 回调）全部 `127.0.0.1` 绑定，腾讯云防火墙**不用加任何规则** |
|
||
| 远程管理走隧道 | 管理面板只允许 localhost 访问（`allow-remote: false`），本地浏览器经 SSH 隧道进入 |
|
||
| 隔离现有服务 | 不改 new-api/nginx/xray 任何配置文件；new-api 只是"运行时接入"共享网络，一条命令可拆 |
|
||
| 凭证本地落盘 | Google OAuth 凭证存在服务器 `/opt/cpa/auths/`（权限 600），不经过任何第三方 |
|
||
| 可完整回滚 | 手册末尾"彻底卸载"四条命令恢复原样 |
|
||
|
||
## 六、风险知情
|
||
|
||
| 风险 | 说明 | 对策 |
|
||
|---|---|---|
|
||
| 国内账号疑虑 | Pro 订阅的模型权限可能因账号区域受限 | 登录后实测；不行换渠道/换号 |
|
||
| 违反 Google ToS | 反代属于非官方客户端使用，理论上有账号风险 | 只挂自己的账号、不放对外服务、用量克制 |
|
||
| 上游收紧 | 反重力/CPA 属猫鼠游戏，工具可能失效（前车之鉴：workbuddy2api 2026-10-21 停维护） | 接受它可能随时需要维护；好在部署可完全卸载 |
|
||
| 合规红线 | 对公众提供未备案生成式 AI 服务违规 | 仅自用；New API 已关闭公开注册（你已做过） |
|
||
|
||
## 七、当前状态与下一步
|
||
|
||
- ✅ 调研完成（反代原理/生态/选型 → 见 `..\反代研究笔记.md`）
|
||
- ✅ 部署包就绪（本目录 3 个文件）
|
||
- ⏳ **→ 你现在做：OrcaTerm 上传 `deploy-cpa.sh` → `sudo bash ~/deploy-cpa.sh` → 输出贴给 AI 检查**
|
||
- ⬜ 后续：③ 登录账号 → ④ 挂渠道 → ⑤⑥ 配置与验证
|
||
|
||
## 八、参考资料
|
||
|
||
- CPA 仓库：https://github.com/router-for-me/CLIProxyAPI
|
||
- CPA 中文文档：https://help.router-for.me/cn/
|
||
- 反重力（Antigravity）模型可用性：https://antigravity.google/docs/models/
|
||
- 你的前置文档：《NewAPI搭建与上线完整实战指南》（Obsidian）
|
||
- 背景研究：《反代研究笔记.md》（F:\AI\docker\）
|