From 5594680130b0ecec0c26d0c7fc8a4201b3ca9e61 Mon Sep 17 00:00:00 2001
From: ianshaw <ianshaw027@gmail.com>
Date: Thu, 25 Dec 2025 23:53:44 -0800
Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E8=AF=B4=E6=98=8E=20AI=20Studi?=
 =?UTF-8?q?o=20OAuth=20Client=20=E9=9C=80=E5=8F=91=E5=B8=83=E4=B8=BA?=
 =?UTF-8?q?=E6=AD=A3=E5=BC=8F=E7=89=88=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README.md:
- 添加第 7 步：发布 OAuth 应用到正式版本
- 说明 Testing 模式限制（100 用户、7 天 token 过期）
- 说明 sensitive scope 可能需要 Google 审核

.env.example:
- 添加 OAuth Client 需发布为正式版本的说明
---
 deploy/.env.example | 16 ++++++++++------
 deploy/README.md    | 22 ++++++++++++++++++----
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/deploy/.env.example b/deploy/.env.example
index a8e87e8c..de7ea722 100644
--- a/deploy/.env.example
+++ b/deploy/.env.example
@@ -67,14 +67,18 @@ JWT_EXPIRE_HOUR=24
 #
 # 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
+#    - Default scopes: generative-language
+#    - OAuth Client: Requires your own OAuth 2.0 Client (内置 Gemini CLI client 不能申请 generative-language scope)
+#    - Requires: Create OAuth 2.0 Client in GCP Console + OAuth consent screen
 #    - Setup Guide: https://ai.google.dev/gemini-api/docs/oauth
+#    - ⚠️ IMPORTANT: OAuth Client 必须发布为正式版本 (Production)
+#      Testing 模式限制: 只能添加 100 个测试用户, refresh token 7 天后过期
+#      发布步骤: GCP Console → OAuth consent screen → PUBLISH APP
 #
 # 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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
+# Leave empty to use the built-in Gemini CLI OAuth client (Code Assist OAuth only).
+# To enable AI Studio OAuth, set your own OAuth client ID/secret here.
+GEMINI_OAUTH_CLIENT_ID=
+GEMINI_OAUTH_CLIENT_SECRET=
 # Optional; leave empty to auto-select scopes based on oauth_type
 GEMINI_OAUTH_SCOPES=
diff --git a/deploy/README.md b/deploy/README.md
index 1633bc79..5b127fc1 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -110,12 +110,15 @@ 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.
+**No configuration needed** - always uses the built-in Gemini CLI OAuth client (public).
 
 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
 
+> Note: Even if you configure `GEMINI_OAUTH_CLIENT_ID` / `GEMINI_OAUTH_CLIENT_SECRET` for AI Studio OAuth,
+> Code Assist OAuth will still use the built-in Gemini CLI client.
+
 **Requirements:**
 - Google account with access to Google Cloud Platform
 - A GCP project (auto-detected or manually specified)
@@ -142,15 +145,24 @@ Requires your own OAuth client credentials.
    - 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 scopes: `https://www.googleapis.com/auth/generative-language.retriever` (and optionally `https://www.googleapis.com/auth/cloud-platform`)
    - 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**
+   - Application type: **Web application** (or **Desktop app**)
    - Name: e.g., "Sub2API Gemini"
-   - Authorized redirect URIs: Add `https://your-domain.com/admin/accounts` (your frontend URL)
+   - Authorized redirect URIs: Add `http://localhost:1455/auth/callback`
 6. Copy the **Client ID** and **Client Secret**
+7. **⚠️ Publish to Production (IMPORTANT):**
+   - Go to "APIs & Services" → "OAuth consent screen"
+   - Click "PUBLISH APP" to move from Testing to Production
+   - **Testing mode limitations:**
+     - Only manually added test users can authenticate (max 100 users)
+     - Refresh tokens expire after 7 days
+     - Users must be re-added periodically
+   - **Production mode:** Any Google user can authenticate, tokens don't expire
+   - Note: For sensitive scopes, Google may require verification (demo video, privacy policy)
 
 **Step 2: Configure Environment Variables**
 
@@ -163,6 +175,8 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-client-secret
 
 1. Create a Gemini OAuth account and select **"AI Studio"** type
 2. Complete the OAuth flow
+   - After consent, your browser will be redirected to `http://localhost:1455/auth/callback?code=...&state=...`
+   - Copy the full callback URL (recommended) or just the `code` and paste it back into the Admin UI
 
 ### Method 3: API Key (Simplest)