Refactor multiple flows to enhance performance, boost scalability, and ensure stability.

.github/workflows/docker.yaml

@@ -6,11 +6,15 @@ on:
       - main
     tags:
       - "v*"
-    paths-ignore:
-      - "**/*.md"
-      - ".github/*"
-      - "LICENSE"
-      - ".gitignore"
+    paths:
+      - "app/**"
+      - "config/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "Dockerfile"
+      - "run.py"
+      - ".github/workflows/docker.yaml"
+  workflow_dispatch:
 
 env:
   REGISTRY: ghcr.io
@@ -25,24 +29,24 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
 
       - name: Log in to Container Registry
-        uses: docker/login-action@v4
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Extract metadata
         id: meta
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -54,7 +58,7 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
         with:
           context: .
           push: true

.github/workflows/lint.yaml

@@ -0,0 +1,41 @@
+name: Lint and Type Check
+
+on:
+  push:
+    paths:
+      - "**.py"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/lint.yaml"
+  pull_request:
+    paths:
+      - "**.py"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/lint.yaml"
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Ruff
+        run: uv run ruff check .
+
+      - name: Run Ruff Format
+        run: uv run ruff format . --check
+
+      - name: Run Ty Check
+        run: uv run ty check

.github/workflows/track.yml

@@ -2,7 +2,7 @@ name: Update gemini-webapi
 
 on:
   schedule:
-    - cron: "0 0 * * *" # Runs every day at midnight
+    - cron: "0 0 * * *"
   workflow_dispatch:
 
 jobs:
@@ -11,13 +11,13 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
+
     steps:
-      - uses: actions/checkout@v6
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
-        with:
-          version: "latest"
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
 
       - name: Update gemini-webapi
         id: update
@@ -33,8 +33,8 @@ jobs:
           fi
           echo "Current gemini-webapi version: $OLD_VERSION"
 
-          # Update the package using uv, which handles pyproject.toml and uv.lock
-          uv add --upgrade gemini-webapi
+          # Update gemini-webapi to the latest version
+          uv lock --upgrade-package gemini-webapi
 
           # Get new version of gemini-webapi after upgrade
           NEW_VERSION=$(uv pip show gemini-webapi | grep ^Version: | awk '{print $2}')
@@ -56,7 +56,7 @@ jobs:
 
       - name: Create Pull Request
         if: steps.update.outputs.updated == 'true'
-        uses: peter-evans/create-pull-request@v8
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: ":arrow_up: update gemini-webapi to ${{ steps.update.outputs.version }}"

Dockerfile

@@ -3,10 +3,14 @@ FROM ghcr.io/astral-sh/uv:python3.13-trixie-slim
 LABEL org.opencontainers.image.title="Gemini-FastAPI" \
       org.opencontainers.image.description="Web-based Gemini models wrapped into an OpenAI-compatible API."
 
+USER root
+
 WORKDIR /app
 
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    tini \
+    tini curl ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 
 ENV UV_COMPILE_BYTECODE=1 \
@@ -22,6 +26,9 @@ COPY run.py .
 
 EXPOSE 8000
 
+HEALTHCHECK --interval=30s --timeout=10s --start-period=300s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
 ENTRYPOINT ["/usr/bin/tini", "--"]
 
 CMD ["uv", "run", "--no-dev", "run.py"]

README.md

