feat: 支持token级打码代理并完善有头Docker双镜像发布

Author: genz27

.github/workflows/docker-publish.yml

@@ -18,6 +18,18 @@ env:
 jobs:
   build-and-push:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - variant: standard
+            dockerfile: Dockerfile
+            image_suffix: ""
+            cache_scope: standard
+          - variant: headed
+            dockerfile: Dockerfile.headed
+            image_suffix: -headed
+            cache_scope: headed
     permissions:
       contents: read
       packages: write
@@ -44,21 +56,22 @@ jobs:
         id: meta
         uses: docker/metadata-action@v5
         with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}${{ matrix.image_suffix }}
           tags: |
             type=ref,event=branch
             type=ref,event=pr
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=raw,value=latest,enable={{is_default_branch}}
 
-      - name: Build and push Docker image
+      - name: Build and push Docker image (${{ matrix.variant }})
         uses: docker/build-push-action@v5
         with:
           context: .
+          file: ${{ matrix.dockerfile }}
           platforms: linux/amd64,linux/arm64
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=${{ matrix.cache_scope }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.cache_scope }}

Dockerfile.headed

@@ -0,0 +1,32 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PLAYWRIGHT_BROWSERS_PATH=0 \
+    ALLOW_DOCKER_HEADED_CAPTCHA=true \
+    DISPLAY=:99 \
+    XVFB_WHD=1920x1080x24
+
+COPY requirements.txt ./
+
+# 有头模式基础依赖：虚拟显示、窗口管理器。
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        xvfb \
+        fluxbox \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt \
+    && python -m playwright install --with-deps chromium
+
+COPY . .
+COPY docker/entrypoint.headed.sh /usr/local/bin/entrypoint.headed.sh
+RUN chmod +x /usr/local/bin/entrypoint.headed.sh
+
+EXPOSE 8000
+
+CMD ["/usr/local/bin/entrypoint.headed.sh"]

README.md

