clean deploy

.dockerignore

@@ -0,0 +1,14 @@
+.git
+.gitignore
+.idea
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+
+web/.next
+web/node_modules
+
+assets
+README.md

.env.example

@@ -0,0 +1,48 @@
+# ============================================
+# ChatGPT2API 环境变量配置示例
+# ============================================
+
+# 认证密钥（必填）
+CHATGPT2API_AUTH_KEY=your_secret_key_here
+
+# 基础 URL（可选，用于生成图片 URL）
+# CHATGPT2API_BASE_URL=https://your-domain.com
+
+# ============================================
+# 存储后端配置
+# ============================================
+
+# 存储后端类型（可选值: json, sqlite, postgres, git）
+# 默认: json
+STORAGE_BACKEND=json
+
+# ============================================
+# 数据库配置（当 STORAGE_BACKEND=sqlite/postgres 时使用）
+# ============================================
+
+# PostgreSQL 示例
+# DATABASE_URL=postgresql://user:password@localhost:5432/chatgpt2api
+
+# Supabase 示例
+# DATABASE_URL=postgresql://postgres.xxx:password@aws-1-us-west-1.pooler.supabase.com:5432/postgres
+
+# SQLite 示例（不指定时自动使用 data/accounts.db）
+# DATABASE_URL=sqlite:///app/data/accounts.db
+
+# ============================================
+# Git 仓库配置（当 STORAGE_BACKEND=git 时使用）
+# ============================================
+
+# Git 仓库地址（必填）
+# GIT_REPO_URL=https://github.com/your-username/your-private-repo.git
+
+# Git 访问令牌（必填）
+# GitHub: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# GitLab: glpat-xxxxxxxxxxxxxxxxxxxx
+# GIT_TOKEN=your_git_token_here
+
+# Git 分支（可选，默认: main）
+# GIT_BRANCH=main
+
+# Git 仓库中的文件路径（可选，默认: accounts.json）
+# GIT_FILE_PATH=accounts.json

.github/workflows/docker-publish.yml

@@ -0,0 +1,61 @@
+name: Publish Docker Image
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+env:
+  IMAGE_NAME: chatgpt2api
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=ref,event=tag
+            type=sha
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          target: app
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -0,0 +1,30 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+web_dist
+# Virtual environments
+.venv
+.idea
+data
+config.json
+edit
+
+docker-compose-local.yml
+
+.claude/settings.local.json
+
+# Environment variables
+.env
+.env.local
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Git cache
+git_cache/

.python-version

@@ -0,0 +1 @@
+3.13

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+## 1.2.3 - 2026-05-29
+
++ [新增] 新增账号级代理。
++ [修复] 修复503异常信息、前端邮箱换行问题。
+
+## 1.2.2 - 2026-05-29
+
++ [新增] 新增Codex链路生图、支持2k,4k。
++ [新增] 支持RT刷新账号信息。
+
+## 1.2.0 - 2026-05-28
+
++ [新增] 当前版本基线，包含 Web 面板、画图、号池管理、注册机、图片管理、日志管理和设置能力。
++ [新增] 前端版本号支持点击查看版本更新弹窗，展示当前版本、最新版本和更新日志。
++ [优化] 优化注册机效率，成功率大幅提高。
++ [优化] 优化生图页面配置选项。

Dockerfile

@@ -0,0 +1,56 @@
+ARG BUILDPLATFORM
+ARG TARGETPLATFORM
+ARG TARGETARCH
+
+FROM --platform=$BUILDPLATFORM node:22-alpine AS web-build
+
+WORKDIR /app/web
+
+COPY web/package.json web/bun.lock ./
+RUN npm install
+
+COPY VERSION /app/VERSION
+COPY CHANGELOG.md /app/CHANGELOG.md
+COPY web ./
+RUN NEXT_PUBLIC_APP_VERSION="$(cat /app/VERSION)" npm run build
+
+
+FROM --platform=$TARGETPLATFORM python:3.13-slim AS app
+
+ARG TARGETPLATFORM
+ARG TARGETARCH
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+# 安装系统依赖
+# - git: Git 存储后端需要
+# - libpq-dev: PostgreSQL 客户端库
+# - gcc: 编译 psycopg2-binary 需要
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    libpq-dev \
+    gcc \
+    openssl \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir uv
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY main.py ./
+COPY config.json ./
+COPY VERSION ./
+COPY api ./api
+COPY services ./services
+COPY utils ./utils
+COPY scripts ./scripts
+COPY --from=web-build /app/web/out ./web_dist
+
+EXPOSE 80
+
+CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80", "--access-log"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kunkun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,336 @@
+<h1 align="center">ChatGPT2API</h1>
+
+
+<p align="center">ChatGPT2API 主要是对 ChatGPT 官网相关能力进行逆向整理与封装，提供面向 ChatGPT 图片生成、图片编辑、多图组图编辑场景的 OpenAI 兼容图片 API / 代理，并集成在线画图、号池管理、多种账号导入方式与 Docker 自托管部署能力。</p>
+
+> [!WARNING]
+> 免责声明：
+>
+> 本项目涉及对 ChatGPT 官网文本生成、图片生成与图片编辑等相关接口的逆向研究，仅供个人学习、技术研究与非商业性技术交流使用。
+>
+> - 严禁将本项目用于任何商业用途、盈利性使用、批量操作、自动化滥用或规模化调用。
+> - 严禁将本项目用于破坏市场秩序、恶意竞争、套利倒卖、二次售卖相关服务，以及任何违反 OpenAI 服务条款或当地法律法规的行为。
+> - 严禁将本项目用于生成、传播或协助生成违法、暴力、色情、未成年人相关内容，或用于诈骗、欺诈、骚扰等非法或不当用途。
+> - 使用者应自行承担全部风险，包括但不限于账号被限制、临时封禁或永久封禁以及因违规使用等所导致的法律责任。
+> - 使用本项目即视为你已充分理解并同意本免责声明全部内容；如因滥用、违规或违法使用造成任何后果，均由使用者自行承担。
+> - 本项目基于对 ChatGPT 官网相关能力的逆向研究实现，存在账号受限、临时封禁或永久封禁的风险。请勿使用你自己的重要账号、常用账号或高价值账号进行测试。
+
+## 快速开始
+
+已发布镜像支持 `linux/amd64` 与 `linux/arm64`，在 x86 服务器和 Apple Silicon / ARM Linux 设备上都会自动拉取匹配架构的版本。
+
+### Docker 运行
+
+```bash
+git clone git@github.com:basketikun/chatgpt2api.git
+cd chatgpt2api
+docker compose up -d
+```
+
+启动前请先在 `config.json` 中设置 `auth-key`，也可以在 `docker-compose.yml` 中通过 `CHATGPT2API_AUTH_KEY` 覆盖。
+
+- Web 面板：`http://localhost:3000`
+- API 地址：`http://localhost:3000/v1`
+- 数据目录：`./data`
+
+### 本地开发
+
+启动后端：
+
+```bash
+git clone git@github.com:basketikun/chatgpt2api.git
+cd chatgpt2api
+uv sync
+uv run main.py
+```
+
+启动前端：
+
+```bash
+cd chatgpt2api/web
+bun install
+bun run dev
+```
+
+后续更新新版本：
+
+```bash
+docker pull ghcr.io/basketikun/chatgpt2api:latest
+docker-compose down
+docker-compose up -d
+
+```
+
+### 存储后端配置
+
+支持通过环境变量 `STORAGE_BACKEND` 切换存储方式：
+
+- `json` - 本地 JSON 文件（默认）
+- `sqlite` - 本地 SQLite 数据库
+- `postgres` - 外部 PostgreSQL（需配置 `DATABASE_URL`）
+- `git` - Git 私有仓库（需配置 `GIT_REPO_URL` 和 `GIT_TOKEN`）
+
+示例：使用 PostgreSQL
+
+```yaml
+environment:
+  - STORAGE_BACKEND=postgres
+  - DATABASE_URL=postgresql://user:password@host:5432/dbname
+```
+
+## 功能
+
+### API 兼容能力
+
+- 兼容 `POST /v1/images/generations` 图片生成接口
+- 兼容 `POST /v1/images/edits` 图片编辑接口
+- 兼容面向图片场景的 `POST /v1/chat/completions`
+- 兼容面向图片场景的 `POST /v1/responses`
+- `GET /v1/models` 返回 `gpt-image-2`、`codex-gpt-image-2`、`auto`、`gpt-5`、`gpt-5-1`、`gpt-5-2`、`gpt-5-3`、`gpt-5-3-mini`、
+  `gpt-5-mini`
+- 支持通过 `n` 返回多张生成结果
+- 支持 Codex 中的画图接口逆向，仅 `Plus` / `Team` / `Pro` 订阅可用，模型别名为 `codex-gpt-image-2`，如有需要可自行在其他场景映射回
+  `gpt-image-2`，用于和官网画图区分；也就意味着同一账号会同时有官网和 Codex 两份生图额度
+
+### 在线画图功能
+
+- 内置在线画图工作台，支持生成、图片编辑与多图组图编辑
+- 支持 `gpt-image-2`、`codex-gpt-image-2`、`auto`、`gpt-5`、`gpt-5-1`、`gpt-5-2`、`gpt-5-3`、`gpt-5-3-mini`、`gpt-5-mini` 模型选择
+- 编辑模式支持参考图上传
+- 前端支持多图生成交互
+- 本地保存图片会话历史，支持回看、删除和清空
+- 支持服务端缓存图片URL
+
+### 号池管理功能
+
+- 自动刷新账号邮箱、类型、额度和恢复时间
+- 轮询可用账号执行图片生成与图片编辑
+- 遇到 Token 失效类错误时自动剔除无效 Token
+- 定时检查限流账号并自动刷新
+- 支持网页端配置全局 HTTP / HTTPS / SOCKS5 / SOCKS5H 代理
+- 支持搜索、筛选、批量刷新、导出、手动编辑和清理账号
+- 支持四种导入方式：本地 CPA JSON 文件导入、远程 CPA 服务器导入、`sub2api` 服务器导入、`access_token` 导入
+- 支持在设置页配置 `sub2api` 服务器，筛选并批量导入其中的 OpenAI OAuth 账号
+
+### 实验性 / 规划中
+
+- `/v1/complete` 文本补全与流式输出已实现，但仍在测试，目前会出现对话重复的问题，请谨慎测试使用
+- `/v1/chat/completions` 文本链路支持短 TTL 缓存、重复请求合并与相邻重复消息清理，可通过 `chat_completion_cache` 配置调整
+- 详细状态说明见：[功能清单](./docs/feature-status.en.md)
+
+## 效果展示
+
+<table width="100%">
+  <tr>
+    <td width="50%"><img src="https://i.ibb.co/Jj8nfwwP/image.png" alt="image" border="0"></td>
+    <td width="50%"><img src="https://i.ibb.co/pqf235v/image-edit.png" alt="image edit" border="0"></td>
+  </tr>
+  <tr>
+    <td width="50%"><img src="https://i.ibb.co/tPcqtVfd/chery-studio.png" alt="chery studio" border="0"></td>
+    <td width="50%"><img src="https://i.ibb.co/PsT9YHBV/account-pool.png" alt="account pool" border="0"></td>
+  </tr>
+  <tr>
+    <td width="50%"><img src="https://i.ibb.co/rRWLG08q/new-api.png" alt="new api" border="0"></td>
+  </tr>
+</table>
+
+## API
+
+所有 AI 接口都需要请求头：
+
+```http
+Authorization: Bearer <auth-key>
+```
+
+<details>
+<summary><code>GET /v1/models</code></summary>
+<br>
+
+返回当前暴露的图片模型列表。
+
+```bash
+curl http://localhost:8000/v1/models \
+  -H "Authorization: Bearer <auth-key>"
+```
+
+<details>
+<summary>说明</summary>
+<br>
+
+| 字段   | 说明                                                                                                         |
+|:-----|:-----------------------------------------------------------------------------------------------------------|
+| 返回模型 | `gpt-image-2`、`codex-gpt-image-2`、`auto`、`gpt-5`、`gpt-5-1`、`gpt-5-2`、`gpt-5-3`、`gpt-5-3-mini`、`gpt-5-mini` |
+| 接入场景 | 可接入 Cherry Studio、New API 等上游或客户端                                                                          |
+
+<br>
+</details>
+</details>
+
+<details>
+<summary><code>POST /v1/images/generations</code></summary>
+<br>
+
+OpenAI 兼容图片生成接口，用于文生图。
+
+```bash
+curl http://localhost:8000/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <auth-key>" \
+  -d '{
+    "model": "gpt-image-2",
+    "prompt": "一只漂浮在太空里的猫",
+    "n": 1,
+    "response_format": "b64_json"
+  }'
+```
+
+<details>
+<summary>字段说明</summary>
+<br>
+
+| 字段                | 说明                                                 |
+|:------------------|:---------------------------------------------------|
+| `model`           | 图片模型，当前可用值以 `/v1/models` 返回结果为准，推荐使用 `gpt-image-2` |
+| `prompt`          | 图片生成提示词                                            |
+| `n`               | 生成数量，当前后端限制为 `1-4`                                 |
+| `response_format` | 当前请求模型中包含该字段，默认值为 `b64_json`                       |
+
+<br>
+</details>
+</details>
+
+<details>
+<summary><code>POST /v1/images/edits</code></summary>
+<br>
+
+OpenAI 兼容图片编辑接口，可上传图片文件，也可按官方 JSON 格式传入图片链接并生成编辑结果。
+
+```bash
+curl http://localhost:8000/v1/images/edits \
+  -H "Authorization: Bearer <auth-key>" \
+  -F "model=gpt-image-2" \
+  -F "prompt=把这张图改成赛博朋克夜景风格" \
+  -F "n=1" \
+  -F "image=@./input.png"
+```
+
+也可以直接传图片 URL：
+
+```bash
+curl http://localhost:8000/v1/images/edits \
+  -H "Authorization: Bearer <auth-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-image-2",
+    "prompt": "把这张图改成赛博朋克夜景风格",
+    "images": [
+      {"image_url": "https://example.com/input.png"}
+    ]
+  }'
+```
+
+<details>
+<summary>字段说明</summary>
+<br>
+
+| 字段          | 说明                                            |
+|:------------|:----------------------------------------------|
+| `model`     | 图片模型， `gpt-image-2`                           |
+| `prompt`    | 图片编辑提示词                                       |
+| `n`         | 生成数量，当前后端限制为 `1-4`                            |
+| `image`     | 需要编辑的图片文件，使用 multipart/form-data 上传           |
+| `images`    | JSON 图片引用数组，支持 `{"image_url": "https://..."}` |
+| `image_url` | 表单模式下也可直接传图片链接，支持重复字段传多张图                     |
+
+<br>
+</details>
+</details>
+
+<details>
+<summary><code>POST /v1/chat/completions</code></summary>
+<br>
+
+面向图片场景的 Chat Completions 兼容接口，不是完整通用聊天代理。
+
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <auth-key>" \
+  -d '{
+    "model": "gpt-image-2",
+    "messages": [
+      {
+        "role": "user",
+        "content": "生成一张雨夜东京街头的赛博朋克猫"
+      }
+    ],
+    "n": 1
+  }'
+```
+
+<details>
+<summary>字段说明</summary>
+<br>
+
+| 字段         | 说明                |
+|:-----------|:------------------|
+| `model`    | 图片模型，默认按图片生成场景处理  |
+| `messages` | 消息数组，需要是图片相关请求内容  |
+| `n`        | 生成数量，按当前实现解析为图片数量 |
+| `stream`   | 已实现，但仍在测试         |
+
+<br>
+</details>
+</details>
+
+<details>
+<summary><code>POST /v1/responses</code></summary>
+<br>
+
+面向图片生成工具调用的 Responses API 兼容接口，不是完整通用 Responses API 代理。
+
+```bash
+curl http://localhost:8000/v1/responses \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <auth-key>" \
+  -d '{
+    "model": "gpt-5",
+    "input": "生成一张未来感城市天际线图片",
+    "tools": [
+      {
+        "type": "image_generation"
+      }
+    ]
+  }'
+```
+
+<details>
+<summary>字段说明</summary>
+<br>
+
+| 字段       | 说明                            |
+|:---------|:------------------------------|
+| `model`  | 响应中会回显该模型字段，但图片生成当前仍走图片生成兼容逻辑 |
+| `input`  | 输入内容，需要能解析出图片生成提示词            |
+| `tools`  | 必须包含 `image_generation` 工具请求  |
+| `stream` | 已实现，但仍在测试                     |
+
+<br>
+</details>
+</details>
+
+## 社区支持
+
+学 AI , 上 L 站：[LinuxDO](https://linux.do)
+
+## Contributors
+
+感谢所有为本项目做出贡献的开发者：
+
+<a href="https://github.com/basketikun/chatgpt2api/graphs/contributors">
+  <img alt="Contributors" src="https://contrib.rocks/image?repo=basketikun/chatgpt2api" />
+</a>
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/chart?repos=basketikun/chatgpt2api&type=date&legend=top-left)](https://www.star-history.com/?repos=basketikun%2Fchatgpt2api&type=date&legend=top-left)

VERSION

@@ -0,0 +1 @@
+1.2.3

api/__init__.py

@@ -0,0 +1,2 @@
+from api.app import create_app
+

api/accounts.py

@@ -0,0 +1,488 @@
+from __future__ import annotations
+
+import io
+import json
+import re
+import zipfile
+from datetime import datetime
+from typing import Any, Literal
+
+from fastapi import APIRouter, Header, HTTPException
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import Response
+from pydantic import BaseModel, Field
+
+from services.auth_service import auth_service
+
+from api.support import (
+    require_admin,
+    sanitize_cpa_pool,
+    sanitize_cpa_pools,
+    sanitize_sub2api_server,
+    sanitize_sub2api_servers,
+)
+from services.account_service import account_service
+from services.cpa_service import cpa_config, cpa_import_service, list_remote_files
+from services.oauth_login_service import OAuthLoginError, oauth_login_service
+from services.sub2api_service import (
+    list_remote_accounts as sub2api_list_remote_accounts,
+    list_remote_groups as sub2api_list_remote_groups,
+    sub2api_config,
+    sub2api_import_service,
+)
+
+
+
+class UserKeyCreateRequest(BaseModel):
+    name: str = ""
+
+
+class UserKeyUpdateRequest(BaseModel):
+    name: str | None = None
+    enabled: bool | None = None
+    key: str | None = None
+
+
+class AccountCreateRequest(BaseModel):
+    tokens: list[str] = Field(default_factory=list)
+    accounts: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class AccountDeleteRequest(BaseModel):
+    tokens: list[str] = Field(default_factory=list)
+
+
+class AccountRefreshRequest(BaseModel):
+    access_tokens: list[str] = Field(default_factory=list)
+
+
+class AccountExportRequest(BaseModel):
+    access_tokens: list[str] = Field(default_factory=list)
+    format: Literal["json", "zip"] = "json"
+
+
+class AccountUpdateRequest(BaseModel):
+    access_token: str = ""
+    type: str | None = None
+    status: str | None = None
+    quota: int | None = None
+    proxy: str | None = None
+
+
+class CPAPoolCreateRequest(BaseModel):
+    name: str = ""
+    base_url: str = ""
+    secret_key: str = ""
+
+
+class CPAPoolUpdateRequest(BaseModel):
+    name: str | None = None
+    base_url: str | None = None
+    secret_key: str | None = None
+
+
+class CPAImportRequest(BaseModel):
+    names: list[str] = Field(default_factory=list)
+
+
+class Sub2APIServerCreateRequest(BaseModel):
+    name: str = ""
+    base_url: str = ""
+    email: str = ""
+    password: str = ""
+    api_key: str = ""
+    group_id: str = ""
+
+
+class Sub2APIServerUpdateRequest(BaseModel):
+    name: str | None = None
+    base_url: str | None = None
+    email: str | None = None
+    password: str | None = None
+    api_key: str | None = None
+    group_id: str | None = None
+
+
+class Sub2APIImportRequest(BaseModel):
+    account_ids: list[str] = Field(default_factory=list)
+
+
+class OAuthLoginStartRequest(BaseModel):
+    """起始 OAuth 桥。email_hint 可选，仅用于让 OpenAI 登录页预填邮箱。"""
+    email_hint: str = ""
+
+
+class OAuthLoginFinishRequest(BaseModel):
+    """提交 callback。callback 既可以是完整 URL 也可以只填 code。"""
+    session_id: str = ""
+    callback: str = ""
+
+
+def _account_payload_token(item: dict[str, Any]) -> str:
+    return str(item.get("access_token") or item.get("accessToken") or "").strip()
+
+
+def _unique_tokens(tokens: list[str]) -> list[str]:
+    return list(dict.fromkeys(str(token or "").strip() for token in tokens if str(token or "").strip()))
+
+
+def _download_timestamp() -> str:
+    return datetime.now().strftime("%Y%m%d-%H%M%S")
+
+
+def _safe_export_name(value: str, fallback: str) -> str:
+    clean = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip()).strip("-._")
+    return (clean or fallback)[:80]
+
+
+def _account_zip_bytes(items: list[dict[str, str]]) -> bytes:
+    buf = io.BytesIO()
+    used_names: set[str] = set()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as archive:
+        for index, item in enumerate(items, start=1):
+            raw_name = item.get("email") or item.get("account_id") or f"account-{index:03d}"
+            base_name = _safe_export_name(raw_name, f"account-{index:03d}")
+            name = base_name
+            suffix = 2
+            while name in used_names:
+                name = f"{base_name}-{suffix}"
+                suffix += 1
+            used_names.add(name)
+            archive.writestr(
+                f"{name}.json",
+                json.dumps(item, ensure_ascii=False, indent=2) + "\n",
+            )
+    return buf.getvalue()
+
+
+def create_router() -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/api/auth/users")
+    async def list_user_keys(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"items": auth_service.list_keys(role="user")}
+
+    @router.post("/api/auth/users")
+    async def create_user_key(body: UserKeyCreateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            item, raw_key = auth_service.create_key(role="user", name=body.name)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+        return {"item": item, "key": raw_key, "items": auth_service.list_keys(role="user")}
+
+    @router.post("/api/auth/users/{key_id}")
+    async def update_user_key(
+            key_id: str,
+            body: UserKeyUpdateRequest,
+            authorization: str | None = Header(default=None),
+    ):
+        require_admin(authorization)
+        updates = {
+            key: value
+            for key, value in {
+                "name": body.name,
+                "enabled": body.enabled,
+                "key": body.key,
+            }.items()
+            if value is not None
+        }
+        if not updates:
+            raise HTTPException(status_code=400, detail={"error": "还没有检测到改动，请修改后再保存"})
+        try:
+            item = auth_service.update_key(key_id, updates, role="user")
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+        if item is None:
+            raise HTTPException(status_code=404, detail={"error": "这条用户密钥不存在，可能已经被删除"})
+        return {"item": item, "items": auth_service.list_keys(role="user")}
+
+    @router.delete("/api/auth/users/{key_id}")
+    async def delete_user_key(key_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        if not auth_service.delete_key(key_id, role="user"):
+            raise HTTPException(status_code=404, detail={"error": "这条用户密钥不存在，可能已经被删除"})
+        return {"items": auth_service.list_keys(role="user")}
+
+    @router.get("/api/accounts")
+    async def get_accounts(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"items": account_service.list_accounts()}
+
+    @router.post("/api/accounts")
+    async def create_accounts(body: AccountCreateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        account_payloads = [item for item in body.accounts if isinstance(item, dict)]
+        payload_tokens = [_account_payload_token(item) for item in account_payloads]
+        tokens = _unique_tokens([*body.tokens, *payload_tokens])
+        if not tokens:
+            raise HTTPException(status_code=400, detail={"error": "tokens is required"})
+        if account_payloads:
+            result = account_service.add_account_items(account_payloads)
+            payload_token_set = set(_unique_tokens(payload_tokens))
+            extra_tokens = [token for token in tokens if token not in payload_token_set]
+            if extra_tokens:
+                extra_result = account_service.add_accounts(extra_tokens)
+                result["added"] = int(result.get("added") or 0) + int(extra_result.get("added") or 0)
+                result["skipped"] = int(result.get("skipped") or 0) + int(extra_result.get("skipped") or 0)
+        else:
+            result = account_service.add_accounts(tokens)
+        refresh_result = account_service.refresh_accounts(tokens)
+        return {
+            **result,
+            "refreshed": refresh_result.get("refreshed", 0),
+            "errors": refresh_result.get("errors", []),
+            "items": refresh_result.get("items", result.get("items", [])),
+        }
+
+    @router.delete("/api/accounts")
+    async def delete_accounts(body: AccountDeleteRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        tokens = [str(token or "").strip() for token in body.tokens if str(token or "").strip()]
+        if not tokens:
+            raise HTTPException(status_code=400, detail={"error": "tokens is required"})
+        return account_service.delete_accounts(tokens)
+
+    @router.post("/api/accounts/refresh")
+    async def refresh_accounts(body: AccountRefreshRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        access_tokens = [str(token or "").strip() for token in body.access_tokens if str(token or "").strip()]
+        if not access_tokens:
+            access_tokens = account_service.list_tokens()
+        if not access_tokens:
+            raise HTTPException(status_code=400, detail={"error": "access_tokens is required"})
+        return account_service.refresh_accounts(access_tokens)
+
+    @router.post("/api/accounts/export")
+    async def export_accounts(body: AccountExportRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        access_tokens = _unique_tokens(body.access_tokens)
+        items = account_service.build_export_items(access_tokens)
+        if not items:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": "没有可导出的完整账号，需要同时有 access_token、refresh_token 和 id_token"},
+            )
+
+        timestamp = _download_timestamp()
+        if body.format == "zip":
+            content = _account_zip_bytes(items)
+            return Response(
+                content,
+                media_type="application/zip",
+                headers={"Content-Disposition": f'attachment; filename="codex-accounts-{timestamp}.zip"'},
+            )
+
+        payload: dict[str, str] | list[dict[str, str]] = items[0] if len(items) == 1 else items
+        return Response(
+            json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+            media_type="application/json",
+            headers={"Content-Disposition": f'attachment; filename="codex-accounts-{timestamp}.json"'},
+        )
+
+    @router.post("/api/accounts/update")
+    async def update_account(body: AccountUpdateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        access_token = str(body.access_token or "").strip()
+        if not access_token:
+            raise HTTPException(status_code=400, detail={"error": "access_token is required"})
+        updates = {key: value for key, value in {"type": body.type, "status": body.status, "quota": body.quota, "proxy": body.proxy}.items() if value is not None}
+        if not updates:
+            raise HTTPException(status_code=400, detail={"error": "还没有检测到改动，请修改后再保存"})
+        account = account_service.update_account(access_token, updates)
+        if account is None:
+            raise HTTPException(status_code=404, detail={"error": "account not found"})
+        return {"item": account, "items": account_service.list_accounts()}
+
+    @router.post("/api/accounts/oauth/start")
+    async def start_oauth_login(
+            body: OAuthLoginStartRequest,
+            authorization: str | None = Header(default=None),
+    ):
+        """登记一次 PKCE 会话，返回可让用户浏览器打开的 authorize URL。"""
+        require_admin(authorization)
+        try:
+            return await run_in_threadpool(oauth_login_service.start, body.email_hint)
+        except OAuthLoginError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.post("/api/accounts/oauth/finish")
+    async def finish_oauth_login(
+            body: OAuthLoginFinishRequest,
+            authorization: str | None = Header(default=None),
+    ):
+        """收用户从浏览器抓回的 callback URL / code，换出 token 三件套并落盘。"""
+        require_admin(authorization)
+        # 入参日志：截断敏感字段，仅保留前几位，方便排错而不泄密
+        cb_preview = (body.callback or "")[:80]
+        sid_preview = (body.session_id or "")[:8]
+        print(
+            f"[oauth-login] finish called: session_id={sid_preview}..., callback_preview={cb_preview!r}",
+            flush=True,
+        )
+        try:
+            tokens = await run_in_threadpool(oauth_login_service.finish, body.session_id, body.callback)
+        except OAuthLoginError as exc:
+            print(f"[oauth-login] finish rejected: {exc}", flush=True)
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+        payload = {
+            "access_token": tokens["access_token"],
+            "refresh_token": tokens["refresh_token"],
+            "id_token": tokens["id_token"],
+            "source_type": "oauth_login",
+        }
+        add_result = await run_in_threadpool(account_service.add_account_items, [payload])
+        refresh_result = await run_in_threadpool(
+            account_service.refresh_accounts, [tokens["access_token"]]
+        )
+        return {
+            **add_result,
+            "refreshed": refresh_result.get("refreshed", 0),
+            "errors": refresh_result.get("errors", []),
+            "items": refresh_result.get("items", add_result.get("items", [])),
+        }
+
+    @router.get("/api/cpa/pools")
+    async def list_cpa_pools(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"pools": sanitize_cpa_pools(cpa_config.list_pools())}
+
+    @router.post("/api/cpa/pools")
+    async def create_cpa_pool(body: CPAPoolCreateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        if not body.base_url.strip():
+            raise HTTPException(status_code=400, detail={"error": "base_url is required"})
+        if not body.secret_key.strip():
+            raise HTTPException(status_code=400, detail={"error": "secret_key is required"})
+        pool = cpa_config.add_pool(name=body.name, base_url=body.base_url, secret_key=body.secret_key)
+        return {"pool": sanitize_cpa_pool(pool), "pools": sanitize_cpa_pools(cpa_config.list_pools())}
+
+    @router.post("/api/cpa/pools/{pool_id}")
+    async def update_cpa_pool(pool_id: str, body: CPAPoolUpdateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        pool = cpa_config.update_pool(pool_id, body.model_dump(exclude_none=True))
+        if pool is None:
+            raise HTTPException(status_code=404, detail={"error": "pool not found"})
+        return {"pool": sanitize_cpa_pool(pool), "pools": sanitize_cpa_pools(cpa_config.list_pools())}
+
+    @router.delete("/api/cpa/pools/{pool_id}")
+    async def delete_cpa_pool(pool_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        if not cpa_config.delete_pool(pool_id):
+            raise HTTPException(status_code=404, detail={"error": "pool not found"})
+        return {"pools": sanitize_cpa_pools(cpa_config.list_pools())}
+
+    @router.get("/api/cpa/pools/{pool_id}/files")
+    async def cpa_pool_files(pool_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        pool = cpa_config.get_pool(pool_id)
+        if pool is None:
+            raise HTTPException(status_code=404, detail={"error": "pool not found"})
+        return {"pool_id": pool_id, "files": await run_in_threadpool(list_remote_files, pool)}
+
+    @router.post("/api/cpa/pools/{pool_id}/import")
+    async def cpa_pool_import(pool_id: str, body: CPAImportRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        pool = cpa_config.get_pool(pool_id)
+        if pool is None:
+            raise HTTPException(status_code=404, detail={"error": "pool not found"})
+        try:
+            job = cpa_import_service.start_import(pool, body.names)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+        return {"import_job": job}
+
+    @router.get("/api/cpa/pools/{pool_id}/import")
+    async def cpa_pool_import_progress(pool_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        pool = cpa_config.get_pool(pool_id)
+        if pool is None:
+            raise HTTPException(status_code=404, detail={"error": "pool not found"})
+        return {"import_job": pool.get("import_job")}
+
+    @router.get("/api/sub2api/servers")
+    async def list_sub2api_servers(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"servers": sanitize_sub2api_servers(sub2api_config.list_servers())}
+
+    @router.post("/api/sub2api/servers")
+    async def create_sub2api_server(body: Sub2APIServerCreateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        if not body.base_url.strip():
+            raise HTTPException(status_code=400, detail={"error": "base_url is required"})
+        has_login = body.email.strip() and body.password.strip()
+        has_api_key = bool(body.api_key.strip())
+        if not has_login and not has_api_key:
+            raise HTTPException(status_code=400, detail={"error": "email+password or api_key is required"})
+        server = sub2api_config.add_server(
+            name=body.name,
+            base_url=body.base_url,
+            email=body.email,
+            password=body.password,
+            api_key=body.api_key,
+            group_id=body.group_id,
+        )
+        return {"server": sanitize_sub2api_server(server), "servers": sanitize_sub2api_servers(sub2api_config.list_servers())}
+
+    @router.post("/api/sub2api/servers/{server_id}")
+    async def update_sub2api_server(server_id: str, body: Sub2APIServerUpdateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        server = sub2api_config.update_server(server_id, body.model_dump(exclude_none=True))
+        if server is None:
+            raise HTTPException(status_code=404, detail={"error": "server not found"})
+        return {"server": sanitize_sub2api_server(server), "servers": sanitize_sub2api_servers(sub2api_config.list_servers())}
+
+    @router.delete("/api/sub2api/servers/{server_id}")
+    async def delete_sub2api_server(server_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        if not sub2api_config.delete_server(server_id):
+            raise HTTPException(status_code=404, detail={"error": "server not found"})
+        return {"servers": sanitize_sub2api_servers(sub2api_config.list_servers())}
+
+    @router.get("/api/sub2api/servers/{server_id}/groups")
+    async def sub2api_server_groups(server_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        server = sub2api_config.get_server(server_id)
+        if server is None:
+            raise HTTPException(status_code=404, detail={"error": "server not found"})
+        try:
+            groups = await run_in_threadpool(sub2api_list_remote_groups, server)
+        except Exception as exc:
+            raise HTTPException(status_code=502, detail={"error": str(exc)}) from exc
+        return {"server_id": server_id, "groups": groups}
+
+    @router.get("/api/sub2api/servers/{server_id}/accounts")
+    async def sub2api_server_accounts(server_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        server = sub2api_config.get_server(server_id)
+        if server is None:
+            raise HTTPException(status_code=404, detail={"error": "server not found"})
+        try:
+            accounts = await run_in_threadpool(sub2api_list_remote_accounts, server)
+        except Exception as exc:
+            raise HTTPException(status_code=502, detail={"error": str(exc)}) from exc
+        return {"server_id": server_id, "accounts": accounts}
+
+    @router.post("/api/sub2api/servers/{server_id}/import")
+    async def sub2api_server_import(server_id: str, body: Sub2APIImportRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        server = sub2api_config.get_server(server_id)
+        if server is None:
+            raise HTTPException(status_code=404, detail={"error": "server not found"})
+        try:
+            job = sub2api_import_service.start_import(server, body.account_ids)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+        return {"import_job": job}
+
+    @router.get("/api/sub2api/servers/{server_id}/import")
+    async def sub2api_server_import_progress(server_id: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        server = sub2api_config.get_server(server_id)
+        if server is None:
+            raise HTTPException(status_code=404, detail={"error": "server not found"})
+        return {"import_job": server.get("import_job")}
+
+    return router

api/ai.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel, ConfigDict, Field
+
+from api.image_inputs import parse_image_edit_request, read_image_sources
+from api.support import require_identity, resolve_image_base_url
+from services.content_filter import check_request, request_text
+from services.log_service import LoggedCall
+from services.protocol import (
+    anthropic_v1_messages,
+    openai_v1_chat_complete,
+    openai_v1_image_edit,
+    openai_v1_image_generations,
+    openai_v1_models,
+    openai_v1_response,
+)
+
+
+class ImageGenerationRequest(BaseModel):
+    prompt: str = Field(..., min_length=1)
+    model: str = "gpt-image-2"
+    n: int = Field(default=1, ge=1, le=4)
+    size: str | None = None
+    quality: str = "auto"
+    response_format: str = "b64_json"
+    history_disabled: bool = True
+    stream: bool | None = None
+
+
+class ChatCompletionRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    model: str | None = None
+    prompt: str | None = None
+    n: int | None = None
+    stream: bool | None = None
+    modalities: list[str] | None = None
+    messages: list[dict[str, object]] | None = None
+
+
+class ResponseCreateRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    model: str | None = None
+    input: object | None = None
+    tools: list[dict[str, object]] | None = None
+    tool_choice: object | None = None
+    stream: bool | None = None
+
+
+class AnthropicMessageRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    model: str | None = None
+    messages: list[dict[str, object]] | None = None
+    system: object | None = None
+    stream: bool | None = None
+
+
+async def filter_or_log(call: LoggedCall, text: str) -> None:
+    try:
+        await run_in_threadpool(check_request, text)
+    except HTTPException as exc:
+        call.log("调用失败", status="failed", error=str(exc.detail))
+        raise
+
+
+def create_router() -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/v1/models")
+    async def list_models(authorization: str | None = Header(default=None)):
+        require_identity(authorization)
+        try:
+            return await run_in_threadpool(openai_v1_models.list_models)
+        except Exception as exc:
+            raise HTTPException(status_code=502, detail={"error": str(exc)}) from exc
+
+    @router.post("/v1/images/generations")
+    async def generate_images(
+            body: ImageGenerationRequest,
+            request: Request,
+            authorization: str | None = Header(default=None),
+    ):
+        identity = require_identity(authorization)
+        payload = body.model_dump(mode="python")
+        payload["base_url"] = resolve_image_base_url(request)
+        call = LoggedCall(identity, "/v1/images/generations", body.model, "文生图", request_text=body.prompt)
+        await filter_or_log(call, body.prompt)
+        return await call.run(openai_v1_image_generations.handle, payload)
+
+    @router.post("/v1/images/edits")
+    async def edit_images(
+            request: Request,
+            authorization: str | None = Header(default=None),
+    ):
+        identity = require_identity(authorization)
+        payload, image_sources = await parse_image_edit_request(request)
+        prompt = str(payload["prompt"])
+        model = str(payload["model"])
+        call = LoggedCall(identity, "/v1/images/edits", model, "图生图", request_text=prompt)
+        await filter_or_log(call, prompt)
+        payload["images"] = await read_image_sources(image_sources)
+        payload["base_url"] = resolve_image_base_url(request)
+        return await call.run(openai_v1_image_edit.handle, payload)
+
+    @router.post("/v1/chat/completions")
+    async def create_chat_completion(body: ChatCompletionRequest, authorization: str | None = Header(default=None)):
+        identity = require_identity(authorization)
+        payload = body.model_dump(mode="python")
+        model = str(payload.get("model") or "auto")
+        request_preview = request_text(payload.get("prompt"), payload.get("messages"))
+        call = LoggedCall(identity, "/v1/chat/completions", model, "文本生成", request_text=request_preview)
+        await filter_or_log(call, request_preview)
+        return await call.run(openai_v1_chat_complete.handle, payload)
+
+    @router.post("/v1/responses")
+    async def create_response(body: ResponseCreateRequest, authorization: str | None = Header(default=None)):
+        identity = require_identity(authorization)
+        payload = body.model_dump(mode="python")
+        model = str(payload.get("model") or "auto")
+        request_preview = request_text(payload.get("input"), payload.get("instructions"))
+        call = LoggedCall(identity, "/v1/responses", model, "Responses", request_text=request_preview)
+        await filter_or_log(call, request_preview)
+        return await call.run(openai_v1_response.handle, payload)
+
+    @router.post("/v1/messages")
+    async def create_message(
+            body: AnthropicMessageRequest,
+            authorization: str | None = Header(default=None),
+            x_api_key: str | None = Header(default=None, alias="x-api-key"),
+            anthropic_version: str | None = Header(default=None, alias="anthropic-version"),
+    ):
+        identity = require_identity(authorization or (f"Bearer {x_api_key}" if x_api_key else None))
+        payload = body.model_dump(mode="python")
+        model = str(payload.get("model") or "auto")
+        request_preview = request_text(payload.get("system"), payload.get("messages"), payload.get("tools"))
+        call = LoggedCall(identity, "/v1/messages", model, "Messages", request_text=request_preview)
+        await filter_or_log(call, request_preview)
+        return await call.run(anthropic_v1_messages.handle, payload, sse="anthropic")
+
+    return router

api/app.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from threading import Event
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+
+from api import accounts, ai, image_tasks, register, system
+from api.errors import install_exception_handlers
+from api.support import resolve_web_asset, start_limited_account_watcher
+from services.backup_service import backup_service
+from services.config import config
+from services.image_service import start_image_cleanup_scheduler
+
+
+def create_app() -> FastAPI:
+    app_version = config.app_version
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        stop_event = Event()
+        thread = start_limited_account_watcher(stop_event)
+        cleanup_thread = start_image_cleanup_scheduler(stop_event)
+        backup_service.start()
+        config.cleanup_old_images()
+        try:
+            yield
+        finally:
+            stop_event.set()
+            thread.join(timeout=1)
+            cleanup_thread.join(timeout=1)
+            backup_service.stop()
+
+    app = FastAPI(title="chatgpt2api", version=app_version, lifespan=lifespan)
+    install_exception_handlers(app)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.include_router(ai.create_router())
+    app.include_router(accounts.create_router())
+    app.include_router(image_tasks.create_router())
+    app.include_router(register.create_router())
+    app.include_router(system.create_router(app_version))
+
+    @app.get("/{full_path:path}", include_in_schema=False)
+    async def serve_web(full_path: str):
+        asset = resolve_web_asset(full_path)
+        if asset is not None:
+            return FileResponse(asset)
+        if full_path.strip("/").startswith("_next/"):
+            raise HTTPException(status_code=404, detail="Not Found")
+        fallback = resolve_web_asset("")
+        if fallback is None:
+            raise HTTPException(status_code=404, detail="Not Found")
+        return FileResponse(fallback)
+
+    return app

api/errors.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from services.protocol.error_response import anthropic_error_response, openai_error_response
+
+
+def _is_openai_compatible_path(path: str) -> bool:
+    return path == "/v1" or path.startswith("/v1/")
+
+
+def _is_anthropic_messages_path(path: str) -> bool:
+    return path == "/v1/messages"
+
+
+def _compatible_error_response(
+    request: Request,
+    detail: object,
+    status_code: int,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    if _is_anthropic_messages_path(request.url.path):
+        return anthropic_error_response(detail, status_code, headers=headers)
+    return openai_error_response(detail, status_code, headers=headers)
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(StarletteHTTPException)
+    async def http_exception_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+        if _is_openai_compatible_path(request.url.path):
+            return _compatible_error_response(request, exc.detail, exc.status_code, exc.headers)
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"detail": jsonable_encoder(exc.detail)},
+            headers=exc.headers,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+        if _is_openai_compatible_path(request.url.path):
+            return _compatible_error_response(request, exc.errors(), 422)
+        return JSONResponse(status_code=422, content={"detail": jsonable_encoder(exc.errors())})

api/image_inputs.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import mimetypes
+import re
+from pathlib import PurePosixPath
+from typing import Any, TypeGuard
+from urllib.parse import unquote, unquote_to_bytes, urlparse
+
+from curl_cffi import requests
+from fastapi import HTTPException, Request
+from fastapi.concurrency import run_in_threadpool
+from starlette.datastructures import UploadFile
+
+from services.proxy_service import proxy_settings
+
+ImageInput = tuple[bytes, str, str]
+ImageSource = str | UploadFile | ImageInput
+
+MAX_IMAGE_REFERENCE_BYTES = 50 * 1024 * 1024
+IMAGE_REFERENCE_FIELDS = {"image", "image[]", "images", "images[]", "image_url", "image_url[]"}
+
+
+def _clean(value: object, default: str = "") -> str:
+    """清理字符串：转换为字符串并去掉首尾空白。"""
+    text = str(value if value is not None else default).strip()
+    return text or default
+
+
+def _is_upload(value: object) -> TypeGuard[UploadFile]:
+    """识别上传文件：兼容 Starlette 表单返回的 UploadFile。"""
+    return isinstance(value, UploadFile)
+
+
+def _parse_bool(value: object) -> bool | None:
+    """解析布尔字段：兼容 JSON 布尔值和表单字符串。"""
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        return value
+    text = _clean(value).lower()
+    if text in {"true", "1", "yes", "y", "on"}:
+        return True
+    if text in {"false", "0", "no", "n", "off"}:
+        return False
+    raise HTTPException(status_code=400, detail={"error": "stream must be a boolean"})
+
+
+def _parse_count(value: object) -> int:
+    """解析生成数量：保持图片接口的 1 到 4 限制。"""
+    try:
+        count = int(value or 1)
+    except (TypeError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": "n must be an integer"}) from exc
+    if count < 1 or count > 4:
+        raise HTTPException(status_code=400, detail={"error": "n must be between 1 and 4"})
+    return count
+
+
+def _payload_from_fields(fields: dict[str, Any]) -> dict[str, Any]:
+    """构造图片编辑载荷：从表单或 JSON 字段提取通用参数。"""
+    prompt = _clean(fields.get("prompt"))
+    if not prompt:
+        raise HTTPException(status_code=400, detail={"error": "prompt is required"})
+    payload = {
+        "prompt": prompt,
+        "model": _clean(fields.get("model"), "gpt-image-2"),
+        "n": _parse_count(fields.get("n")),
+        "size": _clean(fields.get("size")) or None,
+        "quality": _clean(fields.get("quality"), "auto"),
+        "response_format": _clean(fields.get("response_format"), "b64_json"),
+        "stream": _parse_bool(fields.get("stream")),
+    }
+    if "client_task_id" in fields:
+        payload["client_task_id"] = _clean(fields.get("client_task_id"))
+    return payload
+
+
+def _json_reference_value(value: object) -> object:
+    """解析表单图片引用：支持把 images 字段写成 JSON 字符串。"""
+    if not isinstance(value, str):
+        return value
+    text = value.strip()
+    if not text or text[0] not in "[{":
+        return value
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return value
+
+
+def _decode_base64_image(value: object, filename: str, mime_type: str) -> ImageInput:
+    try:
+        data = base64.b64decode(str(value).strip(), validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": "invalid base64 image data"}) from exc
+    if not data:
+        raise HTTPException(status_code=400, detail={"error": "image file is empty"})
+    if len(data) > MAX_IMAGE_REFERENCE_BYTES:
+        raise HTTPException(status_code=400, detail={"error": "image URL exceeds 50MB limit"})
+    return data, filename, mime_type
+
+
+def _source_from_object(value: dict[str, Any]) -> list[ImageSource]:
+    """提取图片引用对象：支持 image_url 或 url，明确拒绝 file_id。"""
+    has_url = "image_url" in value or "url" in value
+    if value.get("file_id"):
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "file_id image references are not supported; use image_url instead"},
+        )
+    inline = value.get("b64_json") or value.get("base64")
+    if inline:
+        filename = _clean(value.get("filename") or value.get("file_name"), "image.png")
+        mime_type = _clean(value.get("mime_type") or value.get("mimeType"), "image/png")
+        return [_decode_base64_image(inline, filename, mime_type)]
+    if not has_url:
+        raise HTTPException(status_code=400, detail={"error": "image reference must include image_url"})
+    image_url = value.get("image_url", value.get("url"))
+    if isinstance(image_url, dict):
+        image_url = image_url.get("url")
+    return _sources_from_value(image_url)
+
+
+def _sources_from_value(value: object) -> list[ImageSource]:
+    """展开图片引用：把字符串、数组和对象统一成图片来源列表。"""
+    value = _json_reference_value(value)
+    if _is_upload(value):
+        return [value]
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return []
+        if text.lower().startswith(("data:", "http://", "https://")):
+            return [text]
+        return [_decode_base64_image(text, "image.png", "image/png")]
+    if isinstance(value, list):
+        sources: list[ImageSource] = []
+        for item in value:
+            sources.extend(_sources_from_value(item))
+        return sources
+    if isinstance(value, dict):
+        return _source_from_object(value)
+    if value is None:
+        return []
+    raise HTTPException(status_code=400, detail={"error": "invalid image reference"})
+
+
+def _json_image_sources(body: dict[str, Any]) -> list[ImageSource]:
+    """读取 JSON 图片引用：优先支持官方 images 数组字段。"""
+    sources: list[ImageSource] = []
+    for key in ("images", "image", "image_url"):
+        if key in body:
+            sources.extend(_sources_from_value(body.get(key)))
+    return sources
+
+
+async def parse_image_edit_request(request: Request) -> tuple[dict[str, Any], list[ImageSource]]:
+    """解析图片编辑请求：同时支持 multipart 上传和官方 JSON 图片 URL。"""
+    content_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
+    if content_type == "application/json":
+        try:
+            body = await request.json()
+        except json.JSONDecodeError as exc:
+            raise HTTPException(status_code=400, detail={"error": "invalid JSON body"}) from exc
+        if not isinstance(body, dict):
+            raise HTTPException(status_code=400, detail={"error": "JSON body must be an object"})
+        return _payload_from_fields(body), _json_image_sources(body)
+
+    form = await request.form()
+    fields: dict[str, Any] = {}
+    for key in ("client_task_id", "prompt", "model", "n", "size", "quality", "response_format", "stream"):
+        value = form.get(key)
+        if isinstance(value, str):
+            fields[key] = value
+    sources: list[ImageSource] = []
+    for key, value in form.multi_items():
+        if key in IMAGE_REFERENCE_FIELDS:
+            sources.extend(_sources_from_value(value))
+    return _payload_from_fields(fields), sources
+
+
+def _extension_from_mime(mime_type: str) -> str:
+    """推导图片扩展名：把 MIME 类型转换为常见文件后缀。"""
+    subtype = mime_type.split("/", 1)[1].split("+", 1)[0] if "/" in mime_type else "png"
+    if subtype == "jpeg":
+        return "jpg"
+    return re.sub(r"[^a-z0-9]+", "", subtype.lower()) or "png"
+
+
+def _safe_filename(name: str, mime_type: str, fallback: str) -> str:
+    """生成安全文件名：清理 URL 文件名并补齐扩展名。"""
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("._")
+    if not cleaned:
+        cleaned = fallback
+    if "." not in cleaned:
+        cleaned = f"{cleaned}.{_extension_from_mime(mime_type)}"
+    return cleaned
+
+
+def _decode_data_url(url: str) -> ImageInput:
+    """解码 data URL：把内联图片转成标准图片输入元组。"""
+    header, separator, payload = url.partition(",")
+    if not separator:
+        raise HTTPException(status_code=400, detail={"error": "invalid data image URL"})
+    mime_type = header.split(";", 1)[0].removeprefix("data:") or "image/png"
+    if not mime_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail={"error": "image_url must point to an image"})
+    try:
+        data = base64.b64decode(payload, validate=True) if ";base64" in header else unquote_to_bytes(payload)
+    except (binascii.Error, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": "invalid data image URL"}) from exc
+    if not data:
+        raise HTTPException(status_code=400, detail={"error": "image URL is empty"})
+    if len(data) > MAX_IMAGE_REFERENCE_BYTES:
+        raise HTTPException(status_code=400, detail={"error": "image URL exceeds 50MB limit"})
+    return data, f"image_url.{_extension_from_mime(mime_type)}", mime_type
+
+
+def _response_mime_type(response: requests.Response, parsed_path: str) -> str:
+    """识别下载图片类型：优先响应头，必要时按 URL 后缀推断。"""
+    header_type = str(response.headers.get("content-type") or "").split(";", 1)[0].strip().lower()
+    guessed_type = mimetypes.guess_type(parsed_path)[0] or ""
+    if header_type.startswith("image/"):
+        return header_type
+    if header_type and header_type not in {"application/octet-stream", "binary/octet-stream"}:
+        raise HTTPException(status_code=400, detail={"error": "image_url must point to an image"})
+    if guessed_type.startswith("image/"):
+        return guessed_type
+    if not header_type or header_type in {"application/octet-stream", "binary/octet-stream"}:
+        return "image/png"
+    raise HTTPException(status_code=400, detail={"error": "image_url must point to an image"})
+
+
+def _filename_from_url(parsed_path: str, mime_type: str) -> str:
+    """生成 URL 图片文件名：从链接路径提取名称并做安全化。"""
+    raw_name = PurePosixPath(unquote(parsed_path)).name
+    return _safe_filename(raw_name, mime_type, "image_url")
+
+
+def _download_image_url(url: str) -> ImageInput:
+    """下载远程图片：把 http/https 图片链接转成标准图片输入元组。"""
+    source = _clean(url)
+    if source.startswith("data:"):
+        return _decode_data_url(source)
+    parsed = urlparse(source)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise HTTPException(status_code=400, detail={"error": "image_url must be an http or https URL"})
+    try:
+        response = requests.get(
+            source,
+            headers={"Accept": "image/*,*/*;q=0.8", "User-Agent": "chatgpt2api image fetcher"},
+            timeout=60,
+            allow_redirects=True,
+            **proxy_settings.build_session_kwargs(),
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail={"error": f"image_url fetch failed: {exc}"}) from exc
+    if not 200 <= response.status_code < 300:
+        raise HTTPException(status_code=400, detail={"error": f"image_url fetch failed: HTTP {response.status_code}"})
+    content_length = _clean(response.headers.get("content-length"))
+    if content_length and content_length.isdigit() and int(content_length) > MAX_IMAGE_REFERENCE_BYTES:
+        raise HTTPException(status_code=400, detail={"error": "image_url exceeds 50MB limit"})
+    data = response.content
+    if not data:
+        raise HTTPException(status_code=400, detail={"error": "image_url returned empty content"})
+    if len(data) > MAX_IMAGE_REFERENCE_BYTES:
+        raise HTTPException(status_code=400, detail={"error": "image_url exceeds 50MB limit"})
+    mime_type = _response_mime_type(response, parsed.path)
+    return data, _filename_from_url(parsed.path, mime_type), mime_type
+
+
+async def read_image_sources(sources: list[ImageSource]) -> list[ImageInput]:
+    """读取图片来源：上传文件直接读取，URL 下载后统一返回图片元组。"""
+    images: list[ImageInput] = []
+    for source in sources:
+        if isinstance(source, tuple):
+            images.append(source)
+            continue
+        if _is_upload(source):
+            try:
+                image_data = await source.read()
+            finally:
+                await source.close()
+            if not image_data:
+                raise HTTPException(status_code=400, detail={"error": "image file is empty"})
+            images.append((image_data, source.filename or "image.png", source.content_type or "image/png"))
+            continue
+        images.append(await run_in_threadpool(_download_image_url, source))
+    if not images:
+        raise HTTPException(status_code=400, detail={"error": "image file or image_url is required"})
+    return images

api/image_tasks.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Header, HTTPException, Query, Request
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel, Field
+
+from api.image_inputs import parse_image_edit_request, read_image_sources
+from api.support import require_identity, resolve_image_base_url
+from services.content_filter import check_request
+from services.image_task_service import image_task_service
+from services.log_service import LoggedCall
+
+
+class ImageGenerationTaskRequest(BaseModel):
+    client_task_id: str = Field(..., min_length=1)
+    prompt: str = Field(..., min_length=1)
+    model: str = "gpt-image-2"
+    size: str | None = None
+    quality: str = "auto"
+
+
+def _parse_task_ids(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+async def filter_or_log(call: LoggedCall, text: str) -> None:
+    try:
+        await run_in_threadpool(check_request, text)
+    except HTTPException as exc:
+        call.log("调用失败", status="failed", error=str(exc.detail))
+        raise
+
+
+def create_router() -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/api/image-tasks")
+    async def list_image_tasks(
+        ids: str = Query(default=""),
+        authorization: str | None = Header(default=None),
+    ):
+        identity = require_identity(authorization)
+        return await run_in_threadpool(image_task_service.list_tasks, identity, _parse_task_ids(ids))
+
+    @router.post("/api/image-tasks/generations")
+    async def create_generation_task(
+        body: ImageGenerationTaskRequest,
+        request: Request,
+        authorization: str | None = Header(default=None),
+    ):
+        identity = require_identity(authorization)
+        await filter_or_log(LoggedCall(identity, "/api/image-tasks/generations", body.model, "文生图任务", request_text=body.prompt), body.prompt)
+        try:
+            return await run_in_threadpool(
+                image_task_service.submit_generation,
+                identity,
+                client_task_id=body.client_task_id,
+                prompt=body.prompt,
+                model=body.model,
+                size=body.size,
+                quality=body.quality,
+                base_url=resolve_image_base_url(request),
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.post("/api/image-tasks/edits")
+    async def create_edit_task(
+        request: Request,
+        authorization: str | None = Header(default=None),
+    ):
+        identity = require_identity(authorization)
+        payload, image_sources = await parse_image_edit_request(request)
+        client_task_id = str(payload.get("client_task_id") or "").strip()
+        if not client_task_id:
+            raise HTTPException(status_code=400, detail={"error": "client_task_id is required"})
+        prompt = str(payload["prompt"])
+        model = str(payload["model"])
+        await filter_or_log(LoggedCall(identity, "/api/image-tasks/edits", model, "图生图任务", request_text=prompt), prompt)
+        images = await read_image_sources(image_sources)
+        try:
+            return await run_in_threadpool(
+                image_task_service.submit_edit,
+                identity,
+                client_task_id=client_task_id,
+                prompt=prompt,
+                model=model,
+                size=payload["size"],
+                quality=payload["quality"],
+                base_url=resolve_image_base_url(request),
+                images=images,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    return router

api/register.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import asyncio
+import json
+
+from fastapi import APIRouter, Header
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+from api.support import require_admin
+from services.register_service import register_service
+
+
+class RegisterConfigRequest(BaseModel):
+    mail: dict | None = None
+    proxy: str | None = None
+    total: int | None = None
+    threads: int | None = None
+    mode: str | None = None
+    target_quota: int | None = None
+    target_available: int | None = None
+    check_interval: int | None = None
+
+
+def create_router() -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/api/register")
+    async def get_register_config(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"register": register_service.get()}
+
+    @router.post("/api/register")
+    async def update_register_config(body: RegisterConfigRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"register": register_service.update(body.model_dump(exclude_none=True))}
+
+    @router.post("/api/register/start")
+    async def start_register(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"register": register_service.start()}
+
+    @router.post("/api/register/stop")
+    async def stop_register(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"register": register_service.stop()}
+
+    @router.post("/api/register/reset")
+    async def reset_register(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"register": register_service.reset()}
+
+    @router.get("/api/register/events")
+    async def register_events(token: str = ""):
+        require_admin(f"Bearer {token}")
+
+        async def stream():
+            last = ""
+            while True:
+                payload = json.dumps(register_service.get(), ensure_ascii=False)
+                if payload != last:
+                    last = payload
+                    yield f"data: {payload}\n\n"
+                await asyncio.sleep(0.5)
+
+        return StreamingResponse(stream(), media_type="text/event-stream")
+
+    return router

api/support.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+from threading import Event, Thread
+
+from fastapi import HTTPException, Request
+
+from services.account_service import account_service
+from services.auth_service import auth_service
+from services.config import config
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+WEB_DIST_DIR = BASE_DIR / "web_dist"
+
+
+def extract_bearer_token(authorization: str | None) -> str:
+    scheme, _, value = str(authorization or "").partition(" ")
+    if scheme.lower() != "bearer" or not value.strip():
+        return ""
+    return value.strip()
+
+
+def _legacy_admin_identity(token: str) -> dict[str, object] | None:
+    auth_key = str(config.auth_key or "").strip()
+    if auth_key and token == auth_key:
+        return {"id": "admin", "name": "管理员", "role": "admin"}
+    return None
+
+
+def require_identity(authorization: str | None) -> dict[str, object]:
+    token = extract_bearer_token(authorization)
+    identity = _legacy_admin_identity(token) or auth_service.authenticate(token)
+    if identity is None:
+        raise HTTPException(status_code=401, detail={"error": "密钥无效或已失效，请重新登录"})
+    return identity
+
+
+def require_auth_key(authorization: str | None) -> None:
+    require_identity(authorization)
+
+
+def require_admin(authorization: str | None) -> dict[str, object]:
+    identity = require_identity(authorization)
+    if identity.get("role") != "admin":
+        raise HTTPException(status_code=403, detail={"error": "需要管理员权限才能执行这个操作"})
+    return identity
+
+
+def resolve_image_base_url(request: Request) -> str:
+    return config.base_url or f"{request.url.scheme}://{request.headers.get('host', request.url.netloc)}"
+
+
+def raise_image_quota_error(exc: Exception) -> None:
+    message = str(exc)
+    if "no available image quota" in message.lower():
+        raise HTTPException(status_code=429, detail={"error": "no available image quota"}) from exc
+    raise HTTPException(status_code=502, detail={"error": message}) from exc
+
+
+def sanitize_cpa_pool(pool: dict | None) -> dict | None:
+    if not isinstance(pool, dict):
+        return None
+    return {key: value for key, value in pool.items() if key != "secret_key"}
+
+
+def sanitize_cpa_pools(pools: list[dict]) -> list[dict]:
+    return [sanitized for pool in pools if (sanitized := sanitize_cpa_pool(pool)) is not None]
+
+
+def sanitize_sub2api_server(server: dict | None) -> dict | None:
+    if not isinstance(server, dict):
+        return None
+    sanitized = {key: value for key, value in server.items() if key not in {"password", "api_key"}}
+    sanitized["has_api_key"] = bool(str(server.get("api_key") or "").strip())
+    return sanitized
+
+
+def sanitize_sub2api_servers(servers: list[dict]) -> list[dict]:
+    return [sanitized for server in servers if (sanitized := sanitize_sub2api_server(server)) is not None]
+
+
+def start_limited_account_watcher(stop_event: Event) -> Thread:
+    interval_seconds = config.refresh_account_interval_minute * 60
+
+    def worker() -> None:
+        while not stop_event.is_set():
+            try:
+                limited_tokens = account_service.list_limited_tokens()
+                expiring_tokens = account_service.list_expiring_access_tokens()
+                keepalive_tokens = account_service.list_refresh_token_keepalive_tokens()
+                tokens = list(dict.fromkeys([*limited_tokens, *expiring_tokens]))
+                expiring_token_set = set(expiring_tokens)
+                keepalive_tokens = [token for token in keepalive_tokens if token not in expiring_token_set]
+                if tokens:
+                    print(
+                        "[account-watcher] checking "
+                        f"{len(limited_tokens)} limited accounts, "
+                        f"{len(expiring_tokens)} expiring access tokens"
+                    )
+                    account_service.refresh_accounts(tokens)
+                if keepalive_tokens:
+                    print(f"[account-watcher] keepalive {len(keepalive_tokens)} refresh tokens")
+                    result = account_service.keepalive_refresh_tokens(keepalive_tokens)
+                    if result.get("errors"):
+                        print(f"[account-watcher] keepalive errors: {result['errors']}")
+            except Exception as exc:
+                print(f"[account-watcher] fail {exc}")
+            stop_event.wait(interval_seconds)
+
+    thread = Thread(target=worker, name="account-watcher", daemon=True)
+    thread.start()
+    return thread
+
+
+def resolve_web_asset(requested_path: str) -> Path | None:
+    if not WEB_DIST_DIR.exists():
+        return None
+    clean_path = requested_path.strip("/")
+    base_dir = WEB_DIST_DIR.resolve()
+    candidates = [base_dir / "index.html"] if not clean_path else [
+        base_dir / Path(clean_path),
+        base_dir / clean_path / "index.html",
+        base_dir / f"{clean_path}.html",
+    ]
+    for candidate in candidates:
+        try:
+            candidate.resolve().relative_to(base_dir)
+        except ValueError:
+            continue
+        if candidate.is_file():
+            return candidate
+    return None

api/system.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from fastapi import APIRouter, Header, HTTPException, Query, Request
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import HTMLResponse, Response, StreamingResponse
+from pydantic import BaseModel, ConfigDict
+
+from api.support import require_admin, require_identity, resolve_image_base_url
+from services.backup_service import BackupError, backup_service
+from services.config import config
+from services.image_service import (
+    compress_images,
+    delete_images,
+    delete_to_target,
+    download_images_zip,
+    get_image_download_response,
+    get_image_response,
+    get_thumbnail_response,
+    list_images,
+    storage_stats,
+)
+from services.image_storage_service import ImageStorageError, image_storage_service
+from services.image_tags_service import delete_tag, get_all_tags, set_tags
+from services.log_service import log_service
+from services.proxy_service import test_proxy
+
+
+class SettingsUpdateRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class ProxyTestRequest(BaseModel):
+    url: str = ""
+
+
+class ImageDeleteRequest(BaseModel):
+    paths: list[str] = []
+    start_date: str = ""
+    end_date: str = ""
+    all_matching: bool = False
+
+class ImageDownloadRequest(BaseModel):
+    paths: list[str]
+
+class ImageTagsRequest(BaseModel):
+    path: str
+    tags: list[str]
+
+class LogDeleteRequest(BaseModel):
+    ids: list[str] = []
+class BackupDeleteRequest(BaseModel):
+    key: str = ""
+
+
+def create_router(app_version: str) -> APIRouter:
+    router = APIRouter()
+
+    @router.post("/auth/login")
+    async def login(authorization: str | None = Header(default=None)):
+        identity = require_identity(authorization)
+        return {
+            "ok": True,
+            "version": app_version,
+            "role": identity.get("role"),
+            "subject_id": identity.get("id"),
+            "name": identity.get("name"),
+        }
+
+    @router.get("/version")
+    async def get_version():
+        return {"version": app_version}
+
+    @router.get("/api/settings")
+    async def get_settings(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"config": config.get()}
+
+    @router.post("/api/settings")
+    async def save_settings(body: SettingsUpdateRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            return {"config": config.update(body.model_dump(mode="python"))}
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.get("/api/images")
+    async def get_images(request: Request, start_date: str = "", end_date: str = "", authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return list_images(resolve_image_base_url(request), start_date=start_date.strip(), end_date=end_date.strip())
+
+    @router.get("/images/{image_path:path}", include_in_schema=False)
+    async def get_image(image_path: str):
+        return get_image_response(image_path)
+
+    @router.get("/image-thumbnails/{image_path:path}", include_in_schema=False)
+    async def get_image_thumbnail(image_path: str):
+        return get_thumbnail_response(image_path)
+
+    @router.post("/api/images/delete")
+    async def delete_images_endpoint(body: ImageDeleteRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return delete_images(body.paths, start_date=body.start_date.strip(), end_date=body.end_date.strip(), all_matching=body.all_matching)
+
+    @router.post("/api/images/download")
+    async def download_images_endpoint(body: ImageDownloadRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        buf = download_images_zip(body.paths)
+        return StreamingResponse(
+            buf,
+            media_type="application/zip",
+            headers={"Content-Disposition": 'attachment; filename="images.zip"'},
+        )
+
+    @router.get("/api/images/download/{image_path:path}")
+    async def download_single_image_endpoint(image_path: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return get_image_download_response(image_path)
+
+    @router.get("/api/logs")
+    async def get_logs(type: str = "", start_date: str = "", end_date: str = "", authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"items": log_service.list(type=type.strip(), start_date=start_date.strip(), end_date=end_date.strip())}
+
+    @router.post("/api/logs/delete")
+    async def delete_logs(body: LogDeleteRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return log_service.delete(body.ids)
+
+    @router.post("/api/proxy/test")
+    async def test_proxy_endpoint(body: ProxyTestRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        candidate = (body.url or "").strip() or config.get_proxy_settings()
+        if not candidate:
+            raise HTTPException(status_code=400, detail={"error": "proxy url is required"})
+        return {"result": await run_in_threadpool(test_proxy, candidate)}
+
+    @router.get("/api/storage/info")
+    async def get_storage_info(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        storage = config.get_storage_backend()
+        return {
+            "backend": storage.get_backend_info(),
+            "health": storage.health_check(),
+        }
+
+    @router.post("/api/backup/test")
+    async def test_backup_connection(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            return {"result": await run_in_threadpool(backup_service.test_connection)}
+        except BackupError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.post("/api/image-storage/test")
+    async def test_image_storage_endpoint(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"result": await run_in_threadpool(image_storage_service.test_webdav)}
+
+    @router.post("/api/image-storage/sync")
+    async def sync_image_storage_endpoint(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            return {"result": await run_in_threadpool(image_storage_service.sync_all)}
+        except ImageStorageError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.get("/api/backups")
+    async def get_backups(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            return {
+                "items": await run_in_threadpool(backup_service.list_backups),
+                "state": backup_service.get_status(),
+                "settings": backup_service.get_settings(),
+            }
+        except BackupError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.post("/api/backups/run")
+    async def run_backup_endpoint(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            return {"result": await run_in_threadpool(backup_service.run_backup)}
+        except BackupError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.post("/api/backups/delete")
+    async def delete_backup_endpoint(body: BackupDeleteRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            await run_in_threadpool(backup_service.delete_backup, body.key)
+            return {"ok": True}
+        except BackupError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.get("/api/backups/detail")
+    async def get_backup_detail(key: str = "", authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            return {"item": await run_in_threadpool(backup_service.get_backup_detail, key)}
+        except BackupError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+
+    @router.get("/api/backups/download")
+    async def download_backup_endpoint(key: str = "", authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        try:
+            item = await run_in_threadpool(backup_service.download_backup, key)
+        except BackupError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)}) from exc
+        filename = str(item.get("name") or "backup.bin")
+        quoted = quote(filename)
+        headers = {
+            "Content-Disposition": f"attachment; filename*=UTF-8''{quoted}",
+            "Content-Length": str(int(item.get("size") or 0)),
+        }
+        return Response(
+            content=bytes(item.get("payload") or b""),
+            media_type=str(item.get("content_type") or "application/octet-stream"),
+            headers=headers,
+        )
+
+
+    @router.get("/api/images/tags")
+    async def list_image_tags(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return {"tags": get_all_tags()}
+
+    @router.post("/api/images/tags")
+    async def update_image_tags(body: ImageTagsRequest, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        rel = body.path.strip().lstrip("/")
+        if not rel:
+            raise HTTPException(status_code=400, detail={"error": "path is required"})
+        tags = set_tags(rel, body.tags)
+        return {"ok": True, "tags": tags}
+
+    @router.delete("/api/images/tags/{tag}")
+    async def delete_image_tag(tag: str, authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        count = delete_tag(tag)
+        return {"ok": True, "removed_from": count}
+
+    @router.get("/api/images/storage")
+    async def get_image_storage(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return storage_stats()
+
+    @router.post("/api/images/storage/compress")
+    async def compress_all_images(authorization: str | None = Header(default=None)):
+        require_admin(authorization)
+        return await run_in_threadpool(compress_images)
+
+    @router.post("/api/images/storage/cleanup-to-target")
+    async def cleanup_to_target(
+        target_free_mb: int = 500,
+        dry_run: bool = False,
+        authorization: str | None = Header(default=None),
+    ):
+        require_admin(authorization)
+        return await run_in_threadpool(delete_to_target, target_free_mb, dry_run)
+
+    @router.get("/health", response_model=None)
+    async def health_dashboard(format: str = Query(default="html")):
+        from services.account_service import account_service as acct_svc
+        stats = acct_svc.get_stats()
+        storage = config.get_storage_backend()
+        storage_health = storage.health_check()
+        healthy = stats["active"] > 0 or stats["unlimited_quota_count"] > 0
+
+        stats_json = {
+            "status": "ok" if healthy else "degraded",
+            "healthy": healthy,
+            "version": app_version,
+            "storage": {"backend": storage.get_backend_info(), "health": storage_health},
+            "accounts": stats,
+        }
+        if format == "json":
+            return stats_json
+        return HTMLResponse(f"""<!DOCTYPE html>
+<html lang="zh">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>号池健康监控 - chatgpt2api</title>
+<style>
+*{{margin:0;padding:0;box-sizing:border-box}}
+body{{font-family:system-ui,-apple-system,sans-serif;background:#0f1117;color:#e2e8f0;min-height:100vh}}
+.header{{background:#1a1d27;border-bottom:1px solid #2a2d3a;padding:16px 24px;display:flex;justify-content:space-between;align-items:center}}
+.header h1{{font-size:20px}}
+.status-dot{{display:inline-block;width:10px;height:10px;border-radius:50%;margin-right:8px}}
+.status-ok{{background:#22c55e;box-shadow:0 0 8px #22c55e88}}
+.status-degraded{{background:#f59e0b;box-shadow:0 0 8px #f59e0b88}}
+.container{{max-width:960px;margin:0 auto;padding:24px}}
+.cards{{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:24px}}
+.card{{background:#1a1d27;border:1px solid #2a2d3a;border-radius:10px;padding:16px}}
+.card .value{{font-size:28px;font-weight:700;margin:4px 0}}
+.card .label{{font-size:13px;color:#94a3b8}}
+.green{{color:#22c55e}}.yellow{{color:#f59e0b}}.red{{color:#ef4444}}.blue{{color:#6c63ff}}
+table{{width:100%;border-collapse:collapse;background:#1a1d27;border:1px solid #2a2d3a;border-radius:10px;overflow:hidden}}
+th{{background:#242836;font-weight:600;text-align:left;padding:10px 12px;font-size:12px;color:#94a3b8;text-transform:uppercase}}
+td{{padding:8px 12px;border-top:1px solid #2a2d3a;font-size:14px}}tr:hover td{{background:rgba(108,99,255,.05)}}
+.api-url{{font-family:monospace;font-size:12px;color:#6c63ff}}
+.refresh{{font-size:12px;color:#64748b;text-align:center;margin-top:24px}}
+</style>
+<meta http-equiv="refresh" content="30">
+</head>
+<body>
+<div class="header">
+<h1><span class="status-dot {'status-ok' if healthy else 'status-degraded'}"></span>号池健康监控</h1>
+<div style="font-size:13px;color:#94a3b8">v{app_version} · 30s 自动刷新</div>
+</div>
+<div class="container">
+<div class="cards">
+<div class="card"><div class="label">号池状态</div><div class="value {'green' if healthy else 'yellow'}">{'正常' if healthy else '异常'}</div></div>
+<div class="card"><div class="label">当前账号</div><div class="value blue">{stats['total']}</div></div>
+<div class="card"><div class="label">累计入库</div><div class="value">{stats['cumulative_total']}</div></div>
+<div class="card"><div class="label">可用账号</div><div class="value green">{stats['active']}</div></div>
+<div class="card"><div class="label">无限额</div><div class="value">{stats['unlimited_quota_count']}</div></div>
+<div class="card"><div class="label">剩余额度</div><div class="value">{stats['total_quota']}</div></div>
+<div class="card"><div class="label">限流</div><div class="value yellow">{stats['limited']}</div></div>
+<div class="card"><div class="label">异常</div><div class="value red">{stats['abnormal']}</div></div>
+<div class="card"><div class="label">禁用</div><div class="value">{stats['disabled']}</div></div>
+<div class="card"><div class="label">成功/失败</div><div class="value">{stats['total_success']}<span style="font-size:18px;color:#94a3b8">/</span><span class="red">{stats['total_fail']}</span></div></div>
+</div>
+<h2 style="margin-bottom:12px;font-size:16px">账号类型分布</h2>
+<table>
+<tr><th>类型</th><th>数量</th></tr>
+{''.join(f'<tr><td>{t}</td><td>{c}</td></tr>' for t,c in sorted(stats['by_type'].items()))}
+</table>
+<div class="refresh">JSON: <span class="api-url">/health?format=json</span></div>
+</div></body></html>""")
+
+    return router

docker-compose.local.yml

@@ -0,0 +1,34 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: chatgpt2api:local
+    container_name: chatgpt2api-local
+    ports:
+      - "8000:80"
+    volumes:
+      - ./data:/app/data
+      - ./config.json:/app/config.json
+    environment:
+      STORAGE_BACKEND: sqlite
+      DATABASE_URL: sqlite:////app/data/accounts.db
+    # 存储后端配置 (可选值: json, sqlite, postgres, git)
+    # environment:
+    #   STORAGE_BACKEND: json
+
+    # 数据库配置 (当 STORAGE_BACKEND=sqlite/postgres 时使用)
+    #   DATABASE_URL: postgresql://user:password@host:5432/dbname
+    #   DATABASE_URL: sqlite:////app/data/accounts.db
+
+    # Git 仓库配置 (当 STORAGE_BACKEND=git 时使用)
+    #   GIT_REPO_URL: https://github.com/user/repo.git
+    #   GIT_TOKEN: ghp_xxxxxxxxxxxx
+    #   GIT_BRANCH: main
+    #   GIT_FILE_PATH: accounts.json
+
+    # 认证密钥 (可选，覆盖 config.json)
+    #   CHATGPT2API_AUTH_KEY: your_secret_key
+
+    # 基础 URL (可选)
+    #   CHATGPT2API_BASE_URL: https://your-domain.com

docker-compose.yml

@@ -0,0 +1,29 @@
+services:
+  app:
+    image: ghcr.io/basketikun/chatgpt2api:latest
+    container_name: chatgpt2api
+    restart: unless-stopped
+    ports:
+      - "3000:80"
+    volumes:
+      - ./data:/app/data
+      - ./config.json:/app/config.json
+    environment:
+      # 存储后端配置 (可选值: json, sqlite, postgres, git)
+       - STORAGE_BACKEND=json
+      
+      # 数据库配置 (当 STORAGE_BACKEND=sqlite/postgres 时使用)
+      # - DATABASE_URL=postgresql://user:password@host:5432/dbname
+      # - DATABASE_URL=sqlite:///app/data/accounts.db
+      
+      # Git 仓库配置 (当 STORAGE_BACKEND=git 时使用)
+      # - GIT_REPO_URL=https://github.com/user/repo.git
+      # - GIT_TOKEN=ghp_xxxxxxxxxxxx
+      # - GIT_BRANCH=main
+      # - GIT_FILE_PATH=accounts.json
+      
+      # 认证密钥 (可选，覆盖 config.json)
+      # - CHATGPT2API_AUTH_KEY=your_secret_key
+      
+      # 基础 URL (可选)
+      # - CHATGPT2API_BASE_URL=https://your-domain.com

docs/feature-status.en.md

@@ -0,0 +1,37 @@
+# 功能状态
+
+本文基于当前仓库当前实现整理，用于帮助用户快速了解哪些功能已经可用、哪些仍在完善、哪些待实现。
+
+| 功能 | 状态 | 说明 |
+|:----------------------------------------|:--:|:--------------------------------------------------------------|
+| OpenAI 兼容 `POST /v1/images/generations` | ✅  | 已支持，用于图片生成，并可通过 `n` 返回多张图片。 |
+| OpenAI 兼容 `POST /v1/images/edits` | ✅  | 已支持，可上传图片进行编辑。 |
+| 面向图片工作流的 `POST /v1/chat/completions` | ✅  | 已支持图片相关请求。 |
+| 面向图片工作流的 `POST /v1/responses` | ✅  | 已支持图片生成工具调用。 |
+| `GET /v1/models` 接口 | ✅  | 当前返回 `gpt-image-2`、`codex-gpt-image-2`、`auto`、`gpt-5`、`gpt-5-1`、`gpt-5-2`、`gpt-5-3`、`gpt-5-3-mini`、`gpt-5-mini`。 |
+| 同时生成多张图片 | ✅  | 已支持，后端与前端都可进行多图生成。 |
+| 前端图片工作台 | ✅  | 已支持图片生成、图片编辑、模型选择、历史记录与查看大图。 |
+| 前端图片输入 / 参考图交互 | ✅  | 已支持参考图上传、预览、移除和编辑模式工作流。 |
+| Codex 画图接口逆向 | ✅  | 已支持，仅 `Plus` / `Team` / `Pro` 订阅可用，模型别名为 `codex-gpt-image-2`；如有需要可自行在其他场景映射回 `gpt-image-2`。这是 Codex 逆向链路，用于和官网画图区分，同一账号通常会同时支持官网和 Codex 两份生图额度。 |
+| Cherry Studio 接入 | ✅  | 已支持作为绘图接口接入 Cherry Studio。 |
+| New API 接入 | ✅  | 已支持接入 New API。 |
+| 账号池管理 | ✅  | 已支持列表、筛选、批量操作、导出、手动编辑、刷新和删除。 |
+| 账号额度刷新与恢复时间同步 | ✅  | 已支持账号信息刷新，限流账号也会自动继续检查。 |
+| 失效 Token 自动清理 | ✅  | 已支持自动移除失效 Token。 |
+| CPA 连接管理 | ✅  | 已支持 CPA 连接的新增、修改、查询和删除。 |
+| CPA 文件浏览与按需导入 | ✅  | 已支持读取远程文件列表、筛选、勾选并导入到本地号池。 |
+| CPA 导入进度跟踪 | ✅  | 已支持导入进度展示与轮询更新。 |
+| `sub2api` 连接管理与账号浏览 | ✅  | 已支持 `sub2api` 服务器的新增、修改、删除、分组查询和 OpenAI OAuth 账号列表读取。 |
+| `sub2api` 导入 | ✅  | 已支持勾选 `sub2api` 中的 OpenAI OAuth 账号，批量拉取 `access_token` 导入本地号池，并展示导入进度。 |
+| Docker 自托管部署 | ✅  | 已支持 Docker Compose 部署，并提供多架构镜像。 |
+| 兼容接口中的多参考图能力 | ✅  | 已实现，支持在兼容接口中传入多参考图。 |
+| 更高级的 Token 调度策略 | ⚠️ | 当前已有基础轮询与限流刷新机制，更复杂的调度策略仍在完善中。 |
+| Render / Vercel 等部署表述 | ⚠️ | 当前主要以 Docker 部署为主，其他平台部署方式暂未重点说明。 |
+| `/v1/complete` 文本补全与流式输出 | ✅  | 已实现。 |
+| 流式输出支持 | ✅  | 已实现。 |
+| 文本补全缓存与重复请求合并 | ✅  | `/v1/chat/completions` 文本链路默认启用 60 秒短缓存、流式结果回放、in-flight 请求合并和相邻重复消息清理；可通过 `chat_completion_cache` 配置关闭或调整。 |
+| 图片尺寸参数 | ❌  | 待实现。 |
+| 服务端图片 URL 缓存 | ✅  | 已实现。 |
+| `rt_token` 刷新 | ❌  | 待实现。 |
+| 代理配置功能 | ✅  | 已支持网页端配置全局 HTTP / HTTPS / SOCKS5 / SOCKS5H 代理，并应用到出站请求。 |
+| Anthropic 协议支持 | ❌  | 待实现。 |

docs/review.md

@@ -0,0 +1,9 @@
+# Review
+
+- [P2] Poll when the image tool was invoked  
+  `services/protocol/conversation.py:586`  
+  对于没有输入图片的图像生成任务，延迟结果仍可能在 SSE 返回 `tool_invoked: true` 之后到达，但这里新的判断条件忽略了 `tool_invoked`。这样会直接返回中间文本，而不会继续轮询会话来拿图片 ID。
+
+- [P2] Align CloudMail domain validation with the UI  
+  `web/src/app/register/components/register-card.tsx:266`  
+  `cloudmail_gen` 的 placeholder 写的是留空会使用服务默认域名，但后端 `create_mailbox` 不接受空域名。用户按 UI 提示保存后，这个 provider 会在真正创建地址前失败。

docs/upstream-sse-conversation.md

@@ -0,0 +1,271 @@
+# 上游 Conversation SSE 协议说明
+
+Conversation SSE 是上游对话链路的流式返回协议。每条 SSE `data:` 通常是一段 JSON payload，也可能是协议标记或结束标记。客户端需要按顺序消费这些 payload，维护当前会话状态、文本内容、工具调用状态和图片结果指针。
+
+## 基本形态
+
+常见 payload 示例：
+
+```text
+"v1"
+{"type":"resume_conversation_token",...}
+{"p":"","o":"add","v":{...}}
+{"v":{...}}
+{"p":"/message/content/parts/0","o":"append","v":"..."}
+{"type":"server_ste_metadata","metadata":{...}}
+[DONE]
+```
+
+处理建议：
+
+| payload | 含义 | 处理方式 |
+|:--|:--|:--|
+| `"v1"` | 协议版本标记 | 可记录，通常不影响业务 |
+| `[DONE]` | 当前 SSE 流结束 | 停止继续读取 |
+| JSON object | 事件、消息或 patch | 按字段更新会话状态 |
+| JSON string | 短文本 patch 或协议标记 | 结合上下文处理 |
+| 非 JSON 内容 | 原始内容 | 保留为 raw 事件，避免中断流 |
+
+## 常用字段
+
+| 字段 | 说明 |
+|:--|:--|
+| `type` | 上游事件类型，如 `resume_conversation_token`、`input_message`、`message_marker`、`title_generation`、`server_ste_metadata` |
+| `conversation_id` | 当前会话 ID，可从多个事件中获得 |
+| `p` | patch 路径，例如 `/message/content/parts/0` |
+| `o` | patch 操作，例如 `add`、`append`、`replace`、`patch` |
+| `v` | patch 值，可能是字符串、数组，也可能包含完整 message |
+| `c` | 消息序号或游标，常见于 add 类事件 |
+| `message.id` | 消息 ID |
+| `message.author.role` | 消息角色，常见 `system`、`user`、`assistant`、`tool` |
+| `message.content.content_type` | 内容类型，如 `text`、`multimodal_text`、`model_editable_context` |
+| `message.content.parts` | 内容片段，可能包含文本、图片指针或多模态对象 |
+| `message.status` | 消息状态，如 `in_progress`、`finished_successfully` |
+| `message.end_turn` | 是否结束当前轮次 |
+| `metadata.tool_invoked` | 本轮是否调用工具 |
+| `metadata.turn_use_case` | 本轮用途，如 `text`、`multimodal` |
+| `metadata.async_task_type` | 异步工具任务类型，图片生成通常为 `image_gen` |
+
+## 会话启动事件
+
+上游通常会先返回恢复令牌或会话令牌：
+
+```json
+{
+  "type": "resume_conversation_token",
+  "kind": "topic",
+  "token": "...",
+  "conversation_id": "..."
+}
+```
+
+这个事件主要用于标识会话和恢复上下文。业务层通常只需要保存 `conversation_id`，`token` 不应该暴露给下游用户。
+
+## 消息 add 场景
+
+完整消息可能通过 `add` 或带 `v.message` 的事件出现：
+
+```json
+{
+  "p": "",
+  "o": "add",
+  "v": {
+    "message": {
+      "author": {"role": "assistant"},
+      "content": {"content_type": "text", "parts": [""]},
+      "status": "in_progress"
+    },
+    "conversation_id": "..."
+  },
+  "c": 3
+}
+```
+
+此类事件常用于创建一条新消息。若消息角色为 `assistant`，后续文本通常会通过 patch 继续追加。
+
+## 文本增量场景
+
+文本输出通常由多条 patch 组成：
+
+```json
+{"p":"/message/content/parts/0","o":"append","v":"Hello"}
+{"v":" world"}
+{"p":"","o":"patch","v":[
+  {"p":"/message/content/parts/0","o":"append","v":"!"},
+  {"p":"/message/status","o":"replace","v":"finished_successfully"},
+  {"p":"/message/end_turn","o":"replace","v":true}
+]}
+```
+
+处理要点：
+
+| 形态 | 含义 |
+|:--|:--|
+| `p == "/message/content/parts/0"` 且 `o == "append"` | 向当前文本追加内容 |
+| `o == "replace"` | 用新值替换目标字段 |
+| `o == "patch"` 且 `v` 是数组 | 批量 patch，需要按数组顺序处理 |
+| 只有 `v` 且 `v` 是字符串 | 可能是省略路径的文本增量，应结合当前文本流处理 |
+
+## 输入消息场景
+
+用户输入会以 `input_message` 或普通 `user` message 出现。图片编辑请求会包含用户上传的参考图：
+
+```json
+{
+  "type": "input_message",
+  "input_message": {
+    "author": {"role": "user"},
+    "content": {
+      "content_type": "multimodal_text",
+      "parts": [
+        {"asset_pointer": "sediment://file_input"},
+        "编辑提示词"
+      ]
+    }
+  },
+  "conversation_id": "..."
+}
+```
+
+这类 `sediment://...` 表示输入附件，不是生成结果。即使它可以被下载，也不能当作输出图片返回。
+
+## 图片工具成功场景
+
+图片生成或图片编辑成功时，上游一般会出现工具消息：
+
+```json
+{
+  "v": {
+    "message": {
+      "author": {"role": "tool"},
+      "content": {
+        "content_type": "multimodal_text",
+        "parts": [
+          {"asset_pointer": "file-service://file_result"},
+          {"asset_pointer": "sediment://file_result"}
+        ]
+      },
+      "metadata": {"async_task_type": "image_gen"}
+    }
+  },
+  "conversation_id": "..."
+}
+```
+
+只有同时满足以下条件的图片指针，才应该视为输出结果：
+
+| 条件 | 说明 |
+|:--|:--|
+| `message.author.role == "tool"` | 来源是工具消息 |
+| `metadata.async_task_type == "image_gen"` | 工具任务是图片生成 |
+| `asset_pointer` 为 `file-service://...` 或 `sediment://...` | 指向可解析图片资源 |
+
+## 图片指针类型
+
+| 指针 | 常见来源 | 说明 |
+|:--|:--|:--|
+| `file-service://file_xxx` | 图片工具输出 | 可通过文件下载接口解析 |
+| `sediment://file_xxx` | 输入附件或图片工具输出 | 需要结合消息角色判断来源 |
+| `file_upload` | 上传过程占位 | 通常不应作为输出 |
+
+不要只凭字符串里出现 `file_` 或 `sediment://` 就判定为输出图。必须结合消息角色和任务类型。
+
+## 策略拒绝场景
+
+当上游拒绝请求时，通常不会产生图片工具消息，而是返回普通 assistant 文本：
+
+```text
+I can't assist with that request. If you have another type of modification...
+```
+
+常见伴随事件：
+
+```json
+{"type":"title_generation","title":"Request Denied","conversation_id":"..."}
+```
+
+```json
+{
+  "type": "server_ste_metadata",
+  "metadata": {
+    "tool_invoked": false,
+    "turn_use_case": "multimodal",
+    "did_prompt_contain_image": true
+  },
+  "conversation_id": "..."
+}
+```
+
+处理要点：
+
+| 条件 | 行为 |
+|:--|:--|
+| 有 assistant 拒绝文本 | 应返回文本消息 |
+| `tool_invoked == false` | 说明没有实际工具结果 |
+| 没有 `role=tool` 且 `async_task_type=image_gen` 的消息 | 不应收集输出图片 |
+| 用户输入消息里有图片指针 | 仍然只视为输入附件 |
+
+## moderation 场景
+
+部分请求可能返回 moderation 事件：
+
+```json
+{
+  "type": "moderation",
+  "moderation_response": {
+    "blocked": true
+  },
+  "conversation_id": "..."
+}
+```
+
+若 `blocked == true`，应认为本轮被策略拦截。后续如有 assistant 文本，应优先返回该文本；若没有文本，可返回合适的错误信息。
+
+## marker 和 title 事件
+
+上游会返回一些辅助事件：
+
+```json
+{"type":"message_marker","marker":"user_visible_token","event":"first"}
+{"type":"message_marker","marker":"last_token","event":"last"}
+{"type":"title_generation","title":"...","conversation_id":"..."}
+```
+
+这些事件通常用于前端展示、标题生成或流式状态标记，不代表实际文本内容或图片结果。
+
+## metadata 事件
+
+`server_ste_metadata` 用于描述本轮调度和工具状态：
+
+```json
+{
+  "type": "server_ste_metadata",
+  "metadata": {
+    "tool_invoked": true,
+    "turn_use_case": "multimodal",
+    "model_slug": "i-mini-m",
+    "did_prompt_contain_image": true
+  }
+}
+```
+
+常用判断：
+
+| 字段 | 说明 |
+|:--|:--|
+| `tool_invoked == true` | 上游认为本轮调用过工具 |
+| `tool_invoked == false` | 上游未调用工具，常见于拒绝或纯文本响应 |
+| `turn_use_case == "text"` | 按文本响应处理 |
+| `turn_use_case == "multimodal"` | 多模态请求，不代表一定有图片输出 |
+| `did_prompt_contain_image == true` | 输入包含图片，不代表输出包含图片 |
+
+## 结束后的结果判断
+
+SSE 结束后可按以下顺序判断结果：
+
+1. 如果已经收集到图片工具输出指针，解析并下载输出图片。
+2. 如果没有输出图片指针，但有 assistant 文本，并且本轮被拦截或未调用工具，返回文本消息。
+3. 如果没有输出图片指针，但有 `conversation_id`，可查询完整会话明细，继续寻找图片工具输出。
+4. 查询完整会话时，仍然只读取 `role=tool` 且 `async_task_type=image_gen` 的消息。
+5. 如果没有图片结果也没有文本，返回上游异常或空结果错误。
+

main.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import uvicorn
+from api import create_app
+
+app = create_app()
+
+if __name__ == "__main__":
+    uvicorn.run(app, access_log=False, log_level="info")

pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "chatgpt2api"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "curl-cffi>=0.15.0",
+    "fastapi>=0.136.0",
+    "pillow>=12.2.0",
+    "pybase64>=1.4.3",
+    "python-multipart>=0.0.26",
+    "tiktoken>=0.12.0",
+    "uvicorn>=0.44.0",
+    "sqlalchemy>=2.0.0",
+    "psycopg2-binary>=2.9.0",
+    "gitpython>=3.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+]
+
+[[tool.uv.index]]
+url = "https://mirrors.aliyun.com/pypi/simple"
+default = true

scripts/migrate_storage.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+存储后端数据迁移脚本
+
+用法：
+  python scripts/migrate_storage.py --from json --to postgres
+  python scripts/migrate_storage.py --from postgres --to git
+  python scripts/migrate_storage.py --export accounts.json
+  python scripts/migrate_storage.py --import accounts.json
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# 添加项目根目录到 Python 路径
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+DATA_DIR = Path(__file__).resolve().parents[1] / "data"
+
+from services.storage.factory import create_storage_backend
+
+
+def export_to_json(output_file: str):
+    """导出当前存储后端的数据到 JSON 文件"""
+    print(f"[migrate] Exporting data to {output_file}")
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    storage = create_storage_backend(DATA_DIR)
+    accounts = storage.load_accounts()
+    
+    output_path = Path(output_file)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(
+        json.dumps(accounts, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    
+    print(f"[migrate] Exported {len(accounts)} accounts to {output_file}")
+
+
+def import_from_json(input_file: str):
+    """从 JSON 文件导入数据到当前存储后端"""
+    print(f"[migrate] Importing data from {input_file}")
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    input_path = Path(input_file)
+    if not input_path.exists():
+        print(f"[migrate] Error: File not found: {input_file}")
+        sys.exit(1)
+    
+    try:
+        accounts = json.loads(input_path.read_text(encoding="utf-8"))
+        if not isinstance(accounts, list):
+            print(f"[migrate] Error: Invalid JSON format, expected array")
+            sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"[migrate] Error: Invalid JSON: {e}")
+        sys.exit(1)
+    
+    storage = create_storage_backend(DATA_DIR)
+    storage.save_accounts(accounts)
+    
+    print(f"[migrate] Imported {len(accounts)} accounts")
+
+
+def migrate_data(from_backend: str, to_backend: str):
+    """从一个存储后端迁移到另一个"""
+    print(f"[migrate] Migrating from {from_backend} to {to_backend}")
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    # 保存原始环境变量
+    original_backend = os.environ.get("STORAGE_BACKEND")
+    
+    try:
+        # 从源后端读取数据
+        os.environ["STORAGE_BACKEND"] = from_backend
+        from_storage = create_storage_backend(DATA_DIR)
+        accounts = from_storage.load_accounts()
+        print(f"[migrate] Loaded {len(accounts)} accounts from {from_backend}")
+        
+        # 写入目标后端
+        os.environ["STORAGE_BACKEND"] = to_backend
+        to_storage = create_storage_backend(DATA_DIR)
+        to_storage.save_accounts(accounts)
+        print(f"[migrate] Saved {len(accounts)} accounts to {to_backend}")
+        
+        print(f"[migrate] Migration completed successfully!")
+        
+    finally:
+        # 恢复原始环境变量
+        if original_backend:
+            os.environ["STORAGE_BACKEND"] = original_backend
+        elif "STORAGE_BACKEND" in os.environ:
+            del os.environ["STORAGE_BACKEND"]
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ChatGPT2API 存储后端数据迁移工具",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  # 从 JSON 迁移到 PostgreSQL
+  python scripts/migrate_storage.py --from json --to postgres
+  
+  # 从 PostgreSQL 迁移到 Git
+  python scripts/migrate_storage.py --from postgres --to git
+  
+  # 导出当前数据到 JSON 文件
+  python scripts/migrate_storage.py --export backup.json
+  
+  # 从 JSON 文件导入数据
+  python scripts/migrate_storage.py --import backup.json
+
+环境变量:
+  STORAGE_BACKEND  - 存储后端类型 (json, sqlite, postgres, git)
+  DATABASE_URL     - 数据库连接字符串
+  GIT_REPO_URL     - Git 仓库地址
+  GIT_TOKEN        - Git 访问令牌
+        """
+    )
+    
+    parser.add_argument(
+        "--from",
+        dest="from_backend",
+        choices=["json", "sqlite", "postgres", "git"],
+        help="源存储后端",
+    )
+    parser.add_argument(
+        "--to",
+        dest="to_backend",
+        choices=["json", "sqlite", "postgres", "git"],
+        help="目标存储后端",
+    )
+    parser.add_argument(
+        "--export",
+        dest="export_file",
+        metavar="FILE",
+        help="导出数据到 JSON 文件",
+    )
+    parser.add_argument(
+        "--import",
+        dest="import_file",
+        metavar="FILE",
+        help="从 JSON 文件导入数据",
+    )
+    
+    args = parser.parse_args()
+    
+    # 检查参数
+    if args.from_backend and args.to_backend:
+        migrate_data(args.from_backend, args.to_backend)
+    elif args.export_file:
+        export_to_json(args.export_file)
+    elif args.import_file:
+        import_from_json(args.import_file)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_storage.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+存储后端测试脚本
+
+用法：
+  python scripts/test_storage.py
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# 添加项目根目录到 Python 路径
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+DATA_DIR = Path(__file__).resolve().parents[1] / "data"
+
+from services.storage.factory import create_storage_backend
+
+
+def test_storage():
+    """测试当前配置的存储后端"""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    print("=" * 60)
+    print("ChatGPT2API 存储后端测试")
+    print("=" * 60)
+    
+    # 显示当前配置
+    backend_type = os.getenv("STORAGE_BACKEND", "json")
+    print(f"\n当前存储后端: {backend_type}")
+    
+    if backend_type in ("sqlite", "postgres", "postgresql", "mysql", "database"):
+        database_url = os.getenv("DATABASE_URL", "")
+        if database_url:
+            # 隐藏密码
+            if "://" in database_url and "@" in database_url:
+                protocol, rest = database_url.split("://", 1)
+                if "@" in rest:
+                    credentials, host = rest.split("@", 1)
+                    if ":" in credentials:
+                        username, _ = credentials.split(":", 1)
+                        database_url = f"{protocol}://{username}:****@{host}"
+            print(f"数据库连接: {database_url}")
+        else:
+            print(f"数据库连接: 本地 SQLite (data/accounts.db)")
+    
+    elif backend_type == "git":
+        repo_url = os.getenv("GIT_REPO_URL", "")
+        branch = os.getenv("GIT_BRANCH", "main")
+        file_path = os.getenv("GIT_FILE_PATH", "accounts.json")
+        print(f"Git 仓库: {repo_url}")
+        print(f"Git 分支: {branch}")
+        print(f"文件路径: {file_path}")
+    
+    print("\n" + "=" * 60)
+    
+    try:
+        # 创建存储后端
+        print("\n[1/5] 创建存储后端...")
+        storage = create_storage_backend(DATA_DIR)
+        print("✅ 存储后端创建成功")
+        
+        # 获取后端信息
+        print("\n[2/5] 获取后端信息...")
+        info = storage.get_backend_info()
+        print(f"✅ 后端类型: {info.get('type')}")
+        print(f"   描述: {info.get('description')}")
+        for key, value in info.items():
+            if key not in ('type', 'description'):
+                print(f"   {key}: {value}")
+        
+        # 健康检查
+        print("\n[3/5] 执行健康检查...")
+        health = storage.health_check()
+        status = health.get("status")
+        if status == "healthy":
+            print(f"✅ 健康状态: {status}")
+        else:
+            print(f"❌ 健康状态: {status}")
+            print(f"   错误: {health.get('error')}")
+            return False
+        
+        # 读取数据
+        print("\n[4/5] 读取账号数据...")
+        accounts = storage.load_accounts()
+        print(f"✅ 成功读取 {len(accounts)} 个账号")
+        
+        # 写入测试（可选）
+        print("\n[5/5] 测试写入功能...")
+        test_account = {
+            "access_token": "test_token_" + str(os.getpid()),
+            "type": "Free",
+            "status": "测试",
+            "quota": 0,
+            "email": "test@example.com",
+        }
+        
+        # 添加测试账号
+        test_accounts = accounts + [test_account]
+        storage.save_accounts(test_accounts)
+        print("✅ 写入测试账号成功")
+        
+        # 验证写入
+        reloaded = storage.load_accounts()
+        if len(reloaded) == len(test_accounts):
+            print("✅ 验证写入成功")
+        else:
+            print(f"❌ 验证失败: 期望 {len(test_accounts)} 个账号，实际 {len(reloaded)} 个")
+            return False
+        
+        # 恢复原始数据
+        storage.save_accounts(accounts)
+        print("✅ 恢复原始数据")
+        
+        print("\n" + "=" * 60)
+        print("✅ 所有测试通过！")
+        print("=" * 60)
+        return True
+        
+    except Exception as e:
+        print(f"\n❌ 测试失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    success = test_storage()
+    sys.exit(0 if success else 1)

scripts/verify_oauth_refresh.py

@@ -0,0 +1,92 @@
+"""验证 OAuth 账号的自动刷新是否生效。
+
+用法（在容器内，工作目录 /app）：
+    uv run python scripts/verify_oauth_refresh.py            # 只读诊断，安全
+    uv run python scripts/verify_oauth_refresh.py --force    # 真正触发一次刷新
+
+只读模式：列出每个账号的 access_token 剩余有效期、是否带 refresh_token、
+          上次刷新时间与上次刷新错误，判断"有没有料可刷"。
+--force ：对每个带 refresh_token 的账号强制走一次 refresh_access_token(force=True)，
+          直接验证 refresh_token + 本项目 client_id 能否从 OpenAI 换出新 access_token。
+          这会真实轮换 access_token（新 token 有效，不损坏账号）。
+"""
+from __future__ import annotations
+
+import sys
+
+from services.account_service import account_service
+
+
+def _fmt_remaining(seconds: int | None) -> str:
+    if seconds is None:
+        return "无法解析 exp"
+    if seconds <= 0:
+        return f"已过期 {(-seconds) // 3600}h"
+    return f"{seconds // 3600}h{(seconds % 3600) // 60}m 后过期"
+
+
+def diagnose() -> list[str]:
+    """只读：打印每个账号的刷新就绪状态，返回带 refresh_token 的 token 列表。"""
+    tokens = account_service.list_tokens()
+    print(f"账号总数: {len(tokens)}\n")
+    refreshable: list[str] = []
+    for token in tokens:
+        account = account_service.get_account(token) or {}
+        remaining = account_service._token_expires_in(token)
+        has_rt = bool(str(account.get("refresh_token") or "").strip())
+        if has_rt:
+            refreshable.append(token)
+        print(f"- email={account.get('email') or '(未知)'}")
+        print(f"    access_token[:20]   = {token[:20]}...")
+        print(f"    距过期              = {_fmt_remaining(remaining)}")
+        print(f"    refresh_token       = {'有 ✅' if has_rt else '无 ❌（无法自动刷新）'}")
+        print(f"    last_token_refresh_at    = {account.get('last_token_refresh_at')}")
+        print(f"    last_token_refresh_error = {account.get('last_token_refresh_error')}")
+        print()
+    return refreshable
+
+
+def force_refresh(tokens: list[str]) -> None:
+    """对每个账号 force 刷新一次，并对比前后状态判断成败。"""
+    if not tokens:
+        print("没有带 refresh_token 的账号，无法验证刷新。")
+        return
+    print("=" * 60)
+    print(f"开始对 {len(tokens)} 个账号 force 刷新（真实调用 OpenAI）...\n")
+    ok = 0
+    for token in tokens:
+        before = account_service.get_account(token) or {}
+        new_token = account_service.refresh_access_token(token, force=True, event="manual_verify")
+        after = account_service.get_account(new_token) or {}
+        err = str(after.get("last_token_refresh_error") or "").strip()
+        rotated = new_token != token
+        success = bool(new_token) and not err
+        if success:
+            ok += 1
+        print(f"- email={before.get('email') or '(未知)'}")
+        print(f"    旧 access_token[:20] = {token[:20]}...")
+        print(f"    新 access_token[:20] = {new_token[:20]}...")
+        print(f"    token 是否轮换       = {'是' if rotated else '否（exp 未到刷新窗口时可能返回原值）'}")
+        print(f"    last_token_refresh_at    = {after.get('last_token_refresh_at')}")
+        print(f"    last_token_refresh_error = {after.get('last_token_refresh_error') or '无'}")
+        print(f"    >>> 刷新结果         = {'成功 ✅' if success else '失败 ❌'}")
+        print()
+    print("=" * 60)
+    print(f"汇总: {ok}/{len(tokens)} 个账号刷新成功")
+    if ok == len(tokens):
+        print("✅ 自动刷新机制对这些账号完全可用——refresh_token 与 client_id 匹配。")
+    else:
+        print("❌ 有账号刷新失败，看上面的 last_token_refresh_error，或 docker logs 里的 [oauth-login]/refresh 日志。")
+
+
+def main() -> None:
+    do_force = "--force" in sys.argv[1:]
+    refreshable = diagnose()
+    if do_force:
+        force_refresh(refreshable)
+    else:
+        print("提示: 加 --force 参数可真正触发一次刷新以验证能否成功。")
+
+
+if __name__ == "__main__":
+    main()

services/account_service.py

@@ -0,0 +1,1031 @@
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from threading import Condition, Lock
+from typing import Any
+
+from services.config import config
+from services.log_service import (
+    LOG_TYPE_ACCOUNT,
+    log_service,
+)
+from services.storage.base import StorageBackend
+from utils.helper import anonymize_token
+
+
+class AccountService:
+    """账号池服务，使用 token -> account 的 dict 保存账号。"""
+
+    _NEW_ACCOUNT_INVALID_GRACE_SECONDS = 10 * 60
+    _INVALID_CONFIRM_SECONDS = 30
+    _ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 24 * 60 * 60
+    _REFRESH_TOKEN_KEEPALIVE_SECONDS = 3 * 24 * 60 * 60
+    _REFRESH_TOKEN_KEEPALIVE_ERROR_BACKOFF_SECONDS = 6 * 60 * 60
+    _REFRESH_TOKEN_KEEPALIVE_BATCH_SIZE = 3
+    _TOKEN_REFRESH_ERROR_BACKOFF_SECONDS = 5 * 60
+    _OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token"
+    _OAUTH_CLIENT_ID = "app_2SKx67EdpoN0G6j64rFvigXD"
+    _OAUTH_USER_AGENT = (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/145.0.0.0 Safari/537.36"
+    )
+
+    def __init__(self, storage_backend: StorageBackend):
+        self.storage = storage_backend
+        self._lock = Lock()
+        self._token_refresh_lock = Lock()
+        self._image_slot_condition = Condition(self._lock)
+        self._index = 0
+        self._accounts = self._load_accounts()
+        self._image_inflight: dict[str, int] = {}
+        self._token_aliases: dict[str, str] = {}
+        self._cumulative_total = self._load_cumulative_total()
+
+    def _get_cumulative_file(self) -> Path:
+        from services.config import DATA_DIR
+        return DATA_DIR / ".cumulative_total"
+
+    def _load_cumulative_total(self) -> int:
+        try:
+            f = self._get_cumulative_file()
+            if f.exists():
+                return int(f.read_text().strip())
+        except Exception:
+            pass
+        return len(self._accounts)
+
+    def _save_cumulative_total(self) -> None:
+        try:
+            self._get_cumulative_file().write_text(str(self._cumulative_total))
+        except Exception:
+            pass
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+    @staticmethod
+    def _decode_jwt_payload(token: str) -> dict:
+        try:
+            payload = str(token or "").split(".")[1]
+            payload += "=" * ((4 - len(payload) % 4) % 4)
+            import base64
+            import json
+            data = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")))
+            return data if isinstance(data, dict) else {}
+        except Exception:
+            return {}
+
+    @staticmethod
+    def _parse_time(value: object) -> datetime | None:
+        raw = str(value or "").strip()
+        if not raw:
+            return None
+        try:
+            parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        except Exception:
+            try:
+                parsed = datetime.strptime(raw, "%Y-%m-%d %H:%M:%S")
+            except Exception:
+                return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc)
+
+    @staticmethod
+    def _timestamp_to_iso(value: object) -> str:
+        try:
+            ts = int(value)
+        except (TypeError, ValueError):
+            return ""
+        tz = timezone(timedelta(hours=8))
+        return datetime.fromtimestamp(ts, tz=timezone.utc).astimezone(tz).isoformat()
+
+    def _load_accounts(self) -> dict[str, dict]:
+        accounts = self.storage.load_accounts()
+        return {
+            normalized["access_token"]: normalized
+            for item in accounts
+            if (normalized := self._normalize_account(item)) is not None
+        }
+
+    def _save_accounts(self) -> None:
+        self.storage.save_accounts(list(self._accounts.values()))
+
+    @staticmethod
+    def _is_image_account_available(account: dict) -> bool:
+        if not isinstance(account, dict):
+            return False
+        if account.get("status") in {"禁用", "限流", "异常"}:
+            return False
+        if bool(account.get("image_quota_unknown")):
+            return True
+        return int(account.get("quota") or 0) > 0
+
+    @classmethod
+    def _account_matches_plan_type(cls, account: dict, plan_type: str | None = None) -> bool:
+        if not plan_type:
+            return True
+        normalized_plan = cls._normalize_account_type(plan_type)
+        normalized_account = cls._normalize_account_type(account.get("type"))
+        if not normalized_plan or not normalized_account:
+            return False
+        return normalized_plan.lower() == normalized_account.lower()
+
+    @classmethod
+    def _account_matches_source_type(cls, account: dict, source_type: str | None = None) -> bool:
+        if not source_type:
+            return True
+        return cls._normalize_source_type(account.get("source_type")) == cls._normalize_source_type(source_type)
+
+    @classmethod
+    def _account_matches_any_plan_type(cls, account: dict, plan_types: set[str] | tuple[str, ...] | None = None) -> bool:
+        if not plan_types:
+            return True
+        normalized_account = cls._normalize_account_type(account.get("type"))
+        normalized_plans = {
+            normalized
+            for plan_type in plan_types
+            if (normalized := cls._normalize_account_type(plan_type))
+        }
+        return bool(normalized_account and normalized_account in normalized_plans)
+
+    @staticmethod
+    def _normalize_source_type(value: object) -> str:
+        return str(value or "web").strip().lower() or "web"
+
+    @staticmethod
+    def _normalize_account_type(value: object) -> str | None:
+        raw = str(value or "").strip()
+        if not raw:
+            return None
+        key = raw.lower().replace("-", "_").replace(" ", "_")
+        compact = key.replace("_", "")
+        aliases = {
+            "free": "free",
+            "plus": "Plus",
+            "pro": "Pro",
+            "prolite": "ProLite",
+            "team": "Team",
+            "business": "Team",
+            "enterprise": "Enterprise",
+        }
+        return aliases.get(compact) or aliases.get(key) or raw
+
+    def _search_account_type(self, payload: object) -> str | None:
+        if isinstance(payload, dict):
+            for key in ("plan_type", "account_plan", "account_type", "subscription_type", "type"):
+                plan = self._normalize_account_type(payload.get(key))
+                if plan:
+                    return plan
+            for value in payload.values():
+                plan = self._search_account_type(value)
+                if plan:
+                    return plan
+        elif isinstance(payload, list):
+            for value in payload:
+                plan = self._search_account_type(value)
+                if plan:
+                    return plan
+        return None
+
+    def _normalize_account(self, item: dict) -> dict | None:
+        if not isinstance(item, dict):
+            return None
+        access_token = item.get("access_token") or item.get("accessToken") or ""
+        if not access_token:
+            return None
+        normalized = dict(item)
+        normalized.pop("accessToken", None)
+        normalized["access_token"] = access_token
+        if str(normalized.get("type") or "").strip().lower() == "codex":
+            normalized["export_type"] = "codex"
+            normalized.pop("type", None)
+        normalized["type"] = normalized.get("type") or "free"
+        normalized["status"] = normalized.get("status") or "正常"
+        normalized["quota"] = max(0, int(normalized.get("quota") if normalized.get("quota") is not None else 0))
+        normalized["image_quota_unknown"] = bool(normalized.get("image_quota_unknown"))
+        normalized["email"] = normalized.get("email") or None
+        normalized["user_id"] = normalized.get("user_id") or None
+        normalized["proxy"] = str(normalized.get("proxy") or "").strip()
+        source_type = normalized.get("source_type")
+        if not source_type and str(normalized.get("export_type") or "").strip().lower() == "codex":
+            source_type = "codex"
+        normalized["source_type"] = self._normalize_source_type(source_type)
+        limits_progress = normalized.get("limits_progress")
+        normalized["limits_progress"] = limits_progress if isinstance(limits_progress, list) else []
+        normalized["default_model_slug"] = normalized.get("default_model_slug") or None
+        normalized["restore_at"] = normalized.get("restore_at") or None
+        normalized["success"] = int(normalized.get("success") or 0)
+        normalized["fail"] = int(normalized.get("fail") or 0)
+        normalized["invalid_count"] = int(normalized.get("invalid_count") or 0)
+        normalized["last_used_at"] = normalized.get("last_used_at")
+        normalized["last_invalid_at"] = normalized.get("last_invalid_at") or None
+        normalized["last_refresh_error"] = normalized.get("last_refresh_error") or None
+        normalized["last_refresh_error_at"] = normalized.get("last_refresh_error_at") or None
+        normalized["last_token_refresh_at"] = normalized.get("last_token_refresh_at") or None
+        normalized["last_token_refresh_error"] = normalized.get("last_token_refresh_error") or None
+        normalized["last_token_refresh_error_at"] = normalized.get("last_token_refresh_error_at") or None
+        normalized["created_at"] = normalized.get("created_at") or AccountService._now()
+        return normalized
+
+    @staticmethod
+    def _jwt_exp(access_token: str) -> int:
+        try:
+            return int(AccountService._decode_jwt_payload(access_token).get("exp") or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    @classmethod
+    def _token_expires_in(cls, access_token: str) -> int | None:
+        exp = cls._jwt_exp(access_token)
+        if exp <= 0:
+            return None
+        return exp - int(time.time())
+
+    @classmethod
+    def _token_needs_refresh(cls, access_token: str, *, force: bool = False) -> bool:
+        if force:
+            return True
+        remaining = cls._token_expires_in(access_token)
+        return remaining is not None and remaining <= cls._ACCESS_TOKEN_REFRESH_SKEW_SECONDS
+
+    @classmethod
+    def _token_issued_at(cls, access_token: str) -> datetime | None:
+        try:
+            iat = int(cls._decode_jwt_payload(access_token).get("iat") or 0)
+        except (TypeError, ValueError):
+            return None
+        if iat <= 0:
+            return None
+        return datetime.fromtimestamp(iat, tz=timezone.utc)
+
+    @staticmethod
+    def _safe_response_text(response: object, limit: int = 300) -> str:
+        try:
+            return str(getattr(response, "text", "") or "")[:limit]
+        except Exception:
+            return ""
+
+    def _resolve_access_token_locked(self, access_token: str) -> str:
+        token = str(access_token or "").strip()
+        seen: set[str] = set()
+        while token and token not in self._accounts and token in self._token_aliases and token not in seen:
+            seen.add(token)
+            token = self._token_aliases.get(token, token)
+        return token
+
+    def resolve_access_token(self, access_token: str) -> str:
+        if not access_token:
+            return ""
+        with self._lock:
+            return self._resolve_access_token_locked(access_token)
+
+    def _get_account_for_token(self, access_token: str) -> tuple[str, dict | None]:
+        with self._lock:
+            resolved = self._resolve_access_token_locked(access_token)
+            account = self._accounts.get(resolved)
+            return resolved, dict(account) if account else None
+
+    def _record_token_refresh_error(self, access_token: str, event: str, error: str) -> None:
+        now = datetime.now(timezone.utc).isoformat()
+        with self._lock:
+            resolved = self._resolve_access_token_locked(access_token)
+            current = self._accounts.get(resolved)
+            if current is None:
+                return
+            next_item = dict(current)
+            next_item["last_token_refresh_error"] = str(error or "refresh token failed")
+            next_item["last_token_refresh_error_at"] = now
+            account = self._normalize_account(next_item)
+            if account is not None:
+                self._accounts[resolved] = account
+                self._save_accounts()
+        log_service.add(
+            LOG_TYPE_ACCOUNT,
+            "refresh_token 刷新 access_token 失败",
+            {"source": event, "token": anonymize_token(access_token), "error": str(error or "")},
+        )
+
+    def _recent_token_refresh_error(self, account: dict) -> bool:
+        last_error_at = self._parse_time(account.get("last_token_refresh_error_at"))
+        if last_error_at is None:
+            return False
+        return (datetime.now(timezone.utc) - last_error_at).total_seconds() < self._TOKEN_REFRESH_ERROR_BACKOFF_SECONDS
+
+    def _recent_refresh_token_keepalive_error(self, account: dict, now: datetime) -> bool:
+        last_error_at = self._parse_time(account.get("last_token_refresh_error_at"))
+        if last_error_at is None:
+            return False
+        return (now - last_error_at).total_seconds() < self._REFRESH_TOKEN_KEEPALIVE_ERROR_BACKOFF_SECONDS
+
+    def _refresh_token_keepalive_anchor(self, account: dict) -> datetime | None:
+        return (
+            self._parse_time(account.get("last_token_refresh_at"))
+            or self._token_issued_at(str(account.get("access_token") or ""))
+            or self._parse_time(account.get("created_at"))
+        )
+
+    def _refresh_token_keepalive_due_at(self, account: dict, now: datetime) -> datetime | None:
+        if not str(account.get("refresh_token") or "").strip():
+            return None
+        if account.get("status") == "禁用":
+            return None
+        if self._recent_refresh_token_keepalive_error(account, now):
+            return None
+        anchor = self._refresh_token_keepalive_anchor(account)
+        if anchor is None:
+            return now
+        due_at = anchor + timedelta(seconds=self._REFRESH_TOKEN_KEEPALIVE_SECONDS)
+        return due_at if due_at <= now else None
+
+    def _request_access_token_refresh(self, refresh_token: str, account: dict | None = None) -> dict[str, str]:
+        from curl_cffi import requests
+        from services.proxy_service import proxy_settings
+
+        session = requests.Session(**proxy_settings.build_session_kwargs(account=account, impersonate="chrome", verify=True))
+        try:
+            response = session.post(
+                self._OAUTH_TOKEN_URL,
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "User-Agent": self._OAUTH_USER_AGENT,
+                },
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": refresh_token,
+                    "client_id": self._OAUTH_CLIENT_ID,
+                },
+                timeout=60,
+            )
+            data = response.json() if response.text else {}
+            if response.status_code != 200 or not isinstance(data, dict) or not data.get("access_token"):
+                detail = ""
+                if isinstance(data, dict):
+                    detail = str(data.get("error_description") or data.get("error") or data.get("message") or "")
+                detail = detail or self._safe_response_text(response)
+                raise RuntimeError(f"oauth_refresh_http_{response.status_code}{': ' + detail if detail else ''}")
+            return {
+                "access_token": str(data.get("access_token") or "").strip(),
+                "refresh_token": str(data.get("refresh_token") or refresh_token).strip(),
+                "id_token": str(data.get("id_token") or "").strip(),
+            }
+        finally:
+            session.close()
+
+    def _apply_refreshed_tokens(self, old_access_token: str, token_data: dict, event: str) -> str:
+        now = datetime.now(timezone.utc).isoformat()
+        with self._image_slot_condition:
+            old_token = self._resolve_access_token_locked(old_access_token)
+            current = self._accounts.get(old_token)
+            if current is None:
+                return old_token
+            new_token = str(token_data.get("access_token") or old_token).strip()
+            if not new_token:
+                return old_token
+
+            next_item = dict(current)
+            next_item["access_token"] = new_token
+            if token_data.get("refresh_token"):
+                next_item["refresh_token"] = str(token_data.get("refresh_token") or "").strip()
+            if token_data.get("id_token"):
+                next_item["id_token"] = str(token_data.get("id_token") or "").strip()
+            next_item["last_token_refresh_at"] = now
+            next_item["last_token_refresh_error"] = None
+            next_item["last_token_refresh_error_at"] = None
+            next_item["invalid_count"] = 0
+            next_item["last_invalid_at"] = None
+            next_item["last_refresh_error"] = None
+            next_item["last_refresh_error_at"] = None
+
+            account = self._normalize_account(next_item)
+            if account is None:
+                return old_token
+
+            rotated = new_token != old_token
+            if rotated:
+                self._accounts.pop(old_token, None)
+                self._token_aliases[old_token] = new_token
+                old_inflight = int(self._image_inflight.pop(old_token, 0))
+                if old_inflight:
+                    self._image_inflight[new_token] = int(self._image_inflight.get(new_token, 0)) + old_inflight
+            self._accounts[new_token] = account
+            self._save_accounts()
+            self._image_slot_condition.notify_all()
+
+        log_service.add(
+            LOG_TYPE_ACCOUNT,
+            "refresh_token 已刷新 access_token",
+            {"source": event, "token": anonymize_token(new_token), "rotated": rotated},
+        )
+        return new_token
+
+    def refresh_access_token(self, access_token: str, *, force: bool = False, event: str = "refresh_access_token") -> str:
+        if not access_token:
+            return ""
+        with self._token_refresh_lock:
+            resolved_token, account = self._get_account_for_token(access_token)
+            if not account:
+                return access_token
+            active_token = str(account.get("access_token") or resolved_token or access_token)
+            if not self._token_needs_refresh(active_token, force=force):
+                return active_token
+            refresh_token = str(account.get("refresh_token") or "").strip()
+            if not refresh_token:
+                return active_token
+            if not force and self._recent_token_refresh_error(account):
+                return active_token
+            try:
+                token_data = self._request_access_token_refresh(refresh_token, account)
+            except Exception as exc:
+                self._record_token_refresh_error(active_token, event, str(exc))
+                return active_token
+            return self._apply_refreshed_tokens(active_token, token_data, event)
+
+    def list_expiring_access_tokens(self) -> list[str]:
+        with self._lock:
+            return [
+                token
+                for account in self._accounts.values()
+                if str(account.get("refresh_token") or "").strip()
+                and (token := str(account.get("access_token") or "").strip())
+                and self._token_needs_refresh(token)
+            ]
+
+    def list_refresh_token_keepalive_tokens(self) -> list[str]:
+        now = datetime.now(timezone.utc)
+        due_items: list[tuple[datetime, str]] = []
+        with self._lock:
+            for account in self._accounts.values():
+                due_at = self._refresh_token_keepalive_due_at(account, now)
+                token = str(account.get("access_token") or "").strip()
+                if due_at is not None and token:
+                    due_items.append((due_at, token))
+        due_items.sort(key=lambda item: item[0])
+        return [token for _, token in due_items[: self._REFRESH_TOKEN_KEEPALIVE_BATCH_SIZE]]
+
+    def keepalive_refresh_tokens(self, access_tokens: list[str]) -> dict[str, Any]:
+        access_tokens = list(dict.fromkeys(token for token in access_tokens if token))
+        if not access_tokens:
+            return {"refreshed": 0, "errors": [], "items": self.list_accounts()}
+
+        refreshed = 0
+        errors = []
+        for access_token in access_tokens:
+            before = self.resolve_access_token(access_token)
+            after = self.refresh_access_token(before, force=True, event="refresh_token_keepalive")
+            account = self.get_account(after)
+            if account and str(account.get("last_token_refresh_error") or "").strip():
+                errors.append({
+                    "token": anonymize_token(before),
+                    "error": str(account.get("last_token_refresh_error") or "refresh token failed"),
+                })
+                continue
+            if account:
+                refreshed += 1
+
+        return {
+            "refreshed": refreshed,
+            "errors": errors,
+            "items": self.list_accounts(),
+        }
+
+    def list_tokens(self) -> list[str]:
+        with self._lock:
+            return list(self._accounts)
+
+    def _list_ready_candidate_tokens(
+            self,
+            excluded_tokens: set[str] | None = None,
+            plan_type: str | None = None,
+            source_type: str | None = None,
+            plan_types: set[str] | tuple[str, ...] | None = None,
+    ) -> list[str]:
+        excluded = set(excluded_tokens or set())
+        return [
+            token
+            for item in self._accounts.values()
+            if self._is_image_account_available(item)
+               and self._account_matches_plan_type(item, plan_type)
+               and self._account_matches_any_plan_type(item, plan_types)
+               and self._account_matches_source_type(item, source_type)
+               and (token := item.get("access_token") or "")
+               and token not in excluded
+        ]
+
+    def _list_available_candidate_tokens(
+            self,
+            excluded_tokens: set[str] | None = None,
+            plan_type: str | None = None,
+            source_type: str | None = None,
+            plan_types: set[str] | tuple[str, ...] | None = None,
+    ) -> list[str]:
+        max_concurrency = max(1, int(config.image_account_concurrency or 1))
+        return [
+            token
+            for token in self._list_ready_candidate_tokens(excluded_tokens, plan_type, source_type, plan_types)
+            if int(self._image_inflight.get(token, 0)) < max_concurrency
+        ]
+
+    def _acquire_next_candidate_token(
+            self,
+            excluded_tokens: set[str] | None = None,
+            plan_type: str | None = None,
+            source_type: str | None = None,
+            plan_types: set[str] | tuple[str, ...] | None = None,
+    ) -> str:
+        with self._image_slot_condition:
+            while True:
+                if not self._list_ready_candidate_tokens(excluded_tokens, plan_type, source_type, plan_types):
+                    raise RuntimeError(
+                        f"no available {plan_type or source_type or ''} image quota".replace("  ", " ").strip()
+                        if plan_type or source_type else "no available image quota"
+                    )
+                tokens = self._list_available_candidate_tokens(excluded_tokens, plan_type, source_type, plan_types)
+                if tokens:
+                    access_token = tokens[self._index % len(tokens)]
+                    self._index += 1
+                    self._image_inflight[access_token] = int(self._image_inflight.get(access_token, 0)) + 1
+                    return access_token
+                self._image_slot_condition.wait(timeout=1.0)
+
+    def release_image_slot(self, access_token: str) -> None:
+        if not access_token:
+            return
+        with self._image_slot_condition:
+            access_token = self._resolve_access_token_locked(access_token)
+            current_inflight = int(self._image_inflight.get(access_token, 0))
+            if current_inflight <= 1:
+                self._image_inflight.pop(access_token, None)
+            else:
+                self._image_inflight[access_token] = current_inflight - 1
+            self._image_slot_condition.notify_all()
+
+    def get_available_access_token(
+            self,
+            plan_type: str | None = None,
+            source_type: str | None = None,
+            plan_types: set[str] | tuple[str, ...] | None = None,
+    ) -> str:
+        attempted_tokens: set[str] = set()
+        while True:
+            access_token = self._acquire_next_candidate_token(
+                excluded_tokens=attempted_tokens,
+                plan_type=plan_type,
+                source_type=source_type,
+                plan_types=plan_types,
+            )
+            attempted_tokens.add(access_token)
+            try:
+                account = self.fetch_remote_info(access_token, "get_available_access_token")
+            except Exception:
+                self.release_image_slot(access_token)
+                continue
+            if (
+                    self._is_image_account_available(account or {})
+                    and self._account_matches_plan_type(account or {}, plan_type)
+                    and self._account_matches_any_plan_type(account or {}, plan_types)
+                    and self._account_matches_source_type(account or {}, source_type)
+            ):
+                return str((account or {}).get("access_token") or access_token)
+            self.release_image_slot(access_token)
+
+    def get_text_access_token(self, excluded_tokens: set[str] | None = None) -> str:
+        excluded = set(excluded_tokens or set())
+        with self._lock:
+            candidates = [
+                token
+                for account in self._accounts.values()
+                if account.get("status") not in {"禁用", "异常"}
+                   and (token := account.get("access_token") or "")
+                   and token not in excluded
+            ]
+            if not candidates:
+                return ""
+            access_token = candidates[self._index % len(candidates)]
+            self._index += 1
+        return self.refresh_access_token(access_token, event="get_text_access_token") or access_token
+
+    def mark_text_used(self, access_token: str) -> None:
+        if not access_token:
+            return
+        with self._lock:
+            access_token = self._resolve_access_token_locked(access_token)
+            current = self._accounts.get(access_token)
+            if current is None:
+                return
+            next_item = dict(current)
+            next_item["last_used_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            account = self._normalize_account(next_item)
+            if account is None:
+                return
+            self._accounts[access_token] = account
+            self._save_accounts()
+
+    def remove_invalid_token(self, access_token: str, event: str) -> bool:
+        if not config.auto_remove_invalid_accounts:
+            self.update_account(access_token, {"status": "异常", "quota": 0})
+            return False
+        removed = bool(self.delete_accounts([access_token])["removed"])
+        if removed:
+            log_service.add(LOG_TYPE_ACCOUNT, "自动移除异常账号",
+                            {"source": event, "token": anonymize_token(access_token)})
+        elif access_token:
+            self.update_account(access_token, {"status": "异常", "quota": 0})
+        return removed
+
+    def get_account(self, access_token: str) -> dict | None:
+        if not access_token:
+            return None
+        with self._lock:
+            access_token = self._resolve_access_token_locked(access_token)
+            account = self._accounts.get(access_token)
+            return dict(account) if account else None
+
+    def list_accounts(self) -> list[dict]:
+        with self._lock:
+            return [dict(item) for item in self._accounts.values()]
+
+    def list_limited_tokens(self) -> list[str]:
+        with self._lock:
+            return [
+                token
+                for item in self._accounts.values()
+                if item.get("status") == "限流"
+                   and (token := item.get("access_token") or "")
+            ]
+
+    @staticmethod
+    def _account_payload_token(item: dict) -> str:
+        return str(item.get("access_token") or item.get("accessToken") or "").strip()
+
+    @staticmethod
+    def _prepare_account_payload(item: dict) -> dict | None:
+        if not isinstance(item, dict):
+            return None
+        access_token = AccountService._account_payload_token(item)
+        if not access_token:
+            return None
+        payload = dict(item)
+        payload.pop("accessToken", None)
+        payload["access_token"] = access_token
+        # CPA/Codex 导出文件里的 `type=codex` 是导出格式，不是号池套餐类型。
+        if str(payload.get("type") or "").strip().lower() == "codex":
+            payload["export_type"] = "codex"
+            payload["source_type"] = "codex"
+            payload.pop("type", None)
+        if str(payload.get("export_type") or "").strip().lower() == "codex":
+            payload["source_type"] = "codex"
+        if payload.get("plan_type") and not payload.get("type"):
+            payload["type"] = str(payload.get("plan_type") or "").strip()
+        return payload
+
+    def add_account_items(self, items: list[dict]) -> dict:
+        payloads = [
+            payload
+            for item in items
+            if (payload := self._prepare_account_payload(item)) is not None
+        ]
+        return self._add_account_payloads(payloads)
+
+    def add_accounts(self, tokens: list[str], source_type: str = "web") -> dict:
+        tokens = list(dict.fromkeys(token for token in tokens if token))
+        if not tokens:
+            return {"added": 0, "skipped": 0, "items": self.list_accounts()}
+        return self._add_account_payloads([
+            {"access_token": token, "source_type": self._normalize_source_type(source_type)}
+            for token in tokens
+        ])
+
+    def _add_account_payloads(self, payloads: list[dict]) -> dict:
+        deduped: dict[str, dict] = {}
+        for payload in payloads:
+            if not isinstance(payload, dict):
+                continue
+            access_token = self._account_payload_token(payload)
+            if not access_token:
+                continue
+            current = deduped.get(access_token, {})
+            deduped[access_token] = {**current, **payload, "access_token": access_token}
+
+        if not deduped:
+            return {"added": 0, "skipped": 0, "items": self.list_accounts()}
+
+        with self._lock:
+            added = 0
+            skipped = 0
+            for access_token, payload in deduped.items():
+                current = self._accounts.get(access_token)
+                if current is None:
+                    added += 1
+                    self._cumulative_total += 1
+                    self._save_cumulative_total()
+                    current = {"created_at": self._now()}
+                else:
+                    skipped += 1
+                incoming = dict(payload)
+                if not incoming.get("created_at"):
+                    incoming.pop("created_at", None)
+                account = self._normalize_account(
+                    {
+                        **current,
+                        **incoming,
+                        "access_token": access_token,
+                        "type": str(incoming.get("type") or current.get("type") or "free"),
+                    }
+                )
+                if account is not None:
+                    self._accounts[access_token] = account
+            self._save_accounts()
+            items = [dict(item) for item in self._accounts.values()]
+            log_service.add(LOG_TYPE_ACCOUNT, f"新增 {added} 个账号，跳过 {skipped} 个",
+                            {"added": added, "skipped": skipped})
+        return {"added": added, "skipped": skipped, "items": items}
+
+    def delete_accounts(self, tokens: list[str]) -> dict:
+        target_set = set(token for token in tokens if token)
+        if not target_set:
+            return {"removed": 0, "items": self.list_accounts()}
+        with self._lock:
+            target_set = {self._resolve_access_token_locked(token) for token in target_set if token}
+            removed = sum(self._accounts.pop(token, None) is not None for token in target_set)
+            for token in target_set:
+                self._image_inflight.pop(token, None)
+            self._token_aliases = {
+                old: new
+                for old, new in self._token_aliases.items()
+                if old not in target_set and new not in target_set
+            }
+            if removed:
+                if self._accounts:
+                    self._index %= len(self._accounts)
+                else:
+                    self._index = 0
+                self._save_accounts()
+                log_service.add(LOG_TYPE_ACCOUNT, f"删除 {removed} 个账号", {"removed": removed})
+            items = [dict(item) for item in self._accounts.values()]
+        return {"removed": removed, "items": items}
+
+    def update_account(self, access_token: str, updates: dict) -> dict | None:
+        if not access_token:
+            return None
+        with self._lock:
+            access_token = self._resolve_access_token_locked(access_token)
+            current = self._accounts.get(access_token)
+            if current is None:
+                return None
+            account = self._normalize_account({**current, **updates, "access_token": access_token})
+            if account is None:
+                return None
+            if account.get("status") == "限流" and config.auto_remove_rate_limited_accounts:
+                self._accounts.pop(access_token, None)
+                self._save_accounts()
+                log_service.add(LOG_TYPE_ACCOUNT, "自动移除限流账号", {"token": anonymize_token(access_token)})
+                return None
+            self._accounts[access_token] = account
+            self._save_accounts()
+            log_service.add(LOG_TYPE_ACCOUNT, "更新账号",
+                            {"token": anonymize_token(access_token), "status": account.get("status")})
+            return dict(account)
+        return None
+
+    def _record_refresh_success(self, access_token: str) -> None:
+        with self._lock:
+            access_token = self._resolve_access_token_locked(access_token)
+            current = self._accounts.get(access_token)
+            if current is None:
+                return
+            next_item = dict(current)
+            next_item["invalid_count"] = 0
+            next_item["last_invalid_at"] = None
+            next_item["last_refresh_error"] = None
+            next_item["last_refresh_error_at"] = None
+            account = self._normalize_account(next_item)
+            if account is not None:
+                self._accounts[access_token] = account
+
+    def _should_defer_invalid_token(self, account: dict | None, now: datetime) -> bool:
+        if not isinstance(account, dict):
+            return False
+        created_at = self._parse_time(account.get("created_at"))
+        if created_at is not None and (now - created_at).total_seconds() < self._NEW_ACCOUNT_INVALID_GRACE_SECONDS:
+            return True
+        last_invalid_at = self._parse_time(account.get("last_invalid_at"))
+        invalid_count = int(account.get("invalid_count") or 0)
+        if invalid_count <= 1:
+            return True
+        if last_invalid_at is not None and (now - last_invalid_at).total_seconds() < self._INVALID_CONFIRM_SECONDS:
+            return True
+        return False
+
+    def _record_invalid_token_seen(self, access_token: str, event: str, error: str) -> bool:
+        now = datetime.now(timezone.utc)
+        with self._lock:
+            access_token = self._resolve_access_token_locked(access_token)
+            current = self._accounts.get(access_token)
+            if current is None:
+                return True
+            should_defer = self._should_defer_invalid_token(current, now)
+            next_item = dict(current)
+            next_item["invalid_count"] = int(next_item.get("invalid_count") or 0) + 1
+            next_item["last_invalid_at"] = now.isoformat()
+            next_item["last_refresh_error"] = str(error or "invalid access token")
+            next_item["last_refresh_error_at"] = now.isoformat()
+            account = self._normalize_account(next_item)
+            if account is not None:
+                self._accounts[access_token] = account
+                self._save_accounts()
+            if should_defer:
+                log_service.add(
+                    LOG_TYPE_ACCOUNT,
+                    "暂缓标记异常账号",
+                    {"source": event, "token": anonymize_token(access_token), "error": str(error or "")},
+                )
+                return False
+        return True
+
+    def mark_image_result(self, access_token: str, success: bool) -> dict | None:
+        if not access_token:
+            return None
+        self.release_image_slot(access_token)
+        with self._lock:
+            access_token = self._resolve_access_token_locked(access_token)
+            current = self._accounts.get(access_token)
+            if current is None:
+                return None
+            next_item = dict(current)
+            next_item["last_used_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            image_quota_unknown = bool(next_item.get("image_quota_unknown"))
+            if success:
+                next_item["success"] = int(next_item.get("success") or 0) + 1
+                if not image_quota_unknown:
+                    next_item["quota"] = max(0, int(next_item.get("quota") or 0) - 1)
+                if not image_quota_unknown and next_item["quota"] == 0:
+                    next_item["status"] = "限流"
+                    next_item["restore_at"] = next_item.get("restore_at") or None
+                elif next_item.get("status") == "限流":
+                    next_item["status"] = "正常"
+            else:
+                next_item["fail"] = int(next_item.get("fail") or 0) + 1
+            account = self._normalize_account(next_item)
+            if account is None:
+                return None
+            if account.get("status") == "限流" and config.auto_remove_rate_limited_accounts:
+                self._accounts.pop(access_token, None)
+                self._save_accounts()
+                log_service.add(LOG_TYPE_ACCOUNT, "自动移除限流账号", {"token": anonymize_token(access_token)})
+                return None
+            self._accounts[access_token] = account
+            self._save_accounts()
+            return dict(account)
+        return None
+
+    def fetch_remote_info(self, access_token: str, event: str = "fetch_remote_info") -> dict[str, Any] | None:
+        if not access_token:
+            raise ValueError("access_token is required")
+
+        active_token = self.refresh_access_token(access_token, event=f"{event}:preflight") or access_token
+        try:
+            from services.openai_backend_api import InvalidAccessTokenError, OpenAIBackendAPI
+            result = OpenAIBackendAPI(active_token).get_user_info()
+        except InvalidAccessTokenError as exc:
+            refreshed_token = self.refresh_access_token(active_token, force=True, event=f"{event}:invalid_access_token")
+            if refreshed_token and refreshed_token != active_token:
+                try:
+                    result = OpenAIBackendAPI(refreshed_token).get_user_info()
+                except InvalidAccessTokenError as retry_exc:
+                    if self._record_invalid_token_seen(refreshed_token, event, str(retry_exc)):
+                        self.remove_invalid_token(refreshed_token, event)
+                    raise
+                active_token = refreshed_token
+            else:
+                if self._record_invalid_token_seen(active_token, event, str(exc)):
+                    self.remove_invalid_token(active_token, event)
+                raise
+        self._record_refresh_success(active_token)
+        return self.update_account(active_token, result)
+
+    def refresh_accounts(self, access_tokens: list[str]) -> dict[str, Any]:
+        access_tokens = list(dict.fromkeys(token for token in access_tokens if token))
+        if not access_tokens:
+            return {"refreshed": 0, "errors": [], "items": self.list_accounts()}
+
+        refreshed = 0
+        errors = []
+        max_workers = min(10, len(access_tokens))
+
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {
+                executor.submit(self.fetch_remote_info, token, "refresh_accounts"): token
+                for token in access_tokens
+            }
+            for future in as_completed(futures):
+                try:
+                    account = future.result()
+                except Exception as exc:
+                    errors.append({"token": anonymize_token(futures[future]), "error": str(exc)})
+                    continue
+                if account is not None:
+                    refreshed += 1
+
+        return {
+            "refreshed": refreshed,
+            "errors": errors,
+            "items": self.list_accounts(),
+        }
+
+    def build_export_items(self, access_tokens: list[str] | None = None) -> list[dict[str, str]]:
+        target_tokens = set(token for token in (access_tokens or []) if token)
+        with self._lock:
+            accounts = [
+                dict(item)
+                for item in self._accounts.values()
+                if not target_tokens or str(item.get("access_token") or "") in target_tokens
+            ]
+
+        items: list[dict[str, str]] = []
+        for account in accounts:
+            access_token = str(account.get("access_token") or "").strip()
+            refresh_token = str(account.get("refresh_token") or "").strip()
+            id_token = str(account.get("id_token") or "").strip()
+            if not access_token or not refresh_token or not id_token:
+                continue
+
+            access_payload = self._decode_jwt_payload(access_token)
+            id_payload = self._decode_jwt_payload(id_token)
+            auth_claim = access_payload.get("https://api.openai.com/auth")
+            auth_claim = auth_claim if isinstance(auth_claim, dict) else {}
+            profile_claim = access_payload.get("https://api.openai.com/profile")
+            profile_claim = profile_claim if isinstance(profile_claim, dict) else {}
+
+            email = (
+                str(account.get("email") or "").strip()
+                or str(profile_claim.get("email") or "").strip()
+                or str(id_payload.get("email") or "").strip()
+            )
+            account_id = (
+                str(account.get("account_id") or "").strip()
+                or str(auth_claim.get("chatgpt_account_id") or "").strip()
+                or str(account.get("user_id") or "").strip()
+            )
+            item = {
+                "type": str(account.get("export_type") or "codex"),
+                "email": email,
+                "account_id": account_id,
+                "access_token": access_token,
+                "refresh_token": refresh_token,
+                "id_token": id_token,
+                "expired": self._timestamp_to_iso(access_payload.get("exp")),
+                "last_refresh": self._timestamp_to_iso(access_payload.get("iat")),
+            }
+            password = str(account.get("password") or "").strip()
+            if password:
+                item["password"] = password
+            items.append(item)
+        return items
+
+    def get_stats(self) -> dict:
+        with self._lock:
+            items = list(self._accounts.values())
+        total = len(items)
+        active = sum(1 for a in items if a.get("status") == "正常")
+        limited = sum(1 for a in items if a.get("status") == "限流")
+        abnormal = sum(1 for a in items if a.get("status") == "异常")
+        disabled = sum(1 for a in items if a.get("status") == "禁用")
+        total_quota = sum(max(0, int(a.get("quota") or 0)) for a in items if a.get("status") == "正常")
+        unlimited = sum(1 for a in items if a.get("status") == "正常" and bool(a.get("image_quota_unknown")))
+        total_success = sum(int(a.get("success") or 0) for a in items)
+        total_fail = sum(int(a.get("fail") or 0) for a in items)
+        by_type = {}
+        for a in items:
+            t = a.get("type", "unknown")
+            by_type[t] = by_type.get(t, 0) + 1
+        return {
+            "total": total,
+            "cumulative_total": self._cumulative_total,
+            "active": active,
+            "limited": limited,
+            "abnormal": abnormal,
+            "disabled": disabled,
+            "total_quota": total_quota,
+            "unlimited_quota_count": unlimited,
+            "total_success": total_success,
+            "total_fail": total_fail,
+            "by_type": by_type,
+        }
+
+    def account_health(self) -> dict:
+        stats = self.get_stats()
+        return {
+            "healthy": stats["active"] > 0 or stats["unlimited_quota_count"] > 0,
+            "status": "ok" if stats["active"] > 0 else "degraded",
+            **stats,
+        }
+
+
+account_service = AccountService(config.get_storage_backend())

services/auth_service.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import uuid
+from datetime import datetime, timezone
+from threading import Lock
+from typing import Literal
+
+from services.config import config
+from services.storage.base import StorageBackend
+
+AuthRole = Literal["admin", "user"]
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _hash_key(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+class AuthService:
+    def __init__(self, storage: StorageBackend):
+        self.storage = storage
+        self._lock = Lock()
+        self._items = self._load()
+        self._last_used_flush_at: dict[str, datetime] = {}
+
+    @staticmethod
+    def _clean(value: object) -> str:
+        return str(value or "").strip()
+
+    @staticmethod
+    def _default_name(role: object) -> str:
+        return "管理员密钥" if str(role or "").strip().lower() == "admin" else "普通用户"
+
+    def _normalize_item(self, raw: object) -> dict[str, object] | None:
+        if not isinstance(raw, dict):
+            return None
+        role = self._clean(raw.get("role")).lower()
+        if role not in {"admin", "user"}:
+            return None
+        key_hash = self._clean(raw.get("key_hash"))
+        if not key_hash:
+            return None
+        item_id = self._clean(raw.get("id")) or uuid.uuid4().hex[:12]
+        name = self._clean(raw.get("name")) or self._default_name(role)
+        created_at = self._clean(raw.get("created_at")) or _now_iso()
+        last_used_at = self._clean(raw.get("last_used_at")) or None
+        return {
+            "id": item_id,
+            "name": name,
+            "role": role,
+            "key_hash": key_hash,
+            "enabled": bool(raw.get("enabled", True)),
+            "created_at": created_at,
+            "last_used_at": last_used_at,
+        }
+
+    def _load(self) -> list[dict[str, object]]:
+        try:
+            items = self.storage.load_auth_keys()
+        except Exception:
+            return []
+        if not isinstance(items, list):
+            return []
+        return [normalized for item in items if (normalized := self._normalize_item(item)) is not None]
+
+    def _save(self) -> None:
+        self.storage.save_auth_keys(self._items)
+
+    def _reload_locked(self) -> None:
+        self._items = self._load()
+
+    @staticmethod
+    def _public_item(item: dict[str, object]) -> dict[str, object]:
+        return {
+            "id": item.get("id"),
+            "name": item.get("name"),
+            "role": item.get("role"),
+            "enabled": bool(item.get("enabled", True)),
+            "created_at": item.get("created_at"),
+            "last_used_at": item.get("last_used_at"),
+        }
+
+    def list_keys(self, role: AuthRole | None = None) -> list[dict[str, object]]:
+        with self._lock:
+            self._reload_locked()
+            items = [item for item in self._items if role is None or item.get("role") == role]
+            return [self._public_item(item) for item in items]
+
+    def _has_key_hash_locked(self, key_hash: str, *, exclude_id: str = "") -> bool:
+        for item in self._items:
+            item_id = self._clean(item.get("id"))
+            if exclude_id and item_id == exclude_id:
+                continue
+            stored_hash = self._clean(item.get("key_hash"))
+            if stored_hash and hmac.compare_digest(stored_hash, key_hash):
+                return True
+        return False
+
+    def _build_key_hash_locked(self, raw_key: str, *, exclude_id: str = "") -> str:
+        candidate = self._clean(raw_key)
+        if not candidate:
+            raise ValueError("请输入新的专用密钥")
+        admin_key = self._clean(config.auth_key)
+        if admin_key and hmac.compare_digest(candidate, admin_key):
+            raise ValueError("这个密钥和管理员密钥冲突了，请换一个新的密钥")
+        key_hash = _hash_key(candidate)
+        if self._has_key_hash_locked(key_hash, exclude_id=exclude_id):
+            raise ValueError("这个专用密钥已经存在，请换一个新的密钥")
+        return key_hash
+
+    def _has_name_locked(self, name: str, *, role: AuthRole | None = None, exclude_id: str = "") -> bool:
+        candidate = self._clean(name)
+        if not candidate:
+            return False
+        for item in self._items:
+            item_id = self._clean(item.get("id"))
+            if exclude_id and item_id == exclude_id:
+                continue
+            if role is not None and item.get("role") != role:
+                continue
+            if self._clean(item.get("name")) == candidate:
+                return True
+        return False
+
+    def _build_default_name_locked(self, role: AuthRole, *, exclude_id: str = "") -> str:
+        base_name = self._default_name(role)
+        if not self._has_name_locked(base_name, role=role, exclude_id=exclude_id):
+            return base_name
+        suffix = 2
+        while True:
+            candidate = f"{base_name} {suffix}"
+            if not self._has_name_locked(candidate, role=role, exclude_id=exclude_id):
+                return candidate
+            suffix += 1
+
+    def _build_name_locked(self, name: str, *, role: AuthRole, exclude_id: str = "") -> str:
+        candidate = self._clean(name)
+        if not candidate:
+            return self._build_default_name_locked(role, exclude_id=exclude_id)
+        if self._has_name_locked(candidate, role=role, exclude_id=exclude_id):
+            raise ValueError("这个名称已经在使用中了，换一个更容易区分的名称吧")
+        return candidate
+
+    def create_key(self, *, role: AuthRole, name: str = "") -> tuple[dict[str, object], str]:
+        with self._lock:
+            self._reload_locked()
+            normalized_name = self._build_name_locked(name, role=role)
+            while True:
+                raw_key = f"sk-{secrets.token_urlsafe(24)}"
+                try:
+                    key_hash = self._build_key_hash_locked(raw_key)
+                    break
+                except ValueError:
+                    continue
+            item = {
+                "id": uuid.uuid4().hex[:12],
+                "name": normalized_name,
+                "role": role,
+                "key_hash": key_hash,
+                "enabled": True,
+                "created_at": _now_iso(),
+                "last_used_at": None,
+            }
+            self._items.append(item)
+            self._save()
+            return self._public_item(item), raw_key
+
+    def update_key(
+        self,
+        key_id: str,
+        updates: dict[str, object],
+        *,
+        role: AuthRole | None = None,
+    ) -> dict[str, object] | None:
+        normalized_id = self._clean(key_id)
+        if not normalized_id:
+            return None
+        with self._lock:
+            self._reload_locked()
+            for index, item in enumerate(self._items):
+                if item.get("id") != normalized_id:
+                    continue
+                if role is not None and item.get("role") != role:
+                    return None
+                next_item = dict(item)
+                next_role = "admin" if str(next_item.get("role") or "").strip().lower() == "admin" else "user"
+                if "name" in updates and updates.get("name") is not None:
+                    next_item["name"] = self._build_name_locked(
+                        str(updates.get("name") or ""),
+                        role=next_role,
+                        exclude_id=normalized_id,
+                    )
+                if "enabled" in updates and updates.get("enabled") is not None:
+                    next_item["enabled"] = bool(updates.get("enabled"))
+                if "key" in updates and updates.get("key") is not None:
+                    next_item["key_hash"] = self._build_key_hash_locked(str(updates.get("key") or ""), exclude_id=normalized_id)
+                self._items[index] = next_item
+                self._save()
+                return self._public_item(next_item)
+        return None
+
+    def delete_key(self, key_id: str, *, role: AuthRole | None = None) -> bool:
+        normalized_id = self._clean(key_id)
+        if not normalized_id:
+            return False
+        with self._lock:
+            self._reload_locked()
+            before = len(self._items)
+            self._items = [
+                item
+                for item in self._items
+                if not (item.get("id") == normalized_id and (role is None or item.get("role") == role))
+            ]
+            if len(self._items) == before:
+                return False
+            self._save()
+            return True
+
+    def authenticate(self, raw_key: str) -> dict[str, object] | None:
+        candidate = self._clean(raw_key)
+        if not candidate:
+            return None
+        candidate_hash = _hash_key(candidate)
+        with self._lock:
+            for index, item in enumerate(self._items):
+                if not bool(item.get("enabled", True)):
+                    continue
+                stored_hash = self._clean(item.get("key_hash"))
+                if not stored_hash or not hmac.compare_digest(stored_hash, candidate_hash):
+                    continue
+                next_item = dict(item)
+                now = datetime.now(timezone.utc)
+                next_item["last_used_at"] = now.isoformat()
+                self._items[index] = next_item
+                item_id = self._clean(next_item.get("id"))
+                last_flush_at = self._last_used_flush_at.get(item_id)
+                if last_flush_at is None or (now - last_flush_at).total_seconds() >= 60:
+                    try:
+                        self._save()
+                        self._last_used_flush_at[item_id] = now
+                    except Exception:
+                        pass
+                return self._public_item(next_item)
+        return None
+
+
+auth_service = AuthService(config.get_storage_backend())

services/backup_service.py

@@ -0,0 +1,673 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import io
+import json
+import os
+import random
+import subprocess
+import tarfile
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+from urllib.parse import quote, urlencode
+
+from curl_cffi import requests
+
+from services.config import BASE_DIR, CONFIG_FILE, DATA_DIR, config, load_backup_state, save_backup_state
+from services.image_storage_service import IMAGE_INDEX_FILE
+from services.image_tags_service import TAGS_FILE
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _iso_now() -> str:
+    return _utc_now().replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _clean(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _sha256_hex(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _is_backup_object(key: object) -> bool:
+    name = _clean(key).rsplit("/", 1)[-1]
+    return name.startswith("backup-") and (name.endswith(".tar.gz") or name.endswith(".tar.gz.enc"))
+
+
+def _hmac_sha256(key: bytes, message: str) -> bytes:
+    return hmac.new(key, message.encode("utf-8"), hashlib.sha256).digest()
+
+
+def _openssl_encrypt(data: bytes, passphrase: str) -> bytes:
+    env = dict(os.environ)
+    env["CHATGPT2API_BACKUP_PASSPHRASE"] = passphrase
+    try:
+        result = subprocess.run(
+            [
+                "openssl",
+                "enc",
+                "-aes-256-cbc",
+                "-pbkdf2",
+                "-salt",
+                "-md",
+                "sha256",
+                "-pass",
+                "env:CHATGPT2API_BACKUP_PASSPHRASE",
+            ],
+            input=data,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=True,
+            env=env,
+        )
+    except FileNotFoundError as exc:
+        raise BackupError("当前环境缺少 openssl，无法执行加密备份") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or b"").decode("utf-8", errors="replace").strip()
+        raise BackupError(f"加密备份失败：{detail or 'openssl 执行失败'}") from exc
+    return result.stdout
+
+
+def _openssl_decrypt(data: bytes, passphrase: str) -> bytes:
+    env = dict(os.environ)
+    env["CHATGPT2API_BACKUP_PASSPHRASE"] = passphrase
+    try:
+        result = subprocess.run(
+            [
+                "openssl",
+                "enc",
+                "-d",
+                "-aes-256-cbc",
+                "-pbkdf2",
+                "-md",
+                "sha256",
+                "-pass",
+                "env:CHATGPT2API_BACKUP_PASSPHRASE",
+            ],
+            input=data,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=True,
+            env=env,
+        )
+    except FileNotFoundError as exc:
+        raise BackupError("当前环境缺少 openssl，无法解密备份内容") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or b"").decode("utf-8", errors="replace").strip()
+        raise BackupError(f"解密备份失败：{detail or 'openssl 执行失败'}") from exc
+    return result.stdout
+
+
+def _guess_content_type(name: str) -> str:
+    if name.endswith(".json"):
+        return "application/json"
+    if name.endswith(".jsonl"):
+        return "application/x-ndjson"
+    if name.endswith(".tar.gz"):
+        return "application/gzip"
+    if name.endswith(".gz"):
+        return "application/gzip"
+    return "application/octet-stream"
+
+
+def _json_bytes(value: object) -> bytes:
+    return json.dumps(value, ensure_ascii=False, indent=2).encode("utf-8")
+
+
+def _count_items(value: object) -> int:
+    if isinstance(value, list):
+        return len(value)
+    if isinstance(value, dict):
+        return len(value)
+    return 0
+
+
+class BackupError(RuntimeError):
+    pass
+
+
+class CloudflareR2Client:
+    def __init__(self, settings: dict[str, object]) -> None:
+        self.account_id = _clean(settings.get("account_id"))
+        self.access_key_id = _clean(settings.get("access_key_id"))
+        self.secret_access_key = _clean(settings.get("secret_access_key"))
+        self.bucket = _clean(settings.get("bucket"))
+        self.prefix = _clean(settings.get("prefix")) or "backups"
+        self.session = requests.Session(impersonate="chrome", verify=True)
+
+    def validate(self) -> None:
+        missing = []
+        if not self.account_id:
+            missing.append("Account ID")
+        if not self.access_key_id:
+            missing.append("Access Key ID")
+        if not self.secret_access_key:
+            missing.append("Secret Access Key")
+        if not self.bucket:
+            missing.append("Bucket")
+        if missing:
+            raise BackupError(f"R2 配置不完整：缺少 {'、'.join(missing)}")
+
+    @property
+    def endpoint(self) -> str:
+        return f"https://{self.account_id}.r2.cloudflarestorage.com"
+
+    def _aws_v4_headers(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, str] | None = None,
+        body: bytes = b"",
+        extra_headers: dict[str, str] | None = None,
+    ) -> tuple[str, dict[str, str]]:
+        now = _utc_now()
+        amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+        date_stamp = now.strftime("%Y%m%d")
+        encoded_query = urlencode(sorted((query or {}).items()))
+        payload_hash = _sha256_hex(body)
+        host = f"{self.account_id}.r2.cloudflarestorage.com"
+        headers = {
+            "host": host,
+            "x-amz-content-sha256": payload_hash,
+            "x-amz-date": amz_date,
+        }
+        if extra_headers:
+            for key, value in extra_headers.items():
+                headers[key.lower()] = value.strip()
+        sorted_items = sorted((key.lower(), " ".join(str(value).strip().split())) for key, value in headers.items())
+        canonical_headers = "".join(f"{key}:{value}\n" for key, value in sorted_items)
+        signed_headers = ";".join(key for key, _ in sorted_items)
+        canonical_request = "\n".join([
+            method.upper(),
+            path,
+            encoded_query,
+            canonical_headers,
+            signed_headers,
+            payload_hash,
+        ])
+        credential_scope = f"{date_stamp}/auto/s3/aws4_request"
+        string_to_sign = "\n".join([
+            "AWS4-HMAC-SHA256",
+            amz_date,
+            credential_scope,
+            _sha256_hex(canonical_request.encode("utf-8")),
+        ])
+        k_date = _hmac_sha256(("AWS4" + self.secret_access_key).encode("utf-8"), date_stamp)
+        k_region = hmac.new(k_date, b"auto", hashlib.sha256).digest()
+        k_service = hmac.new(k_region, b"s3", hashlib.sha256).digest()
+        k_signing = hmac.new(k_service, b"aws4_request", hashlib.sha256).digest()
+        signature = hmac.new(k_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+        authorization = (
+            "AWS4-HMAC-SHA256 "
+            f"Credential={self.access_key_id}/{credential_scope}, "
+            f"SignedHeaders={signed_headers}, "
+            f"Signature={signature}"
+        )
+        request_headers = {key: value for key, value in headers.items()}
+        request_headers["authorization"] = authorization
+        return encoded_query, request_headers
+
+    def _request(
+        self,
+        method: str,
+        key: str = "",
+        *,
+        query: dict[str, str] | None = None,
+        body: bytes = b"",
+        extra_headers: dict[str, str] | None = None,
+        timeout: float = 60.0,
+    ):
+        object_path = f"/{self.bucket}"
+        if key:
+            object_path += f"/{quote(key.lstrip('/'), safe='/')}"
+        encoded_query, headers = self._aws_v4_headers(method, object_path, query=query, body=body, extra_headers=extra_headers)
+        url = f"{self.endpoint}{object_path}"
+        if encoded_query:
+            url += f"?{encoded_query}"
+        response = self.session.request(method.upper(), url, headers=headers, data=body, timeout=timeout)
+        return response
+
+    def test_connection(self) -> dict[str, object]:
+        self.validate()
+        response = self._request("GET", query={"list-type": "2", "max-keys": "1"}, timeout=30.0)
+        if response.status_code >= 400:
+            raise BackupError(f"连接 R2 失败：HTTP {response.status_code}")
+        return {"ok": True, "status": int(response.status_code)}
+
+    def upload_bytes(self, key: str, payload: bytes, *, content_type: str, metadata: dict[str, str] | None = None) -> dict[str, object]:
+        headers = {"content-type": content_type}
+        if metadata:
+            for item_key, item_value in metadata.items():
+                headers[f"x-amz-meta-{item_key}"] = str(item_value)
+        response = self._request("PUT", key, body=payload, extra_headers=headers)
+        if response.status_code >= 400:
+            raise BackupError(f"上传备份失败：HTTP {response.status_code}")
+        return {"key": key, "etag": str(response.headers.get("etag") or "").strip('"')}
+
+    def delete_object(self, key: str) -> None:
+        response = self._request("DELETE", key, timeout=30.0)
+        if response.status_code >= 400 and response.status_code != 404:
+            raise BackupError(f"删除备份失败：HTTP {response.status_code}")
+
+    def download_bytes(self, key: str) -> bytes:
+        response = self._request("GET", key, timeout=60.0)
+        if response.status_code >= 400:
+            raise BackupError(f"读取备份失败：HTTP {response.status_code}")
+        return bytes(response.content or b"")
+
+    def list_objects(self) -> list[dict[str, object]]:
+        items: list[dict[str, object]] = []
+        continuation = ""
+        while True:
+            query = {"list-type": "2", "prefix": f"{self.prefix.rstrip('/')}/", "max-keys": "1000"}
+            if continuation:
+                query["continuation-token"] = continuation
+            response = self._request("GET", query=query, timeout=30.0)
+            if response.status_code >= 400:
+                raise BackupError(f"获取备份列表失败：HTTP {response.status_code}")
+            text = response.text
+            for block in text.split("<Contents>")[1:]:
+                key = _clean(block.split("<Key>", 1)[1].split("</Key>", 1)[0]) if "<Key>" in block else ""
+                if not key:
+                    continue
+                size_text = _clean(block.split("<Size>", 1)[1].split("</Size>", 1)[0]) if "<Size>" in block else "0"
+                updated = _clean(block.split("<LastModified>", 1)[1].split("</LastModified>", 1)[0]) if "<LastModified>" in block else ""
+                items.append({
+                    "key": key,
+                    "size": int(size_text or 0),
+                    "updated_at": updated,
+                })
+            truncated = "<IsTruncated>true</IsTruncated>" in text
+            if not truncated:
+                break
+            if "<NextContinuationToken>" not in text:
+                break
+            continuation = _clean(text.split("<NextContinuationToken>", 1)[1].split("</NextContinuationToken>", 1)[0])
+            if not continuation:
+                break
+        items.sort(key=lambda item: str(item.get("updated_at") or ""), reverse=True)
+        return items
+
+    def close(self) -> None:
+        self.session.close()
+
+
+class BackupService:
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._running = False
+
+    def start(self) -> None:
+        with self._lock:
+            if self._thread and self._thread.is_alive():
+                return
+            self._stop_event.clear()
+            self._thread = threading.Thread(target=self._run, daemon=True, name="r2-backup-scheduler")
+            self._thread.start()
+
+    def stop(self) -> None:
+        with self._lock:
+            self._stop_event.set()
+            thread = self._thread
+            self._thread = None
+        if thread and thread.is_alive():
+            thread.join(timeout=2)
+
+    def _run(self) -> None:
+        while not self._stop_event.is_set():
+            try:
+                self.run_scheduled_backup_if_needed()
+            except Exception:
+                pass
+            self._stop_event.wait(30)
+
+    def run_scheduled_backup_if_needed(self) -> None:
+        settings = config.get_backup_settings()
+        if not settings.get("enabled"):
+            return
+        state = self.get_status()
+        if state.get("running"):
+            return
+        interval_minutes = int(settings.get("interval_minutes") or 360)
+        last_finished_raw = _clean(state.get("last_finished_at"))
+        if last_finished_raw:
+            try:
+                last_finished = datetime.fromisoformat(last_finished_raw.replace("Z", "+00:00"))
+                elapsed = (_utc_now() - last_finished.astimezone(UTC)).total_seconds()
+                if elapsed < interval_minutes * 60:
+                    return
+            except Exception:
+                pass
+        self.run_backup(trigger="schedule")
+
+    def get_status(self) -> dict[str, object]:
+        return {
+            **load_backup_state(),
+            "running": self._running,
+        }
+
+    def is_configured(self) -> bool:
+        settings = config.get_backup_settings()
+        return all([
+            _clean(settings.get("account_id")),
+            _clean(settings.get("access_key_id")),
+            _clean(settings.get("secret_access_key")),
+            _clean(settings.get("bucket")),
+        ])
+
+    def get_settings(self) -> dict[str, object]:
+        settings = dict(config.get_backup_settings())
+        settings["secret_access_key"] = "********" if _clean(settings.get("secret_access_key")) else ""
+        settings["passphrase"] = "********" if _clean(settings.get("passphrase")) else ""
+        return settings
+
+    def update_settings(self, payload: dict[str, object]) -> dict[str, object]:
+        current = config.get_backup_settings()
+        merged = dict(current)
+        merged.update(dict(payload or {}))
+        if "include" in payload and isinstance(payload.get("include"), dict):
+            include = dict(current.get("include") or {})
+            include.update(payload.get("include") or {})
+            merged["include"] = include
+        if payload.get("secret_access_key") == "********":
+            merged["secret_access_key"] = current.get("secret_access_key")
+        if payload.get("passphrase") == "********":
+            merged["passphrase"] = current.get("passphrase")
+        updated = config.update({"backup": merged})
+        return dict(updated.get("backup") or {})
+
+    def test_connection(self) -> dict[str, object]:
+        client = CloudflareR2Client(config.get_backup_settings())
+        try:
+            return client.test_connection()
+        finally:
+            client.close()
+
+    def list_backups(self) -> list[dict[str, object]]:
+        if not self.is_configured():
+            return []
+        client = CloudflareR2Client(config.get_backup_settings())
+        try:
+            items = client.list_objects()
+        finally:
+            client.close()
+        parsed: list[dict[str, object]] = []
+        for item in items:
+            key = _clean(item.get("key"))
+            name = key.rsplit("/", 1)[-1]
+            encrypted = name.endswith(".enc")
+            parsed.append({
+                "key": key,
+                "name": name,
+                "size": int(item.get("size") or 0),
+                "updated_at": item.get("updated_at"),
+                "encrypted": encrypted,
+            })
+        return parsed
+
+    def delete_backup(self, key: str) -> None:
+        candidate = _clean(key)
+        if not candidate:
+            raise BackupError("备份对象 key 不能为空")
+        client = CloudflareR2Client(config.get_backup_settings())
+        try:
+            client.delete_object(candidate)
+        finally:
+            client.close()
+
+    def download_backup(self, key: str) -> dict[str, object]:
+        candidate = _clean(key)
+        if not candidate:
+            raise BackupError("备份对象 key 不能为空")
+        client = CloudflareR2Client(config.get_backup_settings())
+        try:
+            payload = client.download_bytes(candidate)
+        finally:
+            client.close()
+        name = candidate.rsplit("/", 1)[-1] or "backup.bin"
+        if candidate.endswith(".enc"):
+            passphrase = _clean(config.get_backup_settings().get("passphrase"))
+            if not passphrase:
+                raise BackupError("当前未配置加密口令，无法下载并解密已加密备份")
+            payload = _openssl_decrypt(payload, passphrase)
+            if name.endswith(".enc"):
+                name = name[:-4] or "backup.tar.gz"
+        return {
+            "key": candidate,
+            "name": name,
+            "content_type": _guess_content_type(name),
+            "payload": payload,
+            "size": len(payload),
+        }
+
+    def get_backup_detail(self, key: str) -> dict[str, object]:
+        candidate = _clean(key)
+        if not candidate:
+            raise BackupError("备份对象 key 不能为空")
+        client = CloudflareR2Client(config.get_backup_settings())
+        try:
+            payload = client.download_bytes(candidate)
+        finally:
+            client.close()
+        detail = self._decode_backup_payload(candidate, payload)
+        detail["key"] = candidate
+        detail["name"] = candidate.rsplit("/", 1)[-1]
+        detail["encrypted"] = candidate.endswith(".enc")
+        return detail
+
+    def run_backup(self, *, trigger: str = "manual") -> dict[str, object]:
+        with self._lock:
+            current = self.get_status()
+            if self._running:
+                raise BackupError("当前已有备份任务正在执行")
+            started_at = _iso_now()
+            self._running = True
+            save_backup_state({
+                "last_started_at": started_at,
+                "last_finished_at": current.get("last_finished_at"),
+                "last_status": "idle",
+                "last_error": None,
+                "last_object_key": current.get("last_object_key"),
+            })
+        try:
+            result = self._run_backup_once(trigger=trigger)
+            save_backup_state({
+                "last_started_at": started_at,
+                "last_finished_at": _iso_now(),
+                "last_status": "success",
+                "last_error": None,
+                "last_object_key": result["key"],
+            })
+            return result
+        except Exception as exc:
+            save_backup_state({
+                "last_started_at": started_at,
+                "last_finished_at": _iso_now(),
+                "last_status": "error",
+                "last_error": str(exc) or exc.__class__.__name__,
+                "last_object_key": current.get("last_object_key"),
+            })
+            raise
+        finally:
+            self._running = False
+
+    def _run_backup_once(self, *, trigger: str) -> dict[str, object]:
+        settings = config.get_backup_settings()
+        client = CloudflareR2Client(settings)
+        client.validate()
+        payload_raw = self._build_backup_archive(settings, trigger=trigger)
+        encrypted = bool(settings.get("encrypt"))
+        if encrypted:
+            passphrase = _clean(settings.get("passphrase"))
+            if not passphrase:
+                raise BackupError("已启用备份加密，但未设置加密口令")
+            payload = _openssl_encrypt(payload_raw, passphrase)
+            suffix = ".tar.gz.enc"
+        else:
+            payload = payload_raw
+            suffix = ".tar.gz"
+        timestamp = _utc_now().strftime("%Y%m%dT%H%M%SZ")
+        random_tag = f"{random.randint(0, 0xFFFF):04x}"
+        object_key = f"{client.prefix.rstrip('/')}/backup-{timestamp}-{random_tag}{suffix}"
+        metadata = {
+            "created-at": _iso_now(),
+            "encrypted": "true" if encrypted else "false",
+            "trigger": trigger,
+        }
+        try:
+            result = client.upload_bytes(object_key, payload, content_type="application/octet-stream", metadata=metadata)
+            self._apply_rotation(client, int(settings.get("rotation_keep") or 0))
+            return {
+                "key": result["key"],
+                "size": len(payload),
+                "encrypted": encrypted,
+            }
+        finally:
+            client.close()
+
+    def _decode_backup_payload(self, key: str, payload: bytes) -> dict[str, object]:
+        decoded = payload
+        if key.endswith(".enc"):
+            passphrase = _clean(config.get_backup_settings().get("passphrase"))
+            if not passphrase:
+                raise BackupError("当前未配置加密口令，无法查看已加密备份")
+            decoded = _openssl_decrypt(decoded, passphrase)
+        return self._decode_archive_detail(decoded)
+
+    def _apply_rotation(self, client: CloudflareR2Client, keep: int) -> None:
+        if keep <= 0:
+            return
+        items = [item for item in client.list_objects() if _is_backup_object(item.get("key"))]
+        if len(items) <= keep:
+            return
+        for item in items[keep:]:
+            key = _clean(item.get("key"))
+            if key:
+                client.delete_object(key)
+
+    def _decode_archive_detail(self, payload: bytes) -> dict[str, object]:
+        files: list[dict[str, object]] = []
+        snapshots: list[dict[str, object]] = []
+        metadata: dict[str, object] = {}
+        try:
+            with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+                members = [member for member in archive.getmembers() if member.isfile()]
+                for member in members:
+                    extracted = archive.extractfile(member)
+                    if extracted is None:
+                        continue
+                    raw = extracted.read()
+                    name = member.name
+                    if name == "backup-metadata.json":
+                        try:
+                            parsed = json.loads(raw.decode("utf-8"))
+                            if isinstance(parsed, dict):
+                                metadata = parsed
+                        except Exception:
+                            metadata = {}
+                        continue
+                    if name.startswith("snapshots/") and name.endswith(".json"):
+                        count = 0
+                        try:
+                            parsed_snapshot = json.loads(raw.decode("utf-8"))
+                            count = _count_items(parsed_snapshot)
+                        except Exception:
+                            count = 0
+                        snapshots.append({
+                            "name": name.removeprefix("snapshots/").removesuffix(".json"),
+                            "count": count,
+                        })
+                        continue
+                    files.append({
+                        "name": name,
+                        "exists": True,
+                        "content_type": _guess_content_type(name),
+                        "size": len(raw),
+                        "sha256": _sha256_hex(raw),
+                    })
+        except tarfile.TarError as exc:
+            raise BackupError("解析备份压缩包失败，备份可能已损坏") from exc
+        files.sort(key=lambda item: str(item.get("name") or ""))
+        snapshots.sort(key=lambda item: str(item.get("name") or ""))
+        return {
+            "created_at": metadata.get("created_at"),
+            "trigger": metadata.get("trigger"),
+            "app_version": metadata.get("app_version"),
+            "storage_backend": metadata.get("storage_backend"),
+            "files": files,
+            "snapshots": snapshots,
+        }
+
+    def _build_backup_archive(self, settings: dict[str, object], *, trigger: str) -> bytes:
+        include = settings.get("include") if isinstance(settings.get("include"), dict) else {}
+        metadata = {
+            "version": 2,
+            "created_at": _iso_now(),
+            "trigger": trigger,
+            "app_version": config.app_version,
+            "storage_backend": config.get_storage_backend().get_backend_info(),
+        }
+        buffer = io.BytesIO()
+        with tarfile.open(fileobj=buffer, mode="w:gz") as archive:
+            self._add_bytes_to_archive(archive, "backup-metadata.json", _json_bytes(metadata))
+            if include.get("config"):
+                self._add_file_to_archive(archive, CONFIG_FILE, "config.json")
+            if include.get("register"):
+                self._add_file_to_archive(archive, DATA_DIR / "register.json", "data/register.json")
+            if include.get("cpa"):
+                self._add_file_to_archive(archive, DATA_DIR / "cpa_config.json", "data/cpa_config.json")
+            if include.get("sub2api"):
+                self._add_file_to_archive(archive, DATA_DIR / "sub2api_config.json", "data/sub2api_config.json")
+            if include.get("logs"):
+                self._add_file_to_archive(archive, DATA_DIR / "logs.jsonl", "data/logs.jsonl")
+            if include.get("image_tasks"):
+                self._add_file_to_archive(archive, DATA_DIR / "image_tasks.json", "data/image_tasks.json")
+                self._add_file_to_archive(archive, IMAGE_INDEX_FILE, "data/image_index.json")
+            if include.get("accounts_snapshot"):
+                self._add_bytes_to_archive(
+                    archive,
+                    "snapshots/accounts.json",
+                    _json_bytes(config.get_storage_backend().load_accounts()),
+                )
+            if include.get("auth_keys_snapshot"):
+                self._add_bytes_to_archive(
+                    archive,
+                    "snapshots/auth_keys.json",
+                    _json_bytes(config.get_storage_backend().load_auth_keys()),
+                )
+            if include.get("images"):
+                self._add_file_to_archive(archive, TAGS_FILE, "data/image_tags.json")
+                self._add_directory_to_archive(archive, config.images_dir, "data/images")
+        return buffer.getvalue()
+
+    def _add_bytes_to_archive(self, archive: tarfile.TarFile, name: str, payload: bytes) -> None:
+        info = tarfile.TarInfo(name=name)
+        info.size = len(payload)
+        info.mtime = int(_utc_now().timestamp())
+        archive.addfile(info, io.BytesIO(payload))
+
+    def _add_file_to_archive(self, archive: tarfile.TarFile, source: Path, arcname: str) -> None:
+        if not source.exists() or not source.is_file():
+            return
+        archive.add(source, arcname=arcname)
+
+    def _add_directory_to_archive(self, archive: tarfile.TarFile, source_dir: Path, arcname_root: str) -> None:
+        if not source_dir.exists() or not source_dir.is_dir():
+            return
+        for path in sorted(source_dir.rglob("*")):
+            if path.is_file():
+                relative = path.relative_to(source_dir).as_posix()
+                archive.add(path, arcname=f"{arcname_root}/{relative}")
+
+
+backup_service = BackupService()

services/config.py

@@ -0,0 +1,446 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+import sys
+from pathlib import Path
+import time
+
+from services.storage.base import StorageBackend
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+DATA_DIR = BASE_DIR / "data"
+CONFIG_FILE = BASE_DIR / "config.json"
+VERSION_FILE = BASE_DIR / "VERSION"
+BACKUP_STATE_FILE = DATA_DIR / "backup_state.json"
+
+DEFAULT_BACKUP_INCLUDE = {
+    "config": True,
+    "register": True,
+    "cpa": True,
+    "sub2api": True,
+    "logs": True,
+    "image_tasks": True,
+    "accounts_snapshot": True,
+    "auth_keys_snapshot": True,
+    "images": False,
+}
+
+DEFAULT_IMAGE_STORAGE = {
+    "enabled": False,
+    "mode": "local",
+    "webdav_url": "",
+    "webdav_username": "",
+    "webdav_password": "",
+    "webdav_root_path": "chatgpt2api/images",
+    "public_base_url": "",
+}
+
+DEFAULT_CHAT_COMPLETION_CACHE = {
+    "enabled": True,
+    "ttl_seconds": 60,
+    "max_entries": 256,
+    "dedupe_inflight": True,
+    "stream_cache": True,
+    "normalize_messages": True,
+    "drop_adjacent_duplicates": True,
+    "drop_assistant_history": False,
+}
+
+
+def _normalize_bool(value: object, default: bool = False) -> bool:
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"1", "true", "yes", "on"}:
+            return True
+        if lowered in {"0", "false", "no", "off"}:
+            return False
+    if value is None:
+        return default
+    return bool(value)
+
+
+def _normalize_positive_int(value: object, default: int, minimum: int = 0) -> int:
+    try:
+        normalized = int(value)
+    except (TypeError, ValueError):
+        normalized = default
+    return max(minimum, normalized)
+
+
+def _normalize_backup_include(value: object) -> dict[str, bool]:
+    source = value if isinstance(value, dict) else {}
+    normalized = dict(DEFAULT_BACKUP_INCLUDE)
+    for key in normalized:
+        normalized[key] = _normalize_bool(source.get(key), normalized[key])
+    return normalized
+
+
+def _normalize_backup_settings(value: object) -> dict[str, object]:
+    source = value if isinstance(value, dict) else {}
+    return {
+        "enabled": _normalize_bool(source.get("enabled"), False),
+        "provider": "cloudflare_r2",
+        "account_id": str(source.get("account_id") or "").strip(),
+        "access_key_id": str(source.get("access_key_id") or "").strip(),
+        "secret_access_key": str(source.get("secret_access_key") or "").strip(),
+        "bucket": str(source.get("bucket") or "").strip(),
+        "prefix": str(source.get("prefix") or "backups").strip().strip("/") or "backups",
+        "interval_minutes": _normalize_positive_int(source.get("interval_minutes"), 360, 1),
+        "rotation_keep": _normalize_positive_int(source.get("rotation_keep"), 10, 0),
+        "encrypt": _normalize_bool(source.get("encrypt"), False),
+        "passphrase": str(source.get("passphrase") or "").strip(),
+        "include": _normalize_backup_include(source.get("include")),
+    }
+
+
+def _normalize_backup_state(value: object) -> dict[str, object]:
+    source = value if isinstance(value, dict) else {}
+    return {
+        "last_started_at": str(source.get("last_started_at") or "").strip() or None,
+        "last_finished_at": str(source.get("last_finished_at") or "").strip() or None,
+        "last_status": str(source.get("last_status") or "idle").strip() or "idle",
+        "last_error": str(source.get("last_error") or "").strip() or None,
+        "last_object_key": str(source.get("last_object_key") or "").strip() or None,
+    }
+
+
+def _normalize_image_storage_settings(value: object) -> dict[str, object]:
+    source = value if isinstance(value, dict) else {}
+    mode = str(source.get("mode") or "local").strip().lower()
+    if mode not in {"local", "webdav", "both"}:
+        mode = "local"
+    enabled = _normalize_bool(source.get("enabled"), False)
+    if not enabled:
+        mode = "local"
+    root_path = str(source.get("webdav_root_path") or DEFAULT_IMAGE_STORAGE["webdav_root_path"]).strip().strip("/")
+    return {
+        "enabled": enabled,
+        "mode": mode,
+        "webdav_url": str(source.get("webdav_url") or "").strip().rstrip("/"),
+        "webdav_username": str(source.get("webdav_username") or "").strip(),
+        "webdav_password": str(source.get("webdav_password") or "").strip(),
+        "webdav_root_path": root_path or str(DEFAULT_IMAGE_STORAGE["webdav_root_path"]),
+        "public_base_url": str(source.get("public_base_url") or "").strip().rstrip("/"),
+    }
+
+
+def _normalize_chat_completion_cache_settings(value: object) -> dict[str, object]:
+    source = value if isinstance(value, dict) else {}
+    return {
+        "enabled": _normalize_bool(source.get("enabled"), DEFAULT_CHAT_COMPLETION_CACHE["enabled"]),
+        "ttl_seconds": _normalize_positive_int(
+            source.get("ttl_seconds"),
+            int(DEFAULT_CHAT_COMPLETION_CACHE["ttl_seconds"]),
+            0,
+        ),
+        "max_entries": _normalize_positive_int(
+            source.get("max_entries"),
+            int(DEFAULT_CHAT_COMPLETION_CACHE["max_entries"]),
+            1,
+        ),
+        "dedupe_inflight": _normalize_bool(
+            source.get("dedupe_inflight"),
+            bool(DEFAULT_CHAT_COMPLETION_CACHE["dedupe_inflight"]),
+        ),
+        "stream_cache": _normalize_bool(
+            source.get("stream_cache"),
+            bool(DEFAULT_CHAT_COMPLETION_CACHE["stream_cache"]),
+        ),
+        "normalize_messages": _normalize_bool(
+            source.get("normalize_messages"),
+            bool(DEFAULT_CHAT_COMPLETION_CACHE["normalize_messages"]),
+        ),
+        "drop_adjacent_duplicates": _normalize_bool(
+            source.get("drop_adjacent_duplicates"),
+            bool(DEFAULT_CHAT_COMPLETION_CACHE["drop_adjacent_duplicates"]),
+        ),
+        "drop_assistant_history": _normalize_bool(
+            source.get("drop_assistant_history"),
+            bool(DEFAULT_CHAT_COMPLETION_CACHE["drop_assistant_history"]),
+        ),
+    }
+
+
+def _validate_image_storage_settings(settings: dict[str, object]) -> None:
+    if not _normalize_bool(settings.get("enabled"), False):
+        return
+    if not str(settings.get("webdav_url") or "").strip():
+        raise ValueError("启用 WebDAV 图片存储后必须填写 WebDAV URL")
+    if not str(settings.get("webdav_password") or "").strip():
+        raise ValueError("启用 WebDAV 图片存储后必须填写 WebDAV 密码")
+
+
+@dataclass(frozen=True)
+class LoadedSettings:
+    auth_key: str
+    refresh_account_interval_minute: int
+
+
+def _normalize_auth_key(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _is_invalid_auth_key(value: object) -> bool:
+    return _normalize_auth_key(value) == ""
+
+
+def _read_json_object(path: Path, *, name: str) -> dict[str, object]:
+    if not path.exists():
+        return {}
+    if path.is_dir():
+        print(
+            f"Warning: {name} at '{path}' is a directory, ignoring it and falling back to other configuration sources.",
+            file=sys.stderr,
+        )
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_settings() -> LoadedSettings:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    raw_config = _read_json_object(CONFIG_FILE, name="config.json")
+    auth_key = _normalize_auth_key(os.getenv("CHATGPT2API_AUTH_KEY") or raw_config.get("auth-key"))
+    if _is_invalid_auth_key(auth_key):
+        raise ValueError(
+            "❌ auth-key 未设置！\n"
+            "请在环境变量 CHATGPT2API_AUTH_KEY 中设置，或者在 config.json 中填写 auth-key。"
+        )
+
+    try:
+        refresh_interval = int(raw_config.get("refresh_account_interval_minute", 5))
+    except (TypeError, ValueError):
+        refresh_interval = 5
+
+    return LoadedSettings(
+        auth_key=auth_key,
+        refresh_account_interval_minute=refresh_interval,
+    )
+
+
+class ConfigStore:
+    def __init__(self, path: Path):
+        self.path = path
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        self.data = self._load()
+        self._storage_backend: StorageBackend | None = None
+        if _is_invalid_auth_key(self.auth_key):
+            raise ValueError(
+                "❌ auth-key 未设置！\n"
+                "请按以下任意一种方式解决：\n"
+                "1. 在 Render 的 Environment 变量中添加：\n"
+                "   CHATGPT2API_AUTH_KEY = your_real_auth_key\n"
+                "2. 或者在 config.json 中填写：\n"
+                '   "auth-key": "your_real_auth_key"'
+            )
+
+    def _load(self) -> dict[str, object]:
+        return _read_json_object(self.path, name="config.json")
+
+    def _save(self) -> None:
+        self.path.write_text(json.dumps(self.data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    @property
+    def auth_key(self) -> str:
+        return _normalize_auth_key(os.getenv("CHATGPT2API_AUTH_KEY") or self.data.get("auth-key"))
+
+    @property
+    def accounts_file(self) -> Path:
+        return DATA_DIR / "accounts.json"
+
+    @property
+    def refresh_account_interval_minute(self) -> int:
+        try:
+            return int(self.data.get("refresh_account_interval_minute", 5))
+        except (TypeError, ValueError):
+            return 5
+
+    @property
+    def image_retention_days(self) -> int:
+        try:
+            return max(1, int(self.data.get("image_retention_days", 30)))
+        except (TypeError, ValueError):
+            return 30
+
+    @property
+    def image_poll_timeout_secs(self) -> int:
+        try:
+            return max(1, int(self.data.get("image_poll_timeout_secs", 120)))
+        except (TypeError, ValueError):
+            return 120
+
+    @property
+    def image_poll_interval_secs(self) -> float:
+        try:
+            return max(0.5, float(self.data.get("image_poll_interval_secs", 10.0)))
+        except (TypeError, ValueError):
+            return 10.0
+
+    @property
+    def image_poll_initial_wait_secs(self) -> float:
+        """Image generation upstream takes ~30s; polling immediately wastes requests
+        and trips a transient 429. Default 10s gives the conversation document time
+        to commit before the first poll."""
+        try:
+            return max(0.0, float(self.data.get("image_poll_initial_wait_secs", 10.0)))
+        except (TypeError, ValueError):
+            return 10.0
+
+    @property
+    def image_account_concurrency(self) -> int:
+        try:
+            return max(1, int(self.data.get("image_account_concurrency", 3)))
+        except (TypeError, ValueError):
+            return 3
+
+    @property
+    def auto_remove_invalid_accounts(self) -> bool:
+        value = self.data.get("auto_remove_invalid_accounts", False)
+        if isinstance(value, str):
+            return value.strip().lower() in {"1", "true", "yes", "on"}
+        return bool(value)
+
+    @property
+    def auto_remove_rate_limited_accounts(self) -> bool:
+        value = self.data.get("auto_remove_rate_limited_accounts", False)
+        if isinstance(value, str):
+            return value.strip().lower() in {"1", "true", "yes", "on"}
+        return bool(value)
+
+    @property
+    def log_levels(self) -> list[str]:
+        levels = self.data.get("log_levels")
+        if not isinstance(levels, list):
+            return []
+        allowed = {"debug", "info", "warning", "error"}
+        return [level for item in levels if (level := str(item or "").strip().lower()) in allowed]
+
+    @property
+    def sensitive_words(self) -> list[str]:
+        words = self.data.get("sensitive_words")
+        return [word for item in words if (word := str(item or "").strip())] if isinstance(words, list) else []
+
+    @property
+    def ai_review(self) -> dict[str, object]:
+        value = self.data.get("ai_review")
+        return value if isinstance(value, dict) else {}
+
+    @property
+    def global_system_prompt(self) -> str:
+        return str(self.data.get("global_system_prompt") or "").strip()
+
+    @property
+    def images_dir(self) -> Path:
+        path = DATA_DIR / "images"
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def image_thumbnails_dir(self) -> Path:
+        path = DATA_DIR / "image_thumbnails"
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def cleanup_old_images(self) -> int:
+        cutoff = time.time() - self.image_retention_days * 86400
+        removed = 0
+        for path in self.images_dir.rglob("*"):
+            if path.is_file() and path.stat().st_mtime < cutoff:
+                path.unlink()
+                removed += 1
+        for path in sorted((p for p in self.images_dir.rglob("*") if p.is_dir()), key=lambda p: len(p.parts), reverse=True):
+            try:
+                path.rmdir()
+            except OSError:
+                pass
+        return removed
+
+    @property
+    def base_url(self) -> str:
+        return str(
+            os.getenv("CHATGPT2API_BASE_URL")
+            or self.data.get("base_url")
+            or ""
+        ).strip().rstrip("/")
+
+    @property
+    def app_version(self) -> str:
+        try:
+            value = VERSION_FILE.read_text(encoding="utf-8").strip()
+        except FileNotFoundError:
+            return "0.0.0"
+        return value or "0.0.0"
+
+    def get(self) -> dict[str, object]:
+        data = dict(self.data)
+        data["refresh_account_interval_minute"] = self.refresh_account_interval_minute
+        data["image_retention_days"] = self.image_retention_days
+        data["image_poll_timeout_secs"] = self.image_poll_timeout_secs
+        data["image_poll_interval_secs"] = self.image_poll_interval_secs
+        data["image_poll_initial_wait_secs"] = self.image_poll_initial_wait_secs
+        data["image_account_concurrency"] = self.image_account_concurrency
+        data["auto_remove_invalid_accounts"] = self.auto_remove_invalid_accounts
+        data["auto_remove_rate_limited_accounts"] = self.auto_remove_rate_limited_accounts
+        data["log_levels"] = self.log_levels
+        data["sensitive_words"] = self.sensitive_words
+        data["ai_review"] = self.ai_review
+        data["global_system_prompt"] = self.global_system_prompt
+        data["backup"] = self.get_backup_settings()
+        data["image_storage"] = self.get_image_storage_settings()
+        data["chat_completion_cache"] = self.get_chat_completion_cache_settings()
+        data.pop("auth-key", None)
+        return data
+
+    def get_proxy_settings(self) -> str:
+        return str(self.data.get("proxy") or "").strip()
+
+    def update(self, data: dict[str, object]) -> dict[str, object]:
+        next_data = dict(self.data)
+        next_data.update(dict(data or {}))
+        if "backup" in next_data:
+            next_data["backup"] = _normalize_backup_settings(next_data.get("backup"))
+        if "image_storage" in next_data:
+            next_data["image_storage"] = _normalize_image_storage_settings(next_data.get("image_storage"))
+            _validate_image_storage_settings(next_data["image_storage"])
+        if "chat_completion_cache" in next_data:
+            next_data["chat_completion_cache"] = _normalize_chat_completion_cache_settings(
+                next_data.get("chat_completion_cache")
+            )
+        next_data.pop("backup_state", None)
+        self.data = next_data
+        self._save()
+        return self.get()
+
+    def get_backup_settings(self) -> dict[str, object]:
+        return _normalize_backup_settings(self.data.get("backup"))
+
+    def get_image_storage_settings(self) -> dict[str, object]:
+        return _normalize_image_storage_settings(self.data.get("image_storage"))
+
+    def get_chat_completion_cache_settings(self) -> dict[str, object]:
+        return _normalize_chat_completion_cache_settings(self.data.get("chat_completion_cache"))
+
+    def get_storage_backend(self) -> StorageBackend:
+        """获取存储后端实例（单例）"""
+        if self._storage_backend is None:
+            from services.storage.factory import create_storage_backend
+            self._storage_backend = create_storage_backend(DATA_DIR)
+        return self._storage_backend
+
+
+def load_backup_state() -> dict[str, object]:
+    return _normalize_backup_state(_read_json_object(BACKUP_STATE_FILE, name="backup_state.json"))
+
+
+def save_backup_state(state: dict[str, object]) -> dict[str, object]:
+    normalized = _normalize_backup_state(state)
+    BACKUP_STATE_FILE.write_text(json.dumps(normalized, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return normalized
+
+
+config = ConfigStore(CONFIG_FILE)

services/content_filter.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import re
+
+from curl_cffi import requests
+from fastapi import HTTPException
+
+from services.config import config
+from services.proxy_service import proxy_settings
+from utils.log import logger
+
+DEFAULT_REVIEW_PROMPT = "判断用户请求是否允许。只回答 ALLOW 或 REJECT。"
+
+# Strip base64 image data URIs before review: a text-only review model can't
+# analyze image bytes, and a single inlined image easily blows past the token
+# budget of the upstream review service.
+_BASE64_DATA_URI = re.compile(r"data:[\w/.+;-]+;base64,[A-Za-z0-9+/=]+")
+
+# Cap aligned to the upstream review service's max context. If text still
+# exceeds the cap after base64 stripping, keep equal head/tail halves so both
+# the system prompt and the most recent user message survive.
+_MAX_REVIEW_TEXT_LEN = 100_000
+_TRUNCATION_MARKER = "\n…[truncated]…\n"
+
+
+def _text(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return "\n".join(_text(item) for item in value)
+    if isinstance(value, dict):
+        return "\n".join(_text(value.get(key)) for key in ("text", "input_text", "content", "input", "instructions", "system", "prompt"))
+    return ""
+
+
+def request_text(*values: object) -> str:
+    return "\n".join(part for value in values if (part := _text(value).strip()))
+
+
+def _sanitize_for_review(text: str) -> tuple[str, dict[str, int]]:
+    """Strip base64 data URIs and truncate to the review-service context limit.
+
+    Returns (sanitized_text, stats) where stats carries base64_blocks_stripped
+    and truncated_chars so callers can emit structured logs.
+    """
+    sanitized, base64_blocks_stripped = _BASE64_DATA_URI.subn("[image]", text)
+    truncated_chars = 0
+    if len(sanitized) > _MAX_REVIEW_TEXT_LEN:
+        # Reserve marker space so the result stays within the cap.
+        half = (_MAX_REVIEW_TEXT_LEN - len(_TRUNCATION_MARKER)) // 2
+        truncated_chars = len(sanitized) - 2 * half
+        sanitized = sanitized[:half] + _TRUNCATION_MARKER + sanitized[-half:]
+    stats = {
+        "base64_blocks_stripped": base64_blocks_stripped,
+        "truncated_chars": truncated_chars,
+    }
+    return sanitized, stats
+
+
+def _extract_review_decision(data: object) -> str | None:
+    """Defensively pull the decision text out of the review service response.
+
+    Returns None when the response shape doesn't match the OpenAI chat-completion
+    contract (e.g. {"error": ...} with no choices). The caller treats None as
+    "undecided" and applies the configured fail-open policy.
+    """
+    if not isinstance(data, dict):
+        return None
+    choices = data.get("choices")
+    if not isinstance(choices, list) or not choices:
+        return None
+    first = choices[0]
+    if not isinstance(first, dict):
+        return None
+    message = first.get("message")
+    if not isinstance(message, dict):
+        return None
+    content = message.get("content")
+    if content is None:
+        return None
+    return str(content).strip().lower()
+
+
+def _is_allow_decision(decision: str) -> bool:
+    return decision.startswith(("allow", "pass", "true", "yes", "通过", "允许", "安全"))
+
+
+def _is_reject_decision(decision: str) -> bool:
+    return decision.startswith(("reject", "deny", "block", "false", "no", "拒绝", "不允许", "违规", "禁止"))
+
+
+def _resolve_fail_open(review: dict) -> bool:
+    """Resolve fail_open from review config. Defaults to True."""
+    value = review.get("fail_open")
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def check_request(text: str) -> None:
+    text = str(text or "")
+    if not text.strip():
+        return
+    # Local sensitive-word match runs on the raw text (cheap, no network).
+    for word in config.sensitive_words:
+        if word in text:
+            raise HTTPException(status_code=400, detail={"error": "检测到敏感词，拒绝本次任务"})
+    review = config.ai_review
+    if not review.get("enabled"):
+        return
+    base_url = str(review.get("base_url") or "").strip().rstrip("/")
+    api_key = str(review.get("api_key") or "").strip()
+    model = str(review.get("model") or "").strip()
+    if not base_url or not api_key or not model:
+        raise HTTPException(status_code=400, detail={"error": "ai review config is incomplete"})
+
+    fail_open = _resolve_fail_open(review)
+
+    review_text, sanitize_stats = _sanitize_for_review(text)
+    if sanitize_stats["base64_blocks_stripped"] or sanitize_stats["truncated_chars"]:
+        logger.info({
+            "event": "ai_review_text_sanitized",
+            "original_text_len": len(text),
+            "review_text_len": len(review_text),
+            **sanitize_stats,
+        })
+    prompt = str(review.get("prompt") or DEFAULT_REVIEW_PROMPT).strip()
+    content = f"{prompt}\n\n用户请求:\n{review_text}\n\n只回答 ALLOW 或 REJECT。"
+
+    # fail_open=True (default): on upstream failure or ambiguous reply, let the
+    # request through. The review is a soft safety net; one missed review is
+    # preferable to a 5xx storm when the review service is flaky. Set
+    # config.ai_review.fail_open=false for strict-compliance deployments.
+    def _on_failure(event_payload: dict) -> None:
+        logger.warning(event_payload)
+        if not fail_open:
+            raise HTTPException(
+                status_code=503,
+                detail={"error": "AI 审核服务暂时不可用，请稍后重试"},
+            )
+
+    try:
+        response = requests.post(
+            f"{base_url}/v1/chat/completions",
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            json={"model": model, "messages": [{"role": "user", "content": content}], "temperature": 0},
+            timeout=60,
+            **proxy_settings.build_session_kwargs(),
+        )
+    except Exception as exc:
+        _on_failure({
+            "event": "ai_review_request_failed",
+            "error": str(exc),
+            "error_type": exc.__class__.__name__,
+            "review_text_len": len(review_text),
+            "original_text_len": len(text),
+        })
+        return
+
+    try:
+        data = response.json()
+    except Exception as exc:
+        _on_failure({
+            "event": "ai_review_response_not_json",
+            "status_code": response.status_code,
+            "body_preview": str(response.text or "")[:200],
+            "error": str(exc),
+        })
+        return
+
+    decision = _extract_review_decision(data)
+    if decision is None:
+        _on_failure({
+            "event": "ai_review_malformed_response",
+            "status_code": response.status_code,
+            "body_preview": str(data)[:300],
+            "review_text_len": len(review_text),
+            "original_text_len": len(text),
+        })
+        return
+
+    if _is_allow_decision(decision):
+        return
+    if _is_reject_decision(decision):
+        raise HTTPException(status_code=400, detail={"error": "AI 审核未通过，拒绝本次任务"})
+    # Ambiguous decisions (e.g. "MAYBE", empty content) fall back to fail-open policy.
+    _on_failure({
+        "event": "ai_review_ambiguous_decision",
+        "decision": decision[:100],
+        "review_text_len": len(review_text),
+    })
+    return

services/cpa_service.py

@@ -0,0 +1,315 @@
+"""CLIProxyAPI integration for browsing remote auth files and importing selected tokens."""
+
+from __future__ import annotations
+
+import json
+import threading
+import uuid
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import Lock
+
+from curl_cffi.requests import Session
+
+from services.account_service import account_service
+from services.config import DATA_DIR
+from services.proxy_service import proxy_settings
+
+
+CPA_CONFIG_FILE = DATA_DIR / "cpa_config.json"
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _normalize_import_job(raw: object, *, fail_unfinished: bool) -> dict | None:
+    if not isinstance(raw, dict):
+        return None
+    status = str(raw.get("status") or "failed").strip() or "failed"
+    if fail_unfinished and status in {"pending", "running"}:
+        status = "failed"
+    return {
+        "job_id": str(raw.get("job_id") or uuid.uuid4().hex).strip(),
+        "status": status,
+        "created_at": str(raw.get("created_at") or _now_iso()).strip() or _now_iso(),
+        "updated_at": str(raw.get("updated_at") or raw.get("created_at") or _now_iso()).strip() or _now_iso(),
+        "total": int(raw.get("total") or 0),
+        "completed": int(raw.get("completed") or 0),
+        "added": int(raw.get("added") or 0),
+        "skipped": int(raw.get("skipped") or 0),
+        "refreshed": int(raw.get("refreshed") or 0),
+        "failed": int(raw.get("failed") or 0),
+        "errors": raw.get("errors") if isinstance(raw.get("errors"), list) else [],
+    }
+
+
+def _normalize_pool(raw: dict) -> dict:
+    return {
+        "id": str(raw.get("id") or _new_id()).strip(),
+        "name": str(raw.get("name") or "").strip(),
+        "base_url": str(raw.get("base_url") or "").strip(),
+        "secret_key": str(raw.get("secret_key") or "").strip(),
+        "import_job": _normalize_import_job(raw.get("import_job"), fail_unfinished=True),
+    }
+
+
+def _management_headers(secret_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {secret_key}",
+        "Accept": "application/json",
+    }
+
+
+class CPAConfig:
+    def __init__(self, store_file: Path):
+        self._store_file = store_file
+        self._lock = Lock()
+        self._pools: list[dict] = self._load()
+
+    def _load(self) -> list[dict]:
+        if not self._store_file.exists():
+            return []
+        try:
+            raw = json.loads(self._store_file.read_text(encoding="utf-8"))
+            if isinstance(raw, dict) and "base_url" in raw:
+                pool = _normalize_pool(raw)
+                return [pool] if pool["base_url"] else []
+            if isinstance(raw, list):
+                return [_normalize_pool(item) for item in raw if isinstance(item, dict)]
+        except Exception:
+            pass
+        return []
+
+    def _save(self) -> None:
+        self._store_file.parent.mkdir(parents=True, exist_ok=True)
+        self._store_file.write_text(json.dumps(self._pools, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    def list_pools(self) -> list[dict]:
+        with self._lock:
+            return [dict(pool) for pool in self._pools]
+
+    def get_pool(self, pool_id: str) -> dict | None:
+        with self._lock:
+            for pool in self._pools:
+                if pool["id"] == pool_id:
+                    return dict(pool)
+        return None
+
+    def add_pool(self, name: str, base_url: str, secret_key: str) -> dict:
+        pool = _normalize_pool({"id": _new_id(), "name": name, "base_url": base_url, "secret_key": secret_key})
+        with self._lock:
+            self._pools.append(pool)
+            self._save()
+        return dict(pool)
+
+    def update_pool(self, pool_id: str, updates: dict) -> dict | None:
+        with self._lock:
+            for index, pool in enumerate(self._pools):
+                if pool["id"] != pool_id:
+                    continue
+                merged = {**pool, **{key: value for key, value in updates.items() if value is not None}, "id": pool_id}
+                self._pools[index] = _normalize_pool(merged)
+                self._save()
+                return dict(self._pools[index])
+        return None
+
+    def delete_pool(self, pool_id: str) -> bool:
+        with self._lock:
+            before = len(self._pools)
+            self._pools = [pool for pool in self._pools if pool["id"] != pool_id]
+            if len(self._pools) < before:
+                self._save()
+                return True
+        return False
+
+    def set_import_job(self, pool_id: str, import_job: dict | None) -> dict | None:
+        with self._lock:
+            for index, pool in enumerate(self._pools):
+                if pool["id"] != pool_id:
+                    continue
+                next_pool = dict(pool)
+                next_pool["import_job"] = _normalize_import_job(import_job, fail_unfinished=False)
+                self._pools[index] = next_pool
+                self._save()
+                return dict(next_pool)
+        return None
+
+    def get_import_job(self, pool_id: str) -> dict | None:
+        with self._lock:
+            for pool in self._pools:
+                if pool["id"] == pool_id:
+                    job = pool.get("import_job")
+                    return dict(job) if isinstance(job, dict) else None
+        return None
+
+
+def list_remote_files(pool: dict) -> list[dict]:
+    base_url = str(pool.get("base_url") or "").strip()
+    secret_key = str(pool.get("secret_key") or "").strip()
+    if not base_url or not secret_key:
+        return []
+
+    url = f"{base_url.rstrip('/')}/v0/management/auth-files"
+    session = Session(**proxy_settings.build_session_kwargs(verify=True))
+    try:
+        response = session.get(url, headers=_management_headers(secret_key), timeout=30)
+        if not response.ok:
+            raise RuntimeError(f"remote list failed: HTTP {response.status_code}")
+        payload = response.json()
+    finally:
+        session.close()
+
+    files = payload.get("files") if isinstance(payload, dict) else None
+    if not isinstance(files, list):
+        raise RuntimeError("remote list payload is invalid")
+
+    items: list[dict] = []
+    for item in files:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "").strip()
+        email = str(item.get("email") or item.get("account") or "").strip()
+        if not name:
+            continue
+        items.append({"name": name, "email": email})
+    return items
+
+
+def fetch_remote_access_token(pool: dict, file_name: str) -> tuple[str | None, str | None]:
+    base_url = str(pool.get("base_url") or "").strip()
+    secret_key = str(pool.get("secret_key") or "").strip()
+    file_name = str(file_name or "").strip()
+    if not base_url or not secret_key or not file_name:
+        return None, "invalid request"
+
+    url = f"{base_url.rstrip('/')}/v0/management/auth-files/download"
+    session = Session(**proxy_settings.build_session_kwargs(verify=True))
+    try:
+        response = session.get(url, headers=_management_headers(secret_key), params={"name": file_name}, timeout=30)
+        if not response.ok:
+            return None, f"HTTP {response.status_code}"
+        payload = response.json()
+    except Exception as exc:
+        return None, str(exc)
+    finally:
+        session.close()
+
+    if not isinstance(payload, dict):
+        return None, "invalid payload"
+
+    access_token = str(payload.get("access_token") or "").strip()
+    if not access_token:
+        return None, "missing access_token"
+    return access_token, None
+
+
+class CPAImportService:
+    def __init__(self, cpa_config: CPAConfig):
+        self._config = cpa_config
+
+    def start_import(self, pool: dict, selected_files: list[str]) -> dict:
+        names = [str(name or "").strip() for name in selected_files if str(name or "").strip()]
+        if not names:
+            raise ValueError("selected files is required")
+
+        pool_id = str(pool.get("id") or "").strip()
+        job = {
+            "job_id": uuid.uuid4().hex,
+            "status": "pending",
+            "created_at": _now_iso(),
+            "updated_at": _now_iso(),
+            "total": len(names),
+            "completed": 0,
+            "added": 0,
+            "skipped": 0,
+            "refreshed": 0,
+            "failed": 0,
+            "errors": [],
+        }
+        saved_pool = self._config.set_import_job(pool_id, job)
+        if saved_pool is None:
+            raise ValueError("pool not found")
+
+        thread = threading.Thread(
+            target=self._run_import,
+            args=(pool_id, pool, names),
+            name=f"cpa-import-{pool_id}",
+            daemon=True,
+        )
+        thread.start()
+        return dict(saved_pool.get("import_job") or job)
+
+    def _update_job(self, pool_id: str, **updates) -> dict | None:
+        current = self._config.get_import_job(pool_id)
+        if current is None:
+            return None
+        next_job = {**current, **updates, "updated_at": _now_iso()}
+        pool = self._config.set_import_job(pool_id, next_job)
+        if pool is None:
+            return None
+        job = pool.get("import_job")
+        return dict(job) if isinstance(job, dict) else None
+
+    def _append_error(self, pool_id: str, file_name: str, message: str) -> None:
+        current = self._config.get_import_job(pool_id)
+        if current is None:
+            return
+        errors = list(current.get("errors") or [])
+        errors.append({"name": file_name, "error": message})
+        self._update_job(pool_id, errors=errors, failed=len(errors))
+
+    def _run_import(self, pool_id: str, pool: dict, names: list[str]) -> None:
+        self._update_job(pool_id, status="running")
+
+        tokens: list[str] = []
+        max_workers = min(16, max(1, len(names)))
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            future_map = {executor.submit(fetch_remote_access_token, pool, name): name for name in names}
+            for future in as_completed(future_map):
+                file_name = future_map[future]
+                try:
+                    token, error = future.result()
+                except Exception as exc:
+                    token, error = None, str(exc)
+
+                if token:
+                    tokens.append(token)
+                else:
+                    self._append_error(pool_id, file_name, error or "unknown error")
+
+                current = self._config.get_import_job(pool_id) or {}
+                failed = len(current.get("errors") or [])
+                self._update_job(pool_id, completed=int(current.get("completed") or 0) + 1, failed=failed)
+
+        if not tokens:
+            current = self._config.get_import_job(pool_id) or {}
+            self._update_job(
+                pool_id,
+                status="failed",
+                completed=int(current.get("total") or 0),
+                failed=len(current.get("errors") or []),
+            )
+            return
+
+        add_result = account_service.add_accounts(tokens, source_type="codex")
+        refresh_result = account_service.refresh_accounts(tokens)
+        current = self._config.get_import_job(pool_id) or {}
+        self._update_job(
+            pool_id,
+            status="completed",
+            completed=len(names),
+            added=int(add_result.get("added") or 0),
+            skipped=int(add_result.get("skipped") or 0),
+            refreshed=int(refresh_result.get("refreshed") or 0),
+            failed=len(current.get("errors") or []),
+        )
+
+
+cpa_config = CPAConfig(CPA_CONFIG_FILE)
+cpa_import_service = CPAImportService(cpa_config)

services/image_service.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import io
+import shutil
+import threading
+import time
+import zipfile
+from pathlib import Path
+
+from fastapi import HTTPException
+from fastapi.responses import FileResponse, Response
+from PIL import Image, ImageOps
+
+from services.config import config
+from services.image_storage_service import image_storage_service
+from services.image_tags_service import load_tags, remove_tags
+from utils.log import logger
+
+THUMBNAIL_SIZE = (320, 320)
+
+
+def _cleanup_empty_dirs(root: Path) -> None:
+    for path in sorted((p for p in root.rglob("*") if p.is_dir()), key=lambda p: len(p.parts), reverse=True):
+        try:
+            path.rmdir()
+        except OSError:
+            pass
+
+
+def _safe_relative_path(path: str) -> str:
+    value = str(path or "").strip().replace("\\", "/").lstrip("/")
+    if not value:
+        raise HTTPException(status_code=404, detail="image not found")
+    parts = Path(value).parts
+    if any(part in {"", ".", ".."} for part in parts):
+        raise HTTPException(status_code=404, detail="image not found")
+    return Path(*parts).as_posix()
+
+
+def _safe_image_path(relative_path: str) -> Path:
+    rel = _safe_relative_path(relative_path)
+    root = config.images_dir.resolve()
+    path = (root / rel).resolve()
+    try:
+        path.relative_to(root)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail="image not found") from exc
+    if not path.is_file():
+        raise HTTPException(status_code=404, detail="image not found")
+    return path
+
+
+def get_image_response(relative_path: str) -> FileResponse | Response:
+    if image_storage_service.has_local(relative_path):
+        return FileResponse(_safe_image_path(relative_path))
+    return Response(content=image_storage_service.get_bytes(relative_path), media_type="image/png")
+
+
+def _thumbnail_path(relative_path: str) -> Path:
+    rel = _safe_relative_path(relative_path)
+    return config.image_thumbnails_dir / f"{rel}.png"
+
+
+def thumbnail_url(base_url: str, relative_path: str) -> str:
+    return f"{base_url.rstrip('/')}/image-thumbnails/{_safe_relative_path(relative_path)}"
+
+
+def _image_dimensions(path: Path) -> tuple[int, int] | None:
+    try:
+        with Image.open(path) as image:
+            return image.size
+    except Exception:
+        return None
+
+
+def ensure_thumbnail(relative_path: str) -> Path:
+    target = _thumbnail_path(relative_path)
+    source_mtime = 0.0
+    source: Path | None = None
+    if image_storage_service.has_local(relative_path):
+        source = _safe_image_path(relative_path)
+        source_mtime = source.stat().st_mtime
+    if target.exists() and (not source_mtime or target.stat().st_mtime >= source_mtime):
+        return target
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        image_source = source if source is not None else io.BytesIO(image_storage_service.get_bytes(relative_path))
+        with Image.open(image_source) as image:
+            image = ImageOps.exif_transpose(image)
+            if image.mode not in {"RGB", "RGBA"}:
+                image = image.convert("RGBA" if "A" in image.getbands() else "RGB")
+            image.thumbnail(THUMBNAIL_SIZE, Image.Resampling.LANCZOS)
+            image.save(target, format="PNG", optimize=True)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail="failed to create thumbnail") from exc
+    return target
+
+
+def get_thumbnail_response(relative_path: str) -> FileResponse:
+    return FileResponse(ensure_thumbnail(relative_path))
+
+
+def get_image_download_response(relative_path: str) -> FileResponse:
+    if image_storage_service.has_local(relative_path):
+        path = _safe_image_path(relative_path)
+        return FileResponse(path, filename=path.name)
+    rel = _safe_relative_path(relative_path)
+    return Response(
+        content=image_storage_service.get_bytes(rel),
+        media_type="image/png",
+        headers={"Content-Disposition": f'attachment; filename="{Path(rel).name}"'},
+    )
+
+
+def cleanup_image_thumbnails() -> int:
+    thumbnails_root = config.image_thumbnails_dir
+    removed = 0
+    for path in thumbnails_root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(thumbnails_root).as_posix()
+        if not rel.endswith(".png") or not image_storage_service.exists(rel[:-4]):
+            path.unlink()
+            removed += 1
+    _cleanup_empty_dirs(thumbnails_root)
+    return removed
+
+def list_images(base_url: str, start_date: str = "", end_date: str = "") -> dict[str, object]:
+    config.cleanup_old_images()
+    cleanup_image_thumbnails()
+    all_tags = load_tags()
+    items = [
+        {
+            **item,
+            "url": str(item.get("url") or f"{base_url.rstrip('/')}/images/{item['path']}"),
+            "thumbnail_url": thumbnail_url(base_url, str(item["path"])),
+            "tags": all_tags.get(str(item["path"]), []),
+        }
+        for item in image_storage_service.list_items(base_url, start_date, end_date)
+    ]
+    groups: dict[str, list[dict[str, object]]] = {}
+    for item in items:
+        groups.setdefault(str(item["date"]), []).append(item)
+    return {"items": items, "groups": [{"date": key, "items": value} for key, value in groups.items()]}
+
+
+def delete_images(paths: list[str] | None = None, start_date: str = "", end_date: str = "", all_matching: bool = False) -> dict[str, int]:
+    root = config.images_dir.resolve()
+    targets = [
+        str(item["path"])
+        for item in image_storage_service.list_items("", start_date=start_date, end_date=end_date)
+    ] if all_matching else (paths or [])
+    removed = 0
+    for item in targets:
+        path = (root / item).resolve()
+        try:
+            path.relative_to(root)
+        except ValueError:
+            continue
+        if image_storage_service.delete(item):
+            removed += 1
+        for thumbnail in (_thumbnail_path(item), config.image_thumbnails_dir / _safe_relative_path(item)):
+            if thumbnail.is_file():
+                thumbnail.unlink()
+        remove_tags(item)
+    _cleanup_empty_dirs(root)
+    _cleanup_empty_dirs(config.image_thumbnails_dir)
+    return {"removed": removed}
+
+
+def download_images_zip(paths: list[str]) -> io.BytesIO:
+    root = config.images_dir.resolve()
+    buf = io.BytesIO()
+    added = 0
+    used_names: set[str] = set()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for item in paths:
+            rel = _safe_relative_path(item)
+            path = (root / rel).resolve()
+            payload: bytes | None = None
+            try:
+                path.relative_to(root)
+            except ValueError:
+                continue
+            if path.is_file():
+                payload = path.read_bytes()
+            else:
+                try:
+                    payload = image_storage_service.get_bytes(rel)
+                except Exception:
+                    continue
+            name = path.name
+            if name in used_names:
+                stem = path.stem
+                suffix = path.suffix
+                counter = 2
+                while f"{stem}_{counter}{suffix}" in used_names:
+                    counter += 1
+                name = f"{stem}_{counter}{suffix}"
+            used_names.add(name)
+            zf.writestr(name, payload)
+            added += 1
+    if added == 0:
+        raise HTTPException(status_code=404, detail="no images found")
+    buf.seek(0)
+    return buf
+def storage_stats() -> dict:
+    import shutil
+    usage = shutil.disk_usage(config.images_dir)
+    total_mb = usage.total // (1024 * 1024)
+    used_mb = usage.used // (1024 * 1024)
+    free_mb = usage.free // (1024 * 1024)
+
+    image_count = 0
+    image_size = 0
+    for p in config.images_dir.rglob("*"):
+        if p.is_file():
+            image_count += 1
+            image_size += p.stat().st_size
+
+    return {
+        "disk_total_mb": total_mb,
+        "disk_used_mb": used_mb,
+        "disk_free_mb": free_mb,
+        "image_count": image_count,
+        "image_size_mb": image_size // (1024 * 1024),
+        "image_size_bytes": image_size,
+    }
+
+
+def compress_images(quality: int = 60) -> dict:
+    """重新压缩所有图片，返回节省的空间"""
+    saved = 0
+    count = 0
+    for p in sorted(config.images_dir.rglob("*.png")):
+        if not p.is_file():
+            continue
+        try:
+            orig = p.stat().st_size
+            with Image.open(p) as img:
+                img = ImageOps.exif_transpose(img)
+                img.save(str(p) + ".tmp", format="PNG", optimize=True)
+            new_size = Path(str(p) + ".tmp").stat().st_size
+            if new_size < orig:
+                Path(str(p) + ".tmp").replace(p)
+                saved += orig - new_size
+                count += 1
+            else:
+                Path(str(p) + ".tmp").unlink()
+        except Exception:
+            pass
+    return {"compressed": count, "saved_bytes": saved, "saved_mb": saved // (1024 * 1024)}
+
+
+def delete_to_target(target_free_mb: int, dry_run: bool = False) -> dict:
+    """删除最旧的图片直到剩余空间达到 target_free_mb"""
+    import shutil
+    usage = shutil.disk_usage(config.images_dir)
+    current_free = usage.free // (1024 * 1024)
+    if current_free >= target_free_mb and not dry_run:
+        return {"removed": 0, "current_free_mb": current_free, "target_free_mb": target_free_mb, "done": True}
+
+    files = sorted(
+        (p for p in config.images_dir.rglob("*.png") if p.is_file()),
+        key=lambda p: p.stat().st_mtime,
+    )
+    removed = 0
+    freed = 0
+    for p in files:
+        if current_free + freed // (1024 * 1024) >= target_free_mb:
+            break
+        size = p.stat().st_size
+        if not dry_run:
+            rel = p.relative_to(config.images_dir).as_posix()
+            for tp in (_thumbnail_path(rel), config.image_thumbnails_dir / _safe_relative_path(rel)):
+                if tp.is_file():
+                    tp.unlink()
+            remove_tags(rel)
+            p.unlink()
+        freed += size
+        removed += 1
+
+    if not dry_run:
+        _cleanup_empty_dirs(config.images_dir)
+        _cleanup_empty_dirs(config.image_thumbnails_dir)
+
+    return {
+        "removed": removed,
+        "freed_mb": freed // (1024 * 1024),
+        "target_free_mb": target_free_mb,
+        "current_free_mb": current_free + (freed // (1024 * 1024)),
+        "done": (current_free + freed // (1024 * 1024)) >= target_free_mb,
+        "dry_run": dry_run,
+    }
+
+
+def download_images_zip(paths: list[str]) -> io.BytesIO:
+    root = config.images_dir.resolve()
+    buf = io.BytesIO()
+    added = 0
+    used_names: set[str] = set()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for item in paths:
+            rel = _safe_relative_path(item)
+            path = (root / rel).resolve()
+            try:
+                path.relative_to(root)
+            except ValueError:
+                continue
+            if not path.is_file():
+                continue
+            name = path.name
+            if name in used_names:
+                stem = path.stem
+                suffix = path.suffix
+                counter = 2
+                while f"{stem}_{counter}{suffix}" in used_names:
+                    counter += 1
+                name = f"{stem}_{counter}{suffix}"
+            used_names.add(name)
+            zf.write(path, name)
+            added += 1
+    if added == 0:
+        raise HTTPException(status_code=404, detail="no images found")
+    buf.seek(0)
+    return buf
+
+
+def _auto_cleanup_worker(stop_event: threading.Event) -> None:
+    """后台线程：每30分钟检查存储，空间低于阈值自动清理最旧图片"""
+    import shutil
+    min_free_mb = getattr(config, "image_min_free_mb", None)
+    if min_free_mb is None:
+        min_free_mb = 500
+
+    while not stop_event.wait(1800):  # 每30分钟
+        try:
+            config.cleanup_old_images()
+            cleanup_image_thumbnails()
+            usage = shutil.disk_usage(config.images_dir)
+            free_mb = usage.free // (1024 * 1024)
+            if free_mb < min_free_mb:
+                logger.info({"event": "image_auto_cleanup", "free_mb": free_mb, "min_free_mb": min_free_mb})
+                result = delete_to_target(min_free_mb)
+                logger.info({"event": "image_auto_cleanup_done", **result})
+        except Exception:
+            pass
+
+
+def start_image_cleanup_scheduler(stop_event: threading.Event) -> threading.Thread:
+    t = threading.Thread(target=_auto_cleanup_worker, args=(stop_event,), daemon=True, name="image-cleanup")
+    t.start()
+    return t

services/image_storage_service.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from threading import Lock
+from urllib.parse import quote, urlparse
+
+from curl_cffi import requests
+from fastapi import HTTPException
+from PIL import Image
+
+from services.config import DATA_DIR, config
+
+IMAGE_INDEX_FILE = DATA_DIR / "image_index.json"
+IMAGE_INDEX_LOCK = Lock()
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp"}
+
+
+class ImageStorageError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class StoredImage:
+    rel: str
+    url: str
+    storage: str
+    size: int
+
+
+def _clean(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _now_iso() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _safe_relative_path(path: str) -> str:
+    value = str(path or "").strip().replace("\\", "/").lstrip("/")
+    if not value:
+        raise HTTPException(status_code=404, detail="image not found")
+    parts = Path(value).parts
+    if any(part in {"", ".", ".."} for part in parts):
+        raise HTTPException(status_code=404, detail="image not found")
+    return Path(*parts).as_posix()
+
+
+def _image_dimensions(payload: bytes) -> tuple[int, int] | None:
+    try:
+        with Image.open(io.BytesIO(payload)) as image:
+            return image.size
+    except Exception:
+        return None
+
+
+def _is_image_rel(path: str) -> bool:
+    try:
+        safe_rel = _safe_relative_path(path)
+    except HTTPException:
+        return False
+    return Path(safe_rel).suffix.lower() in IMAGE_EXTENSIONS
+
+
+def _local_image_path(relative_path: str) -> Path:
+    rel = _safe_relative_path(relative_path)
+    root = config.images_dir.resolve()
+    path = (root / rel).resolve()
+    try:
+        path.relative_to(root)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail="image not found") from exc
+    return path
+
+
+def _read_json_object(path: Path) -> dict[str, object]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_json_object(path: Path, data: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    tmp_path.replace(path)
+
+
+class WebDAVClient:
+    def __init__(self, settings: dict[str, object]):
+        self.url = _clean(settings.get("webdav_url")).rstrip("/")
+        self.username = _clean(settings.get("webdav_username"))
+        self.password = _clean(settings.get("webdav_password"))
+        self.root_path = _clean(settings.get("webdav_root_path")).strip("/")
+        self.session = requests.Session()
+
+    def _auth_kwargs(self) -> dict[str, object]:
+        return {"auth": (self.username, self.password)} if self.username or self.password else {}
+
+    def _request(self, method: str, url: str, **kwargs):
+        response = self.session.request(method, url, timeout=30, **self._auth_kwargs(), **kwargs)
+        if response.status_code >= 400 and not (method == "MKCOL" and response.status_code in {405}):
+            raise ImageStorageError(f"WebDAV {method} failed: HTTP {response.status_code}")
+        return response
+
+    def remote_url(self, rel: str = "") -> str:
+        parts = [part for part in [self.root_path, _safe_relative_path(rel) if rel else ""] if part]
+        encoded = "/".join(quote(part, safe="") for item in parts for part in item.split("/") if part)
+        return f"{self.url}/{encoded}" if encoded else self.url
+
+    def ensure_dirs(self, rel: str) -> None:
+        parts = [part for part in [self.root_path, Path(_safe_relative_path(rel)).parent.as_posix()] if part and part != "."]
+        current = self.url
+        for item in "/".join(parts).split("/"):
+            if not item:
+                continue
+            current = f"{current}/{quote(item, safe='')}"
+            response = self.session.request("MKCOL", current, timeout=30, **self._auth_kwargs())
+            if response.status_code in {201, 405}:
+                continue
+            if response.status_code >= 400:
+                raise ImageStorageError(f"WebDAV MKCOL failed: HTTP {response.status_code}")
+
+    def put(self, rel: str, payload: bytes, content_type: str = "image/png") -> str:
+        self.ensure_dirs(rel)
+        url = self.remote_url(rel)
+        self._request("PUT", url, data=payload, headers={"Content-Type": content_type})
+        return url
+
+    def get(self, rel: str) -> bytes:
+        response = self._request("GET", self.remote_url(rel))
+        return bytes(response.content)
+
+    def delete(self, rel: str) -> bool:
+        response = self.session.request("DELETE", self.remote_url(rel), timeout=30, **self._auth_kwargs())
+        if response.status_code in {200, 202, 204, 404}:
+            return response.status_code != 404
+        raise ImageStorageError(f"WebDAV DELETE failed: HTTP {response.status_code}")
+
+    def test(self) -> dict[str, object]:
+        if not self.url:
+            return {"ok": False, "status": 0, "error": "WebDAV URL is required"}
+        if urlparse(self.url).scheme not in {"http", "https"}:
+            return {"ok": False, "status": 0, "error": "invalid WebDAV URL"}
+        test_rel = ".chatgpt2api_webdav_test.txt"
+        try:
+            self.put(test_rel, b"chatgpt2api webdav test\n", content_type="text/plain")
+            self.delete(test_rel)
+            return {"ok": True, "status": 200, "error": None}
+        except ImageStorageError as exc:
+            return {"ok": False, "status": 0, "error": str(exc)}
+        except Exception as exc:
+            return {"ok": False, "status": 0, "error": str(exc) or exc.__class__.__name__}
+        finally:
+            self.session.close()
+
+
+class ImageStorageService:
+    def __init__(self, index_file: Path = IMAGE_INDEX_FILE):
+        self.index_file = index_file
+        self._index_lock = IMAGE_INDEX_LOCK
+
+    def settings(self) -> dict[str, object]:
+        return config.get_image_storage_settings()
+
+    def mode(self) -> str:
+        return _clean(self.settings().get("mode")) or "local"
+
+    def _load_index(self) -> dict[str, dict[str, object]]:
+        raw = _read_json_object(self.index_file)
+        items = raw.get("items")
+        if not isinstance(items, dict):
+            return {}
+        return {str(key): value for key, value in items.items() if isinstance(value, dict)}
+
+    def _load_clean_index(self) -> dict[str, dict[str, object]]:
+        items = self._load_index()
+        return {rel: item for rel, item in items.items() if _is_image_rel(rel)}
+
+    def _save_index(self, items: dict[str, dict[str, object]]) -> None:
+        _write_json_object(self.index_file, {"items": items})
+
+    def _public_url(self, rel: str, base_url: str | None = None) -> str:
+        settings = self.settings()
+        public_base_url = _clean(settings.get("public_base_url"))
+        if public_base_url:
+            return f"{public_base_url.rstrip('/')}/{_safe_relative_path(rel)}"
+        return f"{(base_url or config.base_url).rstrip('/')}/images/{_safe_relative_path(rel)}"
+
+    def make_relative_path(self, image_data: bytes) -> str:
+        file_hash = hashlib.md5(image_data).hexdigest()
+        filename = f"{int(time.time())}_{file_hash}.png"
+        relative_dir = Path(time.strftime("%Y"), time.strftime("%m"), time.strftime("%d"))
+        return f"{relative_dir.as_posix()}/{filename}"
+
+    def save(self, image_data: bytes, base_url: str | None = None) -> StoredImage:
+        config.cleanup_old_images()
+        rel = self.make_relative_path(image_data)
+        mode = self.mode()
+        if mode not in {"local", "webdav", "both"}:
+            mode = "local"
+        stored_local = False
+        stored_webdav = False
+        remote_url = ""
+
+        if mode in {"local", "both"}:
+            path = _local_image_path(rel)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(image_data)
+            stored_local = True
+
+        if mode in {"webdav", "both"}:
+            remote_url = WebDAVClient(self.settings()).put(rel, image_data)
+            stored_webdav = True
+
+        dimensions = _image_dimensions(image_data)
+        item = {
+            "rel": rel,
+            "path": rel,
+            "name": Path(rel).name,
+            "date": "-".join(rel.split("/")[:3]),
+            "size": len(image_data),
+            "created_at": _now_iso(),
+            "storage": "both" if stored_local and stored_webdav else ("webdav" if stored_webdav else "local"),
+            "local": stored_local,
+            "webdav": stored_webdav,
+            "remote_url": remote_url,
+        }
+        if dimensions:
+            item["width"], item["height"] = dimensions
+        with self._index_lock:
+            items = self._load_clean_index()
+            items[rel] = item
+            self._save_index(items)
+        return StoredImage(rel=rel, url=self._public_url(rel, base_url), storage=str(item["storage"]), size=len(image_data))
+
+    def get_bytes(self, rel: str) -> bytes:
+        safe_rel = _safe_relative_path(rel)
+        if not _is_image_rel(safe_rel):
+            raise HTTPException(status_code=404, detail="image not found")
+        path = _local_image_path(safe_rel)
+        if path.is_file():
+            return path.read_bytes()
+        item = self._load_clean_index().get(safe_rel, {})
+        if item.get("webdav"):
+            return WebDAVClient(self.settings()).get(safe_rel)
+        raise HTTPException(status_code=404, detail="image not found")
+
+    def exists(self, rel: str) -> bool:
+        safe_rel = _safe_relative_path(rel)
+        if not _is_image_rel(safe_rel):
+            return False
+        if _local_image_path(safe_rel).is_file():
+            return True
+        item = self._load_clean_index().get(safe_rel, {})
+        return bool(item.get("webdav"))
+
+    def has_local(self, rel: str) -> bool:
+        safe_rel = _safe_relative_path(rel)
+        return _is_image_rel(safe_rel) and _local_image_path(safe_rel).is_file()
+
+    def list_items(self, base_url: str, start_date: str = "", end_date: str = "") -> list[dict[str, object]]:
+        with self._index_lock:
+            indexed = self._load_clean_index()
+            root = config.images_dir
+            changed = False
+            for path in root.rglob("*"):
+                if not path.is_file() or not _is_image_rel(path.name):
+                    continue
+                rel = path.relative_to(root).as_posix()
+                if rel in indexed:
+                    continue
+                dimensions = None
+                try:
+                    dimensions = _image_dimensions(path.read_bytes())
+                except Exception:
+                    dimensions = None
+                indexed[rel] = {
+                    "rel": rel,
+                    "path": rel,
+                    "name": path.name,
+                    "date": "-".join(rel.split("/")[:3]) if len(rel.split("/")) >= 4 else datetime.fromtimestamp(path.stat().st_mtime).strftime("%Y-%m-%d"),
+                    "size": path.stat().st_size,
+                    "created_at": datetime.fromtimestamp(path.stat().st_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+                    "storage": "local",
+                    "local": True,
+                    "webdav": False,
+                    **({"width": dimensions[0], "height": dimensions[1]} if dimensions else {}),
+                }
+                changed = True
+
+            items: list[dict[str, object]] = []
+            for rel, item in list(indexed.items()):
+                if not _is_image_rel(rel):
+                    indexed.pop(rel, None)
+                    changed = True
+                    continue
+                local = _local_image_path(rel).is_file()
+                webdav = bool(item.get("webdav"))
+                if not local and not webdav:
+                    indexed.pop(rel, None)
+                    changed = True
+                    continue
+                storage = "both" if local and webdav else ("webdav" if webdav else "local")
+                if item.get("local") != local or item.get("storage") != storage:
+                    item = {
+                        **item,
+                        "local": local,
+                        "storage": storage,
+                    }
+                    indexed[rel] = item
+                    changed = True
+                day = str(item.get("date") or "")
+                if start_date and day < start_date:
+                    continue
+                if end_date and day > end_date:
+                    continue
+                items.append({
+                    **item,
+                    "rel": rel,
+                    "path": rel,
+                    "url": self._public_url(rel, base_url),
+                })
+            if changed:
+                self._save_index(indexed)
+        items.sort(key=lambda item: str(item.get("created_at") or ""), reverse=True)
+        return items
+
+    def delete(self, rel: str) -> bool:
+        safe_rel = _safe_relative_path(rel)
+        removed = False
+        path = _local_image_path(safe_rel)
+        if path.is_file():
+            path.unlink()
+            removed = True
+        with self._index_lock:
+            items = self._load_clean_index()
+            item = items.get(safe_rel, {})
+            if item.get("webdav"):
+                try:
+                    removed = WebDAVClient(self.settings()).delete(safe_rel) or removed
+                except ImageStorageError:
+                    if not removed:
+                        raise
+            if safe_rel in items:
+                items.pop(safe_rel, None)
+                self._save_index(items)
+        return removed
+
+    def sync_all(self) -> dict[str, int]:
+        settings = self.settings()
+        if self.mode() not in {"webdav", "both"}:
+            raise ImageStorageError("WebDAV 图片存储未启用")
+        uploaded = 0
+        skipped = 0
+        failed = 0
+        with self._index_lock:
+            items = self._load_clean_index()
+            client = WebDAVClient(settings)
+            for path in sorted(config.images_dir.rglob("*")):
+                if not path.is_file() or not _is_image_rel(path.name):
+                    continue
+                rel = path.relative_to(config.images_dir).as_posix()
+                item = items.get(rel, {})
+                if item.get("webdav"):
+                    skipped += 1
+                    continue
+                try:
+                    payload = path.read_bytes()
+                    remote_url = client.put(rel, payload)
+                    dimensions = _image_dimensions(payload)
+                    items[rel] = {
+                        **item,
+                        "rel": rel,
+                        "path": rel,
+                        "name": path.name,
+                        "date": "-".join(rel.split("/")[:3]) if len(rel.split("/")) >= 4 else datetime.fromtimestamp(path.stat().st_mtime).strftime("%Y-%m-%d"),
+                        "size": len(payload),
+                        "created_at": str(item.get("created_at") or datetime.fromtimestamp(path.stat().st_mtime).strftime("%Y-%m-%d %H:%M:%S")),
+                        "storage": "both",
+                        "local": True,
+                        "webdav": True,
+                        "remote_url": remote_url,
+                        **({"width": dimensions[0], "height": dimensions[1]} if dimensions else {}),
+                    }
+                    uploaded += 1
+                except Exception:
+                    failed += 1
+            self._save_index(items)
+        return {"uploaded": uploaded, "skipped": skipped, "failed": failed}
+
+    def test_webdav(self) -> dict[str, object]:
+        return WebDAVClient(self.settings()).test()
+
+
+image_storage_service = ImageStorageService()

services/image_tags_service.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from services.config import DATA_DIR
+
+TAGS_FILE = DATA_DIR / "image_tags.json"
+
+
+def _ensure_file() -> None:
+    TAGS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if not TAGS_FILE.exists():
+        TAGS_FILE.write_text("{}", encoding="utf-8")
+
+
+def load_tags() -> dict[str, list[str]]:
+    _ensure_file()
+    try:
+        data = json.loads(TAGS_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_tags(data: dict[str, list[str]]) -> None:
+    _ensure_file()
+    TAGS_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def get_tags(image_rel: str) -> list[str]:
+    return load_tags().get(image_rel, [])
+
+
+def set_tags(image_rel: str, tags: list[str]) -> list[str]:
+    data = load_tags()
+    cleaned = list(dict.fromkeys(t.strip() for t in tags if t.strip()))
+    if cleaned:
+        data[image_rel] = cleaned
+    else:
+        data.pop(image_rel, None)
+    save_tags(data)
+    return cleaned
+
+
+def remove_tags(image_rel: str) -> None:
+    data = load_tags()
+    if data.pop(image_rel, None) is not None:
+        save_tags(data)
+
+
+def delete_tag(tag: str) -> int:
+    """从所有图片中删除指定标签，返回受影响的图片数。"""
+    data = load_tags()
+    count = 0
+    for rel in list(data):
+        if tag in data[rel]:
+            data[rel] = [t for t in data[rel] if t != tag]
+            if not data[rel]:
+                del data[rel]
+            count += 1
+    if count > 0:
+        save_tags(data)
+    return count
+
+
+def get_all_tags() -> list[str]:
+    data = load_tags()
+    seen: set[str] = set()
+    result: list[str] = []
+    for tags in data.values():
+        for t in tags:
+            if t not in seen:
+                seen.add(t)
+                result.append(t)
+    return result

services/image_task_service.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from services.config import DATA_DIR, config
+from services.content_filter import request_text
+from services.log_service import LOG_TYPE_CALL, log_service
+from services.protocol import openai_v1_image_edit, openai_v1_image_generations
+
+TASK_STATUS_QUEUED = "queued"
+TASK_STATUS_RUNNING = "running"
+TASK_STATUS_SUCCESS = "success"
+TASK_STATUS_ERROR = "error"
+TERMINAL_STATUSES = {TASK_STATUS_SUCCESS, TASK_STATUS_ERROR}
+UNFINISHED_STATUSES = {TASK_STATUS_QUEUED, TASK_STATUS_RUNNING}
+
+
+def _now_iso() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _timestamp(value: object) -> float:
+    if not isinstance(value, str) or not value.strip():
+        return 0.0
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%dT%H:%M:%S"):
+        try:
+            return datetime.strptime(value[:26], fmt).timestamp()
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+    except Exception:
+        return 0.0
+
+
+def _clean(value: object, default: str = "") -> str:
+    return str(value or default).strip()
+
+
+def _owner_id(identity: dict[str, object]) -> str:
+    return _clean(identity.get("id")) or "anonymous"
+
+
+def _task_key(owner_id: str, task_id: str) -> str:
+    return f"{owner_id}:{task_id}"
+
+
+def _collect_image_urls(data: list[Any]) -> list[str]:
+    urls: list[str] = []
+    for item in data:
+        if isinstance(item, dict):
+            url = item.get("url")
+            if isinstance(url, str) and url:
+                urls.append(url)
+    return urls
+
+
+def _public_task(task: dict[str, Any]) -> dict[str, Any]:
+    item = {
+        "id": task.get("id"),
+        "status": task.get("status"),
+        "mode": task.get("mode"),
+        "model": task.get("model"),
+        "size": task.get("size"),
+        "quality": task.get("quality"),
+        "created_at": task.get("created_at"),
+        "updated_at": task.get("updated_at"),
+    }
+    if task.get("data") is not None:
+        item["data"] = task.get("data")
+    if task.get("usage") is not None:
+        item["usage"] = task.get("usage")
+    if task.get("error"):
+        item["error"] = task.get("error")
+    return item
+
+
+class ImageTaskService:
+    def __init__(
+        self,
+        path: Path,
+        *,
+        generation_handler: Callable[[dict[str, Any]], dict[str, Any]] = openai_v1_image_generations.handle,
+        edit_handler: Callable[[dict[str, Any]], dict[str, Any]] = openai_v1_image_edit.handle,
+        retention_days_getter: Callable[[], int] | None = None,
+    ):
+        self.path = path
+        self.generation_handler = generation_handler
+        self.edit_handler = edit_handler
+        self.retention_days_getter = retention_days_getter or (lambda: config.image_retention_days)
+        self._lock = threading.RLock()
+        self._tasks: dict[str, dict[str, Any]] = {}
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._lock:
+            self._tasks = self._load_locked()
+            changed = self._recover_unfinished_locked()
+            changed = self._cleanup_locked() or changed
+            if changed:
+                self._save_locked()
+
+    def submit_generation(
+        self,
+        identity: dict[str, object],
+        *,
+        client_task_id: str,
+        prompt: str,
+        model: str,
+        size: str | None,
+        quality: str = "auto",
+        base_url: str = "",
+    ) -> dict[str, Any]:
+        payload = {
+            "prompt": prompt,
+            "model": model,
+            "n": 1,
+            "size": size,
+            "quality": quality,
+            "response_format": "url",
+            "base_url": base_url,
+        }
+        return self._submit(identity, client_task_id=client_task_id, mode="generate", payload=payload)
+
+    def submit_edit(
+        self,
+        identity: dict[str, object],
+        *,
+        client_task_id: str,
+        prompt: str,
+        model: str,
+        size: str | None,
+        quality: str = "auto",
+        base_url: str = "",
+        images: list[tuple[bytes, str, str]] | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "prompt": prompt,
+            "images": images or [],
+            "model": model,
+            "n": 1,
+            "size": size,
+            "quality": quality,
+            "response_format": "url",
+            "base_url": base_url,
+        }
+        return self._submit(identity, client_task_id=client_task_id, mode="edit", payload=payload)
+
+    def list_tasks(self, identity: dict[str, object], task_ids: list[str]) -> dict[str, Any]:
+        owner = _owner_id(identity)
+        requested_ids = [_clean(task_id) for task_id in task_ids if _clean(task_id)]
+        with self._lock:
+            if self._cleanup_locked():
+                self._save_locked()
+            items = []
+            missing_ids = []
+            for task_id in requested_ids:
+                task = self._tasks.get(_task_key(owner, task_id))
+                if task is None:
+                    missing_ids.append(task_id)
+                else:
+                    items.append(_public_task(task))
+            if not requested_ids:
+                items = [
+                    _public_task(task)
+                    for task in self._tasks.values()
+                    if task.get("owner_id") == owner
+                ]
+                items.sort(key=lambda item: str(item.get("updated_at") or ""), reverse=True)
+                missing_ids = []
+            return {"items": items, "missing_ids": missing_ids}
+
+    def _submit(
+        self,
+        identity: dict[str, object],
+        *,
+        client_task_id: str,
+        mode: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        task_id = _clean(client_task_id)
+        if not task_id:
+            raise ValueError("client_task_id is required")
+        owner = _owner_id(identity)
+        key = _task_key(owner, task_id)
+        now = _now_iso()
+        should_start = False
+        with self._lock:
+            cleaned = self._cleanup_locked()
+            task = self._tasks.get(key)
+            if task is not None:
+                if cleaned:
+                    self._save_locked()
+                return _public_task(task)
+            task = {
+                "id": task_id,
+                "owner_id": owner,
+                "status": TASK_STATUS_QUEUED,
+                "mode": mode,
+                "model": _clean(payload.get("model"), "gpt-image-2"),
+                "size": _clean(payload.get("size")),
+                "quality": _clean(payload.get("quality"), "auto"),
+                "created_at": now,
+                "updated_at": now,
+            }
+            self._tasks[key] = task
+            self._save_locked()
+            should_start = True
+
+        if should_start:
+            thread = threading.Thread(
+                target=self._run_task,
+                args=(key, mode, payload, dict(identity), _clean(payload.get("model"), "gpt-image-2")),
+                name=f"image-task-{task_id[:16]}",
+                daemon=True,
+            )
+            thread.start()
+        return _public_task(task)
+
+    def _run_task(
+        self,
+        key: str,
+        mode: str,
+        payload: dict[str, Any],
+        identity: dict[str, object],
+        model: str,
+    ) -> None:
+        started = time.time()
+        self._update_task(key, status=TASK_STATUS_RUNNING, error="")
+        try:
+            handler = self.edit_handler if mode == "edit" else self.generation_handler
+            result = handler(payload)
+            if not isinstance(result, dict):
+                raise RuntimeError("image task returned streaming result unexpectedly")
+            data = result.get("data")
+            account_email = _clean(result.get("_account_email") or result.get("account_email"))
+            if not isinstance(data, list) or not data:
+                upstream = _clean(result.get("message"))
+                if upstream:
+                    message = upstream
+                else:
+                    message = "号池中没有可用账号或所有账号均被限流，请检查号池状态（账号额度、是否被封禁、是否到达生图上限）"
+                error = RuntimeError(message)
+                if account_email:
+                    setattr(error, "account_email", account_email)
+                raise error
+            usage = result.get("usage")
+            self._update_task(key, status=TASK_STATUS_SUCCESS, data=data, usage=usage, error="")
+            self._log_call(
+                identity,
+                mode,
+                model,
+                started,
+                "调用完成",
+                request_preview=request_text(payload.get("prompt")),
+                urls=_collect_image_urls(data),
+                account_email=account_email,
+            )
+        except Exception as exc:
+            error_message = str(exc) or "image task failed"
+            account_email = _clean(getattr(exc, "account_email", ""))
+            self._update_task(key, status=TASK_STATUS_ERROR, error=error_message, data=[])
+            self._log_call(
+                identity,
+                mode,
+                model,
+                started,
+                "调用失败",
+                request_preview=request_text(payload.get("prompt")),
+                status="failed",
+                error=error_message,
+                account_email=account_email,
+            )
+
+    def _log_call(
+        self,
+        identity: dict[str, object],
+        mode: str,
+        model: str,
+        started: float,
+        suffix: str,
+        *,
+        request_preview: str = "",
+        status: str = "success",
+        error: str = "",
+        urls: list[str] | None = None,
+        account_email: str = "",
+    ) -> None:
+        endpoint = "/v1/images/edits" if mode == "edit" else "/v1/images/generations"
+        summary_prefix = "图生图" if mode == "edit" else "文生图"
+        detail = {
+            "key_id": identity.get("id"),
+            "key_name": identity.get("name"),
+            "role": identity.get("role"),
+            "endpoint": endpoint,
+            "model": model,
+            "started_at": datetime.fromtimestamp(started).strftime("%Y-%m-%d %H:%M:%S"),
+            "ended_at": _now_iso(),
+            "duration_ms": int((time.time() - started) * 1000),
+            "status": status,
+        }
+        if request_preview:
+            detail["request_text"] = request_preview
+        if error:
+            detail["error"] = error
+        if account_email:
+            detail["account_email"] = account_email
+        if urls:
+            detail["urls"] = list(dict.fromkeys(urls))
+        try:
+            log_service.add(LOG_TYPE_CALL, f"{summary_prefix}{suffix}", detail)
+        except Exception:
+            pass
+
+    def _update_task(self, key: str, **updates: Any) -> None:
+        with self._lock:
+            task = self._tasks.get(key)
+            if task is None:
+                return
+            task.update(updates)
+            task["updated_at"] = _now_iso()
+            self._save_locked()
+
+    def _load_locked(self) -> dict[str, dict[str, Any]]:
+        if not self.path.exists():
+            return {}
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except Exception:
+            return {}
+        raw_items = raw.get("tasks") if isinstance(raw, dict) else raw
+        if not isinstance(raw_items, list):
+            return {}
+        tasks: dict[str, dict[str, Any]] = {}
+        for item in raw_items:
+            if not isinstance(item, dict):
+                continue
+            task_id = _clean(item.get("id"))
+            owner = _clean(item.get("owner_id"))
+            if not task_id or not owner:
+                continue
+            status = _clean(item.get("status"))
+            if status not in {TASK_STATUS_QUEUED, TASK_STATUS_RUNNING, TASK_STATUS_SUCCESS, TASK_STATUS_ERROR}:
+                status = TASK_STATUS_ERROR
+            task = {
+                "id": task_id,
+                "owner_id": owner,
+                "status": status,
+                "mode": "edit" if item.get("mode") == "edit" else "generate",
+                "model": _clean(item.get("model"), "gpt-image-2"),
+                "size": _clean(item.get("size")),
+                "quality": _clean(item.get("quality"), "auto"),
+                "created_at": _clean(item.get("created_at"), _now_iso()),
+                "updated_at": _clean(item.get("updated_at"), _clean(item.get("created_at"), _now_iso())),
+            }
+            data = item.get("data")
+            if isinstance(data, list):
+                task["data"] = data
+            usage = item.get("usage")
+            if isinstance(usage, dict):
+                task["usage"] = usage
+            error = _clean(item.get("error"))
+            if error:
+                task["error"] = error
+            tasks[_task_key(owner, task_id)] = task
+        return tasks
+
+    def _save_locked(self) -> None:
+        items = sorted(self._tasks.values(), key=lambda item: str(item.get("updated_at") or ""), reverse=True)
+        tmp_path = self.path.with_suffix(self.path.suffix + ".tmp")
+        tmp_path.write_text(json.dumps({"tasks": items}, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        tmp_path.replace(self.path)
+
+    def _recover_unfinished_locked(self) -> bool:
+        changed = False
+        for task in self._tasks.values():
+            if task.get("status") in UNFINISHED_STATUSES:
+                task["status"] = TASK_STATUS_ERROR
+                task["error"] = "服务已重启，未完成的图片任务已中断"
+                task["updated_at"] = _now_iso()
+                changed = True
+        return changed
+
+    def _cleanup_locked(self) -> bool:
+        try:
+            retention_days = max(1, int(self.retention_days_getter()))
+        except Exception:
+            retention_days = 30
+        cutoff = time.time() - retention_days * 86400
+        removed_keys = [
+            key
+            for key, task in self._tasks.items()
+            if task.get("status") in TERMINAL_STATUSES and _timestamp(task.get("updated_at")) < cutoff
+        ]
+        for key in removed_keys:
+            self._tasks.pop(key, None)
+        return bool(removed_keys)
+
+
+image_task_service = ImageTaskService(DATA_DIR / "image_tasks.json")

services/log_service.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import itertools
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from fastapi import HTTPException
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from services.config import DATA_DIR
+from services.protocol.error_response import anthropic_error_response, openai_error_response
+from utils.helper import anthropic_sse_stream, sse_json_stream
+
+LOG_TYPE_CALL = "call"
+LOG_TYPE_ACCOUNT = "account"
+INTERNAL_RESPONSE_KEYS = {"_account_email"}
+
+
+class LogService:
+    def __init__(self, path: Path):
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def _legacy_id(raw_line: str, line_number: int) -> str:
+        payload = f"{line_number}:{raw_line}".encode("utf-8", errors="ignore")
+        return hashlib.sha1(payload).hexdigest()[:24]
+
+    def _parse_line(self, raw_line: str, line_number: int) -> dict[str, Any] | None:
+        try:
+            item = json.loads(raw_line)
+        except Exception:
+            return None
+        if not isinstance(item, dict):
+            return None
+        parsed = dict(item)
+        parsed["id"] = str(parsed.get("id") or self._legacy_id(raw_line, line_number))
+        return parsed
+
+    @staticmethod
+    def _serialize_item(item: dict[str, Any]) -> str:
+        return json.dumps(item, ensure_ascii=False, separators=(",", ":"))
+
+    @staticmethod
+    def _matches_filters(item: dict[str, Any], *, type: str = "", start_date: str = "", end_date: str = "") -> bool:
+        t = str(item.get("time") or "")
+        day = t[:10]
+        if type and item.get("type") != type:
+            return False
+        if start_date and day < start_date:
+            return False
+        if end_date and day > end_date:
+            return False
+        return True
+
+    def add(self, type: str, summary: str = "", detail: dict[str, Any] | None = None, **data: Any) -> None:
+        item = {
+            "id": uuid4().hex,
+            "time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "type": type,
+            "summary": summary,
+            "detail": detail or data,
+        }
+        with self.path.open("a", encoding="utf-8") as file:
+            file.write(self._serialize_item(item) + "\n")
+
+    def list(self, type: str = "", start_date: str = "", end_date: str = "", limit: int = 200) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        items: list[dict[str, Any]] = []
+        lines = self.path.read_text(encoding="utf-8").splitlines()
+        for line_number in range(len(lines) - 1, -1, -1):
+            item = self._parse_line(lines[line_number], line_number)
+            if item is None:
+                continue
+            if not self._matches_filters(item, type=type, start_date=start_date, end_date=end_date):
+                continue
+            items.append(item)
+            if len(items) >= limit:
+                break
+        return items
+
+    def delete(self, ids: list[str]) -> dict[str, int]:
+        target_ids = {str(item or "").strip() for item in ids if str(item or "").strip()}
+        if not self.path.exists() or not target_ids:
+            return {"removed": 0}
+        lines = self.path.read_text(encoding="utf-8").splitlines()
+        kept_lines: list[str] = []
+        removed = 0
+        for line_number, raw_line in enumerate(lines):
+            item = self._parse_line(raw_line, line_number)
+            if item is None:
+                kept_lines.append(raw_line)
+                continue
+            if str(item.get("id") or "") in target_ids:
+                removed += 1
+                continue
+            kept_lines.append(self._serialize_item(item))
+        content = "\n".join(kept_lines)
+        if content:
+            content += "\n"
+        self.path.write_text(content, encoding="utf-8")
+        return {"removed": removed}
+
+
+log_service = LogService(DATA_DIR / "logs.jsonl")
+
+
+def _collect_urls(value: object) -> list[str]:
+    urls: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key == "url" and isinstance(item, str):
+                urls.append(item)
+            elif key == "urls" and isinstance(item, list):
+                urls.extend(str(url) for url in item if isinstance(url, str))
+            else:
+                urls.extend(_collect_urls(item))
+    elif isinstance(value, list):
+        for item in value:
+            urls.extend(_collect_urls(item))
+    return urls
+
+
+def _collect_account_emails(value: object) -> list[str]:
+    emails: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in {"_account_email", "account_email"} and isinstance(item, str) and item.strip():
+                emails.append(item.strip())
+            else:
+                emails.extend(_collect_account_emails(item))
+    elif isinstance(value, list):
+        for item in value:
+            emails.extend(_collect_account_emails(item))
+    return emails
+
+
+def _strip_internal_response_fields(value: object) -> object:
+    if isinstance(value, dict):
+        return {
+            key: _strip_internal_response_fields(item)
+            for key, item in value.items()
+            if key not in INTERNAL_RESPONSE_KEYS
+        }
+    if isinstance(value, list):
+        return [_strip_internal_response_fields(item) for item in value]
+    return value
+
+
+def _request_excerpt(text: object, limit: int = 1000) -> str:
+    value = str(text or "").strip()
+    if not value:
+        return ""
+    normalized = " ".join(value.split())
+    if len(normalized) <= limit:
+        return normalized
+    return normalized[: limit - 1].rstrip() + "…"
+
+
+def _image_error_response(exc: Exception) -> JSONResponse:
+    from services.protocol.conversation import public_image_error_message
+
+    message = public_image_error_message(str(exc))
+    if "no available image quota" in message.lower():
+        return openai_error_response(
+            {
+                "error": {
+                    "message": "no available image quota",
+                    "type": "insufficient_quota",
+                    "param": None,
+                    "code": "insufficient_quota",
+                }
+            },
+            429,
+        )
+    if hasattr(exc, "to_openai_error") and hasattr(exc, "status_code"):
+        return JSONResponse(status_code=int(exc.status_code), content=exc.to_openai_error())
+    return openai_error_response(message, 502)
+
+
+def _protocol_error_response(exc: Exception, status_code: int, sse: str) -> JSONResponse:
+    message = str(exc)
+    if sse == "anthropic":
+        return anthropic_error_response(message, status_code)
+    return openai_error_response(message, status_code)
+
+
+def _next_item(items):
+    try:
+        return True, next(items)
+    except StopIteration:
+        return False, None
+
+
+@dataclass
+class LoggedCall:
+    identity: dict[str, object]
+    endpoint: str
+    model: str
+    summary: str
+    started: float = field(default_factory=time.time)
+    request_text: str = ""
+
+    async def run(self, handler, *args, sse: str = "openai"):
+        from services.protocol.conversation import ImageGenerationError
+
+        try:
+            result = await run_in_threadpool(handler, *args)
+        except ImageGenerationError as exc:
+            self.log("调用失败", status="failed", error=str(exc), account_email=getattr(exc, "account_email", ""))
+            return _image_error_response(exc)
+        except HTTPException as exc:
+            self.log("调用失败", status="failed", error=str(exc.detail))
+            raise
+        except Exception as exc:
+            self.log("调用失败", status="failed", error=str(exc), account_email=getattr(exc, "account_email", ""))
+            if self.endpoint.startswith("/v1/images"):
+                return _image_error_response(exc)
+            return _protocol_error_response(exc, 502, sse)
+
+        if isinstance(result, dict):
+            self.log("调用完成", result)
+            response = dict(result)
+            response.pop("_account_email", None)
+            return response
+
+        sender = anthropic_sse_stream if sse == "anthropic" else sse_json_stream
+        try:
+            has_first, first = await run_in_threadpool(_next_item, result)
+        except ImageGenerationError as exc:
+            self.log("调用失败", status="failed", error=str(exc), account_email=getattr(exc, "account_email", ""))
+            return _image_error_response(exc)
+        except HTTPException as exc:
+            self.log("调用失败", status="failed", error=str(exc.detail))
+            raise
+        except Exception as exc:
+            self.log("调用失败", status="failed", error=str(exc), account_email=getattr(exc, "account_email", ""))
+            if self.endpoint.startswith("/v1/images"):
+                return _image_error_response(exc)
+            return _protocol_error_response(exc, 502, sse)
+        if not has_first:
+            self.log("流式调用结束")
+            return StreamingResponse(sender(()), media_type="text/event-stream")
+        return StreamingResponse(sender(self.stream(itertools.chain([first], result))), media_type="text/event-stream")
+
+    def stream(self, items):
+        urls: list[str] = []
+        account_emails: list[str] = []
+        failed = False
+        try:
+            for item in items:
+                urls.extend(_collect_urls(item))
+                account_emails.extend(_collect_account_emails(item))
+                yield _strip_internal_response_fields(item)
+        except Exception as exc:
+            failed = True
+            self.log(
+                "流式调用失败",
+                status="failed",
+                error=str(exc),
+                urls=urls,
+                account_email=(account_emails[0] if account_emails else getattr(exc, "account_email", "")),
+            )
+            if self.endpoint.startswith("/v1/images") and not hasattr(exc, "to_openai_error"):
+                from services.protocol.conversation import ImageGenerationError, public_image_error_message
+
+                raise ImageGenerationError(public_image_error_message(str(exc))) from exc
+            raise
+        finally:
+            if not failed:
+                self.log("流式调用结束", urls=urls, account_email=account_emails[0] if account_emails else "")
+
+    def log(self, suffix: str, result: object = None, status: str = "success", error: str = "",
+            urls: list[str] | None = None, account_email: str = "") -> None:
+        detail = {
+            "key_id": self.identity.get("id"),
+            "key_name": self.identity.get("name"),
+            "role": self.identity.get("role"),
+            "endpoint": self.endpoint,
+            "model": self.model,
+            "started_at": datetime.fromtimestamp(self.started).strftime("%Y-%m-%d %H:%M:%S"),
+            "ended_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "duration_ms": int((time.time() - self.started) * 1000),
+            "status": status,
+        }
+        request_excerpt = _request_excerpt(self.request_text)
+        if request_excerpt:
+            detail["request_text"] = request_excerpt
+        if error:
+            detail["error"] = error
+        email = str(account_email or "").strip()
+        if not email:
+            emails = _collect_account_emails(result)
+            email = emails[0] if emails else ""
+        if email:
+            detail["account_email"] = email
+        collected_urls = [*(urls or []), *_collect_urls(result)]
+        if collected_urls:
+            detail["urls"] = list(dict.fromkeys(collected_urls))
+        log_service.add(LOG_TYPE_CALL, f"{self.summary}{suffix}", detail)

services/oauth_login_service.py

@@ -0,0 +1,272 @@
+"""手动 OAuth 桥服务
+
+让用户用自己浏览器走一遍 OpenAI 的标准 OAuth + PKCE 授权码流程：
+  1. 后端生成 code_verifier / code_challenge / state，构造 authorize URL。
+  2. 用户在浏览器登录，浏览器最终被 OpenAI 重定向到 platform.openai.com 的
+     callback 地址；用户从地址栏或 devtools 抓出 code，回填到前端。
+  3. 后端拿之前存好的 code_verifier + 回填的 code 调用 /api/accounts/oauth/token
+     得到 {access_token, refresh_token, id_token}。
+
+得到的 refresh_token 跟 account_service 自动刷新机制用的 client_id 是同一个
+（app_2SKx67EdpoN0G6j64rFvigXD），所以落盘后能直接进入 keepalive 周期。
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import threading
+import time
+import uuid
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+from curl_cffi import requests
+
+from services.proxy_service import proxy_settings
+from services.register.openai_register import (
+    auth_base,
+    common_headers,
+    platform_auth0_client,
+    platform_base,
+    platform_oauth_audience,
+    platform_oauth_client_id,
+    platform_oauth_redirect_uri,
+    sec_ch_ua,
+    user_agent,
+)
+
+
+class OAuthLoginError(Exception):
+    """OAuth 桥流程中的可预期错误，会被 API 层翻译成 400。"""
+
+
+class OAuthLoginService:
+    """维护 PKCE 临时会话，并完成 code → token 的兑换。"""
+
+    _SESSION_TTL_SECONDS = 10 * 60  # 用户点开浏览器 + 拿 code 给的时间上限
+    _MAX_SESSIONS = 64               # 防止异常累积；超过容量时清理最老的
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._sessions: dict[str, dict[str, Any]] = {}
+
+    @staticmethod
+    def _generate_pkce() -> tuple[str, str]:
+        """生成 PKCE code_verifier 与对应的 code_challenge（S256）。"""
+        verifier = base64.urlsafe_b64encode(secrets.token_bytes(64)).rstrip(b"=").decode("ascii")
+        challenge = base64.urlsafe_b64encode(
+            hashlib.sha256(verifier.encode("ascii")).digest()
+        ).rstrip(b"=").decode("ascii")
+        return verifier, challenge
+
+    def _purge_expired_locked(self) -> None:
+        """清理过期或溢出容量的会话，必须在持锁状态下调用。"""
+        now = time.time()
+        expired = [sid for sid, item in self._sessions.items() if now - item["created_at"] > self._SESSION_TTL_SECONDS]
+        for sid in expired:
+            self._sessions.pop(sid, None)
+        if len(self._sessions) > self._MAX_SESSIONS:
+            ordered = sorted(self._sessions.items(), key=lambda kv: kv[1]["created_at"])
+            for sid, _ in ordered[: len(self._sessions) - self._MAX_SESSIONS]:
+                self._sessions.pop(sid, None)
+
+    def start(self, email_hint: str = "") -> dict[str, str]:
+        """登记一个新的 PKCE 会话，返回 session_id 与可让用户打开的 authorize_url。
+
+        state 形如 "<session_id>.<nonce>"，让 callback URL 自带 session_id，
+        finish 时即便前端 React 状态被覆盖也能从 URL 恢复正确的 verifier。
+        """
+        verifier, challenge = self._generate_pkce()
+        nonce = secrets.token_urlsafe(32)
+        device_id = str(uuid.uuid4())
+        session_id = uuid.uuid4().hex
+        state = f"{session_id}.{secrets.token_urlsafe(16)}"
+
+        params = {
+            "issuer": auth_base,
+            "client_id": platform_oauth_client_id,
+            "audience": platform_oauth_audience,
+            "redirect_uri": platform_oauth_redirect_uri,
+            "device_id": device_id,
+            "screen_hint": "login_or_signup",
+            "max_age": "0",
+            "scope": "openid profile email offline_access",
+            "response_type": "code",
+            "response_mode": "query",
+            "state": state,
+            "nonce": nonce,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+            "auth0Client": platform_auth0_client,
+        }
+        email_hint = str(email_hint or "").strip()
+        if email_hint:
+            params["login_hint"] = email_hint
+
+        authorize_url = f"{auth_base}/api/accounts/authorize?{urlencode(params)}"
+
+        with self._lock:
+            self._purge_expired_locked()
+            self._sessions[session_id] = {
+                "code_verifier": verifier,
+                "state": state,
+                "created_at": time.time(),
+                "redirect_uri": platform_oauth_redirect_uri,
+            }
+
+        return {
+            "session_id": session_id,
+            "authorize_url": authorize_url,
+            "expires_in": str(self._SESSION_TTL_SECONDS),
+            "redirect_uri_prefix": platform_oauth_redirect_uri,
+        }
+
+    @staticmethod
+    def _extract_code_from_callback(value: str) -> tuple[str, str]:
+        """从 callback URL 或 raw code 中提取 (code, state)。
+
+        既允许用户粘贴整段 platform.openai.com/auth/callback?code=...&state=... 的 URL，
+        也允许只粘 code 本身。
+        """
+        raw = str(value or "").strip()
+        if not raw:
+            return "", ""
+        if raw.startswith("http://") or raw.startswith("https://"):
+            try:
+                parsed = parse_qs(urlparse(raw).query)
+            except Exception as exc:
+                raise OAuthLoginError(f"无法解析 callback URL: {exc}") from exc
+            code = str((parsed.get("code") or [""])[0]).strip()
+            state = str((parsed.get("state") or [""])[0]).strip()
+            if not code:
+                err = str((parsed.get("error_description") or parsed.get("error") or [""])[0]).strip()
+                raise OAuthLoginError(err or "callback URL 中没有 code 参数")
+            return code, state
+        # 用户可能直接粘了 code 字符串
+        return raw, ""
+
+    def finish(self, session_id: str, callback: str) -> dict[str, str]:
+        """用 session_id 配对的 code_verifier 把 callback 里的 code 换成 token 三件套。
+
+        - 优先用 callback URL 自带 state 里的 session_id（更可靠），
+          找不到才用前端传来的 session_id；
+        - 失败时不立刻销毁 session（OAuth code 错配换 token 失败通常不会消耗 code），
+          只有成功兑换才 pop，便于用户用同一 verifier 重试。
+        """
+        body_sid = str(session_id or "").strip()
+        code, state = self._extract_code_from_callback(callback)
+        if not code:
+            raise OAuthLoginError("缺少 code 或 callback URL")
+
+        # state 里嵌的 session_id 优先级最高
+        state_sid = state.split(".", 1)[0] if state else ""
+        candidate_sids = [sid for sid in (state_sid, body_sid) if sid]
+        if not candidate_sids:
+            raise OAuthLoginError("既未提供 session_id，callback URL 中也未携带 state")
+
+        with self._lock:
+            self._purge_expired_locked()
+            session = None
+            picked_sid = ""
+            for sid in candidate_sids:
+                cur = self._sessions.get(sid)
+                if cur is not None:
+                    session = cur
+                    picked_sid = sid
+                    break
+        if session is None:
+            raise OAuthLoginError(
+                "OAuth 会话已过期或不存在，请回到导入对话框点\"重新生成\"再走一次"
+            )
+
+        if state and session.get("state") and state != session["state"]:
+            raise OAuthLoginError(
+                "state 不匹配。常见原因：你点过两次\"打开授权页面\"，但浏览器里登录的还是前一次的窗口。请点\"重新生成\"重来。"
+            )
+
+        tokens = self._exchange_code(
+            code,
+            session["code_verifier"],
+            session.get("redirect_uri") or platform_oauth_redirect_uri,
+        )
+        # 仅在成功兑换之后才消耗 session
+        with self._lock:
+            self._sessions.pop(picked_sid, None)
+        return tokens
+
+    @staticmethod
+    def _exchange_code(code: str, code_verifier: str, redirect_uri: str) -> dict[str, str]:
+        """调用 /api/accounts/oauth/token 用 code+verifier 换 token 三件套。"""
+        kwargs = proxy_settings.build_session_kwargs(impersonate="chrome", verify=False)
+        session = requests.Session(**kwargs)
+        try:
+            response = session.post(
+                f"{auth_base}/api/accounts/oauth/token",
+                headers={
+                    **common_headers,
+                    "referer": f"{platform_base}/",
+                    "origin": platform_base,
+                    "auth0-client": platform_auth0_client,
+                    "sec-ch-ua": sec_ch_ua,
+                    "user-agent": user_agent,
+                },
+                json={
+                    "client_id": platform_oauth_client_id,
+                    "code_verifier": code_verifier,
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "redirect_uri": redirect_uri,
+                },
+                timeout=60,
+            )
+        except Exception as exc:
+            raise OAuthLoginError(f"换 token 网络异常: {exc}") from exc
+        finally:
+            session.close()
+
+        try:
+            data = response.json() if response.text else {}
+        except Exception:
+            data = {}
+
+        if response.status_code != 200 or not isinstance(data, dict) or not data.get("access_token"):
+            detail = ""
+            if isinstance(data, dict):
+                detail = str(data.get("error_description") or data.get("error") or data.get("message") or "")
+            if not detail:
+                try:
+                    detail = str(response.text or "")[:300]
+                except Exception:
+                    detail = ""
+            # 打到 docker logs 方便排错——OAuth 换 token 的失败原因往往只有这里能看到
+            print(
+                f"[oauth-login] /api/accounts/oauth/token rejected: "
+                f"status={response.status_code} detail={detail!r} "
+                f"raw_body={(getattr(response, 'text', '') or '')[:500]!r}",
+                flush=True,
+            )
+            raise OAuthLoginError(
+                f"OpenAI 拒绝换 token (HTTP {response.status_code}){': ' + detail if detail else ''}"
+            )
+
+        access_token = str(data.get("access_token") or "").strip()
+        refresh_token = str(data.get("refresh_token") or "").strip()
+        id_token = str(data.get("id_token") or "").strip()
+
+        if not access_token:
+            raise OAuthLoginError("OpenAI 返回的 access_token 为空")
+        if not refresh_token:
+            # scope 含 offline_access 时正常会下发 refresh_token；这里给出明确提示
+            raise OAuthLoginError(
+                "OpenAI 没有返回 refresh_token（可能 scope 未包含 offline_access 或 code 已使用过）"
+            )
+
+        return {
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "id_token": id_token,
+        }
+
+
+oauth_login_service = OAuthLoginService()

services/openai_backend_api.py

@@ -0,0 +1,1264 @@
+import base64
+import json
+import os
+import random
+import re
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Dict, Iterator, Optional
+
+from curl_cffi import requests
+from PIL import Image
+
+from services.account_service import account_service
+from services.config import config
+from services.proxy_service import proxy_settings
+from utils.helper import UpstreamHTTPError, ensure_ok, iter_sse_payloads, new_uuid, split_image_model
+from utils.log import logger
+from utils.pow import build_legacy_requirements_token, build_proof_token, parse_pow_resources
+from utils.turnstile import solve_turnstile_token
+
+
+class InvalidAccessTokenError(RuntimeError):
+    pass
+
+
+class ImagePollTimeoutError(RuntimeError):
+    pass
+
+
+@dataclass
+class ChatRequirements:
+    """保存一次对话请求所需的 sentinel token。"""
+    token: str
+    proof_token: str = ""
+    turnstile_token: str = ""
+    so_token: str = ""
+    raw_finalize: Optional[Dict[str, Any]] = None
+
+
+DEFAULT_CLIENT_VERSION = "prod-be885abbfcfe7b1f511e88b3003d9ee44757fbad"
+DEFAULT_CLIENT_BUILD_NUMBER = "5955942"
+DEFAULT_POW_SCRIPT = "https://chatgpt.com/backend-api/sentinel/sdk.js"
+CODEX_IMAGE_MODEL = "codex-gpt-image-2"
+CODEX_RESPONSES_MODEL = "gpt-5.5"
+CODEX_RESPONSES_INSTRUCTIONS = (
+    "Use the image_generation tool to create exactly one image for the user's request. "
+    "Return the generated image result."
+)
+
+
+class OpenAIBackendAPI:
+    """ChatGPT Web 后端封装。
+
+    说明：
+    - 传入 `access_token` 时，聊天和模型列表都会走已登录链路
+      例如 `/backend-api/sentinel/chat-requirements`、`/backend-api/conversation`
+    - 不传 `access_token` 时，会走未登录链路
+      例如 `/backend-anon/sentinel/chat-requirements`、`/backend-anon/conversation`
+    - `stream_conversation()` 是底层统一流式入口
+    - 协议兼容转换放在 `services.protocol`
+    """
+
+    def __init__(self, access_token: str = "") -> None:
+        """初始化后端客户端。
+
+        参数：
+        - `access_token`：可选。传入后表示使用已登录链路；不传则使用未登录链路。
+        """
+        self.base_url = "https://chatgpt.com"
+        self.client_version = DEFAULT_CLIENT_VERSION
+        self.client_build_number = DEFAULT_CLIENT_BUILD_NUMBER
+        self.access_token = access_token
+        self.account = account_service.get_account(self.access_token) if self.access_token else {}
+        self.account = self.account if isinstance(self.account, dict) else {}
+        self.fp = self._build_fp()
+        self.user_agent = self.fp["user-agent"]
+        self.device_id = self.fp["oai-device-id"]
+        self.session_id = self.fp["oai-session-id"]
+        self.pow_script_sources: list[str] = []
+        self.pow_data_build = ""
+        self.session = requests.Session(**proxy_settings.build_session_kwargs(
+            account=self.account,
+            impersonate=self.fp["impersonate"],
+            verify=True,
+        ))
+        self.session.headers.update({
+            "User-Agent": self.user_agent,
+            "Origin": self.base_url,
+            "Referer": self.base_url + "/",
+            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8,en-US;q=0.7",
+            "Cache-Control": "no-cache",
+            "Pragma": "no-cache",
+            "Priority": "u=1, i",
+            "Sec-Ch-Ua": self.fp["sec-ch-ua"],
+            "Sec-Ch-Ua-Arch": '"x86"',
+            "Sec-Ch-Ua-Bitness": '"64"',
+            "Sec-Ch-Ua-Full-Version": '"143.0.3650.96"',
+            "Sec-Ch-Ua-Full-Version-List": '"Microsoft Edge";v="143.0.3650.96", "Chromium";v="143.0.7499.147", "Not A(Brand";v="24.0.0.0"',
+            "Sec-Ch-Ua-Mobile": self.fp["sec-ch-ua-mobile"],
+            "Sec-Ch-Ua-Model": '""',
+            "Sec-Ch-Ua-Platform": self.fp["sec-ch-ua-platform"],
+            "Sec-Ch-Ua-Platform-Version": '"19.0.0"',
+            "Sec-Fetch-Dest": "empty",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-origin",
+            "OAI-Device-Id": self.device_id,
+            "OAI-Session-Id": self.session_id,
+            "OAI-Language": "zh-CN",
+            "OAI-Client-Version": self.client_version,
+            "OAI-Client-Build-Number": self.client_build_number,
+        })
+        if self.access_token:
+            self.session.headers["Authorization"] = f"Bearer {self.access_token}"
+
+    def _build_fp(self) -> Dict[str, str]:
+        account = self.account
+        raw_fp = account.get("fp")
+        fp = {str(k).lower(): str(v) for k, v in raw_fp.items()} if isinstance(raw_fp, dict) else {}
+        for key in (
+                "user-agent",
+                "impersonate",
+                "oai-device-id",
+                "oai-session-id",
+                "sec-ch-ua",
+                "sec-ch-ua-mobile",
+                "sec-ch-ua-platform",
+        ):
+            value = str(account.get(key) or "").strip()
+            if value:
+                fp[key] = value
+        fp.setdefault(
+            "user-agent",
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0",
+        )
+        fp.setdefault("impersonate", "edge101")
+        fp.setdefault("oai-device-id", new_uuid())
+        fp.setdefault("oai-session-id", new_uuid())
+        fp.setdefault("sec-ch-ua", '"Microsoft Edge";v="143", "Chromium";v="143", "Not A(Brand";v="24"')
+        fp.setdefault("sec-ch-ua-mobile", "?0")
+        fp.setdefault("sec-ch-ua-platform", '"Windows"')
+        return fp
+
+    def _headers(self, path: str, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """构造请求头，并补上 web 端要求的 target path/route。"""
+        headers = dict(self.session.headers)
+        headers["X-OpenAI-Target-Path"] = path
+        headers["X-OpenAI-Target-Route"] = path
+        if extra:
+            headers.update(extra)
+        return headers
+
+    @staticmethod
+    def _extract_quota_and_restore_at(limits_progress: list[Any]) -> tuple[int, str | None, bool]:
+        for item in limits_progress:
+            if isinstance(item, dict) and item.get("feature_name") == "image_gen":
+                return int(item.get("remaining") or 0), str(item.get("reset_after") or "") or None, False
+        return 0, None, True
+
+    def _get_me(self) -> Dict[str, Any]:
+        path = "/backend-api/me"
+        response = self.session.get(self.base_url + path, headers=self._headers(path), timeout=20)
+        if response.status_code != 200:
+            if response.status_code == 401:
+                raise InvalidAccessTokenError(f"{path} failed: HTTP {response.status_code}")
+            raise RuntimeError(f"{path} failed: HTTP {response.status_code}")
+        return response.json()
+
+    def _get_conversation_init(self) -> Dict[str, Any]:
+        path = "/backend-api/conversation/init"
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._headers(path, {"Content-Type": "application/json"}),
+            json={
+                "gizmo_id": None,
+                "requested_default_model": None,
+                "conversation_id": None,
+                "timezone_offset_min": -480,
+            },
+            timeout=20,
+        )
+        if response.status_code != 200:
+            if response.status_code == 401:
+                raise InvalidAccessTokenError(f"{path} failed: HTTP {response.status_code}")
+            raise RuntimeError(f"{path} failed: HTTP {response.status_code}")
+        return response.json()
+
+    def _get_default_account(self) -> Dict[str, Any]:
+        route = "/backend-api/accounts/check/v4-2023-04-27"
+        response = self.session.get(self.base_url + route + "?timezone_offset_min=-480", headers=self._headers(route),
+                                    timeout=20)
+        if response.status_code != 200:
+            if response.status_code == 401:
+                raise InvalidAccessTokenError(f"{route} failed: HTTP {response.status_code}")
+            raise RuntimeError(f"/backend-api/accounts/check failed: HTTP {response.status_code}")
+        payload = response.json()
+        logger.debug({"event": "backend_user_info_account_payload", "account_payload": payload})
+        return ((payload.get("accounts") or {}).get("default") or {}).get("account") or {}
+
+    def get_user_info(self) -> Dict[str, Any]:
+        """获取当前 token 的账号信息。"""
+        if not self.access_token:
+            raise RuntimeError("access_token is required")
+        logger.debug({"event": "backend_user_info_start"})
+        with ThreadPoolExecutor(max_workers=3) as executor:
+            me_future = executor.submit(self._get_me)
+            init_future = executor.submit(self._get_conversation_init)
+            account_future = executor.submit(self._get_default_account)
+            me_payload, init_payload, default_account = me_future.result(), init_future.result(), account_future.result()
+
+        plan_type = str(default_account.get("plan_type") or "free")
+
+        limits_progress = init_payload.get("limits_progress")
+        limits_progress = limits_progress if isinstance(limits_progress, list) else []
+        quota, restore_at, image_quota_unknown = self._extract_quota_and_restore_at(limits_progress)
+        result = {
+            "email": me_payload.get("email"),
+            "user_id": me_payload.get("id"),
+            "type": plan_type,
+            "quota": quota,
+            "image_quota_unknown": image_quota_unknown,
+            "limits_progress": limits_progress,
+            "default_model_slug": init_payload.get("default_model_slug"),
+            "restore_at": restore_at,
+            "status": "正常" if image_quota_unknown and plan_type.lower() != "free" else ("限流" if quota == 0 else "正常"),
+        }
+        logger.debug({
+            "event": "backend_user_info_result",
+            "email": result.get("email"),
+            "user_id": result.get("user_id"),
+            "type": result.get("type"),
+            "quota": result.get("quota"),
+            "image_quota_unknown": result.get("image_quota_unknown"),
+            "default_model_slug": result.get("default_model_slug"),
+            "restore_at": result.get("restore_at"),
+            "status": result.get("status"),
+        })
+        return result
+
+    def _bootstrap_headers(self) -> Dict[str, str]:
+        """构造首页预热请求头。"""
+        return {
+            "User-Agent": self.user_agent,
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+            "Sec-Ch-Ua": self.session.headers["Sec-Ch-Ua"],
+            "Sec-Ch-Ua-Mobile": self.session.headers["Sec-Ch-Ua-Mobile"],
+            "Sec-Ch-Ua-Platform": self.session.headers["Sec-Ch-Ua-Platform"],
+            "Sec-Fetch-Dest": "document",
+            "Sec-Fetch-Mode": "navigate",
+            "Sec-Fetch-Site": "none",
+            "Sec-Fetch-User": "?1",
+            "Upgrade-Insecure-Requests": "1",
+        }
+
+    def _build_requirements(self, data: Dict[str, Any], source_p: str = "") -> ChatRequirements:
+        """把 sentinel 响应整理成后续对话需要的 token 集合。"""
+        if (data.get("arkose") or {}).get("required"):
+            raise RuntimeError("chat requirements requires arkose token, which is not implemented")
+
+        proof_token = ""
+        proof_info = data.get("proofofwork") or {}
+        if proof_info.get("required"):
+            proof_token = build_proof_token(
+                proof_info.get("seed", ""),
+                proof_info.get("difficulty", ""),
+                self.user_agent,
+                script_sources=self.pow_script_sources,
+                data_build=self.pow_data_build,
+            )
+
+        turnstile_token = ""
+        turnstile_info = data.get("turnstile") or {}
+        if turnstile_info.get("required") and turnstile_info.get("dx"):
+            turnstile_token = solve_turnstile_token(turnstile_info["dx"], source_p) or ""
+
+        return ChatRequirements(
+            token=data.get("token", ""),
+            proof_token=proof_token,
+            turnstile_token=turnstile_token,
+            so_token=data.get("so_token", ""),
+            raw_finalize=data,
+        )
+
+    def _conversation_headers(self, path: str, requirements: ChatRequirements) -> Dict[str, str]:
+        """根据当前 requirements 构造对话 SSE 请求头。"""
+        headers = {
+            "Accept": "text/event-stream",
+            "Content-Type": "application/json",
+            "OpenAI-Sentinel-Chat-Requirements-Token": requirements.token,
+        }
+        if requirements.proof_token:
+            headers["OpenAI-Sentinel-Proof-Token"] = requirements.proof_token
+        if requirements.turnstile_token:
+            headers["OpenAI-Sentinel-Turnstile-Token"] = requirements.turnstile_token
+        if requirements.so_token:
+            headers["OpenAI-Sentinel-SO-Token"] = requirements.so_token
+        return self._headers(path, headers)
+
+    def _api_messages_to_conversation_messages(self, messages: list[Dict[str, Any]]) -> list[Dict[str, Any]]:
+        """把标准 chat messages 转成 web conversation 所需的 messages。"""
+        conversation_messages = []
+        for item in messages:
+            role = item.get("role", "user")
+            content = item.get("content", "")
+            if isinstance(content, str):
+                conversation_messages.append({
+                    "id": new_uuid(),
+                    "author": {"role": role},
+                    "content": {"content_type": "text", "parts": [content]},
+                })
+                continue
+            if not isinstance(content, list):
+                raise RuntimeError("only string or list message content is supported")
+            text_parts: list[str] = []
+            image_inputs: list[tuple[bytes, str]] = []
+            for part in content:
+                if not isinstance(part, dict):
+                    continue
+                part_type = str(part.get("type") or "")
+                if part_type == "text":
+                    text_parts.append(str(part.get("text") or ""))
+                elif part_type == "image":
+                    data = part.get("data")
+                    mime = str(part.get("mime") or "image/png")
+                    if isinstance(data, (bytes, bytearray)):
+                        image_inputs.append((bytes(data), mime))
+            if not image_inputs:
+                conversation_messages.append({
+                    "id": new_uuid(),
+                    "author": {"role": role},
+                    "content": {"content_type": "text", "parts": ["".join(text_parts)]},
+                })
+                continue
+            if not self.access_token:
+                raise RuntimeError("authenticated upstream account required for image input")
+            uploaded: list[Dict[str, Any]] = []
+            for idx, (data, mime) in enumerate(image_inputs, start=1):
+                ext_part = mime.split("/", 1)[1].split("+")[0] if "/" in mime else "png"
+                extension = "jpg" if ext_part == "jpeg" else (ext_part or "png")
+                b64 = base64.b64encode(data).decode("ascii")
+                uploaded.append(self._upload_image(f"data:{mime};base64,{b64}", f"image_{idx}.{extension}"))
+            parts: list[Any] = []
+            for ref in uploaded:
+                parts.append({
+                    "content_type": "image_asset_pointer",
+                    "asset_pointer": f"file-service://{ref['file_id']}",
+                    "width": ref["width"],
+                    "height": ref["height"],
+                    "size_bytes": ref["file_size"],
+                })
+            text = "".join(text_parts)
+            if text:
+                parts.append(text)
+            conversation_messages.append({
+                "id": new_uuid(),
+                "author": {"role": role},
+                "content": {"content_type": "multimodal_text", "parts": parts},
+                "metadata": {
+                    "attachments": [{
+                        "id": ref["file_id"],
+                        "mimeType": ref["mime_type"],
+                        "name": ref["file_name"],
+                        "size": ref["file_size"],
+                        "width": ref["width"],
+                        "height": ref["height"],
+                    } for ref in uploaded],
+                },
+            })
+        return conversation_messages
+
+    def _conversation_payload(self, messages: list[Dict[str, Any]], model: str, timezone: str) -> Dict[str, Any]:
+        """把标准 messages 构造成 web 对话请求体。"""
+        return {
+            "action": "next",
+            "messages": self._api_messages_to_conversation_messages(messages),
+            "model": model,
+            "parent_message_id": new_uuid(),
+            "conversation_mode": {"kind": "primary_assistant"},
+            "conversation_origin": None,
+            "force_paragen": False,
+            "force_paragen_model_slug": "",
+            "force_rate_limit": False,
+            "force_use_sse": True,
+            "history_and_training_disabled": True,
+            "reset_rate_limits": False,
+            "suggestions": [],
+            "supported_encodings": [],
+            "system_hints": [],
+            "timezone": timezone,
+            "timezone_offset_min": -480,
+            "variant_purpose": "comparison_implicit",
+            "websocket_request_id": new_uuid(),
+            "client_contextual_info": {
+                "is_dark_mode": False,
+                "time_since_loaded": 120,
+                "page_height": 900,
+                "page_width": 1400,
+                "pixel_ratio": 2,
+                "screen_height": 1440,
+                "screen_width": 2560,
+            },
+        }
+
+    def _image_model_slug(self, model: str) -> str:
+        """把标准图片模型名映射到底层 model slug。"""
+        _, base_model = split_image_model(model)
+        if not base_model:
+            return "auto"
+        if base_model == "gpt-image-2":
+            return "gpt-5-3"
+        if base_model == CODEX_IMAGE_MODEL:
+            return base_model
+        return "auto"
+
+    def _image_headers(self, path: str, requirements: ChatRequirements, conduit_token: str = "", accept: str = "*/*") -> \
+            Dict[str, str]:
+        """构造图片链路请求头。"""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": accept,
+            "OpenAI-Sentinel-Chat-Requirements-Token": requirements.token,
+        }
+        if requirements.proof_token:
+            headers["OpenAI-Sentinel-Proof-Token"] = requirements.proof_token
+        if conduit_token:
+            headers["X-Conduit-Token"] = conduit_token
+        if accept == "text/event-stream":
+            headers["X-Oai-Turn-Trace-Id"] = new_uuid()
+        return self._headers(path, headers)
+
+    def _codex_responses_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+    def _ensure_codex_source_account(self) -> None:
+        account = account_service.get_account(self.access_token)
+        source_type = str((account or {}).get("source_type") or "web").strip().lower()
+        if source_type != "codex":
+            raise RuntimeError("codex responses endpoint requires a codex source account")
+
+    @staticmethod
+    def _codex_image_input(prompt: str, images: list[str]) -> list[Dict[str, Any]]:
+        content: list[Dict[str, Any]] = [{"type": "input_text", "text": prompt}]
+        for image in images:
+            payload = image if image.startswith("data:image/") else f"data:image/png;base64,{image}"
+            content.append({"type": "input_image", "image_url": payload})
+        return [{"role": "user", "content": content}]
+
+    @staticmethod
+    def _codex_body_preview(body: Any, limit: int = 4000) -> str:
+        if isinstance(body, (dict, list)):
+            try:
+                text = json.dumps(body, ensure_ascii=False)
+            except Exception:
+                text = repr(body)
+        else:
+            text = str(body or "")
+        return text if len(text) <= limit else text[:limit] + "...[truncated]"
+
+    @staticmethod
+    def _codex_event_image_result_lengths(value: Any) -> list[int]:
+        if isinstance(value, dict):
+            lengths: list[int] = []
+            if value.get("type") == "image_generation_call" and isinstance(value.get("result"), str):
+                lengths.append(len(value["result"]))
+            for item in value.values():
+                lengths.extend(OpenAIBackendAPI._codex_event_image_result_lengths(item))
+            return lengths
+        if isinstance(value, list):
+            lengths: list[int] = []
+            for item in value:
+                lengths.extend(OpenAIBackendAPI._codex_event_image_result_lengths(item))
+            return lengths
+        return []
+
+    @staticmethod
+    def _codex_event_summary(event: Dict[str, Any]) -> Dict[str, Any]:
+        summary: Dict[str, Any] = {
+            "type": str(event.get("type") or ""),
+            "keys": list(event.keys())[:30],
+        }
+        for key in ("id", "status", "sequence_number", "response_id", "item_id", "output_index", "content_index"):
+            value = event.get(key)
+            if isinstance(value, (str, int, float, bool)) or value is None:
+                summary[key] = value
+        for key in ("response", "item", "output"):
+            value = event.get(key)
+            if isinstance(value, dict):
+                summary[f"{key}_type"] = value.get("type")
+                summary[f"{key}_status"] = value.get("status")
+                summary[f"{key}_keys"] = list(value.keys())[:30]
+            elif isinstance(value, list):
+                summary[f"{key}_len"] = len(value)
+                summary[f"{key}_types"] = [
+                    item.get("type") for item in value[:10] if isinstance(item, dict)
+                ]
+        error = event.get("error")
+        if isinstance(error, dict):
+            summary["error"] = {
+                key: error.get(key)
+                for key in ("type", "code", "message")
+                if error.get(key) is not None
+            }
+        delta = event.get("delta")
+        if isinstance(delta, str):
+            summary["delta_len"] = len(delta)
+            summary["delta_preview"] = delta[:200]
+        result_lengths = OpenAIBackendAPI._codex_event_image_result_lengths(event)
+        if result_lengths:
+            summary["image_result_lengths"] = result_lengths[:10]
+        return summary
+
+    def _log_codex_response_failure(
+            self,
+            path: str,
+            status_code: int,
+            headers: Any,
+            payload: Dict[str, Any],
+            body: Any,
+    ) -> None:
+        request_headers = self._codex_responses_headers()
+        safe_request_headers = {
+            key: value for key, value in request_headers.items() if key.lower() != "authorization"
+        }
+        response_headers = dict(headers.items()) if hasattr(headers, "items") else dict(headers or {})
+        tool = ((payload.get("tools") or [{}])[0]) if isinstance(payload.get("tools"), list) else {}
+        logger.warning({
+            "event": "codex_responses_http_error",
+            "path": path,
+            "status_code": status_code,
+            "request": {
+                "model": payload.get("model"),
+                "tool_model": tool.get("model"),
+                "tool_action": tool.get("action"),
+                "size": tool.get("size"),
+                "quality": tool.get("quality"),
+                "image_input_count": max(len((payload.get("input") or [{}])[0].get("content") or []) - 1, 0),
+                "prompt_preview": self._codex_body_preview(
+                    (((payload.get("input") or [{}])[0].get("content") or [{}])[0].get("text") or ""),
+                    500,
+                ),
+                "headers": safe_request_headers,
+            },
+            "response": {
+                "headers": response_headers,
+                "body_preview": self._codex_body_preview(body),
+            },
+        })
+
+    @staticmethod
+    def _iter_codex_response_events(raw: Any) -> Iterator[Dict[str, Any]]:
+        content_type = str(raw.headers.get("content-type") or "").lower()
+        text = raw.read().decode("utf-8", "replace")
+        status_code = getattr(raw, "status", None)
+        parse_errors: list[str] = []
+        events: list[Dict[str, Any]] = []
+        if "application/json" in content_type:
+            try:
+                data = json.loads(text)
+                if isinstance(data, dict):
+                    events.append(data)
+            except Exception as exc:
+                parse_errors.append(str(exc))
+        else:
+            lines: list[str] = []
+            for line in text.splitlines() + [""]:
+                if not line:
+                    if lines:
+                        payload_text = "\n".join(lines).strip()
+                        if payload_text and payload_text != "[DONE]":
+                            try:
+                                data = json.loads(payload_text)
+                            except Exception as exc:
+                                parse_errors.append(str(exc))
+                                data = None
+                            if isinstance(data, dict):
+                                events.append(data)
+                        lines = []
+                elif line.startswith("data:"):
+                    lines.append(line[5:].lstrip())
+
+        event_types: Dict[str, int] = {}
+        image_result_lengths: list[int] = []
+        for event in events:
+            event_type = str(event.get("type") or "<missing>")
+            event_types[event_type] = event_types.get(event_type, 0) + 1
+            image_result_lengths.extend(OpenAIBackendAPI._codex_event_image_result_lengths(event))
+        logger.info({
+            "event": "codex_responses_response_debug",
+            "status_code": status_code,
+            "content_type": content_type,
+            "response_text_len": len(text),
+            "event_count": len(events),
+            "event_types": event_types,
+            "image_result_lengths": image_result_lengths[:10],
+            "parse_error_count": len(parse_errors),
+            "parse_errors": parse_errors[:5],
+            "event_summaries": [OpenAIBackendAPI._codex_event_summary(event) for event in events[:30]],
+            "event_previews": [
+                OpenAIBackendAPI._codex_body_preview(event, 1500)
+                for event in events[:10]
+            ] if not image_result_lengths else [],
+            "body_preview": text[:1000] if not events else "",
+        })
+        for event in events:
+            yield event
+
+    def iter_codex_image_response_events(
+            self,
+            prompt: str,
+            images: list[str] | None = None,
+            size: str | None = None,
+            quality: str = "auto",
+    ) -> Iterator[Dict[str, Any]]:
+        if not self.access_token:
+            raise RuntimeError("access_token is required for codex image endpoints")
+        self._ensure_codex_source_account()
+        path = "/backend-api/codex/responses"
+        payload = {
+            "model": CODEX_RESPONSES_MODEL,
+            "instructions": CODEX_RESPONSES_INSTRUCTIONS,
+            "store": False,
+            "input": self._codex_image_input(prompt, images or []),
+            "tools": [{
+                "type": "image_generation",
+                "model": "gpt-image-2",
+                "action": "edit" if images else "generate",
+                "size": str(size or "1024x1024"),
+                "quality": str(quality or "auto"),
+                "output_format": "png",
+            }],
+            "tool_choice": {"type": "image_generation"},
+            "stream": True,
+        }
+        request = urllib.request.Request(
+            self.base_url + path,
+            json.dumps(payload).encode(),
+            self._codex_responses_headers(),
+            method="POST",
+        )
+        account = account_service.get_account(self.access_token) or {}
+        token_payload = account_service._decode_jwt_payload(self.access_token)
+        auth_claim = token_payload.get("https://api.openai.com/auth")
+        auth_claim = auth_claim if isinstance(auth_claim, dict) else {}
+        tool = payload["tools"][0]
+        logger.info({
+            "event": "codex_responses_request_debug",
+            "url": self.base_url + path,
+            "transport": "urllib.request",
+            "timeout_secs": 1200,
+            "account_email": str(account.get("email") or "").strip(),
+            "source_type": str(account.get("source_type") or "").strip(),
+            "account_type": str(account.get("type") or "").strip(),
+            "token_claims": {
+                "jti": token_payload.get("jti"),
+                "iat": token_payload.get("iat"),
+                "exp": token_payload.get("exp"),
+                "client_id": token_payload.get("client_id"),
+                "chatgpt_account_id": auth_claim.get("chatgpt_account_id"),
+                "chatgpt_plan_type": auth_claim.get("chatgpt_plan_type"),
+                "localhost": auth_claim.get("localhost"),
+            },
+            "request": {
+                "model": payload.get("model"),
+                "tool_model": tool.get("model"),
+                "tool_action": tool.get("action"),
+                "size": tool.get("size"),
+                "quality": tool.get("quality"),
+                "output_format": tool.get("output_format"),
+                "stream": payload.get("stream"),
+                "image_input_count": max(len((payload.get("input") or [{}])[0].get("content") or []) - 1, 0),
+                "prompt_preview": self._codex_body_preview(
+                    (((payload.get("input") or [{}])[0].get("content") or [{}])[0].get("text") or ""),
+                    500,
+                ),
+            },
+            "headers": {
+                key: value for key, value in self._codex_responses_headers().items()
+                if key.lower() != "authorization"
+            },
+        })
+        try:
+            with urllib.request.urlopen(request, timeout=1200) as raw:
+                yield from self._iter_codex_response_events(raw)
+        except urllib.error.HTTPError as error:
+            body_text = error.read().decode("utf-8", "replace")
+            body: Any = body_text
+            try:
+                body = json.loads(body_text)
+            except Exception:
+                pass
+            self._log_codex_response_failure(path, error.code, error.headers, payload, body)
+            retry_after_header = error.headers.get("Retry-After") if error.headers else None
+            retry_after = int(retry_after_header) if str(retry_after_header or "").isdigit() else None
+            raise UpstreamHTTPError(path, error.code, body, retry_after=retry_after) from error
+
+    def _prepare_image_conversation(self, prompt: str, requirements: ChatRequirements, model: str) -> str:
+        """为图片生成准备 conduit token。"""
+        path = "/backend-api/f/conversation/prepare"
+        payload = {
+            "action": "next",
+            "fork_from_shared_post": False,
+            "parent_message_id": new_uuid(),
+            "model": self._image_model_slug(model),
+            "client_prepare_state": "success",
+            "timezone_offset_min": -480,
+            "timezone": "Asia/Shanghai",
+            "conversation_mode": {"kind": "primary_assistant"},
+            "system_hints": ["picture_v2"],
+            "partial_query": {
+                "id": new_uuid(),
+                "author": {"role": "user"},
+                "content": {"content_type": "text", "parts": [prompt]},
+            },
+            "supports_buffering": True,
+            "supported_encodings": ["v1"],
+            "client_contextual_info": {"app_name": "chatgpt.com"},
+        }
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._image_headers(path, requirements),
+            json=payload,
+            timeout=60,
+        )
+        ensure_ok(response, path)
+        return response.json().get("conduit_token", "")
+
+    def _decode_image_base64(self, image: str) -> bytes:
+        """把 base64 图片字符串或本地路径解码成二进制。"""
+        if (
+                image
+                and len(image) < 512
+                and not image.startswith("data:")
+                and "\n" not in image
+                and "\r" not in image
+        ):
+            file_path = Path(os.path.expanduser(image))
+            if file_path.exists() and file_path.is_file():
+                return file_path.read_bytes()
+        payload = image.split(",", 1)[1] if image.startswith("data:") and "," in image else image
+        return base64.b64decode(payload)
+
+    def _upload_image(self, image: str, file_name: str = "image.png") -> Dict[str, Any]:
+        """上传一张 base64 图片，返回底层文件元数据。"""
+        data = self._decode_image_base64(image)
+        if (
+                image
+                and len(image) < 512
+                and not image.startswith("data:")
+                and "\n" not in image
+                and "\r" not in image
+        ):
+            candidate_path = Path(os.path.expanduser(image))
+            if candidate_path.exists() and candidate_path.is_file():
+                file_name = candidate_path.name
+        image = Image.open(BytesIO(data))
+        width, height = image.size
+        mime_type = Image.MIME.get(image.format, "image/png")
+        path = "/backend-api/files"
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._headers(path, {"Content-Type": "application/json", "Accept": "application/json"}),
+            json={"file_name": file_name, "file_size": len(data), "use_case": "multimodal", "width": width,
+                  "height": height},
+            timeout=60,
+        )
+        ensure_ok(response, path)
+        upload_meta = response.json()
+        time.sleep(0.5)
+        response = self.session.put(
+            upload_meta["upload_url"],
+            headers={
+                "Content-Type": mime_type,
+                "x-ms-blob-type": "BlockBlob",
+                "x-ms-version": "2020-04-08",
+                "Origin": self.base_url,
+                "Referer": self.base_url + "/",
+                "User-Agent": self.user_agent,
+                "Accept": "application/json, text/plain, */*",
+                "Accept-Language": "en-US,en;q=0.8",
+            },
+            data=data,
+            timeout=120,
+        )
+        ensure_ok(response, "image_upload")
+        path = f"/backend-api/files/{upload_meta['file_id']}/uploaded"
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._headers(path, {"Content-Type": "application/json", "Accept": "application/json"}),
+            data="{}",
+            timeout=60,
+        )
+        ensure_ok(response, path)
+        return {
+            "file_id": upload_meta["file_id"],
+            "file_name": file_name,
+            "file_size": len(data),
+            "mime_type": mime_type,
+            "width": width,
+            "height": height,
+        }
+
+    def _start_image_generation(self, prompt: str, requirements: ChatRequirements, conduit_token: str, model: str,
+                                references: Optional[list[Dict[str, Any]]] = None) -> requests.Response:
+        """启动图片生成或编辑的 SSE 请求。"""
+        references = references or []
+        parts = [{
+            "content_type": "image_asset_pointer",
+            "asset_pointer": f"file-service://{item['file_id']}",
+            "width": item["width"],
+            "height": item["height"],
+            "size_bytes": item["file_size"],
+        } for item in references]
+        parts.append(prompt)
+        content = {"content_type": "multimodal_text", "parts": parts} if references else {"content_type": "text",
+                                                                                          "parts": [prompt]}
+        metadata = {
+            "developer_mode_connector_ids": [],
+            "selected_github_repos": [],
+            "selected_all_github_repos": False,
+            "system_hints": ["picture_v2"],
+            "serialization_metadata": {"custom_symbol_offsets": []},
+        }
+        if references:
+            metadata["attachments"] = [{
+                "id": item["file_id"],
+                "mimeType": item["mime_type"],
+                "name": item["file_name"],
+                "size": item["file_size"],
+                "width": item["width"],
+                "height": item["height"],
+            } for item in references]
+        payload = {
+            "action": "next",
+            "messages": [{
+                "id": new_uuid(),
+                "author": {"role": "user"},
+                "create_time": time.time(),
+                "content": content,
+                "metadata": metadata,
+            }],
+            "parent_message_id": new_uuid(),
+            "model": self._image_model_slug(model),
+            "client_prepare_state": "sent",
+            "timezone_offset_min": -480,
+            "timezone": "Asia/Shanghai",
+            "conversation_mode": {"kind": "primary_assistant"},
+            "enable_message_followups": True,
+            "system_hints": ["picture_v2"],
+            "supports_buffering": True,
+            "supported_encodings": ["v1"],
+            "client_contextual_info": {
+                "is_dark_mode": False,
+                "time_since_loaded": 1200,
+                "page_height": 1072,
+                "page_width": 1724,
+                "pixel_ratio": 1.2,
+                "screen_height": 1440,
+                "screen_width": 2560,
+                "app_name": "chatgpt.com",
+            },
+            "paragen_cot_summary_display_override": "allow",
+            "force_parallel_switch": "auto",
+        }
+        path = "/backend-api/f/conversation"
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._image_headers(path, requirements, conduit_token, "text/event-stream"),
+            json=payload,
+            timeout=300,
+            stream=True,
+        )
+        ensure_ok(response, path)
+        return response
+
+    def _get_conversation(self, conversation_id: str) -> Dict[str, Any]:
+        """获取完整 conversation 详情。"""
+        path = f"/backend-api/conversation/{conversation_id}"
+        response = self.session.get(self.base_url + path, headers=self._headers(path, {"Accept": "application/json"}),
+                                    timeout=60)
+        ensure_ok(response, path)
+        return response.json()
+
+    def _extract_image_tool_records(self, data: Dict[str, Any]) -> list[Dict[str, Any]]:
+        """从 conversation 明细里提取图片工具输出记录。"""
+        mapping = data.get("mapping") or {}
+        file_pat = re.compile(r"file-service://([A-Za-z0-9_-]+)")
+        sed_pat = re.compile(r"sediment://([A-Za-z0-9_-]+)")
+        records = []
+        for message_id, node in mapping.items():
+            message = (node or {}).get("message") or {}
+            author = message.get("author") or {}
+            metadata = message.get("metadata") or {}
+            content = message.get("content") or {}
+            if author.get("role") != "tool":
+                continue
+            if content.get("content_type") != "multimodal_text":
+                continue
+            file_ids, sediment_ids = [], []
+            for part in content.get("parts") or []:
+                text = (part.get("asset_pointer") or "") if isinstance(part, dict) else (
+                    part if isinstance(part, str) else "")
+                for hit in file_pat.findall(text):
+                    if hit not in file_ids:
+                        file_ids.append(hit)
+                for hit in sed_pat.findall(text):
+                    if hit not in sediment_ids:
+                        sediment_ids.append(hit)
+            if metadata.get("async_task_type") != "image_gen" and not file_ids and not sediment_ids:
+                continue
+            records.append(
+                {"message_id": message_id, "create_time": message.get("create_time") or 0, "file_ids": file_ids,
+                 "sediment_ids": sediment_ids})
+        return sorted(records, key=lambda item: item["create_time"])
+
+    def _poll_image_results(self, conversation_id: str, timeout_secs: float = 120.0) -> tuple[list[str], list[str]]:
+        """Poll the conversation document until image file ids appear or budget runs out.
+
+        - Sleeps image_poll_initial_wait_secs first (default 10s, +jitter). ChatGPT
+          image generation takes ~30s; polling immediately wastes requests and trips
+          a transient 429 the upstream returns within ~200ms of the SSE stream
+          closing (the conversation document is not yet committed).
+        - Subsequent polls are image_poll_interval_secs apart (default 10s).
+        - On upstream 429 / 5xx or network errors, backs off exponentially
+          (capped at 16s, +jitter) honoring Retry-After when present.
+        - All sleeps stay within timeout_secs; on exhaustion raises ImagePollTimeoutError.
+        """
+        start = time.time()
+        attempt = 0
+        interval = float(config.image_poll_interval_secs)
+        initial_wait = float(config.image_poll_initial_wait_secs)
+        logger.info({
+            "event": "image_poll_start",
+            "conversation_id": conversation_id,
+            "timeout_secs": timeout_secs,
+            "initial_wait_secs": initial_wait,
+            "interval_secs": interval,
+        })
+
+        def _remaining() -> float:
+            return timeout_secs - (time.time() - start)
+
+        if initial_wait > 0:
+            jitter = random.uniform(0, min(2.0, initial_wait * 0.2))
+            sleep_for = min(initial_wait + jitter, max(0.0, _remaining()))
+            if sleep_for > 0:
+                time.sleep(sleep_for)
+
+        def _retry_sleep(reason: str, status_code: int | None, error: str | None, retry_after: int | None) -> bool:
+            # retry_after=0 means "retry immediately" — must not be coerced via falsy check.
+            base = retry_after if retry_after is not None else min(2 ** min(attempt, 4), 16)
+            backoff = base + random.uniform(0, 0.5)
+            remaining = _remaining()
+            if remaining <= 0:
+                return False
+            sleep_for = min(backoff, remaining)
+            log_payload: Dict[str, Any] = {
+                "event": "image_poll_retry",
+                "conversation_id": conversation_id,
+                "attempt": attempt,
+                "reason": reason,
+                "sleep_secs": round(sleep_for, 2),
+            }
+            if status_code is not None:
+                log_payload["status_code"] = status_code
+            if error is not None:
+                log_payload["error"] = error
+            logger.warning(log_payload)
+            time.sleep(sleep_for)
+            return True
+
+        while _remaining() > 0:
+            attempt += 1
+            try:
+                conversation = self._get_conversation(conversation_id)
+            except UpstreamHTTPError as exc:
+                if exc.status_code in (429, 500, 502, 503, 504):
+                    if _retry_sleep("upstream_status", exc.status_code, None, exc.retry_after):
+                        continue
+                    break
+                raise
+            except requests.exceptions.RequestException as exc:
+                if _retry_sleep("network", None, str(exc), None):
+                    continue
+                break
+
+            file_ids, sediment_ids = [], []
+            for record in self._extract_image_tool_records(conversation):
+                for file_id in record["file_ids"]:
+                    if file_id not in file_ids:
+                        file_ids.append(file_id)
+                for sediment_id in record["sediment_ids"]:
+                    if sediment_id not in sediment_ids:
+                        sediment_ids.append(sediment_id)
+            logger.debug({"event": "image_poll_check", "conversation_id": conversation_id, "attempt": attempt,
+                          "file_ids": file_ids, "sediment_ids": sediment_ids})
+            if file_ids:
+                logger.info({"event": "image_poll_hit", "conversation_id": conversation_id, "file_ids": file_ids,
+                             "sediment_ids": sediment_ids})
+                return file_ids, sediment_ids
+            if sediment_ids:
+                logger.info({"event": "image_poll_hit", "conversation_id": conversation_id, "file_ids": [],
+                             "sediment_ids": sediment_ids})
+                return [], sediment_ids
+            logger.debug({"event": "image_poll_wait", "conversation_id": conversation_id,
+                          "elapsed_secs": round(time.time() - start, 1)})
+            wait = min(interval, max(0.0, _remaining()))
+            if wait > 0:
+                time.sleep(wait)
+        logger.info({
+            "event": "image_poll_timeout",
+            "conversation_id": conversation_id,
+            "timeout_secs": timeout_secs,
+            "attempts_made": attempt,
+            # attempts_made == 0 means the initial_wait consumed the entire budget — no HTTP attempted.
+            "initial_wait_exhausted_budget": attempt == 0,
+        })
+        raise ImagePollTimeoutError(
+            f"ChatGPT 生图超时（已等待 {timeout_secs} 秒）。"
+            f"当前超时阈值可在 config.json 中调大 image_poll_timeout_secs，"
+            f"也可能是账号被限流或生图队列拥堵导致。"
+        )
+
+    def _get_file_download_url(self, file_id: str) -> str:
+        """获取文件下载地址。"""
+        path = f"/backend-api/files/{file_id}/download"
+        response = self.session.get(self.base_url + path, headers=self._headers(path, {"Accept": "application/json"}),
+                                    timeout=60)
+        ensure_ok(response, path)
+        data = response.json()
+        return data.get("download_url") or data.get("url") or ""
+
+    def _get_attachment_download_url(self, conversation_id: str, attachment_id: str) -> str:
+        """通过 conversation 附件接口获取下载地址。"""
+        path = f"/backend-api/conversation/{conversation_id}/attachment/{attachment_id}/download"
+        response = self.session.get(self.base_url + path, headers=self._headers(path, {"Accept": "application/json"}),
+                                    timeout=60)
+        ensure_ok(response, path)
+        data = response.json()
+        return data.get("download_url") or data.get("url") or ""
+
+    def _resolve_image_urls(self, conversation_id: str, file_ids: list[str], sediment_ids: list[str]) -> list[str]:
+        """把图片结果 id 解析成可下载 URL。"""
+        urls = []
+        skip_patterns = {"file_upload"}
+        for file_id in file_ids:
+            if file_id in skip_patterns:
+                logger.debug({
+                    "event": "image_file_id_skipped",
+                    "source": "file",
+                    "conversation_id": conversation_id,
+                    "id": file_id,
+                })
+                continue
+            try:
+                url = self._get_file_download_url(file_id)
+            except Exception as exc:
+                logger.debug({
+                    "event": "image_download_url_failed",
+                    "source": "file",
+                    "conversation_id": conversation_id,
+                    "id": file_id,
+                    "error": repr(exc),
+                })
+                continue
+            if url:
+                urls.append(url)
+            else:
+                logger.debug({
+                    "event": "image_download_url_empty",
+                    "source": "file",
+                    "conversation_id": conversation_id,
+                    "id": file_id,
+                })
+        if urls or not conversation_id:
+            logger.debug({
+                "event": "image_urls_resolved",
+                "conversation_id": conversation_id,
+                "file_ids": file_ids,
+                "sediment_ids": sediment_ids,
+                "urls": urls,
+            })
+            return urls
+        for sediment_id in sediment_ids:
+            try:
+                url = self._get_attachment_download_url(conversation_id, sediment_id)
+            except Exception as exc:
+                logger.debug({
+                    "event": "image_download_url_failed",
+                    "source": "sediment",
+                    "conversation_id": conversation_id,
+                    "id": sediment_id,
+                    "error": repr(exc),
+                })
+                continue
+            if url:
+                urls.append(url)
+            else:
+                logger.debug({
+                    "event": "image_download_url_empty",
+                    "source": "sediment",
+                    "conversation_id": conversation_id,
+                    "id": sediment_id,
+                })
+        logger.debug({
+            "event": "image_urls_resolved",
+            "conversation_id": conversation_id,
+            "file_ids": file_ids,
+            "sediment_ids": sediment_ids,
+            "urls": urls,
+        })
+        return urls
+
+    def resolve_conversation_image_urls(
+            self,
+            conversation_id: str,
+            file_ids: list[str],
+            sediment_ids: list[str],
+            poll: bool = True,
+    ) -> list[str]:
+        file_ids = [item for item in file_ids if item != "file_upload"]
+        sediment_ids = list(sediment_ids)
+        if poll and conversation_id and not file_ids and not sediment_ids:
+            logger.info({"event": "image_resolve_poll_needed", "conversation_id": conversation_id})
+            polled_file_ids, polled_sediment_ids = self._poll_image_results(conversation_id,
+                                                                            config.image_poll_timeout_secs)
+            file_ids.extend(item for item in polled_file_ids if item and item not in file_ids)
+            sediment_ids.extend(item for item in polled_sediment_ids if item and item not in sediment_ids)
+        return self._resolve_image_urls(conversation_id, file_ids, sediment_ids)
+
+    def download_image_bytes(self, urls: list[str]) -> list[bytes]:
+        images = []
+        for url in urls:
+            response = self.session.get(url, timeout=120)
+            ensure_ok(response, "image_download")
+            images.append(response.content)
+        return images
+
+    def stream_conversation(
+            self,
+            messages: Optional[list[Dict[str, Any]]] = None,
+            model: str = "auto",
+            prompt: str = "",
+            images: Optional[list[str]] = None,
+            system_hints: Optional[list[str]] = None,
+    ) -> Iterator[str]:
+        system_hints = system_hints or []
+        if "picture_v2" in system_hints:
+            yield from self._stream_picture_conversation(prompt, model, images or [])
+            return
+
+        normalized = messages or [{"role": "user", "content": prompt}]
+        self._bootstrap()
+        requirements = self._get_chat_requirements()
+        path, timezone = self._chat_target()
+        payload = self._conversation_payload(normalized, model, timezone)
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._conversation_headers(path, requirements),
+            json=payload,
+            timeout=300,
+            stream=True,
+        )
+        ensure_ok(response, path)
+        try:
+            yield from iter_sse_payloads(response)
+        finally:
+            response.close()
+
+    def _stream_picture_conversation(
+            self,
+            prompt: str,
+            model: str,
+            images: list[str],
+    ) -> Iterator[str]:
+        if not self.access_token:
+            raise RuntimeError("access_token is required for image endpoints")
+        references = [self._upload_image(image, f"image_{idx}.png") for idx, image in enumerate(images, start=1)]
+        self._bootstrap()
+        requirements = self._get_chat_requirements()
+        conduit_token = self._prepare_image_conversation(prompt, requirements, model)
+        response = self._start_image_generation(prompt, requirements, conduit_token, model, references)
+        try:
+            yield from iter_sse_payloads(response)
+        finally:
+            response.close()
+
+    def _bootstrap(self) -> None:
+        """预热首页，并提取 PoW 相关脚本引用。"""
+        response = self.session.get(
+            self.base_url + "/",
+            headers=self._bootstrap_headers(),
+            timeout=30,
+        )
+        ensure_ok(response, "bootstrap")
+        self.pow_script_sources, self.pow_data_build = parse_pow_resources(response.text)
+        if not self.pow_script_sources:
+            self.pow_script_sources = [DEFAULT_POW_SCRIPT]
+
+    def _get_chat_requirements(self) -> ChatRequirements:
+        """获取当前模式对话所需的 sentinel token。"""
+        path = "/backend-api/sentinel/chat-requirements" if self.access_token else "/backend-anon/sentinel/chat-requirements"
+        context = "auth_chat_requirements" if self.access_token else "noauth_chat_requirements"
+        body = {"p": build_legacy_requirements_token(self.user_agent, self.pow_script_sources, self.pow_data_build)}
+        response = self.session.post(
+            self.base_url + path,
+            headers=self._headers(path, {"Content-Type": "application/json"}),
+            json=body,
+            timeout=30,
+        )
+        ensure_ok(response, context)
+        requirements = self._build_requirements(response.json(), "" if self.access_token else body["p"])
+        if not requirements.token:
+            message = "missing auth chat requirements token" if self.access_token else "missing chat requirements token"
+            raise RuntimeError(f"{message}: {requirements.raw_finalize}")
+        return requirements
+
+    def _chat_target(self) -> tuple[str, str]:
+        if self.access_token:
+            return "/backend-api/conversation", "Asia/Shanghai"
+        return "/backend-anon/conversation", "America/Los_Angeles"
+
+    def list_models(self) -> Dict[str, Any]:
+        """返回当前模式下可用模型，格式对齐 OpenAI `/v1/models`。"""
+        self._bootstrap()
+        path = "/backend-api/models?history_and_training_disabled=false" if self.access_token else (
+            "/backend-anon/models?iim=false&is_gizmo=false"
+        )
+        route = "/backend-api/models" if self.access_token else "/backend-anon/models"
+        context = "auth_models" if self.access_token else "anon_models"
+        response = self.session.get(
+            self.base_url + path,
+            headers=self._headers(route),
+            timeout=30,
+        )
+        ensure_ok(response, context)
+        data = []
+        seen = set()
+        for item in response.json().get("models", []):
+            if not isinstance(item, dict):
+                continue
+            slug = str(item.get("slug", "")).strip()
+            if not slug or slug in seen:
+                continue
+            seen.add(slug)
+            data.append({
+                "id": slug,
+                "object": "model",
+                "created": int(item.get("created") or 0),
+                "owned_by": str(item.get("owned_by") or "chatgpt"),
+                "permission": [],
+                "root": slug,
+                "parent": None,
+            })
+        data.sort(key=lambda item: item["id"])
+        return {"object": "list", "data": data}

services/protocol/__init__.py

@@ -0,0 +1,2 @@
+"""Protocol converters for OpenAI-compatible endpoints."""
+

services/protocol/anthropic_v1_messages.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import html
+import json
+import re
+import time
+import uuid
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from services.account_service import account_service
+from services.openai_backend_api import OpenAIBackendAPI
+from services.protocol.conversation import count_message_tokens, count_text_tokens, normalize_messages
+from services.protocol.openai_v1_chat_complete import collect_chat_content, stream_text_chat_completion
+
+XML_TOOL_RULE = """Tool output adapter: when calling tools, output ONLY this XML and no prose/markdown:
+<tool_calls><tool_call><tool_name>TOOL_NAME</tool_name><parameters><PARAM><![CDATA[value]]></PARAM></parameters></tool_call></tool_calls>"""
+
+
+@dataclass
+class MessageRequest:
+    backend: OpenAIBackendAPI
+    messages: list[dict[str, Any]]
+    model: str
+    tools: Any = None
+
+
+def _tool_meta(tool: dict[str, object]) -> tuple[str, str, object]:
+    fn = tool.get("function") if isinstance(tool.get("function"), dict) else {}
+    name = str(tool.get("name") or fn.get("name") or "").strip()
+    desc = str(tool.get("description") or fn.get("description") or "").strip()
+    schema = tool.get("input_schema") or tool.get("parameters") or fn.get("input_schema") or fn.get("parameters") or {}
+    return name, desc, schema
+
+
+def build_tool_prompt(tools: object) -> str:
+    if not isinstance(tools, list):
+        return ""
+    blocks = []
+    for tool in tools:
+        if not isinstance(tool, dict):
+            continue
+        name, desc, schema = _tool_meta(tool)
+        if name:
+            blocks.append(f"Tool: {name}\nDescription: {desc}\nParameters: {json.dumps(schema, ensure_ascii=False)}")
+    if not blocks:
+        return ""
+    return "Available tools:\n" + "\n".join(blocks) + """
+
+Tool use rules:
+- If the user asks to list/read/search files, inspect project state, run a command, or answer from local code, you MUST call a suitable tool first. Do not say you cannot access files.
+- To call tools, output ONLY XML and no prose/markdown:
+<tool_calls><tool_call><tool_name>TOOL_NAME</tool_name><parameters><PARAM><![CDATA[value]]></PARAM></parameters></tool_call></tool_calls>
+- Put parameters under <parameters> using the exact schema names.
+""".strip()
+
+
+def merge_system(system: object, extra: str) -> object:
+    system = compact_system(system)
+    if _has_claude_code_system(system):
+        extra = XML_TOOL_RULE
+    if not extra:
+        return system
+    if isinstance(system, str) and system.strip():
+        return f"{system.strip()}\n\n{extra}"
+    if isinstance(system, list):
+        return [*system, {"type": "text", "text": extra}]
+    return extra
+
+
+def _has_claude_code_system(system: object) -> bool:
+    if isinstance(system, str):
+        return "You are Claude Code" in system
+    if isinstance(system, list):
+        return any(isinstance(item, dict) and "You are Claude Code" in str(item.get("text") or "") for item in system)
+    return False
+
+
+def compact_system(system: object) -> object:
+    if isinstance(system, str):
+        return _compact_system_text(system)
+    if isinstance(system, list):
+        result = []
+        for item in system:
+            if isinstance(item, dict) and str(item.get("type") or "") == "text":
+                copied = dict(item)
+                copied["text"] = _compact_system_text(str(item.get("text") or ""))
+                result.append(copied)
+            else:
+                result.append(item)
+        return result
+    return system
+
+
+def _compact_system_text(text: str) -> str:
+    return text or ""
+
+
+def _compact_message_text(text: str) -> str:
+    return text or ""
+
+
+def preprocess_payload(payload: dict[str, object], text_mapper: Callable[[str], str] | None = None) -> dict[str, object]:
+    payload["messages"] = preprocess_messages(payload.get("messages"), text_mapper)
+    payload["system"] = merge_system(payload.get("system"), build_tool_prompt(payload.get("tools")))
+    return payload
+
+
+def message_request(body: dict[str, Any]) -> MessageRequest:
+    payload = preprocess_payload(dict(body))
+    return MessageRequest(
+        backend=OpenAIBackendAPI(access_token=account_service.get_text_access_token()),
+        messages=normalize_messages(payload.get("messages"), payload.get("system")),
+        model=str(payload.get("model") or "auto").strip() or "auto",
+        tools=payload.get("tools"),
+    )
+
+
+def preprocess_messages(messages: object, text_mapper: Callable[[str], str] | None = None) -> object:
+    if not isinstance(messages, list):
+        return messages
+    mapper = text_mapper or (lambda text: text)
+    result = []
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        item = dict(message)
+        content = item.get("content")
+        if isinstance(content, str):
+            item["content"] = _compact_message_text(mapper(content))
+        elif isinstance(content, list):
+            item["content"] = [_preprocess_block(block, mapper) for block in content]
+        result.append(item)
+    return result
+
+
+def _preprocess_block(block: object, text_mapper: Callable[[str], str]) -> object:
+    if not isinstance(block, dict):
+        return block
+    block_type = str(block.get("type") or "")
+    if block_type == "text":
+        item = dict(block)
+        item["text"] = _compact_message_text(text_mapper(str(block.get("text") or "")))
+        return item
+    if block_type == "tool_use":
+        return {"type": "text", "text": f"<tool_calls><tool_call><tool_name>{block.get('name') or ''}</tool_name><parameters>{json.dumps(block.get('input') or {}, ensure_ascii=False)}</parameters></tool_call></tool_calls>"}
+    if block_type == "tool_result":
+        return {"type": "text", "text": f"Tool result {block.get('tool_use_id') or ''}: {block.get('content') or ''}"}
+    return block
+
+
+def message_response(model: str, text: str, input_tokens: int, output_tokens: int, tools: object = None) -> dict[str, object]:
+    content, stop_reason = content_blocks(text, tools)
+    return {
+        "id": f"msg_{uuid.uuid4()}",
+        "type": "message",
+        "role": "assistant",
+        "model": model,
+        "content": content,
+        "stop_reason": stop_reason,
+        "stop_sequence": None,
+        "usage": {"input_tokens": input_tokens, "output_tokens": output_tokens},
+    }
+
+
+def content_blocks(text: str, tools: object = None) -> tuple[list[dict[str, object]], str]:
+    calls = parse_tool_calls(text) if isinstance(tools, list) and tools else []
+    text = strip_tool_markup(text)
+    if calls:
+        content = ([{"type": "text", "text": text}] if text else []) + [{"type": "tool_use", "id": f"toolu_{uuid.uuid4()}", "name": name, "input": args} for name, args in calls]
+        return content, "tool_use"
+    return [{"type": "text", "text": text}], "end_turn"
+
+
+def strip_tool_markup(text: str) -> str:
+    return re.sub(r"(?is)<tool_calls\b[^>]*>.*?</tool_calls>|<tool_call\b[^>]*>.*?</tool_call>|<function_call\b[^>]*>.*?</function_call>|<invoke\b[^>]*>.*?</invoke>", "", text or "").strip()
+
+
+def streamable_text(text: str) -> str:
+    text = text or ""
+    match = re.search(r"(?is)<tool_calls\b|<tool_call\b|<function_call\b|<invoke\b", text)
+    return text[:match.start()].rstrip() if match else text
+
+
+def parse_tool_calls(text: str) -> list[tuple[str, dict[str, object]]]:
+    text = re.sub(r"(?is)```.*?```", "", text or "").strip()
+    blocks = re.findall(r"(?is)<tool_call\b[^>]*>(.*?)</tool_call>|<function_call\b[^>]*>(.*?)</function_call>|<invoke\b[^>]*>(.*?)</invoke>", text)
+    result = []
+    for block in (next((part for part in match if part), "") for match in blocks):
+        name = xml_value(block, "tool_name") or xml_value(block, "name") or xml_value(block, "function")
+        params = xml_value(block, "parameters") or xml_value(block, "input") or xml_value(block, "arguments") or "{}"
+        if name:
+            result.append((name, parse_tool_params(params)))
+    return result
+
+
+def xml_value(text: str, tag: str) -> str:
+    match = re.search(rf"(?is)<{tag}\b[^>]*>(.*?)</{tag}>", text)
+    if not match:
+        return ""
+    value = match.group(1).strip()
+    cdata = re.fullmatch(r"(?is)<!\[CDATA\[(.*?)]]>", value)
+    return html.unescape(cdata.group(1) if cdata else value).strip()
+
+
+def parse_tool_params(raw: str) -> dict[str, object]:
+    raw = raw.strip()
+    try:
+        parsed = json.loads(raw)
+        return parsed if isinstance(parsed, dict) else {}
+    except Exception:
+        return {m.group(1): parse_tool_value(m.group(2)) for m in re.finditer(r"(?is)<([\w.-]+)\b[^>]*>(.*?)</\1>", raw)}
+
+
+def parse_tool_value(raw: str) -> object:
+    value = xml_value(f"<x>{raw}</x>", "x")
+    try:
+        return json.loads(value)
+    except Exception:
+        return value
+
+
+def stream_events(chunks: Iterable[dict[str, object]], model: str, input_tokens: int, output_tokens: Callable[[str], int], tools: object = None) -> Iterator[dict[str, object]]:
+    message_id = f"msg_{uuid.uuid4()}"
+    created = int(time.time())
+    current_text = ""
+    streamed_text = ""
+    tool_mode = isinstance(tools, list) and bool(tools)
+    tool_started = False
+    text_open = False
+    yield {"type": "message_start", "message": {"id": message_id, "type": "message", "role": "assistant", "model": model, "content": [], "stop_reason": None, "stop_sequence": None, "usage": {"input_tokens": input_tokens, "output_tokens": 0}}}
+    if not tool_mode:
+        text_open = True
+        yield {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
+    for chunk in chunks:
+        choice = (chunk.get("choices") or [{}])[0]
+        delta = choice.get("delta") or {}
+        text_delta = delta.get("content", "") if isinstance(delta, dict) else ""
+        if text_delta:
+            current_text += text_delta
+            if not tool_started:
+                visible_text = current_text if not tool_mode else streamable_text(current_text)
+                if visible_text.startswith(streamed_text):
+                    text_delta = visible_text[len(streamed_text):]
+                    if text_delta:
+                        if not text_open:
+                            text_open = True
+                            yield {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
+                        streamed_text = visible_text
+                        yield {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": text_delta}}
+                tool_started = tool_mode and visible_text != current_text
+        if choice.get("finish_reason"):
+            content, stop_reason = content_blocks(current_text, tools)
+            if text_open:
+                yield {"type": "content_block_stop", "index": 0}
+            if stop_reason == "tool_use":
+                start_index = 1 if text_open else 0
+                if content and content[0]["type"] == "text":
+                    remaining = str(content[0].get("text") or "")[len(streamed_text):]
+                    if remaining:
+                        if not text_open:
+                            yield {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
+                        yield {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": remaining}}
+                        if not text_open:
+                            yield {"type": "content_block_stop", "index": 0}
+                    start_index = 1
+                    content = content[1:]
+                yield from _stream_buffered_blocks(content, start_index)
+            yield {"type": "message_delta", "delta": {"stop_reason": stop_reason, "stop_sequence": None}, "usage": {"output_tokens": output_tokens(current_text)}}
+            break
+    yield {"type": "message_stop", "created": created}
+
+
+def _stream_buffered_blocks(content: list[dict[str, object]], start_index: int = 0) -> Iterator[dict[str, object]]:
+    for offset, block in enumerate(content):
+        index = start_index + offset
+        if block["type"] == "tool_use":
+            start = {"type": "tool_use", "id": block["id"], "name": block["name"], "input": {}}
+            delta = {"type": "input_json_delta", "partial_json": json.dumps(block.get("input") or {}, ensure_ascii=False)}
+        else:
+            start = {"type": "text", "text": ""}
+            delta = {"type": "text_delta", "text": block.get("text") or ""}
+        yield {"type": "content_block_start", "index": index, "content_block": start}
+        yield {"type": "content_block_delta", "index": index, "delta": delta}
+        yield {"type": "content_block_stop", "index": index}
+
+
+def handle(body: dict[str, Any]) -> dict[str, Any] | Iterator[dict[str, Any]]:
+    request = message_request(body)
+    if body.get("stream"):
+        return stream_events(
+            stream_text_chat_completion(request.backend, request.messages, request.model),
+            request.model,
+            count_message_tokens(request.messages, request.model),
+            lambda text: count_text_tokens(text, request.model),
+            request.tools,
+        )
+    text = collect_chat_content(stream_text_chat_completion(request.backend, request.messages, request.model))
+    return message_response(
+        request.model,
+        text,
+        count_message_tokens(request.messages, request.model),
+        count_text_tokens(text, request.model),
+        request.tools,
+    )

services/protocol/chat_completion_cache.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterable, Iterator
+
+from services.config import config
+
+CACHEABLE_TEXT_KEYS = {
+    "frequency_penalty",
+    "max_completion_tokens",
+    "max_tokens",
+    "metadata",
+    "model",
+    "presence_penalty",
+    "reasoning_effort",
+    "response_format",
+    "seed",
+    "stop",
+    "temperature",
+    "tool_choice",
+    "tools",
+    "top_p",
+    "user",
+}
+
+
+@dataclass
+class CacheEntry:
+    expires_at: float
+    value: Any
+
+
+@dataclass
+class InflightCall:
+    condition: threading.Condition = field(default_factory=lambda: threading.Condition(threading.RLock()))
+    done: bool = False
+    value: Any = None
+    error: BaseException | None = None
+
+
+def _json_safe(value: Any) -> Any:
+    if isinstance(value, bytes):
+        return {"__bytes_sha256__": hashlib.sha256(value).hexdigest(), "length": len(value)}
+    if isinstance(value, bytearray):
+        data = bytes(value)
+        return {"__bytes_sha256__": hashlib.sha256(data).hexdigest(), "length": len(data)}
+    if isinstance(value, dict):
+        return {str(key): _json_safe(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(item) for item in value]
+    return value
+
+
+def canonical_body(body: dict[str, Any], messages: list[dict[str, Any]], *, stream: bool) -> dict[str, Any]:
+    payload = {key: body.get(key) for key in CACHEABLE_TEXT_KEYS if key in body}
+    payload["messages"] = messages
+    payload["stream"] = bool(stream)
+    return payload
+
+
+def cache_key(body: dict[str, Any], messages: list[dict[str, Any]], *, stream: bool) -> str:
+    encoded = json.dumps(
+        _json_safe(canonical_body(body, messages, stream=stream)),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _message_signature(message: dict[str, Any]) -> str:
+    return json.dumps(_json_safe(message), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def normalize_text_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    settings = config.get_chat_completion_cache_settings()
+    if not settings.get("normalize_messages"):
+        return messages
+
+    normalized: list[dict[str, Any]] = []
+    previous_signature = ""
+    for message in messages:
+        if settings.get("drop_assistant_history") and str(message.get("role") or "") == "assistant":
+            continue
+        signature = _message_signature(message)
+        if settings.get("drop_adjacent_duplicates") and signature == previous_signature:
+            continue
+        normalized.append(message)
+        previous_signature = signature
+    return normalized
+
+
+class ChatCompletionCache:
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._entries: dict[str, CacheEntry] = {}
+        self._inflight: dict[str, InflightCall] = {}
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+            self._inflight.clear()
+
+    def _settings(self) -> dict[str, object]:
+        return config.get_chat_completion_cache_settings()
+
+    def _prune_locked(self, now: float, max_entries: int) -> None:
+        expired = [key for key, item in self._entries.items() if item.expires_at <= now]
+        for key in expired:
+            self._entries.pop(key, None)
+        while len(self._entries) > max_entries:
+            oldest_key = min(self._entries, key=lambda key: self._entries[key].expires_at)
+            self._entries.pop(oldest_key, None)
+
+    @staticmethod
+    def _copy(value: Any) -> Any:
+        return copy.deepcopy(value)
+
+    def get_or_compute_response(self, key: str, compute: Callable[[], dict[str, Any]]) -> dict[str, Any]:
+        settings = self._settings()
+        if not settings.get("enabled") or int(settings.get("ttl_seconds") or 0) <= 0:
+            return compute()
+
+        now = time.time()
+        max_entries = int(settings.get("max_entries") or 1)
+        with self._lock:
+            self._prune_locked(now, max_entries)
+            entry = self._entries.get(key)
+            if entry and entry.expires_at > now:
+                return self._copy(entry.value)
+            inflight = self._inflight.get(key) if settings.get("dedupe_inflight") else None
+            if inflight is None:
+                inflight = InflightCall()
+                if settings.get("dedupe_inflight"):
+                    self._inflight[key] = inflight
+                owner = True
+            else:
+                owner = False
+
+        if not owner:
+            with inflight.condition:
+                while not inflight.done:
+                    inflight.condition.wait()
+                if inflight.error:
+                    raise inflight.error
+                return self._copy(inflight.value)
+
+        try:
+            value = compute()
+        except BaseException as exc:
+            with self._lock:
+                self._inflight.pop(key, None)
+            with inflight.condition:
+                inflight.error = exc
+                inflight.done = True
+                inflight.condition.notify_all()
+            raise
+
+        expires_at = time.time() + int(settings.get("ttl_seconds") or 0)
+        with self._lock:
+            self._entries[key] = CacheEntry(expires_at=expires_at, value=self._copy(value))
+            self._prune_locked(time.time(), max_entries)
+            self._inflight.pop(key, None)
+        with inflight.condition:
+            inflight.value = self._copy(value)
+            inflight.done = True
+            inflight.condition.notify_all()
+        return value
+
+    def get_or_compute_stream(self, key: str, compute: Callable[[], Iterable[dict[str, Any]]]) -> Iterator[dict[str, Any]]:
+        settings = self._settings()
+        if (
+            not settings.get("enabled")
+            or not settings.get("stream_cache")
+            or int(settings.get("ttl_seconds") or 0) <= 0
+        ):
+            yield from compute()
+            return
+
+        now = time.time()
+        max_entries = int(settings.get("max_entries") or 1)
+        with self._lock:
+            self._prune_locked(now, max_entries)
+            entry = self._entries.get(key)
+            if entry and entry.expires_at > now:
+                yield from self._copy(entry.value)
+                return
+            inflight = self._inflight.get(key) if settings.get("dedupe_inflight") else None
+            if inflight is None:
+                inflight = InflightCall()
+                if settings.get("dedupe_inflight"):
+                    self._inflight[key] = inflight
+                owner = True
+            else:
+                owner = False
+
+        if not owner:
+            with inflight.condition:
+                while not inflight.done:
+                    inflight.condition.wait()
+                if inflight.error:
+                    raise inflight.error
+                yield from self._copy(inflight.value)
+                return
+
+        chunks: list[dict[str, Any]] = []
+        try:
+            for chunk in compute():
+                chunks.append(self._copy(chunk))
+                yield chunk
+        except BaseException as exc:
+            with self._lock:
+                self._inflight.pop(key, None)
+            with inflight.condition:
+                inflight.error = exc
+                inflight.done = True
+                inflight.condition.notify_all()
+            raise
+
+        expires_at = time.time() + int(settings.get("ttl_seconds") or 0)
+        with self._lock:
+            self._entries[key] = CacheEntry(expires_at=expires_at, value=self._copy(chunks))
+            self._prune_locked(time.time(), max_entries)
+            self._inflight.pop(key, None)
+        with inflight.condition:
+            inflight.value = self._copy(chunks)
+            inflight.done = True
+            inflight.condition.notify_all()
+
+
+chat_completion_cache = ChatCompletionCache()

services/protocol/conversation.py

@@ -0,0 +1,835 @@
+from __future__ import annotations
+
+import base64
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Iterator
+
+import tiktoken
+
+from services.account_service import account_service
+from services.config import config
+from services.image_storage_service import image_storage_service
+from services.openai_backend_api import ImagePollTimeoutError, OpenAIBackendAPI
+from utils.helper import (
+    IMAGE_MODELS,
+    extract_image_from_message_content,
+    is_codex_image_model,
+    is_supported_image_model,
+    split_image_model,
+)
+from utils.image_tokens import count_image_content_tokens
+from utils.log import logger
+
+
+class ImageGenerationError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 502,
+        error_type: str = "server_error",
+        code: str | None = "upstream_error",
+        param: str | None = None,
+        account_email: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_type = error_type
+        self.code = code
+        self.param = param
+        self.account_email = account_email
+
+    def to_openai_error(self) -> dict[str, Any]:
+        return {
+            "error": {
+                "message": public_image_error_message(str(self)),
+                "type": self.error_type,
+                "param": self.param,
+                "code": self.code,
+            }
+        }
+
+
+def public_image_error_message(message: str) -> str:
+    text = str(message or "").strip()
+    lower = text.lower()
+    if any(item in lower for item in ("backend-api/", "status=", "body=", "chatgpt.com", "upstreamhttperror")):
+        return "The image generation request failed. Please try again later."
+    return text or "The image generation request failed. Please try again later."
+
+
+def is_token_invalid_error(message: str) -> bool:
+    text = str(message or "").lower()
+    return (
+        "token_invalidated" in text
+        or "token_revoked" in text
+        or "authentication token has been invalidated" in text
+        or "invalidated oauth token" in text
+    )
+
+
+def image_stream_error_message(message: str) -> str:
+    text = str(message or "")
+    lower = text.lower()
+    if is_token_invalid_error(text):
+        return "image generation failed"
+    if "curl: (35)" in lower or "tls connect error" in lower or "openssl_internal" in lower:
+        return "upstream image connection failed, please retry later"
+    return text or "image generation failed"
+
+
+def encode_images(images: Iterable[tuple[bytes, str, str]]) -> list[str]:
+    return [base64.b64encode(data).decode("ascii") for data, _, _ in images if data]
+
+
+def save_image_bytes(image_data: bytes, base_url: str | None = None) -> str:
+    return image_storage_service.save(image_data, base_url).url
+
+
+def message_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict) and str(item.get("type") or "") in {"text", "input_text", "output_text"}:
+                parts.append(str(item.get("text") or ""))
+        return "".join(parts)
+    return ""
+
+
+def normalize_messages(messages: object, system: Any = None) -> list[dict[str, Any]]:
+    normalized = []
+    if config.global_system_prompt:
+        normalized.append({"role": "system", "content": config.global_system_prompt})
+    system_text = message_text(system)
+    if system_text:
+        normalized.append({"role": "system", "content": system_text})
+    if isinstance(messages, list):
+        for message in messages:
+            if not isinstance(message, dict):
+                continue
+            role = message.get("role", "user")
+            content = message.get("content", "")
+            text = message_text(content)
+            images: list[tuple[bytes, str]] = []
+            if role == "user":
+                images.extend(extract_image_from_message_content(content))
+                if isinstance(content, list):
+                    for part in content:
+                        if not isinstance(part, dict) or part.get("type") != "image":
+                            continue
+                        data = part.get("data")
+                        if isinstance(data, (bytes, bytearray)):
+                            images.append((bytes(data), str(part.get("mime") or "image/png")))
+            if images:
+                parts: list[Any] = []
+                if text:
+                    parts.append({"type": "text", "text": text})
+                for data, mime in images:
+                    parts.append({"type": "image", "data": data, "mime": mime})
+                normalized.append({"role": role, "content": parts})
+            else:
+                normalized.append({"role": role, "content": text})
+    return normalized
+
+
+def prompt_with_global_system(prompt: str) -> str:
+    return f"{config.global_system_prompt}\n\n{prompt}" if config.global_system_prompt else prompt
+
+
+def assistant_history_text(messages: list[dict[str, Any]]) -> str:
+    return "".join(str(item.get("content") or "") for item in messages if item.get("role") == "assistant")
+
+
+def assistant_history_messages(messages: list[dict[str, Any]]) -> list[str]:
+    return [str(item.get("content") or "") for item in messages if item.get("role") == "assistant" and item.get("content")]
+
+
+def build_image_prompt(prompt: str, size: str | None, quality: str = "auto") -> str:
+    hints = []
+    if size:
+        hints.append(f"输出图片尺寸为 {size}。")
+    if quality:
+        hints.append(f"输出图片质量为 {quality}。")
+    return f"{prompt.strip()}\n\n{''.join(hints)}" if hints else prompt
+
+
+def encoding_for_model(model: str):
+    try:
+        return tiktoken.encoding_for_model(model)
+    except KeyError:
+        try:
+            return tiktoken.get_encoding("o200k_base")
+        except KeyError:
+            return tiktoken.get_encoding("cl100k_base")
+
+
+def count_message_image_tokens(messages: list[dict[str, Any]], model: str) -> int:
+    return sum(count_image_content_tokens(message.get("content"), model) for message in messages)
+
+
+def count_message_text_tokens(messages: list[dict[str, Any]], model: str) -> int:
+    encoding = encoding_for_model(model)
+    total = 0
+    for message in messages:
+        total += 3
+        for key, value in message.items():
+            if key == "content" and isinstance(value, list):
+                total += len(encoding.encode(message_text(value)))
+            elif isinstance(value, str):
+                total += len(encoding.encode(value))
+            else:
+                continue
+            if key == "name":
+                total += 1
+    return total + 3
+
+
+def count_message_tokens(messages: list[dict[str, Any]], model: str) -> int:
+    return count_message_text_tokens(messages, model) + count_message_image_tokens(messages, model)
+
+
+def count_text_tokens(text: str, model: str) -> int:
+    return len(encoding_for_model(model).encode(text))
+
+
+def format_image_result(
+    items: list[dict[str, Any]],
+    prompt: str,
+    response_format: str,
+    base_url: str | None = None,
+    created: int | None = None,
+    message: str = "",
+) -> dict[str, Any]:
+    data: list[dict[str, Any]] = []
+    for item in items:
+        b64_json = str(item.get("b64_json") or "").strip()
+        if not b64_json:
+            continue
+        revised_prompt = str(item.get("revised_prompt") or prompt).strip() or prompt
+        if response_format == "b64_json":
+            data.append({
+                "b64_json": b64_json,
+                "url": save_image_bytes(base64.b64decode(b64_json), base_url),
+                "revised_prompt": revised_prompt,
+            })
+        else:
+            data.append({
+                "url": save_image_bytes(base64.b64decode(b64_json), base_url),
+                "revised_prompt": revised_prompt,
+            })
+    result: dict[str, Any] = {"created": created or int(time.time()), "data": data}
+    if message and not data:
+        result["message"] = message
+    return result
+
+
+@dataclass
+class ConversationRequest:
+    model: str = "auto"
+    prompt: str = ""
+    messages: list[dict[str, Any]] | None = None
+    images: list[str] | None = None
+    n: int = 1
+    size: str | None = None
+    quality: str = "auto"
+    response_format: str = "b64_json"
+    base_url: str | None = None
+    message_as_error: bool = False
+
+
+@dataclass
+class ConversationState:
+    text: str = ""
+    raw_text: str = ""
+    conversation_id: str = ""
+    file_ids: list[str] = field(default_factory=list)
+    sediment_ids: list[str] = field(default_factory=list)
+    blocked: bool = False
+    tool_invoked: bool | None = None
+    turn_use_case: str = ""
+
+
+@dataclass
+class ImageOutput:
+    kind: str
+    model: str
+    index: int
+    total: int
+    created: int = field(default_factory=lambda: int(time.time()))
+    text: str = ""
+    upstream_event_type: str = ""
+    data: list[dict[str, Any]] = field(default_factory=list)
+    account_email: str = ""
+
+    def to_chunk(self) -> dict[str, Any]:
+        chunk: dict[str, Any] = {
+            "object": "image.generation.chunk",
+            "created": self.created,
+            "model": self.model,
+            "index": self.index,
+            "total": self.total,
+            "progress_text": self.text,
+            "upstream_event_type": self.upstream_event_type,
+            "data": [],
+        }
+        if self.account_email:
+            chunk["_account_email"] = self.account_email
+        if self.kind == "message":
+            chunk.update({
+                "object": "image.generation.message",
+                "message": self.text,
+            })
+            chunk.pop("progress_text", None)
+            chunk.pop("upstream_event_type", None)
+        elif self.kind == "result":
+            chunk.update({
+                "object": "image.generation.result",
+                "data": self.data,
+            })
+            chunk.pop("progress_text", None)
+            chunk.pop("upstream_event_type", None)
+        return chunk
+
+
+def assistant_message_text(message: dict[str, Any]) -> str:
+    content = message.get("content") or {}
+    parts = content.get("parts") or []
+    if not isinstance(parts, list):
+        return ""
+    return "".join(part for part in parts if isinstance(part, str))
+
+
+def strip_history(text: str, history_text: str = "") -> str:
+    text = str(text or "")
+    history_text = str(history_text or "")
+    while history_text and text.startswith(history_text):
+        text = text[len(history_text):]
+    return text
+
+
+def sanitize_output_text(text: str) -> str:
+    text = str(text or "")
+
+    def replace_url(match: re.Match[str]) -> str:
+        label = match.group(1).strip()
+        url = match.group(2).strip()
+        if label and url.startswith(("http://", "https://")):
+            return f"{label} ({url})"
+        return label or url
+
+    # ChatGPT web sometimes returns rich annotation markers using private-use
+    # characters. API clients cannot render those, so convert links and drop
+    # citations before emitting OpenAI-compatible text.
+    text = re.sub(r"\ue200url\ue202([^\ue202\ue201]*)\ue202([^\ue201]*)\ue201", replace_url, text)
+    text = re.sub(r"\ue200cite\ue202[^\ue201]*\ue201", "", text)
+    text = re.sub(r"\ue200[^\ue201]*\ue201", "", text)
+    text = re.sub(r"\ue200[^\ue201]*$", "", text)
+    return text
+
+
+def assistant_raw_text(event: dict[str, Any], current_text: str = "", history_text: str = "") -> str:
+    for candidate in (event, event.get("v")):
+        if not isinstance(candidate, dict):
+            continue
+        message = candidate.get("message")
+        if not isinstance(message, dict):
+            continue
+        role = str((message.get("author") or {}).get("role") or "").strip().lower()
+        if role != "assistant":
+            continue
+        text = assistant_message_text(message)
+        if text:
+            return strip_history(text, history_text)
+    return apply_text_patch(event, current_text, history_text)
+
+
+def assistant_text(event: dict[str, Any], current_text: str = "", history_text: str = "") -> str:
+    return sanitize_output_text(assistant_raw_text(event, current_text, history_text))
+
+
+def event_assistant_text(event: dict[str, Any], history_text: str = "") -> str:
+    for candidate in (event, event.get("v")):
+        if not isinstance(candidate, dict):
+            continue
+        message = candidate.get("message")
+        if isinstance(message, dict) and (message.get("author") or {}).get("role") == "assistant":
+            return strip_history(assistant_message_text(message), history_text)
+    return ""
+
+
+def apply_text_patch(event: dict[str, Any], current_text: str = "", history_text: str = "") -> str:
+    if event.get("p") == "/message/content/parts/0":
+        return apply_patch_op(event, current_text, history_text)
+
+    operations = event.get("v")
+    if isinstance(operations, str) and current_text and not event.get("p") and not event.get("o"):
+        return current_text + operations
+
+    if event.get("o") == "patch" and isinstance(operations, list):
+        text = current_text
+        for item in operations:
+            if isinstance(item, dict):
+                text = apply_text_patch(item, text, history_text)
+        return text
+
+    if not isinstance(operations, list):
+        return current_text
+
+    text = current_text
+    for item in operations:
+        if isinstance(item, dict):
+            text = apply_text_patch(item, text, history_text)
+    return text
+
+
+def apply_patch_op(operation: dict[str, Any], current_text: str, history_text: str = "") -> str:
+    op = operation.get("o")
+    value = str(operation.get("v") or "")
+    if op == "append":
+        return current_text + value
+    if op == "replace":
+        return strip_history(value, history_text)
+    return current_text
+
+
+def add_unique(values: list[str], candidates: list[str]) -> None:
+    for candidate in candidates:
+        if candidate and candidate not in values:
+            values.append(candidate)
+
+
+def extract_conversation_ids(payload: str) -> tuple[str, list[str], list[str]]:
+    conversation_match = re.search(r'"conversation_id"\s*:\s*"([^"]+)"', payload)
+    conversation_id = conversation_match.group(1) if conversation_match else ""
+    # Negative lookahead excludes "file-service" (URI prefix, not a real id).
+    file_ids = re.findall(r"(file[-_](?!service\b)[A-Za-z0-9]+)", payload)
+    sediment_ids = re.findall(r"sediment://([A-Za-z0-9_-]+)", payload)
+    return conversation_id, file_ids, sediment_ids
+
+
+def is_image_tool_event(event: dict[str, Any]) -> bool:
+    value = event.get("v")
+    message = event.get("message") or (value.get("message") if isinstance(value, dict) else None)
+    if not isinstance(message, dict):
+        return False
+    metadata = message.get("metadata") or {}
+    author = message.get("author") or {}
+    content = message.get("content") or {}
+    if author.get("role") != "tool":
+        return False
+    if metadata.get("async_task_type") == "image_gen":
+        return True
+    if content.get("content_type") != "multimodal_text":
+        return False
+    return any(
+        isinstance(part, dict) and (
+                part.get("content_type") == "image_asset_pointer"
+                or str(part.get("asset_pointer") or "").startswith(("file-service://", "sediment://"))
+        )
+        for part in content.get("parts") or []
+    )
+
+
+def update_conversation_state(state: ConversationState, payload: str, event: dict[str, Any] | None = None) -> None:
+    conversation_id, file_ids, sediment_ids = extract_conversation_ids(payload)
+    if conversation_id and not state.conversation_id:
+        state.conversation_id = conversation_id
+    # Accept file_id / sediment_id when any of:
+    #   1) event is a complete image_gen tool message
+    #   2) prior server_ste_metadata already flipped tool_invoked True (in an image_gen turn)
+    #   3) patch event whose payload references asset_pointer / file-service://
+    # User messages (type=conversation.message) never satisfy these, so attacker-controlled
+    # substrings in user input cannot inject file ids into state.
+    is_patch_event = isinstance(event, dict) and event.get("o") == "patch"
+    image_context = (
+        (isinstance(event, dict) and is_image_tool_event(event))
+        or state.tool_invoked is True
+        or (is_patch_event and ("asset_pointer" in payload or "file-service://" in payload))
+    )
+    if image_context:
+        add_unique(state.file_ids, file_ids)
+        add_unique(state.sediment_ids, sediment_ids)
+    if not isinstance(event, dict):
+        return
+    state.conversation_id = str(event.get("conversation_id") or state.conversation_id)
+    value = event.get("v")
+    if isinstance(value, dict):
+        state.conversation_id = str(value.get("conversation_id") or state.conversation_id)
+    if event.get("type") == "moderation":
+        moderation = event.get("moderation_response")
+        if isinstance(moderation, dict) and moderation.get("blocked") is True:
+            state.blocked = True
+    if event.get("type") == "server_ste_metadata":
+        metadata = event.get("metadata")
+        if isinstance(metadata, dict):
+            if isinstance(metadata.get("tool_invoked"), bool):
+                state.tool_invoked = metadata["tool_invoked"]
+            state.turn_use_case = str(metadata.get("turn_use_case") or state.turn_use_case)
+
+
+def conversation_base_event(event_type: str, state: ConversationState, **extra: Any) -> dict[str, Any]:
+    return {
+        "type": event_type,
+        "text": state.text,
+        "conversation_id": state.conversation_id,
+        "file_ids": list(state.file_ids),
+        "sediment_ids": list(state.sediment_ids),
+        "blocked": state.blocked,
+        "tool_invoked": state.tool_invoked,
+        "turn_use_case": state.turn_use_case,
+        **extra,
+    }
+
+
+def iter_conversation_payloads(payloads: Iterator[str], history_text: str = "",
+                               history_messages: list[str] | None = None) -> Iterator[dict[str, Any]]:
+    state = ConversationState()
+    history_messages = history_messages or []
+    history_index = 0
+    for payload in payloads:
+        # print(f"[upstream_sse] {payload}", flush=True)
+        if not payload:
+            continue
+        if payload == "[DONE]":
+            yield conversation_base_event("conversation.done", state, done=True)
+            break
+        try:
+            event = json.loads(payload)
+        except json.JSONDecodeError:
+            update_conversation_state(state, payload)
+            yield conversation_base_event("conversation.raw", state, payload=payload)
+            continue
+        if not isinstance(event, dict):
+            yield conversation_base_event("conversation.event", state, raw=event)
+            continue
+        update_conversation_state(state, payload, event)
+        if history_index < len(history_messages) and event_assistant_text(event, history_text) == history_messages[history_index]:
+            history_index += 1
+            state.raw_text = ""
+            state.text = ""
+            continue
+        next_raw_text = assistant_raw_text(event, state.raw_text, history_text)
+        next_text = sanitize_output_text(next_raw_text)
+        state.raw_text = next_raw_text
+        if next_text != state.text:
+            delta = next_text[len(state.text):] if next_text.startswith(state.text) else next_text
+            state.text = next_text
+            yield conversation_base_event("conversation.delta", state, raw=event, delta=delta)
+            continue
+        yield conversation_base_event("conversation.event", state, raw=event)
+
+
+def conversation_events(
+    backend: OpenAIBackendAPI,
+    messages: list[dict[str, Any]] | None = None,
+    model: str = "auto",
+    prompt: str = "",
+    images: list[str] | None = None,
+    size: str | None = None,
+    quality: str = "auto",
+) -> Iterator[dict[str, Any]]:
+    normalized = normalize_messages(messages or ([{"role": "user", "content": prompt}] if prompt else []))
+    image_model = is_supported_image_model(model)
+    history_text = "" if image_model else assistant_history_text(normalized)
+    history_messages = [] if image_model else assistant_history_messages(normalized)
+    final_prompt = prompt_with_global_system(build_image_prompt(prompt, size, quality)) if image_model else prompt
+    payloads = backend.stream_conversation(
+        messages=normalized,
+        model=model,
+        prompt=final_prompt,
+        images=images if image_model else None,
+        system_hints=["picture_v2"] if image_model else None,
+    )
+    yield from iter_conversation_payloads(payloads, history_text, history_messages)
+
+
+def text_backend() -> OpenAIBackendAPI:
+    return OpenAIBackendAPI(access_token=account_service.get_text_access_token())
+
+
+def stream_text_deltas(backend: OpenAIBackendAPI, request: ConversationRequest) -> Iterator[str]:
+    attempted_tokens: set[str] = set()
+    token = getattr(backend, "access_token", "")
+    emitted = False
+    while True:
+        if token and token in attempted_tokens:
+            raise RuntimeError("no available text account")
+        if token:
+            attempted_tokens.add(token)
+        try:
+            active_backend = OpenAIBackendAPI(access_token=token)
+            for event in conversation_events(active_backend, messages=request.messages, model=request.model, prompt=request.prompt):
+                if event.get("type") != "conversation.delta":
+                    continue
+                delta = str(event.get("delta") or "")
+                if delta:
+                    emitted = True
+                    yield delta
+            account_service.mark_text_used(token)
+            return
+        except Exception as exc:
+            error_message = str(exc)
+            if token and not emitted and is_token_invalid_error(error_message):
+                refreshed_token = account_service.refresh_access_token(token, force=True, event="text_stream")
+                if refreshed_token and refreshed_token != token and refreshed_token not in attempted_tokens:
+                    token = refreshed_token
+                else:
+                    account_service.remove_invalid_token(token, "text_stream")
+                    token = account_service.get_text_access_token(attempted_tokens)
+                if token:
+                    continue
+            raise
+
+
+def collect_text(backend: OpenAIBackendAPI, request: ConversationRequest) -> str:
+    return "".join(stream_text_deltas(backend, request))
+
+
+def stream_image_outputs(
+        backend: OpenAIBackendAPI,
+        request: ConversationRequest,
+        index: int = 1,
+        total: int = 1,
+) -> Iterator[ImageOutput]:
+    last: dict[str, Any] = {}
+    for event in conversation_events(
+            backend,
+            prompt=request.prompt,
+            model=request.model,
+            images=request.images or [],
+            size=request.size,
+            quality=request.quality,
+    ):
+        last = event
+        if event.get("type") == "conversation.delta":
+            yield ImageOutput(
+                kind="progress",
+                model=request.model,
+                index=index,
+                total=total,
+                text=str(event.get("delta") or ""),
+                upstream_event_type="conversation.delta",
+            )
+            continue
+        if event.get("type") == "conversation.event":
+            raw = event.get("raw")
+            raw_type = str(raw.get("type") or "") if isinstance(raw, dict) else ""
+            yield ImageOutput(
+                kind="progress",
+                model=request.model,
+                index=index,
+                total=total,
+                upstream_event_type=raw_type,
+            )
+
+    conversation_id = str(last.get("conversation_id") or "")
+    file_ids = [str(item) for item in last.get("file_ids") or []]
+    sediment_ids = [str(item) for item in last.get("sediment_ids") or []]
+    message = str(last.get("text") or "").strip()
+    logger.info({
+        "event": "image_stream_resolve_start",
+        "conversation_id": conversation_id,
+        "file_ids": file_ids,
+        "sediment_ids": sediment_ids,
+        "tool_invoked": last.get("tool_invoked"),
+        "turn_use_case": last.get("turn_use_case"),
+    })
+    if message and not file_ids and not sediment_ids and last.get("blocked"):
+        yield ImageOutput(kind="message", model=request.model, index=index, total=total, text=message)
+        return
+    should_poll_for_image = bool(request.images) or last.get("turn_use_case") == "image gen"
+    if message and not file_ids and not sediment_ids and not should_poll_for_image:
+        yield ImageOutput(kind="message", model=request.model, index=index, total=total, text=message)
+        return
+
+    image_urls = backend.resolve_conversation_image_urls(conversation_id, file_ids, sediment_ids)
+    if image_urls:
+        image_items = [
+            {"b64_json": base64.b64encode(image_data).decode("ascii")}
+            for image_data in backend.download_image_bytes(image_urls)
+        ]
+        data = format_image_result(
+            image_items,
+            request.prompt,
+            request.response_format,
+            request.base_url,
+            int(time.time()),
+        )["data"]
+        if data:
+            yield ImageOutput(kind="result", model=request.model, index=index, total=total, data=data)
+        return
+
+    if message:
+        yield ImageOutput(kind="message", model=request.model, index=index, total=total, text=message)
+
+
+def _codex_response_images(value: Any) -> list[str]:
+    if isinstance(value, dict):
+        if value.get("type") == "image_generation_call" and isinstance(value.get("result"), str):
+            result = value["result"].strip()
+            if result:
+                return [result.split(",", 1)[1] if result.startswith("data:image/") else result]
+        images: list[str] = []
+        for item in value.values():
+            images.extend(_codex_response_images(item))
+        return images
+    if isinstance(value, list):
+        images: list[str] = []
+        for item in value:
+            images.extend(_codex_response_images(item))
+        return images
+    return []
+
+
+def stream_codex_image_outputs(
+        backend: OpenAIBackendAPI,
+        request: ConversationRequest,
+        index: int = 1,
+        total: int = 1,
+) -> Iterator[ImageOutput]:
+    images = _codex_response_images(list(backend.iter_codex_image_response_events(
+        prompt=request.prompt,
+        images=request.images or [],
+        size=request.size,
+        quality=request.quality,
+    )))
+    if not images:
+        raise ImageGenerationError("No image result found in response")
+    data = format_image_result(
+        [{"b64_json": item, "revised_prompt": request.prompt} for item in images],
+        request.prompt,
+        request.response_format,
+        request.base_url,
+        int(time.time()),
+    )["data"]
+    if data:
+        yield ImageOutput(kind="result", model=request.model, index=index, total=total, data=data)
+        return
+    raise ImageGenerationError("No image result found in response")
+
+
+def stream_image_outputs_with_pool(request: ConversationRequest) -> Iterator[ImageOutput]:
+    if not is_supported_image_model(request.model):
+        raise ImageGenerationError("unsupported image model,supported models: " + ", ".join(sorted(IMAGE_MODELS)))
+
+    emitted = False
+    last_error = ""
+    for index in range(1, request.n + 1):
+        while True:
+            try:
+                plan_type, _ = split_image_model(request.model)
+                codex_model = is_codex_image_model(request.model)
+                token = account_service.get_available_access_token(
+                    plan_type=plan_type,
+                    source_type="codex" if codex_model else None,
+                    plan_types=("plus", "team", "pro") if codex_model and not plan_type else None,
+                )
+            except RuntimeError as exc:
+                if emitted:
+                    return
+                raise ImageGenerationError(str(exc) or "image generation failed") from exc
+
+            emitted_for_token = False
+            returned_message = False
+            returned_result = False
+            account = account_service.get_account(token) or {}
+            account_email = str(account.get("email") or "").strip()
+            try:
+                backend = OpenAIBackendAPI(access_token=token)
+                stream_fn = stream_codex_image_outputs if is_codex_image_model(request.model) else stream_image_outputs
+                for output in stream_fn(backend, request, index, request.n):
+                    if account_email and not output.account_email:
+                        output.account_email = account_email
+                    if output.kind == "message" and request.message_as_error:
+                        raise ImageGenerationError(
+                            output.text or "Image generation was rejected by upstream policy.",
+                            status_code=400,
+                            error_type="invalid_request_error",
+                            code="content_policy_violation",
+                            account_email=account_email,
+                        )
+                    emitted = True
+                    emitted_for_token = True
+                    returned_message = output.kind == "message"
+                    returned_result = returned_result or output.kind == "result"
+                    yield output
+                if returned_message or not returned_result:
+                    account_service.mark_image_result(token, False)
+                    return
+                account_service.mark_image_result(token, True)
+                break
+            except ImagePollTimeoutError as exc:
+                if account_email and not getattr(exc, "account_email", ""):
+                    exc.account_email = account_email
+                raise
+            except ImageGenerationError as exc:
+                account_service.mark_image_result(token, False)
+                if account_email and not getattr(exc, "account_email", ""):
+                    exc.account_email = account_email
+                logger.warning({
+                    "event": "image_stream_generation_error",
+                    "request_token": token,
+                    "account_email": account_email,
+                    "error": str(exc),
+                })
+                raise
+            except Exception as exc:
+                account_service.mark_image_result(token, False)
+                last_error = str(exc)
+                logger.warning({
+                    "event": "image_stream_fail",
+                    "request_token": token,
+                    "account_email": account_email,
+                    "error": last_error,
+                })
+                if not emitted_for_token and is_token_invalid_error(last_error):
+                    refreshed_token = account_service.refresh_access_token(token, force=True, event="image_stream")
+                    if refreshed_token and refreshed_token != token:
+                        token = refreshed_token
+                        continue
+                    account_service.remove_invalid_token(token, "image_stream")
+                    continue
+                raise ImageGenerationError(image_stream_error_message(last_error), account_email=account_email) from exc
+
+    if not emitted:
+        if not last_error:
+            last_error = "no account in the pool could generate images — check account quota and rate-limit status"
+        raise ImageGenerationError(image_stream_error_message(last_error))
+
+
+def stream_image_chunks(outputs: Iterable[ImageOutput]) -> Iterator[dict[str, Any]]:
+    for output in outputs:
+        yield output.to_chunk()
+
+
+def collect_image_outputs(outputs: Iterable[ImageOutput]) -> dict[str, Any]:
+    created = None
+    data: list[dict[str, Any]] = []
+    message = ""
+    progress_parts: list[str] = []
+    account_email = ""
+    for output in outputs:
+        created = created or output.created
+        if output.account_email and not account_email:
+            account_email = output.account_email
+        if output.kind == "progress" and output.text:
+            progress_parts.append(output.text)
+        elif output.kind == "message":
+            message = output.text
+        elif output.kind == "result":
+            data.extend(output.data)
+
+    result: dict[str, Any] = {"created": created or int(time.time()), "data": data}
+    if not data:
+        text = message or "".join(progress_parts).strip()
+        if text:
+            result["message"] = text
+    if account_email:
+        result["_account_email"] = account_email
+    return result

services/protocol/error_response.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi.responses import JSONResponse
+
+
+def _message_from_value(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    if not isinstance(value, dict):
+        return ""
+    message = value.get("message")
+    if isinstance(message, str) and message:
+        return message
+    return _message_from_value(value.get("error"))
+
+
+def error_message_from_detail(detail: object) -> str:
+    if isinstance(detail, list):
+        messages = []
+        for item in detail:
+            if not isinstance(item, dict):
+                continue
+            location = ".".join(str(part) for part in item.get("loc", []) if part != "body")
+            message = str(item.get("msg") or "").strip()
+            if location and message:
+                messages.append(f"{location}: {message}")
+            elif message:
+                messages.append(message)
+        return "; ".join(messages)
+    if isinstance(detail, dict):
+        message = _message_from_value(detail.get("error")) or _message_from_value(detail)
+        if message:
+            return message
+    return str(detail or "").strip()
+
+
+def _default_error_type(status_code: int) -> str:
+    if status_code == 401:
+        return "authentication_error"
+    if status_code == 403:
+        return "permission_error"
+    if status_code == 429:
+        return "rate_limit_error"
+    if 400 <= status_code < 500:
+        return "invalid_request_error"
+    return "server_error"
+
+
+def _default_error_code(status_code: int) -> str:
+    if status_code == 401:
+        return "invalid_api_key"
+    if status_code == 403:
+        return "permission_denied"
+    if status_code == 429:
+        return "rate_limit_exceeded"
+    if 400 <= status_code < 500:
+        return "bad_request"
+    return "upstream_error"
+
+
+def openai_error_payload(
+    detail: object,
+    status_code: int,
+    *,
+    error_type: str | None = None,
+    code: object | None = None,
+    param: object | None = None,
+) -> dict[str, Any]:
+    error_detail = detail.get("error") if isinstance(detail, dict) else None
+    if isinstance(error_detail, dict):
+        return {
+            "error": {
+                "message": error_message_from_detail(error_detail) or "request failed",
+                "type": str(error_detail.get("type") or error_type or _default_error_type(status_code)),
+                "param": error_detail.get("param", param),
+                "code": error_detail.get("code", code if code is not None else _default_error_code(status_code)),
+            }
+        }
+    return {
+        "error": {
+            "message": error_message_from_detail(detail) or "request failed",
+            "type": error_type or _default_error_type(status_code),
+            "param": param,
+            "code": code if code is not None else _default_error_code(status_code),
+        }
+    }
+
+
+def openai_error_response(
+    detail: object,
+    status_code: int,
+    *,
+    headers: dict[str, str] | None = None,
+    error_type: str | None = None,
+    code: object | None = None,
+    param: object | None = None,
+) -> JSONResponse:
+    return JSONResponse(
+        status_code=status_code,
+        content=openai_error_payload(detail, status_code, error_type=error_type, code=code, param=param),
+        headers=headers,
+    )
+
+
+def anthropic_error_response(
+    detail: object,
+    status_code: int,
+    *,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    error_type = "api_error" if status_code >= 500 else _default_error_type(status_code)
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "type": "error",
+            "error": {
+                "type": error_type,
+                "message": error_message_from_detail(detail) or "request failed",
+            },
+        },
+        headers=headers,
+    )

services/protocol/openai_v1_chat_complete.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Iterable, Iterator
+
+from fastapi import HTTPException
+
+from services.protocol.chat_completion_cache import cache_key, chat_completion_cache, normalize_text_messages
+from services.protocol.conversation import (
+    ConversationRequest,
+    ImageOutput,
+    collect_image_outputs,
+    collect_text,
+    count_message_image_tokens,
+    count_message_text_tokens,
+    count_text_tokens,
+    encode_images,
+    normalize_messages,
+    stream_image_outputs_with_pool,
+    stream_text_deltas,
+    text_backend,
+)
+from utils.helper import build_chat_image_markdown_content, extract_chat_image, extract_chat_prompt, is_image_chat_request, parse_image_count
+from utils.image_tokens import (
+    chat_usage_from_image_usage,
+    count_image_inputs_tokens,
+    count_image_output_items_tokens,
+    image_usage,
+)
+
+TOOL_UNAVAILABLE_SYSTEM_MESSAGE = (
+    "This compatibility backend cannot execute local tools, shell commands, web searches, "
+    "or file operations. Do not claim to have run tools or inspected external resources. "
+    "If a user asks you to use a tool, say that tool execution is unavailable through this backend."
+)
+
+
+def completion_chunk(model: str, delta: dict[str, Any], finish_reason: str | None = None, completion_id: str = "", created: int | None = None) -> dict[str, Any]:
+    return {
+        "id": completion_id or f"chatcmpl-{uuid.uuid4().hex}",
+        "object": "chat.completion.chunk",
+        "created": created or int(time.time()),
+        "model": model,
+        "choices": [{"index": 0, "delta": delta, "finish_reason": finish_reason}],
+    }
+
+
+def completion_response(
+    model: str,
+    content: str,
+    created: int | None = None,
+    messages: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    prompt_text_tokens = count_message_text_tokens(messages, model) if messages else 0
+    prompt_image_tokens = count_message_image_tokens(messages, model) if messages else 0
+    prompt_tokens = prompt_text_tokens + prompt_image_tokens
+    completion_tokens = count_text_tokens(content, model) if messages else 0
+    return {
+        "id": f"chatcmpl-{uuid.uuid4().hex}",
+        "object": "chat.completion",
+        "created": created or int(time.time()),
+        "model": model,
+        "choices": [{
+            "index": 0,
+            "message": {"role": "assistant", "content": content},
+            "finish_reason": "stop",
+        }],
+        "usage": {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": prompt_tokens + completion_tokens,
+            "prompt_tokens_details": {
+                "text_tokens": prompt_text_tokens,
+                "image_tokens": prompt_image_tokens,
+                "cached_tokens": 0,
+            },
+            "completion_tokens_details": {
+                "text_tokens": completion_tokens,
+                "image_tokens": 0,
+                "reasoning_tokens": 0,
+            },
+        },
+    }
+
+
+def stream_text_chat_completion(backend, messages: list[dict[str, Any]], model: str) -> Iterator[dict[str, Any]]:
+    completion_id = f"chatcmpl-{uuid.uuid4().hex}"
+    created = int(time.time())
+    sent_role = False
+    request = ConversationRequest(model=model, messages=messages)
+    for delta_text in stream_text_deltas(backend, request):
+        if not sent_role:
+            sent_role = True
+            yield completion_chunk(model, {"role": "assistant", "content": delta_text}, None, completion_id, created)
+        else:
+            yield completion_chunk(model, {"content": delta_text}, None, completion_id, created)
+    if not sent_role:
+        yield completion_chunk(model, {"role": "assistant", "content": ""}, None, completion_id, created)
+    yield completion_chunk(model, {}, "stop", completion_id, created)
+
+
+def collect_chat_content(chunks: Iterable[dict[str, Any]]) -> str:
+    parts: list[str] = []
+    for chunk in chunks:
+        choices = chunk.get("choices")
+        first = choices[0] if isinstance(choices, list) and choices and isinstance(choices[0], dict) else {}
+        delta = first.get("delta") if isinstance(first.get("delta"), dict) else {}
+        content = str(delta.get("content") or "")
+        if content:
+            parts.append(content)
+    return "".join(parts)
+
+
+def chat_messages_from_body(body: dict[str, Any]) -> list[dict[str, Any]]:
+    messages = body.get("messages")
+    if isinstance(messages, list) and messages:
+        return [message for message in messages if isinstance(message, dict)]
+    prompt = str(body.get("prompt") or "").strip()
+    if prompt:
+        return [{"role": "user", "content": prompt}]
+    raise HTTPException(status_code=400, detail={"error": "messages or prompt is required"})
+
+
+def chat_image_args(body: dict[str, Any]) -> tuple[str, str, int, list[tuple[bytes, str, str]]]:
+    model = str(body.get("model") or "gpt-image-2").strip() or "gpt-image-2"
+    prompt = extract_chat_prompt(body)
+    if not prompt:
+        raise HTTPException(status_code=400, detail={"error": "prompt is required"})
+    images = [
+        (data, f"image_{idx}.png", mime)
+        for idx, (data, mime) in enumerate(extract_chat_image(body), start=1)
+    ]
+    return model, prompt, parse_image_count(body.get("n")), images
+
+
+def text_chat_parts(body: dict[str, Any]) -> tuple[str, list[dict[str, Any]]]:
+    model = str(body.get("model") or "auto").strip() or "auto"
+    messages = normalize_text_messages(normalize_messages(chat_messages_from_body(body)))
+    tools = body.get("tools")
+    if isinstance(tools, list) and tools:
+        messages.insert(0, {"role": "system", "content": TOOL_UNAVAILABLE_SYSTEM_MESSAGE})
+    return model, messages
+
+
+def image_result_content(result: dict[str, Any]) -> str:
+    data = result.get("data")
+    if isinstance(data, list) and data:
+        return build_chat_image_markdown_content(result)
+    return str(result.get("message") or "Image generation completed.")
+
+
+def image_chat_response(body: dict[str, Any]) -> dict[str, Any]:
+    model, prompt, n, images = chat_image_args(body)
+    result = collect_image_outputs(stream_image_outputs_with_pool(ConversationRequest(
+        prompt=prompt,
+        model=model,
+        n=n,
+        response_format="b64_json",
+        images=encode_images(images) or None,
+    )))
+    response = completion_response(model, image_result_content(result), int(result.get("created") or 0) or None)
+    usage = image_usage(
+        input_text_tokens=count_text_tokens(prompt, model),
+        input_image_tokens=count_image_inputs_tokens(images, model),
+        output_tokens=count_image_output_items_tokens(result.get("data")),
+    )
+    response["usage"] = chat_usage_from_image_usage(usage)
+    return response
+
+
+def image_chat_events(body: dict[str, Any]) -> Iterator[dict[str, Any]]:
+    model, prompt, n, images = chat_image_args(body)
+    image_outputs = stream_image_outputs_with_pool(ConversationRequest(
+        prompt=prompt,
+        model=model,
+        n=n,
+        response_format="b64_json",
+        images=encode_images(images) or None,
+    ))
+    yield from stream_image_chat_completion(image_outputs, model)
+
+
+def stream_image_chat_completion(image_outputs: Iterable[ImageOutput], model: str) -> Iterator[dict[str, Any]]:
+    completion_id = f"chatcmpl-{uuid.uuid4().hex}"
+    created = int(time.time())
+    sent_role = False
+    sent_text = ""
+    for output in image_outputs:
+        content = ""
+        if output.kind == "progress":
+            content = output.text
+            sent_text += content
+        elif output.kind == "result":
+            content = build_chat_image_markdown_content({"data": output.data})
+        elif output.kind == "message":
+            content = output.text[len(sent_text):] if output.text.startswith(sent_text) else output.text
+        if not content:
+            continue
+        if not sent_role:
+            sent_role = True
+            yield completion_chunk(model, {"role": "assistant", "content": content}, None, completion_id, created)
+        else:
+            yield completion_chunk(model, {"content": content}, None, completion_id, created)
+    if not sent_role:
+        yield completion_chunk(model, {"role": "assistant", "content": ""}, None, completion_id, created)
+    yield completion_chunk(model, {}, "stop", completion_id, created)
+
+
+def handle(body: dict[str, Any]) -> dict[str, Any] | Iterator[dict[str, Any]]:
+    if body.get("stream"):
+        if is_image_chat_request(body):
+            return image_chat_events(body)
+        model, messages = text_chat_parts(body)
+        key = cache_key(body, messages, stream=True)
+        return chat_completion_cache.get_or_compute_stream(
+            key,
+            lambda: stream_text_chat_completion(text_backend(), messages, model),
+        )
+    if is_image_chat_request(body):
+        return image_chat_response(body)
+    model, messages = text_chat_parts(body)
+    key = cache_key(body, messages, stream=False)
+    return chat_completion_cache.get_or_compute_response(
+        key,
+        lambda: completion_response(
+            model,
+            collect_text(text_backend(), ConversationRequest(model=model, messages=messages)),
+            messages=messages,
+        ),
+    )