@@ -1,22 +1,22 @@
 # Gemini-FastAPI
 
 [![Python 3.13](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
-[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-green.svg)](https://fastapi.tiangolo.com/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 [ English | [中文](README.zh.md) ]
 
 Web-based Gemini models wrapped into an OpenAI-compatible API. Powered by [HanaokaYuzu/Gemini-API](https://github.com/HanaokaYuzu/Gemini-API).
 
-**✅ Call Gemini's web-based models via API without an API Key, completely free!**
+**Call Gemini's web-based models via API without an API Key, completely free!**
 
 ## Features
 
-- **🔐 No Google API Key Required**: Use web cookies to freely access Gemini's models via API.
-- **🔍 Google Search Included**: Get up-to-date answers using web-based Gemini's search capabilities.
-- **💾 Conversation Persistence**: LMDB-based storage supporting multi-turn conversations.
-- **🖼️ Multi-modal Support**: Support for handling text, images, and file uploads.
-- **⚖️ Multi-account Load Balancing**: Distribute requests across multiple accounts with per-account proxy settings.
+- **No Google API Key Required**: Use web cookies to freely access Gemini's models via API.
+- **Google Search Included**: Get up-to-date answers using web-based Gemini's search capabilities.
+- **Conversation Persistence**: LMDB-based storage supporting multi-turn conversations.
+- **Multi-modal Support**: Support for handling text, images, and file uploads.
+- **Multi-account Load Balancing**: Distribute requests across multiple accounts with per-account proxy settings.
 
 ## Quick Start
 
@@ -25,7 +25,7 @@ Web-based Gemini models wrapped into an OpenAI-compatible API. Powered by [Hanao
 ### Prerequisites
 
 - Python 3.13
-- Google account with Gemini access on web
+- Google account with Gemini access on web (Enable **[Gemini Apps activity](https://myactivity.google.com/product/gemini)** for best conversation persistence)
 - `secure_1psid` and `secure_1psidts` cookies from Gemini web interface
 
 ### Installation
@@ -96,7 +96,7 @@ These endpoints are designed to be compatible with OpenAI's API structure, allow
 ### Utility Endpoints
 
 - **`GET /health`**: Health check endpoint. Returns the status of the server, configured Gemini clients, and conversation storage.
-- **`GET /images/{filename}`**: Internal endpoint to serve generated images. Requires a valid token (automatically included in image URLs returned by the API).
+- **`GET /media/{filename}`**: Internal endpoint to serve generated media. Requires a valid token (automatically included in image URLs returned by the API).
 
 ## Docker Deployment
 
@@ -180,6 +180,7 @@ export CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="your-secure-1psidts"
 # Override optional proxy settings for client 0
 export CONFIG_GEMINI__CLIENTS__0__PROXY="socks5://127.0.0.1:1080"
 
+
 # Override conversation storage size limit
 export CONFIG_STORAGE__MAX_SIZE=268435456  # 256 MB
 ```
@@ -204,6 +205,11 @@ To use Gemini-FastAPI, you need to extract your Gemini session cookies:
    - `__Secure-1PSID`
    - `__Secure-1PSIDTS`
 
+> [!IMPORTANT]
+> **Enable [Gemini Apps activity](https://myactivity.google.com/product/gemini)** to ensure stable conversation persistence.
+>
+> While active chat turns may work temporarily without it, any transient error, TLS session restart, or server reboot can cause Google to expire the conversation metadata. If this setting is disabled, the model will **completely lose the context of your multi-turn conversation**, making old threads unreachable even if they are stored in your local LMDB.
+
 > [!TIP]
 > For detailed instructions, refer to the [HanaokaYuzu/Gemini-API authentication guide](https://github.com/HanaokaYuzu/Gemini-API?tab=readme-ov-file#authentication).
 

README.zh.md

@@ -1,22 +1,22 @@
 # Gemini-FastAPI
 
 [![Python 3.13](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
-[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-green.svg)](https://fastapi.tiangolo.com/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 [ [English](README.md) | 中文 ]
 
 将 Gemini 网页端模型封装为兼容 OpenAI API 的 API Server。基于 [HanaokaYuzu/Gemini-API](https://github.com/HanaokaYuzu/Gemini-API) 实现。
 
-**✅ 无需 API Key，免费通过 API 调用 Gemini 网页端模型！**
+**无需 API Key，免费通过 API 调用 Gemini 网页端模型！**
 
 ## 功能特性
 
-- 🔐 **无需 Google API Key**：只需网页 Cookie，即可免费通过 API 调用 Gemini 模型。
-- 🔍 **内置 Google 搜索**：API 已内置 Gemini 网页端的搜索能力，模型响应更加准确。
-- 💾 **会话持久化**：基于 LMDB 存储，支持多轮对话历史记录。
-- 🖼️ **多模态支持**：可处理文本、图片及文件上传。
-- ⚖️ **多账户负载均衡**：支持多账户分发请求，可为每个账户单独配置代理。
+- **无需 Google API Key**：只需网页 Cookie，即可免费通过 API 调用 Gemini 模型。
+- **内置 Google 搜索**：API 已内置 Gemini 网页端的搜索能力，模型响应更加准确。
+- **会话持久化**：基于 LMDB 存储，支持多轮对话历史记录。
+- **多模态支持**：可处理文本、图片及文件上传。
+- **多账户负载均衡**：支持多账户分发请求，可为每个账户单独配置代理。
 
 ## 快速开始
 
@@ -25,7 +25,7 @@
 ### 前置条件
 
 - Python 3.13
-- 拥有网页版 Gemini 访问权限的 Google 账号
+- 拥有网页版 Gemini 访问权限的 Google 账号 (开启 **[Gemini Apps 应用活动](https://myactivity.google.com/product/gemini)** 以获得最佳会话持久化体验)
 - 从 Gemini 网页获取的 `secure_1psid` 和 `secure_1psidts` Cookie
 
 ### 安装
@@ -56,7 +56,7 @@ gemini:
     - id: "client-a"
       secure_1psid: "YOUR_SECURE_1PSID_HERE"
       secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE"
-      proxy: null # Optional proxy URL (null/empty keeps direct connection)
+      proxy: null # 可选代理 URL (null/空值则保持直连)
 ```
 
 > [!NOTE]
@@ -93,10 +93,10 @@ python run.py
 
 - **`POST /v1/responses`**: 用于复杂交互模式的专用接口，支持分步输出、生成图片及工具调用等更丰富的响应项。
 
-### 辅助与系统接口
+### 实用工具接口
 
-- **`GET /health`**: 健康检查接口。返回服务器运行状态、已配置的 Gemini 客户端健康度以及对话存储统计信息。
-- **`GET /images/{filename}`**: 用于访问生成的图片的内部接口。需携带有效 Token（API 返回的图片 URL 中已自动包含该 Token）。
+- **`GET /health`**: 健康检查接口。返回服务器、已配置的 Gemini 客户端以及对话存储的状态。
+- **`GET /media/{filename}`**: 用于分发生成的媒体内容的内部接口。需要有效的 Token（API 返回的图片 URL 中已自动包含该 Token）。
 
 ## Docker 部署
 
@@ -180,6 +180,7 @@ export CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="your-secure-1psidts"
 # 覆盖 Client 0 的代理设置
 export CONFIG_GEMINI__CLIENTS__0__PROXY="socks5://127.0.0.1:1080"
 
+
 # 覆盖对话存储大小限制
 export CONFIG_STORAGE__MAX_SIZE=268435456  # 256 MB
 ```
@@ -203,8 +204,10 @@ export CONFIG_STORAGE__MAX_SIZE=268435456  # 256 MB
    - `__Secure-1PSID`
    - `__Secure-1PSIDTS`
 
-> [!TIP]
-> 详细操作请参考 [HanaokaYuzu/Gemini-API 认证指南](https://github.com/HanaokaYuzu/Gemini-API?tab=readme-ov-file#authentication)。
+> [!IMPORTANT]
+> **请开启 [Gemini Apps 应用活动](https://myactivity.google.com/product/gemini)** 以确保稳定的会话持久化。
+>
+> 虽然在没有开启该设置的情况下，连续的聊天过程可能暂时正常，但任何瞬时错误、TLS 会话重启或服务器重启都可能导致 Google 端过期的会话元数据。如果该设置被禁用，模型将 **完全丢失多轮对话的上下文**，导致即使本地 LMDB 中存有历史记录，旧对话也将无法继续。
 
 ### 代理设置
 

app/main.py

@@ -6,11 +6,11 @@
 
 from .server.chat import router as chat_router
 from .server.health import router as health_router
-from .server.images import router as images_router
+from .server.media import router as media_router
 from .server.middleware import (
     add_cors_middleware,
     add_exception_handler,
-    cleanup_expired_images,
+    cleanup_expired_media,
 )
 from .services import GeminiClientPool, LMDBConversationStore
 
@@ -33,7 +33,7 @@ async def _run_retention_cleanup(stop_event: asyncio.Event) -> None:
     while not stop_event.is_set():
         try:
             store.cleanup_expired()
-            cleanup_expired_images(store.retention_days)
+            cleanup_expired_media(store.retention_days)
         except Exception:
             logger.exception("LMDB retention cleanup task failed.")
 
@@ -76,6 +76,11 @@ async def lifespan(app: FastAPI):
         yield
     finally:
         cleanup_stop_event.set()
+        try:
+            await pool.close()
+        except Exception:
+            logger.exception("Failed to close Gemini client pool gracefully.")
+
         try:
             await cleanup_task
         except asyncio.CancelledError:
@@ -99,6 +104,6 @@ def create_app() -> FastAPI:
 
     app.include_router(health_router, tags=["Health"])
     app.include_router(chat_router, tags=["Chat"])
-    app.include_router(images_router, tags=["Images"])
+    app.include_router(media_router, tags=["Media"])
 
     return app