@@ -32,6 +32,8 @@
 
 - 由于Flow增加了额外的验证码，你可以自行选择使用浏览器打码或第三发打码：
 注册[YesCaptcha](https://yescaptcha.com/i/13Xd8K)并获取api key，将其填入系统配置页面```YesCaptcha API密钥```区域
+- 默认 `docker-compose.yml` 建议搭配第三方打码（yescaptcha/capmonster/ezcaptcha/capsolver）。
+如需 Docker 内有头打码（browser/personal），请使用下方 `docker-compose.headed.yml`。
 
 - 自动更新st浏览器拓展：[Flow2API-Token-Updater](https://github.com/TheSmallHanCat/Flow2API-Token-Updater)
 
@@ -61,6 +63,23 @@ docker-compose -f docker-compose.warp.yml up -d
 docker-compose -f docker-compose.warp.yml logs -f
 ```
 
+#### Docker 有头打码模式（browser / personal）
+
+> 适用于你有虚拟化桌面需求、希望在容器里启用有头浏览器打码的场景。  
+> 该模式默认启动 `Xvfb + Fluxbox` 实现容器内部可视化，并设置 `ALLOW_DOCKER_HEADED_CAPTCHA=true`。  
+> 仅开放应用端口，不提供任何远程桌面连接端口。
+
+```bash
+# 启动有头模式（首次建议带 --build）
+docker compose -f docker-compose.headed.yml up -d --build
+
+# 查看日志
+docker compose -f docker-compose.headed.yml logs -f
+```
+
+- API 端口：`8000`
+- 进入管理后台后，将验证码方式设为 `browser` 或 `personal`
+
 ### 方式二：本地部署
 
 ```bash

docker-compose.headed.yml

@@ -0,0 +1,21 @@
+version: '3.8'
+
+services:
+  flow2api-headed:
+    build:
+      context: .
+      dockerfile: Dockerfile.headed
+    image: flow2api:headed
+    container_name: flow2api-headed
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./data:/app/data
+      - ./config/setting.toml:/app/config/setting.toml
+    environment:
+      - PYTHONUNBUFFERED=1
+      - ALLOW_DOCKER_HEADED_CAPTCHA=true
+      - DISPLAY=:99
+      - XVFB_WHD=1920x1080x24
+    shm_size: "2gb"
+    restart: unless-stopped

docker/entrypoint.headed.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+set -eu
+
+export DISPLAY="${DISPLAY:-:99}"
+export ALLOW_DOCKER_HEADED_CAPTCHA="${ALLOW_DOCKER_HEADED_CAPTCHA:-true}"
+export XVFB_WHD="${XVFB_WHD:-1920x1080x24}"
+
+echo "[entrypoint] starting Xvfb on ${DISPLAY} (${XVFB_WHD})"
+Xvfb "${DISPLAY}" -screen 0 "${XVFB_WHD}" -ac -nolisten tcp +extension RANDR >/tmp/xvfb.log 2>&1 &
+
+sleep 1
+
+echo "[entrypoint] starting Fluxbox"
+fluxbox >/tmp/fluxbox.log 2>&1 &
+
+if [ -z "${BROWSER_EXECUTABLE_PATH:-}" ]; then
+  BROWSER_EXECUTABLE_PATH="$(python - <<'PY'
+from playwright.sync_api import sync_playwright
+
+try:
+    with sync_playwright() as p:
+        print(p.chromium.executable_path)
+except Exception:
+    print("")
+PY
+)"
+  if [ -n "${BROWSER_EXECUTABLE_PATH}" ]; then
+    export BROWSER_EXECUTABLE_PATH
+    echo "[entrypoint] browser executable: ${BROWSER_EXECUTABLE_PATH}"
+  fi
+fi
+
+exec python main.py

src/api/admin.py

@@ -229,6 +229,7 @@ class AddTokenRequest(BaseModel):
     project_id: Optional[str] = None  # 用户可选输入project_id
     project_name: Optional[str] = None
     remark: Optional[str] = None
+    captcha_proxy_url: Optional[str] = None
     image_enabled: bool = True
     video_enabled: bool = True
     image_concurrency: int = -1
@@ -240,6 +241,7 @@ class UpdateTokenRequest(BaseModel):
     project_id: Optional[str] = None  # 用户可选输入project_id
     project_name: Optional[str] = None
     remark: Optional[str] = None
+    captcha_proxy_url: Optional[str] = None
     image_enabled: Optional[bool] = None
     video_enabled: Optional[bool] = None
     image_concurrency: Optional[int] = None
@@ -301,6 +303,7 @@ class ImportTokenItem(BaseModel):
     access_token: Optional[str] = None
     session_token: Optional[str] = None
     is_active: bool = True
+    captcha_proxy_url: Optional[str] = None
     image_enabled: bool = True
     video_enabled: bool = True
     image_concurrency: int = -1
@@ -411,6 +414,7 @@ async def get_tokens(token: str = Depends(verify_admin_token)):
         "user_paygate_tier": row.get("user_paygate_tier"),
         "current_project_id": row.get("current_project_id"),  # 🆕 项目ID
         "current_project_name": row.get("current_project_name"),  # 🆕 项目名称
+        "captcha_proxy_url": row.get("captcha_proxy_url") or "",
         "image_enabled": bool(row.get("image_enabled")),
         "video_enabled": bool(row.get("video_enabled")),
         "image_concurrency": row.get("image_concurrency"),
@@ -433,6 +437,7 @@ async def add_token(
             project_id=request.project_id,  # 🆕 支持用户指定project_id
             project_name=request.project_name,
             remark=request.remark,
+            captcha_proxy_url=request.captcha_proxy_url.strip() if request.captcha_proxy_url is not None else None,
             image_enabled=request.image_enabled,
             video_enabled=request.video_enabled,
             image_concurrency=request.image_concurrency,
@@ -495,6 +500,7 @@ async def update_token(
             project_id=request.project_id,
             project_name=request.project_name,
             remark=request.remark,
+            captcha_proxy_url=request.captcha_proxy_url.strip() if request.captcha_proxy_url is not None else None,
             image_enabled=request.image_enabled,
             video_enabled=request.video_enabled,
             image_concurrency=request.image_concurrency,
@@ -695,6 +701,7 @@ async def import_tokens(
                         st=st,
                         at=at,
                         at_expires=at_expires,
+                        captcha_proxy_url=item.captcha_proxy_url.strip() if item.captcha_proxy_url is not None else None,
                         image_enabled=item.image_enabled,
                         video_enabled=item.video_enabled,
                         image_concurrency=item.image_concurrency,
@@ -707,6 +714,7 @@ async def import_tokens(
                     existing.st = st
                     existing.at = at
                     existing.at_expires = at_expires
+                    existing.captcha_proxy_url = item.captcha_proxy_url
                     existing.image_enabled = item.image_enabled
                     existing.video_enabled = item.video_enabled
                     existing.image_concurrency = item.image_concurrency
@@ -716,6 +724,7 @@ async def import_tokens(
                     # 添加新Token
                     new_token = await token_manager.add_token(
                         st=st,
+                        captcha_proxy_url=item.captcha_proxy_url.strip() if item.captcha_proxy_url is not None else None,
                         image_enabled=item.image_enabled,
                         video_enabled=item.video_enabled,
                         image_concurrency=item.image_concurrency,

src/core/database.py

@@ -283,6 +283,7 @@ async def check_and_migrate_db(self, config_dict: dict = None):
                     ("video_enabled", "BOOLEAN DEFAULT 1"),
                     ("image_concurrency", "INTEGER DEFAULT -1"),
                     ("video_concurrency", "INTEGER DEFAULT -1"),
+                    ("captcha_proxy_url", "TEXT"),  # token级打码代理
                     ("ban_reason", "TEXT"),  # 禁用原因
                     ("banned_at", "TIMESTAMP"),  # 禁用时间
                 ]
@@ -406,6 +407,7 @@ async def init_db(self):
                     video_enabled BOOLEAN DEFAULT 1,
                     image_concurrency INTEGER DEFAULT -1,
                     video_concurrency INTEGER DEFAULT -1,
+                    captcha_proxy_url TEXT,
                     ban_reason TEXT,
                     banned_at TIMESTAMP
                 )
@@ -653,13 +655,13 @@ async def add_token(self, token: Token) -> int:
             cursor = await db.execute("""
                 INSERT INTO tokens (st, at, at_expires, email, name, remark, is_active,
                                    credits, user_paygate_tier, current_project_id, current_project_name,
-                                   image_enabled, video_enabled, image_concurrency, video_concurrency)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                                   image_enabled, video_enabled, image_concurrency, video_concurrency, captcha_proxy_url)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """, (token.st, token.at, token.at_expires, token.email, token.name, token.remark,
                   token.is_active, token.credits, token.user_paygate_tier,
                   token.current_project_id, token.current_project_name,
                   token.image_enabled, token.video_enabled,
-                  token.image_concurrency, token.video_concurrency))
+                  token.image_concurrency, token.video_concurrency, token.captcha_proxy_url))
             await db.commit()
             token_id = cursor.lastrowid
 

src/core/models.py

@@ -38,6 +38,9 @@ class Token(BaseModel):
     image_concurrency: int = -1  # -1表示无限制
     video_concurrency: int = -1  # -1表示无限制
 
+    # 打码代理（token 级，可覆盖全局浏览器打码代理）
+    captcha_proxy_url: Optional[str] = None
+
     # 429禁用相关
     ban_reason: Optional[str] = None  # 禁用原因: "429_rate_limit" 或 None
     banned_at: Optional[datetime] = None  # 禁用时间

src/main.py

@@ -105,7 +105,7 @@ async def lifespan(app: FastAPI):
     elif captcha_config.captcha_method == "browser":
         from .services.browser_captcha import BrowserCaptchaService
         browser_service = await BrowserCaptchaService.get_instance(db)
-        print("✓ Browser captcha service initialized (headless mode)")
+        print("✓ Browser captcha service initialized (headed mode)")
 
     # Initialize concurrency manager
     tokens = await token_manager.get_all_tokens()