Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,13 +132,13 @@ When the service runs on a server without Chrome, generate a pairing token on th
.\gemini-web2api.exe setup --email "name@example.com" --remote https://example.com
```

Setup creates `auth/<account>/storage-state.json` and verifies the live model catalog. Chrome import also saves the OAuth renewal material needed to renew cookies after Chrome exits. Daily startup is:
Setup creates `auth/<account>/storage-state.json` and verifies the live model catalog. Chrome import also saves the OAuth renewal material needed to renew cookies after Chrome exits. While the service is running, import accounts on the console's Import account page; when the `auth` directory that setup would write to is in use by a running service, setup exits with a message. Daily startup is:

```powershell
.\gemini-web2api.exe
```

The default auth directory is `auth`, and the default listener is `127.0.0.1:8007`. Linux and macOS can use existing cookies copied in an `auth` directory; renewal requires setup on the original Windows device.
The default auth directory is `auth`, and the default listener is `127.0.0.1:8007`. Linux and macOS can use a copied `auth` directory: accounts whose `storage-state.json` has `wrappedBindingKey` (renewal material bound to the original device) work until their cookies expire and are renewed on the original Windows device; other Chrome-imported accounts renew automatically on any system.

While running, the service rotates each account's sign-in cookies every 10 minutes, as the Gemini website does. Cookies that change in a response are written back to `auth/<account>/storage-state.json` and reused after a restart. Chrome-imported accounts renew automatically when their session expires.

Expand Down Expand Up @@ -282,11 +282,11 @@ Authentication accepts `Authorization: Bearer xxx`, `?key=xxx`, `x-goog-api-key`
Open `http://127.0.0.1:8007/` in a browser for the console, which uses the `/api/*` endpoints.

- **Connect**: the Connect page lists the base URLs of the three protocols and ready-made configuration for Claude Code, Codex, OpenCode, OpenClaw, omp, Magpie, Cherry Studio, SillyTavern, and curl with the selected model; Connection test lists models with the selected API key and sends the shortest request to the selected model, showing the result, duration, and error reason per request
- **Import accounts**: pasting cookies lists the accounts signed in to them; the import of the selected accounts runs in the background on the service and continues after you leave the page, which shows the progress and failure reason of each account
- **Import accounts**: pasting cookies lists the accounts signed in to them; the import of the selected accounts runs in the background on the service and continues after you leave the page, which shows the progress and failure reason of each account; re-importing an account that is already imported keeps its disabled state, and keeps its fixed proxy when the proxy field is left empty
- **Warm up**: Warm up on the All accounts page sends one minimal generation request for each selected account and model and lists the result, duration, and failure reason per row; the requests appear in the request records
- **Listen port**: when the configured port falls inside a range reserved by Windows (Hyper-V, WSL2, Docker), the service listens on the next available port and the console shows the actual address at the top
- **Remote access**: only local connections are accepted by default; with `ADMIN_AUTH_ENABLED=true`, `ADMIN_PASSWORD`, and `LISTEN_ADDR` on an externally reachable address, other devices can sign in; after 5 consecutive failed sign-ins, sign-in returns 429 with `Retry-After` for 60 seconds
- **Reverse proxy**: the proxy must pass the browser's original `Host` header to the service; in nginx, use `proxy_set_header Host $http_host;`. The service also works under a subpath, for example nginx `location /gemini/ { proxy_pass http://127.0.0.1:8007/; proxy_set_header Host $http_host; proxy_buffering off; }`; open the console at `/gemini/` and add the same prefix to client base URLs
- **Remote access**: only local connections are accepted by default; with `ADMIN_AUTH_ENABLED=true`, `ADMIN_PASSWORD`, and `LISTEN_ADDR` on an externally reachable address, other devices can sign in; after 5 consecutive failed sign-ins from one client, sign-in from that client returns 429 with `Retry-After` for 60 seconds
- **Reverse proxy**: the proxy must pass the browser's original `Host` header to the service and forward the client address in `X-Forwarded-For`; in nginx, use `proxy_set_header Host $http_host;` and `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`. The client address forwarded by a reverse proxy on the same machine is used for the local-access check, sign-in rate limiting, and request records. The service also works under a subpath, for example nginx `location /gemini/ { proxy_pass http://127.0.0.1:8007/; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_buffering off; }`; open the console at `/gemini/` and add the same prefix to client base URLs
- **Applying settings**: settings saved in the console are written back to `.env`, and values equal to the default are removed from it; the listen address, auth paths, and log format take effect after a restart, and everything else applies immediately; invalid values in `.env` run with the default and are listed at the top of the settings page; settings set by process environment variables or `--auth` and `--listen` show their source and are read-only
- **Online update**: the About page shows the latest GitHub release and its notes; after confirmation the command-line and desktop builds download the package for the current platform, verify its SHA-256, replace the executable, and restart into the new version, showing download progress meanwhile; the new version deletes the replaced files when it starts; downloads go through the first proxy in `PROXY`, or the system proxy when it is unset; Docker deployments update with the image

Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,13 +132,13 @@ Cookie 来自登录了多个 Google 账号的浏览器时,用 `--authuser` 指
.\gemini-web2api.exe setup --email "name@example.com" --remote https://example.com
```

`setup` 会生成 `auth/<账号>/storage-state.json` 并验证模型目录。Chrome 导入还会保存浏览器退出后续签所需的 OAuth 续签材料。日常启动只需运行:
`setup` 会生成 `auth/<账号>/storage-state.json` 并验证模型目录。Chrome 导入还会保存浏览器退出后续签所需的 OAuth 续签材料。服务已在运行时,账号从管理端“导入账号”页导入;`setup` 要写入的 `auth` 目录正被运行中的服务使用时,`setup` 退出并给出提示。日常启动只需运行:

```powershell
.\gemini-web2api.exe
```

默认读取 `auth` 目录并监听 `127.0.0.1:8007`。Linux 和 macOS 可以在现有 Cookie 有效期内使用已经生成的 `auth` 目录;续签仍需在原 Windows 设备执行。
默认读取 `auth` 目录并监听 `127.0.0.1:8007`。Linux 和 macOS 可以使用已经生成的 `auth` 目录:`storage-state.json` 带 `wrappedBindingKey`(续签材料绑定在原设备上)的账号在现有 Cookie 有效期内使用,续签在原 Windows 设备执行;其余 Chrome 导入的账号在任何系统上自动续签。

服务运行期间每 10 分钟为每个账号轮换一次登录 Cookie,与 Gemini 网页相同;响应中变化的 Cookie 写回 `auth/<账号>/storage-state.json`,重启后直接沿用。Chrome 导入的账号在登录态失效时自动续签。

Expand Down Expand Up @@ -282,11 +282,11 @@ GET /readyz
浏览器打开 `http://127.0.0.1:8007/` 进入管理端,页面使用 `/api/*` 接口。

