docs(readme): padrão SaaS
This commit is contained in:
1 parent
2a5d482c52
commit
e3652f43f5
14 files changed
+982
-894
No files matched your search
+195
-277
@@ -1,344 +1,262 @@
|
||||
<p align="center">
|
||||
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
|
||||
</p>
|
||||
<div align="center">
|
||||
|
||||
<h1 align="center">Gemini Nexus</h1>
|
||||
<img src="assets/readme/hero.zh-CN.png" width="100%" alt="Gemini Nexus:桌面网关,把多个 Google 账号汇成号池,在 http://localhost:8045/v1 提供兼容 OpenAI 与 Anthropic 的本地 API,配额不足时自动切换账号">
|
||||
|
||||
<p align="center">
|
||||
<strong>🚀 专业的多账户 AI 网关,支持 Google Gemini 和 Claude</strong>
|
||||
</p>
|
||||

|
||||

|
||||

|
||||
|
||||
<p align="center">
|
||||
<a href="README.md">English</a> | <a href="README.pt-BR.md">Português</a> | 中文 | <a href="README.es.md">Español</a>
|
||||
</p>
|
||||
<p><strong><a href="#-快速开始">快速开始</a></strong> · <a href="#-文档与开发">文档</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
|
||||
<img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="版本" />
|
||||
</a>
|
||||
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
|
||||
<img src="https://img.shields.io/github/downloads/evandrodevbr/GeminiNexus/total?style=flat-square&color=blue" alt="下载量" />
|
||||
</a>
|
||||
<a href="https://github.com/evandrodevbr/GeminiNexus/blob/main/LICENSE">
|
||||
<img src="https://img.shields.io/github/license/evandrodevbr/GeminiNexus?style=flat-square" alt="许可证" />
|
||||
</a>
|
||||
<img src="https://img.shields.io/badge/平台-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="平台" />
|
||||
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
|
||||
</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>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Windows 用户:** 如果在安装过程中看到 **“Windows 已保护你的电脑”** (SmartScreen) 警告,请点击 **“更多信息”** (More info),然后点击 **“仍要运行”** (Run anyway)。这是未签名的新应用预期的安全提示,属于正常现象。
|
||||
|
||||
---
|
||||
|
||||
## 📖 目录
|
||||
|
||||
- [✨ 为什么选择 Gemini Nexus?](#-为什么选择-gemini-nexus)
|
||||
- [🎯 功能特性](#-功能特性)
|
||||
- [📸 截图](#-截图)
|
||||
- [⚡ 安装与快速开始](#-安装与快速开始)
|
||||
- [🛠️ 技术栈](#️-技术栈)
|
||||
- [💻 开发](#-开发)
|
||||
- [❓ 常见问题](#-常见问题)
|
||||
- [🤝 参与贡献](#-参与贡献)
|
||||
- [📄 许可证](#-许可证)
|
||||
|
||||
---
|
||||
|
||||
## ✨ 为什么选择 Gemini Nexus?
|
||||
|
||||
在使用 AI 驱动的 IDE 和编程工具时,你是否遇到过这些问题?
|
||||
|
||||
- 😫 **配额限制:** 单个账户配额很快用完,需要频繁手动切换。
|
||||
- 🔄 **账户管理:** 管理多个 Google/Claude 账户非常繁琐。
|
||||
- 📊 **盲目使用:** 不知道已经消耗了多少 Token 或还剩多少配额。
|
||||
- 🔌 **集成问题:** 需要一个可靠的本地 API 代理,并且必须原生支持 OpenAI/Anthropic 协议。
|
||||
- 🔍 **缺乏透明度:** 无法查看代理在后台实际发送或接收的数据。
|
||||
|
||||
**Gemini Nexus** 解决所有这些问题。它是一个专业的 Electron 桌面应用,作为你的开发工具和 Google Gemini / Claude AI 之间的智能网关。
|
||||
|
||||
### 核心价值主张
|
||||
|
||||
- ✅ **无限账户池** — 添加任意数量的 Google Gemini 和 Claude 账户。
|
||||
- ✅ **智能自动切换** — 当配额不足或被限速时自动轮换到下一个可用账户。
|
||||
- ✅ **实时使用分析** — SaaS 级仪表板,配备面积图、趋势指标和模型分布。
|
||||
- ✅ **完整的代理可观测性** — 实时流量监控、请求重放和模型能力检查器。
|
||||
- ✅ **兼容 OpenAI 和 Anthropic** — 即插即用的代理,支持 Cursor、Windsurf、OpenCode 以及任何兼容 OpenAI 的工具。
|
||||
- ✅ **默认安全** — AES-256-GCM 加密,配合操作系统原生凭证管理。
|
||||
|
||||
---
|
||||
|
||||
## 🎯 功能特性
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>☁️ 云端账户池</h3>
|
||||
<ul>
|
||||
<li>通过 OAuth 添加无限量的 Google Gemini / Claude 账户</li>
|
||||
<li>显示头像、邮箱、状态和最后使用时间</li>
|
||||
<li>实时状态监控(活跃、限速、过期)</li>
|
||||
<li>每个账户可独立配置代理 URL</li>
|
||||
<li>设备身份档案管理及历史记录</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>📊 使用分析仪表板</h3>
|
||||
<ul>
|
||||
<li>实时 Token 消耗,每 15 秒自动刷新</li>
|
||||
<li>面积图展示每日/每小时的 Prompt 和 Completion Token</li>
|
||||
<li>趋势指标(与上一周期相比的百分比变化)</li>
|
||||
<li>统计卡片内嵌迷你折线图(Sparklines)</li>
|
||||
<li>水平柱状图展示模型分布排名</li>
|
||||
<li>Prompt/Completion 比例可视化</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>🔌 本地 API 代理(网关)</h3>
|
||||
<ul>
|
||||
<li>兼容 OpenAI <code>/v1/chat/completions</code></li>
|
||||
<li>兼容 Anthropic <code>/v1/messages</code></li>
|
||||
<li>完整的 SSE 流式传输支持(已在 Cursor, Windsurf, OpenCode 测试)</li>
|
||||
<li>模型映射(如 <code>claude-sonnet-4-6</code> → <code>gemini-3-flash</code>)</li>
|
||||
<li>可配置端口、超时时间和 API 密钥</li>
|
||||
<li>模型可见性控制(隐藏/显示特定模型)</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>🔄 智能自动切换</h3>
|
||||
<ul>
|
||||
<li>无限池模式,智能备份选择</li>
|
||||
<li>配额低于 5% 或被限速时自动切换</li>
|
||||
<li>每 5 分钟后台监控</li>
|
||||
<li>优雅降级,带状态原因追踪</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>🔍 代理可观测性(高级)</h3>
|
||||
<ul>
|
||||
<li><strong>流量监控</strong> — 实时请求/响应日志,含延迟和模型信息</li>
|
||||
<li><strong>请求重放</strong> — 重放任意请求进行调试</li>
|
||||
<li><strong>模型能力</strong> — 检查每个模型对视觉、思考、流式、JSON 模式的支持</li>
|
||||
<li><strong>开发者工具</strong> — cURL 和 Python 代码生成,一键复制</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>🔐 安全与加密</h3>
|
||||
<ul>
|
||||
<li>所有敏感数据采用 AES-256-GCM 加密</li>
|
||||
<li>集成操作系统原生凭证管理器 (Keytar + SafeStorage)</li>
|
||||
<li>自动迁移旧版明文数据</li>
|
||||
<li>每个账户的 Token 和配额均加密存储</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>⚙️ 设置与自定义</h3>
|
||||
<ul>
|
||||
<li>深色 / 浅色 / 跟随系统主题</li>
|
||||
<li>多语言:English & Português (Brasil)</li>
|
||||
<li>每个账户可独立覆盖代理 URL</li>
|
||||
<li>模型可见性开关</li>
|
||||
<li>日志目录访问</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>🖥️ 桌面体验</h3>
|
||||
<ul>
|
||||
<li>原生 Electron 应用,系统托盘集成</li>
|
||||
<li>可折叠侧边栏,状态持久化</li>
|
||||
<li>响应式布局适配所有视图</li>
|
||||
<li>状态栏实时显示代理和连接指标</li>
|
||||
<li>错误边界处理以及友好的用户提示</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
</div>
|
||||
|
||||
## 📸 截图
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/main.png" alt="Main" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/7config.png" alt="Config" width="80%" />
|
||||
</p>
|
||||
<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>
|
||||
|
||||
您可以从我们的 [Releases 页面](https://github.com/evandrodevbr/GeminiNexus/releases) 下载适用于 Windows、macOS 和 Linux 的最新预编译版本。
|
||||
## 🎯 功能特性
|
||||
|
||||
*(如果您使用的是 Windows 并在安装时遇到了 SmartScreen 提示,请参阅页面顶部的警告)。*
|
||||
只用一个 Google 账号配合 AI IDE,意味着配额很快耗尽、要手动切换账号,也看不到代理到底向上游发送了什么。Gemini Nexus 把所有账号放进一个号池,通过一个本地端点统一提供服务。
|
||||
|
||||
### 🔌 配合 AI IDE 使用
|
||||
<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>
|
||||
|
||||
在代理运行并至少添加一个账户后,配置您首选的 IDE(Cursor、Windsurf、OpenCode 等):
|
||||
已保存的凭据使用 AES-256-GCM 加密,主密钥存放在系统钥匙串中(见[安全模型](#安全模型))。
|
||||
|
||||
```plaintext
|
||||
API Base URL: http://localhost:10100/v1
|
||||
API Key: (从应用的 Proxy 页面复制)
|
||||
Model: gemini-3-flash (或您选择的任何映射模型)
|
||||
```
|
||||
## 工作原理
|
||||
|
||||
### 🛠️ 从源码构建
|
||||
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 % 或账号被限流时,自动切换生效。
|
||||
|
||||
#### 前置要求
|
||||
包含各组件的完整流程见[架构](#架构)。
|
||||
|
||||
- **Node.js** v20 或更高版本
|
||||
- **npm** (本项目使用 `package-lock.json`)
|
||||
## ⚡ 快速开始
|
||||
|
||||
#### 步骤
|
||||
目前 [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://github.com/evandrodevbr/GeminiNexus.git
|
||||
cd GeminiNexus
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 启动开发环境
|
||||
npm start
|
||||
|
||||
# 构建生产版本(例如 Windows 安装程序)
|
||||
npm run make
|
||||
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, React 19, TypeScript |
|
||||
| **构建** | Vite, Electron Forge |
|
||||
| **样式** | Tailwind CSS v4, Radix UI, Lucide Icons |
|
||||
| **状态** | TanStack Query, TanStack Router |
|
||||
| **后端** | NestJS (内部网关), ORPC (类型安全 RPC) |
|
||||
| **数据库** | Better-SQLite3, Drizzle ORM |
|
||||
| **图表** | Nivo (Line, Bar, Pie) |
|
||||
| **测试** | Vitest, Playwright |
|
||||
| 层 | 技术 |
|
||||
|---|---|
|
||||
| 桌面外壳 | 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 |
|
||||
|
||||
---
|
||||
## 架构
|
||||
|
||||
## 💻 开发
|
||||
|
||||
```bash
|
||||
# 启动开发环境 (Electron + Vite HMR)
|
||||
npm start
|
||||
|
||||
# 运行代码规范检查
|
||||
npm run lint
|
||||
|
||||
# 类型检查
|
||||
npm run type-check
|
||||
|
||||
# 格式化代码
|
||||
npm run format:write
|
||||
|
||||
# 运行测试
|
||||
npm test
|
||||
```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 SmartScreen 警告("Windows 已保护你的电脑")?</b></summary>
|
||||
<summary><b>Windows 提示“Windows 已保护你的电脑”,正常吗?</b></summary>
|
||||
|
||||
正常。构建产物没有代码签名。请点击 **更多信息 → 仍要运行**。
|
||||
|
||||
是的,对于未签名的新应用,这是一个常见的警告。请点击 **"更多信息"** (More info),然后点击 **"仍要运行"** (Run anyway)。详情请参阅 README 顶部的提示。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>问:从源码构建时应用无法启动?</b></summary>
|
||||
<summary><b>IDE 连不上代理。</b></summary>
|
||||
|
||||
代理默认关闭:请在 Proxy 页面启用。默认端口为 `8045`(开发构建为 `8046`),可在该页面修改。从同一页面复制 API key,并确认号池中至少有一个账号。
|
||||
|
||||
1. 确保所有依赖均已安装:`npm install`
|
||||
2. 检查 Node.js 版本是否 >= 20。
|
||||
3. 尝试删除 `node_modules` 并重新安装。
|
||||
4. 在 Windows 上,请确保已安装 WiX Toolset 以便执行 `npm run make` 命令。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>问:账户登录失败?</b></summary>
|
||||
<summary><b>需要 API key 吗?</b></summary>
|
||||
|
||||
`api_key` 为空时代理以开放模式运行。启用后它监听 `0.0.0.0`,所以请设置 key 并妥善保管。
|
||||
|
||||
1. 确保您的网络连接正常。
|
||||
2. 尝试清除应用数据并重新登录。
|
||||
3. 检查该账户是否已被 Google/Claude 限制。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>问:IDE 无法连接到代理?</b></summary>
|
||||
<summary><b>能使用 Claude 模型吗?</b></summary>
|
||||
|
||||
可以,通过号池中 Google 账号上的模型映射实现,而不是使用单独的 Claude 账号。
|
||||
|
||||
1. 确保代理正在运行(查看状态栏的绿色指示器)。
|
||||
2. 确认端口与您 IDE 中的配置一致(默认为 `10100`)。
|
||||
3. 直接从 Proxy 页面复制 API 密钥并粘贴到 IDE 设置中。
|
||||
4. 确保在 Accounts 页面中至少有一个活跃的账户。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>问:Token 计数显示为零?</b></summary>
|
||||
<summary><b>我的 token 存在哪里?</b></summary>
|
||||
|
||||
存放在独立的 `cloud_accounts.db` 中,`token_json` 和 `quota_json` 使用 AES-256-GCM 加密。主密钥通过 `keytar` 存放在系统凭据存储中。详见[安全模型](#安全模型)。
|
||||
|
||||
1. 这是早期版本中的一个已知漏洞 — 请更新至最新版本。
|
||||
2. 目前 Token 追踪功能已能正确处理流式元数据及预估计数。
|
||||
3. 使用数据会在 Usage Analytics 页面每 15 秒自动刷新。
|
||||
</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`](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
|
||||
```
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用双重许可结构:
|
||||
|
||||
- **原始代码**来自 [Draculabo](https://github.com/Draculabo) 的 [AntigravityManager](https://github.com/Draculabo/AntigravityManager):采用 [CC BY-NC-SA 4.0](LICENSE) 许可。
|
||||
- **所有新代码、功能和架构**由 [evandrodevbr](https://github.com/evandrodevbr) 开发:采用 [MIT 许可证](LICENSE-MIT)。
|
||||
|
||||
> 🔄 **迁移通知:** 本项目正在积极迁移到完全开源许可证(MIT)。随着剩余原始代码的逐步重写,整个项目将过渡到 MIT。我们致力于将 Gemini Nexus 打造为 100% 开源项目。
|
||||
混合许可:继承自 [AntigravityManager](https://github.com/Draculabo/AntigravityManager)(作者 Draculabo)的代码采用 [CC BY-NC-SA 4.0](LICENSE)(非商业、相同方式共享);所有新代码采用 [MIT](LICENSE-MIT)。随着剩余原始代码被重写,项目正在迁移到 MIT,因此任何商业使用前请同时查看两个文件。
|
||||
|
||||
---
|
||||
|
||||
## 🙏 致谢
|
||||
<div align="center">
|
||||
|
||||
本项目最初是从 [Draculabo](https://github.com/Draculabo) 创建的 [AntigravityManager](https://github.com/Draculabo/AntigravityManager) 分支而来的。最初的代理概念和早期的 Electron 框架基于他的工作。
|
||||
<img src="docs/assets/logo.png" width="56" alt="Gemini Nexus 标志">
|
||||
|
||||
自从分支以来,[evandrodevbr](https://github.com/evandrodevbr) **重写、重新设计并扩展了绝大部分代码库**,包括但不限于:
|
||||
<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>
|
||||
|
||||
- 完整的 UI/UX 重新设计(导航、账户、使用分析、代理管理)
|
||||
- 使用分析仪表板,包含成本跟踪、Token 平均值以及 OpenRouter 集成
|
||||
- 流量监视器,提供按请求查看的 Token/成本检查
|
||||
- 环境隔离(dev/prod)、CI/CD 流水线和测试基础设施
|
||||
- IDE 快速设置(OpenCode、Cursor、VS Code、Claude Code)
|
||||
- 自定义模型定价配置
|
||||
- 所有文档和国际化(EN, PT-BR, ES, ZH-CN)
|
||||
</div>
|
||||
Reference in new issue
Block a user