docs(deploy): 更新部署配置和文档

- .env.example: 新增 Gemini OAuth 环境变量配置示例 - config.example.yaml: 新增 Gemini OAuth 配置示例 - README.md: 更新部署文档 - docker-compose.yml: 添加 Gemini OAuth 环境变量传递
2025-12-25 21:25:16 -08:00
parent 2d1a15b196
commit 79d1585250
4 changed files with 129 additions and 6 deletions
--- a/deploy/.env.example
+++ b/deploy/.env.example
@@ -53,3 +53,28 @@ ADMIN_PASSWORD=
 # Leave empty to auto-generate (recommended)
 JWT_SECRET=
 JWT_EXPIRE_HOUR=24
+
+# -----------------------------------------------------------------------------
+# Gemini OAuth (OPTIONAL, required only for Gemini OAuth accounts)
+# -----------------------------------------------------------------------------
+# Sub2API supports TWO Gemini OAuth modes:
+#
+# 1. Code Assist OAuth (需要 GCP project_id)
+#    - Uses: cloudcode-pa.googleapis.com (Code Assist API)
+#    - Auto scopes: cloud-platform + userinfo.email + userinfo.profile
+#    - OAuth Client: Can use built-in Gemini CLI client (留空即可)
+#    - Requires: Google Cloud Platform project with Code Assist enabled
+#
+# 2. AI Studio OAuth (不需要 project_id)
+#    - Uses: generativelanguage.googleapis.com (AI Studio API)
+#    - Default scopes: cloud-platform (+ userinfo.*)
+#    - OAuth Client: Leave empty to use built-in Gemini CLI client; or provide your own.
+#    - Requires: Create OAuth 2.0 Client in GCP Console
+#    - Setup Guide: https://ai.google.dev/gemini-api/docs/oauth
+#
+# Configuration:
+# Use Gemini CLI's public OAuth credentials (same as official Google Gemini CLI tool):
+GEMINI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
+GEMINI_OAUTH_CLIENT_SECRET=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
+# Optional; leave empty to auto-select scopes based on oauth_type
+GEMINI_OAUTH_SCOPES=
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -96,11 +96,93 @@ docker-compose down -v
 | `ADMIN_PASSWORD` | No | *(auto-generated)* | Admin password |
 | `JWT_SECRET` | No | *(auto-generated)* | JWT secret |
 | `TZ` | No | `Asia/Shanghai` | Timezone |
+| `GEMINI_OAUTH_CLIENT_ID` | No | *(builtin)* | Google OAuth client ID (Gemini OAuth). Leave empty to use the built-in Gemini CLI client. |
+| `GEMINI_OAUTH_CLIENT_SECRET` | No | *(builtin)* | Google OAuth client secret (Gemini OAuth). Leave empty to use the built-in Gemini CLI client. |
+| `GEMINI_OAUTH_SCOPES` | No | *(default)* | OAuth scopes (Gemini OAuth) |

 See `.env.example` for all available options.

 ---