- **接入**:“接入”页列出三种协议的 base URL,并按所选模型给出 Claude Code、Codex、OpenCode、OpenClaw、omp、Magpie、Cherry Studio、SillyTavern 与 curl 的现成配置;“连通测试”用所选 API key 读取模型列表并向所选模型发一条最短的请求,逐条显示结果、耗时与错误原因
- **导入账号**:粘贴 Cookie 后自动识别其中登录的账号,勾选后导入;导入在服务端后台运行,离开页面后继续,页面显示每个账号的进度与失败原因
- **导入账号**:粘贴 Cookie 后自动识别其中登录的账号,勾选后导入;导入在服务端后台运行,离开页面后继续,页面显示每个账号的进度与失败原因;已导入的账号重新导入时沿用停用状态,代理一栏留空时沿用原有固定代理
- **预热**:“全部账号”页的“预热”对选中的账号与模型各发一条最小生成请求,逐行显示结果、耗时与失败原因,请求计入请求记录
- **监听端口**:配置的端口落在 Windows 的系统保留端口段(Hyper-V、WSL2、Docker)时,服务改用其后第一个可用端口,管理端顶部显示实际地址
- **远程访问**:默认只接受本机访问;设置 `ADMIN_AUTH_ENABLED=true` 与 `ADMIN_PASSWORD`,并让 `LISTEN_ADDR` 监听对外地址后,可从其他设备登录;登录连续失败 5 次后,60 秒内的登录返回 429 并带 `Retry-After`
- **反向代理**:代理需把浏览器请求的原始 `Host` 头透传给服务,nginx 写 `proxy_set_header Host $http_host;`;也可挂在子路径下,例如 nginx `location /gemini/ { proxy_pass http://127.0.0.1:8007/; proxy_set_header Host $http_host; proxy_buffering off; }`,管理端从 `/gemini/` 打开,客户端的 Base URL 带上同一前缀
- **远程访问**:默认只接受本机访问;设置 `ADMIN_AUTH_ENABLED=true` 与 `ADMIN_PASSWORD`,并让 `LISTEN_ADDR` 监听对外地址后,可从其他设备登录;同一客户端登录连续失败 5 次后,60 秒内它的登录返回 429 并带 `Retry-After`
- **反向代理**:代理需把浏览器请求的原始 `Host` 头透传给服务,并以 `X-Forwarded-For` 转发客户端地址,nginx 写 `proxy_set_header Host $http_host;` 与 `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`;本机反向代理转发的客户端地址用于本机访问判定、登录限流与请求记录;也可挂在子路径下,例如 nginx `location /gemini/ { proxy_pass http://127.0.0.1:8007/; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_buffering off; }`,管理端从 `/gemini/` 打开,客户端的 Base URL 带上同一前缀
- **设置生效**:设置页修改的配置写回 `.env`,与默认值相同的项从 `.env` 中删去;监听地址、认证路径与日志格式重启后生效,其余立即生效;`.env` 中取值无效的项按默认值运行并在设置页顶部列出;由进程环境变量或 `--auth`、`--listen` 决定的项在设置页标出来源且不可修改
- **在线更新**:“关于”页显示 GitHub 最新发行版本与更新内容,命令行版与桌面版确认后下载当前平台的发行包、校验 SHA-256、替换可执行文件并重启到新版本,更新期间显示下载进度,新版本启动时删除被替换的旧文件;下载经 `PROXY` 的第一个代理发出,未设置时使用系统代理;Docker 部署随镜像更新

