一个本地端点
POST /v1/chat/completions(OpenAI)、POST /v1/messages(Anthropic)、GET /v1/models 和 GET /v1/models/capabilities,Cursor、Windsurf、OpenCode、Claude Code 等客户端都能接入。模型名通过 custom_mapping 和 anthropic_mapping 映射。 |
账号池 通过 OAuth 添加 Google 账号,每个账号显示状态(Active、Rate Limited、Expired)、最近使用时间,并可单独设置代理 URL。 |
自动切换
CloudMonitorService 每 5 分钟查询一次配额,当配额低于 5 % 或账号被限流时,AutoSwitchService 切换到其他账号。 |
带熔断器的调度
cache-first、balance(默认)或 performance-first,每个账号都有熔断器(默认退避 60 s → 5 min → 30 min → 2 h)。 |
用量与成本 按账号和模型统计 token 用量,提供 prompt 与 completion 图表,并根据可编辑的模型单价估算成本。 |
流量检查器 每个请求的延迟、状态和模型,可重放已记录的请求,生成 cURL 和 Python 代码片段,并提供 IDE 快速配置(Quick Setup)。 |
已保存的凭据使用 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`。 |
## ❓ 常见问题