boos
e0a5f57793
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
205 lines
5.8 KiB
Markdown
205 lines
5.8 KiB
Markdown
# API 网关
|
||
|
||
## 什么是 API 网关？
|
||
|
||
BoosApi 内置了一个本地 API 网关服务器，可以将你在 BoosApi 中配置的 AI 服务商统一暴露为标准 API 接口。其他工具和客户端（如 Claude Code、Codex CLI、Cursor 等）可以通过这个网关访问你的所有模型，无需为每个工具分别配置 API 密钥。
|
||
|
||
网关支持以下兼容格式：
|
||
|
||
- **OpenAI 兼容** — `/v1/chat/completions`
|
||
- **Claude 原生** — Anthropic API 格式
|
||
- **Gemini 原生** — Google AI API 格式
|
||
|
||
::: tip 使用场景
|
||
如果你已经在 BoosApi 中配置了多个服务商和密钥，API 网关可以让其他开发工具直接复用这些配置，省去重复配置的麻烦。同时，网关提供统一的用量统计和访问控制。
|
||
:::
|
||
|
||
## 快速上手
|
||
|
||
### 启用网关
|
||
|
||
1. 进入 **设置 → API 网关**
|
||
2. 开启网关开关
|
||
3. 配置监听参数：
|
||
- **端口** — 网关监听的端口号，默认 `8080`
|
||
- **主机** — 监听地址，默认 `127.0.0.1`（仅本机访问）
|
||
|
||
::: warning 网络安全
|
||
如果将主机设置为 `0.0.0.0`，网关将对所有网络接口开放。请确保你了解其安全风险，并配合 API 密钥和防火墙使用。
|
||
:::
|
||
|
||
### 测试连通性
|
||
|
||
网关启动后，可以用 `curl` 快速验证：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8080/v1/models \
|
||
-H "Authorization: Bearer your-gateway-api-key"
|
||
```
|
||
|
||
如果返回了模型列表，说明网关运行正常。
|
||
|
||
## API 密钥管理
|
||
|
||
网关使用独立的 API 密钥体系来控制访问权限。
|
||
|
||
### 生成新密钥
|
||
|
||
1. 在 **API 网关** 页面中找到 **密钥管理** 区域
|
||
2. 点击 **生成密钥**
|
||
3. 为密钥添加描述备注（如 "Claude Code 专用"、"团队共享"）
|
||
4. 复制并妥善保存生成的密钥
|
||
|
||
::: danger 密钥安全
|
||
密钥仅在创建时完整显示一次。请立即复制保存，之后只能看到密钥前缀。
|
||
:::
|
||
|
||
### 撤销 / 停用密钥
|
||
|
||
- **停用** — 暂时禁用密钥，可随时重新启用
|
||
- **删除** — 永久撤销密钥，使用该密钥的所有客户端将立即失去访问权限
|
||
|
||
### 描述备注
|
||
|
||
为每个密钥添加描述可以帮助你管理多个客户端的访问。例如区分不同工具或团队成员使用的密钥。
|
||
|
||
## SSL/TLS
|
||
|
||
网关支持 HTTPS 加密通信，部分工具（如 Claude Code）要求使用 HTTPS 连接。
|
||
|
||
### 自动自签名证书
|
||
|
||
启用 SSL 后，BoosApi 会自动生成自签名证书，无需手动操作。证书文件存储在：
|
||
|
||
```
|
||
~/.boosapi/ssl/
|
||
├── cert.pem # 自签名证书
|
||
└── key.pem # 私钥（Unix 系统权限 0600）
|
||
```
|
||
|
||
### 自定义证书
|
||
|
||
如果你有自己的 SSL 证书（如 Let's Encrypt 签发的证书），可以在网关设置中指定证书和私钥的路径。
|
||
|
||
### 配置选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| 启用 SSL | 是否开启 HTTPS |
|
||
| SSL 端口 | HTTPS 监听端口 |
|
||
| 证书路径 | cert.pem 文件路径 |
|
||
| 私钥路径 | key.pem 文件路径 |
|
||
| 强制 SSL | 是否将所有 HTTP 请求重定向到 HTTPS |
|
||
|
||
::: info 自签名证书信任
|
||
使用自签名证书时，客户端可能会报告证书不受信任的警告。大部分 CLI 工具可以通过设置环境变量来跳过证书验证（见下方配置模板）。
|
||
:::
|
||
|
||
## 用量统计
|
||
|
||
网关提供详细的用量统计面板，帮助你了解 API 的使用情况。
|
||
|
||
### 请求量面板
|
||
|
||
实时显示网关处理的请求总量、成功率和错误率。
|
||
|
||
### Token 用量
|
||
|
||
按不同维度查看 Token 消耗：
|
||
|
||
- **按密钥** — 每个 API 密钥使用了多少 Token
|
||
- **按服务商** — 每个后端服务商处理了多少请求和 Token
|
||
- **按日期** — 每日的 Token 使用趋势
|
||
|
||
::: tip
|
||
通过用量统计，你可以了解哪个工具消耗最多资源，合理分配 API 配额。
|
||
:::
|
||
|
||
## 请求日志
|
||
|
||
网关记录所有经过它的 API 请求，方便调试和审计。
|
||
|
||
每条日志包含以下信息：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| 时间 | 请求的时间戳 |
|
||
| 方法 | HTTP 方法（GET、POST 等） |
|
||
| 路径 | 请求路径 |
|
||
| 模型 | 请求使用的模型 |
|
||
| 服务商 | 转发到的后端服务商 |
|
||
| 状态码 | HTTP 响应状态码 |
|
||
| Token | 输入/输出 Token 数量 |
|
||
| 延迟 | 请求处理耗时 |
|
||
|
||
支持按时间范围、状态码、模型等条件过滤日志。
|
||
|
||
## 配置模板
|
||
|
||
BoosApi 内置了常见开发工具的配置模板，帮助你快速接入。以下是一些常用工具的配置方式：
|
||
|
||
### Claude Code CLI
|
||
|
||
```bash
|
||
export ANTHROPIC_BASE_URL=https://127.0.0.1:8443
|
||
export ANTHROPIC_API_KEY=your-gateway-api-key
|
||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||
|
||
claude
|
||
```
|
||
|
||
::: tip
|
||
`NODE_TLS_REJECT_UNAUTHORIZED=0` 用于跳过自签名证书验证。如果你使用了受信任的证书，可以移除此设置。
|
||
:::
|
||
|
||
### OpenAI Codex CLI
|
||
|
||
```bash
|
||
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
|
||
export OPENAI_API_KEY=your-gateway-api-key
|
||
|
||
codex
|
||
```
|
||
|
||
### OpenCode
|
||
|
||
```bash
|
||
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
|
||
export OPENAI_API_KEY=your-gateway-api-key
|
||
|
||
opencode
|
||
```
|
||
|
||
### Gemini CLI
|
||
|
||
```bash
|
||
export GEMINI_API_KEY=your-gateway-api-key
|
||
export GEMINI_BASE_URL=http://127.0.0.1:8080
|
||
|
||
gemini
|
||
```
|
||
|
||
### 自定义客户端
|
||
|
||
对于任何支持 OpenAI 兼容 API 的客户端，使用以下配置：
|
||
|
||
- **Base URL**: `http://127.0.0.1:8080/v1`
|
||
- **API Key**: 你的网关 API 密钥
|
||
- **模型**: 通过 `/v1/models` 接口查询可用模型
|
||
|
||
## 接入外部工具
|
||
|
||
除 CLI 工具外，许多图形化工具也支持自定义 API 端点。通用配置方式：
|
||
|
||
1. 在工具的设置中找到 API 配置或自定义端点选项
|
||
2. 将 Base URL 设置为 BoosApi 网关地址
|
||
3. 将 API Key 设置为网关密钥
|
||
4. 保存后即可使用 BoosApi 配置的所有模型
|
||
|
||
::: tip 统一管理的优势
|
||
通过 API 网关统一管理，你可以：
|
||
- 在 BoosApi 中集中管理所有服务商密钥，其他工具只需一个网关密钥
|
||
- 在用量统计中查看所有工具的使用情况
|
||
- 利用多密钥轮询提高可靠性
|
||
:::
|