Expand Down
6 changes: 3 additions & 3 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,14 +127,14 @@ Release 的 Windows 包是只含桌面版 `gemini-web2api.exe` 的 zip,`setup`
| 加载 | `internal/auth` | 读取 `auth/<账号>/storage-state.json` |
| 初始化 | `accounts.Manager.Start` | 执行初始化链路,失败按间隔重试 |
| 轮换 | `internal/accounts`、`gemini/rotate.go` | 按官网周期轮换 Cookie 并重读目录 |
| 续签 | `internal/chromeauth` | Chrome 导入的账号在登录态失效时续签 |
| 续签 | `internal/chromeauth` | Chrome 导入的账号在登录态失效时续签,带设备绑定密钥的材料在原 Windows 设备上签发,其余材料在任何系统上签发 |
| 冷却 | `AccountPool.ReportFailure` | 按模型或整个账号移出调度 |
| 运行期变更 | `Manager.Add`、`Remove`、`SetEnabled`、`SetProxy`、`Verify` | 导入、删除、停用、改代理、重新连接 |
| 运行期变更 | `Manager.Add`、`Remove`、`SetEnabled`、`SetProxy`、`Verify` | 导入、删除、停用、改代理、重新连接;账号每次启动都取认证文件当前的 Cookie、续签材料与设置 |
| 代理 | `internal/accounts/proxies.go`、`internal/proxypool` | 分配代理,定时检测,故障时改绑 |
| 写回 | `internal/auth` | 变化的 Cookie 原子写回认证文件 |

- **启动**:`internal/app` 读取配置后创建 `AccountPool` 与 `accounts.Manager`,`Start` 为每个账号启动独立的初始化与轮换循环,并另建访客会话
- **管理端操作**:`internal/admin` 的账号接口调用 `Manager` 的对应方法,Chrome 导入、Cookie 导入与远程配对分别经 `ImportChrome`、`ImportCookie`、`ImportState` 写入认证目录后加入调度;Chrome 与 Cookie 导入是 `internal/admin/tasks.go` 的后台任务,发起请求结束后逐个账号继续,进度由 `GET /api/accounts/tasks` 读取;粘贴的 Cookie 由 `DiscoverCookie` 按 authuser 读出登录邮箱
- **管理端操作**:`internal/admin` 的账号接口调用 `Manager` 的对应方法,Chrome 导入、Cookie 导入与远程配对分别经 `ChromeImporter`、`ImportCookie`、`ImportState` 写入认证目录后加入调度;一次 Chrome 导入任务的各账号共用 `chromeauth.OpenChrome` 的账号发现结果与主密钥;三种导入写入已导入的账号时都经 `auth.Inherit` 沿用原有的停用标记与未重新填写的固定代理;Chrome 与 Cookie 导入是 `internal/admin/tasks.go` 的后台任务,发起请求结束后逐个账号继续,进度由 `GET /api/accounts/tasks` 读取;粘贴的 Cookie 由 `DiscoverCookie` 按 authuser 读出登录邮箱
- **预热**:`POST /api/warmup`(`internal/admin/warmup.go`)占用选定账号的请求槽,对选定模型发一条最小生成请求,结果写入请求账本,协议记为 `warmup`
- **状态读取**:管理端读取 `AccountPool.Status` 并附上各账号首页 `oPEP7c` 的登录邮箱,账号用量读取 `AccountPool.Usage`
- **冷却原因**:以代码记录,取值为 `usage_limit`、`rate_limited`、`model_mismatch`、`ip_restricted`、`captcha` 与 `upstream_error`,管理端按代码显示当前语言的文案
Expand Down
Loading
Loading