forked from boos/BoosAPI
[codex] refresh integration and settings docs for current UI and provider coverage (#398)
* docs: refresh integration and settings guides * docs: address review follow-up
This commit is contained in:
Cita
+224
@@ -0,0 +1,224 @@
|
||||
# 🔐 OAuth 管理
|
||||
|
||||
本文档介绍 Metapi 里的「OAuth 管理」页面，适合需要直接授权 provider 账号的场景。
|
||||
|
||||
[返回文档中心](/)
|
||||
|
||||
---
|
||||
|
||||
## 这页解决什么问题
|
||||
|
||||
不是所有上游都适合手填 API Key、Access Token 或 Cookie。
|
||||
|
||||
对下面这类 provider 账号，更推荐直接走 OAuth：
|
||||
|
||||
- Codex
|
||||
- Claude
|
||||
- Gemini CLI
|
||||
- Antigravity
|
||||
|
||||
这类接法的特点是：
|
||||
|
||||
- 使用浏览器授权，而不是手填用户名密码
|
||||
- 授权成功后，Metapi 会自动创建或复用对应 provider 的站点
|
||||
- 账号会按 OAuth 连接保存，后续刷新和重绑也走同一套流程
|
||||
|
||||
如果你接的是 New API、One API、Sub2API、CPA、OpenAI-compatible、Claude-compatible 这类**普通站点或网关**，请看 [上游接入](/upstream-integration)。
|
||||
|
||||
---
|
||||
|
||||
## 入口在哪里
|
||||
|
||||
管理后台左侧菜单已经有独立入口：
|
||||
|
||||
```text
|
||||
OAuth 管理
|
||||
```
|
||||
|
||||
这不是站点编辑器里的一个隐藏选项，而是和「站点管理」「账号管理」并列的一页。
|
||||
|
||||
---
|
||||
|
||||
## 当前支持的 provider
|
||||
|
||||
| Provider | 对应平台 | 自动创建的站点名 | 典型用途 |
|
||||
|------|------|------|------|
|
||||
| Codex | `codex` | `ChatGPT Codex OAuth` | 直接用 Codex 账号授权 |
|
||||
| Claude | `claude` | `Anthropic Claude OAuth` | 直接用 Claude / Anthropic 账号授权 |
|
||||
| Gemini CLI | `gemini-cli` | `Google Gemini CLI OAuth` | 复用 Gemini CLI / Google Cloud 账号授权，可选输入 Project ID |
|
||||
| Antigravity | `antigravity` | `Google Antigravity OAuth` | 复用 Antigravity 账号授权 |
|
||||
|
||||
授权完成后，这些站点会出现在「站点管理」里，但通常**不建议你手动创建**它们。
|
||||
|
||||
---
|
||||
|
||||
## 授权前的准备
|
||||
|
||||
### 1. 确保 Metapi 能访问 provider 的 OAuth 端点
|
||||
|
||||
如果你的部署环境访问外网受限，可以：
|
||||
|
||||
- 先配置全局 `SYSTEM_PROXY_URL`
|
||||
- 或在 OAuth 启动 / 重绑时使用单次代理参数
|
||||
|
||||
相关环境变量见 [配置说明](/configuration) 里的「OAuth 与 Provider 登录」一节。
|
||||
|
||||
### 2. 远程部署要提前考虑回调方式
|
||||
|
||||
OAuth 默认使用 Metapi 本机上的 loopback 回调地址，例如本机 `127.0.0.1` 端口。
|
||||
|
||||
如果你的 Metapi 跑在远程服务器上，而浏览器跑在本地电脑上，常见做法有两个：
|
||||
|
||||
1. **SSH 隧道**：按页面给出的命令，把回调端口转发到远端
|
||||
2. **手动回填 callback URL**：如果浏览器已经完成授权，但自动回调没打通，可把最终回调地址手动贴回管理页
|
||||
|
||||
### 3. 了解它和普通站点接入的边界
|
||||
|
||||
OAuth 连接更适合“provider 原生账号授权”，而不是：
|
||||
|
||||
- 面板站点账号密码登录
|
||||
- New API / One API 后台管理
|
||||
- CPA / OpenAI-compatible 的普通 API Key 托管
|
||||
|
||||
---
|
||||
|
||||
## 标准流程
|
||||
|
||||
### 步骤 1：打开 OAuth 管理
|
||||
|
||||
进入左侧菜单「OAuth 管理」，等待页面加载 provider 列表和已有连接。
|
||||
|
||||
### 步骤 2：点击要连接的 provider
|
||||
|
||||
页面会为 provider 发起一个 OAuth 会话，并弹出授权窗口。
|
||||
|
||||
Metapi 会同时给出：
|
||||
|
||||
- 授权链接
|
||||
- 本机回调端口
|
||||
- 手动回填等待时间
|
||||
- 如果当前是远程访问，还会给出 SSH 隧道命令模板
|
||||
|
||||
### 步骤 3：在 provider 页面完成授权
|
||||
|
||||
完成授权后，Metapi 会轮询当前会话状态：
|
||||
|
||||
- `pending`：等待回调
|
||||
- `success`：授权成功
|
||||
- `error`：授权失败，需要重新检查浏览器回调或网络
|
||||
|
||||
### 步骤 4：必要时手动回填 callback URL
|
||||
|
||||
如果弹窗里已经能看到类似 `...?code=...&state=...` 的回调地址，但 Metapi 页面还没成功：
|
||||
|
||||
1. 复制浏览器最终回调 URL
|
||||
2. 回到「OAuth 管理」
|
||||
3. 粘贴到手动回填区域提交
|
||||
|
||||
### 步骤 5：确认站点与连接都已出现
|
||||
|
||||
成功后通常会看到两层结果：
|
||||
|
||||
- 「OAuth 管理」页里出现新的连接记录
|
||||
- 「站点管理」页里出现对应 provider 的站点行
|
||||
|
||||
---
|
||||
|
||||
## 和普通站点 / API Key 的区别
|
||||
|
||||
| 方式 | 入口 | 适合什么 | 典型例子 |
|
||||
|------|------|------|------|
|
||||
| 普通站点 + Session | 站点管理 / 账号管理 | 有后台面板，需要签到、余额、账号令牌管理 | New API、One API、DoneHub、AnyRouter、Sub2API |
|
||||
| 普通站点 + API Key | 站点管理 / API Key 管理 | 只关心代理调用和模型列表 | OpenAI-compatible、Claude-compatible、CPA |
|
||||
| OAuth 连接 | OAuth 管理 | 需要 provider 官方授权、刷新、重绑 | Codex、Claude、Gemini CLI、Antigravity |
|
||||
|
||||
简单判断：
|
||||
|
||||
- 你拿到的是 **站点后台地址**，优先看 [上游接入](/upstream-integration)
|
||||
- 你拿到的是 **provider 登录授权**，优先看这页
|
||||
|
||||
---
|
||||
|
||||
## 自动生成的站点有什么用
|
||||
|
||||
OAuth 成功后，Metapi 会确保对应 provider 的站点存在。这样做是为了让 OAuth 连接也能融入现有的：
|
||||
|
||||
- 站点列表
|
||||
- 路由通道
|
||||
- 账号归属
|
||||
- 代理与重绑逻辑
|
||||
|
||||
但这类站点和普通面板站点仍然不同：
|
||||
|
||||
- 它们通常不是拿来手动登录的
|
||||
- 不要把它理解成“我又多了一个可签到的面板站”
|
||||
- 更准确地说，它是 OAuth 账号在 Metapi 里的宿主站点
|
||||
|
||||
---
|
||||
|
||||
## 管理 API 里怎么自动化
|
||||
|
||||
如果你想脚本化处理 OAuth，可以用这些接口：
|
||||
|
||||
| 接口 | 作用 |
|
||||
|------|------|
|
||||
| `GET /api/oauth/providers` | 获取当前可用 provider 列表 |
|
||||
| `POST /api/oauth/providers/:provider/start` | 启动 OAuth 流程 |
|
||||
| `GET /api/oauth/sessions/:state` | 轮询会话状态 |
|
||||
| `POST /api/oauth/sessions/:state/manual-callback` | 手动回填 callback URL |
|
||||
| `GET /api/oauth/connections` | 列出现有连接 |
|
||||
| `POST /api/oauth/connections/:accountId/rebind` | 重绑已有 OAuth 连接 |
|
||||
| `DELETE /api/oauth/connections/:accountId` | 删除 OAuth 连接 |
|
||||
|
||||
脚本示例见 [管理 API](/management-api)。
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### provider 显示“当前不可用”
|
||||
|
||||
通常说明回调监听器不可用，或当前 provider 的启动条件不满足。优先检查：
|
||||
|
||||
1. 服务是否刚启动但回调监听失败
|
||||
2. 端口是否被占用
|
||||
3. 当前环境是否缺少必要的 OAuth 配置
|
||||
|
||||
### 浏览器授权成功了，但页面一直停在“等待授权完成”
|
||||
|
||||
优先怀疑回调链路没通：
|
||||
|
||||
1. 如果是远程服务器，先按页面提示建 SSH 隧道
|
||||
2. 如果不方便建隧道，直接用手动 callback 回填
|
||||
3. 如果 provider 页面最终没有 `code` / `state` 参数，说明授权本身还没成功
|
||||
|
||||
### OAuth 连接需要系统代理吗
|
||||
|
||||
有可能需要，尤其是：
|
||||
|
||||
- 国内服务器访问 OpenAI / Anthropic / Google OAuth 端点
|
||||
- 服务器本身不能直连 provider
|
||||
|
||||
优先使用：
|
||||
|
||||
1. 全局 `SYSTEM_PROXY_URL`
|
||||
2. OAuth 启动 / 重绑时指定单次代理
|
||||
|
||||
### OAuth 成功后为什么还会在站点管理看到一行站点
|
||||
|
||||
这是预期行为。Metapi 需要一个明确的站点记录来承载：
|
||||
|
||||
- 账号所属平台
|
||||
- 路由与通道归属
|
||||
- 后续重绑 / 刷新逻辑
|
||||
|
||||
它不代表你又新增了一个普通面板站点。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [上游接入](/upstream-integration)
|
||||
- [管理 API](/management-api)
|
||||
- [配置说明](/configuration)
|
||||
- [常见问题 FAQ](/faq)
|
||||
Reference in New Issue
Block a user