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

16 KiB
Raw Blame History

📸 截图

Accounts 页面:号池中的一个 Google 账号,带按模型显示的配额条、Auto-Switch 开关和全局配额计数

更多截图:用量、代理、路由、文档、连接、设置

用量分析

代理监控

路由配置

文档

活动连接

设置

🎯 功能特性

只用一个 Google 账号配合 AI IDE,意味着配额很快耗尽、要手动切换账号,也看不到代理到底向上游发送了什么。Gemini Nexus 把所有账号放进一个号池,通过一个本地端点统一提供服务。

一个本地端点
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 页面还没有预编译下载(.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)
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 指向它:

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

架构

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。

安全模型

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);流量日志还会隐去 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-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。

💻 文档与开发

目录结构

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。

❓ 常见问题

Windows 提示“Windows 已保护你的电脑”,正常吗?

正常。构建产物没有代码签名。请点击 更多信息 → 仍要运行。

IDE 连不上代理。

代理默认关闭:请在 Proxy 页面启用。默认端口为 8045(开发构建为 8046),可在该页面修改。从同一页面复制 API key,并确认号池中至少有一个账号。

需要 API key 吗?

api_key 为空时代理以开放模式运行。启用后它监听 0.0.0.0,所以请设置 key 并妥善保管。

能使用 Claude 模型吗?

可以,通过号池中 Google 账号上的模型映射实现,而不是使用单独的 Claude 账号。

我的 token 存在哪里?

存放在独立的 cloud_accounts.db 中,token_json 和 quota_json 使用 AES-256-GCM 加密。主密钥通过 keytar 存放在系统凭据存储中。详见安全模型。

可以商用吗?

请先查看许可证:继承自 AntigravityManager 的代码采用 CC BY-NC-SA 4.0(非商业),新代码采用 MIT。

局限与后续计划

  • 上游访问经由 Google 的 v1internal Cloud Code 端点和 OAuth scope(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 和 CODE_OF_CONDUCT.md。版本由 semantic-release 根据 Conventional Commits 生成。提交 PR 之前,以下命令必须通过:

pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test

📄 许可证

混合许可:继承自 AntigravityManager(作者 Draculabo)的代码采用 CC BY-NC-SA 4.0(非商业、相同方式共享);所有新代码采用 MIT。随着剩余原始代码被重写,项目正在迁移到 MIT,因此任何商业使用前请同时查看两个文件。