+## Gemini OAuth Configuration
+
+Sub2API supports three methods to connect to Gemini:
+
+### Method 1: Code Assist OAuth (Recommended for GCP Users)
+
+**No configuration needed** - uses built-in Gemini CLI OAuth client.
+
+1. Leave `GEMINI_OAUTH_CLIENT_ID` and `GEMINI_OAUTH_CLIENT_SECRET` empty
+2. In the Admin UI, create a Gemini OAuth account and select **"Code Assist"** type
+3. Complete the OAuth flow in your browser
+
+**Requirements:**
+- Google account with access to Google Cloud Platform
+- A GCP project (auto-detected or manually specified)
+
+**How to get Project ID (if auto-detection fails):**
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Click the project dropdown at the top of the page
+3. Copy the Project ID (not the project name) from the list
+4. Common formats: `my-project-123456` or `cloud-ai-companion-xxxxx`
+
+### Method 2: AI Studio OAuth (For Regular Google Accounts)
+
+Requires your own OAuth client credentials.
+
+**Step 1: Create OAuth Client in Google Cloud Console**
+
+1. Go to [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
+2. Create a new project or select an existing one
+3. **Enable the Generative Language API:**
+   - Go to "APIs & Services" → "Library"
+   - Search for "Generative Language API"
+   - Click "Enable"
+4. **Configure OAuth Consent Screen** (if not done):
+   - Go to "APIs & Services" → "OAuth consent screen"
+   - Choose "External" user type
+   - Fill in app name, user support email, developer contact
+   - Add scopes: `https://www.googleapis.com/auth/generative-language`
+   - Add test users (your Google account email)
+5. **Create OAuth 2.0 credentials:**
+   - Go to "APIs & Services" → "Credentials"
+   - Click "Create Credentials" → "OAuth client ID"
+   - Application type: **Web application**
+   - Name: e.g., "Sub2API Gemini"
+   - Authorized redirect URIs: Add `https://your-domain.com/admin/accounts` (your frontend URL)
+6. Copy the **Client ID** and **Client Secret**
+
+**Step 2: Configure Environment Variables**
+
+```bash
+GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-client-secret
+```
+
+**Step 3: Create Account in Admin UI**
+
+1. Create a Gemini OAuth account and select **"AI Studio"** type
+2. Complete the OAuth flow
+
+### Method 3: API Key (Simplest)
+
+1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. Click "Create API key"
+3. In Admin UI, create a Gemini **API Key** account
+4. Paste your API key (starts with `AIza...`)
+
+### Comparison Table
+
+| Feature | Code Assist OAuth | AI Studio OAuth | API Key |
+|---------|-------------------|-----------------|---------|
+| Setup Complexity | Easy (no config) | Medium (OAuth client) | Easy |
+| GCP Project Required | Yes | No | No |
+| Custom OAuth Client | No (built-in) | Yes (required) | N/A |
+| Rate Limits | GCP quota | Standard | Standard |
+| Best For | GCP developers | Regular users needing OAuth | Quick testing |
+
+---
+
 ## Binary Installation

 For production servers using systemd.
--- a/deploy/config.example.yaml
+++ b/deploy/config.example.yaml
@@ -89,12 +89,21 @@ pricing:
  hash_check_interval_minutes: 10

 # =============================================================================
-# Gemini (Optional)
+# Gemini OAuth (Required for Gemini accounts)
 # =============================================================================
+# Sub2API supports TWO Gemini OAuth modes:
+#
+# 1. Code Assist OAuth (需要 GCP project_id)
+#    - Uses: cloudcode-pa.googleapis.com (Code Assist API)
+#
+# 2. AI Studio OAuth (不需要 project_id)
+#    - Uses: generativelanguage.googleapis.com (AI Studio API)
+#
+# Default: Uses Gemini CLI's public OAuth credentials (same as Google's official CLI tool)
 gemini:
  oauth:
-    # Google OAuth Client ID / Secret (for GeminiCli / Code Assist internal API)
-    client_id: ""
-    client_secret: ""
-    # Optional scopes (space-separated). Leave empty to use default cloud-platform scope.
+    # Gemini CLI public OAuth credentials (works for both Code Assist and AI Studio)
+    client_id: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com"
+    client_secret: "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"
+    # Optional scopes (space-separated). Leave empty to auto-select based on oauth_type.
    scopes: ""
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -16,7 +16,7 @@ services:
  # Sub2API Application
  # ===========================================================================
  sub2api:
-    image: sub2api:latest
+    image: weishaw/sub2api:latest
    container_name: sub2api
    restart: unless-stopped
    ports:
@@ -78,6 +78,13 @@ services:
      # Common values: Asia/Shanghai, America/New_York, Europe/London, UTC
      # =======================================================================
      - TZ=${TZ:-Asia/Shanghai}
+
+      # =======================================================================
+      # Gemini OAuth Configuration (for Gemini accounts)
+      # =======================================================================
+      - GEMINI_OAUTH_CLIENT_ID=${GEMINI_OAUTH_CLIENT_ID:-}
+      - GEMINI_OAUTH_CLIENT_SECRET=${GEMINI_OAUTH_CLIENT_SECRET:-}
+      - GEMINI_OAUTH_SCOPES=${GEMINI_OAUTH_SCOPES:-}
    depends_on:
      postgres:
        condition: service_healthy