Files
gemini-nexus/README.zh-CN.md
T
evandro e3652f43f5
Lint / ESLint Check (pull_request) Failing after 8m20s
Check formatting / Prettier Format Check (pull_request) Failing after 8m37s
Tests / Unit Tests (pull_request) Successful in 13m53s
Tests / Type Check (pull_request) Successful in 11m31s
docs(readme): padrão SaaS
2026-11-16 00:02:29 -03:00

263 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<div align="center">
<img src="assets/readme/hero.zh-CN.png" width="100%" alt="Gemini Nexus:桌面网关,把多个 Google 账号汇成号池,在 http://localhost:8045/v1 提供兼容 OpenAI 与 Anthropic 的本地 API,配额不足时自动切换账号">
![Stack](https://img.shields.io/badge/Stack-Electron_41_%C2%B7_React_19-47848F?logo=electron&logoColor=white)
![Status](https://img.shields.io/badge/status-v0.15.3_active-brightgreen)
![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-lightgrey)
<p><strong><a href="#-快速开始">快速开始</a></strong> · <a href="#-文档与开发">文档</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
<sub><a href="README.md">English</a> · <a href="README.pt-BR.md">Português</a> · 中文 · <a href="README.es.md">Español</a></sub>
</div>
## 📸 截图
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Accounts 页面:号池中的一个 Google 账号,带按模型显示的配额条、Auto-Switch 开关和全局配额计数"></p>
<details>
<summary>更多截图:用量、代理、路由、文档、连接、设置</summary>
<p align="center"><img src="docs/assets/2usage.png" alt="用量分析" width="80%"></p>
<p align="center"><img src="docs/assets/3proxy.png" alt="代理监控" width="80%"></p>
<p align="center"><img src="docs/assets/4routing.png" alt="路由配置" width="80%"></p>
<p align="center"><img src="docs/assets/5docs.png" alt="文档" width="80%"></p>
<p align="center"><img src="docs/assets/6connections.png" alt="活动连接" width="80%"></p>
<p align="center"><img src="docs/assets/7config.png" alt="设置" width="80%"></p>
</details>
## 🎯 功能特性
只用一个 Google 账号配合 AI IDE,意味着配额很快耗尽、要手动切换账号,也看不到代理到底向上游发送了什么。Gemini Nexus 把所有账号放进一个号池,通过一个本地端点统一提供服务。
<table>
<tr>
<td width="50%" valign="top"><b>一个本地端点</b><br><code>POST /v1/chat/completions</code>(OpenAI)、<code>POST /v1/messages</code>(Anthropic)、<code>GET /v1/models</code> 和 <code>GET /v1/models/capabilities</code>,Cursor、Windsurf、OpenCode、Claude Code 等客户端都能接入。模型名通过 <code>custom_mapping</code> 和 <code>anthropic_mapping</code> 映射。</td>
<td width="50%" valign="top"><b>账号池</b><br>通过 OAuth 添加 Google 账号,每个账号显示状态(Active、Rate Limited、Expired)、最近使用时间,并可单独设置代理 URL。</td>
</tr>
<tr>
<td width="50%" valign="top"><b>自动切换</b><br><code>CloudMonitorService</code> 每 5 分钟查询一次配额,当配额低于 5 % 或账号被限流时,<code>AutoSwitchService</code> 切换到其他账号。</td>
<td width="50%" valign="top"><b>带熔断器的调度</b><br><code>cache-first</code>、<code>balance</code>(默认)或 <code>performance-first</code>,每个账号都有熔断器(默认退避 60 s → 5 min → 30 min → 2 h)。</td>
</tr>
<tr>
<td width="50%" valign="top"><b>用量与成本</b><br>按账号和模型统计 token 用量,提供 prompt 与 completion 图表,并根据可编辑的模型单价估算成本。</td>
<td width="50%" valign="top"><b>流量检查器</b><br>每个请求的延迟、状态和模型,可重放已记录的请求,生成 cURL 和 Python 代码片段,并提供 IDE 快速配置(Quick Setup)。</td>
</tr>
</table>
已保存的凭据使用 AES-256-GCM 加密,主密钥存放在系统钥匙串中(见[安全模型](#安全模型))。
## 工作原理
1. **添加账号。** 在 Accounts 页面通过 Google OAuth 登录。token 在写入 SQLite 之前就已加密。
2. **让 IDE 指向代理。** 在 Proxy 页面启用代理(默认关闭),使用 `http://localhost:8045/v1` 和页面上显示的 API key,OpenAI 或 Anthropic 格式均可。
3. **Nexus 路由每个请求。** token manager 根据调度模式和熔断器状态选择账号,用该账号的 OAuth token 调用 Google 上游 API;当配额低于 5 % 或账号被限流时,自动切换生效。
包含各组件的完整流程见[架构](#架构)。
## ⚡ 快速开始
目前 [Gitea Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases) 页面还没有预编译下载(`.github/workflows/` 中的发布工作流面向 GitHub),因此请从源码构建。
| 工具 | 最低版本 |
|---|---|
| Node.js | 20+(`AGENTS.md` 中推荐;`.nvmrc` 固定为 22.17.1) |
| pnpm | 10.11.0(`packageManager`;锁文件为 `pnpm-lock.yaml`) |
| 原生工具链 | `better-sqlite3` 和 `keytar` 需要:Windows 上的 Visual Studio 2022 Build Tools(C++)、macOS 上的 Xcode Command Line Tools、Ubuntu 上的 `build-essential` + `python3` + `libsecret-1-dev`(Arch 上为 `base-devel` + `python` + `libsecret`) |
```bash
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
cd gemini-nexus
pnpm install # postinstall 会运行 scripts/setup-dev.js --check-only 检查工具链
pnpm start # 开发模式(Electron + Vite HMR)
pnpm run make # 为当前平台生成安装包/软件包
pnpm run make:win # Windows:从 wix314-binaries.zip 解压 WiX,然后运行 make
```
然后至少添加一个账号,启用代理(默认关闭),并把 IDE 指向它:
```text
API Base URL: http://localhost:8045/v1 (默认值,可在 Proxy 页面修改;开发构建使用 8046)
API Key: (从应用的 Proxy 页面复制)
Model: gemini-3-flash (或任意已映射的模型)
```
> [!WARNING]
> 构建产物没有代码签名。如果 Windows 提示“Windows 已保护你的电脑”,请点击 **更多信息 → 仍要运行**。
项目没有 `.env.example`,也没有必填变量。代码读取或文档中提到的可选变量:
| 变量 | 必填 | 说明 |
|---|---|---|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 否 | 让应用的出站请求经过本地代理(TLS 检查见[安全模型](#安全模型))。 |
| `NODE_EXTRA_CA_CERTS` | 否 | 检查流量时,Node 侧 TLS 使用的额外 CA 证书。 |
| `SENTRY_DSN` | 否 | 启用错误上报时使用的 Sentry DSN。 |
## 🛠️ 技术栈
| 层 | 技术 |
|---|---|
| 桌面外壳 | Electron 41、Electron Forge、Vite |
| 界面 | React 19、TypeScript、Tailwind CSS 4、Radix UI、Nivo 图表、i18next |
| 应用数据流 | TanStack Router 与 Query,基于 Electron IPC 的 oRPC |
| 代理 | NestJS 11 + Fastify |
| 存储 | SQLite(better-sqlite3 + Drizzle ORM),通过 `keytar` 使用系统钥匙串 |
| 日志与错误 | Winston(滚动日志文件)、Sentry(可选) |
| 测试 | Vitest、Playwright |
## 架构
```mermaid
flowchart LR
C["客户端:Cursor、Windsurf、OpenCode、Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["NestJS 代理,端口 8045"]
P --> S["账号调度器与熔断器"]
S -->|"Google OAuth 账号"| G["Google 上游 API"]
M["CloudMonitor 与 AutoSwitch,每 5 分钟查询配额"] -->|"配额轮询"| G
S -->|"读取账号"| DB[("SQLite:better-sqlite3 与 Drizzle")]
M --> DB
K["AES-256-GCM,主密钥在系统钥匙串"] -->|"加密 token"| DB
```
1. 客户端向 NestJS 代理(Fastify,绑定 `0.0.0.0`)发送 OpenAI 或 Anthropic 格式的请求。
2. 配置了 API key 时,代理守卫会校验它;key 为空时代理以开放模式运行。
3. token manager 根据调度模式和各账号的熔断器状态选择账号,再用该账号的 OAuth token 调用 Google 上游 API。
4. `CloudMonitorService` 每 5 分钟查询一次配额,当配额低于 5 % 或账号被限流时,`AutoSwitchService` 切换当前账号。
5. React 19 渲染进程(TanStack Router 与 Query)通过 IPC 上的 oRPC 与主进程通信;账号、用量和设置保存在 SQLite(better-sqlite3 + Drizzle)中。设计说明:[`docs/cloud_features.md`](docs/cloud_features.md)。
## 安全模型
Gemini Nexus 保存多个账号的 OAuth token 并向上游转发流量,因此凭据处理是设计的核心。以下内容均已在本仓库中实现;存在限制的地方都已注明。
- **凭据存储与隔离。** `token_json` 和 `quota_json` 在写入 SQLite 之前使用 AES-256-GCM 加密(每次操作使用唯一 IV,带认证)。主密钥通过 `keytar` 存放在系统凭据存储中(Windows 凭据管理器、macOS 钥匙串、Linux Secret Service/libsecret),绝不写入普通文件。旧的明文记录会在启动时迁移。账号保存在独立的数据库(`cloud_accounts.db`)中,与 IDE 的本地数据库分开。
- **日志脱敏。** `token`、`refresh_token`、`api_key`、`authorization`、`cookie`、`client_secret` 等键在写入日志前会被替换为 `[REDACTED]`([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts));流量日志还会隐去 `authorization`、`x-api-key` 和 `cookie` 请求头。
- **请求日志,而非审计追踪。** Winston 把 API、流量和应用日志写入滚动文件(API 日志:保留 30 天,每个文件 50 MB)。这些是运维日志,不是防篡改的审计追踪;`*-audit.json` 文件是 `winston-daily-rotate-file` 的轮转记录。
- **代理访问。** 代理默认关闭。启用后监听 `0.0.0.0`,只有在 `api_key` 非空时才会校验请求(为空即开放模式)。请设置 key 并妥善保管。
- **TLS 检查(仅用于调试)。** [`docs/proxyman-install.md`](docs/proxyman-install.md) 和 [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) 说明如何用 Proxyman 查看应用的 HTTPS 流量:信任其根 CA,设置代理变量和 `NODE_EXTRA_CA_CERTS`,然后启动应用。`NODE_TLS_REJECT_UNAUTHORIZED=0`(以及脚本的 `-AllowInsecureTls` 参数)只是临时覆盖,切勿一直开启。不要提交代理地址、证书路径、cookie 或 OAuth code,分享日志前请先脱敏。`scripts/start-antigravity-with-proxyman.ps1` 针对的是已安装的官方 Antigravity 客户端,而不是本应用。
- **错误上报。** Sentry 上报(需要 `SENTRY_DSN`)受 `error_reporting_enabled` 设置控制,`DEFAULT_APP_CONFIG` 中默认为 `true`;可在 Settings 中关闭。上报的异常消息中会屏蔽 Windows 用户名部分。
支持的版本以及如何报告漏洞:[`SECURITY.md`](SECURITY.md)。
## 💻 文档与开发
- [`docs/cloud_features.md`](docs/cloud_features.md):账号池、配额监控与自动切换的设计。
- [`docs/proxyman-install.md`](docs/proxyman-install.md) 和 [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md):TLS 检查配置(Windows)。
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md):OpenCode 自定义端点集成(葡萄牙语)。
- [`cli/README.md`](cli/README.md):Python 命令行工具。
- [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`SECURITY.md`](SECURITY.md)、[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)、[`CHANGELOG.md`](CHANGELOG.md)、[`LICENSE`](LICENSE)、[`LICENSE-MIT`](LICENSE-MIT)。
- 其他语言:[English](README.md)、[Português](README.pt-BR.md)、[Español](README.es.md)。
### 目录结构
```text
src/
├── components/ # UI(proxy/、usage/、ui/ 基础组件)
├── ipc/ # oRPC 路由(account、cloud、config、gateway、usage...)
├── server/ # NestJS 代理网关(模块:proxy、usage)
├── services/ # AutoSwitchService、CloudMonitorService、GoogleAPIService
├── routes/ # index、usage、proxy、settings
├── utils/ # paths、logger、sensitiveDataMasking
└── tests/ # 单元测试(Vitest)与 E2E(Playwright)
cli/ # 独立的 Python CLI,用于切换账号和查询配额
docs/ # 设计说明与 Proxyman 指南
scripts/ # setup-dev、build-windows、generate-assets
```
### 脚本
| 命令 | 作用 |
|---|---|
| `pnpm start` | 以开发模式运行应用(`electron-forge start`,带 `DEBUG=electron-forge:*`)。 |
| `pnpm run dev` | 与 `start` 相同。 |
| `pnpm run package` | 用 Electron Forge 打包应用,不生成安装包。 |
| `pnpm run make` | 为当前平台生成安装包/软件包。 |
| `pnpm run make:win` | Windows 构建辅助:从 `wix314-binaries.zip` 解压 WiX,加入 `PATH`,运行 `electron-forge make`。 |
| `pnpm run publish` | 通过 Electron Forge 发布。 |
| `pnpm run setup` | 运行 `scripts/setup-dev.js`:检测原生工具链并安装或引导配置。 |
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`;在 `pnpm install` 后自动运行。 |
| `pnpm run lint` | 对仓库运行 ESLint。 |
| `pnpm run format` | Prettier 检查。 |
| `pnpm run format:write` | Prettier 写入格式化。 |
| `pnpm test` | Vitest 单元测试(`vitest run`)。 |
| `pnpm run test:watch` | Vitest 监听模式。 |
| `pnpm run test:unit` | Vitest(默认模式)。 |
| `pnpm run test:e2e` | Playwright E2E 测试。 |
| `pnpm run test:all` | 先跑单元测试,再跑 Playwright。 |
| `pnpm run type-check` | `tsc --noEmit`。 |
## ❓ 常见问题
<details>
<summary><b>Windows 提示“Windows 已保护你的电脑”,正常吗?</b></summary>
正常。构建产物没有代码签名。请点击 **更多信息 → 仍要运行**。
</details>
<details>
<summary><b>IDE 连不上代理。</b></summary>
代理默认关闭:请在 Proxy 页面启用。默认端口为 `8045`(开发构建为 `8046`),可在该页面修改。从同一页面复制 API key,并确认号池中至少有一个账号。
</details>
<details>
<summary><b>需要 API key 吗?</b></summary>
`api_key` 为空时代理以开放模式运行。启用后它监听 `0.0.0.0`,所以请设置 key 并妥善保管。
</details>
<details>
<summary><b>能使用 Claude 模型吗?</b></summary>
可以,通过号池中 Google 账号上的模型映射实现,而不是使用单独的 Claude 账号。
</details>
<details>
<summary><b>我的 token 存在哪里?</b></summary>
存放在独立的 `cloud_accounts.db` 中,`token_json` 和 `quota_json` 使用 AES-256-GCM 加密。主密钥通过 `keytar` 存放在系统凭据存储中。详见[安全模型](#安全模型)。
</details>
<details>
<summary><b>可以商用吗?</b></summary>
请先查看[许可证](#-许可证):继承自 AntigravityManager 的代码采用 CC BY-NC-SA 4.0(非商业),新代码采用 MIT。
</details>
## 局限与后续计划
- 上游访问经由 Google 的 `v1internal` Cloud Code 端点和 OAuth scope([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts))。这些是内部、未公开文档的 API,可能随时变更。本项目为非官方项目,与 Google 或 Anthropic 无关联。
- 账号通过 Google OAuth 添加;Claude 模型通过模型映射访问,而不是通过单独的 Claude 账号。
- 端到端测试不在 CI 中运行(Electron 需要图形环境);请在本地运行 `pnpm run test:e2e`。
- 只有构建机器上有 WiX Toolset 时才会生成 Windows MSI,否则 Windows 产物为 ZIP。
- `.github/workflows/` 中的工作流是为 GitHub 编写的(调用 `gh` CLI 和 GitHub 发布器),因此本 README 不显示 CI 徽章。
- 项目声明的下一步:把剩余的原始代码迁移到 MIT(见[许可证](#-许可证))。
## 🤝 参与贡献
请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。版本由 semantic-release 根据 Conventional Commits 生成。提交 PR 之前,以下命令必须通过:
```bash
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
```
## 📄 许可证
混合许可:继承自 [AntigravityManager](https://github.com/Draculabo/AntigravityManager)(作者 Draculabo)的代码采用 [CC BY-NC-SA 4.0](LICENSE)(非商业、相同方式共享);所有新代码采用 [MIT](LICENSE-MIT)。随着剩余原始代码被重写,项目正在迁移到 MIT,因此任何商业使用前请同时查看两个文件。
---
<div align="center">
<img src="docs/assets/logo.png" width="56" alt="Gemini Nexus 标志">
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gitea 上的 Gemini Nexus</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">报告问题</a> · <a href="#-快速开始">快速开始</a></p>
</div>