chore: release v0.2.2

Remove the legacy video category feature from the frontend, public API, admin API, scanner, crawler import flow, and catalog schema. Add startup migration handling that drops the old videos.category column, including a rebuild fallback for legacy databases with category-dependent indexes, and extend regression tests for existing deployments.

Keep tag-based workflows as the only classification surface by updating listing, promo, tag management, and video edit UI. Replace the old categories data module with promos and prevent category data from leaking through list or admin responses.

Improve mobile and desktop video management UX: align drive/search/refresh controls, keep bulk actions from shifting video cards, add blacklist drive filtering, center mobile modals, tighten drive picker cards, and fix edit-video tag options so short labels stay on one line.

Refine public video cards and detail navigation: truncate long author metadata, avoid empty author separators, and return users to their originating page after deleting a video instead of always navigating to /list.

Verified with go test ./..., npm run lint, npm test, npm run build, and git diff --check.

.dockerignore

@@ -0,0 +1,21 @@
+.git
+.github
+.gitattributes
+.gitignore
+
+node_modules
+dist
+release
+data
+backend/data
+backend/config.yaml
+config.yaml
+
+*.db
+*.sqlite
+*.sqlite3
+*.log
+*.tmp
+
+tests
+video-site-implementation-plan.md

.github/workflows/docker-build.yml

@@ -0,0 +1,82 @@
+name: Docker
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=sha-
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=raw,value=stable,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+
+      - name: Determine image version
+        id: version
+        shell: bash
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            version="$GITHUB_REF_NAME"
+          else
+            version="$(git describe --tags --always --dirty 2>/dev/null || git rev-parse --short=12 HEAD)"
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ steps.version.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/release.yml

@@ -15,6 +15,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Go
         uses: actions/setup-go@v5
@@ -36,8 +38,11 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ github.ref_name }}
         run: |
-          if gh release view "$TAG" >/dev/null 2>&1; then
-            gh release upload "$TAG" release/*.tar.gz --clobber
-          else
-            gh release create "$TAG" release/*.tar.gz --title "$TAG" --notes "Prebuilt Linux release packages."
+          git tag -d "$TAG" >/dev/null 2>&1 || true
+          git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+          NOTES="$(git tag -l "$TAG" --format='%(contents)')"
+          if [ -z "$NOTES" ]; then
+            NOTES="Prebuilt Linux release packages."
           fi
+          gh release delete "$TAG" --yes >/dev/null 2>&1 || true
+          gh release create "$TAG" release/*.tar.gz --title "$TAG" --notes "$NOTES" --verify-tag

.gitignore

@@ -23,13 +23,27 @@ tools/
 
 # 编译产物
 backend/server
+backend/server.*
 release/
 tsconfig.tsbuildinfo
+tmp/
 
 # 91 爬虫脚本独立运行时的默认输出文件（backend 跑时会显式 --output 到 backend/data/spider91/，所以不会落在这里）
 91porn_videos.json
-91VideoSpider/91porn_videos.json
-91VideoSpider/data/
-91VideoSpider/__pycache__/
 __pycache__/
 *.pyc
+
+# Local scratch images
+/*.png
+/*.jpg
+/*.jpeg
+/*.gif
+/*.webp
+/*.bmp
+/*.ico
+/image.jpg
+/image003.jpg
+/image004.jpg
+/image005.png
+/image006.png
+/image02.png

91VideoSpider/spider_91porn.py

@@ -1,834 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-91porn 视频爬虫脚本
-===================
-爬取 https://www.91porn.com/v.php?category=top&viewtype=basic 下的所有视频信息：
-  - 视频名称
-  - 封面图直链
-  - 视频直链 (MP4)
-
-依赖安装:
-    pip install requests beautifulsoup4 lxml
-
-使用方法:
-    # 全量爬取（默认行为，从 page=1 一直爬到末尾，写到 OUTPUT_FILE）
-    python spider_91porn.py
-
-    # 只爬指定页（单页模式，手动调试用）
-    python spider_91porn.py --page 1 --output /tmp/spider91_page1.json
-
-    # 凑够 N 个新视频模式（backend 凌晨任务用）
-    python spider_91porn.py --target-new 15 --seen-viewkeys-file /tmp/seen.txt --output /tmp/new.json
-
-CLI 参数:
-    --page N                  只爬第 N 页，配合 --output 用于手动调试
-    --target-new N            从 page 1 起翻页直到凑够 N 个新视频（不在 seen 列表里的）
-    --seen-viewkeys-file FILE 每行一个已知 viewkey 或 mp4 源 ID，命中即跳过；与 --target-new 配合使用
-    --output FILE             输出 JSON 路径，覆盖默认的 OUTPUT_FILE
-    --no-resume               禁用断点续爬（单页/target-new 模式下自动禁用）
-    --quiet                   压缩日志，每条视频只输出一行
-    -h / --help               帮助
-
-配置说明 (编辑脚本内 "配置区域"):
-    - MIN_PAGE_DELAY / MAX_PAGE_DELAY : 列表页请求间隔 (默认 3-6 秒)
-    - MIN_DETAIL_DELAY / MAX_DETAIL_DELAY : 详情页请求间隔 (默认 2-5 秒)
-    - MAX_PAGES : 限制最大爬取页数 (None=不限, 如 5=只爬前5页)
-    - OUTPUT_FILE : 输出文件名
-
-输出格式 (JSON):
-    {
-      "videos": [
-        {
-          "title": "视频标题",
-          "thumb_url": "https://...thumb/xxxx.jpg",
-          "video_url": "https://...mp43/xxxx.mp4?st=...",
-          "viewkey": "abc123...",
-          "source_id": "xxxx",
-          "detail_url": "https://...view_video.php?viewkey=..."
-        },
-        ...
-      ]
-    }
-
-注意:
-    1. 视频直链包含时效性token (e参数为过期时间戳)，会过期，需定期重新爬取
-    2. 脚本已内置随机延时，请勿移除，避免对服务器造成压力
-    3. 网站有Cloudflare保护，如遇到403/5xx错误，可能需要使用带cookie的session
-    4. 本脚本仅供学习交流，请遵守当地法律法规
-
-作者: OpenCode
-日期: 2026-05-22
-"""
-
-import argparse
-import requests
-import re
-import time
-import random
-import json
-import os
-import sys
-import html
-from urllib.parse import urljoin, unquote, urlparse
-from datetime import datetime
-
-try:
-    from bs4 import BeautifulSoup
-except ImportError:
-    print("错误: 缺少依赖库 beautifulsoup4")
-    print("请运行: pip install beautifulsoup4 lxml")
-    sys.exit(1)
-
-# ===================== 配置区域 =====================
-BASE_URL = "https://www.91porn.com/v.php"
-LIST_PARAMS = {
-    "category": "top",
-    "viewtype": "basic"
-}
-
-# 请求头 (模拟真实浏览器)
-HEADERS = {
-    "User-Agent": (
-        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-        "AppleWebKit/537.36 (KHTML, like Gecko) "
-        "Chrome/125.0.0.0 Safari/537.36"
-    ),
-    "Accept": (
-        "text/html,application/xhtml+xml,application/xml;"
-        "q=0.9,image/avif,image/webp,image/apng,*/*;"
-        "q=0.8,application/signed-exchange;v=b3;q=0.7"
-    ),
-    "Accept-Language": "zh-CN,zh;q=0.9",
-    # 注意: 不要包含 "br" (brotli)，除非安装了 brotli 库
-    # "Accept-Encoding": "gzip, deflate, br",
-    "Connection": "keep-alive",
-    "Upgrade-Insecure-Requests": "1",
-    "Sec-Fetch-Dest": "document",
-    "Sec-Fetch-Mode": "navigate",
-    "Sec-Fetch-Site": "none",
-    "Sec-Fetch-User": "?1",
-}
-
-# 延时配置 (秒) - 控制爬取频率，避免被封
-MIN_PAGE_DELAY = 3.0      # 列表页之间最小延时
-MAX_PAGE_DELAY = 6.0      # 列表页之间最大延时
-MIN_DETAIL_DELAY = 2.0    # 详情页之间最小延时
-MAX_DETAIL_DELAY = 5.0    # 详情页之间最大延时
-
-# 重试配置
-MAX_RETRIES = 3
-RETRY_DELAY = 5.0
-
-# 输出配置
-OUTPUT_FILE = "91porn_videos.json"
-MAX_PAGES = None          # 设置为 None 爬取所有页，或设置整数如 5 只爬前5页
-RESUME = True             # 是否跳过输出文件中已存在的 viewkey (断点续爬)
-MAX_EMPTY_PAGES = 2       # 连续空页数达到此值时停止爬取
-# ===================================================
-
-
-class Porn91Spider:
-    def __init__(
-        self,
-        output_file: str = None,
-        start_page: int = 1,
-        max_pages: int = None,
-        resume: bool = None,
-        max_empty_pages: int = None,
-        quiet: bool = False,
-        target_new: int = None,
-        seen_viewkeys: list = None,
-        stream_output: bool = False,
-    ):
-        """
-        构造函数。所有参数都有默认值，等同于使用脚本顶部的全局配置。
-        backend 调用时会传 output_file/seen_viewkeys/target_new，等价于：
-            "从第 1 页开始爬，跳过 seen_viewkeys 里的视频，凑够 target_new 个新视频后停止"
-
-        stream_output=True 时（backend 流水线用）：
-            - 每凑齐一个 video 直链就把该 entry 作为一行 JSON 写到 stdout 并 flush，
-              便于上层（Go crawler）边读边下载，不再等所有详情页处理完。
-            - 所有日志改走 stderr，避免与 stdout JSONL 流混合。
-            - --output 仍生效，作为离线归档用（脚本退出时一次性写完整 JSON）。
-        """
-        self.session = requests.Session()
-        self.session.headers.update(HEADERS)
-        # 91porn 没有固定 mode cookie 时，详情页首次请求可能返回与列表卡片
-        # 不一致的视频源；固定桌面模式让列表页和详情页解析保持一致。
-        self.session.cookies.set("mode", "d")
-
-        # 解析后的实际配置；优先使用构造参数，回退到模块级配置
-        self.output_file = output_file if output_file is not None else OUTPUT_FILE
-        self.start_page = max(1, int(start_page or 1))
-        # max_pages=None 表示不限制；max_pages=N 表示从 start_page 起爬 N 页
-        self.max_pages = max_pages if max_pages is None or max_pages > 0 else None
-        # resume 默认跟模块配置；单页模式下调用方应该显式传 False
-        self.resume = RESUME if resume is None else bool(resume)
-        self.max_empty_pages = (
-            MAX_EMPTY_PAGES if max_empty_pages is None else int(max_empty_pages)
-        )
-        # target_new 是 backend 触发时的核心模式：累计处理这么多新源视频后退出。
-        self.target_new = target_new if target_new and target_new > 0 else None
-        self.quiet = bool(quiet)
-        # stream_output：每解析出一个 video 直链立即输出一行 JSON 到 stdout
-        # （配合 backend Go 端 bufio.Scanner 实时消费，下载一个就开始下一个）。
-        # 开启后所有 log 都走 stderr。
-        self.stream_output = bool(stream_output)
-
-        # 添加重试适配器
-        try:
-            from requests.adapters import HTTPAdapter
-            from urllib3.util.retry import Retry
-            retry_strategy = Retry(
-                total=MAX_RETRIES,
-                backoff_factor=1,
-                status_forcelist=[429, 500, 502, 503, 504],
-            )
-            adapter = HTTPAdapter(max_retries=retry_strategy)
-            self.session.mount("https://", adapter)
-            self.session.mount("http://", adapter)
-        except ImportError:
-            pass  # urllib3 版本可能较低
-
-        self.results = []
-        self.pages_crawled = 0
-        self.processed_videos = 0
-        self.skipped_videos = 0
-        self.failed_videos = 0
-        self.skip_viewkeys = set()
-
-        # backend 通过 --seen-viewkeys-file 传进来一批已入库的历史 ID。
-        # 兼容旧名：文件里可能是 viewkey，也可能是新逻辑使用的 mp4 源 ID。
-        if seen_viewkeys:
-            for vk in seen_viewkeys:
-                if not vk:
-                    continue
-                vk = vk.strip()
-                if vk:
-                    self.skip_viewkeys.add(vk)
-
-        # 断点续爬：加载已有结果，跳过已处理的 viewkey
-        if self.resume and os.path.exists(self.output_file):
-            try:
-                with open(self.output_file, 'r', encoding='utf-8') as f:
-                    existing_data = json.load(f)
-                existing_videos = existing_data.get('videos', [])
-                self.results = existing_videos
-                for v in existing_videos:
-                    vk = v.get('viewkey', '')
-                    if vk:
-                        self.skip_viewkeys.add(vk)
-                self.processed_videos = existing_data.get('successful', 0)
-                self.failed_videos = existing_data.get('failed', 0)
-                self.log(f"加载已有数据: {len(self.results)} 个视频, 将跳过已处理项")
-            except Exception:
-                pass
-
-    def log(self, message: str):
-        """带时间戳的日志输出。stream_output 模式下走 stderr，避免污染 stdout JSONL。"""
-        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-        line = f"[{timestamp}] {message}"
-        if self.stream_output:
-            print(line, file=sys.stderr, flush=True)
-        else:
-            print(line)
-
-    def emit_stream_video(self, video: dict):
-        """stream_output 模式下把单条 video entry 作为一行 JSON 写到 stdout 并立即刷盘。
-        Go 端 bufio.Scanner 按行读取，每收到一行就立即下载视频和封面。"""
-        if not self.stream_output:
-            return
-        try:
-            print(json.dumps(video, ensure_ascii=False), flush=True)
-        except Exception as e:
-            # stdout 异常基本只在管道断开时发生（消费方进程死了）；
-            # 写到 stderr 让 backend 看到，然后让 crawl 循环自己 break。
-            print(f"[stream] emit failed: {e}", file=sys.stderr, flush=True)
-
-    def random_sleep(self, min_sec: float, max_sec: float):
-        """随机延时，模拟人类行为"""
-        delay = random.uniform(min_sec, max_sec)
-        if not self.quiet:
-            self.log(f"  随机延时 {delay:.2f} 秒...")
-        time.sleep(delay)
-
-    def fetch_page(self, url: str, description: str = "", referer: str = "") -> str:
-        """
-        获取页面HTML内容，带错误处理和重试
-        """
-        headers_extra = {}
-        if referer:
-            headers_extra["Referer"] = referer
-
-        for attempt in range(1, MAX_RETRIES + 1):
-            try:
-                self.log(f"正在请求: {description or url} (尝试 {attempt}/{MAX_RETRIES})")
-                response = self.session.get(url, timeout=30, headers=headers_extra)
-
-                # 检查是否被Cloudflare拦截 (需在 raise_for_status 之前)
-                if response.status_code == 403:
-                    self.log("警告: 收到 403 Forbidden，可能被拦截")
-                    if attempt < MAX_RETRIES:
-                        self.random_sleep(RETRY_DELAY, RETRY_DELAY + 3)
-                        continue
-                    return ""
-
-                response.raise_for_status()
-
-                # 优先使用 content.decode('utf-8')，避免 requests 编码检测问题
-                try:
-                    html_content = response.content.decode('utf-8', errors='replace')
-                except Exception:
-                    html_content = response.text
-
-                # Cloudflare 挑战检测：如果页面主要内容只有挑战页面，而非正常内容
-                # 注意：网站本身会加载 challenge-platform 脚本，所以不能仅凭此判断
-                is_cf_challenge = (
-                    "Just a moment" in html_content and
-                    len(html_content) < 8000
-                )
-                if is_cf_challenge:
-                    self.log("警告: 页面被Cloudflare挑战拦截，需要浏览器环境或正确cookie")
-                    if attempt < MAX_RETRIES:
-                        self.random_sleep(RETRY_DELAY, RETRY_DELAY + 5)
-                        continue
-                    return ""
-
-                return html_content
-            except requests.exceptions.HTTPError as e:
-                self.log(f"HTTP错误: {e}")
-                if attempt < MAX_RETRIES:
-                    self.random_sleep(RETRY_DELAY, RETRY_DELAY + 3)
-                else:
-                    return ""
-            except requests.exceptions.RequestException as e:
-                self.log(f"请求失败: {e}")
-                if attempt < MAX_RETRIES:
-                    self.random_sleep(RETRY_DELAY, RETRY_DELAY + 3)
-                else:
-                    self.log(f"达到最大重试次数，放弃: {url}")
-                    return ""
-        return ""
-
-    def parse_list_page(self, html: str) -> list:
-        """
-        解析列表页，提取视频基本信息
-        返回: [{title, detail_url, thumb_url, viewkey}, ...]
-        """
-        videos = []
-        soup = BeautifulSoup(html, 'lxml')
-
-        # 只解析正常视频卡片。页面中还混有 col-lg-8 的异常大卡片，里面的标题、
-        # thumb、detail URL 会串到其它视频，不能作为入库来源。
-        video_cards = soup.select('div.col-xs-12.col-sm-4.col-md-3.col-lg-3')
-
-        seen_cards = set()
-
-        for card in video_cards:
-            link = card.find('a', href=re.compile(r'view_video\.php\?viewkey='))
-            if not link:
-                continue
-            href = link.get('href', '')
-            if not href:
-                continue
-
-            # 提取 viewkey
-            match = re.search(r'viewkey=([^&]+)', href)
-            if not match:
-                continue
-            viewkey = match.group(1)
-
-            detail_url = urljoin(BASE_URL, href)
-
-            # 提取标题
-            title = self._extract_title(link)
-
-            # 提取列表卡片来源 ID 和封面图 URL
-            thumb_url = ""
-            source_id = ""
-            overlay = link.find(id=re.compile(r'^playvthumb_\d+$'))
-            if overlay:
-                source_id = overlay.get('id', '').rsplit('_', 1)[-1]
-            img = link.find('img', class_=re.compile(r'img-responsive'))
-            if img:
-                thumb_url = img.get('src', '') or img.get('data-original', '')
-                if thumb_url:
-                    thumb_url = urljoin(BASE_URL, thumb_url)
-            if not source_id and thumb_url:
-                source_id = self._extract_thumb_source_id(thumb_url)
-
-            card_key = source_id or detail_url
-            if card_key in seen_cards:
-                continue
-            seen_cards.add(card_key)
-
-            videos.append({
-                "title": title,
-                "detail_url": detail_url,
-                "thumb_url": thumb_url,
-                "viewkey": viewkey,
-                "source_id": source_id
-            })
-
-        return videos
-
-    def _extract_title(self, link) -> str:
-        """
-        从视频链接标签中提取并清理标题
-        """
-        # 优先从 span.video-title 获取 (已渲染的干净标题)
-        title_el = link.find('span', class_=re.compile(r'video-title'))
-        if title_el:
-            title = title_el.get_text(strip=True)
-            if title:
-                return html.unescape(title)
-
-        # 备用: 从 link 的 title 属性提取
-        title = link.get('title', '').strip()
-        if title:
-            return html.unescape(title)
-
-        # 最后手段: 从链接文本提取并清理前缀
-        text = link.get_text(separator=' ', strip=True)
-        # 去掉前缀: "HD" / "91" / 时间戳 "HH:MM:SS"
-        text = re.sub(r'^(HD\s+|91\s+)?\d{2}:\d{2}:\d{2}\s*', '', text)
-        text = re.sub(r'\s+', ' ', text).strip()
-        return html.unescape(text)[:120]
-
-    def parse_detail_page(self, html: str) -> dict:
-        """
-        解析详情页，提取视频直链
-        返回: {"video_url": "...", "source_id": "...", "title": "..."} 或空字典
-        """
-        result = {}
-
-        if not html:
-            return result
-
-        title = self._extract_detail_title(html)
-        if title:
-            result["title"] = title
-
-        # 方法1: 解码 strencode2 (主要方式, 页面通过 document.write 动态写入 video 标签)
-        # 格式: document.write(strencode2("%3c%73%6f..."));
-        strencode_match = re.search(r'strencode2\(["\']([^"\']+)["\']\)', html)
-        if strencode_match:
-            encoded = strencode_match.group(1)
-            try:
-                # strencode2 在JS中等价于 unescape / decodeURIComponent
-                decoded = unquote(encoded)
-
-                # 从解码后的 HTML 片段中提取 src
-                src_match = re.search(r"src=['\"]([^'\"]+)['\"]", decoded)
-                if src_match:
-                    video_url = src_match.group(1)
-                    # 规范化双斜杠 (如 https://host//path -> https://host/path)
-                    video_url = re.sub(r'(https?://[^/]+)//+', r'\1/', video_url)
-                    result["video_url"] = video_url
-                    result["source_id"] = self._extract_source_id(video_url)
-                    return result
-            except Exception as e:
-                self.log(f"  解码 strencode2 失败: {e}")
-
-        # 方法2: 通用正则匹配页面中的 mp4 链接 (备用, 过滤广告)
-        mp4_match = re.search(
-            r'https?://[^\s"\'<>]+\.mp4[^\s"\'<>]*',
-            html
-        )
-        if mp4_match:
-            url = mp4_match.group(0)
-            if 'kwai' not in url and 'ad-' not in url.lower():
-                result["video_url"] = url
-                result["source_id"] = self._extract_source_id(url)
-                return result
-
-        return result
-
-    def _extract_detail_title(self, html_text: str) -> str:
-        soup = BeautifulSoup(html_text, 'lxml')
-        title_el = soup.find('title')
-        if not title_el:
-            return ""
-        title = title_el.get_text(" ", strip=True)
-        title = re.sub(r'\s*-\s*91porn.*$', '', title, flags=re.IGNORECASE).strip()
-        return html.unescape(title)[:160]
-
-    def _extract_source_id(self, video_url: str) -> str:
-        path = urlparse(video_url or "").path
-        name = os.path.basename(path)
-        stem, ext = os.path.splitext(name)
-        if ext.lower() not in {".mp4", ".m4v", ".mov", ".webm", ".mkv", ".avi"}:
-            return ""
-        source_id = re.sub(r'[^0-9]+', '', stem)
-        if not source_id or source_id != stem:
-            return ""
-        return source_id
-
-    def _extract_thumb_source_id(self, thumb_url: str) -> str:
-        path = urlparse(thumb_url or "").path
-        match = re.search(r'/thumb/(\d+)\.[A-Za-z0-9]+$', path)
-        return match.group(1) if match else ""
-
-    def _thumb_url_for_source(self, thumb_url: str, source_id: str) -> str:
-        if not thumb_url or not source_id:
-            return thumb_url
-        parsed = urlparse(thumb_url)
-        match = re.search(r'/thumb/([^/?#]+)\.[A-Za-z0-9]+$', parsed.path)
-        if not match:
-            return thumb_url
-        current = match.group(1)
-        if current == source_id:
-            return thumb_url
-        path = re.sub(
-            r'/thumb/[^/?#]+\.[A-Za-z0-9]+$',
-            f'/thumb/{source_id}.jpg',
-            parsed.path,
-        )
-        return parsed._replace(path=path, query="", fragment="").geturl()
-
-    def crawl(self):
-        """
-        主爬取流程。停止条件（任一满足即停）：
-          - 达到 max_pages 配置
-          - 连续 max_empty_pages 页都没有视频
-          - target_new 模式下，已经累计处理 target_new 个新视频
-        """
-        self.log("=" * 60)
-        self.log("91porn 视频爬虫启动")
-        self.log("=" * 60)
-        self.log(f"配置: 列表页延时 {MIN_PAGE_DELAY}-{MAX_PAGE_DELAY}s, 详情页延时 {MIN_DETAIL_DELAY}-{MAX_DETAIL_DELAY}s")
-        self.log(f"配置: 最大重试 {MAX_RETRIES} 次, 连续空页上限 {self.max_empty_pages}")
-        self.log(f"配置: 起始页 {self.start_page}, 最大爬取页数 {self.max_pages if self.max_pages else '不限'}")
-        if self.target_new:
-            self.log(f"配置: 目标新增视频数 {self.target_new}")
-        self.log(f"配置: 输出文件 {os.path.abspath(self.output_file)}")
-        if self.skip_viewkeys:
-            self.log(f"配置: 已跳过 {len(self.skip_viewkeys)} 个已知 viewkey")
-        self.log("")
-
-        page_num = self.start_page
-        consecutive_empty = 0
-        crawled_in_session = 0
-
-        while True:
-            if self.max_pages is not None and crawled_in_session >= self.max_pages:
-                self.log(f"达到配置的页数上限 {self.max_pages}，停止")
-                break
-            if consecutive_empty >= self.max_empty_pages:
-                self.log(f"连续 {self.max_empty_pages} 页无结果，已达到末尾")
-                break
-            if self.target_new is not None and self.processed_videos >= self.target_new:
-                self.log(f"已累计 {self.processed_videos} 个新视频，达到目标 {self.target_new}，停止")
-                break
-
-            if page_num == 1:
-                page_url = f"{BASE_URL}?category=top&viewtype=basic"
-            else:
-                page_url = f"{BASE_URL}?category=top&viewtype=basic&page={page_num}"
-
-            if crawled_in_session > 0:
-                self.log("")
-                self.random_sleep(MIN_PAGE_DELAY, MAX_PAGE_DELAY)
-
-            self.log(f"[页 {page_num}] 请求: {page_url}")
-            page_html = self.fetch_page(page_url, f"列表页 第{page_num}页")
-
-            if not page_html:
-                self.log(f"[页 {page_num}] 获取失败，跳过")
-                consecutive_empty += 1
-                page_num += 1
-                crawled_in_session += 1
-                continue
-
-            page_videos = self.parse_list_page(page_html)
-
-            # 判断页面是否真的没有视频（而非全部已处理）
-            if not page_videos:
-                self.log(f"[页 {page_num}] 页面无视频，可能已到末尾")
-                consecutive_empty += 1
-                page_num += 1
-                crawled_in_session += 1
-                continue
-
-            consecutive_empty = 0
-
-            # 过滤已处理的 viewkey，只保留新视频
-            new_videos = [v for v in page_videos if v['viewkey'] not in self.skip_viewkeys]
-            skipped_on_page = len(page_videos) - len(new_videos)
-
-            if skipped_on_page > 0:
-                self.log(f"[页 {page_num}] 发现 {len(page_videos)} 个链接, 其中 {skipped_on_page} 个已处理, {len(new_videos)} 个新视频")
-            else:
-                self.log(f"[页 {page_num}] 发现 {len(new_videos)} 个视频")
-
-            if new_videos:
-                self._process_video_list(new_videos, referer=page_url)
-            self.pages_crawled += 1
-            page_num += 1
-            crawled_in_session += 1
-
-        self._save_results()
-        self._print_summary()
-
-    def _process_video_list(self, videos: list, referer: str = ""):
-        """
-        处理一批视频列表，逐个获取详情页
-        """
-        for idx, video in enumerate(videos, 1):
-            # target_new 模式下，凑够后立即停止，不再请求详情页
-            if self.target_new is not None and self.processed_videos >= self.target_new:
-                return
-            # 跳过已处理的 viewkey (断点续爬)
-            if video['viewkey'] in self.skip_viewkeys:
-                self.log(f"  [SKIP] 已处理过: {video['viewkey']}")
-                self.skipped_videos += 1
-                continue
-
-            self.log(f"  处理视频 {idx}/{len(videos)}: {video['title'][:40]}...")
-
-            # 延时控制 (同一批次内第一个视频不延时)
-            if idx > 1:
-                self.random_sleep(MIN_DETAIL_DELAY, MAX_DETAIL_DELAY)
-
-            # 获取详情页
-            detail_html = self.fetch_page(video['detail_url'], f"详情页 viewkey={video['viewkey']}", referer=referer)
-
-            if not detail_html:
-                self.log(f"  [FAIL] 详情页获取失败: {video['viewkey']}")
-                video["video_url"] = ""
-                self.results.append(video)
-                self.skip_viewkeys.add(video['viewkey'])
-                self.failed_videos += 1
-                continue
-
-            # 解析视频直链
-            detail_info = self.parse_detail_page(detail_html)
-
-            if detail_info.get("video_url"):
-                video["video_url"] = detail_info["video_url"]
-                if detail_info.get("title"):
-                    video["title"] = detail_info["title"]
-                list_source_id = video.get("source_id", "")
-                detail_source_id = detail_info.get("source_id", "")
-                if list_source_id and detail_source_id and list_source_id != detail_source_id:
-                    self.log(
-                        f"  [FAIL] 详情页视频源不匹配: list_source_id={list_source_id} "
-                        f"detail_source_id={detail_source_id} viewkey={video['viewkey']}"
-                    )
-                    self.failed_videos += 1
-                    self.skip_viewkeys.add(video['viewkey'])
-                    continue
-                if not list_source_id and detail_source_id:
-                    video["source_id"] = detail_source_id
-                if video.get("source_id"):
-                    video["thumb_url"] = self._thumb_url_for_source(
-                        video.get("thumb_url", ""),
-                        video["source_id"],
-                    )
-                    if video["source_id"] in self.skip_viewkeys:
-                        self.log(f"  [SKIP] 已处理过 source_id: {video['source_id']}")
-                        self.skipped_videos += 1
-                        continue
-                self.results.append(video)
-                self.skip_viewkeys.add(video['viewkey'])
-                if video.get("source_id"):
-                    self.skip_viewkeys.add(video["source_id"])
-                self.processed_videos += 1
-                self.log(f"  [OK] 成功提取视频直链")
-                # 流式：立刻把这条 entry 交给 Go 端开始下载，不等本批余下视频
-                self.emit_stream_video(video)
-            else:
-                self.log(f"  [FAIL] 未找到视频直链: {video['viewkey']}")
-                video["video_url"] = ""
-                self.results.append(video)
-                self.skip_viewkeys.add(video['viewkey'])
-                self.failed_videos += 1
-
-    def _save_results(self):
-        """
-        保存结果到JSON文件
-        """
-        output_data = {
-            "crawl_time": datetime.now().isoformat(),
-            "source_url": BASE_URL,
-            "pages_crawled": self.pages_crawled,
-            "total_videos": len(self.results),
-            "successful": self.processed_videos,
-            "skipped": self.skipped_videos,
-            "failed": self.failed_videos,
-            "videos": self.results
-        }
-
-        try:
-            # 保证父目录存在；写入临时文件后原子 rename，避免读到半截 JSON
-            out_path = self.output_file
-            parent = os.path.dirname(os.path.abspath(out_path))
-            if parent:
-                os.makedirs(parent, exist_ok=True)
-            tmp_path = out_path + ".part"
-            with open(tmp_path, 'w', encoding='utf-8') as f:
-                json.dump(output_data, f, ensure_ascii=False, indent=2)
-            os.replace(tmp_path, out_path)
-            self.log(f"结果已保存到: {os.path.abspath(out_path)}")
-        except Exception as e:
-            self.log(f"保存文件失败: {e}")
-            # 尝试输出到控制台作为备份
-            print("\n--- 备份输出 ---")
-            print(json.dumps(output_data, ensure_ascii=False, indent=2))
-
-    def _print_summary(self):
-        """
-        打印爬取摘要
-        """
-        self.log("")
-        self.log("=" * 60)
-        self.log("爬取完成!")
-        self.log("=" * 60)
-        self.log(f"爬取页数: {self.pages_crawled}")
-        self.log(f"总视频数: {len(self.results)}")
-        self.log(f"成功提取直链: {self.processed_videos}")
-        self.log(f"跳过(已处理): {self.skipped_videos}")
-        self.log(f"失败/缺失直链: {self.failed_videos}")
-        self.log(f"输出文件: {os.path.abspath(self.output_file)}")
-        self.log("=" * 60)
-
-
-def print_help():
-    print("""
-================================================
-    91porn 视频爬虫 v1.0
-================================================
-
-本脚本将爬取 91porn "本月最热" 分类下的所有视频信息：
-  - 视频名称
-  - 封面图直链
-  - 视频直链 (MP4)
-
-依赖安装:
-    pip install requests beautifulsoup4 lxml
-
-使用方法:
-    python spider_91porn.py
-
-配置说明 (编辑脚本内 "配置区域"):
-    MIN_PAGE_DELAY / MAX_PAGE_DELAY : 列表页请求间隔 (默认 3-6 秒)
-    MIN_DETAIL_DELAY / MAX_DETAIL_DELAY : 详情页请求间隔 (默认 2-5 秒)
-    MAX_PAGES : 限制最大爬取页数 (None=不限, 如 5=只爬前5页)
-    OUTPUT_FILE : 输出文件名 (默认 91porn_videos.json)
-
-按 Ctrl+C 可随时中断并保存已爬取的数据
-
-注意:
-    1. 视频直链包含时效性token，会过期，需定期重新爬取
-    2. 脚本已内置随机延时，请勿移除，避免对服务器造成压力
-    3. 如遇到Cloudflare拦截，需要先通过浏览器获取Cookie
-    4. 本脚本仅供学习交流，请遵守当地法律法规
-================================================
-""")
-
-
-def main():
-    if len(sys.argv) > 1 and sys.argv[1] in ('-h', '--help', 'help'):
-        print_help()
-        return
-
-    parser = argparse.ArgumentParser(
-        prog="spider_91porn.py",
-        description="91porn 视频元数据爬虫",
-        add_help=False,  # 让 -h/--help 走 print_help() 中文版本
-    )
-    parser.add_argument("--page", type=int, default=None,
-                        help="只爬指定页（单页模式，配合 --output 用于定时任务）")
-    parser.add_argument("--output", type=str, default=None,
-                        help="输出 JSON 路径，覆盖默认 OUTPUT_FILE")
-    parser.add_argument("--max-pages", type=int, default=None,
-                        help="单页模式下，从 --page 起最多再爬几页（默认 1）")
-    parser.add_argument("--no-resume", action="store_true",
-                        help="禁用断点续爬（单页模式默认禁用）")
-    parser.add_argument("--quiet", action="store_true",
-                        help="压缩日志，每条视频只输出关键事件")
-    parser.add_argument("--target-new", type=int, default=None,
-                        help="目标新增模式：从 page 1 起翻页直到累计处理这么多新源视频后停止（backend 凌晨任务用）")
-    parser.add_argument("--seen-viewkeys-file", type=str, default=None,
-                        help="文件路径，每行一个已处理过的 viewkey 或 mp4 源 ID；脚本会跳过这些视频")
-    parser.add_argument("--stream-output", action="store_true",
-                        help="流式模式：每解析一条视频直链就立即把它作为一行 JSON 写到 stdout 并 flush；"
-                             "日志改走 stderr。配合 backend 边读边下载使用。")
-
-    args, _ = parser.parse_known_args()
-
-    print("""
-================================================
-    91porn 视频爬虫启动中...
-================================================
-按 Ctrl+C 可随时中断并保存进度
-""")
-
-    # 加载已知 ID（来自 backend 的 catalog 已入库列表；兼容旧参数名）
-    seen_viewkeys = []
-    if args.seen_viewkeys_file:
-        try:
-            with open(args.seen_viewkeys_file, 'r', encoding='utf-8') as f:
-                for line in f:
-                    line = line.strip()
-                    if line:
-                        seen_viewkeys.append(line)
-        except FileNotFoundError:
-            print(f"警告: --seen-viewkeys-file 不存在: {args.seen_viewkeys_file}")
-        except Exception as e:
-            print(f"警告: 读取 --seen-viewkeys-file 失败: {e}")
-
-    # 决定运行模式
-    if args.target_new is not None:
-        # 凑够 N 个新视频模式：从 page 1 起翻页，直到累计 target_new 个新视频
-        spider = Porn91Spider(
-            output_file=args.output,
-            start_page=1,
-            max_pages=None,
-            resume=False,  # 凑够 N 模式靠 seen_viewkeys 去重，不读 OUTPUT_FILE
-            quiet=args.quiet,
-            target_new=args.target_new,
-            seen_viewkeys=seen_viewkeys,
-            stream_output=args.stream_output,
-        )
-    elif args.page is not None:
-        # 单页模式（保留作手动调试用）：start_page=N, max_pages=1
-        start_page = max(1, args.page)
-        max_pages = args.max_pages if args.max_pages and args.max_pages > 0 else 1
-        spider = Porn91Spider(
-            output_file=args.output,
-            start_page=start_page,
-            max_pages=max_pages,
-            resume=False,
-            quiet=args.quiet,
-            seen_viewkeys=seen_viewkeys,
-            stream_output=args.stream_output,
-        )
-    else:
-        # 全量模式（向后兼容）：从 page 1 起爬到末尾
-        spider = Porn91Spider(
-            output_file=args.output,
-            resume=False if args.no_resume else None,
-            quiet=args.quiet,
-            seen_viewkeys=seen_viewkeys,
-            stream_output=args.stream_output,
-        )
-
-    try:
-        spider.crawl()
-    except KeyboardInterrupt:
-        spider.log("\n用户中断，正在保存已爬取的数据...")
-        spider._save_results()
-        spider._print_summary()
-        sys.exit(0)
-    except Exception as e:
-        spider.log(f"发生未预料的错误: {e}")
-        import traceback
-        traceback.print_exc()
-        spider._save_results()
-        raise
-
-
-if __name__ == "__main__":
-    main()

Dockerfile

@@ -0,0 +1,68 @@
+# ---- Stage 1: Build frontend ----
+FROM node:20-slim AS frontend
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY tsconfig.json vite.config.ts index.html ./
+COPY public/ public/
+COPY src/ src/
+RUN npm run build
+
+# ---- Stage 2: Build backend ----
+FROM golang:1.23-bookworm AS backend
+
+WORKDIR /app/backend
+
+COPY backend/go.mod backend/go.sum ./
+COPY backend/vendor/ vendor/
+COPY backend/cmd/ cmd/
+COPY backend/internal/ internal/
+RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/server ./cmd/server
+
+# ---- Stage 3: Runtime ----
+FROM debian:bookworm-slim AS runtime
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    ffmpeg \
+    openssl \
+    python3 \
+    python3-bs4 \
+    python3-lxml \
+    python3-requests \
+    python3-socks \
+    tar \
+    tzdata \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python3 -c "import requests, bs4, lxml, socks"
+
+WORKDIR /opt/video-site-91
+
+COPY --from=backend /out/server ./server
+COPY --from=frontend /app/dist ./dist
+COPY backend/config.example.yaml ./config.example.yaml
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+
+ARG VERSION=dev
+
+ENV VIDEO_CONFIG=/opt/video-site-91/data/config.yaml \
+    VIDEO_FRONTEND_DIR=/opt/video-site-91/dist \
+    VIDEO_GITHUB_REPO=nianzhibai/91 \
+    VIDEO_IMAGE_VERSION=${VERSION} \
+    VIDEO_LISTEN_PORT=9191 \
+    VIDEO_VERSION_FILE=/opt/video-site-91/data/.version
+
+RUN chmod +x ./server /usr/local/bin/docker-entrypoint.sh
+
+VOLUME ["/opt/video-site-91/data"]
+EXPOSE 9191
+
+ENTRYPOINT ["docker-entrypoint.sh"]
+CMD ["./server"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nianzhibai
+
+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

@@ -1,171 +1,215 @@
-# 视频聚合站
+# 91
 
-把散落在不同网盘里的视频，整理成一个可以自己登录、自己浏览、自己管理的私人视频站。
+<p align="center">
+  <img width="120" height="120" alt="91" src="https://github.com/user-attachments/assets/5b323c94-bbd3-4dce-bbc8-adc86935b7de" />
+</p>
 
-网盘适合存东西，却不适合慢慢看东西。文件多了以后，你很难记住它们在哪里、叫什么、有没有看过、还能不能快速预览。这个项目做的是中间那一层：文件仍然留在原来的网盘里，但你可以用一个更像视频站的界面去搜索、筛选、预览和管理它们。
+<p align="center">
+  😄 个人私有视频站 😄
+</p>
 
-它不是另一个网盘客户端，也不是内容平台。它更像是给你自己的视频收藏做一个入口：安静、集中、可控。
+<p align="center">
+  <a href="#快速开始">快速开始</a> ·
+  <a href="#功能特性">功能特性</a> ·
+  <a href="#预览图">预览图</a> ·
+  <a href="#数据存放位置">数据目录</a> ·
+  <a href="#许可证">许可证</a>
+</p>
 
-## 它能做什么
+---
 
-- **统一入口**：把 115、PikPak、夸克、联通沃盘、OneDrive、本地上传和可选的 91 爬虫源放在同一个站里浏览。
-- **像视频站一样浏览**：首页推荐、最新视频、列表页、搜索、标签筛选、详情播放和相关推荐都已经接好。
-- **自动生成预览**：后端会用 ffmpeg 在本地生成封面和短 teaser，扫到新视频后不用一条条手动整理。
-- **保留网盘本身**：视频文件不需要搬家，播放时由后端按来源取链和代理。
-- **后台可管理**：在管理后台添加网盘、扫描所有网盘、编辑视频信息、维护标签、切换主题。
-- **首次部署更直接**：第一次访问时会要求设置管理员用户名和密码，设置后保存到本地配置文件。
-- **适合长期运行**：扫描、预览、隐藏视频、标签归类这些重复工作，都尽量交给系统处理。
+## 功能特性
 
-## 适合谁
+- **多后端支持** — 兼容 115 云盘、PikPak 云盘、123网盘、联通网盘、光鸭网盘、OneDrive、Google Drive 和本地存储
+- **低带宽播放** — 115 云盘、PikPak 云盘、123网盘、联通网盘、光鸭网盘、OneDrive 支持302模式，在线播放视频时，不占用服务器带宽，播放体验不受服务器带宽影响；Google Drive 不支持302模式，走服务器中转，观看体验会受服务器带宽影响
+- **封面 & 预览片段** — 自动为每个视频生成封面图和预览片段，首页快速选片
+- **爬虫脚本** — 项目支持导入自定义脚本，但是有一些规范，具体可以参考 [SpiderFor91](https://github.com/Just-Spider/SpiderFor91)，项目不再内置任何爬虫脚本
+- **短视频模式** — 一键切换抖音风格，沉浸刷片
+---
 
-如果你有一批视频散落在多个网盘里，想把它们整理成一个自己的私有站点，这个项目会比较合适。
+## 预览图
 
-如果你只是想临时播放单个文件，直接用网盘客户端更简单；如果你想做公开视频网站，这个项目也不是为那个场景设计的。它的重点是个人部署、个人管理、个人观看。
+### 电脑端
 
-## 支持的来源
+<p>
+  <img width="49%" alt="首页" src="https://github.com/user-attachments/assets/9808fceb-760b-4dd5-b7d2-8622b95b90d5" />
+  <img width="49%" alt="播放页" src="https://github.com/user-attachments/assets/859db4aa-1fba-44f2-bb46-1db07c2f964f" />
+</p>
 
-- 115 网盘
-- PikPak
-- 91 爬虫源
-- 夸克网盘
-- 联通沃盘
-- OneDrive
-- 本地上传
+<p>
+  <img width="49%" alt="主题切换" src="https://github.com/user-attachments/assets/96bea37a-8764-413e-9b70-1856b4ae0cd2" />
+  <img width="49%" alt="管理页" src="https://github.com/user-attachments/assets/29c1e27a-7651-4dfc-93dd-556331844214" />
+</p>
 
-91 爬虫源是一种特殊存储来源，用来把爬虫抓到的视频和封面接入站内目录。它不是必须项；如果你只想管理自己的网盘，可以完全不启用。
+### 手机端
+
+<p align="center">
+  <img width="1284" height="1134" alt="手机端" src="https://github.com/user-attachments/assets/bdb7a86c-a4e5-483e-a307-e02c0bb34dac" />
+</p>
+
+---
 
 ## 快速开始
 
-需要先准备：
-
-- Node.js 18+
-- Go 1.23+
-- ffmpeg 和 ffprobe
-
-启动项目：
+### 方式一：一键安装脚本（推荐）
 
 ```bash
-npm install
-./start.sh
-```
-
-默认访问地址：
-
-- 前台：`http://127.0.0.1:9191/`
-- 后台：`http://127.0.0.1:9191/admin`
-- 后端：`127.0.0.1:9192`
-
-第一次打开时，如果还没有设置管理员账号，页面会引导你创建用户名和密码。保存后会写入本地的 `backend/config.yaml`。
-
-常用命令：
-
-```bash
-./start.sh --status
-./start.sh --restart
-./start.sh --stop
-```
-
-需要前端热更新时：
-
-```bash
-FRONTEND_MODE=dev ./start.sh --restart
-```
-
-## 新服务器一键安装
-
-如果你只是想在一台 Ubuntu / Debian 服务器上尽快跑起来，推荐使用预编译安装脚本。普通用户不需要安装 Go、Node.js，也不需要自己编译；脚本会按服务器 CPU 架构下载 GitHub Release 里的预编译包，安装运行依赖，写入 systemd 服务并启动。
-
-```bash
-sudo apt update
-sudo apt install -y curl ca-certificates
+sudo apt update && sudo apt install -y curl ca-certificates
 curl -fsSL https://raw.githubusercontent.com/nianzhibai/91/main/install.sh -o install.sh
 sudo bash install.sh
 ```
 
 部署完成后访问：
 
-- 前台：`http://服务器IP:9191/`
-- 后台：`http://服务器IP:9191/admin`
+| 地址 | 说明 |
+|------|------|
+| `http://服务器IP:9191/` | 前台 |
+| `http://服务器IP:9191/admin` | 后台管理 |
 
-第一次打开后台会要求设置管理员用户名和密码。常用维护命令：
+**注意：如果首次访问，显示502，可以运行 `91 restart` 重启一下服务**
+
+安装后自动注册 `91` 管理命令：
 
 ```bash
-sudo bash install.sh status
-sudo bash install.sh logs
-sudo bash install.sh update
-sudo bash install.sh restart
-sudo bash install.sh stop
+91            # 打开管理菜单
+91 status     # 查看运行状态
+91 logs       # 查看日志
+91 update     # 更新到最新版本
+91 restart    # 重启服务
+91 stop       # 停止服务
 ```
 
-安装后会自动创建 `91` 指令，和 OpenList 的管理指令类似：
+> `video-site-91` 为等效别名，两者可互换使用。
+
+**已部署用户升级：**
 
 ```bash
-91          # 打开管理菜单
-91 status   # 查看状态
-91 logs     # 查看日志
-91 update   # 更新
-91 restart  # 重启
-91 stop     # 停止
+91 update
 ```
 
-同时也保留 `video-site-91` 作为同等别名。
+升级会保留现有 `config.yaml`、数据库、封面、预览、上传文件和爬虫数据。脚本会自动安装或检查 `ffmpeg` / `ffprobe` 等运行依赖，并在新版本启动失败时回滚到升级前文件。
 
-想换端口：
+**自定义端口：**
 
 ```bash
 FRONTEND_PORT=8080 sudo -E bash install.sh
 ```
 
-如果服务器还有云厂商安全组，请记得放行对应端口，默认是 `9191/tcp`。
+**旧版本升级（v0.0.2 之前）：**
 
-如果你是项目维护者，要预先编译发布包：
+旧版脚本直接执行 `91 update` 可能失败，先执行以下修复命令：
 
 ```bash
-scripts/build-release.sh
+curl -fsSL https://raw.githubusercontent.com/nianzhibai/91/main/install.sh -o /tmp/install-91.sh
+sudo bash /tmp/install-91.sh update
 ```
 
-它会生成：
+---
 
-- `release/video-site-91-linux-amd64.tar.gz`
-- `release/video-site-91-linux-arm64.tar.gz`
+### 方式二：Docker Compose 部署
 
-把这两个文件上传到 GitHub Release 后，`install.sh` 就能自动下载。仓库也带了 GitHub Actions：推送 `v*` 标签时会自动构建并上传这两个 Release 包。
-
-源码部署仍然保留在 `deploy.sh`，适合你想在服务器上直接 clone、编译和调试时使用。
-
-## 第一次使用
-
-1. 打开 `http://127.0.0.1:9191/`，先完成管理员账号设置。
-2. 进入 `/admin`，在网盘管理里新建一个来源。
-3. 填入名称和对应凭证，保存。
-4. 点击“扫描所有网盘”，等待视频入库。
-5. 回到前台，用首页、搜索、标签和详情页浏览内容。
-
-## 数据放在哪里
-
-项目会把运行数据保存在本地：
-
-- `backend/config.yaml`：本地配置、管理员账号、网盘凭证。
-- `backend/data/video-site.db`：SQLite 数据库。
-- `backend/data/previews/`：本地生成的封面和 teaser。
-
-这些文件不应该提交到公开仓库。仓库里的 `backend/config.example.yaml` 只是模板，不应该放真实账号、Cookie、Token 或密码。
-
-## 更多文档
-
-根目录 README 只保留项目介绍和最短上手路径。更细的实现、接口、网盘字段和部署方式可以看：
-
-- [backend/README.md](backend/README.md)
-- [video-site-implementation-plan.md](video-site-implementation-plan.md)
-
-## 开发验证
+**1. 准备目录**
 
 ```bash
-npm run lint
-npm test
-cd backend && go test ./... -count=1
+mkdir -p video-site-91 && cd video-site-91
 ```
 
-## 使用边界
+**2. 创建 `docker-compose.yml`**
 
-这个项目面向个人私有部署。请只接入你有权访问和管理的内容，并遵守对应网盘、站点服务条款以及所在地法律法规。
+```yaml
+services:
+  video-site-91:
+    image: ghcr.io/nianzhibai/91:stable
+    container_name: video-site-91
+    ports:
+      - "9191:9191"
+    volumes:
+      - ./data:/opt/video-site-91/data
+    restart: unless-stopped
+```
+创建yml文件后运行下面指令
+```bash
+docker compose pull
+docker compose up -d
+```
+
+如果想固定某个 Release 版本，可以改成明确的 tag，例如：
+
+```yaml
+image: ghcr.io/nianzhibai/91:v0.0.6
+```
+
+或直接拉取仓库内置配置：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nianzhibai/91/main/docker-compose.yml -o docker-compose.yml
+```
+
+**3. 启动**
+
+```bash
+docker compose up -d
+```
+
+**常用命令：**
+
+```bash
+docker compose logs -f       # 查看日志
+docker compose pull          # 拉取最新正式版 stable 镜像
+docker compose up -d         # 更新并重启
+```
+
+> 所有配置、数据库、封面、预览及上传文件均保存在 `./data/` 目录下。
+> 从旧版本升级 Docker 部署时，执行 `docker compose pull && docker compose up -d` 即可；`./data/` 不会被镜像更新覆盖。
+
+---
+
+## 数据存放位置
+
+### 一键脚本部署
+
+| 路径 | 内容 |
+|------|------|
+| `/opt/video-site-91/config.yaml` | 配置文件、管理员账号、网盘凭证 |
+| `/opt/video-site-91/data/video-site.db` | SQLite 数据库 |
+| `/opt/video-site-91/data/previews/` | 封面图和预览片段 |
+
+### Docker Compose 部署
+
+| 路径 | 内容 |
+|------|------|
+| `./data/config.yaml` | 配置文件、管理员账号、网盘凭证 |
+| `./data/video-site.db` | SQLite 数据库 |
+| `./data/previews/` | 封面图和预览片段 |
+| `./data/uploads/` | 本地上传的视频文件 |
+| `./data/spider91/` | 91 爬虫抓取的视频文件 |
+
+---
+
+## 使用须知
+
+本项目面向**个人私有部署**，请仅接入你有权访问和管理的内容，并遵守对应网盘、站点的服务条款及所在地法律法规。
+
+> 不对外传播，仅限个人使用。
+
+---
+
+## PR提交规范
+欢迎大家提交PR，一起来完善这个项目，但是这里要说明一下PR提交的规范
+1. 一个PR的功能改动要单一，不建议一个PR修改了大量功能。单个PR单个功能修改，这样也更容易Merge
+2. 完善项目的PR比新增功能的PR更容易Merge（例如：例如你发现开发者没有实现爬取的视频上传到某个网盘，并且你有这个需求，此时你可以实现一下这个功能然后提交PR，也感谢你为开发者分担工作量）
+3. 新增功能的PR不容易Merge，因为某些功能的需求可能不是所有人都需要的，如果一味的不断增加功能，会让项目变得过于庞大。当然如果你肯定你的新功能和想法很好，并且相信将会对于项目有很大的改善，那么热烈欢迎你的PR
+
+---
+
+## 许可证
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+---
+
+## 致谢
+
+- [OpenList](https://github.com/OpenListTeam/OpenList) — 优秀的开源项目
+- [LinuxDo](https://linux.do/) — 学 AI 上 L 站
+- [NodeSeek](https://nodeseek.com/) — MJJ 上 N 站

backend/README.md

@@ -2,8 +2,8 @@
 
 视频聚合站的 Go 后端。提供三件事：
 
-1. 多家网盘统一抽象（夸克 / 115 / PikPak / 联通沃盘 / OneDrive）
-2. 视频元数据目录（SQLite）+ 扫描 + teaser 预生成
+1. 多家网盘统一抽象（夸克 / 115 / PikPak / 联通网盘 / 光鸭网盘 / OneDrive / Google Drive / 本地存储）
+2. 视频元数据目录（SQLite）+ 扫描 + 预览视频预生成
 3. REST API（前台）+ 管理后台 + 直链代理
 4. 标签池、视频隐藏、按网盘统计和详情页来源网盘类型展示能力
 
@@ -19,10 +19,13 @@ internal/
     quark/                  夸克（自己实现，参考 OpenList quark_uc）
     p115/                   115（壳子 + SheltonZhu/115driver）
     pikpak/                 PikPak（自己实现，参考 OpenList pikpak）
-    wopan/                  联通沃盘（壳子 + OpenListTeam/wopan-sdk-go）
+    wopan/                  联通网盘（壳子 + OpenListTeam/wopan-sdk-go）
+    guangyapan/             光鸭网盘（参考 AList GuangYaPan）
     onedrive/               OneDrive（OpenList 在线续期 + Microsoft Graph 文件接口）
+    googledrive/            Google Drive（OpenList 在线续期 + Google Drive API；播放走后端代理）
+    localstorage/           本地目录扫描（服务器已有视频目录）
   scanner/                  扫目录 → 落库
-  preview/                  ffmpeg 抽封面和生成多段 teaser
+  preview/                  ffmpeg 抽封面和生成多段预览视频
   proxy/                    /p/stream/*、/p/preview/* 代理
   auth/                     管理员 session
   api/                      REST 路由
@@ -79,7 +82,7 @@ go run ./cmd/server 后端 9192
 
 ## 添加一个盘
 
-推荐在前端管理后台 `/admin/drives` 新增网盘。保存后会立即挂载并触发扫描；视频结果可在 `/admin/videos` 按网盘查看，每页 100 条，页面会同时显示各网盘 Teaser 已生成、待生成、失败数量。
+推荐在前端管理后台 `/admin/drives` 新增网盘。保存后会立即挂载并触发扫描；视频结果可在 `/admin/videos` 按网盘查看，每页 100 条，页面会同时显示各网盘预览视频已生成、待生成、失败数量。
 
 也可以直接调用后端接口：
 
@@ -91,7 +94,6 @@ go run ./cmd/server 后端 9192
      "kind": "quark",
      "name": "我的夸克盘",
      "rootId": "0",
-     "scanRootId": "0",
      "credentials": {
        "cookie": "粘贴浏览器 F12 复制的 pan.quark.cn Cookie"
      }
@@ -105,9 +107,12 @@ go run ./cmd/server 后端 9192
 |--------|---------------------------------------------------------------|
 | quark  | `cookie`                                                      |
 | p115   | `cookie`（形如 `UID=...; CID=...; SEID=...; KID=...`）         |
-| pikpak | `username`、`password`，可选 `refresh_token`、`captcha_token`、`device_id`、`platform`、`disable_media_link` |
+| pikpak | `username`、`password`（token、验证码和设备 ID 由服务端自动处理并保存） |
 | wopan  | `access_token`、`refresh_token`，可选 `family_id`              |
-| onedrive | `refresh_token`，可选 `access_token`、`api_url_address`、`region`、`is_sharepoint`、`site_id` |
+| guangyapan | 推荐后台扫码登录自动写入 `access_token`、`refresh_token`；也可手工填写 token；可选 `root_path` |
+| onedrive | `refresh_token` |
+| googledrive | 默认只需 `refresh_token`；自建 OAuth 客户端模式还需 `use_online_api=false`、`client_id`、`client_secret` |
+| localstorage | `path`（服务器上的已有视频目录，如 `/mnt/videos`） |
 
 ### PikPak 速度说明
 
@@ -115,29 +120,49 @@ go run ./cmd/server 后端 9192
 
 当前服务器同时存在 sing-box TUN 透明代理，PikPak 默认出站会被 `tun0` 接管；但强制直连物理网卡并没有更快，慢速的主要差异来自 PikPak 取链方式。media/cache CDN 节点仍有波动，偶尔可能遇到慢节点；如果播放变慢，可重新获取直链或重新挂载 PikPak 后再测。
 
-OneDrive 按 OpenList 默认方式调用 `https://api.oplist.org/onedrive/renewapi` 在线刷新 token，不需要配置 Azure 应用的 `client_id` / `client_secret` / `redirect_uri`。OpenList 代刷得到的 refresh token 可以直接填到本项目。普通 OneDrive 的 `rootId` / `scanRootId` 可填 `root`；SharePoint 文档库需要额外设置 `is_sharepoint=true` 和 `site_id`。
+OneDrive 按 OpenList 默认应用方式调用 `https://api.oplist.org/onedrive/renewapi` 在线刷新 token，不需要配置 Azure 应用的 `client_id` / `client_secret` / `redirect_uri`。后台新建 OneDrive 时只需要填 OpenList 代刷得到的 `refresh_token`；服务端会默认挂载根目录并自动回写新 token。
+
+Google Drive 默认按 OpenList 在线 API 调用 `https://api.oplist.org/googleui/renewapi` 刷新 token。后台新建 Google Drive 时只需要填 OpenList Google Drive 获取到的 `refresh_token`。如果不想依赖 OpenList 在线 API，可以关闭“使用 OpenList 在线续期 API”，并填写同一个 Google OAuth 客户端授权得到的 `refresh_token`、`client_id`、`client_secret`，服务端会直接请求 Google OAuth token 接口续期。Google Drive 下载地址必须携带 `Authorization` 头，浏览器不能直接 302 使用，所以本站会由后端代理 `/p/stream` 播放，不加入零带宽 302 白名单。
 
 ## 文件名约定
 
-扫描器按以下顺序解析文件名：
+扫描器按以下顺序解析文件名，用于提取标题和作者：
 
-1. `[tag1,tag2] 标题 - 作者.mp4`
-2. `[tag1,tag2] 标题.mp4`
+1. `[前缀] 标题 - 作者.mp4`
+2. `[前缀] 标题.mp4`
 3. `标题 - 作者.mp4`
 4. `标题.mp4`
 
-标签分隔符支持 `, ， 、` 和空格。解析结果会和系统标签池匹配，常见番号类噪声会归并到 `AV` 等系统标签，避免把每个番号都变成独立标签。解析结果可在管理后台覆盖。
+开头的 `[前缀]` 只会从标题里剥离，不会按分隔符作为任意标签入库。视频标签来自三类规则：
+
+1. 文件名、作者和目录名命中系统标签或已有标签的标签名 / 别名。
+2. 符合条件的目录名会自动创建 `collection` 合集标签，并给同目录视频打上该标签。
+3. 常见番号类噪声会统一归并到 `AV`，避免把每个番号都变成独立标签。
+
+当前内置系统标签为：`后入`、`奶子`、`口交`、`臀`、`人妻`、`女大`、`AV`。解析结果可在管理后台覆盖；手动保存后，该视频会标记为人工标签，后续扫描不会再自动覆盖。
+
+## 视频去重
+
+项目有三层去重：
+
+1. 同一网盘同一文件按 `(drive_id, file_id)` 形成稳定视频 ID，重复扫描只更新同一行。
+2. 扫描时优先按网盘侧 `content_hash` 去重；没有 hash 时退化为 `file_name + size_bytes`。
+3. 扫描、本地上传或服务启动挂载网盘后，后台指纹 worker 会异步读取视频的少量 Range 片段，生成 `sampled_sha256`。前台列表、首页、搜索、推荐会按 `size_bytes + sampled_sha256` 只展示最早入库的 canonical 视频。
+
+`sampled_sha256` 是文件级去重：适合识别同一个视频文件被复制到 115 / PikPak / OneDrive / Google Drive 等不同网盘的情况。它不会删除任何网盘文件，也不用于识别转码、裁剪、加水印后的同源视频。
+
+封面和预览视频仍然优先生成，不等待指纹完成。夜间流水线最后会做一次重复资产清理：对 `size_bytes + sampled_sha256` 命中的非 canonical 视频，只删除本机生成的重复封面和预览视频，并把对应字段重置为 `pending`。网盘原文件和视频元数据记录不会被删除；如果 canonical 视频以后被移除，这些重复项会重新进入生成队列。
 
 ## 管理能力
 
 - `/admin/drives`：新增、编辑、删除网盘，触发扫描。
-- `/admin/videos`：按网盘筛选视频，每页 100 条分页，查看各网盘 Teaser 统计，编辑标题/作者/分类/标签，单条或全量重生 teaser。
-- `/admin/tags`：新增标签并用内置规则自动匹配已有视频。
-- 播放页视频信息会展示来源网盘类型；同时提供“不再展示”，点击后会把视频标记为全局隐藏。隐藏视频不会再出现在首页、列表、搜索、相关推荐和详情接口中。目前没有管理后台恢复入口，如需恢复可把数据库里对应视频的 `hidden` 字段改回 `0`。
+- `/admin/videos`：按网盘筛选视频，每页 100 条分页，查看各网盘预览视频统计，编辑标题/作者/分类/标签，单条或全量重生预览视频；拉黑视频页可查看被删除或被隐藏的视频，并支持移出黑名单后在下次扫盘重新入库。
+- `/admin/tags`：新增标签并用内置规则自动匹配已有视频；删除非系统标签时会从所有视频上同步移除该标签。
+- 播放页视频信息会展示来源网盘类型，并提供删除入口。被删除或被隐藏的视频会进入黑名单，不会再出现在首页、列表、搜索和详情接口中；在后台移出黑名单后，会在下次扫盘时重新发现并入库。
 
-## Teaser 生成
+## 预览视频生成
 
-scanner 扫到新视频会把 `(driveID, videoID)` 丢进 worker 队列。worker 会先用 `ffprobe` 探测时长，再用 `ffmpeg` 抽封面和生成无声 teaser：
+scanner 扫到新视频会把 `(driveID, videoID)` 丢进 worker 队列。worker 会先用 `ffprobe` 探测时长，再用 `ffmpeg` 抽封面和生成无声预览视频：
 
 ```
 ffmpeg -ss <起点> -headers "UA/Cookie/Referer" -i <直链> \
@@ -145,9 +170,9 @@ ffmpeg -ss <起点> -headers "UA/Cookie/Referer" -i <直链> \
        -movflags +faststart -y <local>.mp4
 ```
 
-当前策略是每段固定 3 秒；30 秒以下最多 3 段，30 秒及以上固定 4 段；长视频在 20% 到 80% 区间均匀取段。生成的 teaser 和封面都只保存在本地 `data/previews/`，不会回写到网盘；旧数据中的 `preview_file_id` 会被忽略。
+当前策略是每段固定 3 秒；30 秒以下最多 3 段，30 秒及以上固定 4 段；长视频在 20% 到 80% 区间均匀取段。生成的预览视频和封面都只保存在本地 `data/previews/`，不会回写到网盘；旧数据中的 `preview_file_id` 会被忽略。
 
-服务启动或网盘重新挂载时，如果 Teaser 开关已开启，后端会把历史 `pending` 任务重新入队，避免重启后长期停在“待生成”。OneDrive 直链生成 teaser 时可能触发 Microsoft 429 限流；后端会识别这类错误并让当前网盘进入冷却期，保留任务为 `pending`，避免连续请求触发更严重限流。
+服务启动或网盘重新挂载时，如果预览视频开关已开启，后端会把历史 `pending` 任务重新入队，避免重启后长期停在“待生成”。OneDrive 扫盘和直链生成预览视频 / 封面时可能触发 Microsoft Graph 429、`TooManyRequests`、`activityLimitReached` 或 throttled 文本；Google Drive 可能返回 429、`usageLimits`、`userRateLimitExceeded`、`downloadQuotaExceeded` 等限制标识。后端会识别这类错误并让当前网盘进入冷却期，保留任务为 `pending`，避免连续请求触发更严重限流。扫盘阶段会按 `Retry-After` 或默认冷却时间等待后继续当前目录。
 
 前端卡片的 `previewSrc` 统一指向 `/p/preview/<videoID>`，后端只从本地 `preview_local` 文件读取。
 

backend/cmd/server/frontend_test.go

@@ -67,3 +67,40 @@ func TestFrontendHandlerDoesNotSwallowBackendRoutes(t *testing.T) {
 		}
 	}
 }
+
+func TestResolveFrontendDirFallsBackToParentDist(t *testing.T) {
+	workspace := t.TempDir()
+	backendDir := filepath.Join(workspace, "backend")
+	distDir := filepath.Join(workspace, "dist")
+	if err := os.MkdirAll(backendDir, 0o755); err != nil {
+		t.Fatalf("mkdir backend: %v", err)
+	}
+	if err := os.MkdirAll(distDir, 0o755); err != nil {
+		t.Fatalf("mkdir dist: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(distDir, "index.html"), []byte("<html>app</html>"), 0o644); err != nil {
+		t.Fatalf("write index: %v", err)
+	}
+
+	oldWD, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := os.Chdir(oldWD); err != nil {
+			t.Fatalf("restore wd: %v", err)
+		}
+	})
+	t.Setenv("VIDEO_FRONTEND_DIR", "")
+	if err := os.Chdir(backendDir); err != nil {
+		t.Fatalf("chdir backend: %v", err)
+	}
+
+	got, ok := resolveFrontendDir()
+	if !ok {
+		t.Fatal("resolveFrontendDir ok = false, want true")
+	}
+	if got != "../dist" {
+		t.Fatalf("frontend dir = %q, want ../dist", got)
+	}
+}

backend/cmd/server/main_crawler_test.go

@@ -6,7 +6,7 @@ import (
 	"github.com/video-site/backend/internal/catalog"
 )
 
-func TestSpider91IntCredFallbacks(t *testing.T) {
+func TestCrawlerIntCredFallbacks(t *testing.T) {
 	tests := []struct {
 		name string
 		d    *catalog.Drive
@@ -23,9 +23,9 @@ func TestSpider91IntCredFallbacks(t *testing.T) {
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			got := spider91IntCred(tc.d, tc.key, tc.def)
+			got := crawlerIntCred(tc.d, tc.key, tc.def)
 			if got != tc.want {
-				t.Fatalf("spider91IntCred(%s) = %d, want %d", tc.name, got, tc.want)
+				t.Fatalf("crawlerIntCred(%s) = %d, want %d", tc.name, got, tc.want)
 			}
 		})
 	}

backend/config.example.yaml

@@ -22,7 +22,7 @@ server:
 storage:
   # SQLite 数据库文件路径
   db_path: "./data/video-site.db"
-  # 本地 teaser 和封面目录
+  # 本地预览视频和封面目录
   local_preview_dir: "./data/previews"
 
 scanner:
@@ -33,33 +33,30 @@ scanner:
   # 单次扫描每家网盘目录递归层数上限
   max_depth: 5
   # 被扫描的扩展名
-  video_extensions: [".mp4", ".mkv", ".mov", ".webm", ".avi"]
+  video_extensions: [".mp4", ".mkv", ".mov", ".webm", ".avi", ".strm"]
 
 nightly:
-  # 凌晨流水线触发整点（0-23），默认 1 即每天 01:00。流程：
-  #   Phase 1  扫所有非 spider91 / 非 localupload 网盘 → 检测新增 / 删除
-  #            → 入队封面和 teaser → 等所有队列 idle
-  #   Phase 2  spider91 爬虫（如配置）→ 入队 teaser → 等队列 idle
-  #   Phase 3  spider91 → 云盘迁移（一次性 sweep）
+  # 凌晨流水线触发整点（0-23），默认 1 即每天 01:00。
+  # 运行时会统一编排扫描、媒体资产生成和后续清理任务。
   cron_hour: 1
   # 单次流水线总耗时上限（软超时）；超过后当前 phase 跑完不启动后续 phase。
   max_duration: 6h
 
 preview:
-  # 是否启用 ffmpeg 抽帧生成 teaser
+  # 是否启用 ffmpeg 抽帧生成预览视频
   enabled: true
   # ffmpeg / ffprobe 可执行文件名或绝对路径
   ffmpeg_path: "ffmpeg"
   ffprobe_path: "ffprobe"
-  # teaser 每段时长（秒），实际生成时每段最多 3 秒
+  # 预览视频每段时长（秒），实际生成时每段最多 3 秒
   duration_seconds: 3
   # 兼容旧配置；当前 30 秒以下最多 3 段，30 秒及以上固定 4 段
   segments: 3
-  # teaser 视频宽度
+  # 预览视频宽度
   width: 480
 
 # 盘列表。上线后请通过管理后台添加，本文件可留空。
-# kind 支持 quark / p115 / pikpak / wopan / onedrive。
+# kind 支持 quark / p115 / p123 / pikpak / wopan / guangyapan / onedrive / googledrive / localstorage。
 # OneDrive 示例：
 # - id: "my-onedrive"
 #   kind: "onedrive"
@@ -67,6 +64,36 @@ preview:
 #   root_id: "root"
 #   params:
 #     refresh_token: "..."
-#     api_url_address: "https://api.oplist.org/onedrive/renewapi"
-#     region: "global"
+# Google Drive 示例：
+# - id: "my-google"
+#   kind: "googledrive"
+#   name: "我的 Google Drive"
+#   root_id: "root"
+#   params:
+#     refresh_token: "..."
+#     # 默认 use_online_api=true，会使用 OpenList 在线续期 API。
+#     # 如需使用自己创建的 Google OAuth 客户端，取消下面三行注释：
+#     # use_online_api: "false"
+#     # client_id: "..."
+#     # client_secret: "..."
+# 光鸭网盘示例：
+# - id: "my-guangyapan"
+#   kind: "guangyapan"
+#   name: "我的光鸭网盘"
+#   # 留空表示光鸭网盘根目录；也可以填写光鸭目录 fileId
+#   root_id: ""
+#   params:
+#     # 推荐在后台使用扫码登录自动写入 access_token / refresh_token。
+#     refresh_token: "..."
+#     # 可选：按路径解析扫描根目录，优先于 root_id
+#     # root_path: "影视/电影"
+# 本地存储示例：
+# - id: "local-media"
+#   kind: "localstorage"
+#   name: "本地视频目录"
+#   root_id: "/"
+#   params:
+#     # Docker 部署时这里和 .strm 里的绝对路径都必须使用容器内路径。
+#     # 例如宿主机 /mnt/videos 挂载为 /media，就填写 /media。
+#     path: "/mnt/videos"
 drives: []

backend/go.mod

@@ -7,15 +7,18 @@ toolchain go1.23.4
 require (
 	github.com/OpenListTeam/wopan-sdk-go v0.2.0
 	github.com/SheltonZhu/115driver v1.3.2
+	github.com/aliyun/aliyun-oss-go-sdk v3.0.2+incompatible
 	github.com/go-chi/chi/v5 v5.1.0
 	github.com/go-resty/resty/v2 v2.14.0
+	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
+	golang.org/x/net v0.27.0
+	golang.org/x/sys v0.30.0
 	gopkg.in/yaml.v3 v3.0.1
 	modernc.org/sqlite v1.33.1
 )
 
 require (
 	github.com/aead/ecdh v0.2.0 // indirect
-	github.com/aliyun/aliyun-oss-go-sdk v3.0.2+incompatible // indirect
 	github.com/andreburgaud/crypt2go v1.1.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
@@ -26,10 +29,7 @@ require (
 	github.com/pierrec/lz4/v4 v4.1.17 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
-	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e // indirect
 	golang.org/x/crypto v0.25.0 // indirect
-	golang.org/x/net v0.27.0 // indirect
-	golang.org/x/sys v0.30.0 // indirect
 	golang.org/x/time v0.8.0 // indirect
 	modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 // indirect
 	modernc.org/libc v1.55.3 // indirect

backend/internal/api/api.go

@@ -11,18 +11,21 @@ import (
 	"io"
 	"math/rand/v2"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/go-chi/chi/v5"
 
 	"github.com/video-site/backend/internal/auth"
 	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/drives/localstorage"
 	"github.com/video-site/backend/internal/drives/localupload"
-	"github.com/video-site/backend/internal/drives/spider91"
+	"github.com/video-site/backend/internal/mediaasset"
 	"github.com/video-site/backend/internal/proxy"
 )
 
@@ -39,7 +42,7 @@ var allowedUploadExtensions = map[string]struct{}{
 var allowedUploadTags = map[string]struct{}{
 	"奶子": {},
 	"臀":  {},
-	"口角": {},
+	"口交": {},
 	"女大": {},
 	"人妻": {},
 	"AV": {},
@@ -51,8 +54,16 @@ type Server struct {
 	LocalDir        string
 	UploadDir       string
 	OnVideoUploaded func(*catalog.Video)
+	// OnHideVideo 处理前台「不再展示」。隐藏机制已废弃，改走拉黑逻辑：
+	// 删除库中记录 + 本地封面/预览，保留网盘源文件，并写黑名单墓碑
+	// （扫盘不再入库）。未注入时回退为旧的 hidden 标记。
+	OnHideVideo func(ctx context.Context, videoID string) error
 
-	// GetTheme 返回当前生效的主题（"dark" | "pink"）。前台 /api/settings/theme 用，
+	tagCacheMu    sync.Mutex
+	tagCacheUntil time.Time
+	tagCache      []TagDTO
+
+	// GetTheme 返回当前生效的主题（"dark" | "pink" | "sky"）。前台 /api/settings/theme 用，
 	// 不需要登录。无注入时返回 "dark"。
 	GetTheme func() string
 }
@@ -82,7 +93,12 @@ type VideoDTO struct {
 	Dislikes        int      `json:"dislikes"`
 	PublishedAt     string   `json:"publishedAt"`
 	Tags            []string `json:"tags,omitempty"`
-	Category        string   `json:"category,omitempty"`
+}
+
+type TagDTO struct {
+	ID    string `json:"id"`
+	Label string `json:"label"`
+	Count int    `json:"count"`
 }
 
 type VideoDetailDTO struct {
@@ -133,20 +149,19 @@ func (s *Server) RegisterRoutes(r chi.Router, a *auth.Authenticator) {
 		r.Post("/api/shorts/next", s.handleShortsNext)
 
 		// 代理路由同样需要鉴权，防止绕过
-		r.Get("/p/stream/{driveID}/{fileID}", s.handleStream)
+		r.Get("/p/stream/{driveID}/*", s.handleStream)
 		r.Get("/p/upload/{videoID}", s.handleUploadedVideo)
-		r.Get("/p/spider91/{videoID}", s.handleSpider91Video)
 		r.Get("/p/preview/{videoID}", s.handlePreview)
 		r.Get("/p/thumb/{videoID}", s.handleThumb)
 	})
 }
 
 // handleGetTheme 返回当前生效的主题。无需登录。响应永远是
-// {"theme": "dark"} 或 {"theme": "pink"}，便于前端无脑解析。
+// {"theme": "dark" | "pink" | "sky"}，便于前端无脑解析。
 func (s *Server) handleGetTheme(w http.ResponseWriter, r *http.Request) {
 	theme := "dark"
 	if s.GetTheme != nil {
-		if v := s.GetTheme(); v == "pink" || v == "dark" {
+		if v := s.GetTheme(); v == "pink" || v == "dark" || v == "sky" {
 			theme = v
 		}
 	}
@@ -155,26 +170,117 @@ func (s *Server) handleGetTheme(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleHome(w http.ResponseWriter, r *http.Request) {
-	// 拉一批候选（按发布时间倒序，覆盖最近 200 个），然后随机洗牌取前 homePageSize 个。
-	// 如果库内不足 200 个会自动按实际数量返回，最后裁剪到 homePageSize。
-	const candidatePool = 200
-	items, _, err := s.Catalog.ListVideos(r.Context(), catalog.ListParams{
-		Sort: "latest", Page: 1, PageSize: candidatePool,
-	})
+	// 首页优先从全量已有封面的视频里随机抽取，避免只在最近一小段候选中反复出现。
+	excludeIDs := parseVideoIDQuery(r, "exclude", 120)
+	items, err := s.Catalog.RandomVideosWithReadyThumbnailsExcluding(r.Context(), excludeIDs, homePageSize)
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, err)
 		return
 	}
-	rand.Shuffle(len(items), func(i, j int) {
-		items[i], items[j] = items[j], items[i]
-	})
-	if len(items) > homePageSize {
-		items = items[:homePageSize]
+	if len(items) < homePageSize {
+		fallbackExclude := append([]string{}, excludeIDs...)
+		for _, item := range items {
+			if item != nil {
+				fallbackExclude = append(fallbackExclude, item.ID)
+			}
+		}
+		fallback, err := s.Catalog.RandomVideosExcluding(r.Context(), fallbackExclude, homePageSize-len(items))
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err)
+			return
+		}
+		items = appendUniqueVideos(items, fallback, homePageSize)
+	}
+	if len(items) < homePageSize && len(excludeIDs) > 0 {
+		// The browser keeps a recent-video exclude list so normal refreshes do not
+		// repeat too quickly. On small libraries that list can cover every visible
+		// video; when that happens, start a new random round instead of returning
+		// an empty home section.
+		roundExclude := videoIDs(items)
+		fallback, err := s.Catalog.RandomVideosWithReadyThumbnailsExcluding(r.Context(), roundExclude, homePageSize-len(items))
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err)
+			return
+		}
+		items = appendUniqueVideos(items, fallback, homePageSize)
+	}
+	if len(items) < homePageSize && len(excludeIDs) > 0 {
+		fallback, err := s.Catalog.RandomVideosExcluding(r.Context(), videoIDs(items), homePageSize-len(items))
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err)
+			return
+		}
+		items = appendUniqueVideos(items, fallback, homePageSize)
 	}
 	w.Header().Set("Cache-Control", "no-store")
 	writeJSON(w, http.StatusOK, mapVideos(items))
 }
 
+func parseVideoIDQuery(r *http.Request, key string, limit int) []string {
+	if r == nil {
+		return nil
+	}
+	values := r.URL.Query()[key]
+	if len(values) == 0 {
+		return nil
+	}
+	seen := map[string]struct{}{}
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		for _, id := range strings.Split(value, ",") {
+			id = strings.TrimSpace(id)
+			if id == "" {
+				continue
+			}
+			if _, ok := seen[id]; ok {
+				continue
+			}
+			seen[id] = struct{}{}
+			out = append(out, id)
+			if limit > 0 && len(out) >= limit {
+				return out
+			}
+		}
+	}
+	return out
+}
+
+func appendUniqueVideos(dst []*catalog.Video, candidates []*catalog.Video, limit int) []*catalog.Video {
+	if len(dst) >= limit {
+		return dst[:limit]
+	}
+	seen := make(map[string]struct{}, len(dst))
+	for _, v := range dst {
+		if v != nil {
+			seen[v.ID] = struct{}{}
+		}
+	}
+	for _, v := range candidates {
+		if v == nil {
+			continue
+		}
+		if _, ok := seen[v.ID]; ok {
+			continue
+		}
+		dst = append(dst, v)
+		seen[v.ID] = struct{}{}
+		if len(dst) >= limit {
+			return dst
+		}
+	}
+	return dst
+}
+
+func videoIDs(items []*catalog.Video) []string {
+	out := make([]string, 0, len(items))
+	for _, item := range items {
+		if item != nil && item.ID != "" {
+			out = append(out, item.ID)
+		}
+	}
+	return out
+}
+
 func (s *Server) handleList(w http.ResponseWriter, r *http.Request) {
 	q := r.URL.Query()
 	page, _ := strconv.Atoi(q.Get("page"))
@@ -182,13 +288,17 @@ func (s *Server) handleList(w http.ResponseWriter, r *http.Request) {
 	if size <= 0 {
 		size = 24
 	}
+	sort := q.Get("sort")
 	params := catalog.ListParams{
-		Keyword:  q.Get("q"),
-		Tag:      q.Get("tag"),
-		Category: q.Get("cat"),
-		Sort:     q.Get("sort"),
-		Page:     page,
-		PageSize: size,
+		Keyword:   q.Get("q"),
+		Tag:       q.Get("tag"),
+		Sort:      sort,
+		Page:      page,
+		PageSize:  size,
+		SkipTotal: strings.EqualFold(q.Get("count"), "false"),
+	}
+	if sort == "" || sort == "latest" {
+		params.PreferReadyThumbnails = true
 	}
 	items, total, err := s.Catalog.ListVideos(r.Context(), params)
 	if err != nil {
@@ -204,7 +314,7 @@ func (s *Server) handleList(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleVideoDetail(w http.ResponseWriter, r *http.Request) {
-	id := chi.URLParam(r, "id")
+	id := routeParam(r, "id")
 	v, err := s.Catalog.GetVideo(r.Context(), id)
 	if err != nil {
 		writeErr(w, http.StatusNotFound, err)
@@ -214,6 +324,15 @@ func (s *Server) handleVideoDetail(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusNotFound, sql.ErrNoRows)
 		return
 	}
+	if v.DriveID != localUploadDriveID {
+		if _, err := s.Catalog.GetDrive(r.Context(), v.DriveID); err != nil {
+			drives, listErr := s.Catalog.ListDrives(r.Context())
+			if listErr != nil || len(drives) > 0 {
+				writeErr(w, http.StatusNotFound, sql.ErrNoRows)
+				return
+			}
+		}
+	}
 	related := s.pickRelatedVideos(r.Context(), v, 6)
 	dto := mapVideo(v)
 	if d, err := s.Catalog.GetDrive(r.Context(), v.DriveID); err == nil {
@@ -225,7 +344,7 @@ func (s *Server) handleVideoDetail(w http.ResponseWriter, r *http.Request) {
 		VideoSrc:    s.videoSource(v),
 		Poster:      thumbnailURL(v),
 		Description: v.Description,
-		EmbedURL:    fmt.Sprintf(`<iframe src="/embed/%s" width="640" height="360" frameborder="0" allowfullscreen></iframe>`, v.ID),
+		EmbedURL:    fmt.Sprintf(`<iframe src="/embed/%s" width="640" height="360" frameborder="0" allowfullscreen></iframe>`, pathSegment(v.ID)),
 		AuthorProfile: AuthorProfile{
 			ID:     "author-" + v.Author,
 			Name:   v.Author,
@@ -241,7 +360,8 @@ func (s *Server) handleVideoDetail(w http.ResponseWriter, r *http.Request) {
 }
 
 // pickRelatedVideos 选 total 个推荐视频。
-// 一半（向上取整）来自同标签命中，剩下用全库随机补齐；不会重复，也不会包含当前视频。
+// 一半来自同标签命中，剩下用全库随机补齐；两段都优先取已有封面的视频，
+// 不够时再回退到未生成封面的候选。结果不会重复，也不会包含当前视频。
 func (s *Server) pickRelatedVideos(ctx context.Context, current *catalog.Video, total int) []*catalog.Video {
 	if total <= 0 || current == nil {
 		return nil
@@ -254,90 +374,158 @@ func (s *Server) pickRelatedVideos(ctx context.Context, current *catalog.Video,
 	picked := make([]*catalog.Video, 0, total)
 	seen := map[string]struct{}{current.ID: {}}
 
-	// 1) 同标签候选：对每个 tag 取一批，合并去重，洗牌后取 tagQuota 个
+	// 1) 同标签候选：先取已有封面的候选，数量不够再从全部候选里补。
 	if tagQuota > 0 && len(current.Tags) > 0 {
-		var tagPool []*catalog.Video
-		for _, tag := range current.Tags {
-			if tag == "" {
-				continue
-			}
-			items, _, err := s.Catalog.ListVideos(ctx, catalog.ListParams{
-				Tag: tag, Sort: "latest", Page: 1, PageSize: 30,
-			})
-			if err != nil {
-				continue
-			}
-			for _, v := range items {
-				if v == nil {
-					continue
-				}
-				if _, ok := seen[v.ID]; ok {
-					continue
-				}
-				seen[v.ID] = struct{}{}
-				tagPool = append(tagPool, v)
-			}
+		picked = appendRandomRelated(
+			picked,
+			s.relatedTagPool(ctx, current.Tags, seen, true),
+			tagQuota,
+			seen,
+		)
+		if len(picked) < tagQuota {
+			picked = appendRandomRelated(
+				picked,
+				s.relatedTagPool(ctx, current.Tags, seen, false),
+				tagQuota,
+				seen,
+			)
 		}
-		rand.Shuffle(len(tagPool), func(i, j int) {
-			tagPool[i], tagPool[j] = tagPool[j], tagPool[i]
-		})
-		if len(tagPool) > tagQuota {
-			tagPool = tagPool[:tagQuota]
-		}
-		picked = append(picked, tagPool...)
 	}
 
-	// 2) 随机补齐：从全库取一批（避开已选 ID），洗牌后取剩下的名额
-	remaining := total - len(picked)
-	if remaining > 0 {
-		items, _, err := s.Catalog.ListVideos(ctx, catalog.ListParams{
-			Sort: "latest", Page: 1, PageSize: 200,
-		})
-		if err == nil {
-			var randomPool []*catalog.Video
-			for _, v := range items {
-				if v == nil {
-					continue
-				}
-				if _, ok := seen[v.ID]; ok {
-					continue
-				}
-				seen[v.ID] = struct{}{}
-				randomPool = append(randomPool, v)
-			}
-			rand.Shuffle(len(randomPool), func(i, j int) {
-				randomPool[i], randomPool[j] = randomPool[j], randomPool[i]
-			})
-			if len(randomPool) > remaining {
-				randomPool = randomPool[:remaining]
-			}
-			picked = append(picked, randomPool...)
-		}
+	// 2) 随机补齐：同样优先已有封面的全库候选，不够再回退。
+	if len(picked) < total {
+		picked = appendRandomRelated(
+			picked,
+			s.relatedListPool(ctx, seen, true, 200),
+			total,
+			seen,
+		)
+	}
+	if len(picked) < total {
+		picked = appendRandomRelated(
+			picked,
+			s.relatedListPool(ctx, seen, false, 200),
+			total,
+			seen,
+		)
 	}
 
 	return picked
 }
 
+func (s *Server) relatedTagPool(ctx context.Context, tags []string, seen map[string]struct{}, readyOnly bool) []*catalog.Video {
+	var pool []*catalog.Video
+	poolSeen := make(map[string]struct{})
+	for _, tag := range tags {
+		if tag == "" {
+			continue
+		}
+		items, _, err := s.Catalog.ListVideos(ctx, catalog.ListParams{
+			Tag:                   tag,
+			Sort:                  "latest",
+			Page:                  1,
+			PageSize:              30,
+			ThumbnailReadyOnly:    readyOnly,
+			PreferReadyThumbnails: !readyOnly,
+		})
+		if err != nil {
+			continue
+		}
+		for _, v := range items {
+			if v == nil {
+				continue
+			}
+			if _, ok := seen[v.ID]; ok {
+				continue
+			}
+			if _, ok := poolSeen[v.ID]; ok {
+				continue
+			}
+			poolSeen[v.ID] = struct{}{}
+			pool = append(pool, v)
+		}
+	}
+	return pool
+}
+
+func (s *Server) relatedListPool(ctx context.Context, seen map[string]struct{}, readyOnly bool, pageSize int) []*catalog.Video {
+	items, _, err := s.Catalog.ListVideos(ctx, catalog.ListParams{
+		Sort:                  "latest",
+		Page:                  1,
+		PageSize:              pageSize,
+		ThumbnailReadyOnly:    readyOnly,
+		PreferReadyThumbnails: !readyOnly,
+	})
+	if err != nil {
+		return nil
+	}
+	pool := make([]*catalog.Video, 0, len(items))
+	for _, v := range items {
+		if v == nil {
+			continue
+		}
+		if _, ok := seen[v.ID]; ok {
+			continue
+		}
+		pool = append(pool, v)
+	}
+	return pool
+}
+
+func appendRandomRelated(picked []*catalog.Video, pool []*catalog.Video, targetLen int, seen map[string]struct{}) []*catalog.Video {
+	if len(picked) >= targetLen || len(pool) == 0 {
+		return picked
+	}
+	rand.Shuffle(len(pool), func(i, j int) {
+		pool[i], pool[j] = pool[j], pool[i]
+	})
+	for _, v := range pool {
+		if len(picked) >= targetLen {
+			break
+		}
+		if v == nil {
+			continue
+		}
+		if _, ok := seen[v.ID]; ok {
+			continue
+		}
+		seen[v.ID] = struct{}{}
+		picked = append(picked, v)
+	}
+	return picked
+}
+
 func (s *Server) handleTags(w http.ResponseWriter, r *http.Request) {
+	now := time.Now()
+	s.tagCacheMu.Lock()
+	if s.tagCache != nil && now.Before(s.tagCacheUntil) {
+		out := append([]TagDTO(nil), s.tagCache...)
+		s.tagCacheMu.Unlock()
+		w.Header().Set("Cache-Control", "private, max-age=15")
+		writeJSON(w, http.StatusOK, out)
+		return
+	}
+	s.tagCacheMu.Unlock()
+
 	stats, err := s.Catalog.ListTags(r.Context())
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, err)
 		return
 	}
-	type tag struct {
-		ID    string `json:"id"`
-		Label string `json:"label"`
-		Count int    `json:"count"`
-	}
-	out := make([]tag, 0, len(stats))
+	out := make([]TagDTO, 0, len(stats))
 	for _, stat := range stats {
-		out = append(out, tag{ID: stat.Label, Label: stat.Label, Count: stat.Count})
+		out = append(out, TagDTO{ID: stat.Label, Label: stat.Label, Count: stat.Count})
 	}
+	s.tagCacheMu.Lock()
+	s.tagCache = append([]TagDTO(nil), out...)
+	s.tagCacheUntil = now.Add(30 * time.Second)
+	s.tagCacheMu.Unlock()
+
+	w.Header().Set("Cache-Control", "private, max-age=15")
 	writeJSON(w, http.StatusOK, out)
 }
 
-// shortsNextReq 客户端把当前轮已看过的 video id 列表传上来，
-// 服务器从未在列表中的视频里随机抽 count 个返回。
+// shortsNextReq 客户端把当前轮已看过的 video id 列表传上来。
 type shortsNextReq struct {
 	SeenIDs []string `json:"seenIds"`
 	Count   int      `json:"count"`
@@ -358,8 +546,8 @@ type ShortsItemDTO struct {
 //   - 服务器从未在 seenIds 中的可见视频里随机抽至多 count 条返回
 //   - 当返回数量 < count 且小于全库可见总数时，说明本轮即将结束，
 //     返回 roundComplete=true，前端应在用户看完返回的这些后清空本地已看记录开新一轮
-//   - 当 seenIds 已经覆盖全库时，本接口直接返回新一轮的随机一批
-//     （传 seenIds=[] 即可让客户端在轮次完成后重新开始）
+//   - 当 seenIds 真实覆盖当前全部可见视频时，本接口直接返回新一轮的随机一批
+//     （不能仅看 seenIds 长度，里面可能有隐藏、删除或历史脏 ID）
 func (s *Server) handleShortsNext(w http.ResponseWriter, r *http.Request) {
 	var body shortsNextReq
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil && !errors.Is(err, io.EOF) {
@@ -380,17 +568,18 @@ func (s *Server) handleShortsNext(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// 如果客户端已看记录已经 ≥ 全库，则视为新一轮，直接忽略 seenIds
-	exclude := body.SeenIDs
-	if total > 0 && len(exclude) >= total {
-		exclude = nil
-	}
-
-	items, err := s.Catalog.RandomVideosExcluding(r.Context(), exclude, count)
+	items, err := s.Catalog.RandomVideosExcluding(r.Context(), body.SeenIDs, count)
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, err)
 		return
 	}
+	if total > 0 && len(items) == 0 && len(body.SeenIDs) > 0 {
+		items, err = s.Catalog.RandomVideosExcluding(r.Context(), nil, count)
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err)
+			return
+		}
+	}
 
 	// 注入 sourceLabel 以便前端展示来源网盘
 	driveLabels := make(map[string]string)
@@ -428,7 +617,7 @@ type updateVideoTagsReq struct {
 }
 
 func (s *Server) handleUpdateVideoTags(w http.ResponseWriter, r *http.Request) {
-	id := chi.URLParam(r, "id")
+	id := routeParam(r, "id")
 	var body updateVideoTagsReq
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		writeErr(w, http.StatusBadRequest, err)
@@ -451,7 +640,7 @@ func (s *Server) handleUpdateVideoTags(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleLike(w http.ResponseWriter, r *http.Request) {
-	id := chi.URLParam(r, "id")
+	id := routeParam(r, "id")
 	likes, err := s.Catalog.IncrementLike(r.Context(), id)
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, err)
@@ -463,7 +652,7 @@ func (s *Server) handleLike(w http.ResponseWriter, r *http.Request) {
 // handleUnlike 取消点赞：likes - 1（保底 0）。
 // 短视频模式中爱心按钮点击切换状态时使用。
 func (s *Server) handleUnlike(w http.ResponseWriter, r *http.Request) {
-	id := chi.URLParam(r, "id")
+	id := routeParam(r, "id")
 	likes, err := s.Catalog.DecrementLike(r.Context(), id)
 	if err != nil {
 		if errors.Is(err, sql.ErrNoRows) {
@@ -477,7 +666,7 @@ func (s *Server) handleUnlike(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleView(w http.ResponseWriter, r *http.Request) {
-	id := chi.URLParam(r, "id")
+	id := routeParam(r, "id")
 	views, err := s.Catalog.IncrementView(r.Context(), id)
 	if err != nil {
 		if errors.Is(err, sql.ErrNoRows) {
@@ -491,8 +680,15 @@ func (s *Server) handleView(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleHideVideo(w http.ResponseWriter, r *http.Request) {
-	id := chi.URLParam(r, "id")
-	if err := s.Catalog.HideVideo(r.Context(), id); err != nil {
+	id := routeParam(r, "id")
+	var err error
+	if s.OnHideVideo != nil {
+		// 走拉黑逻辑：删记录 + 删本地封面/预览 + 写墓碑，保留网盘源文件。
+		err = s.OnHideVideo(r.Context(), id)
+	} else {
+		err = s.Catalog.HideVideo(r.Context(), id)
+	}
+	if err != nil {
 		if errors.Is(err, sql.ErrNoRows) {
 			writeErr(w, http.StatusNotFound, err)
 			return
@@ -608,12 +804,12 @@ func (s *Server) handleUploadVideo(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleStream(w http.ResponseWriter, r *http.Request) {
-	driveID := chi.URLParam(r, "driveID")
-	fileID := chi.URLParam(r, "fileID")
+	driveID := routeParam(r, "driveID")
+	fileID := routeWildcardParam(r, "*")
 	s.Proxy.ServeStream(w, r, driveID, fileID)
 }
 func (s *Server) handleUploadedVideo(w http.ResponseWriter, r *http.Request) {
-	videoID := chi.URLParam(r, "videoID")
+	videoID := routeParam(r, "videoID")
 	v, err := s.Catalog.GetVideo(r.Context(), videoID)
 	if err != nil || v.Hidden || v.DriveID != localUploadDriveID {
 		http.NotFound(w, r)
@@ -633,46 +829,8 @@ func (s *Server) handleUploadedVideo(w http.ResponseWriter, r *http.Request) {
 	http.ServeFile(w, r, path)
 }
 
-// handleSpider91Video 服务 spider91 drive 下载到本地的视频文件。
-// 路径形如 /p/spider91/<videoID>，videoID = "spider91-<driveID>-<sourceID>"。
-// 通过 catalog 拿到 file_id（"<sourceID>.mp4"），再让 driver 解析到绝对路径并 ServeFile。
-func (s *Server) handleSpider91Video(w http.ResponseWriter, r *http.Request) {
-	videoID := chi.URLParam(r, "videoID")
-	v, err := s.Catalog.GetVideo(r.Context(), videoID)
-	if err != nil || v.Hidden {
-		http.NotFound(w, r)
-		return
-	}
-	if s.Proxy == nil || s.Proxy.Registry == nil {
-		http.NotFound(w, r)
-		return
-	}
-	d, ok := s.Proxy.Registry.Get(v.DriveID)
-	if !ok || d.Kind() != spider91.Kind {
-		http.NotFound(w, r)
-		return
-	}
-	sd, ok := d.(*spider91.Driver)
-	if !ok {
-		http.NotFound(w, r)
-		return
-	}
-	path, err := sd.VideoPath(v.FileID)
-	if err != nil {
-		http.Error(w, "invalid video id", http.StatusForbidden)
-		return
-	}
-	info, err := os.Stat(path)
-	if err != nil || info.IsDir() || info.Size() == 0 {
-		http.NotFound(w, r)
-		return
-	}
-	w.Header().Set("Cache-Control", "private, max-age=300")
-	http.ServeFile(w, r, path)
-}
-
 func (s *Server) handlePreview(w http.ResponseWriter, r *http.Request) {
-	videoID := chi.URLParam(r, "videoID")
+	videoID := routeParam(r, "videoID")
 	v, err := s.Catalog.GetVideo(r.Context(), videoID)
 	if err != nil {
 		http.NotFound(w, r)
@@ -697,15 +855,20 @@ func (s *Server) handlePreview(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleThumb(w http.ResponseWriter, r *http.Request) {
-	videoID := chi.URLParam(r, "videoID")
-	// 直接读本地 thumbs 目录中 <videoID>.jpg
-	path := filepath.Join(s.LocalDir, "thumbs", videoID+".jpg")
-	clean := filepath.Clean(path)
-	if !strings.HasPrefix(clean, filepath.Clean(s.LocalDir)) {
-		http.Error(w, "invalid path", http.StatusForbidden)
-		return
+	videoID := routeParam(r, "videoID")
+	var clean string
+	for _, path := range mediaasset.ThumbnailPathCandidates(s.LocalDir, videoID) {
+		candidate := filepath.Clean(path)
+		if !strings.HasPrefix(candidate, filepath.Clean(s.LocalDir)) {
+			http.Error(w, "invalid path", http.StatusForbidden)
+			return
+		}
+		if _, err := os.Stat(candidate); err == nil {
+			clean = candidate
+			break
+		}
 	}
-	if _, err := os.Stat(clean); err != nil {
+	if clean == "" {
 		w.Header().Set("Cache-Control", "no-store")
 		http.NotFound(w, r)
 		return
@@ -727,7 +890,7 @@ func mapVideo(v *catalog.Video) VideoDTO {
 	}
 	return VideoDTO{
 		ID:              v.ID,
-		Href:            "/video/" + v.ID,
+		Href:            "/video/" + pathSegment(v.ID),
 		Title:           v.Title,
 		Thumbnail:       thumbnailURL(v),
 		PreviewSrc:      previewURL(v),
@@ -744,12 +907,11 @@ func mapVideo(v *catalog.Video) VideoDTO {
 		Dislikes:        v.Dislikes,
 		PublishedAt:     v.PublishedAt.Format("2006-01-02"),
 		Tags:            tags,
-		Category:        v.Category,
 	}
 }
 
 func previewURL(v *catalog.Video) string {
-	base := "/p/preview/" + v.ID
+	base := "/p/preview/" + pathSegment(v.ID)
 	if v.UpdatedAt.IsZero() {
 		return base
 	}
@@ -757,31 +919,90 @@ func previewURL(v *catalog.Video) string {
 }
 
 func thumbnailURL(v *catalog.Video) string {
+	base := "/p/thumb/" + pathSegment(v.ID)
 	if v.ThumbnailURL != "" {
-		return v.ThumbnailURL
+		base = v.ThumbnailURL
+		if thumbnailURLMatchesVideoID(base, v.ID) {
+			base = "/p/thumb/" + pathSegment(v.ID)
+		}
 	}
-	return "/p/thumb/" + v.ID
+	if !strings.HasPrefix(base, "/p/thumb/") || v.UpdatedAt.IsZero() {
+		return base
+	}
+	return base + "?v=" + strconv.FormatInt(v.UpdatedAt.UnixMilli(), 10)
+}
+
+// transcodedSource 在视频有就绪的浏览器兼容性转码产物时返回产物的播放地址。
+// 产物和原始文件在同一个 drive 上，走同一条 /p/stream 代理/302 链路。
+func transcodedSource(v *catalog.Video) (string, bool) {
+	if v.TranscodeStatus == "ready" && v.TranscodedFileID != "" && v.DriveID != localUploadDriveID {
+		return fmt.Sprintf("/p/stream/%s/%s", pathSegment(v.DriveID), pathSegment(v.TranscodedFileID)), true
+	}
+	return "", false
 }
 
 func (s *Server) videoSource(v *catalog.Video) string {
 	if v.DriveID == localUploadDriveID {
-		return "/p/upload/" + v.ID
+		return "/p/upload/" + pathSegment(v.ID)
 	}
-	if s.Proxy != nil && s.Proxy.Registry != nil {
-		if d, ok := s.Proxy.Registry.Get(v.DriveID); ok && d.Kind() == spider91.Kind {
-			return "/p/spider91/" + v.ID
-		}
+	if src, ok := transcodedSource(v); ok {
+		return src
 	}
-	return fmt.Sprintf("/p/stream/%s/%s", v.DriveID, v.FileID)
+	return fmt.Sprintf("/p/stream/%s/%s", pathSegment(v.DriveID), pathSegment(v.FileID))
 }
 
 // videoSource 兼容旧调用点，没有 server context 时按之前逻辑回退到 /p/stream。
 // 内部新增的代码请使用 (*Server).videoSource。
 func videoSource(v *catalog.Video) string {
 	if v.DriveID == localUploadDriveID {
-		return "/p/upload/" + v.ID
+		return "/p/upload/" + pathSegment(v.ID)
 	}
-	return fmt.Sprintf("/p/stream/%s/%s", v.DriveID, v.FileID)
+	if src, ok := transcodedSource(v); ok {
+		return src
+	}
+	return fmt.Sprintf("/p/stream/%s/%s", pathSegment(v.DriveID), pathSegment(v.FileID))
+}
+
+func pathSegment(value string) string {
+	return url.PathEscape(value)
+}
+
+func routeParam(r *http.Request, key string) string {
+	value := chi.URLParam(r, key)
+	if value == "" {
+		return ""
+	}
+	if decoded, err := url.PathUnescape(value); err == nil {
+		return decoded
+	}
+	return value
+}
+
+func routeWildcardParam(r *http.Request, key string) string {
+	value := chi.URLParam(r, key)
+	if value == "" {
+		return ""
+	}
+	value = strings.TrimPrefix(value, "/")
+	if decoded, err := url.PathUnescape(value); err == nil {
+		return decoded
+	}
+	return value
+}
+
+func thumbnailURLMatchesVideoID(value, videoID string) bool {
+	if !strings.HasPrefix(value, "/p/thumb/") {
+		return false
+	}
+	tail := strings.TrimPrefix(value, "/p/thumb/")
+	if idx := strings.IndexByte(tail, '?'); idx >= 0 {
+		tail = tail[:idx]
+	}
+	if tail == videoID {
+		return true
+	}
+	decoded, err := url.PathUnescape(tail)
+	return err == nil && decoded == videoID
 }
 
 func driveKindLabel(kind string) string {
@@ -790,14 +1011,20 @@ func driveKindLabel(kind string) string {
 		return "夸克网盘"
 	case "p115":
 		return "115 网盘"
+	case "p123":
+		return "123网盘"
 	case "pikpak":
 		return "PikPak"
 	case "wopan":
-		return "联通沃盘"
+		return "联通网盘"
+	case "guangyapan":
+		return "光鸭网盘"
 	case "onedrive":
 		return "OneDrive"
-	case spider91.Kind:
-		return "91 爬虫"
+	case "googledrive":
+		return "Google Drive"
+	case localstorage.Kind:
+		return "本地存储"
 	default:
 		return kind
 	}

backend/internal/api/api_test.go

@@ -4,11 +4,13 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"io"
 	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -16,6 +18,8 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/drives"
+	"github.com/video-site/backend/internal/mediaasset"
 	"github.com/video-site/backend/internal/proxy"
 )
 
@@ -64,6 +68,68 @@ func TestVideoSourceKeepsDirectStreamForMp4(t *testing.T) {
 	}
 }
 
+func TestVideoURLsEscapePathSegments(t *testing.T) {
+	updated := time.UnixMilli(1778863000123)
+	v := &catalog.Video{
+		ID:        "wopan-drive-fid/with space",
+		DriveID:   "drive-1",
+		FileID:    "fid/with space",
+		Title:     "Video",
+		UpdatedAt: updated,
+	}
+
+	dto := mapVideo(v)
+	if dto.Href != "/video/wopan-drive-fid%2Fwith%20space" {
+		t.Fatalf("href = %q, want escaped video id", dto.Href)
+	}
+	if dto.PreviewSrc != "/p/preview/wopan-drive-fid%2Fwith%20space?v=1778863000123" {
+		t.Fatalf("preview = %q, want escaped video id", dto.PreviewSrc)
+	}
+	if dto.Thumbnail != "/p/thumb/wopan-drive-fid%2Fwith%20space?v=1778863000123" {
+		t.Fatalf("thumbnail = %q, want escaped video id", dto.Thumbnail)
+	}
+	if got := videoSource(v); got != "/p/stream/drive-1/fid%2Fwith%20space" {
+		t.Fatalf("video source = %q, want escaped file id", got)
+	}
+}
+
+func TestThumbnailURLRewritesStoredLocalURLForUnsafeVideoID(t *testing.T) {
+	got := thumbnailURL(&catalog.Video{
+		ID:           "wopan-drive-fid/with space",
+		ThumbnailURL: "/p/thumb/wopan-drive-fid/with space",
+		UpdatedAt:    time.UnixMilli(1778863000123),
+	})
+
+	if got != "/p/thumb/wopan-drive-fid%2Fwith%20space?v=1778863000123" {
+		t.Fatalf("thumbnail URL = %q, want escaped local URL", got)
+	}
+}
+
+func TestHandleStreamDecodesEscapedWildcardFileID(t *testing.T) {
+	local := filepath.Join(t.TempDir(), "video.mp4")
+	if err := os.WriteFile(local, []byte("ok"), 0o644); err != nil {
+		t.Fatalf("write local video: %v", err)
+	}
+	drv := &apiStreamFakeDrive{localPath: local}
+	reg := proxy.NewRegistry()
+	reg.Set("drive-1", drv)
+	srv := &Server{Proxy: proxy.New(reg)}
+
+	router := chi.NewRouter()
+	router.Get("/p/stream/{driveID}/*", srv.handleStream)
+	req := httptest.NewRequest(http.MethodGet, "/p/stream/drive-1/fid%2Fwith%20space", nil)
+	rr := httptest.NewRecorder()
+
+	router.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	if drv.fileID != "fid/with space" {
+		t.Fatalf("fileID = %q, want decoded original", drv.fileID)
+	}
+}
+
 func TestVideoSourceUsesLocalUploadRoute(t *testing.T) {
 	v := &catalog.Video{
 		ID:      "video-1",
@@ -98,6 +164,402 @@ func TestPreviewURLFallsBackWithoutUpdatedAt(t *testing.T) {
 	}
 }
 
+func TestHandleVideoDetailDecodesEscapedVideoID(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	now := time.Now()
+	if err := cat.UpsertVideo(ctx, &catalog.Video{
+		ID:          "wopan-drive-fid/with space",
+		DriveID:     "drive-1",
+		FileID:      "fid/with space",
+		Title:       "Video",
+		PublishedAt: now,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}); err != nil {
+		t.Fatalf("seed video: %v", err)
+	}
+
+	router := chi.NewRouter()
+	router.Get("/api/video/{id}", (&Server{Catalog: cat}).handleVideoDetail)
+	req := httptest.NewRequest(http.MethodGet, "/api/video/wopan-drive-fid%2Fwith%20space", nil)
+	rr := httptest.NewRecorder()
+
+	router.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got VideoDetailDTO
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if got.ID != "wopan-drive-fid/with space" {
+		t.Fatalf("id = %q, want original video id", got.ID)
+	}
+}
+
+func TestThumbnailURLVersionsLocalGeneratedThumbnails(t *testing.T) {
+	got := thumbnailURL(&catalog.Video{
+		ID:           "video-1",
+		ThumbnailURL: "/p/thumb/video-1",
+		UpdatedAt:    time.UnixMilli(1778863000123),
+	})
+	if got != "/p/thumb/video-1?v=1778863000123" {
+		t.Fatalf("thumbnail URL = %q, want versioned local URL", got)
+	}
+
+	remote := "https://thumb.example/video-1.jpg"
+	got = thumbnailURL(&catalog.Video{
+		ID:           "video-1",
+		ThumbnailURL: remote,
+		UpdatedAt:    time.UnixMilli(1778863000123),
+	})
+	if got != remote {
+		t.Fatalf("remote thumbnail URL = %q, want unchanged %q", got, remote)
+	}
+}
+
+func TestHandleHomePrioritizesVideosWithReadyThumbnails(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for i := 0; i < 20; i++ {
+		id := "pending-video-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:          id,
+			DriveID:     "drive",
+			FileID:      id,
+			Title:       id,
+			PublishedAt: now.Add(time.Duration(i) * time.Minute),
+			CreatedAt:   now.Add(time.Duration(i) * time.Minute),
+			UpdatedAt:   now.Add(time.Duration(i) * time.Minute),
+		}); err != nil {
+			t.Fatalf("seed pending video %s: %v", id, err)
+		}
+	}
+	for i := 0; i < homePageSize+2; i++ {
+		id := "ready-video-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:           id,
+			DriveID:      "drive",
+			FileID:       id,
+			Title:        id,
+			ThumbnailURL: "https://thumb.example/" + id + ".jpg",
+			PublishedAt:  now.Add(-time.Duration(i+1) * time.Hour),
+			CreatedAt:    now.Add(-time.Duration(i+1) * time.Hour),
+			UpdatedAt:    now.Add(-time.Duration(i+1) * time.Hour),
+		}); err != nil {
+			t.Fatalf("seed ready video %s: %v", id, err)
+		}
+	}
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/home", nil)
+	(&Server{Catalog: cat}).handleHome(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got []VideoDTO
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(got) != homePageSize {
+		t.Fatalf("home items = %d, want %d", len(got), homePageSize)
+	}
+	for _, item := range got {
+		if !strings.HasPrefix(item.ID, "ready-video-") {
+			t.Fatalf("home returned %q without a ready thumbnail; items=%#v", item.ID, got)
+		}
+		if !strings.HasPrefix(item.Thumbnail, "https://thumb.example/") {
+			t.Fatalf("thumbnail for %q = %q, want ready thumbnail URL", item.ID, item.Thumbnail)
+		}
+	}
+}
+
+func TestHandleHomeExcludesRecentlyShownVideos(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for i := 0; i < homePageSize+4; i++ {
+		id := "ready-video-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:           id,
+			DriveID:      "drive",
+			FileID:       id,
+			Title:        id,
+			ThumbnailURL: "https://thumb.example/" + id + ".jpg",
+			PublishedAt:  now.Add(time.Duration(i) * time.Minute),
+			CreatedAt:    now.Add(time.Duration(i) * time.Minute),
+			UpdatedAt:    now.Add(time.Duration(i) * time.Minute),
+		}); err != nil {
+			t.Fatalf("seed ready video %s: %v", id, err)
+		}
+	}
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/home?exclude=ready-video-0&exclude=ready-video-1", nil)
+	(&Server{Catalog: cat}).handleHome(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got []VideoDTO
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(got) != homePageSize {
+		t.Fatalf("home items = %d, want %d", len(got), homePageSize)
+	}
+	for _, item := range got {
+		if item.ID == "ready-video-0" || item.ID == "ready-video-1" {
+			t.Fatalf("home returned excluded video %q; items=%#v", item.ID, got)
+		}
+		if !strings.HasPrefix(item.ID, "ready-video-") {
+			t.Fatalf("home returned %q without a ready thumbnail; items=%#v", item.ID, got)
+		}
+	}
+}
+
+func TestHandleHomeStartsNewRoundWhenRecentExcludesAllVisibleVideos(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	excludes := make([]string, 0, homePageSize+2)
+	for i := 0; i < homePageSize+2; i++ {
+		id := "ready-video-" + strconv.Itoa(i)
+		excludes = append(excludes, "exclude="+id)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:           id,
+			DriveID:      "drive",
+			FileID:       id,
+			Title:        id,
+			ThumbnailURL: "https://thumb.example/" + id + ".jpg",
+			PublishedAt:  now.Add(time.Duration(i) * time.Minute),
+			CreatedAt:    now.Add(time.Duration(i) * time.Minute),
+			UpdatedAt:    now.Add(time.Duration(i) * time.Minute),
+		}); err != nil {
+			t.Fatalf("seed ready video %s: %v", id, err)
+		}
+	}
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/home?"+strings.Join(excludes, "&"), nil)
+	(&Server{Catalog: cat}).handleHome(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got []VideoDTO
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(got) != homePageSize {
+		t.Fatalf("home items = %d, want %d; body=%s", len(got), homePageSize, rr.Body.String())
+	}
+	seen := map[string]bool{}
+	for _, item := range got {
+		if seen[item.ID] {
+			t.Fatalf("home returned duplicate video %q; items=%#v", item.ID, got)
+		}
+		seen[item.ID] = true
+		if !strings.HasPrefix(item.ID, "ready-video-") {
+			t.Fatalf("home returned unexpected video %q; items=%#v", item.ID, got)
+		}
+	}
+}
+
+func TestHandleListLatestPrefersReadyThumbnails(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for i := 0; i < 20; i++ {
+		id := "pending-latest-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:          id,
+			DriveID:     "drive",
+			FileID:      id,
+			Title:       id,
+			PublishedAt: now.Add(time.Duration(i) * time.Minute),
+			CreatedAt:   now.Add(time.Duration(i) * time.Minute),
+			UpdatedAt:   now.Add(time.Duration(i) * time.Minute),
+		}); err != nil {
+			t.Fatalf("seed pending video %s: %v", id, err)
+		}
+	}
+	for i := 0; i < 12; i++ {
+		id := "ready-latest-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:           id,
+			DriveID:      "drive",
+			FileID:       id,
+			Title:        id,
+			ThumbnailURL: "https://thumb.example/" + id + ".jpg",
+			PublishedAt:  now.Add(-time.Duration(i+1) * time.Hour),
+			CreatedAt:    now.Add(-time.Duration(i+1) * time.Hour),
+			UpdatedAt:    now.Add(-time.Duration(i+1) * time.Hour),
+		}); err != nil {
+			t.Fatalf("seed ready video %s: %v", id, err)
+		}
+	}
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/list?page=1&size=12&sort=latest", nil)
+	(&Server{Catalog: cat}).handleList(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got struct {
+		Items []VideoDTO `json:"items"`
+		Total int        `json:"total"`
+	}
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if got.Total != 32 {
+		t.Fatalf("total = %d, want all matching videos included", got.Total)
+	}
+	if len(got.Items) != 12 {
+		t.Fatalf("items = %d, want 12", len(got.Items))
+	}
+	for _, item := range got.Items {
+		if !strings.HasPrefix(item.ID, "ready-latest-") {
+			t.Fatalf("latest list returned %q before ready thumbnails; items=%#v", item.ID, got.Items)
+		}
+		if !strings.HasPrefix(item.Thumbnail, "https://thumb.example/") {
+			t.Fatalf("thumbnail for %q = %q, want ready thumbnail URL", item.ID, item.Thumbnail)
+		}
+	}
+
+	rr = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/list?page=1&size=12&sort=latest&count=false", nil)
+	(&Server{Catalog: cat}).handleList(rr, req)
+	if rr.Code != http.StatusOK {
+		t.Fatalf("count=false status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	got = struct {
+		Items []VideoDTO `json:"items"`
+		Total int        `json:"total"`
+	}{}
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode count=false response: %v", err)
+	}
+	if got.Total != 0 {
+		t.Fatalf("count=false total = %d, want 0", got.Total)
+	}
+	if len(got.Items) != 12 {
+		t.Fatalf("count=false items = %d, want 12", len(got.Items))
+	}
+}
+
+func TestHandleListIgnoresCategoryQueryAndDoesNotExposeCategory(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for _, v := range []*catalog.Video{
+		{
+			ID:          "video-a",
+			DriveID:     "drive",
+			FileID:      "file-a",
+			Title:       "A",
+			PublishedAt: now,
+			CreatedAt:   now,
+			UpdatedAt:   now,
+		},
+		{
+			ID:          "video-b",
+			DriveID:     "drive",
+			FileID:      "file-b",
+			Title:       "B",
+			PublishedAt: now.Add(-time.Hour),
+			CreatedAt:   now,
+			UpdatedAt:   now,
+		},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed video %s: %v", v.ID, err)
+		}
+	}
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/list?page=1&size=24&cat=alpha", nil)
+	(&Server{Catalog: cat}).handleList(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got struct {
+		Items []map[string]any `json:"items"`
+		Total int              `json:"total"`
+	}
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if got.Total != 2 || len(got.Items) != 2 {
+		t.Fatalf("response total/items = %d/%d, want 2/2", got.Total, len(got.Items))
+	}
+	for _, item := range got.Items {
+		if _, ok := item["category"]; ok {
+			t.Fatalf("list response exposed category: %#v", item)
+		}
+	}
+}
+
 func TestHandleUploadVideoSavesFileVideoTagsAndQueuesPreview(t *testing.T) {
 	ctx := context.Background()
 	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
@@ -120,7 +582,7 @@ func TestHandleUploadVideoSavesFileVideoTagsAndQueuesPreview(t *testing.T) {
 	}
 	req := multipartUploadRequest(t, map[string]string{
 		"title": "用户上传标题",
-		"tags":  "奶子,AV,女大",
+		"tags":  "奶子,口交,AV,女大",
 	}, "clip.mp4", "video-bytes")
 	rr := httptest.NewRecorder()
 
@@ -146,7 +608,7 @@ func TestHandleUploadVideoSavesFileVideoTagsAndQueuesPreview(t *testing.T) {
 	if got.Title != "用户上传标题" {
 		t.Fatalf("title = %q, want submitted title", got.Title)
 	}
-	if !sameStringSet(got.Tags, []string{"奶子", "AV", "女大"}) {
+	if !sameStringSet(got.Tags, []string{"奶子", "口交", "AV", "女大"}) {
 		t.Fatalf("tags = %#v, want selected tags", got.Tags)
 	}
 	if got.PreviewStatus != "pending" {
@@ -317,6 +779,34 @@ func TestHandlePreviewIgnoresRemotePreviewFileIDAndServesLocalFile(t *testing.T)
 	}
 }
 
+func TestHandleThumbServesHashedPathForLongVideoID(t *testing.T) {
+	localDir := t.TempDir()
+	longID := "localstorage-" + strings.Repeat("x", 240)
+	thumbPath := mediaasset.ThumbnailPath(localDir, longID)
+	if err := os.MkdirAll(filepath.Dir(thumbPath), 0o755); err != nil {
+		t.Fatalf("mkdir thumb dir: %v", err)
+	}
+	if err := os.WriteFile(thumbPath, []byte("thumb-bytes"), 0o644); err != nil {
+		t.Fatalf("write thumb: %v", err)
+	}
+
+	server := &Server{
+		LocalDir: localDir,
+		Proxy:    proxy.New(proxy.NewRegistry()),
+	}
+	req := requestWithRouteParam(http.MethodGet, "/p/thumb/"+longID, "videoID", longID, strings.NewReader(``))
+	rr := httptest.NewRecorder()
+
+	server.handleThumb(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	if rr.Body.String() != "thumb-bytes" {
+		t.Fatalf("body = %q, want thumb bytes", rr.Body.String())
+	}
+}
+
 func TestHandleTagsReturnsUnifiedTagPool(t *testing.T) {
 	ctx := context.Background()
 	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
@@ -335,7 +825,6 @@ func TestHandleTagsReturnsUnifiedTagPool(t *testing.T) {
 		FileID:      "file-1",
 		Title:       "清纯女大后入",
 		Tags:        []string{"后入", "女大"},
-		Category:    "random-category",
 		PublishedAt: now,
 		CreatedAt:   now,
 		UpdatedAt:   now,
@@ -382,6 +871,133 @@ func TestHandleTagsReturnsUnifiedTagPool(t *testing.T) {
 	}
 }
 
+func TestHandleShortsNextReturnsRandomBatchExcludingSeen(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for _, v := range []*catalog.Video{
+		{ID: "current", DriveID: "drive", FileID: "f-current", Title: "current", Tags: []string{"common", "rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-1", DriveID: "drive", FileID: "f-common-1", Title: "common 1", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-2", DriveID: "drive", FileID: "f-common-2", Title: "common 2", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "rare-1", DriveID: "drive", FileID: "f-rare-1", Title: "rare 1", Tags: []string{"rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/shorts/next", strings.NewReader(`{"seenIds":["current"],"count":3}`))
+	rr := httptest.NewRecorder()
+	(&Server{Catalog: cat}).handleShortsNext(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got struct {
+		Items         []ShortsItemDTO `json:"items"`
+		Total         int             `json:"total"`
+		RoundComplete bool            `json:"roundComplete"`
+	}
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	ids := make([]string, 0, len(got.Items))
+	for _, item := range got.Items {
+		ids = append(ids, item.ID)
+	}
+	if got.Total != 4 {
+		t.Fatalf("total = %d, want 4", got.Total)
+	}
+	if got.RoundComplete {
+		t.Fatalf("roundComplete = true, want false with a full remaining batch")
+	}
+	if containsString(ids, "current") {
+		t.Fatalf("ids = %#v, should exclude current", ids)
+	}
+	if len(ids) != 3 {
+		t.Fatalf("ids = %#v, want 3 items", ids)
+	}
+	for _, want := range []string{"common-1", "common-2", "rare-1"} {
+		if !containsString(ids, want) {
+			t.Fatalf("ids = %#v, want remaining id %s", ids, want)
+		}
+	}
+}
+
+func TestHandleShortsNextDoesNotResetForStaleSeenIDs(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for _, v := range []*catalog.Video{
+		{ID: "seen-1", DriveID: "drive", FileID: "f-seen-1", Title: "seen 1", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "fresh-1", DriveID: "drive", FileID: "f-fresh-1", Title: "fresh 1", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "fresh-2", DriveID: "drive", FileID: "f-fresh-2", Title: "fresh 2", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "hidden-1", DriveID: "drive", FileID: "f-hidden-1", Title: "hidden 1", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+	if err := cat.HideVideo(ctx, "hidden-1"); err != nil {
+		t.Fatalf("hide hidden-1: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/shorts/next", strings.NewReader(`{"seenIds":["seen-1","hidden-1","deleted-stale"],"count":3}`))
+	rr := httptest.NewRecorder()
+	(&Server{Catalog: cat}).handleShortsNext(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got struct {
+		Items         []ShortsItemDTO `json:"items"`
+		Total         int             `json:"total"`
+		RoundComplete bool            `json:"roundComplete"`
+	}
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	ids := make([]string, 0, len(got.Items))
+	for _, item := range got.Items {
+		ids = append(ids, item.ID)
+	}
+	if got.Total != 3 {
+		t.Fatalf("total = %d, want 3", got.Total)
+	}
+	if !got.RoundComplete {
+		t.Fatalf("roundComplete = false, want true after returning all unviewed visible videos")
+	}
+	if containsString(ids, "seen-1") || containsString(ids, "hidden-1") {
+		t.Fatalf("ids = %#v, should not reset and return seen or hidden videos", ids)
+	}
+	for _, want := range []string{"fresh-1", "fresh-2"} {
+		if !containsString(ids, want) {
+			t.Fatalf("ids = %#v, want %s", ids, want)
+		}
+	}
+	if len(ids) != 2 {
+		t.Fatalf("ids = %#v, want exactly the two unviewed visible videos", ids)
+	}
+}
+
 func TestHandleUpdateVideoTagsRejectsUnknownTags(t *testing.T) {
 	ctx := context.Background()
 	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
@@ -509,6 +1125,88 @@ func TestHandleVideoDetailIncludesDriveKindLabel(t *testing.T) {
 	}
 }
 
+func TestHandleVideoDetailRecommendationsPreferReadyThumbnails(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	if err := cat.UpsertVideo(ctx, &catalog.Video{
+		ID:           "current-video",
+		DriveID:      "drive",
+		FileID:       "current-video",
+		Title:        "Current",
+		Tags:         []string{"same-tag"},
+		ThumbnailURL: "https://thumb.example/current-video.jpg",
+		PublishedAt:  now,
+		CreatedAt:    now,
+		UpdatedAt:    now,
+	}); err != nil {
+		t.Fatalf("seed current video: %v", err)
+	}
+	for i := 0; i < 20; i++ {
+		id := "pending-related-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:          id,
+			DriveID:     "drive",
+			FileID:      id,
+			Title:       id,
+			Tags:        []string{"same-tag"},
+			PublishedAt: now.Add(time.Duration(i+1) * time.Minute),
+			CreatedAt:   now.Add(time.Duration(i+1) * time.Minute),
+			UpdatedAt:   now.Add(time.Duration(i+1) * time.Minute),
+		}); err != nil {
+			t.Fatalf("seed pending related video %s: %v", id, err)
+		}
+	}
+	for i := 0; i < 8; i++ {
+		id := "ready-related-" + strconv.Itoa(i)
+		if err := cat.UpsertVideo(ctx, &catalog.Video{
+			ID:           id,
+			DriveID:      "drive",
+			FileID:       id,
+			Title:        id,
+			Tags:         []string{"same-tag"},
+			ThumbnailURL: "https://thumb.example/" + id + ".jpg",
+			PublishedAt:  now.Add(-time.Duration(i+1) * time.Hour),
+			CreatedAt:    now.Add(-time.Duration(i+1) * time.Hour),
+			UpdatedAt:    now.Add(-time.Duration(i+1) * time.Hour),
+		}); err != nil {
+			t.Fatalf("seed ready related video %s: %v", id, err)
+		}
+	}
+
+	req := requestWithVideoID(http.MethodGet, "/api/video/current-video", "current-video", strings.NewReader(``))
+	rr := httptest.NewRecorder()
+	(&Server{Catalog: cat}).handleVideoDetail(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got VideoDetailDTO
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got.RelatedVideos) != 6 {
+		t.Fatalf("related videos = %d, want 6; items=%#v", len(got.RelatedVideos), got.RelatedVideos)
+	}
+	for _, item := range got.RelatedVideos {
+		if !strings.HasPrefix(item.ID, "ready-related-") {
+			t.Fatalf("related returned %q before ready thumbnails; items=%#v", item.ID, got.RelatedVideos)
+		}
+		if !strings.HasPrefix(item.Thumbnail, "https://thumb.example/") {
+			t.Fatalf("thumbnail for %q = %q, want ready thumbnail URL", item.ID, item.Thumbnail)
+		}
+	}
+}
+
 func TestHandleHideVideoRemovesVideoFromPublicListAndDetail(t *testing.T) {
 	ctx := context.Background()
 	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
@@ -621,6 +1319,37 @@ func sameStringSet(a, b []string) bool {
 	return true
 }
 
+type apiStreamFakeDrive struct {
+	localPath string
+	fileID    string
+}
+
+func (d *apiStreamFakeDrive) Kind() string { return "fake" }
+func (d *apiStreamFakeDrive) ID() string   { return "drive-1" }
+func (d *apiStreamFakeDrive) Init(context.Context) error {
+	return nil
+}
+func (d *apiStreamFakeDrive) List(context.Context, string) ([]drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *apiStreamFakeDrive) Stat(context.Context, string) (*drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *apiStreamFakeDrive) StreamURL(_ context.Context, fileID string) (*drives.StreamLink, error) {
+	d.fileID = fileID
+	return &drives.StreamLink{
+		URL:     d.localPath,
+		Expires: time.Now().Add(time.Minute),
+	}, nil
+}
+func (d *apiStreamFakeDrive) Upload(context.Context, string, string, io.Reader, int64) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *apiStreamFakeDrive) EnsureDir(context.Context, string) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *apiStreamFakeDrive) RootID() string { return "root" }
+
 func requestWithVideoID(method, target, videoID string, body *strings.Reader) *http.Request {
 	return requestWithRouteParam(method, target, "id", videoID, body)
 }

backend/internal/catalog/drives_test.go

@@ -0,0 +1,127 @@
+package catalog
+
+import (
+	"context"
+	"testing"
+)
+
+func TestUpsertDriveUsesRootIDAsScanRootID(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	if err := cat.UpsertDrive(ctx, &Drive{
+		ID:         "drive",
+		Kind:       "p115",
+		Name:       "115",
+		RootID:     "root-folder",
+		ScanRootID: "ignored-scan-root",
+	}); err != nil {
+		t.Fatalf("upsert drive: %v", err)
+	}
+
+	got, err := cat.GetDrive(ctx, "drive")
+	if err != nil {
+		t.Fatalf("get drive: %v", err)
+	}
+	if got.RootID != "root-folder" {
+		t.Fatalf("rootId = %q, want root-folder", got.RootID)
+	}
+	if got.ScanRootID != "root-folder" {
+		t.Fatalf("scanRootId = %q, want root-folder", got.ScanRootID)
+	}
+}
+
+func TestUpsertDriveDefaultsRootIDByKind(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	cases := []struct {
+		id   string
+		kind string
+		want string
+	}{
+		{id: "p115", kind: "p115", want: "0"},
+		{id: "pikpak", kind: "pikpak", want: ""},
+		{id: "guangyapan", kind: "guangyapan", want: ""},
+		{id: "onedrive", kind: "onedrive", want: "root"},
+		{id: "googledrive", kind: "googledrive", want: "root"},
+		{id: "localstorage", kind: "localstorage", want: "/"},
+		{id: "scriptcrawler", kind: "scriptcrawler", want: "/"},
+	}
+	for _, tc := range cases {
+		if err := cat.UpsertDrive(ctx, &Drive{
+			ID:   tc.id,
+			Kind: tc.kind,
+			Name: tc.kind,
+		}); err != nil {
+			t.Fatalf("upsert %s: %v", tc.kind, err)
+		}
+		got, err := cat.GetDrive(ctx, tc.id)
+		if err != nil {
+			t.Fatalf("get %s: %v", tc.kind, err)
+		}
+		if got.RootID != tc.want {
+			t.Fatalf("%s rootId = %q, want %q", tc.kind, got.RootID, tc.want)
+		}
+		if got.ScanRootID != tc.want {
+			t.Fatalf("%s scanRootId = %q, want %q", tc.kind, got.ScanRootID, tc.want)
+		}
+	}
+}
+
+func TestUpsertDriveIgnoresRootIDForLocalStorageAndScriptCrawler(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	for _, tc := range []struct {
+		id   string
+		kind string
+	}{
+		{id: "localstorage", kind: "localstorage"},
+		{id: "scriptcrawler", kind: "scriptcrawler"},
+	} {
+		if err := cat.UpsertDrive(ctx, &Drive{
+			ID:         tc.id,
+			Kind:       tc.kind,
+			Name:       tc.kind,
+			RootID:     "manual-root",
+			ScanRootID: "manual-scan-root",
+		}); err != nil {
+			t.Fatalf("upsert %s: %v", tc.kind, err)
+		}
+		got, err := cat.GetDrive(ctx, tc.id)
+		if err != nil {
+			t.Fatalf("get %s: %v", tc.kind, err)
+		}
+		if got.RootID != "/" {
+			t.Fatalf("%s rootId = %q, want /", tc.kind, got.RootID)
+		}
+		if got.ScanRootID != "/" {
+			t.Fatalf("%s scanRootId = %q, want /", tc.kind, got.ScanRootID)
+		}
+	}
+}

backend/internal/catalog/file_ids_test.go

@@ -2,12 +2,13 @@ package catalog
 
 import (
 	"context"
+	"database/sql"
 	"sort"
 	"testing"
 	"time"
 )
 
-// TestListVideoFileIDsByDrive 校验 spider91 crawler 用到的轻量 file_id 查询：
+// TestListVideoFileIDsByDrive 校验上传 worker 用到的轻量 file_id 查询：
 // - 只返回指定 drive 的 file_id；不返回其它 drive 的
 // - 跳过 file_id 为空的视频
 // - 返回顺序无要求，但每个 file_id 只出现一次
@@ -32,20 +33,20 @@ func TestListVideoFileIDsByDrive(t *testing.T) {
 		}
 	}
 
-	insert("spider91-A-vk001", "spider-a", "vk001.mp4")
-	insert("spider91-A-vk002", "spider-a", "vk002.flv")
-	insert("spider91-A-vk003", "spider-a", "vk003.mp4")
+	insert("scriptcrawler-A-source001", "crawler-a", "source001.mp4")
+	insert("scriptcrawler-A-source002", "crawler-a", "source002.flv")
+	insert("scriptcrawler-A-source003", "crawler-a", "source003.mp4")
 	// 不同 drive 的视频不应出现
 	insert("quark-other-fid", "drive-quark", "abcdef")
 	// 空 file_id 应被过滤
-	insert("spider91-A-empty", "spider-a", "")
+	insert("scriptcrawler-A-empty", "crawler-a", "")
 
-	got, err := cat.ListVideoFileIDsByDrive(ctx, "spider-a")
+	got, err := cat.ListVideoFileIDsByDrive(ctx, "crawler-a")
 	if err != nil {
 		t.Fatalf("ListVideoFileIDsByDrive: %v", err)
 	}
 	sort.Strings(got)
-	want := []string{"vk001.mp4", "vk002.flv", "vk003.mp4"}
+	want := []string{"source001.mp4", "source002.flv", "source003.mp4"}
 	sort.Strings(want)
 	if len(got) != len(want) {
 		t.Fatalf("got %d ids, want %d: got=%v", len(got), len(want), got)
@@ -66,11 +67,11 @@ func TestListVideoFileIDsByDrive(t *testing.T) {
 	}
 }
 
-// TestListSpider91ViewkeysFindsMigratedVideos 校验：即使 spider91 视频
-// 被迁移到 PikPak（drive_id 改了），ListSpider91Viewkeys 仍能通过 video.id
-// 前缀找到这些 viewkey。这是 crawler 写 seen 文件的关键不变量，
-// 否则下一次爬取会把已爬过的 viewkey 当作"新"的再爬一遍。
-func TestListSpider91ViewkeysFindsMigratedVideos(t *testing.T) {
+// TestListCrawlerSourceIDsFindsMigratedVideos 校验：即使爬虫视频被上传迁移
+// 到目标网盘（drive_id 改了），ListCrawlerSourceIDs 仍能通过 video.id 前缀
+// 找到这些 source_id。这是 crawler 写 seen 文件的关键不变量，否则下一次
+// 爬取会把已爬过的 source_id 当作"新"的再爬一遍。
+func TestListCrawlerSourceIDsFindsMigratedVideos(t *testing.T) {
 	ctx := context.Background()
 	cat, err := Open(t.TempDir() + "/catalog.db")
 	if err != nil {
@@ -91,25 +92,25 @@ func TestListSpider91ViewkeysFindsMigratedVideos(t *testing.T) {
 		}
 	}
 
-	// 1) 仍在 spider91 drive 下的视频（未迁移）
-	insert("spider91-91Spider-vk001", "91Spider", "vk001.mp4")
-	// 2) 已迁移到 PikPak 的视频：drive_id 变了，但 id 仍是 spider91-91Spider-...
-	insert("spider91-91Spider-vk002", "PikPak", "PIKPAK-FILE-ID-2")
-	insert("spider91-91Spider-vk003", "PikPak", "PIKPAK-FILE-ID-3")
-	// 3) 别的 spider91 drive 的视频，不应混进来
-	insert("spider91-OtherDrive-vk999", "OtherDrive", "vk999.mp4")
+	// 1) 仍在本地爬虫 drive 下的视频（未上传）
+	insert("scriptcrawler-crawler-a-source001", "crawler-a", "source001.mp4")
+	// 2) 已上传到目标盘的视频：drive_id 变了，但 id 仍保留 crawler 来源前缀。
+	insert("scriptcrawler-crawler-a-source002", "target-drive", "TARGET-FILE-ID-2")
+	insert("scriptcrawler-crawler-a-source003", "target-drive", "TARGET-FILE-ID-3")
+	// 3) 别的爬虫 drive 的视频，不应混进来
+	insert("scriptcrawler-other-source999", "other-crawler", "source999.mp4")
 	// 4) 完全无关的视频
 	insert("quark-some-fid", "drive-quark", "abc")
 
-	got, err := cat.ListSpider91Viewkeys(ctx, "91Spider")
+	got, err := cat.ListCrawlerSourceIDs(ctx, "scriptcrawler", "crawler-a")
 	if err != nil {
-		t.Fatalf("ListSpider91Viewkeys: %v", err)
+		t.Fatalf("ListCrawlerSourceIDs: %v", err)
 	}
 	sort.Strings(got)
-	want := []string{"vk001", "vk002", "vk003"}
+	want := []string{"source001", "source002", "source003"}
 	sort.Strings(want)
 	if len(got) != len(want) {
-		t.Fatalf("got %d viewkeys, want %d: got=%v", len(got), len(want), got)
+		t.Fatalf("got %d source ids, want %d: got=%v", len(got), len(want), got)
 	}
 	for i := range got {
 		if got[i] != want[i] {
@@ -118,11 +119,58 @@ func TestListSpider91ViewkeysFindsMigratedVideos(t *testing.T) {
 	}
 
 	// 不存在的 drive 返回空列表
-	other, err := cat.ListSpider91Viewkeys(ctx, "no-such-drive")
+	other, err := cat.ListCrawlerSourceIDs(ctx, "scriptcrawler", "no-such-drive")
 	if err != nil {
-		t.Fatalf("ListSpider91Viewkeys empty: %v", err)
+		t.Fatalf("ListCrawlerSourceIDs empty: %v", err)
 	}
 	if len(other) != 0 {
 		t.Fatalf("non-existent drive: got %v, want empty", other)
 	}
 }
+
+func TestDeleteVideoWithTombstonePreventsReimport(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	if err := cat.UpsertVideo(ctx, &Video{
+		ID:            "scriptcrawler-crawler-a-source004",
+		DriveID:       "crawler-a",
+		FileID:        "source004.mp4",
+		FileName:      "source004.mp4",
+		ContentHash:   "ABCDEF",
+		Title:         "Deleted Source",
+		Size:          2048,
+		PreviewStatus: "ready",
+		PublishedAt:   now,
+		CreatedAt:     now,
+		UpdatedAt:     now,
+	}); err != nil {
+		t.Fatalf("upsert: %v", err)
+	}
+
+	if err := cat.DeleteVideoWithTombstone(ctx, "scriptcrawler-crawler-a-source004"); err != nil {
+		t.Fatalf("delete with tombstone: %v", err)
+	}
+	if _, err := cat.GetVideo(ctx, "scriptcrawler-crawler-a-source004"); err != sql.ErrNoRows {
+		t.Fatalf("get deleted video error = %v, want sql.ErrNoRows", err)
+	}
+	deleted, err := cat.IsDeletedVideoCandidate(ctx, "scriptcrawler-crawler-a-source004", "crawler-a", "source004.mp4", "abcdef", "source004.mp4", 2048)
+	if err != nil {
+		t.Fatalf("check deleted candidate: %v", err)
+	}
+	if !deleted {
+		t.Fatal("deleted candidate was not recognized")
+	}
+	sourceIDs, err := cat.ListCrawlerSourceIDs(ctx, "scriptcrawler", "crawler-a")
+	if err != nil {
+		t.Fatalf("ListCrawlerSourceIDs: %v", err)
+	}
+	if len(sourceIDs) != 1 || sourceIDs[0] != "source004" {
+		t.Fatalf("source ids = %#v, want [source004]", sourceIDs)
+	}
+}

backend/internal/catalog/fingerprint_test.go

@@ -0,0 +1,179 @@
+package catalog
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestListVideosDeduplicatesBySampledSHA256(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for _, v := range []*Video{
+		{
+			ID:          "drive-a-file-a",
+			DriveID:     "drive-a",
+			FileID:      "file-a",
+			FileName:    "first-name.mp4",
+			Title:       "First",
+			Size:        1234,
+			PublishedAt: now.Add(-time.Minute),
+			CreatedAt:   now.Add(-time.Minute),
+			UpdatedAt:   now.Add(-time.Minute),
+		},
+		{
+			ID:          "drive-b-file-b",
+			DriveID:     "drive-b",
+			FileID:      "file-b",
+			FileName:    "second-name.mp4",
+			Title:       "Second",
+			Size:        1234,
+			PublishedAt: now,
+			CreatedAt:   now,
+			UpdatedAt:   now,
+		},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("upsert %s: %v", v.ID, err)
+		}
+	}
+
+	items, total, err := cat.ListVideos(ctx, ListParams{Page: 1, PageSize: 10})
+	if err != nil {
+		t.Fatalf("list before fingerprint: %v", err)
+	}
+	if total != 2 || len(items) != 2 {
+		t.Fatalf("before fingerprint total=%d len=%d, want 2", total, len(items))
+	}
+
+	const sampled = "abc123"
+	if err := cat.UpdateVideoFingerprint(ctx, "drive-a-file-a", sampled, "ready", ""); err != nil {
+		t.Fatalf("update a fingerprint: %v", err)
+	}
+	if err := cat.UpdateVideoFingerprint(ctx, "drive-b-file-b", sampled, "ready", ""); err != nil {
+		t.Fatalf("update b fingerprint: %v", err)
+	}
+
+	items, total, err = cat.ListVideos(ctx, ListParams{Page: 1, PageSize: 10})
+	if err != nil {
+		t.Fatalf("list after fingerprint: %v", err)
+	}
+	if total != 1 || len(items) != 1 {
+		t.Fatalf("after fingerprint total=%d len=%d, want 1", total, len(items))
+	}
+	if items[0].ID != "drive-a-file-a" {
+		t.Fatalf("canonical id = %q, want earliest created video", items[0].ID)
+	}
+}
+
+func TestDuplicateAssetCleanupCandidates(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	base := time.Date(2026, 5, 29, 12, 0, 0, 0, time.UTC)
+	videos := []*Video{
+		{
+			ID:            "drive-a-canonical",
+			DriveID:       "drive-a",
+			FileID:        "file-a",
+			FileName:      "canonical.mp4",
+			Title:         "Canonical",
+			Size:          1234,
+			ThumbnailURL:  "/p/thumb/drive-a-canonical",
+			PreviewLocal:  "/tmp/previews/canonical.mp4",
+			PreviewStatus: "ready",
+			PublishedAt:   base,
+			CreatedAt:     base,
+			UpdatedAt:     base,
+		},
+		{
+			ID:            "drive-b-duplicate",
+			DriveID:       "drive-b",
+			FileID:        "file-b",
+			FileName:      "duplicate.mp4",
+			Title:         "Duplicate",
+			Size:          1234,
+			ThumbnailURL:  "/p/thumb/drive-b-duplicate",
+			PreviewLocal:  "/tmp/previews/duplicate.mp4",
+			PreviewStatus: "ready",
+			PublishedAt:   base.Add(time.Second),
+			CreatedAt:     base.Add(time.Second),
+			UpdatedAt:     base.Add(time.Second),
+		},
+		{
+			ID:            "drive-c-remote-thumb",
+			DriveID:       "drive-c",
+			FileID:        "file-c",
+			FileName:      "remote-thumb.mp4",
+			Title:         "Remote Thumbnail",
+			Size:          1234,
+			ThumbnailURL:  "https://thumb.example/file-c.jpg",
+			PreviewStatus: "ready",
+			PublishedAt:   base.Add(2 * time.Second),
+			CreatedAt:     base.Add(2 * time.Second),
+			UpdatedAt:     base.Add(2 * time.Second),
+		},
+	}
+	for _, v := range videos {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+	const sampled = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	for _, v := range videos {
+		if err := cat.UpdateVideoFingerprint(ctx, v.ID, sampled, "ready", ""); err != nil {
+			t.Fatalf("fingerprint %s: %v", v.ID, err)
+		}
+	}
+
+	items, err := cat.ListDuplicateAssetCleanupCandidates(ctx, 0)
+	if err != nil {
+		t.Fatalf("list cleanup candidates: %v", err)
+	}
+	if len(items) != 1 {
+		t.Fatalf("candidates = %#v, want only local duplicate", items)
+	}
+	item := items[0]
+	if item.VideoID != "drive-b-duplicate" || item.CanonicalID != "drive-a-canonical" {
+		t.Fatalf("candidate = %#v, want duplicate with canonical", item)
+	}
+
+	if err := cat.ClearGeneratedAssets(ctx, item.VideoID, true, true); err != nil {
+		t.Fatalf("clear generated assets: %v", err)
+	}
+	got, err := cat.GetVideo(ctx, item.VideoID)
+	if err != nil {
+		t.Fatalf("get duplicate: %v", err)
+	}
+	if got.PreviewLocal != "" || got.PreviewStatus != "pending" {
+		t.Fatalf("preview after cleanup local=%q status=%q, want empty pending", got.PreviewLocal, got.PreviewStatus)
+	}
+	if got.ThumbnailURL != "" {
+		t.Fatalf("thumbnail after cleanup = %q, want empty", got.ThumbnailURL)
+	}
+	var thumbStatus string
+	if err := cat.db.QueryRowContext(ctx, `SELECT thumbnail_status FROM videos WHERE id = ?`, item.VideoID).Scan(&thumbStatus); err != nil {
+		t.Fatalf("query thumbnail status: %v", err)
+	}
+	if thumbStatus != "pending" {
+		t.Fatalf("thumbnail_status = %q, want pending", thumbStatus)
+	}
+}

backend/internal/catalog/list_search_test.go

@@ -0,0 +1,50 @@
+package catalog
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestListVideosKeywordMatchesFileName(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	if err := cat.UpsertVideo(ctx, &Video{
+		ID:          "p115-115-sone-089-4k",
+		DriveID:     "drive",
+		FileID:      "file-sone-089-4k",
+		FileName:    "www.98T.la@sone-089-4k.mp4",
+		Title:       "www.98T.la@sone-089",
+		Author:      "4k",
+		PublishedAt: now,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}); err != nil {
+		t.Fatalf("seed video: %v", err)
+	}
+
+	items, total, err := cat.ListVideos(ctx, ListParams{
+		Keyword:  "www.98T.la@sone-089-4k.mp4",
+		Page:     1,
+		PageSize: 10,
+	})
+	if err != nil {
+		t.Fatalf("list videos: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("total = %d, want 1", total)
+	}
+	if len(items) != 1 || items[0].ID != "p115-115-sone-089-4k" {
+		t.Fatalf("items = %#v, want seeded video", items)
+	}
+}

backend/internal/catalog/list_sort_test.go

@@ -0,0 +1,97 @@
+package catalog
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestIncrementViewStoresLastViewedAt(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	if err := cat.UpsertVideo(ctx, &Video{
+		ID:          "video-1",
+		DriveID:     "drive",
+		FileID:      "file-1",
+		Title:       "Video 1",
+		PublishedAt: now,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}); err != nil {
+		t.Fatalf("seed video: %v", err)
+	}
+
+	if _, err := cat.IncrementView(ctx, "video-1"); err != nil {
+		t.Fatalf("increment view: %v", err)
+	}
+	got, err := cat.GetVideo(ctx, "video-1")
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.Views != 1 {
+		t.Fatalf("views = %d, want 1", got.Views)
+	}
+	if got.LastViewedAt.IsZero() {
+		t.Fatal("last viewed time was not stored")
+	}
+}
+
+func TestListVideosRecentSortUsesLastViewedAt(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for _, v := range []*Video{
+		{ID: "old-view", DriveID: "drive", FileID: "old-view", Title: "Old View", PublishedAt: now.Add(3 * time.Hour), CreatedAt: now, UpdatedAt: now},
+		{ID: "recent-view", DriveID: "drive", FileID: "recent-view", Title: "Recent View", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "unviewed", DriveID: "drive", FileID: "unviewed", Title: "Unviewed", PublishedAt: now.Add(4 * time.Hour), CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+	if _, err := cat.db.ExecContext(ctx,
+		`UPDATE videos SET last_viewed_at = CASE id
+			WHEN 'old-view' THEN ?
+			WHEN 'recent-view' THEN ?
+			ELSE 0
+		END`,
+		now.Add(-time.Hour).UnixMilli(),
+		now.Add(time.Hour).UnixMilli(),
+	); err != nil {
+		t.Fatalf("seed last_viewed_at: %v", err)
+	}
+
+	items, _, err := cat.ListVideos(ctx, ListParams{Sort: "recent", Page: 1, PageSize: 3})
+	if err != nil {
+		t.Fatalf("list recent videos: %v", err)
+	}
+	if len(items) != 3 {
+		t.Fatalf("items = %d, want 3", len(items))
+	}
+	got := []string{items[0].ID, items[1].ID, items[2].ID}
+	want := []string{"recent-view", "old-view", "unviewed"}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("recent order = %#v, want %#v", got, want)
+		}
+	}
+}

backend/internal/catalog/orphan_drive_test.go

@@ -0,0 +1,64 @@
+package catalog
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestListVideosHidesMissingDriveVideosWhenDrivesExist(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	if err := cat.UpsertDrive(ctx, &Drive{
+		ID:            "active-drive",
+		Kind:          "pikpak",
+		Name:          "Active",
+		RootID:        "root",
+		TeaserEnabled: true,
+	}); err != nil {
+		t.Fatalf("seed drive: %v", err)
+	}
+
+	now := time.Now()
+	for _, v := range []*Video{
+		{
+			ID:          "visible-video",
+			DriveID:     "active-drive",
+			FileID:      "visible-file",
+			Title:       "Visible",
+			PublishedAt: now,
+			CreatedAt:   now,
+			UpdatedAt:   now,
+		},
+		{
+			ID:          "orphan-video",
+			DriveID:     "deleted-drive",
+			FileID:      "orphan-file",
+			Title:       "Orphan",
+			PublishedAt: now.Add(time.Second),
+			CreatedAt:   now.Add(time.Second),
+			UpdatedAt:   now.Add(time.Second),
+		},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed video %s: %v", v.ID, err)
+		}
+	}
+
+	items, total, err := cat.ListVideos(ctx, ListParams{Page: 1, PageSize: 10, Sort: "latest"})
+	if err != nil {
+		t.Fatalf("list videos: %v", err)
+	}
+	if total != 1 || len(items) != 1 || items[0].ID != "visible-video" {
+		t.Fatalf("items total=%d items=%v, want only visible-video", total, items)
+	}
+}

backend/internal/catalog/schema.sql

@@ -5,6 +5,9 @@ CREATE TABLE IF NOT EXISTS videos (
     file_id          TEXT NOT NULL,
     file_name        TEXT DEFAULT '',           -- 网盘侧原始文件名，用于同名同大小去重
     content_hash     TEXT DEFAULT '',
+    sampled_sha256   TEXT DEFAULT '',           -- 跨网盘统一采样指纹（size + sampled bytes）
+    fingerprint_status TEXT DEFAULT 'pending',  -- pending / ready / failed
+    fingerprint_error  TEXT DEFAULT '',
     parent_id        TEXT,
     title            TEXT NOT NULL,
     author           TEXT,
@@ -14,16 +17,21 @@ CREATE TABLE IF NOT EXISTS videos (
     ext              TEXT,
     quality          TEXT,                      -- HD / SD
     thumbnail_url    TEXT,
-    thumbnail_status TEXT DEFAULT 'pending',    -- pending / ready / failed
-    preview_file_id  TEXT,                      -- deprecated: 旧版回写网盘后的 teaser file id
-    preview_local    TEXT,                      -- 本地 teaser 路径（兜底）
-    preview_status   TEXT DEFAULT 'pending',    -- pending / ready / failed
+    thumbnail_status TEXT DEFAULT 'pending',    -- pending / ready / failed / skipped
+    thumbnail_failures INTEGER DEFAULT 0,        -- consecutive transient thumbnail generation failures
+    preview_file_id  TEXT,                      -- deprecated: 旧版回写网盘后的预览视频 file id
+    preview_local    TEXT,                      -- 本地预览视频路径（兜底）
+    preview_status   TEXT DEFAULT 'pending',    -- pending / ready / failed / disabled
+    transcode_status TEXT DEFAULT '',           -- '' / pending / ready / skipped / failed（浏览器兼容性转码）
+    transcode_error  TEXT DEFAULT '',
+    transcoded_file_id TEXT DEFAULT '',         -- 转码产物在同一 drive 上的 fileID，播放源优先用它
+    transcoded_size  INTEGER DEFAULT 0,
     views            INTEGER DEFAULT 0,
+    last_viewed_at   INTEGER DEFAULT 0,
     favorites        INTEGER DEFAULT 0,
     comments         INTEGER DEFAULT 0,
     likes            INTEGER DEFAULT 0,
     dislikes         INTEGER DEFAULT 0,
-    category         TEXT,
     hidden           INTEGER DEFAULT 0,          -- 1 = hidden from public display
     tags_manual      INTEGER DEFAULT 0,          -- 1 = user explicitly curated tags
     badges           TEXT,                      -- JSON array
@@ -58,17 +66,63 @@ CREATE TABLE IF NOT EXISTS video_tags (
 CREATE INDEX IF NOT EXISTS idx_video_tags_tag ON video_tags(tag_id);
 CREATE INDEX IF NOT EXISTS idx_video_tags_video ON video_tags(video_id);
 
+-- 用户手动删除过的非系统标签。自动扫描/迁移不再重新创建同名标签；
+-- 管理员手动新建同名标签时会移除这里的记录。
+CREATE TABLE IF NOT EXISTS deleted_tags (
+    label      TEXT PRIMARY KEY COLLATE NOCASE,
+    source     TEXT NOT NULL DEFAULT '',
+    deleted_at INTEGER NOT NULL
+);
+
+-- 管理员显式删除过的视频。用于防止后续扫描 / 爬虫把同一个源文件
+-- 再次入库；不代表原始云盘文件已被删除。
+CREATE TABLE IF NOT EXISTS deleted_videos (
+    id           TEXT PRIMARY KEY,
+    drive_id     TEXT NOT NULL DEFAULT '',
+    file_id      TEXT NOT NULL DEFAULT '',
+    content_hash TEXT NOT NULL DEFAULT '',
+    file_name    TEXT NOT NULL DEFAULT '',
+    size_bytes   INTEGER NOT NULL DEFAULT 0,
+    reason       TEXT NOT NULL DEFAULT '',
+    deleted_at   INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_deleted_videos_drive_file
+    ON deleted_videos(drive_id, file_id);
+CREATE INDEX IF NOT EXISTS idx_deleted_videos_drive_hash
+    ON deleted_videos(drive_id, content_hash);
+CREATE INDEX IF NOT EXISTS idx_deleted_videos_drive_signature
+    ON deleted_videos(drive_id, file_name, size_bytes);
+
+-- 爬虫来源记录。用于把已确认重复的 source_id 写回 seen 列表，
+-- 避免后续爬虫反复下载同一个候选视频。
+CREATE TABLE IF NOT EXISTS crawler_seen_sources (
+    kind               TEXT NOT NULL,
+    drive_id           TEXT NOT NULL,
+    source_id          TEXT NOT NULL,
+    status             TEXT NOT NULL DEFAULT 'imported', -- imported / duplicate
+    canonical_video_id TEXT NOT NULL DEFAULT '',
+    sampled_sha256     TEXT NOT NULL DEFAULT '',
+    size_bytes         INTEGER NOT NULL DEFAULT 0,
+    first_seen_at      INTEGER NOT NULL,
+    last_seen_at       INTEGER NOT NULL,
+    PRIMARY KEY (kind, drive_id, source_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_crawler_seen_sources_drive
+    ON crawler_seen_sources(kind, drive_id, status);
+
 -- 网盘账户
 CREATE TABLE IF NOT EXISTS drives (
     id            TEXT PRIMARY KEY,
-    kind          TEXT NOT NULL,                -- quark / p115 / pikpak / wopan / onedrive / spider91
+    kind          TEXT NOT NULL,                -- quark / p115 / p123 / pikpak / wopan / guangyapan / onedrive / googledrive / localstorage / scriptcrawler
     name          TEXT NOT NULL,
     root_id       TEXT NOT NULL DEFAULT '0',
-    scan_root_id  TEXT,                          -- 扫描起点（默认 root_id）
+    scan_root_id  TEXT,                          -- deprecated: 扫描起点固定等于 root_id
     credentials   TEXT,                          -- JSON: cookie / refresh_token 等
     status        TEXT DEFAULT 'disconnected',   -- disconnected / ok / error
     last_error    TEXT,
-    -- 是否给该盘生成 teaser/封面：1 开 / 0 关。
+    -- 是否给该盘生成预览视频：1 开 / 0 关。封面生成不受影响。
     -- 替代了早期的全局 preview.enabled 设置（保留旧 setting 行不再读）。
     teaser_enabled INTEGER NOT NULL DEFAULT 1,
     -- 扫描时要跳过的目录 ID 集合（JSON array of string）。命中其中任意一个的目录及其

backend/internal/catalog/shorts_test.go

@@ -109,3 +109,59 @@ func TestRandomVideosExcluding(t *testing.T) {
 		t.Fatalf("limit 0 should return nil, got %v", got4)
 	}
 }
+
+func TestRandomVideosWithReadyThumbnailsExcluding(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	for i := 0; i < 4; i++ {
+		id := "ready-" + string(rune('a'+i))
+		if err := cat.UpsertVideo(ctx, &Video{
+			ID:           id,
+			DriveID:      "drive",
+			FileID:       "f-" + id,
+			Title:        id,
+			ThumbnailURL: "/p/thumb/" + id,
+			PublishedAt:  now,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		}); err != nil {
+			t.Fatalf("seed %s: %v", id, err)
+		}
+	}
+	for i := 0; i < 4; i++ {
+		id := "pending-" + string(rune('a'+i))
+		if err := cat.UpsertVideo(ctx, &Video{
+			ID:          id,
+			DriveID:     "drive",
+			FileID:      "f-" + id,
+			Title:       id,
+			PublishedAt: now,
+			CreatedAt:   now,
+			UpdatedAt:   now,
+		}); err != nil {
+			t.Fatalf("seed %s: %v", id, err)
+		}
+	}
+
+	got, err := cat.RandomVideosWithReadyThumbnailsExcluding(ctx, []string{"ready-a"}, 10)
+	if err != nil {
+		t.Fatalf("random ready excluding: %v", err)
+	}
+	if len(got) != 3 {
+		t.Fatalf("ready random count = %d, want 3", len(got))
+	}
+	for _, v := range got {
+		if v.ID == "ready-a" {
+			t.Fatal("excluded ready video was returned")
+		}
+		if v.ThumbnailURL == "" {
+			t.Fatalf("pending video %q was returned", v.ID)
+		}
+	}
+}

backend/internal/catalog/video_management_test.go

@@ -0,0 +1,166 @@
+package catalog
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// TestListHiddenVideosForMigration 验证：隐藏的视频不进可见列表，
+// 但能被 ListHiddenVideos 拿到（供一次性迁移为墓碑）。
+func TestListHiddenVideosForMigration(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	for _, id := range []string{"v1", "v2", "v3"} {
+		if err := cat.UpsertVideo(ctx, &Video{
+			ID: id, DriveID: "drive", FileID: "f-" + id, Title: id,
+			PublishedAt: now, CreatedAt: now, UpdatedAt: now,
+		}); err != nil {
+			t.Fatalf("seed %s: %v", id, err)
+		}
+	}
+	if err := cat.HideVideo(ctx, "v2"); err != nil {
+		t.Fatalf("hide v2: %v", err)
+	}
+
+	visible, total, err := cat.ListVideos(ctx, ListParams{Page: 1, PageSize: 50})
+	if err != nil {
+		t.Fatalf("list visible: %v", err)
+	}
+	if total != 2 || len(visible) != 2 {
+		t.Fatalf("visible total/len = %d/%d, want 2/2", total, len(visible))
+	}
+	for _, v := range visible {
+		if v.ID == "v2" {
+			t.Fatalf("hidden v2 leaked into visible list")
+		}
+	}
+
+	hidden, err := cat.ListHiddenVideos(ctx)
+	if err != nil {
+		t.Fatalf("list hidden: %v", err)
+	}
+	if len(hidden) != 1 || hidden[0].ID != "v2" {
+		t.Fatalf("ListHiddenVideos = %v, want only v2", hidden)
+	}
+
+	current, blacklisted, err := cat.VideoManagementCounts(ctx)
+	if err != nil {
+		t.Fatalf("counts: %v", err)
+	}
+	if current != 2 || blacklisted != 0 {
+		t.Fatalf("counts = current %d blacklisted %d, want 2/0", current, blacklisted)
+	}
+}
+
+// TestBlacklistListAndRemove 验证墓碑表的列出、关键字过滤和移除。
+func TestBlacklistListAndRemove(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	seed := []struct{ id, drive, file string }{
+		{"d1", "drive", "movie-alpha.avi"},
+		{"d2", "drive", "movie-beta.mp4"},
+		{"d3", "archive", "clip-gamma.wmv"},
+	}
+	for _, s := range seed {
+		if err := cat.UpsertVideo(ctx, &Video{
+			ID: s.id, DriveID: s.drive, FileID: "f-" + s.id, FileName: s.file,
+			Title: s.id, PublishedAt: now, CreatedAt: now, UpdatedAt: now,
+		}); err != nil {
+			t.Fatalf("seed %s: %v", s.id, err)
+		}
+		var err error
+		if s.id == "d2" {
+			err = cat.DeleteVideoWithTombstoneReason(ctx, s.id, DeletedVideoReasonDuplicate)
+		} else {
+			err = cat.DeleteVideoWithTombstone(ctx, s.id)
+		}
+		if err != nil {
+			t.Fatalf("tombstone %s: %v", s.id, err)
+		}
+	}
+
+	items, total, err := cat.ListDeletedVideos(ctx, ListParams{Page: 1, PageSize: 50})
+	if err != nil {
+		t.Fatalf("list deleted: %v", err)
+	}
+	if total != 3 || len(items) != 3 {
+		t.Fatalf("deleted total/len = %d/%d, want 3/3", total, len(items))
+	}
+	reasons := map[string]string{}
+	for _, item := range items {
+		reasons[item.ID] = item.Reason
+	}
+	if reasons["d1"] != "" || reasons["d3"] != "" {
+		t.Fatalf("manual tombstone reasons = %#v, want empty", reasons)
+	}
+	if reasons["d2"] != DeletedVideoReasonDuplicate {
+		t.Fatalf("duplicate tombstone reason = %q, want %q", reasons["d2"], DeletedVideoReasonDuplicate)
+	}
+
+	// 关键字过滤
+	filtered, ftotal, err := cat.ListDeletedVideos(ctx, ListParams{Keyword: "movie", Page: 1, PageSize: 50})
+	if err != nil {
+		t.Fatalf("list deleted filtered: %v", err)
+	}
+	if ftotal != 2 || len(filtered) != 2 {
+		t.Fatalf("filtered total/len = %d/%d, want 2/2", ftotal, len(filtered))
+	}
+
+	// 网盘过滤
+	driveFiltered, driveTotal, err := cat.ListDeletedVideos(ctx, ListParams{DriveID: "archive", Page: 1, PageSize: 50})
+	if err != nil {
+		t.Fatalf("list deleted drive filtered: %v", err)
+	}
+	if driveTotal != 1 || len(driveFiltered) != 1 || driveFiltered[0].ID != "d3" {
+		t.Fatalf("drive filtered = total %d items %#v, want only d3", driveTotal, driveFiltered)
+	}
+
+	combined, combinedTotal, err := cat.ListDeletedVideos(ctx, ListParams{Keyword: "movie", DriveID: "archive", Page: 1, PageSize: 50})
+	if err != nil {
+		t.Fatalf("list deleted combined filtered: %v", err)
+	}
+	if combinedTotal != 0 || len(combined) != 0 {
+		t.Fatalf("combined filtered total/len = %d/%d, want 0/0", combinedTotal, len(combined))
+	}
+
+	// 移出黑名单
+	if err := cat.RemoveDeletedVideo(ctx, "d1"); err != nil {
+		t.Fatalf("remove d1: %v", err)
+	}
+	if deleted, err := cat.IsVideoDeleted(ctx, "d1"); err != nil || deleted {
+		t.Fatalf("d1 should no longer be blacklisted (deleted=%v err=%v)", deleted, err)
+	}
+	_, total, err = cat.ListDeletedVideos(ctx, ListParams{Page: 1, PageSize: 50})
+	if err != nil {
+		t.Fatalf("list deleted after remove: %v", err)
+	}
+	if total != 2 {
+		t.Fatalf("deleted total after remove = %d, want 2", total)
+	}
+
+	if err := cat.RemoveDeletedVideo(ctx, "does-not-exist"); err == nil {
+		t.Fatalf("remove missing id should return error")
+	}
+
+	// counts: 删完一个还剩 2 个黑名单；可见视频已全部被墓碑删除
+	current, blacklisted, err := cat.VideoManagementCounts(ctx)
+	if err != nil {
+		t.Fatalf("counts: %v", err)
+	}
+	if current != 0 || blacklisted != 2 {
+		t.Fatalf("counts = current %d blacklisted %d, want 0/2", current, blacklisted)
+	}
+}

backend/internal/config/config.go

@@ -16,6 +16,11 @@ const (
 	DefaultAdminPassword = "admin123"
 )
 
+var (
+	legacyDefaultVideoExtensions = []string{".mp4", ".mkv", ".mov", ".webm", ".avi"}
+	defaultVideoExtensions       = []string{".mp4", ".mkv", ".mov", ".webm", ".avi", ".strm"}
+)
+
 type Config struct {
 	Server  Server  `yaml:"server"`
 	Storage Storage `yaml:"storage"`
@@ -202,7 +207,7 @@ type Nightly struct {
 // 这里保留 yaml 中的静态定义，用于启动时预置盘。生产建议只在 DB 里维护。
 type Drive struct {
 	ID     string            `yaml:"id"`
-	Kind   string            `yaml:"kind"` // quark / p115 / pikpak / wopan / onedrive
+	Kind   string            `yaml:"kind"` // quark / p115 / p123 / pikpak / wopan / guangyapan / onedrive / googledrive / localstorage
 	Name   string            `yaml:"name"`
 	RootID string            `yaml:"root_id"`
 	Params map[string]string `yaml:"params,omitempty"`
@@ -247,7 +252,9 @@ func (c *Config) applyDefaults() {
 		c.Scanner.MaxDepth = 5
 	}
 	if len(c.Scanner.VideoExtensions) == 0 {
-		c.Scanner.VideoExtensions = []string{".mp4", ".mkv", ".mov", ".webm", ".avi"}
+		c.Scanner.VideoExtensions = append([]string{}, defaultVideoExtensions...)
+	} else if isLegacyDefaultVideoExtensions(c.Scanner.VideoExtensions) {
+		c.Scanner.VideoExtensions = append(c.Scanner.VideoExtensions, ".strm")
 	}
 	if c.Preview.FFmpegPath == "" {
 		c.Preview.FFmpegPath = "ffmpeg"
@@ -276,3 +283,19 @@ func (c *Config) applyDefaults() {
 		c.Nightly.CronHour = 1
 	}
 }
+
+func isLegacyDefaultVideoExtensions(exts []string) bool {
+	if len(exts) != len(legacyDefaultVideoExtensions) {
+		return false
+	}
+	seen := make(map[string]struct{}, len(exts))
+	for _, ext := range exts {
+		seen[strings.ToLower(strings.TrimSpace(ext))] = struct{}{}
+	}
+	for _, ext := range legacyDefaultVideoExtensions {
+		if _, ok := seen[ext]; !ok {
+			return false
+		}
+	}
+	return true
+}

backend/internal/config/config_test.go

@@ -3,6 +3,7 @@ package config
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -50,3 +51,64 @@ storage:
 		t.Fatalf("db path = %q, want preserved value", cfg.Storage.DBPath)
 	}
 }
+
+func TestLoadDefaultScannerVideoExtensionsIncludeSTRM(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	if err := os.WriteFile(path, []byte(`{}`), 0o644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	if !hasVideoExtension(cfg.Scanner.VideoExtensions, ".strm") {
+		t.Fatalf("video extensions = %#v, want .strm", cfg.Scanner.VideoExtensions)
+	}
+}
+
+func TestLoadLegacyDefaultScannerVideoExtensionsIncludeSTRM(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+scanner:
+  video_extensions: [".mp4", ".mkv", ".mov", ".webm", ".avi"]
+`), 0o644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	if !hasVideoExtension(cfg.Scanner.VideoExtensions, ".strm") {
+		t.Fatalf("video extensions = %#v, want .strm appended for legacy default list", cfg.Scanner.VideoExtensions)
+	}
+}
+
+func TestLoadCustomScannerVideoExtensionsArePreserved(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+scanner:
+  video_extensions: [".mp4"]
+`), 0o644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	if len(cfg.Scanner.VideoExtensions) != 1 || cfg.Scanner.VideoExtensions[0] != ".mp4" {
+		t.Fatalf("video extensions = %#v, want custom list preserved", cfg.Scanner.VideoExtensions)
+	}
+}
+
+func hasVideoExtension(exts []string, want string) bool {
+	want = strings.ToLower(strings.TrimSpace(want))
+	for _, ext := range exts {
+		if strings.ToLower(strings.TrimSpace(ext)) == want {
+			return true
+		}
+	}
+	return false
+}

backend/internal/crawlerupload/migrator_test.go

@@ -0,0 +1,280 @@
+package crawlerupload
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/drives"
+	"github.com/video-site/backend/internal/drives/scriptcrawler"
+)
+
+type fakeRegistry struct {
+	byID map[string]drives.Drive
+}
+
+func newFakeRegistry() *fakeRegistry {
+	return &fakeRegistry{byID: make(map[string]drives.Drive)}
+}
+
+func (r *fakeRegistry) Add(d drives.Drive) {
+	r.byID[d.ID()] = d
+}
+
+func (r *fakeRegistry) Get(id string) (drives.Drive, bool) {
+	d, ok := r.byID[id]
+	return d, ok
+}
+
+func (r *fakeRegistry) All() []drives.Drive {
+	out := make([]drives.Drive, 0, len(r.byID))
+	for _, d := range r.byID {
+		out = append(out, d)
+	}
+	return out
+}
+
+type fakeUploadDrive struct {
+	id          string
+	kind        string
+	rootID      string
+	mu          sync.Mutex
+	uploadCalls int
+	gotBodies   map[string][]byte
+	gotParents  map[string]string
+	ensureCalls []string
+}
+
+func newFakeUploadDrive(id, kind, rootID string) *fakeUploadDrive {
+	return &fakeUploadDrive{
+		id:         id,
+		kind:       kind,
+		rootID:     rootID,
+		gotBodies:  make(map[string][]byte),
+		gotParents: make(map[string]string),
+	}
+}
+
+func (d *fakeUploadDrive) Kind() string { return d.kind }
+func (d *fakeUploadDrive) ID() string   { return d.id }
+func (d *fakeUploadDrive) RootID() string {
+	return d.rootID
+}
+func (d *fakeUploadDrive) Init(context.Context) error { return nil }
+func (d *fakeUploadDrive) List(context.Context, string) ([]drives.Entry, error) {
+	return nil, nil
+}
+func (d *fakeUploadDrive) Stat(context.Context, string) (*drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *fakeUploadDrive) StreamURL(context.Context, string) (*drives.StreamLink, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *fakeUploadDrive) Upload(context.Context, string, string, io.Reader, int64) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *fakeUploadDrive) EnsureDir(_ context.Context, pathFromRoot string) (string, error) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+	d.ensureCalls = append(d.ensureCalls, pathFromRoot)
+	return d.rootID + "/" + pathFromRoot, nil
+}
+func (d *fakeUploadDrive) Rename(context.Context, string, string) error {
+	return nil
+}
+func (d *fakeUploadDrive) UploadAndReportHash(_ context.Context, parentID, name string, r io.Reader, _ int64) (UploadResult, error) {
+	body, _ := io.ReadAll(r)
+	d.mu.Lock()
+	d.uploadCalls++
+	d.gotBodies[name] = body
+	d.gotParents[name] = parentID
+	d.mu.Unlock()
+	return UploadResult{FileID: "remote-" + name, Hash: strings.Repeat("a", 40), Size: int64(len(body))}, nil
+}
+
+var _ drives.Drive = (*fakeUploadDrive)(nil)
+var _ uploadTarget = (*fakeUploadDrive)(nil)
+
+func TestRunOnceUploadsScriptCrawlerLocalVideo(t *testing.T) {
+	ctx := context.Background()
+	cat := setupCatalog(t)
+	src := setupScriptCrawler(t, "crawler-one")
+	target := newFakeUploadDrive("target-drive", "pikpak", "target-root")
+	reg := newFakeRegistry()
+	reg.Add(src)
+	reg.Add(target)
+
+	if err := cat.UpsertDrive(ctx, &catalog.Drive{
+		ID:            src.ID(),
+		Kind:          scriptcrawler.Kind,
+		Name:          "Example Crawler",
+		RootID:        "/",
+		Credentials:   map[string]string{"script_path": "/tmp/example.py", "upload_drive_id": target.ID()},
+		TeaserEnabled: true,
+	}); err != nil {
+		t.Fatalf("upsert crawler drive: %v", err)
+	}
+
+	videoID := writeCrawlerVideo(t, cat, src, "source-001", ".mp4", []byte("video payload"), true)
+	commonThumbDir := filepath.Join(t.TempDir(), "thumbs")
+	m := New(Config{Catalog: cat, Registry: reg, CommonThumbDir: commonThumbDir})
+
+	if err := m.RunOnce(ctx); err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+
+	wantName := desiredUploadName("Sample source-001", "source-001", "mp4")
+	if target.uploadCalls != 1 {
+		t.Fatalf("upload calls = %d, want 1", target.uploadCalls)
+	}
+	if got := string(target.gotBodies[wantName]); got != "video payload" {
+		t.Fatalf("uploaded body = %q, want payload", got)
+	}
+	if got := target.gotParents[wantName]; got != "target-root/Script Crawlers/crawler-one" {
+		t.Fatalf("upload parent = %q, want crawler folder", got)
+	}
+	if len(target.ensureCalls) != 1 || target.ensureCalls[0] != "Script Crawlers/crawler-one" {
+		t.Fatalf("ensure calls = %#v, want crawler upload folder", target.ensureCalls)
+	}
+
+	got, err := cat.GetVideo(ctx, videoID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.DriveID != target.ID() || !strings.HasPrefix(got.FileID, "remote-") {
+		t.Fatalf("catalog target = drive %q file %q, want target drive", got.DriveID, got.FileID)
+	}
+	if got.FileName != wantName {
+		t.Fatalf("file_name = %q, want %q", got.FileName, wantName)
+	}
+	if _, err := os.Stat(filepath.Join(src.VideosDir(), "source-001.mp4")); !os.IsNotExist(err) {
+		t.Fatalf("local video still exists or stat failed: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(src.ThumbsDir(), "source-001.jpg")); !os.IsNotExist(err) {
+		t.Fatalf("local thumb still exists or stat failed: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(commonThumbDir, videoID+".jpg")); err != nil {
+		t.Fatalf("common thumbnail missing: %v", err)
+	}
+}
+
+func TestRunOnceRequiresPerCrawlerUploadTarget(t *testing.T) {
+	ctx := context.Background()
+	cat := setupCatalog(t)
+	src := setupScriptCrawler(t, "crawler-local-only")
+	target := newFakeUploadDrive("target-drive", "pikpak", "target-root")
+	reg := newFakeRegistry()
+	reg.Add(src)
+	reg.Add(target)
+
+	if err := cat.UpsertDrive(ctx, &catalog.Drive{
+		ID:            src.ID(),
+		Kind:          scriptcrawler.Kind,
+		Name:          "Local Only",
+		RootID:        "/",
+		Credentials:   map[string]string{"script_path": "/tmp/example.py"},
+		TeaserEnabled: true,
+	}); err != nil {
+		t.Fatalf("upsert crawler drive: %v", err)
+	}
+	videoID := writeCrawlerVideo(t, cat, src, "source-002", ".mp4", []byte("video payload"), true)
+
+	m := New(Config{Catalog: cat, Registry: reg})
+	if err := m.RunOnce(ctx); err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if target.uploadCalls != 0 {
+		t.Fatalf("upload calls = %d, want 0", target.uploadCalls)
+	}
+	got, err := cat.GetVideo(ctx, videoID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.DriveID != src.ID() {
+		t.Fatalf("drive_id = %q, want local crawler drive", got.DriveID)
+	}
+}
+
+func TestAdaptUploadTargetRejectsUnsupportedTarget(t *testing.T) {
+	src := scriptcrawler.New(scriptcrawler.Config{ID: "crawler", RootDir: t.TempDir()})
+	_, err := adaptUploadTarget(src)
+	if err == nil || !strings.Contains(err.Error(), "does not support crawler upload") {
+		t.Fatalf("err = %v, want unsupported crawler upload target", err)
+	}
+}
+
+func setupCatalog(t *testing.T) *catalog.Catalog {
+	t.Helper()
+	cat, err := catalog.Open(filepath.Join(t.TempDir(), "video-site.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+	return cat
+}
+
+func setupScriptCrawler(t *testing.T, id string) *scriptcrawler.Driver {
+	t.Helper()
+	d := scriptcrawler.New(scriptcrawler.Config{ID: id, RootDir: t.TempDir()})
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("scriptcrawler init: %v", err)
+	}
+	return d
+}
+
+func writeCrawlerVideo(t *testing.T, cat *catalog.Catalog, d *scriptcrawler.Driver, sourceID, ext string, content []byte, readyAssets bool) string {
+	t.Helper()
+	ctx := context.Background()
+	fileID := sourceID + ext
+	videoPath, err := d.VideoPath(fileID)
+	if err != nil {
+		t.Fatalf("video path: %v", err)
+	}
+	if err := os.WriteFile(videoPath, content, 0o644); err != nil {
+		t.Fatalf("write video: %v", err)
+	}
+	thumbPath, err := d.ThumbPath(sourceID + ".jpg")
+	if err != nil {
+		t.Fatalf("thumb path: %v", err)
+	}
+	if err := os.WriteFile(thumbPath, []byte("thumb"), 0o644); err != nil {
+		t.Fatalf("write thumb: %v", err)
+	}
+
+	now := time.Now()
+	videoID := scriptcrawler.BuildVideoID(d.ID(), sourceID)
+	previewStatus := "pending"
+	fingerprintStatus := "pending"
+	sampled := ""
+	if readyAssets {
+		previewStatus = "ready"
+		fingerprintStatus = "ready"
+		sampled = strings.Repeat("b", 64)
+	}
+	if err := cat.UpsertVideo(ctx, &catalog.Video{
+		ID:                videoID,
+		DriveID:           d.ID(),
+		FileID:            fileID,
+		FileName:          fileID,
+		Title:             "Sample " + sourceID,
+		Author:            "tester",
+		Ext:               strings.TrimPrefix(ext, "."),
+		Quality:           "HD",
+		Size:              int64(len(content)),
+		PreviewStatus:     previewStatus,
+		FingerprintStatus: fingerprintStatus,
+		SampledSHA256:     sampled,
+		PublishedAt:       now,
+		CreatedAt:         now,
+		UpdatedAt:         now,
+	}); err != nil {
+		t.Fatalf("upsert video: %v", err)
+	}
+	return videoID
+}

backend/internal/crawlerupload/naming.go

@@ -1,13 +1,13 @@
-package spider91migrate
+package crawlerupload
 
 import (
 	"strings"
 	"unicode"
 )
 
-// 期望的 PikPak 文件名格式（方案 B）：
+// 期望的上传文件名格式：
 //
-//	<sanitized-title>-<viewkey-后8位>.<ext>
+//	<sanitized-title>-<sourceID-后8位>.<ext>
 //
 // 例如：
 //
@@ -15,8 +15,8 @@ import (
 //
 // 设计目标：
 //   - 文件名一眼能看出视频内容（用 catalog 里的 title）
-//   - 后缀的 viewkey 8 字符保证同标题不会撞名
-//   - 全部字符在常见文件系统、PikPak、HTTP/Aliyun OSS Key 编码里都安全
+//   - 后缀的 sourceID 8 字符保证同标题不会撞名
+//   - 全部字符在常见文件系统、网盘 API、HTTP/Aliyun OSS Key 编码里都安全
 //
 // 字符清洗规则（sanitizeTitle）：
 //   - 去除控制字符（< 0x20 或 0x7F）
@@ -85,47 +85,47 @@ func truncateRunes(s string, maxRunes int) string {
 	return s
 }
 
-// extractViewKey 从 video.ID（"spider91-<driveID>-<viewkey>"）里
-// 取出最后一段 viewkey。
+// extractSourceID 从 video.ID（"<kind>-<driveID>-<sourceID>"）里
+// 取出最后一段 sourceID。
 //
-// driveID 中如果有 "-" 不影响（用 LastIndex），viewkey 本身（91 网站的
-// view 标识）目前都是纯 hex 或纯数字，不包含 "-"。
-func extractViewKey(videoID string) string {
+// driveID 中如果有 "-" 不影响（用 LastIndex）。爬虫脚本应提供不包含 "-"
+// 的稳定 source_id；如果包含 "-"，这里会取最后一段作为文件名后缀。
+func extractSourceID(videoID string) string {
 	if i := strings.LastIndex(videoID, "-"); i >= 0 {
 		return videoID[i+1:]
 	}
 	return videoID
 }
 
-// viewKeySuffix 取 viewkey 的最后 N 个字符；不足 N 返回原字符串。
+// sourceIDSuffix 取 sourceID 的最后 N 个字符；不足 N 返回原字符串。
 //
 // 默认 N=8（足够稀疏避免标题撞名时的同名冲突）。
-const viewKeySuffixLen = 8
+const sourceIDSuffixLen = 8
 
-func viewKeySuffix(viewkey string) string {
-	r := []rune(viewkey)
-	if len(r) <= viewKeySuffixLen {
+func sourceIDSuffix(sourceID string) string {
+	r := []rune(sourceID)
+	if len(r) <= sourceIDSuffixLen {
 		return string(r)
 	}
-	return string(r[len(r)-viewKeySuffixLen:])
+	return string(r[len(r)-sourceIDSuffixLen:])
 }
 
-// desiredPikPakName 构造 spider91 视频在 PikPak 上的期望文件名。
+// desiredUploadName 构造爬虫视频上传到目标网盘时的期望文件名。
 //
-//	desiredPikPakName("超白大奶律师约炮", "476fa8bf4b47e672d2fa", "mp4")
+//	desiredUploadName("超白大奶律师约炮", "476fa8bf4b47e672d2fa", "mp4")
 //	  → "超白大奶律师约炮-72d2fa.mp4"  // 实际是 e672d2fa（取最后 8）
 //
 // ext 不带前导点；空时默认 mp4。
-func desiredPikPakName(title, viewkey, ext string) string {
+func desiredUploadName(title, sourceID, ext string) string {
 	clean := sanitizeTitle(title)
-	suffix := viewKeySuffix(strings.TrimSpace(viewkey))
+	suffix := sourceIDSuffix(strings.TrimSpace(sourceID))
 	ext = strings.TrimSpace(ext)
 	ext = strings.TrimPrefix(ext, ".")
 	if ext == "" {
 		ext = "mp4"
 	}
 	if suffix == "" {
-		// viewkey 缺失时退化成 "<title>.<ext>"
+		// sourceID 缺失时退化成 "<title>.<ext>"
 		return clean + "." + ext
 	}
 	return clean + "-" + suffix + "." + ext

backend/internal/crawlerupload/naming_test.go

@@ -1,4 +1,4 @@
-package spider91migrate
+package crawlerupload
 
 import (
 	"strings"
@@ -13,11 +13,11 @@ func TestSanitizeTitleHandlesCommonCases(t *testing.T) {
 		{"hello", "hello"},
 		{"  hello  ", "hello"},
 		{"hello\nworld", "hello world"},
-		{"hello / world", "hello world"},          // 单 forbidden 折叠成空格
+		{"hello / world", "hello world"}, // 单 forbidden 折叠成空格
 		{"a/b\\c:d*e?f\"g<h>i|j", "a b c d e f g h i j"},
-		{"a   b", "a b"},                          // 多空格折叠
+		{"a   b", "a b"}, // 多空格折叠
 		{"a\t\nb", "a b"},
-		{"...trim.dots...", "trim.dots"},          // 首尾点号被 trim 掉
+		{"...trim.dots...", "trim.dots"},           // 首尾点号被 trim 掉
 		{"control\x01char\x1f\x7f", "controlchar"}, // 控制字符直接丢弃
 		{"", "video"},                              // 空串回退
 		{"  /  ", "video"},                         // 全是 forbidden+空白 → 回退
@@ -51,22 +51,22 @@ func TestSanitizeTitleKeepsCJKAndUnicode(t *testing.T) {
 	}
 }
 
-func TestExtractViewKey(t *testing.T) {
+func TestExtractSourceID(t *testing.T) {
 	cases := []struct{ in, want string }{
-		{"spider91-91Spider-476fa8bf4b47e672d2fa", "476fa8bf4b47e672d2fa"},
-		{"spider91-91Spider-1587338723", "1587338723"},
-		{"spider91-some-drive-with-dashes-vk001", "vk001"}, // LastIndex 拿尾段
+		{"scriptcrawler-demo-476fa8bf4b47e672d2fa", "476fa8bf4b47e672d2fa"},
+		{"scriptcrawler-demo-1587338723", "1587338723"},
+		{"scriptcrawler-some-drive-with-dashes-vk001", "vk001"}, // LastIndex 拿尾段
 		{"no-dashes-after-prefix", "prefix"},
 		{"single", "single"}, // 没 dash → 原样返回
 	}
 	for _, c := range cases {
-		if got := extractViewKey(c.in); got != c.want {
-			t.Errorf("extractViewKey(%q) = %q, want %q", c.in, got, c.want)
+		if got := extractSourceID(c.in); got != c.want {
+			t.Errorf("extractSourceID(%q) = %q, want %q", c.in, got, c.want)
 		}
 	}
 }
 
-func TestViewKeySuffix(t *testing.T) {
+func TestSourceIDSuffix(t *testing.T) {
 	cases := []struct{ in, want string }{
 		{"476fa8bf4b47e672d2fa", "e672d2fa"},
 		{"1587338723", "87338723"},
@@ -76,15 +76,15 @@ func TestViewKeySuffix(t *testing.T) {
 		{"123456789", "23456789"},
 	}
 	for _, c := range cases {
-		if got := viewKeySuffix(c.in); got != c.want {
-			t.Errorf("viewKeySuffix(%q) = %q, want %q", c.in, got, c.want)
+		if got := sourceIDSuffix(c.in); got != c.want {
+			t.Errorf("sourceIDSuffix(%q) = %q, want %q", c.in, got, c.want)
 		}
 	}
 }
 
-func TestDesiredPikPakName(t *testing.T) {
+func TestDesiredUploadName(t *testing.T) {
 	cases := []struct {
-		title, viewkey, ext, want string
+		title, sourceID, ext, want string
 	}{
 		{
 			"超白大奶律师约炮第一季",
@@ -112,7 +112,7 @@ func TestDesiredPikPakName(t *testing.T) {
 		},
 		{
 			"title",
-			"", // 空 viewkey → 退化成 "<title>.<ext>"
+			"", // 空 sourceID → 退化成 "<title>.<ext>"
 			"webm",
 			"title.webm",
 		},
@@ -130,9 +130,9 @@ func TestDesiredPikPakName(t *testing.T) {
 		},
 	}
 	for _, c := range cases {
-		got := desiredPikPakName(c.title, c.viewkey, c.ext)
+		got := desiredUploadName(c.title, c.sourceID, c.ext)
 		if got != c.want {
-			t.Errorf("desiredPikPakName(%q,%q,%q) = %q, want %q", c.title, c.viewkey, c.ext, got, c.want)
+			t.Errorf("desiredUploadName(%q,%q,%q) = %q, want %q", c.title, c.sourceID, c.ext, got, c.want)
 		}
 	}
 }

backend/internal/drives/googledrive/driver_test.go

@@ -0,0 +1,407 @@
+package googledrive
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/drives"
+)
+
+func TestInitUsesOnlineRenewAPI(t *testing.T) {
+	var savedAccess, savedRefresh string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/renew" {
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+		if got := r.URL.Query().Get("refresh_ui"); got != "old-refresh" {
+			t.Fatalf("refresh_ui = %q", got)
+		}
+		if got := r.URL.Query().Get("server_use"); got != "true" {
+			t.Fatalf("server_use = %q", got)
+		}
+		if got := r.URL.Query().Get("driver_txt"); got != "googleui_go" {
+			t.Fatalf("driver_txt = %q", got)
+		}
+		writeTestJSON(w, tokenResp{
+			AccessToken:  "new-access",
+			RefreshToken: "new-refresh",
+		})
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:           "g",
+		RefreshToken: "old-refresh",
+		UseOnlineAPI: true,
+		RenewAPIURL:  srv.URL + "/renew",
+		OnTokenUpdate: func(access, refresh string) {
+			savedAccess = access
+			savedRefresh = refresh
+		},
+	})
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("Init() error = %v", err)
+	}
+	if d.accessToken != "new-access" || d.refreshToken != "new-refresh" {
+		t.Fatalf("tokens not applied: access=%q refresh=%q", d.accessToken, d.refreshToken)
+	}
+	if savedAccess != "new-access" || savedRefresh != "new-refresh" {
+		t.Fatalf("tokens not persisted: access=%q refresh=%q", savedAccess, savedRefresh)
+	}
+}
+
+func TestListMapsGoogleDriveFiles(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Bearer access" {
+			t.Fatalf("Authorization = %q", got)
+		}
+		if r.URL.Path != "/drive/v3/files" {
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+		if !strings.Contains(r.URL.Query().Get("q"), "'root' in parents") {
+			t.Fatalf("unexpected q = %q", r.URL.Query().Get("q"))
+		}
+		writeTestJSON(w, filesResp{Files: []driveFile{
+			{ID: "folder-1", Name: "Movies", MimeType: "application/vnd.google-apps.folder"},
+			{
+				ID:            "file-1",
+				Name:          "clip.mp4",
+				MimeType:      "video/mp4",
+				Size:          "1234",
+				MD5Checksum:   "abc",
+				ThumbnailLink: "https://thumb.example/1",
+			},
+		}})
+	}))
+	defer srv.Close()
+
+	d := New(Config{ID: "g", RootID: "root", APIBaseURL: srv.URL + "/drive/v3"})
+	d.accessToken = "access"
+	d.listInterval = -1
+
+	entries, err := d.List(context.Background(), "")
+	if err != nil {
+		t.Fatalf("List() error = %v", err)
+	}
+	if len(entries) != 2 {
+		t.Fatalf("len(entries) = %d", len(entries))
+	}
+	if !entries[0].IsDir || entries[0].ID != "folder-1" {
+		t.Fatalf("folder entry = %+v", entries[0])
+	}
+	if entries[1].ID != "file-1" || entries[1].Size != 1234 || entries[1].Hash != "abc" || entries[1].ThumbnailURL == "" {
+		t.Fatalf("file entry = %+v", entries[1])
+	}
+}
+
+func TestStreamURLReturnsAuthenticatedMediaLinkWithoutRedirectRequirement(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Bearer access" {
+			t.Fatalf("Authorization = %q", got)
+		}
+		if r.URL.Path != "/drive/v3/files/file-1" {
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+		writeTestJSON(w, driveFile{
+			ID:       "file-1",
+			Name:     "clip.mp4",
+			MimeType: "video/mp4",
+			Size:     "1234",
+		})
+	}))
+	defer srv.Close()
+
+	d := New(Config{ID: "g", APIBaseURL: srv.URL + "/drive/v3"})
+	d.accessToken = "access"
+
+	link, err := d.StreamURL(context.Background(), "file-1")
+	if err != nil {
+		t.Fatalf("StreamURL() error = %v", err)
+	}
+	if !strings.HasPrefix(link.URL, srv.URL+"/drive/v3/files/file-1?") {
+		t.Fatalf("link URL = %q", link.URL)
+	}
+	if !strings.Contains(link.URL, "alt=media") {
+		t.Fatalf("link URL missing alt=media: %q", link.URL)
+	}
+	if got := link.Headers.Get("Authorization"); got != "Bearer access" {
+		t.Fatalf("link Authorization = %q", got)
+	}
+}
+
+func TestUploadAndReportHashUsesResumableSession(t *testing.T) {
+	body := "hello google drive"
+	wantHash := md5.Sum([]byte(body))
+	var sawSession bool
+	var sawUpload bool
+	var srv *httptest.Server
+	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/upload/drive/v3/files":
+			sawSession = true
+			if got := r.Header.Get("Authorization"); got != "Bearer access" {
+				t.Fatalf("session Authorization = %q", got)
+			}
+			if got := r.URL.Query().Get("uploadType"); got != "resumable" {
+				t.Fatalf("uploadType = %q", got)
+			}
+			if got := r.Header.Get("X-Upload-Content-Length"); got != "18" {
+				t.Fatalf("X-Upload-Content-Length = %q", got)
+			}
+			var meta struct {
+				Name    string   `json:"name"`
+				Parents []string `json:"parents"`
+			}
+			if err := json.NewDecoder(r.Body).Decode(&meta); err != nil {
+				t.Fatalf("decode session metadata: %v", err)
+			}
+			if meta.Name != "clip.mp4" || len(meta.Parents) != 1 || meta.Parents[0] != "parent-1" {
+				t.Fatalf("metadata = %+v", meta)
+			}
+			w.Header().Set("Location", srv.URL+"/upload/session/1")
+			w.WriteHeader(http.StatusOK)
+		case "/upload/session/1":
+			sawUpload = true
+			if got := r.Header.Get("Authorization"); got != "Bearer access" {
+				t.Fatalf("upload Authorization = %q", got)
+			}
+			if got := r.Header.Get("Content-Range"); got != "bytes 0-17/18" {
+				t.Fatalf("Content-Range = %q", got)
+			}
+			gotBody, err := io.ReadAll(r.Body)
+			if err != nil {
+				t.Fatalf("read upload body: %v", err)
+			}
+			if string(gotBody) != body {
+				t.Fatalf("upload body = %q", string(gotBody))
+			}
+			writeTestJSONStatus(w, http.StatusCreated, driveFile{
+				ID:          "file-uploaded",
+				Name:        "clip.mp4",
+				Size:        "18",
+				MD5Checksum: hex.EncodeToString(wantHash[:]),
+			})
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{ID: "g", APIBaseURL: srv.URL + "/drive/v3"})
+	d.accessToken = "access"
+	res, err := d.UploadAndReportHash(context.Background(), "parent-1", "clip.mp4", strings.NewReader(body), int64(len(body)))
+	if err != nil {
+		t.Fatalf("UploadAndReportHash() error = %v", err)
+	}
+	if !sawSession || !sawUpload {
+		t.Fatalf("saw session/upload = %v/%v, want both", sawSession, sawUpload)
+	}
+	if res.FileID != "file-uploaded" || res.Size != int64(len(body)) || res.Hash != hex.EncodeToString(wantHash[:]) {
+		t.Fatalf("upload result = %+v", res)
+	}
+}
+
+func TestEnsureDirAndRenameUseGoogleDriveFileAPI(t *testing.T) {
+	var madeDir bool
+	var renamed bool
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/drive/v3/files":
+			writeTestJSON(w, filesResp{})
+		case r.Method == http.MethodPost && r.URL.Path == "/drive/v3/files":
+			madeDir = true
+			var meta struct {
+				Name     string   `json:"name"`
+				Parents  []string `json:"parents"`
+				MimeType string   `json:"mimeType"`
+			}
+			if err := json.NewDecoder(r.Body).Decode(&meta); err != nil {
+				t.Fatalf("decode mkdir body: %v", err)
+			}
+			if meta.Name != "Crawler Uploads" || len(meta.Parents) != 1 || meta.Parents[0] != "root" || meta.MimeType != "application/vnd.google-apps.folder" {
+				t.Fatalf("mkdir body = %+v", meta)
+			}
+			writeTestJSON(w, driveFile{ID: "folder-crawler", Name: "Crawler Uploads", MimeType: "application/vnd.google-apps.folder"})
+		case r.Method == http.MethodPatch && r.URL.Path == "/drive/v3/files/file-1":
+			renamed = true
+			var body map[string]string
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatalf("decode rename body: %v", err)
+			}
+			if body["name"] != "new-name.mp4" {
+				t.Fatalf("rename body = %+v", body)
+			}
+			writeTestJSON(w, driveFile{ID: "file-1", Name: "new-name.mp4"})
+		default:
+			t.Fatalf("unexpected %s %s", r.Method, r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{ID: "g", RootID: "root", APIBaseURL: srv.URL + "/drive/v3"})
+	d.accessToken = "access"
+	d.listInterval = -1
+
+	dirID, err := d.EnsureDir(context.Background(), "Crawler Uploads")
+	if err != nil {
+		t.Fatalf("EnsureDir() error = %v", err)
+	}
+	if dirID != "folder-crawler" || !madeDir {
+		t.Fatalf("dirID/madeDir = %q/%v, want folder-crawler/true", dirID, madeDir)
+	}
+	if err := d.Rename(context.Background(), "file-1", "new-name.mp4"); err != nil {
+		t.Fatalf("Rename() error = %v", err)
+	}
+	if !renamed {
+		t.Fatal("rename endpoint was not called")
+	}
+}
+
+func TestRequestRefreshesOnUnauthorized(t *testing.T) {
+	var fileCalls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/renew":
+			writeTestJSON(w, tokenResp{
+				AccessToken:  "new-access",
+				RefreshToken: "new-refresh",
+			})
+		case "/drive/v3/files/file-1":
+			fileCalls++
+			if fileCalls == 1 {
+				writeTestJSONStatus(w, http.StatusUnauthorized, apiErrorResp{Error: apiErrorBody{
+					Code:    http.StatusUnauthorized,
+					Message: "Invalid Credentials",
+				}})
+				return
+			}
+			if got := r.Header.Get("Authorization"); got != "Bearer new-access" {
+				t.Fatalf("Authorization after refresh = %q", got)
+			}
+			writeTestJSON(w, driveFile{ID: "file-1", Name: "clip.mp4", Size: "1"})
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:           "g",
+		RefreshToken: "old-refresh",
+		UseOnlineAPI: true,
+		RenewAPIURL:  srv.URL + "/renew",
+		APIBaseURL:   srv.URL + "/drive/v3",
+	})
+	d.accessToken = "old-access"
+
+	if _, err := d.Stat(context.Background(), "file-1"); err != nil {
+		t.Fatalf("Stat() error = %v", err)
+	}
+	if fileCalls != 2 {
+		t.Fatalf("fileCalls = %d", fileCalls)
+	}
+	if d.accessToken != "new-access" || d.refreshToken != "new-refresh" {
+		t.Fatalf("tokens not refreshed: access=%q refresh=%q", d.accessToken, d.refreshToken)
+	}
+}
+
+func TestRateLimitReasonsFollowGoogleDriveErrorShape(t *testing.T) {
+	reasons := []string{
+		"rateLimitExceeded",
+		"userRateLimitExceeded",
+		"dailyLimitExceeded",
+		"dailyLimitExceededUnreg",
+		"downloadQuotaExceeded",
+		"sharingRateLimitExceeded",
+		"quotaExceeded",
+	}
+	for _, reason := range reasons {
+		body := apiErrorBody{
+			Code:    http.StatusForbidden,
+			Message: "google drive quota or rate limited",
+			Errors: []struct {
+				Domain       string `json:"domain"`
+				Reason       string `json:"reason"`
+				Message      string `json:"message"`
+				LocationType string `json:"location_type"`
+				Location     string `json:"location"`
+			}{
+				{Domain: "usageLimits", Reason: reason, Message: reason},
+			},
+		}
+		if !isGoogleRateLimit(nil, body) {
+			t.Fatalf("reason %q not treated as rate limit", reason)
+		}
+	}
+}
+
+func TestStreamURLRateLimitStartsSharedLinkCooldown(t *testing.T) {
+	var calls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		calls++
+		w.Header().Set("Retry-After", "120")
+		writeTestJSONStatus(w, http.StatusForbidden, apiErrorResp{Error: apiErrorBody{
+			Code:    http.StatusForbidden,
+			Message: "User rate limit exceeded.",
+			Errors: []struct {
+				Domain       string `json:"domain"`
+				Reason       string `json:"reason"`
+				Message      string `json:"message"`
+				LocationType string `json:"location_type"`
+				Location     string `json:"location"`
+			}{
+				{Domain: "usageLimits", Reason: "userRateLimitExceeded", Message: "User rate limit exceeded."},
+			},
+		}})
+	}))
+	defer srv.Close()
+
+	d := New(Config{ID: "g", APIBaseURL: srv.URL})
+	d.accessToken = "access"
+	d.linkCooldownDuration = time.Hour
+
+	_, err := d.StreamURL(context.Background(), "file-1")
+	if err == nil {
+		t.Fatal("first StreamURL succeeded, want rate limit")
+	}
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("first error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.RetryAfter != 2*time.Minute {
+		t.Fatalf("retry after = %s, want 2m", rateLimit.RetryAfter)
+	}
+
+	_, err = d.StreamURL(context.Background(), "file-1")
+	if err == nil {
+		t.Fatal("second StreamURL succeeded during cooldown")
+	}
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("second error = %T %[1]v, want RateLimitError", err)
+	}
+	if calls != 1 {
+		t.Fatalf("remote calls = %d, want 1; second call should use shared cooldown", calls)
+	}
+	if rateLimit.RetryAfter <= 0 || rateLimit.RetryAfter > 2*time.Minute {
+		t.Fatalf("second retry after = %s, want remaining cooldown", rateLimit.RetryAfter)
+	}
+}
+
+func writeTestJSON(w http.ResponseWriter, v any) {
+	writeTestJSONStatus(w, http.StatusOK, v)
+}
+
+func writeTestJSONStatus(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}

backend/internal/drives/googledrive/types.go

@@ -0,0 +1,57 @@
+package googledrive
+
+import "time"
+
+type tokenResp struct {
+	AccessToken      string `json:"access_token"`
+	RefreshToken     string `json:"refresh_token"`
+	ExpiresIn        int64  `json:"expires_in"`
+	Error            string `json:"error"`
+	ErrorDescription string `json:"error_description"`
+	Text             string `json:"text"`
+}
+
+type filesResp struct {
+	NextPageToken string       `json:"nextPageToken"`
+	Files         []driveFile  `json:"files"`
+	Error         apiErrorBody `json:"error"`
+}
+
+type driveFile struct {
+	ID             string    `json:"id"`
+	Name           string    `json:"name"`
+	MimeType       string    `json:"mimeType"`
+	ModifiedTime   time.Time `json:"modifiedTime"`
+	CreatedTime    time.Time `json:"createdTime"`
+	Size           string    `json:"size"`
+	ThumbnailLink  string    `json:"thumbnailLink"`
+	MD5Checksum    string    `json:"md5Checksum"`
+	SHA1Checksum   string    `json:"sha1Checksum"`
+	SHA256Checksum string    `json:"sha256Checksum"`
+	Shortcut       struct {
+		TargetID       string `json:"targetId"`
+		TargetMimeType string `json:"targetMimeType"`
+	} `json:"shortcutDetails"`
+}
+
+type apiErrorResp struct {
+	Error apiErrorBody `json:"error"`
+}
+
+type apiErrorBody struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Errors  []struct {
+		Domain       string `json:"domain"`
+		Reason       string `json:"reason"`
+		Message      string `json:"message"`
+		LocationType string `json:"location_type"`
+		Location     string `json:"location"`
+	} `json:"errors"`
+}
+
+type UploadResult struct {
+	FileID string
+	Hash   string
+	Size   int64
+}

backend/internal/drives/guangyapan/driver_test.go

@@ -0,0 +1,300 @@
+package guangyapan
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/drives"
+)
+
+func TestDriverRefreshListAndStream(t *testing.T) {
+	var refreshed bool
+	var listedRoot bool
+	updates := map[string]string{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/auth/token":
+			refreshed = true
+			writeTestJSON(w, map[string]any{
+				"access_token":  "new-access",
+				"refresh_token": "new-refresh",
+			})
+		case "/v1/user/me":
+			if got := r.Header.Get("Authorization"); got != "Bearer new-access" {
+				t.Fatalf("auth header = %q, want new access token", got)
+			}
+			writeTestJSON(w, map[string]any{"sub": "user-1"})
+		case "/userres/v1/file/get_file_list":
+			if got := r.Header.Get("Authorization"); got != "Bearer new-access" {
+				t.Fatalf("api auth header = %q, want new access token", got)
+			}
+			var body map[string]any
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatalf("decode list body: %v", err)
+			}
+			if body["parentId"] != "" {
+				t.Fatalf("parentId = %#v, want root empty string", body["parentId"])
+			}
+			listedRoot = true
+			writeTestJSON(w, map[string]any{
+				"code": 0,
+				"msg":  "success",
+				"data": map[string]any{
+					"total": 2,
+					"list": []map[string]any{
+						{"fileId": "dir-1", "parentId": "", "fileName": "Movies", "resType": 2},
+						{"fileId": "file-1", "parentId": "", "fileName": "clip.mp4", "fileSize": 123, "resType": 1, "utime": 1700000000},
+					},
+				},
+			})
+		case "/nd.bizuserres.s/v1/get_res_download_url":
+			writeTestJSON(w, map[string]any{
+				"code": 0,
+				"msg":  "success",
+				"data": map[string]any{"signedURL": "https://cdn.example.test/clip.mp4"},
+			})
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:             "gy",
+		RefreshToken:   "old-refresh",
+		AccountBaseURL: srv.URL,
+		APIBaseURL:     srv.URL,
+		OnCredentialsUpdate: func(values map[string]string) {
+			for k, v := range values {
+				updates[k] = v
+			}
+		},
+	})
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("init: %v", err)
+	}
+	if !refreshed {
+		t.Fatal("refresh token endpoint was not called")
+	}
+	if updates["access_token"] != "new-access" || updates["refresh_token"] != "new-refresh" {
+		t.Fatalf("updates = %#v, want refreshed tokens", updates)
+	}
+
+	entries, err := d.List(context.Background(), "")
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if !listedRoot || len(entries) != 2 {
+		t.Fatalf("listedRoot=%v entries=%#v", listedRoot, entries)
+	}
+	if !entries[0].IsDir || entries[1].ID != "file-1" || entries[1].Size != 123 {
+		t.Fatalf("entries = %#v", entries)
+	}
+
+	link, err := d.StreamURL(context.Background(), "file-1")
+	if err != nil {
+		t.Fatalf("stream url: %v", err)
+	}
+	if link.URL != "https://cdn.example.test/clip.mp4" {
+		t.Fatalf("stream url = %q", link.URL)
+	}
+}
+
+func TestDriverResolvesRootPath(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/user/me":
+			writeTestJSON(w, map[string]any{"sub": "user-1"})
+		case "/userres/v1/file/get_file_list":
+			var body map[string]any
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatalf("decode list body: %v", err)
+			}
+			parent, _ := body["parentId"].(string)
+			switch parent {
+			case "":
+				writeTestJSON(w, listTestResponse([]map[string]any{
+					{"fileId": "folder-a", "parentId": "", "fileName": "影视", "resType": 2},
+				}))
+			case "folder-a":
+				writeTestJSON(w, listTestResponse([]map[string]any{
+					{"fileId": "folder-b", "parentId": "folder-a", "fileName": "电影", "resType": 2},
+				}))
+			case "folder-b":
+				writeTestJSON(w, listTestResponse([]map[string]any{
+					{"fileId": "file-1", "parentId": "folder-b", "fileName": "movie.mp4", "fileSize": 456, "resType": 1},
+				}))
+			default:
+				t.Fatalf("unexpected parent %q", parent)
+			}
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:             "gy",
+		RootID:         "configured-root",
+		RootPath:       "影视/电影",
+		AccessToken:    "access",
+		AccountBaseURL: srv.URL,
+		APIBaseURL:     srv.URL,
+	})
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("init: %v", err)
+	}
+	if d.RootID() != "folder-b" {
+		t.Fatalf("root id = %q, want folder-b", d.RootID())
+	}
+	entries, err := d.List(context.Background(), "")
+	if err != nil {
+		t.Fatalf("list resolved root: %v", err)
+	}
+	if len(entries) != 1 || entries[0].ID != "file-1" {
+		t.Fatalf("entries = %#v", entries)
+	}
+}
+
+func TestDriverSendSMSCodeUpdatesVerificationState(t *testing.T) {
+	updates := map[string]string{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/shield/captcha/init":
+			writeTestJSON(w, map[string]any{"captcha_token": "captcha-1"})
+		case "/v1/auth/verification":
+			writeTestJSON(w, map[string]any{"verification_id": "verify-1"})
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:             "gy",
+		PhoneNumber:    "13800000000",
+		SendCode:       true,
+		AccountBaseURL: srv.URL,
+		APIBaseURL:     srv.URL,
+		OnCredentialsUpdate: func(values map[string]string) {
+			for k, v := range values {
+				updates[k] = v
+			}
+		},
+	})
+	err := d.Init(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "验证码已发送") {
+		t.Fatalf("init err = %v, want verification prompt", err)
+	}
+	if updates["captcha_token"] != "captcha-1" || updates["verification_id"] != "verify-1" || updates["send_code"] != "false" {
+		t.Fatalf("updates = %#v, want sms state saved", updates)
+	}
+	if updates["device_id"] == "" {
+		t.Fatalf("updates = %#v, want generated device id saved", updates)
+	}
+}
+
+func TestListHTTP429ReturnsRateLimitError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/userres/v1/file/get_file_list" {
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+		w.Header().Set("Retry-After", "120")
+		w.WriteHeader(http.StatusTooManyRequests)
+		writeTestJSON(w, map[string]any{"code": 429, "msg": "操作频繁，请稍后重试"})
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:             "gy",
+		AccessToken:    "access",
+		AccountBaseURL: srv.URL,
+		APIBaseURL:     srv.URL,
+	})
+	_, err := d.List(context.Background(), "")
+	if err == nil {
+		t.Fatal("list succeeded, want rate limit error")
+	}
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.RetryAfter != 2*time.Minute {
+		t.Fatalf("retry after = %s, want 2m", rateLimit.RetryAfter)
+	}
+}
+
+func TestListCode429ReturnsRateLimitError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/userres/v1/file/get_file_list" {
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+		writeTestJSON(w, map[string]any{"code": 429, "msg": "操作频繁，请稍后再试"})
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:             "gy",
+		AccessToken:    "access",
+		AccountBaseURL: srv.URL,
+		APIBaseURL:     srv.URL,
+	})
+	_, err := d.List(context.Background(), "")
+	if err == nil {
+		t.Fatal("list succeeded, want rate limit error")
+	}
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+}
+
+func TestListInvalidToken403DoesNotReturnRateLimitError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/userres/v1/file/get_file_list" {
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+		w.WriteHeader(http.StatusForbidden)
+		writeTestJSON(w, map[string]any{"code": 401, "msg": "invalid access token"})
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:             "gy",
+		AccessToken:    "access",
+		AccountBaseURL: srv.URL,
+		APIBaseURL:     srv.URL,
+	})
+	_, err := d.List(context.Background(), "")
+	if err == nil {
+		t.Fatal("list succeeded, want auth error")
+	}
+	var rateLimit *drives.RateLimitError
+	if errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want non-rate-limit error", err)
+	}
+}
+
+func listTestResponse(items []map[string]any) map[string]any {
+	return map[string]any{
+		"code": 0,
+		"msg":  "success",
+		"data": map[string]any{
+			"total": len(items),
+			"list":  items,
+		},
+	}
+}
+
+func writeTestJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(v); err != nil {
+		panic(err)
+	}
+}

backend/internal/drives/guangyapan/qr.go

@@ -0,0 +1,244 @@
+package guangyapan
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-resty/resty/v2"
+	"github.com/skip2/go-qrcode"
+)
+
+const (
+	defaultQRScope      = "user"
+	deviceCodeGrantType = "urn:ietf:params:oauth:grant-type:device_code"
+	defaultQRUserAgent  = "GuangYaPan-Login/1.0"
+)
+
+type QRConfig struct {
+	AccountBaseURL string
+	HTTPClient     *http.Client
+	Now            func() time.Time
+}
+
+type QRClient struct {
+	accountBaseURL string
+	client         *resty.Client
+	now            func() time.Time
+}
+
+type QRCodeSession struct {
+	DeviceCode      string `json:"deviceCode"`
+	QRCodeURL       string `json:"qrCodeUrl"`
+	QRImageDataURL  string `json:"qrImageDataUrl"`
+	IntervalSeconds int    `json:"intervalSeconds"`
+	ExpiresAt       string `json:"expiresAt,omitempty"`
+}
+
+type QRCodeStatus struct {
+	State           string `json:"state"`
+	StatusText      string `json:"statusText"`
+	IntervalSeconds int    `json:"intervalSeconds,omitempty"`
+	AccessToken     string `json:"accessToken,omitempty"`
+	RefreshToken    string `json:"refreshToken,omitempty"`
+	TokenType       string `json:"tokenType,omitempty"`
+	ExpiresIn       int64  `json:"expiresIn,omitempty"`
+}
+
+type deviceCodeResp struct {
+	DeviceCode              string `json:"device_code"`
+	VerificationURIComplete string `json:"verification_uri_complete"`
+	ShortURIComplete        string `json:"short_uri_complete"`
+	Interval                int    `json:"interval"`
+	ExpiresIn               int    `json:"expires_in"`
+	Error                   string `json:"error"`
+	ErrorCode               int    `json:"error_code"`
+	ErrorDesc               string `json:"error_description"`
+}
+
+type deviceTokenResp struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int64  `json:"expires_in"`
+	Scope        string `json:"scope"`
+	Error        string `json:"error"`
+	ErrorCode    int    `json:"error_code"`
+	ErrorDesc    string `json:"error_description"`
+}
+
+func NewQRClient(c QRConfig) *QRClient {
+	accountBaseURL := strings.TrimRight(strings.TrimSpace(c.AccountBaseURL), "/")
+	if accountBaseURL == "" {
+		accountBaseURL = defaultAccountBaseURL
+	}
+	httpClient := c.HTTPClient
+	if httpClient == nil {
+		httpClient = &http.Client{Timeout: 20 * time.Second}
+	}
+	now := c.Now
+	if now == nil {
+		now = time.Now
+	}
+	return &QRClient{
+		accountBaseURL: accountBaseURL,
+		client: resty.NewWithClient(httpClient).
+			SetTimeout(20*time.Second).
+			SetBaseURL(accountBaseURL).
+			SetHeader("User-Agent", defaultQRUserAgent).
+			SetHeader("Accept", "application/json").
+			SetHeader("Content-Type", "application/json"),
+		now: now,
+	}
+}
+
+func (c *QRClient) Generate(ctx context.Context) (QRCodeSession, error) {
+	var out deviceCodeResp
+	var errOut deviceCodeResp
+	resp, err := c.client.R().
+		SetContext(ctx).
+		SetBody(map[string]any{
+			"client_id": defaultClientID,
+			"scope":     defaultQRScope,
+		}).
+		SetResult(&out).
+		SetError(&errOut).
+		Post("/v1/auth/device/code")
+	if err != nil {
+		return QRCodeSession{}, err
+	}
+	if resp.IsError() || out.Error != "" {
+		if out.Error == "" {
+			out = errOut
+		}
+		return QRCodeSession{}, fmt.Errorf("guangyapan qr: %s", deviceAPIError(out.ErrorDesc, out.Error, resp))
+	}
+
+	deviceCode := strings.TrimSpace(out.DeviceCode)
+	if deviceCode == "" {
+		return QRCodeSession{}, errors.New("guangyapan qr: empty device_code")
+	}
+	qrURL := strings.TrimSpace(out.VerificationURIComplete)
+	if qrURL == "" {
+		qrURL = strings.TrimSpace(out.ShortURIComplete)
+	}
+	if qrURL == "" {
+		return QRCodeSession{}, errors.New("guangyapan qr: empty verification uri")
+	}
+	interval := out.Interval
+	if interval <= 0 {
+		interval = 5
+	}
+	expiresIn := out.ExpiresIn
+	if expiresIn <= 0 {
+		expiresIn = 300
+	}
+	png, err := qrcode.Encode(qrURL, qrcode.Medium, 220)
+	if err != nil {
+		return QRCodeSession{}, err
+	}
+	return QRCodeSession{
+		DeviceCode:      deviceCode,
+		QRCodeURL:       qrURL,
+		QRImageDataURL:  "data:image/png;base64," + base64.StdEncoding.EncodeToString(png),
+		IntervalSeconds: interval,
+		ExpiresAt:       c.now().Add(time.Duration(expiresIn) * time.Second).Format(time.RFC3339),
+	}, nil
+}
+
+func (c *QRClient) Poll(ctx context.Context, deviceCode string) (QRCodeStatus, error) {
+	deviceCode = strings.TrimSpace(deviceCode)
+	if deviceCode == "" {
+		return QRCodeStatus{}, errors.New("deviceCode is required")
+	}
+
+	var out deviceTokenResp
+	var errOut deviceTokenResp
+	resp, err := c.client.R().
+		SetContext(ctx).
+		SetBody(map[string]any{
+			"client_id":   defaultClientID,
+			"grant_type":  deviceCodeGrantType,
+			"device_code": deviceCode,
+		}).
+		SetResult(&out).
+		SetError(&errOut).
+		Post("/v1/auth/token")
+	if err != nil {
+		return QRCodeStatus{}, err
+	}
+	if resp.IsError() && out.Error == "" {
+		out = errOut
+	}
+	if resp.IsError() && out.Error == "" {
+		_ = json.Unmarshal(resp.Body(), &out)
+	}
+	if out.Error != "" {
+		return qrStatusForDeviceError(out), nil
+	}
+	if resp.IsError() {
+		return QRCodeStatus{}, fmt.Errorf("guangyapan qr: status=%d body=%s", resp.StatusCode(), resp.String())
+	}
+	access := strings.TrimSpace(out.AccessToken)
+	refresh := strings.TrimSpace(out.RefreshToken)
+	if access == "" || refresh == "" {
+		return QRCodeStatus{}, errors.New("guangyapan qr: login succeeded but token response is incomplete")
+	}
+	tokenType := strings.TrimSpace(out.TokenType)
+	if tokenType == "" {
+		tokenType = "Bearer"
+	}
+	return QRCodeStatus{
+		State:        "success",
+		StatusText:   "登录成功",
+		AccessToken:  access,
+		RefreshToken: refresh,
+		TokenType:    tokenType,
+		ExpiresIn:    out.ExpiresIn,
+	}, nil
+}
+
+func qrStatusForDeviceError(out deviceTokenResp) QRCodeStatus {
+	errCode := strings.TrimSpace(out.Error)
+	switch errCode {
+	case "authorization_pending":
+		return QRCodeStatus{State: "pending", StatusText: "等待扫码确认"}
+	case "slow_down":
+		return QRCodeStatus{State: "pending", StatusText: "等待扫码确认，已降低查询频率", IntervalSeconds: 10}
+	case "expired_token":
+		return QRCodeStatus{State: "expired", StatusText: "二维码已过期"}
+	case "access_denied":
+		return QRCodeStatus{State: "denied", StatusText: "用户拒绝了授权"}
+	default:
+		msg := strings.TrimSpace(out.ErrorDesc)
+		if msg == "" {
+			msg = errCode
+		}
+		if msg == "" {
+			msg = "未知错误"
+		}
+		return QRCodeStatus{State: "error", StatusText: msg}
+	}
+}
+
+func deviceAPIError(desc, short string, resp *resty.Response) string {
+	msg := strings.TrimSpace(desc)
+	if msg == "" {
+		msg = strings.TrimSpace(short)
+	}
+	if msg == "" && resp != nil {
+		msg = strings.TrimSpace(resp.String())
+	}
+	if msg == "" && resp != nil {
+		msg = fmt.Sprintf("status=%d", resp.StatusCode())
+	}
+	if msg == "" {
+		msg = "unknown error"
+	}
+	return msg
+}

backend/internal/drives/guangyapan/qr_test.go

@@ -0,0 +1,102 @@
+package guangyapan
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestQRClientGenerate(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/auth/device/code" {
+			t.Fatalf("path = %s, want device code endpoint", r.URL.Path)
+		}
+		var body map[string]any
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Fatalf("decode body: %v", err)
+		}
+		if body["client_id"] != defaultClientID || body["scope"] != defaultQRScope {
+			t.Fatalf("body = %#v", body)
+		}
+		writeTestJSON(w, map[string]any{
+			"device_code":               "device-1",
+			"verification_uri_complete": "https://account.guangyapan.com/device?code=abc",
+			"interval":                  7,
+			"expires_in":                180,
+		})
+	}))
+	defer srv.Close()
+
+	client := NewQRClient(QRConfig{
+		AccountBaseURL: srv.URL,
+		Now:            func() time.Time { return time.Unix(1700000000, 0) },
+	})
+	session, err := client.Generate(context.Background())
+	if err != nil {
+		t.Fatalf("generate: %v", err)
+	}
+	if session.DeviceCode != "device-1" || session.QRCodeURL != "https://account.guangyapan.com/device?code=abc" {
+		t.Fatalf("session = %#v", session)
+	}
+	if session.IntervalSeconds != 7 {
+		t.Fatalf("interval = %d, want 7", session.IntervalSeconds)
+	}
+	if session.ExpiresAt != time.Unix(1700000180, 0).Format(time.RFC3339) {
+		t.Fatalf("expiresAt = %q", session.ExpiresAt)
+	}
+	if !strings.HasPrefix(session.QRImageDataURL, "data:image/png;base64,") {
+		t.Fatalf("qr image = %q", session.QRImageDataURL)
+	}
+}
+
+func TestQRClientPollPendingAndSuccess(t *testing.T) {
+	var calls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/auth/token" {
+			t.Fatalf("path = %s, want token endpoint", r.URL.Path)
+		}
+		var body map[string]any
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Fatalf("decode body: %v", err)
+		}
+		if body["client_id"] != defaultClientID ||
+			body["grant_type"] != deviceCodeGrantType ||
+			body["device_code"] != "device-1" {
+			t.Fatalf("body = %#v", body)
+		}
+		calls++
+		if calls == 1 {
+			w.WriteHeader(http.StatusBadRequest)
+			writeTestJSON(w, map[string]any{"error": "authorization_pending"})
+			return
+		}
+		writeTestJSON(w, map[string]any{
+			"access_token":  "access-1",
+			"refresh_token": "refresh-1",
+			"token_type":    "Bearer",
+			"expires_in":    7200,
+		})
+	}))
+	defer srv.Close()
+
+	client := NewQRClient(QRConfig{AccountBaseURL: srv.URL})
+	pending, err := client.Poll(context.Background(), "device-1")
+	if err != nil {
+		t.Fatalf("poll pending: %v", err)
+	}
+	if pending.State != "pending" || pending.AccessToken != "" {
+		t.Fatalf("pending = %#v", pending)
+	}
+
+	success, err := client.Poll(context.Background(), "device-1")
+	if err != nil {
+		t.Fatalf("poll success: %v", err)
+	}
+	if success.State != "success" || success.AccessToken != "access-1" || success.RefreshToken != "refresh-1" {
+		t.Fatalf("success = %#v", success)
+	}
+}

backend/internal/drives/guangyapan/types.go

@@ -0,0 +1,129 @@
+package guangyapan
+
+import "time"
+
+type tokenResp struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	Error        string `json:"error"`
+	ErrorCode    int    `json:"error_code"`
+	ErrorDesc    string `json:"error_description"`
+}
+
+type verificationResp struct {
+	VerificationID string `json:"verification_id"`
+	Error          string `json:"error"`
+	ErrorCode      int    `json:"error_code"`
+	ErrorDesc      string `json:"error_description"`
+}
+
+type captchaInitResp struct {
+	CaptchaToken string `json:"captcha_token"`
+	Error        string `json:"error"`
+	ErrorCode    int    `json:"error_code"`
+	ErrorDesc    string `json:"error_description"`
+}
+
+type verifyResp struct {
+	VerificationToken string `json:"verification_token"`
+	Error             string `json:"error"`
+	ErrorCode         int    `json:"error_code"`
+	ErrorDesc         string `json:"error_description"`
+}
+
+type userMeResp struct {
+	Sub string `json:"sub"`
+}
+
+type listResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		Total int        `json:"total"`
+		List  []fileItem `json:"list"`
+	} `json:"data"`
+}
+
+type fileItem struct {
+	FileID   string `json:"fileId"`
+	ParentID string `json:"parentId"`
+	FileName string `json:"fileName"`
+	FileSize int64  `json:"fileSize"`
+	ResType  int    `json:"resType"`
+	CTime    int64  `json:"ctime"`
+	UTime    int64  `json:"utime"`
+}
+
+type downloadResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		SignedURL   string `json:"signedURL"`
+		DownloadURL string `json:"downloadUrl"`
+	} `json:"data"`
+}
+
+type createDirResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		FileID   string `json:"fileId"`
+		FileName string `json:"fileName"`
+		ResType  int    `json:"resType"`
+		CTime    int64  `json:"ctime"`
+		UTime    int64  `json:"utime"`
+	} `json:"data"`
+}
+
+type deleteResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		TaskID string `json:"taskId"`
+	} `json:"data"`
+}
+
+type taskStatusResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		Status int `json:"status"`
+	} `json:"data"`
+}
+
+type uploadTokenResp struct {
+	Code int             `json:"code"`
+	Msg  string          `json:"msg"`
+	Data uploadTokenData `json:"data"`
+}
+
+type uploadTokenData struct {
+	TaskID          string `json:"taskId"`
+	ObjectPath      string `json:"objectPath"`
+	BucketName      string `json:"bucketName"`
+	EndPoint        string `json:"endPoint"`
+	FullEndPoint    string `json:"fullEndPoint"`
+	AccessKeyID     string `json:"accessKeyID"`
+	SecretAccessKey string `json:"secretAccessKey"`
+	SessionToken    string `json:"sessionToken"`
+	Creds           struct {
+		AccessKeyID     string `json:"accessKeyID"`
+		SecretAccessKey string `json:"secretAccessKey"`
+		SessionToken    string `json:"sessionToken"`
+	} `json:"creds"`
+}
+
+type taskInfoResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		FileID string `json:"fileId"`
+	} `json:"data"`
+}
+
+func unixOrZero(v int64) time.Time {
+	if v <= 0 {
+		return time.Time{}
+	}
+	return time.Unix(v, 0)
+}

backend/internal/drives/iface.go

@@ -5,12 +5,14 @@ import (
 	"errors"
 	"io"
 	"net/http"
+	"strconv"
+	"strings"
 	"time"
 )
 
 // Drive 是多家网盘统一抽象。上层不区分盘，只区分 Kind。
 type Drive interface {
-	// Kind 返回驱动代号："quark" / "p115" / "pikpak" / "wopan" / "onedrive"
+	// Kind 返回驱动代号："quark" / "p115" / "p123" / "pikpak" / "wopan" / "guangyapan" / "onedrive" / "googledrive" / "localstorage"
 	Kind() string
 
 	// ID 返回该盘在 catalog 中的唯一标识
@@ -30,7 +32,7 @@ type Drive interface {
 	StreamURL(ctx context.Context, fileID string) (*StreamLink, error)
 
 	// Upload 把本地流写入指定目录，返回新文件 fileID。
-	// 当前 teaser 和封面只保存在本地，不再通过该方法写回网盘。
+	// 当前预览视频和封面只保存在本地，不再通过该方法写回网盘。
 	Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error)
 
 	// EnsureDir 保证指定路径存在（相对根目录），返回最终目录 fileID。
@@ -40,6 +42,27 @@ type Drive interface {
 	RootID() string
 }
 
+// Remover is an optional drive capability. It mirrors OpenList's optional
+// Remove interface: callers must type-assert before deleting a source file.
+type Remover interface {
+	Remove(ctx context.Context, fileID string) error
+}
+
+// SourceFile carries the catalog metadata available when an administrator
+// requests deletion of the original source file.
+type SourceFile struct {
+	FileID   string
+	ParentID string
+	Name     string
+	Size     int64
+}
+
+// SourceRemover is an optional, richer removal capability for providers whose
+// playback ID is not the same ID required by their delete API.
+type SourceRemover interface {
+	RemoveSource(ctx context.Context, source SourceFile) error
+}
+
 type Entry struct {
 	ID       string
 	Name     string
@@ -98,3 +121,42 @@ func RateLimitRetryAfter(err error) (time.Duration, bool) {
 	}
 	return 0, false
 }
+
+// TextMentionsHTTPStatus only looks for explicit numeric HTTP status contexts
+// in errors from tools that do not expose structured response metadata.
+func TextMentionsHTTPStatus(text string, statuses ...int) bool {
+	text = strings.ToLower(strings.TrimSpace(text))
+	if text == "" {
+		return false
+	}
+	for _, status := range statuses {
+		if status <= 0 {
+			continue
+		}
+		code := strconv.Itoa(status)
+		if strings.HasPrefix(text, code+" ") ||
+			strings.Contains(text, "status="+code) ||
+			strings.Contains(text, "status: "+code) ||
+			strings.Contains(text, "status "+code) ||
+			strings.Contains(text, "status code "+code) ||
+			strings.Contains(text, "http "+code) ||
+			strings.Contains(text, "http status="+code) ||
+			strings.Contains(text, "http status: "+code) ||
+			strings.Contains(text, "http status "+code) ||
+			strings.Contains(text, "server returned "+code) ||
+			strings.Contains(text, "code="+code) ||
+			strings.Contains(text, "code: "+code) ||
+			strings.Contains(text, "error_code="+code) ||
+			strings.Contains(text, "error_code: "+code) {
+			return true
+		}
+	}
+	return false
+}
+
+func ErrorMentionsHTTPStatus(err error, statuses ...int) bool {
+	if err == nil {
+		return false
+	}
+	return TextMentionsHTTPStatus(err.Error(), statuses...)
+}

backend/internal/drives/iface_test.go

@@ -0,0 +1,24 @@
+package drives
+
+import "testing"
+
+func TestTextMentionsHTTPStatus(t *testing.T) {
+	tests := []struct {
+		name string
+		text string
+		want bool
+	}{
+		{name: "status context", text: "request failed with status: 429 Too Many Requests", want: true},
+		{name: "http context", text: "http 503 service unavailable", want: true},
+		{name: "server returned context", text: "Server returned 403 Forbidden", want: true},
+		{name: "message only", text: "操作频繁，请稍后重试", want: false},
+		{name: "unrelated number", text: "generated 429 bytes", want: false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := TextMentionsHTTPStatus(tc.text, 403, 429, 503); got != tc.want {
+				t.Fatalf("TextMentionsHTTPStatus(%q) = %v, want %v", tc.text, got, tc.want)
+			}
+		})
+	}
+}

backend/internal/drives/localstorage/driver.go

@@ -0,0 +1,453 @@
+// Package localstorage exposes an existing server-side directory as a Drive.
+package localstorage
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/video-site/backend/internal/drives"
+)
+
+const Kind = "localstorage"
+
+const maxSTRMBytes = 64 * 1024
+
+type Config struct {
+	ID       string
+	RootPath string
+	// STRMAllowOutsideRoot 允许 .strm 指向存储根目录之外的本地路径。
+	// 默认关闭：strm 等于可以让 /p/stream 读到服务器上的任意文件，只有
+	// 管理员明确知道自己在做什么（例如 strm 库与 rclone 挂载目录分离）
+	// 时才应打开。
+	STRMAllowOutsideRoot bool
+}
+
+type Driver struct {
+	id                   string
+	rootPath             string
+	strmAllowOutsideRoot bool
+}
+
+func New(c Config) *Driver {
+	return &Driver{
+		id:                   c.ID,
+		rootPath:             c.RootPath,
+		strmAllowOutsideRoot: c.STRMAllowOutsideRoot,
+	}
+}
+
+func (d *Driver) Kind() string { return Kind }
+
+func (d *Driver) ID() string { return d.id }
+
+func (d *Driver) RootID() string { return "/" }
+
+func (d *Driver) Init(context.Context) error {
+	root, err := d.root()
+	if err != nil {
+		return err
+	}
+	info, err := os.Stat(root)
+	if err != nil {
+		return fmt.Errorf("localstorage: stat root %q: %w%s", root, err, localStoragePathHint(d.rootPath))
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("localstorage: root is not a directory: %s", root)
+	}
+	return nil
+}
+
+func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error) {
+	dir, rel, err := d.pathForID(dirID)
+	if err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]drives.Entry, 0, len(entries))
+	for _, entry := range entries {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		// Symlinks can escape the configured root or create cycles. Keep the
+		// local storage drive predictable by scanning real files/directories only.
+		if entry.Type()&os.ModeSymlink != 0 {
+			continue
+		}
+		info, err := entry.Info()
+		if err != nil {
+			continue
+		}
+		if !info.IsDir() && !info.Mode().IsRegular() {
+			continue
+		}
+		childRel := joinRel(rel, entry.Name())
+		out = append(out, drives.Entry{
+			ID:       encodeRel(childRel),
+			Name:     entry.Name(),
+			Size:     sizeForEntry(info),
+			IsDir:    info.IsDir(),
+			ParentID: idForRel(rel),
+			ModTime:  info.ModTime(),
+		})
+	}
+	return out, nil
+}
+
+func (d *Driver) Stat(ctx context.Context, fileID string) (*drives.Entry, error) {
+	p, rel, err := d.pathForID(fileID)
+	if err != nil {
+		return nil, err
+	}
+	info, err := os.Stat(p)
+	if err != nil {
+		return nil, err
+	}
+	return &drives.Entry{
+		ID:       idForRel(rel),
+		Name:     filepath.Base(p),
+		Size:     sizeForEntry(info),
+		IsDir:    info.IsDir(),
+		ParentID: idForRel(parentRel(rel)),
+		ModTime:  info.ModTime(),
+	}, nil
+}
+
+func (d *Driver) StreamURL(ctx context.Context, fileID string) (*drives.StreamLink, error) {
+	p, _, err := d.pathForID(fileID)
+	if err != nil {
+		return nil, err
+	}
+	info, err := os.Stat(p)
+	if err != nil {
+		return nil, err
+	}
+	if info.IsDir() || !info.Mode().IsRegular() {
+		return nil, os.ErrNotExist
+	}
+	if strings.EqualFold(filepath.Ext(p), ".strm") {
+		return d.streamURLFromSTRM(ctx, p)
+	}
+	if info.Size() <= 0 {
+		return nil, os.ErrNotExist
+	}
+	return &drives.StreamLink{
+		URL:     p,
+		Expires: time.Now().Add(24 * time.Hour),
+	}, nil
+}
+
+func (d *Driver) streamURLFromSTRM(ctx context.Context, strmPath string) (*drives.StreamLink, error) {
+	target, err := readSTRMTarget(strmPath)
+	if err != nil {
+		return nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+
+	if filepath.IsAbs(target) {
+		return d.localSTRMLink(strmPath, target)
+	}
+	u, err := url.Parse(target)
+	if err == nil {
+		switch strings.ToLower(u.Scheme) {
+		case "http", "https":
+			if u.Host == "" {
+				return nil, fmt.Errorf("localstorage: invalid strm url %q", target)
+			}
+			return &drives.StreamLink{
+				URL:     target,
+				Expires: time.Now().Add(24 * time.Hour),
+			}, nil
+		case "file":
+			if u.Host != "" && !strings.EqualFold(u.Host, "localhost") {
+				return nil, fmt.Errorf("localstorage: unsupported strm file url host %q", u.Host)
+			}
+			return d.localSTRMLink(strmPath, u.Path)
+		case "":
+			// Local path below.
+		default:
+			return nil, fmt.Errorf("localstorage: unsupported strm target scheme %q", u.Scheme)
+		}
+	} else if strings.Contains(target, "://") {
+		return nil, fmt.Errorf("localstorage: invalid strm url %q: %w", target, err)
+	}
+	return d.localSTRMLink(strmPath, target)
+}
+
+func readSTRMTarget(path string) (string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+
+	data, err := io.ReadAll(io.LimitReader(f, maxSTRMBytes+1))
+	if err != nil {
+		return "", err
+	}
+	if len(data) > maxSTRMBytes {
+		return "", errors.New("localstorage: strm file is too large")
+	}
+	lines := strings.Split(string(data), "\n")
+	for i, line := range lines {
+		if i == 0 {
+			line = strings.TrimPrefix(line, "\ufeff")
+		}
+		line = strings.TrimSpace(line)
+		if line != "" {
+			return line, nil
+		}
+	}
+	return "", errors.New("localstorage: empty strm target")
+}
+
+func (d *Driver) localSTRMLink(strmPath, target string) (*drives.StreamLink, error) {
+	target = strings.TrimSpace(target)
+	if target == "" {
+		return nil, errors.New("localstorage: empty strm target")
+	}
+
+	var p string
+	if filepath.IsAbs(target) {
+		p = filepath.Clean(target)
+	} else {
+		p = filepath.Join(filepath.Dir(strmPath), filepath.FromSlash(target))
+	}
+	p, err := filepath.Abs(p)
+	if err != nil {
+		return nil, err
+	}
+	root, err := d.root()
+	if err != nil {
+		return nil, err
+	}
+	realPath, within, err := realPathWithinRoot(root, p)
+	if err != nil {
+		return nil, err
+	}
+	if !within && !d.strmAllowOutsideRoot {
+		return nil, errors.New("localstorage: strm target escapes root (enable strm_allow_outside_root to allow)")
+	}
+	if strings.EqualFold(filepath.Ext(p), ".strm") || strings.EqualFold(filepath.Ext(realPath), ".strm") {
+		return nil, errors.New("localstorage: nested strm target is not supported")
+	}
+	info, err := os.Stat(realPath)
+	if err != nil {
+		return nil, err
+	}
+	if info.IsDir() || !info.Mode().IsRegular() || info.Size() <= 0 {
+		return nil, os.ErrNotExist
+	}
+	return &drives.StreamLink{
+		URL:     realPath,
+		Expires: time.Now().Add(24 * time.Hour),
+	}, nil
+}
+
+func (d *Driver) Upload(context.Context, string, string, io.Reader, int64) (string, error) {
+	return "", drives.ErrNotSupported
+}
+
+func (d *Driver) EnsureDir(context.Context, string) (string, error) {
+	return "", drives.ErrNotSupported
+}
+
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	p, rel, err := d.pathForID(fileID)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	if rel == "" {
+		return errors.New("localstorage: refusing to remove root")
+	}
+	info, err := os.Stat(p)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	if info.IsDir() {
+		return errors.New("localstorage: refusing to remove directory")
+	}
+	if !info.Mode().IsRegular() {
+		return errors.New("localstorage: refusing to remove non-regular file")
+	}
+	if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func (d *Driver) root() (string, error) {
+	raw := strings.TrimSpace(d.rootPath)
+	if raw == "" {
+		return "", errors.New("localstorage: empty path")
+	}
+	raw = os.ExpandEnv(raw)
+	if strings.HasPrefix(raw, "~") {
+		if home, err := os.UserHomeDir(); err == nil && home != "" {
+			switch {
+			case raw == "~":
+				raw = home
+			case strings.HasPrefix(raw, "~/") || strings.HasPrefix(raw, `~\`):
+				raw = filepath.Join(home, raw[2:])
+			}
+		}
+	}
+	return filepath.Abs(raw)
+}
+
+var _ drives.Remover = (*Driver)(nil)
+
+func (d *Driver) pathForID(id string) (string, string, error) {
+	root, err := d.root()
+	if err != nil {
+		return "", "", err
+	}
+	rel, err := decodeRel(id)
+	if err != nil {
+		return "", "", err
+	}
+	if rel == "" {
+		return root, "", nil
+	}
+	p, err := filepath.Abs(filepath.Join(root, filepath.FromSlash(rel)))
+	if err != nil {
+		return "", "", err
+	}
+	if !pathWithinRoot(root, p) {
+		return "", "", errors.New("localstorage: path escapes root")
+	}
+	if _, within, err := realPathWithinRoot(root, p); err != nil {
+		return "", "", err
+	} else if !within {
+		return "", "", errors.New("localstorage: path escapes root")
+	}
+	return p, rel, nil
+}
+
+func pathWithinRoot(root, path string) bool {
+	rel, err := filepath.Rel(root, path)
+	if err != nil {
+		return false
+	}
+	return rel == "." || (rel != ".." && !strings.HasPrefix(rel, ".."+string(os.PathSeparator)))
+}
+
+func realPathWithinRoot(root, path string) (string, bool, error) {
+	realRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		return "", false, err
+	}
+	realRoot, err = filepath.Abs(realRoot)
+	if err != nil {
+		return "", false, err
+	}
+	realPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		return "", false, err
+	}
+	realPath, err = filepath.Abs(realPath)
+	if err != nil {
+		return "", false, err
+	}
+	return realPath, pathWithinRoot(realRoot, realPath), nil
+}
+
+func localStoragePathHint(configured string) string {
+	cwd, _ := os.Getwd()
+	parts := []string{}
+	if strings.TrimSpace(configured) != "" {
+		parts = append(parts, fmt.Sprintf("configured=%q", strings.TrimSpace(configured)))
+	}
+	if cwd != "" {
+		parts = append(parts, fmt.Sprintf("cwd=%q", cwd))
+	}
+	if _, err := os.Stat("/.dockerenv"); err == nil {
+		parts = append(parts, "docker=host paths must be bind-mounted into the container")
+	}
+	if len(parts) == 0 {
+		return ""
+	}
+	return " (" + strings.Join(parts, ", ") + ")"
+}
+
+func decodeRel(id string) (string, error) {
+	id = strings.TrimSpace(id)
+	if id == "" || id == "/" {
+		return "", nil
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(id)
+	if err != nil {
+		return "", fmt.Errorf("localstorage: invalid file id: %w", err)
+	}
+	rel := filepath.ToSlash(filepath.Clean(filepath.FromSlash(string(raw))))
+	if rel == "." {
+		return "", nil
+	}
+	if strings.HasPrefix(rel, "../") || rel == ".." || strings.HasPrefix(rel, "/") {
+		return "", errors.New("localstorage: invalid relative path")
+	}
+	return rel, nil
+}
+
+func encodeRel(rel string) string {
+	rel = filepath.ToSlash(filepath.Clean(filepath.FromSlash(rel)))
+	if rel == "." || rel == "" {
+		return "/"
+	}
+	return base64.RawURLEncoding.EncodeToString([]byte(rel))
+}
+
+func idForRel(rel string) string {
+	if rel == "" {
+		return "/"
+	}
+	return encodeRel(rel)
+}
+
+func joinRel(parent, name string) string {
+	if parent == "" {
+		return filepath.ToSlash(name)
+	}
+	return filepath.ToSlash(filepath.Join(filepath.FromSlash(parent), name))
+}
+
+func parentRel(rel string) string {
+	if rel == "" {
+		return ""
+	}
+	parent := filepath.ToSlash(filepath.Dir(filepath.FromSlash(rel)))
+	if parent == "." {
+		return ""
+	}
+	return parent
+}
+
+func sizeForEntry(info os.FileInfo) int64 {
+	if info == nil || info.IsDir() {
+		return 0
+	}
+	return info.Size()
+}
+
+var _ drives.Drive = (*Driver)(nil)

backend/internal/drives/localstorage/driver_test.go

@@ -0,0 +1,379 @@
+package localstorage
+
+import (
+	"context"
+	"encoding/base64"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/scanner"
+)
+
+func TestListEncodesRelativePathsAndStreamURLResolvesFile(t *testing.T) {
+	root := t.TempDir()
+	sub := filepath.Join(root, "clips")
+	if err := os.MkdirAll(sub, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	videoPath := filepath.Join(sub, "sample.mp4")
+	if err := os.WriteFile(videoPath, []byte("video"), 0o644); err != nil {
+		t.Fatalf("write video: %v", err)
+	}
+
+	drv := New(Config{ID: "local", RootPath: root})
+	if err := drv.Init(context.Background()); err != nil {
+		t.Fatalf("init: %v", err)
+	}
+	rootEntries, err := drv.List(context.Background(), drv.RootID())
+	if err != nil {
+		t.Fatalf("list root: %v", err)
+	}
+	if len(rootEntries) != 1 || !rootEntries[0].IsDir {
+		t.Fatalf("root entries = %#v, want one directory", rootEntries)
+	}
+	if strings.Contains(rootEntries[0].ID, "/") {
+		t.Fatalf("encoded dir id contains slash: %q", rootEntries[0].ID)
+	}
+
+	fileEntries, err := drv.List(context.Background(), rootEntries[0].ID)
+	if err != nil {
+		t.Fatalf("list subdir: %v", err)
+	}
+	if len(fileEntries) != 1 || fileEntries[0].Name != "sample.mp4" {
+		t.Fatalf("file entries = %#v, want sample.mp4", fileEntries)
+	}
+	if strings.Contains(fileEntries[0].ID, "/") {
+		t.Fatalf("encoded file id contains slash: %q", fileEntries[0].ID)
+	}
+
+	link, err := drv.StreamURL(context.Background(), fileEntries[0].ID)
+	if err != nil {
+		t.Fatalf("stream url: %v", err)
+	}
+	if link.URL != videoPath {
+		t.Fatalf("url = %q, want %q", link.URL, videoPath)
+	}
+}
+
+func TestStreamURLResolvesHTTPSTRM(t *testing.T) {
+	root := t.TempDir()
+	strmPath := filepath.Join(root, "movie.strm")
+	target := "https://media.example/clip.mp4?token=abc"
+	if err := os.WriteFile(strmPath, []byte("\ufeff\n  "+target+"\n"), 0o644); err != nil {
+		t.Fatalf("write strm: %v", err)
+	}
+	drv := New(Config{ID: "local", RootPath: root})
+
+	link, err := drv.StreamURL(context.Background(), encodeRel("movie.strm"))
+	if err != nil {
+		t.Fatalf("stream url: %v", err)
+	}
+	if link.URL != target {
+		t.Fatalf("url = %q, want %q", link.URL, target)
+	}
+}
+
+func TestStreamURLResolvesRelativeLocalSTRM(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "links"), 0o755); err != nil {
+		t.Fatalf("mkdir links: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "media"), 0o755); err != nil {
+		t.Fatalf("mkdir media: %v", err)
+	}
+	videoPath := filepath.Join(root, "media", "clip.mp4")
+	if err := os.WriteFile(videoPath, []byte("video"), 0o644); err != nil {
+		t.Fatalf("write video: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "links", "movie.strm"), []byte("../media/clip.mp4\n"), 0o644); err != nil {
+		t.Fatalf("write strm: %v", err)
+	}
+	drv := New(Config{ID: "local", RootPath: root})
+
+	link, err := drv.StreamURL(context.Background(), encodeRel("links/movie.strm"))
+	if err != nil {
+		t.Fatalf("stream url: %v", err)
+	}
+	if link.URL != videoPath {
+		t.Fatalf("url = %q, want %q", link.URL, videoPath)
+	}
+}
+
+func TestStreamURLRejectsInvalidSTRMTargets(t *testing.T) {
+	tests := []struct {
+		name  string
+		setup func(t *testing.T, root string) string
+		want  string
+	}{
+		{
+			name: "empty",
+			setup: func(t *testing.T, root string) string {
+				t.Helper()
+				writeLocalStorageTestFile(t, filepath.Join(root, "empty.strm"), []byte("\n  \r\n"))
+				return "empty.strm"
+			},
+			want: "empty strm target",
+		},
+		{
+			name: "escapes root",
+			setup: func(t *testing.T, root string) string {
+				t.Helper()
+				writeLocalStorageTestFile(t, filepath.Join(filepath.Dir(root), "outside.mp4"), []byte("video"))
+				writeLocalStorageTestFile(t, filepath.Join(root, "escape.strm"), []byte("../outside.mp4\n"))
+				return "escape.strm"
+			},
+			want: "escapes root",
+		},
+		{
+			name: "nested",
+			setup: func(t *testing.T, root string) string {
+				t.Helper()
+				writeLocalStorageTestFile(t, filepath.Join(root, "nested.strm"), []byte("https://media.example/clip.mp4\n"))
+				writeLocalStorageTestFile(t, filepath.Join(root, "outer.strm"), []byte("nested.strm\n"))
+				return "outer.strm"
+			},
+			want: "nested strm target",
+		},
+		{
+			name: "unsupported scheme",
+			setup: func(t *testing.T, root string) string {
+				t.Helper()
+				writeLocalStorageTestFile(t, filepath.Join(root, "ftp.strm"), []byte("ftp://media.example/clip.mp4\n"))
+				return "ftp.strm"
+			},
+			want: "unsupported strm target scheme",
+		},
+		{
+			name: "too large",
+			setup: func(t *testing.T, root string) string {
+				t.Helper()
+				writeLocalStorageTestFile(t, filepath.Join(root, "large.strm"), []byte(strings.Repeat("x", maxSTRMBytes+1)))
+				return "large.strm"
+			},
+			want: "strm file is too large",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			root := t.TempDir()
+			rel := tt.setup(t, root)
+			drv := New(Config{ID: "local", RootPath: root})
+
+			_, err := drv.StreamURL(context.Background(), encodeRel(rel))
+
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("error = %v, want contain %q", err, tt.want)
+			}
+		})
+	}
+}
+
+func TestStreamURLRejectsSTRMTargetEscapingRootThroughSymlink(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	writeLocalStorageTestFile(t, filepath.Join(outside, "secret.mp4"), []byte("secret"))
+	if err := os.MkdirAll(filepath.Join(root, "links"), 0o755); err != nil {
+		t.Fatalf("mkdir links: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "real"), 0o755); err != nil {
+		t.Fatalf("mkdir real: %v", err)
+	}
+	if err := os.Symlink(outside, filepath.Join(root, "real", "outside")); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	writeLocalStorageTestFile(t, filepath.Join(root, "links", "movie.strm"), []byte("../real/outside/secret.mp4\n"))
+	drv := New(Config{ID: "local", RootPath: root})
+
+	_, err := drv.StreamURL(context.Background(), encodeRel("links/movie.strm"))
+
+	if err == nil || !strings.Contains(err.Error(), "strm target escapes root") {
+		t.Fatalf("error = %v, want strm target escapes root", err)
+	}
+}
+
+func TestStreamURLAllowsSTRMTargetOutsideRootWhenEnabled(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	target := filepath.Join(outside, "movie.mp4")
+	writeLocalStorageTestFile(t, target, []byte("movie-data"))
+	writeLocalStorageTestFile(t, filepath.Join(root, "movie.strm"), []byte(target+"\n"))
+
+	// 默认关闭：根目录外的目标仍被拒绝
+	strict := New(Config{ID: "local", RootPath: root})
+	if _, err := strict.StreamURL(context.Background(), encodeRel("movie.strm")); err == nil || !strings.Contains(err.Error(), "strm target escapes root") {
+		t.Fatalf("default error = %v, want strm target escapes root", err)
+	}
+
+	// 开启 strm_allow_outside_root 后放行
+	relaxed := New(Config{ID: "local", RootPath: root, STRMAllowOutsideRoot: true})
+	link, err := relaxed.StreamURL(context.Background(), encodeRel("movie.strm"))
+	if err != nil {
+		t.Fatalf("StreamURL with allow-outside-root: %v", err)
+	}
+	resolved, err := filepath.EvalSymlinks(target)
+	if err != nil {
+		t.Fatalf("eval target: %v", err)
+	}
+	if link.URL != resolved {
+		t.Fatalf("link url = %q, want %q", link.URL, resolved)
+	}
+}
+
+func TestStreamURLAllowOutsideRootStillRejectsNestedSTRM(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	writeLocalStorageTestFile(t, filepath.Join(outside, "inner.strm"), []byte("http://example.com/v.mp4\n"))
+	writeLocalStorageTestFile(t, filepath.Join(root, "movie.strm"), []byte(filepath.Join(outside, "inner.strm")+"\n"))
+
+	drv := New(Config{ID: "local", RootPath: root, STRMAllowOutsideRoot: true})
+	if _, err := drv.StreamURL(context.Background(), encodeRel("movie.strm")); err == nil || !strings.Contains(err.Error(), "nested strm") {
+		t.Fatalf("error = %v, want nested strm rejection", err)
+	}
+}
+
+func TestStreamURLRejectsSymlinkFileIDEscapingRoot(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	writeLocalStorageTestFile(t, filepath.Join(outside, "secret.mp4"), []byte("secret"))
+	if err := os.Symlink(filepath.Join(outside, "secret.mp4"), filepath.Join(root, "link.mp4")); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	drv := New(Config{ID: "local", RootPath: root})
+
+	_, err := drv.StreamURL(context.Background(), encodeRel("link.mp4"))
+
+	if err == nil || !strings.Contains(err.Error(), "path escapes root") {
+		t.Fatalf("error = %v, want path escapes root", err)
+	}
+}
+
+func TestStreamURLRejectsEscapingID(t *testing.T) {
+	drv := New(Config{ID: "local", RootPath: t.TempDir()})
+	escaped := base64.RawURLEncoding.EncodeToString([]byte("../secret.mp4"))
+
+	_, err := drv.StreamURL(context.Background(), escaped)
+
+	if err == nil || !strings.Contains(err.Error(), "invalid relative path") {
+		t.Fatalf("error = %v, want invalid relative path", err)
+	}
+}
+
+func TestInitRequiresExistingDirectory(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "missing")
+	drv := New(Config{ID: "local", RootPath: missing})
+
+	err := drv.Init(context.Background())
+
+	if err == nil || !strings.Contains(err.Error(), "stat root") {
+		t.Fatalf("error = %v, want stat root failure", err)
+	}
+	if !strings.Contains(err.Error(), missing) || !strings.Contains(err.Error(), "configured=") {
+		t.Fatalf("error = %v, want diagnostic path details", err)
+	}
+}
+
+func TestPathForIDAllowsRootPathSlash(t *testing.T) {
+	drv := New(Config{ID: "local", RootPath: string(os.PathSeparator)})
+	childID := encodeRel("tmp")
+
+	path, rel, err := drv.pathForID(childID)
+
+	if err != nil {
+		t.Fatalf("pathForID: %v", err)
+	}
+	if rel != "tmp" {
+		t.Fatalf("rel = %q, want tmp", rel)
+	}
+	if path != filepath.Join(string(os.PathSeparator), "tmp") {
+		t.Fatalf("path = %q, want /tmp", path)
+	}
+}
+
+func TestScannerPersistsLocalStorageSTRM(t *testing.T) {
+	ctx := context.Background()
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "collection"), 0o755); err != nil {
+		t.Fatalf("mkdir collection: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "collection", "clip.strm"), []byte("https://media.example/clip.mp4\n"), 0o644); err != nil {
+		t.Fatalf("write strm: %v", err)
+	}
+	cat, err := catalog.Open(filepath.Join(t.TempDir(), "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	drv := New(Config{ID: "local", RootPath: root})
+	sc := scanner.New(cat, drv, []string{".strm"}, nil, nil)
+	stats, err := sc.Run(ctx, drv.RootID())
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if stats.Added != 1 {
+		t.Fatalf("added = %d, want 1", stats.Added)
+	}
+
+	fileID := encodeRel("collection/clip.strm")
+	got, err := cat.GetVideo(ctx, Kind+"-local-"+fileID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.Ext != "strm" || got.FileID != fileID || got.ParentID != encodeRel("collection") {
+		t.Fatalf("video = %#v, want local strm video under collection", got)
+	}
+}
+
+func TestScannerPersistsLocalStorageVideo(t *testing.T) {
+	ctx := context.Background()
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "collection"), 0o755); err != nil {
+		t.Fatalf("mkdir collection: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "collection", "clip.mp4"), []byte("video"), 0o644); err != nil {
+		t.Fatalf("write video: %v", err)
+	}
+	cat, err := catalog.Open(filepath.Join(t.TempDir(), "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	drv := New(Config{ID: "local", RootPath: root})
+	sc := scanner.New(cat, drv, []string{".mp4"}, nil, nil)
+	stats, err := sc.Run(ctx, drv.RootID())
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if stats.Added != 1 {
+		t.Fatalf("added = %d, want 1", stats.Added)
+	}
+
+	fileID := encodeRel("collection/clip.mp4")
+	got, err := cat.GetVideo(ctx, Kind+"-local-"+fileID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.DriveID != "local" || got.FileID != fileID || got.ParentID != encodeRel("collection") {
+		t.Fatalf("video = %#v, want local drive video under collection", got)
+	}
+}
+
+func writeLocalStorageTestFile(t *testing.T, path string, data []byte) {
+	t.Helper()
+	if err := os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}

backend/internal/drives/localupload/driver.go

@@ -78,12 +78,38 @@ func (d *Driver) EnsureDir(context.Context, string) (string, error) {
 	return "", drives.ErrNotSupported
 }
 
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	path, err := d.uploadPath(fileID)
+	if err != nil {
+		return err
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	if info.IsDir() {
+		return errors.New("localupload: refusing to remove directory")
+	}
+	if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
 func (d *Driver) RootID() string { return d.uploadDir() }
 
 func (d *Driver) uploadDir() string {
 	return d.uploadDirPath
 }
 
+var _ drives.Remover = (*Driver)(nil)
+
 func (d *Driver) uploadPath(fileID string) (string, error) {
 	if strings.TrimSpace(fileID) == "" || filepath.Base(fileID) != fileID {
 		return "", errors.New("invalid upload file id")

backend/internal/drives/onedrive/driver.go

@@ -3,14 +3,19 @@ package onedrive
 import (
 	"bytes"
 	"context"
+	"crypto/sha1"
+	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
+	"log"
 	"net/http"
 	"net/url"
 	"path"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/go-resty/resty/v2"
@@ -18,8 +23,17 @@ import (
 )
 
 const (
-	maxSmallUploadSize = 250 * 1024 * 1024
-	defaultRenewAPIURL = "https://api.oplist.org/onedrive/renewapi"
+	maxSmallUploadSize         = 250 * 1024 * 1024
+	defaultUploadSessionChunk  = 10 * 1024 * 1024
+	uploadSessionRetryAttempts = 3
+	defaultRenewAPIURL         = "https://api.oplist.org/onedrive/renewapi"
+	onedriveListCooldown       = 5 * time.Minute
+	onedriveListInterval       = 1 * time.Second
+)
+
+var (
+	smallUploadThreshold = int64(maxSmallUploadSize)
+	uploadSessionChunk   = int64(defaultUploadSessionChunk)
 )
 
 type Driver struct {
@@ -34,6 +48,11 @@ type Driver struct {
 	renewAPIURL   string
 	client        *resty.Client
 	onTokenUpdate func(access, refresh string)
+
+	listMu       sync.Mutex
+	lastListAt   time.Time
+	listInterval time.Duration
+	listCooldown time.Duration
 }
 
 type Config struct {
@@ -85,6 +104,8 @@ func New(c Config) *Driver {
 		client: resty.New().
 			SetTimeout(30*time.Second).
 			SetHeader("Accept", "application/json, text/plain, */*"),
+		listInterval: onedriveListInterval,
+		listCooldown: onedriveListCooldown,
 	}
 }
 
@@ -106,10 +127,16 @@ func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error)
 	if dirID == "" {
 		dirID = d.rootID
 	}
+	d.listMu.Lock()
+	defer d.listMu.Unlock()
+
 	nextLink := d.childrenURL(dirID)
 	first := true
 	out := make([]drives.Entry, 0)
 	for nextLink != "" {
+		if err := d.waitForListSlotLocked(ctx); err != nil {
+			return nil, err
+		}
 		var resp filesResp
 		err := d.request(ctx, nextLink, http.MethodGet, func(req *resty.Request) {
 			if first {
@@ -120,6 +147,19 @@ func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error)
 			}
 		}, &resp)
 		if err != nil {
+			if wait, ok := drives.RateLimitRetryAfter(err); ok {
+				if wait <= 0 {
+					wait = d.listCooldown
+					if wait <= 0 {
+						wait = onedriveListCooldown
+					}
+				}
+				log.Printf("[onedrive] list cooling down drive=%s dir=%s cooldown=%s err=%v", d.id, dirID, wait, err)
+				if err := sleepContext(ctx, wait); err != nil {
+					return nil, err
+				}
+				continue
+			}
 			return nil, fmt.Errorf("onedrive list: %w", err)
 		}
 		for _, item := range resp.Value {
@@ -131,6 +171,36 @@ func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error)
 	return out, nil
 }
 
+func (d *Driver) waitForListSlotLocked(ctx context.Context) error {
+	if d.listInterval <= 0 || d.lastListAt.IsZero() {
+		d.lastListAt = time.Now()
+		return ctx.Err()
+	}
+	next := d.lastListAt.Add(d.listInterval)
+	now := time.Now()
+	if now.Before(next) {
+		if err := sleepContext(ctx, next.Sub(now)); err != nil {
+			return err
+		}
+	}
+	d.lastListAt = time.Now()
+	return ctx.Err()
+}
+
+func sleepContext(ctx context.Context, d time.Duration) error {
+	if d <= 0 {
+		return ctx.Err()
+	}
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
 func (d *Driver) Stat(ctx context.Context, fileID string) (*drives.Entry, error) {
 	var item graphItem
 	if err := d.request(ctx, d.itemURL(fileID), http.MethodGet, nil, &item); err != nil {
@@ -156,15 +226,49 @@ func (d *Driver) StreamURL(ctx context.Context, fileID string) (*drives.StreamLi
 }
 
 func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error) {
+	res, err := d.UploadAndReportHash(ctx, parentID, name, r, size)
+	if err != nil {
+		return "", err
+	}
+	return res.FileID, nil
+}
+
+func (d *Driver) UploadAndReportHash(ctx context.Context, parentID, name string, r io.Reader, size int64) (UploadResult, error) {
+	parentID, name, err := d.normalizeUploadArgs(parentID, name, r, size)
+	if err != nil {
+		return UploadResult{}, err
+	}
+	threshold := smallUploadThreshold
+	if threshold <= 0 {
+		threshold = maxSmallUploadSize
+	}
+	if size <= threshold {
+		return d.uploadSmallAndReportHash(ctx, parentID, name, r, size, threshold)
+	}
+	return d.uploadSessionAndReportHash(ctx, parentID, name, r, size)
+}
+
+func (d *Driver) normalizeUploadArgs(parentID, name string, r io.Reader, size int64) (string, string, error) {
+	if r == nil {
+		return "", "", errors.New("onedrive upload: body is required")
+	}
+	if size < 0 {
+		return "", "", fmt.Errorf("onedrive upload: invalid size %d", size)
+	}
 	if parentID == "" {
 		parentID = d.rootID
 	}
-	if size > maxSmallUploadSize {
-		return "", fmt.Errorf("onedrive upload: files over %d bytes require upload session", maxSmallUploadSize)
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return "", "", errors.New("onedrive upload: empty file name")
 	}
-	data, err := readSmallUpload(r)
+	return parentID, name, nil
+}
+
+func (d *Driver) uploadSmallAndReportHash(ctx context.Context, parentID, name string, r io.Reader, size, limit int64) (UploadResult, error) {
+	data, hash, actualSize, err := readSmallUpload(r, size, limit)
 	if err != nil {
-		return "", err
+		return UploadResult{}, err
 	}
 	u := fmt.Sprintf("%s/items/%s:/%s:/content", d.driveBaseURL(), url.PathEscape(parentID), url.PathEscape(name))
 	var item graphItem
@@ -173,26 +277,159 @@ func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader,
 		req.SetContentLength(true)
 	}, &item)
 	if err != nil {
-		return "", fmt.Errorf("onedrive upload: %w", err)
+		return UploadResult{}, fmt.Errorf("onedrive upload: %w", err)
 	}
 	if item.ID == "" {
-		return "", errors.New("onedrive upload: empty item id")
+		return UploadResult{}, errors.New("onedrive upload: empty item id")
 	}
-	return item.ID, nil
+	return UploadResult{FileID: item.ID, Hash: hash, Size: actualSize}, nil
 }
 
-func readSmallUpload(r io.Reader) ([]byte, error) {
-	if r == nil {
-		return nil, errors.New("onedrive upload: body is required")
-	}
-	data, err := io.ReadAll(io.LimitReader(r, maxSmallUploadSize+1))
+func (d *Driver) uploadSessionAndReportHash(ctx context.Context, parentID, name string, r io.Reader, size int64) (UploadResult, error) {
+	session, err := d.createUploadSession(ctx, parentID, name)
 	if err != nil {
-		return nil, fmt.Errorf("onedrive upload: read body: %w", err)
+		return UploadResult{}, err
 	}
-	if len(data) > maxSmallUploadSize {
-		return nil, fmt.Errorf("onedrive upload: files over %d bytes require upload session", maxSmallUploadSize)
+	if strings.TrimSpace(session.UploadURL) == "" {
+		return UploadResult{}, errors.New("onedrive upload session: empty upload url")
 	}
-	return data, nil
+
+	chunkSize := uploadSessionChunk
+	if chunkSize <= 0 {
+		chunkSize = defaultUploadSessionChunk
+	}
+	buf := make([]byte, int(chunkSize))
+	hasher := sha1.New()
+	var finalItem graphItem
+	var offset int64
+	for offset < size {
+		partSize := minInt64(chunkSize, size-offset)
+		chunk := buf[:int(partSize)]
+		n, err := io.ReadFull(r, chunk)
+		if err != nil {
+			if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
+				return UploadResult{}, fmt.Errorf("onedrive upload: size mismatch: declared %d, copied %d", size, offset+int64(n))
+			}
+			return UploadResult{}, fmt.Errorf("onedrive upload: read body: %w", err)
+		}
+		chunk = chunk[:n]
+		_, _ = hasher.Write(chunk)
+		item, err := d.putUploadSessionChunkWithRetry(ctx, session.UploadURL, offset, size, chunk)
+		if err != nil {
+			return UploadResult{}, err
+		}
+		if item != nil {
+			finalItem = *item
+		}
+		offset += int64(n)
+	}
+	if finalItem.ID == "" {
+		return UploadResult{}, errors.New("onedrive upload session: empty item id")
+	}
+	return UploadResult{
+		FileID: finalItem.ID,
+		Hash:   hex.EncodeToString(hasher.Sum(nil)),
+		Size:   offset,
+	}, nil
+}
+
+func (d *Driver) createUploadSession(ctx context.Context, parentID, name string) (uploadSessionResp, error) {
+	u := fmt.Sprintf("%s/items/%s:/%s:/createUploadSession", d.driveBaseURL(), url.PathEscape(parentID), url.PathEscape(name))
+	body := map[string]any{
+		"item": map[string]any{
+			"@microsoft.graph.conflictBehavior": "rename",
+		},
+	}
+	var out uploadSessionResp
+	err := d.request(ctx, u, http.MethodPost, func(req *resty.Request) {
+		req.SetBody(body)
+	}, &out)
+	if err != nil {
+		return uploadSessionResp{}, fmt.Errorf("onedrive upload session: %w", err)
+	}
+	return out, nil
+}
+
+func (d *Driver) putUploadSessionChunkWithRetry(ctx context.Context, uploadURL string, start, total int64, data []byte) (*graphItem, error) {
+	var last error
+	for attempt := 0; attempt < uploadSessionRetryAttempts; attempt++ {
+		if attempt > 0 {
+			if err := sleepContext(ctx, time.Duration(attempt)*time.Second); err != nil {
+				return nil, err
+			}
+		}
+		item, retryable, err := d.putUploadSessionChunk(ctx, uploadURL, start, total, data)
+		if err == nil {
+			return item, nil
+		}
+		last = err
+		if !retryable {
+			return nil, err
+		}
+	}
+	if last == nil {
+		last = errors.New("onedrive upload session: retry attempts exhausted")
+	}
+	return nil, last
+}
+
+func (d *Driver) putUploadSessionChunk(ctx context.Context, uploadURL string, start, total int64, data []byte) (*graphItem, bool, error) {
+	end := start + int64(len(data)) - 1
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, uploadURL, bytes.NewReader(data))
+	if err != nil {
+		return nil, false, err
+	}
+	req.ContentLength = int64(len(data))
+	req.Header.Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, end, total))
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, true, err
+	}
+	defer res.Body.Close()
+
+	switch res.StatusCode {
+	case http.StatusOK, http.StatusCreated:
+		var item graphItem
+		if err := json.NewDecoder(res.Body).Decode(&item); err != nil {
+			return nil, false, fmt.Errorf("onedrive upload session: decode completed item: %w", err)
+		}
+		return &item, false, nil
+	case http.StatusAccepted:
+		return nil, false, nil
+	default:
+		body, _ := io.ReadAll(io.LimitReader(res.Body, 4096))
+		err := fmt.Errorf("onedrive upload session: status=%d body=%s", res.StatusCode, strings.TrimSpace(string(body)))
+		retryable := res.StatusCode == http.StatusTooManyRequests || (res.StatusCode >= 500 && res.StatusCode <= 504)
+		return nil, retryable, err
+	}
+}
+
+func readSmallUpload(r io.Reader, declaredSize, limit int64) ([]byte, string, int64, error) {
+	if r == nil {
+		return nil, "", 0, errors.New("onedrive upload: body is required")
+	}
+	if limit <= 0 {
+		limit = maxSmallUploadSize
+	}
+	data, err := io.ReadAll(io.LimitReader(r, limit+1))
+	if err != nil {
+		return nil, "", 0, fmt.Errorf("onedrive upload: read body: %w", err)
+	}
+	if int64(len(data)) > limit {
+		return nil, "", 0, fmt.Errorf("onedrive upload: files over %d bytes require upload session", limit)
+	}
+	if declaredSize >= 0 && int64(len(data)) != declaredSize {
+		return nil, "", 0, fmt.Errorf("onedrive upload: size mismatch: declared %d, copied %d", declaredSize, len(data))
+	}
+	sum := sha1.Sum(data)
+	return data, hex.EncodeToString(sum[:]), int64(len(data)), nil
+}
+
+func minInt64(a, b int64) int64 {
+	if a < b {
+		return a
+	}
+	return b
 }
 
 func (d *Driver) EnsureDir(ctx context.Context, pathFromRoot string) (string, error) {
@@ -245,6 +482,36 @@ func (d *Driver) makeDir(ctx context.Context, parentID, name string) (string, er
 	return item.ID, nil
 }
 
+func (d *Driver) Rename(ctx context.Context, fileID, newName string) error {
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return errors.New("onedrive rename: empty file id")
+	}
+	newName = strings.TrimSpace(newName)
+	if newName == "" {
+		return errors.New("onedrive rename: empty new name")
+	}
+	var item graphItem
+	err := d.request(ctx, d.itemURL(fileID), http.MethodPatch, func(req *resty.Request) {
+		req.SetBody(map[string]string{"name": newName})
+	}, &item)
+	if err != nil {
+		return fmt.Errorf("onedrive rename: %w", err)
+	}
+	return nil
+}
+
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return errors.New("onedrive remove: empty file id")
+	}
+	if err := d.request(ctx, d.itemURL(fileID), http.MethodDelete, nil, nil); err != nil {
+		return fmt.Errorf("onedrive remove: %w", err)
+	}
+	return nil
+}
+
 func (d *Driver) request(ctx context.Context, rawURL, method string, configure func(*resty.Request), out any) error {
 	return d.requestOnce(ctx, rawURL, method, configure, out, true)
 }
@@ -265,7 +532,7 @@ func (d *Driver) requestOnce(ctx context.Context, rawURL, method string, configu
 	if err != nil {
 		return err
 	}
-	if isRateLimitResponse(res, graphErr.Error.Code) {
+	if isRateLimitResponse(res, graphErr.Error.Code, graphErr.Error.Message) {
 		return onedriveRateLimitError(res, graphErr.Error.Message)
 	}
 	if graphErr.Error.Code != "" {
@@ -327,11 +594,42 @@ func (d *Driver) refresh(ctx context.Context) error {
 	return nil
 }
 
-func isRateLimitResponse(res *resty.Response, code string) bool {
-	if code == "TooManyRequests" || code == "activityLimitReached" {
+func isRateLimitResponse(res *resty.Response, code, _ string) bool {
+	if isRateLimitCode(code) {
 		return true
 	}
-	return res != nil && res.StatusCode() == http.StatusTooManyRequests
+	if res == nil {
+		return false
+	}
+	if res.StatusCode() == http.StatusTooManyRequests {
+		return true
+	}
+	if res.Header().Get("Retry-After") == "" {
+		return false
+	}
+	switch res.StatusCode() {
+	case http.StatusServiceUnavailable, http.StatusGatewayTimeout:
+		return true
+	default:
+		return false
+	}
+}
+
+func isRateLimitCode(code string) bool {
+	normalized := strings.ToLower(strings.ReplaceAll(strings.TrimSpace(code), "_", ""))
+	normalized = strings.ReplaceAll(normalized, "-", "")
+	switch normalized {
+	case "toomanyrequests",
+		"activitylimitreached",
+		"throttledrequest",
+		"requestthrottled",
+		"resourcethrottled",
+		"applicationthrottled",
+		"tenantthrottled":
+		return true
+	default:
+		return false
+	}
 }
 
 func onedriveRateLimitError(res *resty.Response, message string) error {
@@ -442,3 +740,4 @@ func guessMime(name string) string {
 }
 
 var _ drives.Drive = (*Driver)(nil)
+var _ drives.Remover = (*Driver)(nil)

backend/internal/drives/onedrive/driver_test.go

@@ -2,6 +2,8 @@ package onedrive
 
 import (
 	"context"
+	"crypto/sha1"
+	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"io"
@@ -199,7 +201,7 @@ func TestGraph429ReturnsRateLimitErrorWithRetryAfter(t *testing.T) {
 		APIBaseURL:   srv.URL,
 	})
 
-	_, err := d.List(context.Background(), "root")
+	_, err := d.StreamURL(context.Background(), "file-id")
 	if err == nil {
 		t.Fatal("list succeeded, want rate limit error")
 	}
@@ -212,6 +214,92 @@ func TestGraph429ReturnsRateLimitErrorWithRetryAfter(t *testing.T) {
 	}
 }
 
+func TestGraphThrottleMessageDoesNotReturnRateLimitError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusForbidden)
+		if err := json.NewEncoder(w).Encode(map[string]any{
+			"error": map[string]any{
+				"code":    "generalException",
+				"message": "The request has been throttled. Please try again later.",
+			},
+		}); err != nil {
+			t.Fatalf("write json: %v", err)
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:           "od-main",
+		AccessToken:  "access-token",
+		RefreshToken: "refresh-token",
+		APIBaseURL:   srv.URL,
+	})
+
+	_, err := d.StreamURL(context.Background(), "file-id")
+	if err == nil {
+		t.Fatal("list succeeded, want graph error")
+	}
+	var rateLimit *drives.RateLimitError
+	if errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want non-rate-limit error", err)
+	}
+}
+
+func TestListCoolsDownAndRetriesOneDriveRateLimit(t *testing.T) {
+	var calls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1.0/me/drive/items/root/children" {
+			t.Fatalf("unexpected request %s %s", r.Method, r.URL.String())
+		}
+		calls++
+		if calls == 1 {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusTooManyRequests)
+			if err := json.NewEncoder(w).Encode(map[string]any{
+				"error": map[string]any{
+					"code":    "TooManyRequests",
+					"message": "throttled",
+				},
+			}); err != nil {
+				t.Fatalf("write json: %v", err)
+			}
+			return
+		}
+		writeJSON(t, w, map[string]any{
+			"value": []map[string]any{
+				{
+					"id":   "file-id",
+					"name": "demo.mp4",
+					"size": 100,
+					"file": map[string]any{"mimeType": "video/mp4"},
+				},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:           "od-main",
+		AccessToken:  "access-token",
+		RefreshToken: "refresh-token",
+		APIBaseURL:   srv.URL,
+	})
+	d.listInterval = 0
+	d.listCooldown = time.Millisecond
+
+	got, err := d.List(context.Background(), "root")
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if calls != 2 {
+		t.Fatalf("calls = %d, want retry after rate limit", calls)
+	}
+	if len(got) != 1 || got[0].ID != "file-id" {
+		t.Fatalf("entries = %#v, want retried file", got)
+	}
+}
+
 func TestStatAndStreamURLUseDriveItemMetadata(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("Authorization"); got != "Bearer access-token" {
@@ -320,6 +408,36 @@ func TestEnsureDirCreatesMissingFolders(t *testing.T) {
 	}
 }
 
+func TestRenamePatchesDriveItemName(t *testing.T) {
+	var body map[string]string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPatch || r.URL.EscapedPath() != "/v1.0/me/drive/items/file-id" {
+			t.Fatalf("unexpected request %s %s", r.Method, r.URL.String())
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer access-token" {
+			t.Fatalf("authorization = %q, want bearer token", got)
+		}
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Fatalf("decode body: %v", err)
+		}
+		writeJSON(t, w, map[string]any{"id": "file-id", "name": "new name.mp4"})
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:           "od-main",
+		AccessToken:  "access-token",
+		RefreshToken: "refresh-token",
+		APIBaseURL:   srv.URL,
+	})
+	if err := d.Rename(context.Background(), "file-id", "new name.mp4"); err != nil {
+		t.Fatalf("rename: %v", err)
+	}
+	if body["name"] != "new name.mp4" {
+		t.Fatalf("rename body = %#v, want new name", body)
+	}
+}
+
 func TestUploadSmallFileReturnsNewItemID(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("Authorization"); got != "Bearer access-token" {
@@ -358,6 +476,86 @@ func TestUploadSmallFileReturnsNewItemID(t *testing.T) {
 	}
 }
 
+func TestUploadLargeFileUsesUploadSessionAndReportsHash(t *testing.T) {
+	oldThreshold := smallUploadThreshold
+	oldChunk := uploadSessionChunk
+	smallUploadThreshold = 8
+	uploadSessionChunk = 4
+	t.Cleanup(func() {
+		smallUploadThreshold = oldThreshold
+		uploadSessionChunk = oldChunk
+	})
+
+	body := "0123456789abc"
+	var ranges []string
+	var chunks []string
+	var createdSession bool
+	var srv *httptest.Server
+	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodPost && r.URL.EscapedPath() == "/v1.0/me/drive/items/parent-id:/big.mp4:/createUploadSession":
+			createdSession = true
+			if got := r.Header.Get("Authorization"); got != "Bearer access-token" {
+				t.Fatalf("authorization = %q, want bearer token", got)
+			}
+			writeJSON(t, w, map[string]any{"uploadUrl": srv.URL + "/upload-session"})
+		case r.Method == http.MethodPut && r.URL.Path == "/upload-session":
+			ranges = append(ranges, r.Header.Get("Content-Range"))
+			data, err := io.ReadAll(r.Body)
+			if err != nil {
+				t.Fatalf("read chunk: %v", err)
+			}
+			chunks = append(chunks, string(data))
+			if len(ranges) < 4 {
+				w.Header().Set("Content-Type", "application/json")
+				w.WriteHeader(http.StatusAccepted)
+				if _, err := w.Write([]byte(`{"nextExpectedRanges":["0-"]}`)); err != nil {
+					t.Fatalf("write accepted: %v", err)
+				}
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusCreated)
+			if err := json.NewEncoder(w).Encode(map[string]any{"id": "uploaded-big-id"}); err != nil {
+				t.Fatalf("write final item: %v", err)
+			}
+		default:
+			t.Fatalf("unexpected request %s %s", r.Method, r.URL.String())
+		}
+	}))
+	defer srv.Close()
+
+	d := New(Config{
+		ID:           "od-main",
+		AccessToken:  "access-token",
+		RefreshToken: "refresh-token",
+		APIBaseURL:   srv.URL,
+	})
+	got, err := d.UploadAndReportHash(context.Background(), "parent-id", "big.mp4", strings.NewReader(body), int64(len(body)))
+	if err != nil {
+		t.Fatalf("upload: %v", err)
+	}
+	if !createdSession {
+		t.Fatal("createUploadSession was not called")
+	}
+	wantRanges := []string{
+		"bytes 0-3/13",
+		"bytes 4-7/13",
+		"bytes 8-11/13",
+		"bytes 12-12/13",
+	}
+	if strings.Join(ranges, "|") != strings.Join(wantRanges, "|") {
+		t.Fatalf("ranges = %#v, want %#v", ranges, wantRanges)
+	}
+	if strings.Join(chunks, "") != body {
+		t.Fatalf("uploaded chunks = %q, want %q", strings.Join(chunks, ""), body)
+	}
+	sum := sha1.Sum([]byte(body))
+	if got.FileID != "uploaded-big-id" || got.Size != int64(len(body)) || got.Hash != hex.EncodeToString(sum[:]) {
+		t.Fatalf("upload result = %#v, want file id/hash/size for body", got)
+	}
+}
+
 func TestUploadRefreshesExpiredTokenAndReplaysBody(t *testing.T) {
 	var uploadAttempts int
 	var tokenRefreshes int

backend/internal/drives/onedrive/types.go

@@ -82,3 +82,13 @@ type filesResp struct {
 	Value    []graphItem `json:"value"`
 	NextLink string      `json:"@odata.nextLink"`
 }
+
+type UploadResult struct {
+	FileID string
+	Hash   string
+	Size   int64
+}
+
+type uploadSessionResp struct {
+	UploadURL string `json:"uploadUrl"`
+}

backend/internal/drives/p115/driver.go

@@ -20,11 +20,12 @@ import (
 )
 
 type Driver struct {
-	id     string
-	cookie string
-	rootID string
-	client *sdk.Pan115Client
-	ua     string
+	id            string
+	cookie        string
+	rootID        string
+	client        *sdk.Pan115Client
+	ua            string
+	uploadTempDir string
 
 	listMu       sync.Mutex
 	lastListAt   time.Time
@@ -32,10 +33,11 @@ type Driver struct {
 }
 
 type Config struct {
-	ID     string
-	Cookie string // 形如 "UID=xxx; CID=xxx; SEID=xxx; KID=xxx"
-	RootID string // 默认 "0"
-	UA     string // 默认 UA115Browser
+	ID            string
+	Cookie        string // 形如 "UID=xxx; CID=xxx; SEID=xxx; KID=xxx"
+	RootID        string // 默认 "0"
+	UA            string // 默认 UA115Browser
+	UploadTempDir string
 }
 
 func New(c Config) *Driver {
@@ -48,11 +50,12 @@ func New(c Config) *Driver {
 		ua = sdk.UA115Browser
 	}
 	return &Driver{
-		id:           c.ID,
-		cookie:       c.Cookie,
-		rootID:       rootID,
-		ua:           ua,
-		listInterval: 2 * time.Second,
+		id:            c.ID,
+		cookie:        c.Cookie,
+		rootID:        rootID,
+		ua:            ua,
+		uploadTempDir: strings.TrimSpace(c.UploadTempDir),
+		listInterval:  2 * time.Second,
 	}
 }
 
@@ -87,7 +90,7 @@ func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error)
 // p115ListCooldown 是列目录触发疑似风控错误时的冷却时长。
 //
 // 历史上是 [30min × 3]，3 次都失败就放弃；新策略改为 10 分钟无限重试 ——
-// 只要错误仍属 transient（429 / 405 / WAF / blocked / 安全威胁 / unexpected），
+// 只要错误仍属明确 HTTP transient 状态（429 / 405），
 // 就持续等 10 分钟再发一次列目录请求，直到成功或 ctx 取消。这样即使 115
 // 风控持续较长时间，扫描会自然延后到风控结束，不再丢半棵子树。
 const p115ListCooldown = 10 * time.Minute
@@ -149,20 +152,14 @@ func sleepContext(ctx context.Context, d time.Duration) error {
 }
 
 func isTransient115ListError(err error) bool {
+	return isTransient115UpstreamError(err)
+}
+
+func isTransient115UpstreamError(err error) bool {
 	if err == nil {
 		return false
 	}
-	text := strings.ToLower(err.Error())
-	return strings.Contains(text, "405") ||
-		strings.Contains(text, "429") ||
-		strings.Contains(text, "too many request") ||
-		strings.Contains(text, "too many requests") ||
-		strings.Contains(text, "blocked") ||
-		strings.Contains(text, "security") ||
-		strings.Contains(text, "waf") ||
-		strings.Contains(text, "unexpected error") ||
-		strings.Contains(text, "访问被阻断") ||
-		strings.Contains(text, "安全威胁")
+	return drives.ErrorMentionsHTTPStatus(err, http.StatusMethodNotAllowed, http.StatusTooManyRequests)
 }
 
 // ListDirsOnly 只列指定目录的直接**子目录**，不返回文件条目。专为 admin 后台
@@ -248,11 +245,11 @@ func (d *Driver) streamURLWithUA(ctx context.Context, fileID string, ua string)
 	// 需要先拿到 pickCode
 	f, err := d.client.GetFile(fileID)
 	if err != nil {
-		return nil, fmt.Errorf("115 get file: %w", err)
+		return nil, wrap115StreamTransientError("115 get file", err)
 	}
 	info, ua, err := d.downloadInfo(f.PickCode, ua)
 	if err != nil {
-		return nil, fmt.Errorf("115 download url: %w", err)
+		return nil, wrap115StreamTransientError("115 download url", err)
 	}
 	if info == nil || info.Url.Url == "" {
 		return nil, errors.New("115 download url: empty")
@@ -288,6 +285,18 @@ func (d *Driver) downloadInfo(pickCode string, ua string) (*sdk.DownloadInfo, st
 	return info, ua, nil
 }
 
+func wrap115StreamTransientError(op string, err error) error {
+	wrapped := fmt.Errorf("%s: %w", op, err)
+	if !isTransient115UpstreamError(err) {
+		return wrapped
+	}
+	return &drives.RateLimitError{
+		Provider:   "p115",
+		RetryAfter: p115ListCooldown,
+		Err:        wrapped,
+	}
+}
+
 func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error) {
 	res, err := d.UploadAndReportSha1(ctx, parentID, name, r, size)
 	if err != nil {
@@ -341,7 +350,7 @@ func (d *Driver) UploadAndReportSha1(ctx context.Context, parentID, name string,
 		parentID = d.rootID
 	}
 
-	tmp, sha1Hex, written, err := bufferAndHashSha1(r, size)
+	tmp, sha1Hex, written, err := bufferAndHashSha1(d.uploadTempDir, r, size)
 	if err != nil {
 		return UploadResult{}, err
 	}
@@ -445,12 +454,35 @@ func (d *Driver) Rename(ctx context.Context, fileID, newName string) error {
 	return nil
 }
 
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	if d.client == nil {
+		return errors.New("p115 remove: driver not initialized")
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return errors.New("p115 remove: empty fileID")
+	}
+	if err := d.client.Delete(fileID); err != nil {
+		return fmt.Errorf("p115 remove: %w", err)
+	}
+	return nil
+}
+
 // bufferAndHashSha1 把 r 全量复制到一个临时文件，同时计算 SHA1。
 // 返回临时文件（位置在末尾，需调用方 Seek 回 0）、SHA1 hex 大写、实际字节数。
 //
 // 调用方负责 Close + Remove 临时文件。
-func bufferAndHashSha1(r io.Reader, declaredSize int64) (*os.File, string, int64, error) {
-	tmp, err := os.CreateTemp("", "p115-upload-*.bin")
+func bufferAndHashSha1(tempDir string, r io.Reader, declaredSize int64) (*os.File, string, int64, error) {
+	tempDir = strings.TrimSpace(tempDir)
+	if tempDir != "" {
+		if err := os.MkdirAll(tempDir, 0o755); err != nil {
+			return nil, "", 0, fmt.Errorf("p115 upload: create tmp dir: %w", err)
+		}
+	}
+	tmp, err := os.CreateTemp(tempDir, "p115-upload-*.bin")
 	if err != nil {
 		return nil, "", 0, fmt.Errorf("p115 upload: create tmp: %w", err)
 	}
@@ -547,3 +579,4 @@ func guessMime(name string) string {
 }
 
 var _ drives.Drive = (*Driver)(nil)
+var _ drives.Remover = (*Driver)(nil)

backend/internal/drives/p115/driver_test.go

@@ -8,8 +8,12 @@ import (
 	"errors"
 	"io"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/drives"
 )
 
 func TestIsTransient115ListError(t *testing.T) {
@@ -19,8 +23,9 @@ func TestIsTransient115ListError(t *testing.T) {
 		want bool
 	}{
 		{name: "nil", err: nil, want: false},
-		{name: "blocked html", err: errors.New(`<!doctype html><title>405</title>Sorry, your request has been blocked as it may cause potential threats to the server's security.`), want: true},
-		{name: "chinese waf", err: errors.New("很抱歉，由于您访问的URL有可能对网站造成安全威胁，您的访问被阻断。"), want: true},
+		{name: "blocked html without status context", err: errors.New(`<!doctype html><title>405</title>Sorry, your request has been blocked as it may cause potential threats to the server's security.`), want: false},
+		{name: "chinese waf", err: errors.New("很抱歉，由于您访问的URL有可能对网站造成安全威胁，您的访问被阻断。"), want: false},
+		{name: "status 405", err: errors.New("request failed with status: 405"), want: true},
 		{name: "rate limit", err: errors.New("429 too many requests"), want: true},
 		{name: "regular auth error", err: errors.New("invalid credential"), want: false},
 	}
@@ -34,6 +39,42 @@ func TestIsTransient115ListError(t *testing.T) {
 	}
 }
 
+func TestWrap115StreamTransientError(t *testing.T) {
+	cases := []struct {
+		name          string
+		err           error
+		wantRateLimit bool
+	}{
+		{name: "unexpected", err: errors.New("unexpected error"), wantRateLimit: false},
+		{name: "405 blocked", err: errors.New("405 request has been blocked"), wantRateLimit: true},
+		{name: "429", err: errors.New("429 too many requests"), wantRateLimit: true},
+		{name: "blocked", err: errors.New("blocked by waf"), wantRateLimit: false},
+		{name: "auth", err: errors.New("invalid credential"), wantRateLimit: false},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := wrap115StreamTransientError("115 get file", tc.err)
+			var rateLimit *drives.RateLimitError
+			isRateLimit := errors.As(got, &rateLimit)
+			if isRateLimit != tc.wantRateLimit {
+				t.Fatalf("rate limit = %v, want %v; err=%v", isRateLimit, tc.wantRateLimit, got)
+			}
+			if !strings.Contains(got.Error(), "115 get file") {
+				t.Fatalf("err = %v, want operation prefix", got)
+			}
+			if tc.wantRateLimit {
+				if rateLimit.Provider != "p115" {
+					t.Fatalf("provider = %q, want p115", rateLimit.Provider)
+				}
+				if rateLimit.RetryAfter != 10*time.Minute {
+					t.Fatalf("retry after = %s, want 10m", rateLimit.RetryAfter)
+				}
+			}
+		})
+	}
+}
+
 // TestBufferAndHashSha1 验证 bufferAndHashSha1：
 //
 //   - 把 reader 的全部字节落到 tmp 文件
@@ -46,7 +87,7 @@ func TestBufferAndHashSha1(t *testing.T) {
 	wantHex := strings.ToUpper(hex.EncodeToString(want[:]))
 
 	t.Run("declared size matches", func(t *testing.T) {
-		tmp, gotHex, n, err := bufferAndHashSha1(bytes.NewReader(body), int64(len(body)))
+		tmp, gotHex, n, err := bufferAndHashSha1("", bytes.NewReader(body), int64(len(body)))
 		if err != nil {
 			t.Fatalf("bufferAndHashSha1 returned error: %v", err)
 		}
@@ -71,14 +112,14 @@ func TestBufferAndHashSha1(t *testing.T) {
 	})
 
 	t.Run("declared size mismatch returns error", func(t *testing.T) {
-		_, _, _, err := bufferAndHashSha1(bytes.NewReader(body), int64(len(body))+1)
+		_, _, _, err := bufferAndHashSha1("", bytes.NewReader(body), int64(len(body))+1)
 		if err == nil {
 			t.Fatal("expected size mismatch error, got nil")
 		}
 	})
 
 	t.Run("declared size zero is unchecked", func(t *testing.T) {
-		tmp, gotHex, n, err := bufferAndHashSha1(bytes.NewReader(body), 0)
+		tmp, gotHex, n, err := bufferAndHashSha1("", bytes.NewReader(body), 0)
 		if err != nil {
 			t.Fatalf("bufferAndHashSha1 returned error: %v", err)
 		}
@@ -90,6 +131,18 @@ func TestBufferAndHashSha1(t *testing.T) {
 			t.Errorf("written = %d, want %d", n, len(body))
 		}
 	})
+
+	t.Run("uses configured temp dir", func(t *testing.T) {
+		tempDir := filepath.Join(t.TempDir(), "upload-tmp")
+		tmp, _, _, err := bufferAndHashSha1(tempDir, bytes.NewReader(body), int64(len(body)))
+		if err != nil {
+			t.Fatalf("bufferAndHashSha1 returned error: %v", err)
+		}
+		defer cleanup(tmp)
+		if gotDir := filepath.Dir(tmp.Name()); gotDir != tempDir {
+			t.Fatalf("tmp dir = %q, want %q", gotDir, tempDir)
+		}
+	})
 }
 
 // TestUploadAndReportSha1RejectsInvalidArgs 检查空 reader / 空 name / 负 size 在

backend/internal/drives/p123/driver_test.go

@@ -0,0 +1,512 @@
+package p123
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/drives"
+)
+
+func TestStreamURLResolvesDownloadInfoRedirect(t *testing.T) {
+	ctx := context.Background()
+	var downloadReferer string
+	var download *httptest.Server
+	download = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/resolve":
+			downloadReferer = r.Header.Get("Referer")
+			http.Redirect(w, r, download.URL+"/cdn/video.mp4", http.StatusFound)
+		case "/cdn/video.mp4":
+			t.Fatalf("driver followed redirect unexpectedly")
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer download.Close()
+
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/api/user/sign_in":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 200,
+				"data": map[string]string{"token": "token-1"},
+			})
+		case "/b/api/user/info":
+			if got := r.Header.Get("Authorization"); got != "Bearer token-1" {
+				t.Fatalf("Authorization = %q, want bearer token", got)
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{"code": 0, "data": map[string]any{}})
+		case "/b/api/file/list/new":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"Next":  "-1",
+					"Total": 1,
+					"InfoList": []map[string]any{
+						{
+							"FileName":  "video.mp4",
+							"Size":      1234,
+							"UpdateAt":  "2026-01-02 03:04:05",
+							"FileId":    100,
+							"Type":      0,
+							"Etag":      "ABCDEF",
+							"S3KeyFlag": "flag-1",
+						},
+					},
+				},
+			})
+		case "/b/api/file/download_info":
+			var body map[string]any
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatalf("decode download_info body: %v", err)
+			}
+			if got := body["fileName"]; got != "video.mp4" {
+				t.Fatalf("fileName = %#v, want cached file metadata", got)
+			}
+			if got := body["etag"]; got != "ABCDEF" {
+				t.Fatalf("etag = %#v, want cached etag", got)
+			}
+			entryURL := download.URL + "/entry?params=" + base64.StdEncoding.EncodeToString([]byte(download.URL+"/resolve"))
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]string{"DownloadUrl": entryURL},
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer api.Close()
+
+	var savedToken string
+	d := New(Config{
+		ID:              "123-main",
+		Username:        "user@example.com",
+		Password:        "secret",
+		MainAPIBaseURL:  api.URL + "/b/api",
+		LoginAPIBaseURL: api.URL + "/api",
+		OnTokenUpdate: func(access string) {
+			savedToken = access
+		},
+	})
+	if err := d.Init(ctx); err != nil {
+		t.Fatalf("Init() error = %v", err)
+	}
+	if savedToken != "token-1" {
+		t.Fatalf("saved token = %q, want token-1", savedToken)
+	}
+	if _, err := d.List(ctx, d.RootID()); err != nil {
+		t.Fatalf("List() error = %v", err)
+	}
+
+	link, err := d.StreamURL(ctx, "100")
+	if err != nil {
+		t.Fatalf("StreamURL() error = %v", err)
+	}
+	if got := link.URL; got != download.URL+"/cdn/video.mp4" {
+		t.Fatalf("URL = %q, want final CDN URL", got)
+	}
+	if got := link.Headers.Get("Referer"); !strings.HasPrefix(got, download.URL) {
+		t.Fatalf("Referer = %q, want original download host", got)
+	}
+	if downloadReferer != defaultReferer {
+		t.Fatalf("resolve Referer = %q, want %q", downloadReferer, defaultReferer)
+	}
+}
+
+func TestInitUsesAccessTokenWithoutLogin(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/api/user/sign_in":
+			t.Fatalf("driver should not password-login when access_token is configured")
+		case "/b/api/user/info":
+			if got := r.Header.Get("Authorization"); got != "Bearer token-1" {
+				t.Fatalf("Authorization = %q, want bearer token", got)
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{"code": 0, "data": map[string]any{}})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:              "123-main",
+		AccessToken:     "Bearer token-1",
+		MainAPIBaseURL:  api.URL + "/b/api",
+		LoginAPIBaseURL: api.URL + "/api",
+	})
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("Init() error = %v", err)
+	}
+}
+
+func TestLoginRiskErrorSuggestsAccessToken(t *testing.T) {
+	err := loginError("当前账号存在境外登录风险，请使用短信验证码或者微信进行登录。")
+	if err == nil || !strings.Contains(err.Error(), "access_token") {
+		t.Fatalf("loginError() = %v, want access_token guidance", err)
+	}
+}
+
+func TestRequestCode429ReturnsRateLimitError(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Retry-After", "2")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"code":    429,
+			"message": "请求太频繁",
+		})
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:             "123-main",
+		AccessToken:    "token-1",
+		MainAPIBaseURL: api.URL,
+	})
+	_, err := d.request(context.Background(), endpointFileList, http.MethodGet, nil, nil)
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.RetryAfter != 2*time.Second {
+		t.Fatalf("RetryAfter = %s, want 2s", rateLimit.RetryAfter)
+	}
+}
+
+func TestListCoolsDownAndRetriesRateLimit(t *testing.T) {
+	var listCalls int
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/file/list/new" {
+			http.NotFound(w, r)
+			return
+		}
+		listCalls++
+		if listCalls == 1 {
+			w.Header().Set("Retry-After", "1")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code":    429,
+				"message": "请求太频繁",
+			})
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"code": 0,
+			"data": map[string]any{
+				"Next":  "-1",
+				"Total": 1,
+				"InfoList": []map[string]any{
+					{
+						"FileName":  "video.mp4",
+						"Size":      1234,
+						"UpdateAt":  "2026-01-02 03:04:05",
+						"FileId":    100,
+						"Type":      0,
+						"Etag":      "ABCDEF",
+						"S3KeyFlag": "flag-1",
+					},
+				},
+			},
+		})
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:             "123-main",
+		AccessToken:    "token-1",
+		MainAPIBaseURL: api.URL,
+	})
+	entries, err := d.List(context.Background(), d.RootID())
+	if err != nil {
+		t.Fatalf("List() error = %v", err)
+	}
+	if listCalls != 2 {
+		t.Fatalf("list calls = %d, want 2", listCalls)
+	}
+	if len(entries) != 1 || entries[0].ID != "100" {
+		t.Fatalf("entries = %#v, want one file", entries)
+	}
+}
+
+func TestResolveDownloadURL429ReturnsRateLimitError(t *testing.T) {
+	download := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Retry-After", "3")
+		http.Error(w, "too many requests", http.StatusTooManyRequests)
+	}))
+	defer download.Close()
+
+	d := New(Config{ID: "123-main"})
+	_, err := d.resolveDownloadURL(context.Background(), download.URL)
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.RetryAfter != 3*time.Second {
+		t.Fatalf("RetryAfter = %s, want 3s", rateLimit.RetryAfter)
+	}
+}
+
+func TestUploadAndReportHashUsesPresignedPUTAndComplete(t *testing.T) {
+	ctx := context.Background()
+	body := []byte("video bytes for 123 upload")
+	wantMD5 := fmt.Sprintf("%x", md5.Sum(body))
+
+	var putBody []byte
+	upload := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut {
+			t.Fatalf("upload method = %s, want PUT", r.Method)
+		}
+		if r.ContentLength != int64(len(body)) {
+			t.Fatalf("ContentLength = %d, want %d", r.ContentLength, len(body))
+		}
+		got, err := io.ReadAll(r.Body)
+		if err != nil {
+			t.Fatalf("read upload body: %v", err)
+		}
+		putBody = got
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer upload.Close()
+
+	var uploadRequest map[string]any
+	var uploadURLRequest map[string]any
+	var completeRequest map[string]any
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/file/upload_request":
+			if err := json.NewDecoder(r.Body).Decode(&uploadRequest); err != nil {
+				t.Fatalf("decode upload_request: %v", err)
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"FileId":      9001,
+					"Bucket":      "bucket-1",
+					"Key":         "key-1",
+					"StorageNode": "node-1",
+					"UploadId":    "upload-1",
+				},
+			})
+		case "/file/s3_upload_object/auth":
+			if err := json.NewDecoder(r.Body).Decode(&uploadURLRequest); err != nil {
+				t.Fatalf("decode s3 auth: %v", err)
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"presignedUrls": map[string]string{
+						"1": upload.URL + "/part-1",
+					},
+				},
+			})
+		case "/file/upload_complete/v2":
+			if err := json.NewDecoder(r.Body).Decode(&completeRequest); err != nil {
+				t.Fatalf("decode complete: %v", err)
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{"code": 0, "data": map[string]any{}})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:             "123-main",
+		AccessToken:    "token-1",
+		MainAPIBaseURL: api.URL,
+	})
+	res, err := d.UploadAndReportHash(ctx, "parent-1", "video.mp4", bytes.NewReader(body), int64(len(body)))
+	if err != nil {
+		t.Fatalf("UploadAndReportHash() error = %v", err)
+	}
+	if res.FileID != "9001" {
+		t.Fatalf("FileID = %q, want 9001", res.FileID)
+	}
+	if res.Hash != wantMD5 {
+		t.Fatalf("Hash = %q, want %q", res.Hash, wantMD5)
+	}
+	if res.Size != int64(len(body)) {
+		t.Fatalf("Size = %d, want %d", res.Size, len(body))
+	}
+	if !bytes.Equal(putBody, body) {
+		t.Fatalf("PUT body = %q, want %q", putBody, body)
+	}
+	if uploadRequest["etag"] != wantMD5 {
+		t.Fatalf("upload etag = %#v, want %q", uploadRequest["etag"], wantMD5)
+	}
+	if uploadRequest["fileName"] != "video.mp4" || uploadRequest["parentFileId"] != "parent-1" {
+		t.Fatalf("upload request = %#v, want fileName and parentFileId", uploadRequest)
+	}
+	if uploadURLRequest["partNumberStart"].(float64) != 1 || uploadURLRequest["partNumberEnd"].(float64) != 2 {
+		t.Fatalf("s3 auth request = %#v, want part range 1..2", uploadURLRequest)
+	}
+	if completeRequest["fileId"].(float64) != 9001 || completeRequest["fileSize"].(float64) != float64(len(body)) {
+		t.Fatalf("complete request = %#v, want file id and size", completeRequest)
+	}
+	if completeRequest["isMultipart"].(bool) {
+		t.Fatalf("complete isMultipart = true, want false")
+	}
+}
+
+func TestUploadAndReportHashReuseSkipsPUTAndComplete(t *testing.T) {
+	body := []byte("reused body")
+	var presignedCalled bool
+	var completeCalled bool
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/file/upload_request":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"FileId": 7001,
+					"Reuse":  true,
+				},
+			})
+		case "/file/s3_upload_object/auth", "/file/s3_repare_upload_parts_batch":
+			presignedCalled = true
+			_ = json.NewEncoder(w).Encode(map[string]any{"code": 0})
+		case "/file/upload_complete/v2":
+			completeCalled = true
+			_ = json.NewEncoder(w).Encode(map[string]any{"code": 0})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:             "123-main",
+		AccessToken:    "token-1",
+		MainAPIBaseURL: api.URL,
+	})
+	res, err := d.UploadAndReportHash(context.Background(), "parent-1", "reused.mp4", bytes.NewReader(body), int64(len(body)))
+	if err != nil {
+		t.Fatalf("UploadAndReportHash() error = %v", err)
+	}
+	if res.FileID != "7001" {
+		t.Fatalf("FileID = %q, want 7001", res.FileID)
+	}
+	if presignedCalled {
+		t.Fatal("reuse upload should not request presigned URLs")
+	}
+	if completeCalled {
+		t.Fatal("reuse upload should not call upload_complete")
+	}
+}
+
+func TestUploadPresignedPUT429ReturnsRateLimitError(t *testing.T) {
+	upload := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Retry-After", "4")
+		http.Error(w, "too many requests", http.StatusTooManyRequests)
+	}))
+	defer upload.Close()
+
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/file/upload_request":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"FileId":      9001,
+					"Bucket":      "bucket-1",
+					"Key":         "key-1",
+					"StorageNode": "node-1",
+					"UploadId":    "upload-1",
+				},
+			})
+		case "/file/s3_upload_object/auth":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"presignedUrls": map[string]string{"1": upload.URL},
+				},
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:             "123-main",
+		AccessToken:    "token-1",
+		MainAPIBaseURL: api.URL,
+	})
+	_, err := d.UploadAndReportHash(context.Background(), "parent-1", "limited.mp4", strings.NewReader("limited"), int64(len("limited")))
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.RetryAfter != 4*time.Second {
+		t.Fatalf("RetryAfter = %s, want 4s", rateLimit.RetryAfter)
+	}
+}
+
+func TestBufferAndHashMD5UsesConfiguredTempDir(t *testing.T) {
+	body := []byte("hello-123-upload-test")
+	tempDir := filepath.Join(t.TempDir(), "upload-tmp")
+	tmp, gotHex, n, err := bufferAndHashMD5(tempDir, bytes.NewReader(body), int64(len(body)))
+	if err != nil {
+		t.Fatalf("bufferAndHashMD5 returned error: %v", err)
+	}
+	defer func() {
+		_ = tmp.Close()
+		_ = os.Remove(tmp.Name())
+	}()
+	if gotDir := filepath.Dir(tmp.Name()); gotDir != tempDir {
+		t.Fatalf("tmp dir = %q, want %q", gotDir, tempDir)
+	}
+	want := md5.Sum(body)
+	if gotHex != fmt.Sprintf("%x", want) {
+		t.Fatalf("md5 = %s, want %x", gotHex, want)
+	}
+	if n != int64(len(body)) {
+		t.Fatalf("written = %d, want %d", n, len(body))
+	}
+}
+
+func TestRenameSendsExpectedBody(t *testing.T) {
+	var renameRequest map[string]any
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/file/rename" {
+			http.NotFound(w, r)
+			return
+		}
+		if err := json.NewDecoder(r.Body).Decode(&renameRequest); err != nil {
+			t.Fatalf("decode rename: %v", err)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"code": 0, "data": map[string]any{}})
+	}))
+	defer api.Close()
+
+	d := New(Config{
+		ID:             "123-main",
+		AccessToken:    "token-1",
+		MainAPIBaseURL: api.URL,
+	})
+	if err := d.Rename(context.Background(), "9001", "new name.mp4"); err != nil {
+		t.Fatalf("Rename() error = %v", err)
+	}
+	if renameRequest["driveId"].(float64) != 0 || renameRequest["fileId"] != "9001" || renameRequest["fileName"] != "new name.mp4" {
+		t.Fatalf("rename request = %#v, want driveId/fileId/fileName", renameRequest)
+	}
+}

backend/internal/drives/p123/qr.go

@@ -0,0 +1,285 @@
+package p123
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/go-resty/resty/v2"
+	"github.com/skip2/go-qrcode"
+)
+
+const (
+	defaultUserAPIBase = "https://user.123pan.cn/api"
+	defaultQRLoginPage = "https://www.123pan.com/wx-app-login.html"
+	defaultQRReferer   = "https://user.123pan.com/centerlogin"
+	defaultQROrigin    = "https://user.123pan.com"
+	defaultQRUserAgent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0 Safari/537.36"
+
+	endpointQRCodeGenerate = "/user/qr-code/generate"
+	endpointQRCodeResult   = "/user/qr-code/result"
+	endpointQRCodeWXCode   = "/user/qr-code/wx_code"
+)
+
+type QRConfig struct {
+	UserAPIBaseURL string
+	HTTPClient     *http.Client
+	Now            func() time.Time
+}
+
+type QRClient struct {
+	userAPIBase string
+	client      *resty.Client
+	now         func() time.Time
+}
+
+type QRCodeSession struct {
+	LoginUUID      string `json:"loginUuid"`
+	UniID          string `json:"uniID"`
+	QRCodeURL      string `json:"qrCodeUrl"`
+	QRImageDataURL string `json:"qrImageDataUrl"`
+	ExpiresAt      string `json:"expiresAt,omitempty"`
+}
+
+type QRCodeStatus struct {
+	LoginStatus  int    `json:"loginStatus"`
+	StatusText   string `json:"statusText"`
+	ScanPlatform int    `json:"scanPlatform,omitempty"`
+	PlatformText string `json:"platformText,omitempty"`
+	AccessToken  string `json:"accessToken,omitempty"`
+}
+
+func NewQRClient(c QRConfig) *QRClient {
+	userAPIBase := strings.TrimRight(strings.TrimSpace(c.UserAPIBaseURL), "/")
+	if userAPIBase == "" {
+		userAPIBase = defaultUserAPIBase
+	}
+	httpClient := c.HTTPClient
+	if httpClient == nil {
+		httpClient = &http.Client{Timeout: 20 * time.Second}
+	}
+	now := c.Now
+	if now == nil {
+		now = time.Now
+	}
+	return &QRClient{
+		userAPIBase: userAPIBase,
+		client: resty.NewWithClient(httpClient).
+			SetTimeout(20*time.Second).
+			SetHeader("Accept", "application/json, text/plain, */*"),
+		now: now,
+	}
+}
+
+func (c *QRClient) Generate(ctx context.Context) (QRCodeSession, error) {
+	loginUUID, err := newLoginUUID()
+	if err != nil {
+		return QRCodeSession{}, err
+	}
+	var resp qrGenerateResp
+	res, err := c.request(ctx, loginUUID).
+		SetResult(&resp).
+		Get(c.userAPIBase + endpointQRCodeGenerate)
+	if err != nil {
+		return QRCodeSession{}, err
+	}
+	if resp.Code != 0 {
+		return QRCodeSession{}, qrAPIError(resp.Message, res.StatusCode(), resp.Code)
+	}
+	uniID := strings.TrimSpace(resp.Data.UniID)
+	if uniID == "" {
+		return QRCodeSession{}, errors.New("123pan qr: empty uniID")
+	}
+	qrURL := buildQRLoginURL(resp.Data.URL, uniID)
+	png, err := qrcode.Encode(qrURL, qrcode.Medium, 220)
+	if err != nil {
+		return QRCodeSession{}, err
+	}
+	return QRCodeSession{
+		LoginUUID:      loginUUID,
+		UniID:          uniID,
+		QRCodeURL:      qrURL,
+		QRImageDataURL: "data:image/png;base64," + base64.StdEncoding.EncodeToString(png),
+		ExpiresAt:      c.now().Add(5 * time.Minute).Format(time.RFC3339),
+	}, nil
+}
+
+func (c *QRClient) Poll(ctx context.Context, loginUUID, uniID string) (QRCodeStatus, error) {
+	loginUUID = strings.TrimSpace(loginUUID)
+	uniID = strings.TrimSpace(uniID)
+	if loginUUID == "" {
+		return QRCodeStatus{}, errors.New("loginUuid is required")
+	}
+	if uniID == "" {
+		return QRCodeStatus{}, errors.New("uniID is required")
+	}
+	var resp qrResultResp
+	res, err := c.request(ctx, loginUUID).
+		SetQueryParam("uniID", uniID).
+		SetResult(&resp).
+		Get(c.userAPIBase + endpointQRCodeResult)
+	if err != nil {
+		return QRCodeStatus{}, err
+	}
+	if resp.Code != 0 && resp.Code != 200 {
+		return QRCodeStatus{}, qrAPIError(resp.Message, res.StatusCode(), resp.Code)
+	}
+	if resp.Code == 200 {
+		resp.Data.LoginStatus = 3
+		if resp.Data.ScanPlatform == 0 {
+			resp.Data.ScanPlatform = resp.Data.LoginType
+		}
+	}
+	status := QRCodeStatus{
+		LoginStatus:  resp.Data.LoginStatus,
+		StatusText:   qrLoginStatusText(resp.Data.LoginStatus),
+		ScanPlatform: resp.Data.ScanPlatform,
+		PlatformText: qrScanPlatformText(resp.Data.ScanPlatform),
+	}
+	if status.LoginStatus != 3 {
+		return status, nil
+	}
+	if token := resp.TokenValue(); token != "" {
+		status.AccessToken = normalizeAccessToken(token)
+		return status, nil
+	}
+	if resp.Data.ScanPlatform == 4 {
+		token, err := c.finishWechatLogin(ctx, loginUUID, uniID)
+		if err != nil {
+			return QRCodeStatus{}, err
+		}
+		status.AccessToken = normalizeAccessToken(token)
+		return status, nil
+	}
+	return QRCodeStatus{}, errors.New("123pan qr: confirmed login returned empty token")
+}
+
+func (c *QRClient) finishWechatLogin(ctx context.Context, loginUUID, uniID string) (string, error) {
+	var wxResp qrWXCodeResp
+	res, err := c.request(ctx, loginUUID).
+		SetBody(map[string]string{"uniID": uniID}).
+		SetResult(&wxResp).
+		Post(c.userAPIBase + endpointQRCodeWXCode)
+	if err != nil {
+		return "", err
+	}
+	if wxResp.Code != 0 {
+		return "", qrAPIError(wxResp.Message, res.StatusCode(), wxResp.Code)
+	}
+	wxCode := strings.TrimSpace(wxResp.WXCode())
+	if wxCode == "" {
+		return "", errors.New("123pan qr: empty wechat code")
+	}
+	var signIn loginResp
+	res, err = c.request(ctx, loginUUID).
+		SetBody(map[string]any{
+			"from":        "web",
+			"wechat_code": wxCode,
+			"type":        4,
+		}).
+		SetResult(&signIn).
+		Post(c.userAPIBase + endpointSignIn)
+	if err != nil {
+		return "", err
+	}
+	if signIn.Code != 200 && signIn.Code != 0 {
+		return "", qrAPIError(signIn.Message, res.StatusCode(), signIn.Code)
+	}
+	token := strings.TrimSpace(signIn.Data.Token)
+	if token == "" {
+		return "", errors.New("123pan qr: empty token")
+	}
+	return token, nil
+}
+
+func (c *QRClient) request(ctx context.Context, loginUUID string) *resty.Request {
+	return c.client.R().
+		SetContext(ctx).
+		SetHeaders(map[string]string{
+			"Content-Type": "application/json;charset=UTF-8",
+			"platform":     defaultPlatform,
+			"App-Version":  defaultAppVersion,
+			"LoginUuid":    loginUUID,
+			"Referer":      defaultQRReferer,
+			"Origin":       defaultQROrigin,
+			"User-Agent":   defaultQRUserAgent,
+		})
+}
+
+func buildQRLoginURL(raw, uniID string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		raw = defaultQRLoginPage
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		return defaultQRLoginPage + "?env=production&uniID=" + url.QueryEscape(uniID) + "&source=123pan&type=login"
+	}
+	q := u.Query()
+	q.Set("env", "production")
+	q.Set("uniID", uniID)
+	q.Set("source", "123pan")
+	q.Set("type", "login")
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+func newLoginUUID() (string, error) {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", err
+	}
+	b[6] = (b[6] & 0x0f) | 0x40
+	b[8] = (b[8] & 0x3f) | 0x80
+	parts := []string{
+		hex.EncodeToString(b[0:4]),
+		hex.EncodeToString(b[4:6]),
+		hex.EncodeToString(b[6:8]),
+		hex.EncodeToString(b[8:10]),
+		hex.EncodeToString(b[10:16]),
+	}
+	return strings.Join(parts, "-"), nil
+}
+
+func qrAPIError(message string, httpStatus, apiCode int) error {
+	message = strings.TrimSpace(message)
+	if message == "" {
+		message = fmt.Sprintf("HTTP %d code=%d", httpStatus, apiCode)
+	}
+	return errors.New(message)
+}
+
+func qrLoginStatusText(status int) string {
+	switch status {
+	case 0:
+		return "等待扫码"
+	case 1:
+		return "已扫码，等待确认"
+	case 2:
+		return "已拒绝"
+	case 3:
+		return "已确认"
+	case 4:
+		return "已过期"
+	default:
+		return "未知状态"
+	}
+}
+
+func qrScanPlatformText(platform int) string {
+	switch platform {
+	case 4:
+		return "微信"
+	case 7:
+		return "123网盘 App"
+	default:
+		return ""
+	}
+}

backend/internal/drives/p123/qr_test.go

@@ -0,0 +1,182 @@
+package p123
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestQRCodeGenerateBuildsImage(t *testing.T) {
+	var seenLoginUUID string
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/api/user/qr-code/generate" {
+			http.NotFound(w, r)
+			return
+		}
+		seenLoginUUID = r.Header.Get("LoginUuid")
+		if seenLoginUUID == "" {
+			t.Fatalf("missing LoginUuid header")
+		}
+		if r.Header.Get("platform") != defaultPlatform {
+			t.Fatalf("platform header = %q, want %q", r.Header.Get("platform"), defaultPlatform)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"code":    0,
+			"message": "ok",
+			"data": map[string]string{
+				"uniID": "uni-1",
+				"url":   "https://www.123pan.com/wx-app-login.html",
+			},
+		})
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{UserAPIBaseURL: api.URL + "/api"}).Generate(context.Background())
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+	if got.LoginUUID != seenLoginUUID {
+		t.Fatalf("loginUuid = %q, want header %q", got.LoginUUID, seenLoginUUID)
+	}
+	if got.UniID != "uni-1" {
+		t.Fatalf("uniID = %q, want uni-1", got.UniID)
+	}
+	if !strings.Contains(got.QRCodeURL, "uniID=uni-1") || !strings.Contains(got.QRCodeURL, "type=login") {
+		t.Fatalf("qrCodeUrl = %q, want login params", got.QRCodeURL)
+	}
+	if !strings.HasPrefix(got.QRImageDataURL, "data:image/png;base64,") {
+		t.Fatalf("qrImageDataUrl missing png data url prefix")
+	}
+	if got.ExpiresAt == "" {
+		t.Fatalf("expiresAt is empty")
+	}
+}
+
+func TestQRCodePollCompletesWechatLogin(t *testing.T) {
+	var wxCodeRequested bool
+	var signInRequested bool
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.Header.Get("LoginUuid") != "login-1" {
+			t.Fatalf("LoginUuid = %q, want login-1", r.Header.Get("LoginUuid"))
+		}
+		switch r.URL.Path {
+		case "/api/user/qr-code/result":
+			if r.URL.Query().Get("uniID") != "uni-1" {
+				t.Fatalf("uniID = %q, want uni-1", r.URL.Query().Get("uniID"))
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"loginStatus":  3,
+					"scanPlatform": 4,
+				},
+			})
+		case "/api/user/qr-code/wx_code":
+			wxCodeRequested = true
+			var body map[string]string
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatalf("decode wx_code body: %v", err)
+			}
+			if body["uniID"] != "uni-1" {
+				t.Fatalf("wx_code uniID = %q, want uni-1", body["uniID"])
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]string{"wxCode": "wx-code-1"},
+			})
+		case "/api/user/sign_in":
+			signInRequested = true
+			var body map[string]any
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatalf("decode sign_in body: %v", err)
+			}
+			if body["wechat_code"] != "wx-code-1" {
+				t.Fatalf("wechat_code = %#v, want wx-code-1", body["wechat_code"])
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 200,
+				"data": map[string]string{"token": "Bearer token-1"},
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{UserAPIBaseURL: api.URL + "/api"}).Poll(context.Background(), "login-1", "uni-1")
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if !wxCodeRequested || !signInRequested {
+		t.Fatalf("wechat completion calls wx=%v signIn=%v, want both", wxCodeRequested, signInRequested)
+	}
+	if got.LoginStatus != 3 || got.AccessToken != "token-1" || got.PlatformText != "微信" {
+		t.Fatalf("status = %#v, want confirmed wechat token", got)
+	}
+}
+
+func TestQRCodePollUsesAppToken(t *testing.T) {
+	var wxCodeRequested bool
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/api/user/qr-code/result":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"code": 0,
+				"data": map[string]any{
+					"loginStatus":  3,
+					"scanPlatform": 7,
+					"token":        "app-token",
+				},
+			})
+		case "/api/user/qr-code/wx_code":
+			wxCodeRequested = true
+			http.Error(w, "unexpected wx_code", http.StatusInternalServerError)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{UserAPIBaseURL: api.URL + "/api"}).Poll(context.Background(), "login-1", "uni-1")
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if wxCodeRequested {
+		t.Fatalf("wx_code should not be called when app token is already returned")
+	}
+	if got.AccessToken != "app-token" || got.PlatformText != "123网盘 App" {
+		t.Fatalf("status = %#v, want app token", got)
+	}
+}
+
+func TestQRCodePollUsesOfficialAppSuccessCode(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/api/user/qr-code/result" {
+			http.NotFound(w, r)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"code": 200,
+			"data": map[string]any{
+				"login_type": 7,
+				"token":      "app-token",
+			},
+		})
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{UserAPIBaseURL: api.URL + "/api"}).Poll(context.Background(), "login-1", "uni-1")
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if got.LoginStatus != 3 || got.ScanPlatform != 7 || got.AccessToken != "app-token" {
+		t.Fatalf("status = %#v, want official app success token", got)
+	}
+}

backend/internal/drives/p123/types.go

@@ -0,0 +1,204 @@
+package p123
+
+import (
+	"encoding/json"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type apiEnvelope struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+type loginResp struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    struct {
+		Token string `json:"token"`
+	} `json:"data"`
+}
+
+type qrGenerateResp struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    struct {
+		UniID string `json:"uniID"`
+		URL   string `json:"url"`
+	} `json:"data"`
+}
+
+type qrResultResp struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    struct {
+		LoginStatus  int    `json:"loginStatus"`
+		ScanPlatform int    `json:"scanPlatform"`
+		LoginType    int    `json:"login_type"`
+		Token        string `json:"token"`
+		AccessToken  string `json:"accessToken"`
+	} `json:"data"`
+}
+
+func (r qrResultResp) TokenValue() string {
+	if strings.TrimSpace(r.Data.Token) != "" {
+		return r.Data.Token
+	}
+	return r.Data.AccessToken
+}
+
+type qrWXCodeResp struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    struct {
+		WXCodeLower string `json:"wxCode"`
+		WXCodeTitle string `json:"WxCode"`
+		Code        string `json:"code"`
+	} `json:"data"`
+}
+
+func (r qrWXCodeResp) WXCode() string {
+	if r.Data.WXCodeLower != "" {
+		return r.Data.WXCodeLower
+	}
+	if r.Data.WXCodeTitle != "" {
+		return r.Data.WXCodeTitle
+	}
+	return r.Data.Code
+}
+
+type fileListResp struct {
+	Data struct {
+		Next     string    `json:"Next"`
+		Total    int       `json:"Total"`
+		InfoList []panFile `json:"InfoList"`
+	} `json:"data"`
+}
+
+type panFile struct {
+	FileName  string       `json:"FileName"`
+	Size      int64        `json:"Size"`
+	UpdateAt  flexibleTime `json:"UpdateAt"`
+	FileID    int64        `json:"FileId"`
+	Type      int          `json:"Type"`
+	Etag      string       `json:"Etag"`
+	S3KeyFlag string       `json:"S3KeyFlag"`
+}
+
+type cachedFile struct {
+	file     panFile
+	parentID string
+}
+
+type downloadInfoResp struct {
+	Data struct {
+		DownloadURL      string `json:"DownloadUrl"`
+		DownloadURLLower string `json:"downloadUrl"`
+	} `json:"data"`
+}
+
+func (r downloadInfoResp) URL() string {
+	if r.Data.DownloadURL != "" {
+		return r.Data.DownloadURL
+	}
+	return r.Data.DownloadURLLower
+}
+
+type redirectResp struct {
+	Data struct {
+		RedirectURL      string `json:"redirect_url"`
+		RedirectURLCamel string `json:"redirectUrl"`
+		RedirectURLTitle string `json:"RedirectUrl"`
+	} `json:"data"`
+}
+
+func (r redirectResp) URL() string {
+	if r.Data.RedirectURL != "" {
+		return r.Data.RedirectURL
+	}
+	if r.Data.RedirectURLCamel != "" {
+		return r.Data.RedirectURLCamel
+	}
+	return r.Data.RedirectURLTitle
+}
+
+type mkdirResp struct {
+	Data struct {
+		FileID int64 `json:"FileId"`
+	} `json:"data"`
+}
+
+type uploadResp struct {
+	Data struct {
+		AccessKeyID     string `json:"AccessKeyId"`
+		Bucket          string `json:"Bucket"`
+		Key             string `json:"Key"`
+		SecretAccessKey string `json:"SecretAccessKey"`
+		SessionToken    string `json:"SessionToken"`
+		FileID          int64  `json:"FileId"`
+		Reuse           bool   `json:"Reuse"`
+		EndPoint        string `json:"EndPoint"`
+		StorageNode     string `json:"StorageNode"`
+		UploadID        string `json:"UploadId"`
+	} `json:"data"`
+}
+
+type s3PreSignedURLsResp struct {
+	Data struct {
+		PreSignedURLs map[string]string `json:"presignedUrls"`
+	} `json:"data"`
+}
+
+type flexibleTime struct {
+	t time.Time
+}
+
+func (t *flexibleTime) UnmarshalJSON(data []byte) error {
+	if string(data) == "null" || string(data) == `""` {
+		return nil
+	}
+	var s string
+	if err := json.Unmarshal(data, &s); err == nil {
+		t.t = parseTimeString(s)
+		return nil
+	}
+	var n int64
+	if err := json.Unmarshal(data, &n); err == nil {
+		if n > 1_000_000_000_000 {
+			t.t = time.UnixMilli(n)
+		} else {
+			t.t = time.Unix(n, 0)
+		}
+		return nil
+	}
+	return nil
+}
+
+func (t flexibleTime) Time() time.Time {
+	return t.t
+}
+
+func parseTimeString(s string) time.Time {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return time.Time{}
+	}
+	for _, layout := range []string{
+		time.RFC3339Nano,
+		time.RFC3339,
+		"2006-01-02 15:04:05",
+		"2006-01-02T15:04:05",
+	} {
+		if parsed, err := time.ParseInLocation(layout, s, time.FixedZone("UTC+8", 8*3600)); err == nil {
+			return parsed
+		}
+	}
+	if n, err := strconv.ParseInt(s, 10, 64); err == nil {
+		if n > 1_000_000_000_000 {
+			return time.UnixMilli(n)
+		}
+		return time.Unix(n, 0)
+	}
+	return time.Time{}
+}

backend/internal/drives/pikpak/auth.go

@@ -199,9 +199,8 @@ func (d *Driver) refreshCaptchaToken(ctx context.Context, action string, meta ma
 
 // refreshCaptchaTokenOnce 调 /v1/shield/captcha/init 申请新 captcha token。
 //
-// 如果 retry=true 且服务端返回 4002（captcha_token expired，意味着 body 里
-// 携带的 d.captchaToken 已经过期），就清空缓存的 captcha_token 后再调一次；
-// 这次 body 里 captcha_token 为空，服务端会直接发一个新的。这覆盖
+// 如果 retry=true 且服务端返回 captcha 失效错误（4002 或 9），就清空缓存的
+// captcha_token 后再调一次；这次 body 里 captcha_token 为空，服务端会直接发一个新的。这覆盖
 // driver 重启后 Init() 用持久化的旧 captcha_token 调 captcha init 失败的
 // 场景。
 func (d *Driver) refreshCaptchaTokenOnce(ctx context.Context, action string, meta map[string]string, retry bool) error {
@@ -230,7 +229,7 @@ func (d *Driver) refreshCaptchaTokenOnce(ctx context.Context, action string, met
 		return err
 	}
 	if e.isError() {
-		if retry && e.ErrorCode == 4002 && d.captchaToken != "" {
+		if retry && isCaptchaTokenRejectedCode(e.ErrorCode) && d.captchaToken != "" {
 			d.captchaToken = ""
 			return d.refreshCaptchaTokenOnce(ctx, action, meta, false)
 		}

backend/internal/drives/pikpak/captcha_recovery_test.go

@@ -96,6 +96,65 @@ func TestRefreshCaptchaTokenRecoversFrom4002(t *testing.T) {
 	}
 }
 
+// TestRefreshCaptchaTokenRecoversFrom9 覆盖 PikPak 返回 error_code=9
+// captcha_invalid 的路径。这个错误和 4002 一样表示当前 captcha_token 已被拒绝；
+// 重试 captcha/init 前必须先清空旧 token，否则服务端会继续拒绝。
+func TestRefreshCaptchaTokenRecoversFrom9(t *testing.T) {
+	var calls int32
+	type bodyShape struct {
+		CaptchaToken string `json:"captcha_token"`
+	}
+	var (
+		firstBody  bodyShape
+		secondBody bodyShape
+	)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/shield/captcha/init", func(w http.ResponseWriter, r *http.Request) {
+		n := atomic.AddInt32(&calls, 1)
+		switch n {
+		case 1:
+			_ = json.NewDecoder(r.Body).Decode(&firstBody)
+			writeErrorJSON(w, `{
+				"error_code": 9,
+				"error": "captcha_invalid",
+				"error_description": "Verification code is invalid"
+			}`)
+		case 2:
+			_ = json.NewDecoder(r.Body).Decode(&secondBody)
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{
+				"captcha_token": "fresh-captcha",
+				"expires_in": 300
+			}`))
+		default:
+			t.Errorf("unexpected captcha init call #%d", n)
+		}
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	d.captchaToken = "expired-captcha"
+
+	if err := d.refreshCaptchaTokenAtLogin(context.Background(), "GET:/drive/v1/files", "user-1"); err != nil {
+		t.Fatalf("refreshCaptchaTokenAtLogin: %v", err)
+	}
+
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("captcha init called %d times, want 2", got)
+	}
+	if firstBody.CaptchaToken != "expired-captcha" {
+		t.Errorf("first body captcha_token = %q, want \"expired-captcha\"", firstBody.CaptchaToken)
+	}
+	if secondBody.CaptchaToken != "" {
+		t.Errorf("second body captcha_token = %q, want empty (cleared after error_code=9)", secondBody.CaptchaToken)
+	}
+	if d.captchaToken != "fresh-captcha" {
+		t.Errorf("d.captchaToken = %q, want \"fresh-captcha\"", d.captchaToken)
+	}
+}
+
 // TestRefreshCaptchaTokenDoesNotLoopOn4002WithEmptyToken 防止退化成无限重试：
 // 如果调用方一开始 captchaToken 就是空，又遇上 4002，不应该再清空一次重试
 // （清空后还是空，再发会拿到同样的错误），应该直接返回错误让上层处理。
@@ -121,6 +180,141 @@ func TestRefreshCaptchaTokenDoesNotLoopOn4002WithEmptyToken(t *testing.T) {
 	}
 }
 
+func TestInitWithRefreshTokenDoesNotSendPersistedCaptchaToken(t *testing.T) {
+	var captchaCalls int32
+	var captchaBody struct {
+		CaptchaToken string `json:"captcha_token"`
+	}
+	var persisted struct {
+		access, refresh, captcha string
+		calls                    int
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/auth/token", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"access_token": "fresh-access",
+			"refresh_token": "fresh-refresh",
+			"sub": "user-1"
+		}`))
+	})
+	mux.HandleFunc("/v1/shield/captcha/init", func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&captchaCalls, 1)
+		_ = json.NewDecoder(r.Body).Decode(&captchaBody)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"captcha_token": "fresh-captcha",
+			"expires_in": 300
+		}`))
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	d.captchaToken = "persisted-stale-captcha"
+	d.onTokenUpdate = func(access, refresh, captcha, deviceID string) {
+		persisted.access = access
+		persisted.refresh = refresh
+		persisted.captcha = captcha
+		persisted.calls++
+	}
+
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("Init: %v", err)
+	}
+
+	if got := atomic.LoadInt32(&captchaCalls); got != 1 {
+		t.Fatalf("captcha init calls = %d, want 1", got)
+	}
+	if captchaBody.CaptchaToken != "" {
+		t.Errorf("captcha init body captcha_token = %q, want empty", captchaBody.CaptchaToken)
+	}
+	if d.captchaToken != "fresh-captcha" {
+		t.Errorf("d.captchaToken = %q, want \"fresh-captcha\"", d.captchaToken)
+	}
+	if persisted.access != "fresh-access" || persisted.refresh != "fresh-refresh" || persisted.captcha != "fresh-captcha" {
+		t.Errorf("persisted tokens = (%q, %q, %q), want fresh values", persisted.access, persisted.refresh, persisted.captcha)
+	}
+	if persisted.calls < 2 {
+		t.Errorf("persist callback calls = %d, want at least 2 (clear stale + persist fresh)", persisted.calls)
+	}
+}
+
+func TestInitFallsBackToLoginWhenRefreshReturnsCaptchaInvalid(t *testing.T) {
+	var (
+		tokenCalls   int32
+		captchaCalls int32
+		signinCalls  int32
+	)
+	var signinBody struct {
+		CaptchaToken string `json:"captcha_token"`
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/auth/token", func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&tokenCalls, 1)
+		writeErrorJSON(w, `{
+			"error_code": 4002,
+			"error": "captcha_invalid",
+			"error_description": "Code(4002) - captcha_token expired"
+		}`)
+	})
+	mux.HandleFunc("/v1/shield/captcha/init", func(w http.ResponseWriter, r *http.Request) {
+		n := atomic.AddInt32(&captchaCalls, 1)
+		w.Header().Set("Content-Type", "application/json")
+		switch n {
+		case 1:
+			_, _ = w.Write([]byte(`{
+				"captcha_token": "login-captcha",
+				"expires_in": 300
+			}`))
+		case 2:
+			_, _ = w.Write([]byte(`{
+				"captcha_token": "files-captcha",
+				"expires_in": 300
+			}`))
+		default:
+			t.Errorf("unexpected captcha init call #%d", n)
+		}
+	})
+	mux.HandleFunc("/v1/auth/signin", func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&signinCalls, 1)
+		_ = json.NewDecoder(r.Body).Decode(&signinBody)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"access_token": "login-access",
+			"refresh_token": "login-refresh",
+			"sub": "user-1"
+		}`))
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	d.captchaToken = "persisted-stale-captcha"
+
+	if err := d.Init(context.Background()); err != nil {
+		t.Fatalf("Init: %v", err)
+	}
+
+	if got := atomic.LoadInt32(&tokenCalls); got != 1 {
+		t.Fatalf("token refresh calls = %d, want 1", got)
+	}
+	if got := atomic.LoadInt32(&signinCalls); got != 1 {
+		t.Fatalf("signin calls = %d, want 1", got)
+	}
+	if got := atomic.LoadInt32(&captchaCalls); got != 2 {
+		t.Fatalf("captcha init calls = %d, want 2 (login + post-login files action)", got)
+	}
+	if signinBody.CaptchaToken != "login-captcha" {
+		t.Errorf("signin captcha_token = %q, want \"login-captcha\"", signinBody.CaptchaToken)
+	}
+	if d.accessToken != "login-access" || d.refreshToken != "login-refresh" || d.captchaToken != "files-captcha" {
+		t.Errorf("driver tokens = (%q, %q, %q), want login/files tokens", d.accessToken, d.refreshToken, d.captchaToken)
+	}
+}
+
 // TestRequestOnceRecoversFrom4002OnAPICall 验证一个普通 API 调用收到 4002
 // 时，requestOnce 会先清空 captchaToken、再走 captcha 刷新，最后用新 token
 // 重试请求，最终成功返回。
@@ -196,6 +390,76 @@ func TestRequestOnceRecoversFrom4002OnAPICall(t *testing.T) {
 	}
 }
 
+// TestRequestOnceRecoversFrom9OnAPICall 验证普通 API 调用收到 error_code=9
+// 时，会先清空旧 captchaToken，再刷新 captcha 并重试原请求。
+func TestRequestOnceRecoversFrom9OnAPICall(t *testing.T) {
+	var (
+		filesCalls   int32
+		captchaCalls int32
+	)
+	type capturedFiles struct {
+		captchaHeader string
+	}
+	var firstFiles, secondFiles capturedFiles
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/drive/v1/files", func(w http.ResponseWriter, r *http.Request) {
+		n := atomic.AddInt32(&filesCalls, 1)
+		switch n {
+		case 1:
+			firstFiles.captchaHeader = r.Header.Get("X-Captcha-Token")
+			writeErrorJSON(w, `{
+				"error_code": 9,
+				"error": "captcha_invalid",
+				"error_description": "Verification code is invalid"
+			}`)
+		case 2:
+			secondFiles.captchaHeader = r.Header.Get("X-Captcha-Token")
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"files": [], "next_page_token": ""}`))
+		default:
+			t.Errorf("unexpected /drive/v1/files call #%d", n)
+		}
+	})
+	mux.HandleFunc("/v1/shield/captcha/init", func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&captchaCalls, 1)
+		var body struct {
+			CaptchaToken string `json:"captcha_token"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&body)
+		if body.CaptchaToken != "" {
+			t.Errorf("captcha init body captcha_token = %q, want empty (error_code=9 path should clear cache)", body.CaptchaToken)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"captcha_token": "fresh-captcha", "expires_in": 300}`))
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	d.captchaToken = "expired-captcha"
+
+	if _, err := d.List(context.Background(), "any-parent"); err != nil {
+		t.Fatalf("List: %v", err)
+	}
+
+	if got := atomic.LoadInt32(&filesCalls); got != 2 {
+		t.Fatalf("/drive/v1/files calls = %d, want 2 (initial + retry)", got)
+	}
+	if got := atomic.LoadInt32(&captchaCalls); got != 1 {
+		t.Fatalf("captcha init calls = %d, want 1", got)
+	}
+	if firstFiles.captchaHeader != "expired-captcha" {
+		t.Errorf("first request X-Captcha-Token = %q, want \"expired-captcha\"", firstFiles.captchaHeader)
+	}
+	if secondFiles.captchaHeader != "fresh-captcha" {
+		t.Errorf("retry X-Captcha-Token = %q, want \"fresh-captcha\"", secondFiles.captchaHeader)
+	}
+	if d.captchaToken != "fresh-captcha" {
+		t.Errorf("d.captchaToken after recovery = %q, want \"fresh-captcha\"", d.captchaToken)
+	}
+}
+
 // TestRequestOnceDoesNotRetryTwiceOn4002 验证 4002 恢复路径只重试一次；
 // 如果重试请求依然失败（哪怕是再来一个 4002），也不会再次进入恢复逻辑，
 // 而是把错误返回出去，避免无限循环。

backend/internal/drives/pikpak/driver.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"log"
 	"net/http"
 	"path"
@@ -43,8 +44,10 @@ type Driver struct {
 	algorithms    []string
 	userAgent     string
 
-	client        *resty.Client
-	onTokenUpdate func(access, refresh, captcha, deviceID string)
+	client          *resty.Client
+	onTokenUpdate   func(access, refresh, captcha, deviceID string)
+	uploadToOSSFunc func(context.Context, *s3Params, io.Reader) error
+	uploadTempDir   string
 
 	// captchaMu serializes captcha-token refreshes triggered by 4002 / 9
 	// recovery in requestOnce. Without it, N concurrent callers all hitting
@@ -75,6 +78,7 @@ type Config struct {
 	DeviceID         string
 	RootID           string
 	DisableMediaLink bool
+	UploadTempDir    string
 	OnTokenUpdate    func(access, refresh, captcha, deviceID string)
 }
 
@@ -107,6 +111,7 @@ func New(c Config) *Driver {
 		deviceID:         deviceID,
 		disableMediaLink: c.DisableMediaLink,
 		onTokenUpdate:    c.OnTokenUpdate,
+		uploadTempDir:    strings.TrimSpace(c.UploadTempDir),
 		client: resty.New().
 			SetTimeout(30*time.Second).
 			SetHeader("Accept", "application/json, text/plain, */*"),
@@ -121,9 +126,28 @@ func (d *Driver) ID() string     { return d.id }
 func (d *Driver) RootID() string { return d.rootID }
 
 func (d *Driver) Init(ctx context.Context) error {
+	clearPersistedCaptcha := func() {
+		if d.captchaToken == "" {
+			return
+		}
+		d.captchaToken = ""
+		d.persistTokens()
+	}
+
 	if d.refreshToken != "" {
 		if err := d.refresh(ctx, d.refreshToken); err != nil {
-			return err
+			if !IsCaptchaError(err) || d.username == "" || d.password == "" {
+				return err
+			}
+			clearPersistedCaptcha()
+			if err := d.login(ctx); err != nil {
+				return fmt.Errorf("pikpak refresh captcha recovery login: %w", err)
+			}
+		} else {
+			// Persisted captcha tokens are short-lived. With a refresh token we can
+			// safely request a fresh captcha token after auth, and avoiding the
+			// stored value prevents known-stale tokens from poisoning startup.
+			clearPersistedCaptcha()
 		}
 	} else {
 		if err := d.login(ctx); err != nil {
@@ -154,8 +178,8 @@ func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error)
 
 // pikpakListCooldown 是列目录触发疑似限流错误时的冷却时长。
 //
-// 与 p115 driver 的 listCooldown 同语义：只要错误属 transient
-// （error_code=10 / HTTP 429 / 5xx / 通用 "rate limit" 文本），就持续
+// 与 p115 driver 的 listCooldown 同语义：只要错误属明确限流/临时状态
+// （结构化 error_code=10 / HTTP 429 / 5xx），就持续
 // 等 10 分钟再发一次列目录请求，直到成功或 ctx 取消。这样即使 PikPak
 // 风控持续较长时间，扫描会自然延后到风控结束，不再丢半棵子树。
 const pikpakListCooldown = 10 * time.Minute
@@ -221,7 +245,6 @@ func pikpakSleepContext(ctx context.Context, d time.Duration) error {
 //
 //   - PikPak 业务码 error_code=10 ("操作频繁"，见 OpenList drivers/pikpak/util.go)
 //   - HTTP 429 / 500 / 502 / 503 / 504 / 509（rclone 也把这些归为 retry）
-//   - 通用文本：rate limit / too many requests / blocked / temporarily unavailable
 //
 // 不包含 4122/4121/16（access_token 过期）和 9/4002（captcha 过期）—— 这些
 // 由 requestOnce 内部已经做过一次自动恢复重试；如果恢复后仍然报这类错误，
@@ -238,22 +261,14 @@ func isTransientPikPakListError(err error) bool {
 			return true
 		}
 	}
-	text := strings.ToLower(err.Error())
-	return strings.Contains(text, "error_code=10") ||
-		strings.Contains(text, "429") ||
-		strings.Contains(text, "http 500") ||
-		strings.Contains(text, "http 502") ||
-		strings.Contains(text, "http 503") ||
-		strings.Contains(text, "http 504") ||
-		strings.Contains(text, "http 509") ||
-		strings.Contains(text, "too many request") ||
-		strings.Contains(text, "too many requests") ||
-		strings.Contains(text, "rate limit") ||
-		strings.Contains(text, "operation frequent") ||
-		strings.Contains(text, "操作频繁") ||
-		strings.Contains(text, "blocked") ||
-		strings.Contains(text, "temporarily unavailable") ||
-		strings.Contains(text, "service unavailable")
+	return drives.ErrorMentionsHTTPStatus(err,
+		http.StatusTooManyRequests,
+		http.StatusInternalServerError,
+		http.StatusBadGateway,
+		http.StatusServiceUnavailable,
+		http.StatusGatewayTimeout,
+		509,
+	)
 }
 
 func (d *Driver) Stat(ctx context.Context, fileID string) (*drives.Entry, error) {
@@ -335,8 +350,74 @@ func (d *Driver) Rename(ctx context.Context, fileID, newName string) error {
 	return nil
 }
 
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return errors.New("pikpak remove: empty file id")
+	}
+	if err := d.request(ctx, filesURL+":batchTrash", http.MethodPost, func(req *resty.Request) {
+		req.SetBody(map[string]any{"ids": []string{fileID}})
+	}, nil); err != nil {
+		return fmt.Errorf("pikpak remove: %w", err)
+	}
+	return nil
+}
+
 func (d *Driver) EnsureDir(ctx context.Context, pathFromRoot string) (string, error) {
-	return "", drives.ErrNotSupported
+	currentID := d.rootID
+	for _, name := range splitPath(pathFromRoot) {
+		childID, err := d.findChildDir(ctx, currentID, name)
+		if err != nil {
+			return "", err
+		}
+		if childID == "" {
+			childID, err = d.makeDir(ctx, currentID, name)
+			if err != nil {
+				return "", err
+			}
+		}
+		currentID = childID
+	}
+	return currentID, nil
+}
+
+func (d *Driver) findChildDir(ctx context.Context, parentID, name string) (string, error) {
+	entries, err := d.List(ctx, parentID)
+	if err != nil {
+		return "", err
+	}
+	for _, e := range entries {
+		if e.IsDir && e.Name == name {
+			return e.ID, nil
+		}
+	}
+	return "", nil
+}
+
+func (d *Driver) makeDir(ctx context.Context, parentID, name string) (string, error) {
+	var out file
+	err := d.request(ctx, filesURL, http.MethodPost, func(req *resty.Request) {
+		req.SetBody(map[string]any{
+			"kind":      "drive#folder",
+			"parent_id": parentID,
+			"name":      name,
+		})
+	}, &out)
+	if err != nil {
+		return "", fmt.Errorf("pikpak mkdir %s: %w", name, err)
+	}
+	if out.ID == "" {
+		return "", fmt.Errorf("pikpak mkdir %s: empty folder id", name)
+	}
+	return out.ID, nil
+}
+
+func splitPath(p string) []string {
+	p = strings.Trim(p, "/")
+	if p == "" {
+		return nil
+	}
+	return strings.Split(p, "/")
 }
 
 func (d *Driver) getFiles(ctx context.Context, parentID string) ([]file, error) {
@@ -408,14 +489,15 @@ func (d *Driver) requestOnce(ctx context.Context, url, method string, configure
 				// serialized. Once we hold the lock, if d.captchaToken has
 				// already moved past staleToken, another goroutine has refreshed
 				// it for us — we skip the refresh and just retry. Otherwise we
-				// clear the cached token (4002 means "the value in the body is
-				// expired"; sending it again will keep returning 4002) and ask
-				// /v1/shield/captcha/init for a fresh one.
+				// clear the cached token before asking /v1/shield/captcha/init
+				// for a fresh one. PikPak may report stale captcha as either
+				// 4002 or 9, and sending the rejected token into captcha init can
+				// keep returning captcha_invalid.
 				staleToken := d.captchaToken
 				d.captchaMu.Lock()
 				var refreshErr error
 				if d.captchaToken == staleToken {
-					if e.ErrorCode == 4002 {
+					if d.captchaToken != "" {
 						d.captchaToken = ""
 					}
 					refreshErr = d.refreshCaptchaTokenAtLogin(ctx, getAction(method, url), d.userID)
@@ -490,3 +572,4 @@ func ParseBoolDefault(raw string, def bool) bool {
 }
 
 var _ drives.Drive = (*Driver)(nil)
+var _ drives.Remover = (*Driver)(nil)

backend/internal/drives/pikpak/driver_test.go

@@ -1,10 +1,12 @@
 package pikpak
 
 import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
 	"testing"
 	"time"
-
-	"github.com/video-site/backend/internal/drives"
 )
 
 func TestNewDefaults(t *testing.T) {
@@ -95,11 +97,85 @@ func TestFolderToEntry(t *testing.T) {
 	}
 }
 
-func TestEnsureDirStillUnsupported(t *testing.T) {
-	d := New(Config{ID: "pikpak-main"})
+func TestEnsureDirReusesExistingFolder(t *testing.T) {
+	var postCalled bool
+	mux := http.NewServeMux()
+	mux.HandleFunc("/drive/v1/files", func(w http.ResponseWriter, r *http.Request) {
+		switch r.Method {
+		case http.MethodGet:
+			if got := r.URL.Query().Get("parent_id"); got != "root-id" {
+				t.Fatalf("parent_id = %q, want root-id", got)
+			}
+			writePikPakJSON(t, w, map[string]any{
+				"files": []map[string]any{{
+					"id":   "existing-folder-id",
+					"kind": "drive#folder",
+					"name": "Crawler Uploads",
+				}},
+			})
+		case http.MethodPost:
+			postCalled = true
+			t.Fatalf("existing folder should not be created again")
+		default:
+			t.Fatalf("unexpected method %s", r.Method)
+		}
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
 
-	if _, err := d.EnsureDir(nil, "/previews"); err != drives.ErrNotSupported {
-		t.Fatalf("EnsureDir error = %v, want ErrNotSupported", err)
+	d := newTestDriver(t, srv)
+	got, err := d.EnsureDir(context.Background(), "Crawler Uploads")
+	if err != nil {
+		t.Fatalf("ensure dir: %v", err)
+	}
+	if got != "existing-folder-id" {
+		t.Fatalf("dir id = %q, want existing-folder-id", got)
+	}
+	if postCalled {
+		t.Fatal("POST should not be called")
+	}
+}
+
+func TestEnsureDirCreatesMissingFolder(t *testing.T) {
+	var got uploadRequestBody
+	mux := http.NewServeMux()
+	mux.HandleFunc("/drive/v1/files", func(w http.ResponseWriter, r *http.Request) {
+		switch r.Method {
+		case http.MethodGet:
+			writePikPakJSON(t, w, map[string]any{"files": []map[string]any{}})
+		case http.MethodPost:
+			if err := json.NewDecoder(r.Body).Decode(&got); err != nil {
+				t.Fatalf("decode create folder body: %v", err)
+			}
+			writePikPakJSON(t, w, map[string]any{
+				"id":   "new-folder-id",
+				"kind": "drive#folder",
+				"name": "Crawler Uploads",
+			})
+		default:
+			t.Fatalf("unexpected method %s", r.Method)
+		}
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	d := newTestDriver(t, srv)
+	id, err := d.EnsureDir(context.Background(), "Crawler Uploads")
+	if err != nil {
+		t.Fatalf("ensure dir: %v", err)
+	}
+	if id != "new-folder-id" {
+		t.Fatalf("dir id = %q, want new-folder-id", id)
+	}
+	if got.Kind != "drive#folder" || got.ParentID != "root-id" || got.Name != "Crawler Uploads" {
+		t.Fatalf("create folder body = %#v", got)
+	}
+}
+
+func writePikPakJSON(t *testing.T, w http.ResponseWriter, body any) {
+	t.Helper()
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		t.Fatalf("write json: %v", err)
 	}
-	// Upload 的真实实现见 upload_test.go。
 }

backend/internal/drives/pikpak/types.go

@@ -59,8 +59,12 @@ func (e *errResp) Error() string {
 	return fmt.Sprintf("pikpak error_code=%d error=%s description=%s", e.ErrorCode, e.ErrorMsg, e.ErrorDescription)
 }
 
+func isCaptchaTokenRejectedCode(code int64) bool {
+	return code == 9 || code == 4002
+}
+
 // APIError is the public alias for the PikPak API error response. Callers
-// outside this package (e.g. the spider91→PikPak migrator, tests) can either
+// outside this package (e.g. crawler upload workers and tests) can either
 // construct it for fakes or unwrap it via errors.As. Prefer IsCaptchaError
 // over hard-coding the numeric error codes.
 type APIError = errResp
@@ -76,7 +80,7 @@ func IsCaptchaError(err error) bool {
 	}
 	var e *errResp
 	if errors.As(err, &e) {
-		return e != nil && (e.ErrorCode == 4002 || e.ErrorCode == 9)
+		return e != nil && isCaptchaTokenRejectedCode(e.ErrorCode)
 	}
 	return false
 }

backend/internal/drives/pikpak/upload.go

@@ -6,7 +6,10 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log"
+	"net"
 	"net/http"
+	"net/url"
 	"os"
 	"strings"
 	"time"
@@ -26,7 +29,7 @@ import (
 //      - 未命中：resumable.params 含 S3 兼容凭证（access_key / secret /
 //        bucket / endpoint / key / security_token）
 //
-//   3. 用 Aliyun OSS SDK PutObject 把字节传到 endpoint+bucket+key
+//   3. 用 Aliyun OSS SDK PutObject 把字节传到 PikPak 返回的临时 OSS endpoint
 //
 //   4. PikPak 服务端轮询 OSS，发现完成后把 resp.File.ID 标记为可用；
 //      所以 Upload 完成后直接返回 resp.File.ID 即可（一开始就有，
@@ -36,9 +39,11 @@ const (
 	ossSecurityTokenHeaderName = "X-OSS-Security-Token"
 	ossUserAgent               = "aliyun-sdk-android/2.9.13(Linux/Android 14/M2004j7ac;UKQ1.231108.001)"
 	// 单次 PutObject 的硬上限（OSS 文档限制 5GiB；保守用 5GiB-1）。
-	// spider91 视频通常 ~100MiB，远低于该值。超过则需走 multipart，
-	// 当前未实现，遇到会显式报错。
+	// 超过该值需走 multipart；当前未实现，遇到会显式报错。
 	maxSinglePutSize = 5*1024*1024*1024 - 1
+	// 首次上传失败后最多再重试 3 次。每次重试都会重新申请 PikPak
+	// upload session，以避开偶发不可解析/不可达的临时上传 endpoint。
+	pikpakUploadMaxAttempts = 4
 )
 
 // uploadTaskData 是 POST /drive/v1/files 的响应结构。
@@ -73,6 +78,20 @@ type UploadResult struct {
 	Size   int64
 }
 
+type preparedUploadBody struct {
+	reader  io.ReadSeeker
+	start   int64
+	cleanup func()
+}
+
+func (b preparedUploadBody) rewind() error {
+	if b.reader == nil {
+		return errors.New("pikpak upload: nil upload body")
+	}
+	_, err := b.reader.Seek(b.start, io.SeekStart)
+	return err
+}
+
 // Upload 实现 drives.Drive 接口；只返回 fileID。
 // 完整上传元数据见 UploadAndReportHash。
 func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error) {
@@ -85,7 +104,7 @@ func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader,
 
 // UploadAndReportHash 上传并返回 file ID + GCID + 实际字节数。
 //
-// 用于 spider91 → PikPak 迁移 worker：上传完后直接把 hash 写回 catalog
+// 用于 crawler upload worker：上传完后直接把 hash 写回 catalog
 // 的 content_hash 字段，避免再读一次本地文件做 hash。
 //
 // 参数：
@@ -98,8 +117,7 @@ func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader,
 //   - 必须先算 GCID 再申请上传会话（PikPak API 要求 hash 字段），
 //     所以这里先 io.Copy 到临时文件并同步算 GCID。
 //   - 命中秒传时不发任何字节；否则用 OSS PutObject 上传。
-//   - 单次 PutObject 上限保守用 5GiB-1。spider91 视频远小于此值，
-//     超出该值会报错（暂不实现 multipart）。
+//   - 单次 PutObject 上限保守用 5GiB-1，超出该值会报错（暂不实现 multipart）。
 func (d *Driver) UploadAndReportHash(ctx context.Context, parentID, name string, r io.Reader, size int64) (UploadResult, error) {
 	if r == nil {
 		return UploadResult{}, errors.New("pikpak upload: nil reader")
@@ -119,23 +137,59 @@ func (d *Driver) UploadAndReportHash(ctx context.Context, parentID, name string,
 		parentID = d.rootID
 	}
 
-	// 1) 把 r 全量缓冲到临时文件，同时算 GCID。
-	tmp, gcidHex, actualSize, err := bufferAndHashGCID(r, size)
+	// 1) 算 GCID，并准备一个可重试读取的 body。爬虫迁移传入的是
+	// *os.File，可直接复用原文件，避免再占用一份视频大小的临时空间。
+	body, gcidHex, actualSize, err := d.prepareUploadBody(r, size)
 	if err != nil {
 		return UploadResult{}, err
 	}
-	defer func() {
-		_ = tmp.Close()
-		_ = os.Remove(tmp.Name())
-	}()
+	if body.cleanup != nil {
+		defer body.cleanup()
+	}
 
-	// 2) 申请上传会话。
+	result := UploadResult{Hash: gcidHex, Size: actualSize}
+	var lastErr error
+	for attempt := 1; attempt <= pikpakUploadMaxAttempts; attempt++ {
+		if err := ctx.Err(); err != nil {
+			return UploadResult{}, err
+		}
+
+		resp, err := d.requestUploadSession(ctx, parentID, name, actualSize, gcidHex)
+		if err != nil {
+			lastErr = fmt.Errorf("pikpak upload: request session: %w", err)
+			if !shouldRetryPikPakUploadAttempt(lastErr, attempt) {
+				return UploadResult{}, lastErr
+			}
+			d.logUploadRetry(name, attempt, lastErr)
+			if err := pikpakSleepContext(ctx, pikpakUploadRetryDelay(attempt)); err != nil {
+				return UploadResult{}, err
+			}
+			continue
+		}
+
+		out, err := d.completeUploadAttempt(ctx, body, parentID, name, result, resp)
+		if err == nil {
+			return out, nil
+		}
+		lastErr = err
+		if !shouldRetryPikPakUploadAttempt(lastErr, attempt) {
+			return UploadResult{}, lastErr
+		}
+		d.logUploadRetry(name, attempt, lastErr)
+		if err := pikpakSleepContext(ctx, pikpakUploadRetryDelay(attempt)); err != nil {
+			return UploadResult{}, err
+		}
+	}
+	return UploadResult{}, lastErr
+}
+
+func (d *Driver) requestUploadSession(ctx context.Context, parentID, name string, size int64, gcidHex string) (uploadTaskData, error) {
 	var resp uploadTaskData
 	if err := d.request(ctx, filesURL, http.MethodPost, func(req *resty.Request) {
 		req.SetBody(map[string]any{
 			"kind":        "drive#file",
 			"name":        name,
-			"size":        actualSize,
+			"size":        size,
 			"hash":        gcidHex,
 			"upload_type": "UPLOAD_TYPE_RESUMABLE",
 			"objProvider": map[string]any{"provider": "UPLOAD_TYPE_UNKNOWN"},
@@ -143,12 +197,13 @@ func (d *Driver) UploadAndReportHash(ctx context.Context, parentID, name string,
 			"folder_type": "NORMAL",
 		})
 	}, &resp); err != nil {
-		return UploadResult{}, fmt.Errorf("pikpak upload: request session: %w", err)
+		return uploadTaskData{}, err
 	}
+	return resp, nil
+}
 
-	result := UploadResult{Hash: gcidHex, Size: actualSize}
-
-	// 3) 命中秒传：服务端已经知道这个 hash，直接返回新文件 ID。
+func (d *Driver) completeUploadAttempt(ctx context.Context, body preparedUploadBody, parentID, name string, result UploadResult, resp uploadTaskData) (UploadResult, error) {
+	// 命中秒传：服务端已经知道这个 hash，直接返回新文件 ID。
 	if resp.Resumable == nil {
 		if resp.File.ID != "" {
 			result.FileID = resp.File.ID
@@ -163,15 +218,15 @@ func (d *Driver) UploadAndReportHash(ctx context.Context, parentID, name string,
 		return result, nil
 	}
 
-	// 4) 未命中秒传：把字节传到 S3 兼容存储。
-	if _, err := tmp.Seek(0, io.SeekStart); err != nil {
-		return UploadResult{}, fmt.Errorf("pikpak upload: seek tmp: %w", err)
+	// 未命中秒传：把字节传到 S3 兼容存储。
+	if err := body.rewind(); err != nil {
+		return UploadResult{}, fmt.Errorf("pikpak upload: rewind body: %w", err)
 	}
-	if err := d.uploadToOSS(ctx, &resp.Resumable.Params, tmp); err != nil {
+	if err := d.uploadToOSS(ctx, &resp.Resumable.Params, body.reader); err != nil {
 		return UploadResult{}, fmt.Errorf("pikpak upload: oss put: %w", err)
 	}
 
-	// 5) 拿到 fileID。优先走响应里的预分配 ID；为空就回查目录。
+	// 拿到 fileID。优先走响应里的预分配 ID；为空就回查目录。
 	if resp.File.ID != "" {
 		result.FileID = resp.File.ID
 		return result, nil
@@ -184,12 +239,114 @@ func (d *Driver) UploadAndReportHash(ctx context.Context, parentID, name string,
 	return result, nil
 }
 
+func shouldRetryPikPakUploadAttempt(err error, attempt int) bool {
+	return attempt < pikpakUploadMaxAttempts && isRetryablePikPakUploadError(err)
+}
+
+func pikpakUploadRetryDelay(attempt int) time.Duration {
+	if attempt <= 0 {
+		return 0
+	}
+	return time.Duration(attempt) * time.Second
+}
+
+func (d *Driver) logUploadRetry(name string, attempt int, err error) {
+	log.Printf("[pikpak] upload retry drive=%s name=%q next_attempt=%d/%d err=%v",
+		d.id, name, attempt+1, pikpakUploadMaxAttempts, err)
+}
+
+func isRetryablePikPakUploadError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return false
+	}
+	var serviceErr oss.ServiceError
+	if errors.As(err, &serviceErr) {
+		return serviceErr.StatusCode == http.StatusTooManyRequests || serviceErr.StatusCode >= 500
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return true
+	}
+	text := strings.ToLower(err.Error())
+	return strings.Contains(text, "no such host") ||
+		strings.Contains(text, "temporary failure in name resolution") ||
+		strings.Contains(text, "server misbehaving") ||
+		strings.Contains(text, "connection reset") ||
+		strings.Contains(text, "connection refused") ||
+		strings.Contains(text, "broken pipe") ||
+		strings.Contains(text, "eof") ||
+		strings.Contains(text, "i/o timeout") ||
+		strings.Contains(text, "tls handshake timeout") ||
+		strings.Contains(text, "http 429") ||
+		strings.Contains(text, "http 500") ||
+		strings.Contains(text, "http 502") ||
+		strings.Contains(text, "http 503") ||
+		strings.Contains(text, "http 504") ||
+		strings.Contains(text, "http 509") ||
+		strings.Contains(text, "too many requests") ||
+		strings.Contains(text, "temporarily unavailable") ||
+		strings.Contains(text, "service unavailable")
+}
+
+func (d *Driver) prepareUploadBody(r io.Reader, size int64) (preparedUploadBody, string, int64, error) {
+	if rs, ok := r.(io.ReadSeeker); ok {
+		gcidHex, actualSize, start, err := hashGCIDFromReadSeeker(rs, size)
+		if err != nil {
+			return preparedUploadBody{}, "", 0, err
+		}
+		return preparedUploadBody{reader: rs, start: start, cleanup: func() {}}, gcidHex, actualSize, nil
+	}
+
+	tmp, gcidHex, actualSize, err := bufferAndHashGCID(d.uploadTempDir, r, size)
+	if err != nil {
+		return preparedUploadBody{}, "", 0, err
+	}
+	return preparedUploadBody{
+		reader: tmp,
+		start:  0,
+		cleanup: func() {
+			_ = tmp.Close()
+			_ = os.Remove(tmp.Name())
+		},
+	}, gcidHex, actualSize, nil
+}
+
+func hashGCIDFromReadSeeker(r io.ReadSeeker, size int64) (string, int64, int64, error) {
+	start, err := r.Seek(0, io.SeekCurrent)
+	if err != nil {
+		return "", 0, 0, fmt.Errorf("pikpak upload: seek body: %w", err)
+	}
+
+	h := NewGCID(size)
+	written, copyErr := io.Copy(h, r)
+	_, seekErr := r.Seek(start, io.SeekStart)
+	if copyErr != nil {
+		return "", 0, start, fmt.Errorf("pikpak upload: hash body: %w", copyErr)
+	}
+	if seekErr != nil {
+		return "", 0, start, fmt.Errorf("pikpak upload: rewind body: %w", seekErr)
+	}
+	if size > 0 && written != size {
+		return "", 0, start, fmt.Errorf("pikpak upload: size mismatch: declared %d, copied %d", size, written)
+	}
+	return strings.ToUpper(hex.EncodeToString(h.Sum(nil))), written, start, nil
+}
+
 // bufferAndHashGCID 把 r 复制到一个临时文件，同时计算 GCID。
-// 返回临时文件（位置在末尾，需要调用方 Seek 回 0）、GCID hex 大写、实际写入字节数。
+// 返回临时文件（位置在末尾，需要调用方 Seek 回 start）、GCID hex 大写、实际写入字节数。
 //
 // 调用方负责 Close + Remove 临时文件。
-func bufferAndHashGCID(r io.Reader, size int64) (*os.File, string, int64, error) {
-	tmp, err := os.CreateTemp("", "pikpak-upload-*.bin")
+func bufferAndHashGCID(tempDir string, r io.Reader, size int64) (*os.File, string, int64, error) {
+	tempDir = strings.TrimSpace(tempDir)
+	if tempDir != "" {
+		if err := os.MkdirAll(tempDir, 0o755); err != nil {
+			return nil, "", 0, fmt.Errorf("pikpak upload: create tmp dir: %w", err)
+		}
+	}
+	tmp, err := os.CreateTemp(tempDir, "pikpak-upload-*.bin")
 	if err != nil {
 		return nil, "", 0, fmt.Errorf("pikpak upload: create tmp: %w", err)
 	}
@@ -215,10 +372,13 @@ func bufferAndHashGCID(r io.Reader, size int64) (*os.File, string, int64, error)
 //
 // 参数复用 PikPak 的临时凭证；必须带 Security Token 头部 + UserAgent，与 OpenList 一致。
 func (d *Driver) uploadToOSS(ctx context.Context, p *s3Params, body io.Reader) error {
+	if d.uploadToOSSFunc != nil {
+		return d.uploadToOSSFunc(ctx, p, body)
+	}
 	if p == nil {
 		return errors.New("pikpak upload: nil s3 params")
 	}
-	client, err := oss.New(p.Endpoint, p.AccessKeyID, p.AccessKeySecret)
+	client, err := newPikPakOSSClient(p)
 	if err != nil {
 		return fmt.Errorf("oss client: %w", err)
 	}
@@ -235,6 +395,44 @@ func (d *Driver) uploadToOSS(ctx context.Context, p *s3Params, body io.Reader) e
 	)
 }
 
+func newPikPakOSSClient(p *s3Params, options ...oss.ClientOption) (*oss.Client, error) {
+	if p == nil {
+		return nil, errors.New("pikpak upload: nil s3 params")
+	}
+	clientOptions := make([]oss.ClientOption, 0, len(options)+1)
+	if isPikPakCNAMEEndpoint(p.Endpoint) {
+		clientOptions = append(clientOptions, oss.UseCname(true))
+	}
+	clientOptions = append(clientOptions, options...)
+	return oss.New(p.Endpoint, p.AccessKeyID, p.AccessKeySecret, clientOptions...)
+}
+
+func isPikPakCNAMEEndpoint(endpoint string) bool {
+	host := endpointHost(endpoint)
+	if host == "" {
+		return false
+	}
+	host = strings.TrimSuffix(strings.ToLower(host), ".")
+	return host != "mypikpak.com" && host != "mypikpak.net" &&
+		(strings.HasSuffix(host, ".mypikpak.com") || strings.HasSuffix(host, ".mypikpak.net"))
+}
+
+func endpointHost(endpoint string) string {
+	endpoint = strings.TrimSpace(endpoint)
+	if endpoint == "" {
+		return ""
+	}
+	if u, err := url.Parse(endpoint); err == nil && u.Host != "" {
+		endpoint = u.Host
+	} else if idx := strings.IndexByte(endpoint, '/'); idx >= 0 {
+		endpoint = endpoint[:idx]
+	}
+	if host, _, err := net.SplitHostPort(endpoint); err == nil {
+		endpoint = host
+	}
+	return strings.Trim(endpoint, "[]")
+}
+
 type readerWithCtx struct {
 	ctx context.Context
 	r   io.Reader

backend/internal/drives/pikpak/upload_test.go

@@ -6,12 +6,17 @@ import (
 	"crypto/sha1"
 	"encoding/hex"
 	"encoding/json"
+	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
+	"github.com/aliyun/aliyun-oss-go-sdk/oss"
 	"github.com/go-resty/resty/v2"
 )
 
@@ -139,6 +144,80 @@ func TestUploadInstantSuccessReturnsFileID(t *testing.T) {
 	}
 }
 
+func TestUploadUsesReadSeekerWithoutTempCopy(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/drive/v1/files", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"upload_type": "UPLOAD_TYPE_RESUMABLE",
+			"resumable":   null,
+			"file":        {"id": "instant-file-id", "name": "test.mp4", "kind": "drive#file"}
+		}`))
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	uploadTempDir := filepath.Join(t.TempDir(), "upload-tmp")
+	d.uploadTempDir = uploadTempDir
+
+	data := bytes.Repeat([]byte{0x31}, 1024)
+	path := filepath.Join(t.TempDir(), "video.bin")
+	if err := os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatalf("write source: %v", err)
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		t.Fatalf("open source: %v", err)
+	}
+	defer f.Close()
+
+	id, err := d.Upload(context.Background(), "parent-id", "test.mp4", f, int64(len(data)))
+	if err != nil {
+		t.Fatalf("upload: %v", err)
+	}
+	if id != "instant-file-id" {
+		t.Fatalf("file id = %q, want instant-file-id", id)
+	}
+	if _, err := os.Stat(uploadTempDir); !os.IsNotExist(err) {
+		t.Fatalf("upload temp dir stat err = %v, want not created for read seeker input", err)
+	}
+}
+
+func TestUploadBuffersNonSeekReaderInConfiguredTempDir(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/drive/v1/files", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"upload_type": "UPLOAD_TYPE_RESUMABLE",
+			"resumable":   null,
+			"file":        {"id": "instant-file-id", "name": "test.mp4", "kind": "drive#file"}
+		}`))
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	uploadTempDir := filepath.Join(t.TempDir(), "upload-tmp")
+	d.uploadTempDir = uploadTempDir
+
+	data := bytes.Repeat([]byte{0x42}, 1024)
+	id, err := d.Upload(context.Background(), "parent-id", "test.mp4", bytes.NewBuffer(data), int64(len(data)))
+	if err != nil {
+		t.Fatalf("upload: %v", err)
+	}
+	if id != "instant-file-id" {
+		t.Fatalf("file id = %q, want instant-file-id", id)
+	}
+	entries, err := os.ReadDir(uploadTempDir)
+	if err != nil {
+		t.Fatalf("read upload temp dir: %v", err)
+	}
+	if len(entries) != 0 {
+		t.Fatalf("upload temp dir entries = %d, want cleaned", len(entries))
+	}
+}
+
 func TestUploadInstantSuccessFallsBackToListWhenFileIDMissing(t *testing.T) {
 	listCalled := false
 	mux := http.NewServeMux()
@@ -181,6 +260,95 @@ func TestUploadInstantSuccessFallsBackToListWhenFileIDMissing(t *testing.T) {
 	}
 }
 
+func TestUploadRetriesWithNewSessionWhenOSSEndpointDNSFails(t *testing.T) {
+	sessionRequests := 0
+	mux := http.NewServeMux()
+	mux.HandleFunc("/drive/v1/files", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			t.Errorf("method = %q, want POST", r.Method)
+		}
+		sessionRequests++
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(fmt.Sprintf(`{
+			"upload_type": "UPLOAD_TYPE_RESUMABLE",
+			"resumable": {
+				"kind": "drive#resumable",
+				"provider": "UPLOAD_TYPE_UNKNOWN",
+				"params": {
+					"access_key_id": "ak",
+					"access_key_secret": "sk",
+					"bucket": "bucket",
+					"endpoint": "https://vip-lixian-%02d.upload-a10b.mypikpak.com",
+					"key": "object-key-%02d",
+					"security_token": "token"
+				}
+			},
+			"file": {"id": "retry-file-%02d", "name": "retry.mp4", "kind": "drive#file"}
+		}`, sessionRequests, sessionRequests, sessionRequests)))
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	d := newTestDriver(t, server)
+	uploadAttempts := 0
+	var uploaded []byte
+	d.uploadToOSSFunc = func(_ context.Context, _ *s3Params, body io.Reader) error {
+		uploadAttempts++
+		if uploadAttempts == 1 {
+			return &net.DNSError{Err: "no such host", Name: "vip-lixian-01.upload-a10b.mypikpak.com"}
+		}
+		var err error
+		uploaded, err = io.ReadAll(body)
+		return err
+	}
+
+	payload := []byte("retry payload body")
+	id, err := d.Upload(context.Background(), "parent-id", "retry.mp4", bytes.NewReader(payload), int64(len(payload)))
+	if err != nil {
+		t.Fatalf("upload: %v", err)
+	}
+	if id != "retry-file-02" {
+		t.Fatalf("file id = %q, want retry-file-02 from the second session", id)
+	}
+	if sessionRequests != 2 {
+		t.Fatalf("session requests = %d, want 2", sessionRequests)
+	}
+	if uploadAttempts != 2 {
+		t.Fatalf("upload attempts = %d, want 2", uploadAttempts)
+	}
+	if !bytes.Equal(uploaded, payload) {
+		t.Fatalf("uploaded body = %q, want %q", string(uploaded), string(payload))
+	}
+}
+
+func TestPikPakOSSClientUsesCNAMEForPikPakUploadEndpoint(t *testing.T) {
+	params := &s3Params{
+		AccessKeyID:     "ak",
+		AccessKeySecret: "sk",
+		Bucket:          "vip-lixian-07",
+		Endpoint:        "http://upload-a10b.mypikpak.com",
+		Key:             "upload_tmp/object-key",
+	}
+	client, err := newPikPakOSSClient(params)
+	if err != nil {
+		t.Fatalf("new oss client: %v", err)
+	}
+	bucket, err := client.Bucket(params.Bucket)
+	if err != nil {
+		t.Fatalf("bucket: %v", err)
+	}
+	signed, err := bucket.SignURL(params.Key, oss.HTTPPut, 60)
+	if err != nil {
+		t.Fatalf("sign url: %v", err)
+	}
+	if strings.Contains(signed, "vip-lixian-07.upload-a10b.mypikpak.com") {
+		t.Fatalf("signed url uses invalid bucket-prefixed PikPak host: %s", signed)
+	}
+	if !strings.Contains(signed, "http://upload-a10b.mypikpak.com/upload_tmp%2Fobject-key") {
+		t.Fatalf("signed url = %s, want PikPak endpoint host with object key path", signed)
+	}
+}
+
 func TestUploadRejectsInvalidArguments(t *testing.T) {
 	d := New(Config{ID: "x", Username: "u", Password: "p", Platform: "web"})
 	cases := []struct {
@@ -212,7 +380,7 @@ func TestUploadRejectsInvalidArguments(t *testing.T) {
 func TestBufferAndHashGCIDDetectsSizeMismatch(t *testing.T) {
 	src := bytes.NewReader([]byte("hello"))
 	// 声明 size=10 但实际只有 5 字节
-	_, _, _, err := bufferAndHashGCID(src, 10)
+	_, _, _, err := bufferAndHashGCID("", src, 10)
 	if err == nil {
 		t.Fatal("expected size mismatch error")
 	}
@@ -223,7 +391,7 @@ func TestBufferAndHashGCIDDetectsSizeMismatch(t *testing.T) {
 
 func TestBufferAndHashGCIDComputesCorrectHash(t *testing.T) {
 	data := bytes.Repeat([]byte{0x55}, 1024)
-	tmp, hex, written, err := bufferAndHashGCID(bytes.NewReader(data), int64(len(data)))
+	tmp, hex, written, err := bufferAndHashGCID("", bytes.NewReader(data), int64(len(data)))
 	if err != nil {
 		t.Fatalf("buffer: %v", err)
 	}

backend/internal/drives/quark/driver.go

@@ -16,23 +16,23 @@ import (
 )
 
 const (
-	defaultUA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) quark-cloud-drive/2.5.20 Chrome/100.0.4896.160 Electron/18.3.5.4-b478491100 Safari/537.36 Channel/pckk_other_ch"
+	defaultUA      = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) quark-cloud-drive/2.5.20 Chrome/100.0.4896.160 Electron/18.3.5.4-b478491100 Safari/537.36 Channel/pckk_other_ch"
 	defaultReferer = "https://pan.quark.cn"
 	defaultAPI     = "https://drive.quark.cn/1/clouddrive"
 	defaultPR      = "ucpro"
 )
 
 type Driver struct {
-	id                     string
-	cookie                 string
-	rootID                 string
-	ua                     string
-	referer                string
-	apiBase                string
-	pr                     string
-	client                 *resty.Client
-	onCookieUpdate         func(string)
-	useTranscodingAddress  bool
+	id                    string
+	cookie                string
+	rootID                string
+	ua                    string
+	referer               string
+	apiBase               string
+	pr                    string
+	client                *resty.Client
+	onCookieUpdate        func(string)
+	useTranscodingAddress bool
 }
 
 type Config struct {
@@ -60,7 +60,7 @@ func New(c Config) *Driver {
 		onCookieUpdate:        c.OnCookieUpdate,
 	}
 	d.client = resty.New().
-		SetTimeout(30 * time.Second).
+		SetTimeout(30*time.Second).
 		SetHeader("Accept", "application/json, text/plain, */*").
 		SetHeader("Referer", d.referer).
 		SetHeader("User-Agent", d.ua)
@@ -263,12 +263,28 @@ func (d *Driver) findChildDir(ctx context.Context, parent, name string) (string,
 	return "", nil
 }
 
-// ---------- 上传（第一版不实现，走本地 teaser 兜底） ----------
+// ---------- 上传（第一版不实现，走本地预览视频兜底） ----------
 
 func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error) {
 	return "", drives.ErrNotSupported
 }
 
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return errors.New("quark remove: empty file id")
+	}
+	body := map[string]any{
+		"action_type":  1,
+		"exclude_fids": []string{},
+		"filelist":     []string{fileID},
+	}
+	if err := d.request(ctx, "/file/delete", http.MethodPost, nil, body, nil); err != nil {
+		return fmt.Errorf("quark remove: %w", err)
+	}
+	return nil
+}
+
 // ---------- helpers ----------
 
 func fileToEntry(f *file, parentID string) drives.Entry {
@@ -343,3 +359,4 @@ func setCookieValue(cookie, key, value string) string {
 }
 
 var _ drives.Drive = (*Driver)(nil)
+var _ drives.Remover = (*Driver)(nil)

backend/internal/drives/scriptcrawler/crawler_test.go

@@ -0,0 +1,986 @@
+package scriptcrawler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/fingerprint"
+	"github.com/video-site/backend/internal/mediaasset"
+)
+
+const (
+	scriptCrawlerDuplicateBytes = "duplicate-video-bytes"
+	scriptCrawlerUniqueBytes    = "unique-video-bytes"
+)
+
+func writeScriptCrawlerFFprobeStub(t *testing.T, dir string, ok bool) string {
+	t.Helper()
+	name := "ffprobe-ok.sh"
+	body := "#!/bin/sh\necho video\nexit 0\n"
+	if !ok {
+		name = "ffprobe-fail.sh"
+		body = "#!/bin/sh\necho 'moov atom not found' >&2\nexit 1\n"
+	}
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, []byte(body), 0o755); err != nil {
+		t.Fatalf("write ffprobe stub: %v", err)
+	}
+	return path
+}
+
+func writeScriptCrawlerFFmpegStub(t *testing.T, dir string) string {
+	t.Helper()
+	path := filepath.Join(dir, "ffmpeg-hls.sh")
+	body := "#!/bin/sh\nif [ -n \"$GO_SCRIPTCRAWLER_FFMPEG_ARGS_FILE\" ]; then printf '%s\\n' \"$@\" > \"$GO_SCRIPTCRAWLER_FFMPEG_ARGS_FILE\"; fi\nout=\"\"\nfor arg do out=\"$arg\"; done\nprintf 'hls-video-bytes' > \"$out\"\n"
+	if err := os.WriteFile(path, []byte(body), 0o755); err != nil {
+		t.Fatalf("write ffmpeg stub: %v", err)
+	}
+	return path
+}
+
+func writeScriptCrawlerJPEG(t *testing.T, path string, c color.RGBA) {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, 48, 48))
+	for y := 0; y < 48; y++ {
+		for x := 0; x < 48; x++ {
+			img.SetRGBA(x, y, c)
+		}
+	}
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatalf("create jpeg: %v", err)
+	}
+	defer f.Close()
+	if err := jpeg.Encode(f, img, &jpeg.Options{Quality: 95}); err != nil {
+		t.Fatalf("encode jpeg: %v", err)
+	}
+}
+
+func TestCrawlerRunOnceImportsLocalFileAndSkipsExisting(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		CrawlerName: "Demo Crawler",
+		PythonPath:  wrapper,
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:  dummyScript,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Skipped != 0 || res.Failed != 0 {
+		t.Fatalf("result = new:%d skipped:%d failed:%d, want 1/0/0", res.NewVideos, res.Skipped, res.Failed)
+	}
+	v, err := cat.GetVideo(ctx, BuildVideoID("demo", "abc-123"))
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if v.Title != "Imported From Helper" || v.FileID != "abc-123.mp4" || v.Size == 0 {
+		t.Fatalf("video = title:%q file:%q size:%d", v.Title, v.FileID, v.Size)
+	}
+	if !hasString(v.Tags, "Demo Crawler") {
+		t.Fatalf("video tags = %#v, want crawler name tag", v.Tags)
+	}
+	if _, err := os.Stat(filepath.Join(drv.VideosDir(), "abc-123.mp4")); err != nil {
+		t.Fatalf("video file not copied: %v", err)
+	}
+
+	res, err = c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("second run: %v", err)
+	}
+	if res.NewVideos != 0 || res.Skipped != 1 {
+		t.Fatalf("second result = new:%d skipped:%d, want 0/1", res.NewVideos, res.Skipped)
+	}
+	if res.SeenSnapshot != 1 {
+		t.Fatalf("seen snapshot = %d, want 1", res.SeenSnapshot)
+	}
+}
+
+func TestCrawlerRunOnceMarksPreviewDisabledWhenConfigured(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:         drv,
+		Catalog:        cat,
+		PythonPath:     wrapper,
+		FFprobePath:    writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:     dummyScript,
+		DisablePreview: true,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Failed != 0 {
+		t.Fatalf("result = new:%d failed:%d, want 1/0", res.NewVideos, res.Failed)
+	}
+	v, err := cat.GetVideo(ctx, BuildVideoID("demo", "abc-123"))
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if v.PreviewStatus != "disabled" {
+		t.Fatalf("preview status = %q, want disabled", v.PreviewStatus)
+	}
+	if v.FingerprintStatus != "ready" || v.SampledSHA256 == "" {
+		t.Fatalf("fingerprint status=%q sampled=%q, want ready and sampled hash", v.FingerprintStatus, v.SampledSHA256)
+	}
+	pending, err := cat.ListVideosByPreviewStatus(ctx, "demo", "pending", 0)
+	if err != nil {
+		t.Fatalf("list pending previews: %v", err)
+	}
+	if len(pending) != 0 {
+		t.Fatalf("pending previews = %d, want 0", len(pending))
+	}
+}
+
+func TestCrawlerRunOnceUsesCurrentDrivePreviewSwitch(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	if err := cat.UpsertDrive(ctx, &catalog.Drive{
+		ID:            drv.ID(),
+		Kind:          Kind,
+		Name:          "Demo",
+		RootID:        "/",
+		Credentials:   map[string]string{"script_path": "/tmp/crawler.py"},
+		TeaserEnabled: true,
+	}); err != nil {
+		t.Fatalf("seed drive: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:         drv,
+		Catalog:        cat,
+		PythonPath:     wrapper,
+		FFprobePath:    writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:     dummyScript,
+		DisablePreview: true,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Failed != 0 {
+		t.Fatalf("result = new:%d failed:%d, want 1/0", res.NewVideos, res.Failed)
+	}
+	v, err := cat.GetVideo(ctx, BuildVideoID("demo", "abc-123"))
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if v.PreviewStatus != "pending" {
+		t.Fatalf("preview status = %q, want pending from current drive switch", v.PreviewStatus)
+	}
+}
+
+func TestCrawlerRunOnceUsesDefaultCrawlerNamespace(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		PythonPath:  wrapper,
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:  dummyScript,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.SeenSnapshot != 0 {
+		t.Fatalf("result = new:%d seen:%d, want 1/0", res.NewVideos, res.SeenSnapshot)
+	}
+	videoID := BuildVideoID("demo", "abc-123")
+	if _, err := cat.GetVideo(ctx, videoID); err != nil {
+		t.Fatalf("get crawler video: %v", err)
+	}
+
+	res, err = c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("second run: %v", err)
+	}
+	if res.NewVideos != 0 || res.Skipped != 1 || res.SeenSnapshot != 1 {
+		t.Fatalf("second result = new:%d skipped:%d seen:%d, want 0/1/1", res.NewVideos, res.Skipped, res.SeenSnapshot)
+	}
+}
+
+func TestCrawlerRunOncePassesAbsoluteJobPathsWhenWorkDirDiffers(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	t.Chdir(tmp)
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join("data", "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	scriptDir := filepath.Join(tmp, "scripts")
+	if err := os.MkdirAll(scriptDir, 0o755); err != nil {
+		t.Fatalf("mkdir script dir: %v", err)
+	}
+	dummyScript := filepath.Join(scriptDir, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_ASSERT_ABS", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		PythonPath:  wrapper,
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:  dummyScript,
+		WorkDir:     scriptDir,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Skipped != 0 || res.Failed != 0 {
+		t.Fatalf("result = new:%d skipped:%d failed:%d, want 1/0/0", res.NewVideos, res.Skipped, res.Failed)
+	}
+	if !filepath.IsAbs(res.JobFile) || !filepath.IsAbs(res.SeenFile) {
+		t.Fatalf("result paths should be absolute: job=%q seen=%q", res.JobFile, res.SeenFile)
+	}
+}
+
+func TestCrawlerRunOnceImportsSimpleMediaURLWithoutSourceID(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/video.mp4" {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = w.Write([]byte("simple-video-bytes"))
+	}))
+	defer srv.Close()
+
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_SIMPLE", "1")
+	t.Setenv("GO_SCRIPTCRAWLER_MEDIA_URL", srv.URL+"/video.mp4?token=first")
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		PythonPath:  wrapper,
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:  dummyScript,
+		HTTPClient:  srv.Client(),
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Skipped != 0 || res.Failed != 0 {
+		t.Fatalf("result = new:%d skipped:%d failed:%d, want 1/0/0", res.NewVideos, res.Skipped, res.Failed)
+	}
+	videos, err := cat.ListVideosByDrive(ctx, "demo")
+	if err != nil {
+		t.Fatalf("list videos: %v", err)
+	}
+	if len(videos) != 1 {
+		t.Fatalf("videos = %d, want 1", len(videos))
+	}
+	v := videos[0]
+	if !strings.HasPrefix(v.ID, BuildVideoID("demo", "auto-")) {
+		t.Fatalf("video id = %q, want generated auto source id", v.ID)
+	}
+	if v.Title != "Simple Protocol Video" || v.Ext != "mp4" || v.ThumbnailURL != "" || v.Size == 0 {
+		t.Fatalf("video = title:%q ext:%q thumb:%q size:%d", v.Title, v.Ext, v.ThumbnailURL, v.Size)
+	}
+	if _, err := os.Stat(filepath.Join(drv.VideosDir(), v.FileID)); err != nil {
+		t.Fatalf("video file not downloaded: %v", err)
+	}
+
+	t.Setenv("GO_SCRIPTCRAWLER_MEDIA_URL", srv.URL+"/video.mp4?token=second")
+	res, err = c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("second run: %v", err)
+	}
+	if res.NewVideos != 0 || res.Skipped != 1 {
+		t.Fatalf("second result = new:%d skipped:%d, want 0/1", res.NewVideos, res.Skipped)
+	}
+}
+
+func TestCrawlerRunOnceSkipsFingerprintDuplicateAndContinues(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+
+	seedFile := "seed-canonical.mp4"
+	if err := os.WriteFile(filepath.Join(drv.VideosDir(), seedFile), []byte(scriptCrawlerDuplicateBytes), 0o644); err != nil {
+		t.Fatalf("write seed video: %v", err)
+	}
+	seed := &catalog.Video{
+		ID:          "seed-for-hash",
+		DriveID:     drv.ID(),
+		FileID:      seedFile,
+		Title:       "Seed",
+		Size:        int64(len(scriptCrawlerDuplicateBytes)),
+		PublishedAt: time.Now(),
+	}
+	sampled, err := fingerprint.Compute(ctx, drv, seed, fingerprint.Config{}, nil)
+	if err != nil {
+		t.Fatalf("compute seed fingerprint: %v", err)
+	}
+	_ = os.Remove(filepath.Join(drv.VideosDir(), seedFile))
+
+	now := time.Now()
+	if err := cat.UpsertVideo(ctx, &catalog.Video{
+		ID:                "existing-canonical",
+		DriveID:           "other-drive",
+		FileID:            "existing.mp4",
+		FileName:          "existing.mp4",
+		Title:             "Existing Canonical",
+		Size:              int64(len(scriptCrawlerDuplicateBytes)),
+		Ext:               "mp4",
+		SampledSHA256:     sampled,
+		FingerprintStatus: "ready",
+		PublishedAt:       now,
+		CreatedAt:         now,
+		UpdatedAt:         now,
+	}); err != nil {
+		t.Fatalf("seed canonical video: %v", err)
+	}
+
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_DUP_UNIQUE", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		PythonPath:  wrapper,
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:  dummyScript,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Skipped != 1 || res.Failed != 0 || res.TotalEntries != 2 {
+		t.Fatalf("result = total:%d new:%d skipped:%d failed:%d, want 2/1/1/0", res.TotalEntries, res.NewVideos, res.Skipped, res.Failed)
+	}
+	if res.CandidateBudget <= res.TargetNew {
+		t.Fatalf("candidate budget = %d, target = %d; want expanded budget", res.CandidateBudget, res.TargetNew)
+	}
+	if _, err := cat.GetVideo(ctx, BuildVideoID("demo", "dup-source")); err == nil {
+		t.Fatal("duplicate candidate should not be imported")
+	}
+	if _, err := os.Stat(filepath.Join(drv.VideosDir(), "dup-source.mp4")); !os.IsNotExist(err) {
+		t.Fatalf("duplicate local file stat = %v, want removed", err)
+	}
+	v, err := cat.GetVideo(ctx, BuildVideoID("demo", "unique-source"))
+	if err != nil {
+		t.Fatalf("unique video should be imported: %v", err)
+	}
+	if v.SampledSHA256 == "" || v.FingerprintStatus != "ready" {
+		t.Fatalf("unique fingerprint = %q status=%q, want ready sampled fingerprint", v.SampledSHA256, v.FingerprintStatus)
+	}
+	seen, err := cat.ListCrawlerSourceIDs(ctx, Kind, "demo")
+	if err != nil {
+		t.Fatalf("list seen source ids: %v", err)
+	}
+	seenSet := map[string]bool{}
+	for _, id := range seen {
+		seenSet[id] = true
+	}
+	if !seenSet["dup-source"] || !seenSet["unique-source"] {
+		t.Fatalf("seen ids = %#v, want duplicate and imported source ids", seen)
+	}
+}
+
+func TestCrawlerProcessItemSkipsNearDuplicateByTitleDurationAndThumbnail(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	commonThumbDir := filepath.Join(tmp, "common-thumbs")
+	if err := os.MkdirAll(commonThumbDir, 0o755); err != nil {
+		t.Fatalf("mkdir common thumbs: %v", err)
+	}
+
+	now := time.Now()
+	canonicalID := "existing-canonical"
+	if err := cat.UpsertVideo(ctx, &catalog.Video{
+		ID:              canonicalID,
+		DriveID:         "other-drive",
+		FileID:          "existing.mp4",
+		FileName:        "existing.mp4",
+		Title:           "91 Test Similar Title 1215516",
+		DurationSeconds: 257,
+		Size:            12345,
+		Ext:             "mp4",
+		ThumbnailURL:    "/p/thumb/" + canonicalID,
+		PublishedAt:     now,
+		CreatedAt:       now,
+		UpdatedAt:       now,
+	}); err != nil {
+		t.Fatalf("seed canonical video: %v", err)
+	}
+	writeScriptCrawlerJPEG(t, mediaasset.ThumbnailPathInDir(commonThumbDir, canonicalID), color.RGBA{R: 210, G: 40, B: 40, A: 255})
+
+	outputDir := drv.OutputDir()
+	mediaPath := filepath.Join(outputDir, "near-video.mp4")
+	if err := os.WriteFile(mediaPath, []byte("near-duplicate-but-different-bytes"), 0o644); err != nil {
+		t.Fatalf("write media: %v", err)
+	}
+	thumbPath := filepath.Join(outputDir, "near-thumb.jpg")
+	writeScriptCrawlerJPEG(t, thumbPath, color.RGBA{R: 211, G: 41, B: 41, A: 255})
+
+	c := NewCrawler(CrawlerConfig{
+		Driver:         drv,
+		Catalog:        cat,
+		FFprobePath:    writeScriptCrawlerFFprobeStub(t, tmp, true),
+		CommonThumbDir: commonThumbDir,
+	})
+	imported, err := c.processItem(ctx, Item{
+		SourceID:        "near-source",
+		Title:           "91 Test Similar Title 1215516 - source suffix",
+		Author:          "helper",
+		DurationSeconds: 257,
+		Media:           MediaRef{LocalFile: mediaPath},
+		Thumbnail:       MediaRef{LocalFile: thumbPath},
+	})
+	if err != nil {
+		t.Fatalf("process item: %v", err)
+	}
+	if imported {
+		t.Fatal("near duplicate imported, want skipped")
+	}
+	if _, err := cat.GetVideo(ctx, BuildVideoID("demo", "near-source")); err == nil {
+		t.Fatal("near duplicate should not be inserted into catalog")
+	}
+	if _, err := os.Stat(filepath.Join(drv.VideosDir(), "near-source.mp4")); !os.IsNotExist(err) {
+		t.Fatalf("near duplicate video stat = %v, want removed", err)
+	}
+	if sourceThumb, err := drv.ThumbPath("near-source.jpg"); err != nil {
+		t.Fatalf("source thumb path: %v", err)
+	} else if _, err := os.Stat(sourceThumb); !os.IsNotExist(err) {
+		t.Fatalf("source thumb stat = %v, want removed", err)
+	}
+	if _, err := os.Stat(mediaasset.ThumbnailPathInDir(commonThumbDir, BuildVideoID("demo", "near-source"))); !os.IsNotExist(err) {
+		t.Fatalf("common thumb stat = %v, want removed", err)
+	}
+	seen, err := cat.ListCrawlerSourceIDs(ctx, Kind, "demo")
+	if err != nil {
+		t.Fatalf("list seen source ids: %v", err)
+	}
+	if !hasString(seen, "near-source") {
+		t.Fatalf("seen ids = %#v, want near-source", seen)
+	}
+}
+
+func TestCrawlerProcessItemKeepsLargerNearDuplicate(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	commonThumbDir := filepath.Join(tmp, "common-thumbs")
+	if err := os.MkdirAll(commonThumbDir, 0o755); err != nil {
+		t.Fatalf("mkdir common thumbs: %v", err)
+	}
+
+	now := time.Now()
+	smallerID := "smaller-canonical"
+	if err := cat.UpsertVideo(ctx, &catalog.Video{
+		ID:              smallerID,
+		DriveID:         "other-drive",
+		FileID:          "smaller.mp4",
+		FileName:        "smaller.mp4",
+		Title:           "91 Test Larger Candidate 1215516",
+		DurationSeconds: 257,
+		Size:            5,
+		Ext:             "mp4",
+		ThumbnailURL:    "/p/thumb/" + smallerID,
+		PublishedAt:     now,
+		CreatedAt:       now,
+		UpdatedAt:       now,
+	}); err != nil {
+		t.Fatalf("seed smaller video: %v", err)
+	}
+	writeScriptCrawlerJPEG(t, mediaasset.ThumbnailPathInDir(commonThumbDir, smallerID), color.RGBA{R: 80, G: 160, B: 80, A: 255})
+
+	outputDir := drv.OutputDir()
+	mediaPath := filepath.Join(outputDir, "larger-video.mp4")
+	if err := os.WriteFile(mediaPath, []byte("near-duplicate-larger-candidate-bytes"), 0o644); err != nil {
+		t.Fatalf("write media: %v", err)
+	}
+	thumbPath := filepath.Join(outputDir, "larger-thumb.jpg")
+	writeScriptCrawlerJPEG(t, thumbPath, color.RGBA{R: 81, G: 161, B: 81, A: 255})
+
+	c := NewCrawler(CrawlerConfig{
+		Driver:         drv,
+		Catalog:        cat,
+		FFprobePath:    writeScriptCrawlerFFprobeStub(t, tmp, true),
+		CommonThumbDir: commonThumbDir,
+	})
+	imported, err := c.processItem(ctx, Item{
+		SourceID:        "larger-source",
+		Title:           "91 Test Larger Candidate 1215516 - source suffix",
+		Author:          "helper",
+		DurationSeconds: 257,
+		Media:           MediaRef{LocalFile: mediaPath},
+		Thumbnail:       MediaRef{LocalFile: thumbPath},
+	})
+	if err != nil {
+		t.Fatalf("process item: %v", err)
+	}
+	if !imported {
+		t.Fatal("larger near duplicate was skipped, want imported")
+	}
+	if _, err := cat.GetVideo(ctx, smallerID); err == nil {
+		t.Fatal("smaller near duplicate should be deleted from catalog")
+	}
+	if deleted, err := cat.IsVideoDeleted(ctx, smallerID); err != nil || !deleted {
+		t.Fatalf("smaller tombstone = %v, %v; want deleted tombstone", deleted, err)
+	}
+	larger, err := cat.GetVideo(ctx, BuildVideoID("demo", "larger-source"))
+	if err != nil {
+		t.Fatalf("larger video should be imported: %v", err)
+	}
+	if larger.Size <= 5 {
+		t.Fatalf("larger size = %d, want > 5", larger.Size)
+	}
+}
+
+func TestCrawlerRunOnceRejectsInvalidDownloadedVideo(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		CrawlerName: "Demo Crawler",
+		PythonPath:  wrapper,
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, false),
+		ScriptPath:  dummyScript,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 0 || res.Skipped != 0 || res.Failed != 1 || res.TotalEntries != 1 {
+		t.Fatalf("result = total:%d new:%d skipped:%d failed:%d, want 1/0/0/1", res.TotalEntries, res.NewVideos, res.Skipped, res.Failed)
+	}
+	if _, err := cat.GetVideo(ctx, BuildVideoID("demo", "abc-123")); err == nil {
+		t.Fatal("invalid video should not be imported")
+	}
+	if _, err := os.Stat(filepath.Join(drv.VideosDir(), "abc-123.mp4")); !os.IsNotExist(err) {
+		t.Fatalf("invalid local video stat = %v, want removed", err)
+	}
+	seen, err := cat.ListCrawlerSourceIDs(ctx, Kind, "demo")
+	if err != nil {
+		t.Fatalf("list seen source ids: %v", err)
+	}
+	if len(seen) != 0 {
+		t.Fatalf("seen ids = %#v, want none for invalid video", seen)
+	}
+}
+
+func TestCrawlerRunOnceDownloadsHLSMediaURL(t *testing.T) {
+	ctx := context.Background()
+	tmp := t.TempDir()
+	cat, err := catalog.Open(filepath.Join(tmp, "catalog.db"))
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+	drv := New(Config{ID: "demo", RootDir: filepath.Join(tmp, "crawler")})
+	if err := drv.Init(ctx); err != nil {
+		t.Fatalf("driver init: %v", err)
+	}
+	dummyScript := filepath.Join(tmp, "helper-script")
+	if err := os.WriteFile(dummyScript, []byte("helper"), 0o755); err != nil {
+		t.Fatalf("write dummy script: %v", err)
+	}
+	wrapper := filepath.Join(tmp, "helper-wrapper.sh")
+	wrapperScript := fmt.Sprintf("#!/bin/sh\nexec %q -test.run=TestScriptCrawlerHelperProcess \"$@\"\n", os.Args[0])
+	if err := os.WriteFile(wrapper, []byte(wrapperScript), 0o755); err != nil {
+		t.Fatalf("write helper wrapper: %v", err)
+	}
+
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HELPER", "1")
+	t.Setenv("GO_WANT_SCRIPTCRAWLER_HLS", "1")
+	ffmpegArgsFile := filepath.Join(tmp, "ffmpeg-args.txt")
+	t.Setenv("GO_SCRIPTCRAWLER_FFMPEG_ARGS_FILE", ffmpegArgsFile)
+	c := NewCrawler(CrawlerConfig{
+		Driver:      drv,
+		Catalog:     cat,
+		CrawlerName: "Demo Crawler",
+		PythonPath:  wrapper,
+		FFmpegPath:  writeScriptCrawlerFFmpegStub(t, tmp),
+		FFprobePath: writeScriptCrawlerFFprobeStub(t, tmp, true),
+		ScriptPath:  dummyScript,
+	})
+	res, err := c.RunOnce(ctx, 1)
+	if err != nil {
+		t.Fatalf("run once: %v", err)
+	}
+	if res.NewVideos != 1 || res.Skipped != 0 || res.Failed != 0 {
+		t.Fatalf("result = new:%d skipped:%d failed:%d, want 1/0/0", res.NewVideos, res.Skipped, res.Failed)
+	}
+	v, err := cat.GetVideo(ctx, BuildVideoID("demo", "hls-source"))
+	if err != nil {
+		t.Fatalf("get hls video: %v", err)
+	}
+	if v.FileID != "hls-source.mp4" || v.Size != int64(len("hls-video-bytes")) {
+		t.Fatalf("video file=%q size=%d, want hls-source.mp4 size %d", v.FileID, v.Size, len("hls-video-bytes"))
+	}
+	data, err := os.ReadFile(filepath.Join(drv.VideosDir(), "hls-source.mp4"))
+	if err != nil {
+		t.Fatalf("read hls output: %v", err)
+	}
+	if string(data) != "hls-video-bytes" {
+		t.Fatalf("hls output = %q", string(data))
+	}
+	argsData, err := os.ReadFile(ffmpegArgsFile)
+	if err != nil {
+		t.Fatalf("read ffmpeg args: %v", err)
+	}
+	argsText := "\n" + string(argsData) + "\n"
+	for _, want := range []string{
+		"\n-protocol_whitelist\nhttp,https,tcp,tls,crypto\n",
+		"\n-allowed_extensions\nALL\n",
+		"\n-allowed_segment_extensions\nALL\n",
+		"\n-extension_picky\n0\n",
+	} {
+		if !strings.Contains(argsText, want) {
+			t.Fatalf("ffmpeg args missing %q in:\n%s", strings.TrimSpace(want), string(argsData))
+		}
+	}
+}
+
+func TestScriptCrawlerHelperProcess(t *testing.T) {
+	if os.Getenv("GO_WANT_SCRIPTCRAWLER_HELPER") != "1" {
+		return
+	}
+	args := os.Args
+	jobPath := ""
+	for i := 0; i < len(args)-1; i++ {
+		if args[i] == "--job" {
+			jobPath = args[i+1]
+			break
+		}
+	}
+	if jobPath == "" {
+		fmt.Fprintln(os.Stderr, "missing --job")
+		os.Exit(2)
+	}
+	data, err := os.ReadFile(jobPath)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+	var job Job
+	if err := json.Unmarshal(data, &job); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+	if os.Getenv("GO_WANT_SCRIPTCRAWLER_ASSERT_ABS") == "1" {
+		if !filepath.IsAbs(jobPath) || !filepath.IsAbs(job.SeenSourceIDsFile) || !filepath.IsAbs(job.OutputDir) {
+			fmt.Fprintf(os.Stderr, "expected absolute paths, got job=%q seen=%q output=%q\n", jobPath, job.SeenSourceIDsFile, job.OutputDir)
+			os.Exit(2)
+		}
+	}
+	if os.Getenv("GO_WANT_SCRIPTCRAWLER_SIMPLE") == "1" {
+		event := map[string]any{
+			"title":     "Simple Protocol Video",
+			"media_url": os.Getenv("GO_SCRIPTCRAWLER_MEDIA_URL"),
+		}
+		_ = json.NewEncoder(os.Stdout).Encode(event)
+		os.Exit(0)
+	}
+	if os.Getenv("GO_WANT_SCRIPTCRAWLER_HLS") == "1" {
+		event := Event{
+			Type: "item",
+			Item: Item{
+				SourceID: "hls-source",
+				Title:    "HLS Protocol Video",
+				Author:   "helper",
+				Media: MediaRef{
+					URL: "https://media.example.test/video.m3u8",
+					Headers: map[string]string{
+						"Referer": "https://example.test/",
+					},
+				},
+			},
+		}
+		_ = json.NewEncoder(os.Stdout).Encode(event)
+		os.Exit(0)
+	}
+	if os.Getenv("GO_WANT_SCRIPTCRAWLER_DUP_UNIQUE") == "1" {
+		duplicateFile := filepath.Join(job.OutputDir, "duplicate.mp4")
+		if err := os.WriteFile(duplicateFile, []byte(scriptCrawlerDuplicateBytes), 0o644); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(2)
+		}
+		uniqueFile := filepath.Join(job.OutputDir, "unique.mp4")
+		if err := os.WriteFile(uniqueFile, []byte(scriptCrawlerUniqueBytes), 0o644); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(2)
+		}
+		for _, event := range []Event{
+			{
+				Type: "item",
+				Item: Item{
+					SourceID: "dup-source",
+					Title:    "Duplicate Candidate",
+					Author:   "helper",
+					Media:    MediaRef{LocalFile: duplicateFile},
+				},
+			},
+			{
+				Type: "item",
+				Item: Item{
+					SourceID: "unique-source",
+					Title:    "Unique Candidate",
+					Author:   "helper",
+					Media:    MediaRef{LocalFile: uniqueFile},
+				},
+			},
+		} {
+			_ = json.NewEncoder(os.Stdout).Encode(event)
+		}
+		os.Exit(0)
+	}
+	localFile := filepath.Join(job.OutputDir, "helper.mp4")
+	if err := os.WriteFile(localFile, []byte("helper-video"), 0o644); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+	event := Event{
+		Type: "item",
+		Item: Item{
+			SourceID: "abc-123",
+			Title:    "Imported From Helper",
+			Author:   "helper",
+			Media:    MediaRef{LocalFile: localFile},
+		},
+	}
+	_ = json.NewEncoder(os.Stdout).Encode(event)
+	os.Exit(0)
+}
+
+func hasString(values []string, want string) bool {
+	for _, value := range values {
+		if value == want {
+			return true
+		}
+	}
+	return false
+}

backend/internal/drives/scriptcrawler/driver.go

@@ -0,0 +1,213 @@
+// Package scriptcrawler provides a generic local drive for script-based
+// crawlers. A crawler script discovers videos; the Go runner downloads them
+// into this drive and the existing preview/fingerprint workers consume them
+// through the normal drives.Drive interface.
+package scriptcrawler
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/video-site/backend/internal/drives"
+)
+
+const Kind = "scriptcrawler"
+
+type Config struct {
+	ID      string
+	RootDir string
+}
+
+type Driver struct {
+	id      string
+	rootDir string
+}
+
+func New(c Config) *Driver {
+	return &Driver{id: c.ID, rootDir: c.RootDir}
+}
+
+func (d *Driver) Kind() string { return Kind }
+
+func (d *Driver) ID() string { return d.id }
+
+func (d *Driver) RootID() string { return "/" }
+
+func (d *Driver) Init(context.Context) error {
+	if strings.TrimSpace(d.id) == "" {
+		return errors.New("scriptcrawler: empty drive id")
+	}
+	if strings.TrimSpace(d.rootDir) == "" {
+		return errors.New("scriptcrawler: empty root dir")
+	}
+	for _, sub := range []string{"videos", "thumbs", "output", ".crawl"} {
+		if err := os.MkdirAll(filepath.Join(d.rootDir, sub), 0o755); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (d *Driver) RootDir() string { return d.rootDir }
+
+func (d *Driver) VideosDir() string { return filepath.Join(d.rootDir, "videos") }
+
+func (d *Driver) ThumbsDir() string { return filepath.Join(d.rootDir, "thumbs") }
+
+func (d *Driver) OutputDir() string { return filepath.Join(d.rootDir, "output") }
+
+func (d *Driver) CrawlDir() string { return filepath.Join(d.rootDir, ".crawl") }
+
+func (d *Driver) VideoPath(fileID string) (string, error) {
+	return safeJoin(d.VideosDir(), fileID)
+}
+
+func (d *Driver) ThumbPath(fileID string) (string, error) {
+	return safeJoin(d.ThumbsDir(), fileID)
+}
+
+func (d *Driver) OutputPath(fileName string) (string, error) {
+	return safeJoin(d.OutputDir(), fileName)
+}
+
+func (d *Driver) List(context.Context, string) ([]drives.Entry, error) {
+	entries, err := os.ReadDir(d.VideosDir())
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	out := make([]drives.Entry, 0, len(entries))
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		out = append(out, drives.Entry{
+			ID:      e.Name(),
+			Name:    e.Name(),
+			Size:    info.Size(),
+			IsDir:   false,
+			ModTime: info.ModTime(),
+		})
+	}
+	return out, nil
+}
+
+func (d *Driver) Stat(ctx context.Context, fileID string) (*drives.Entry, error) {
+	path, err := d.VideoPath(fileID)
+	if err != nil {
+		return nil, err
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		return nil, err
+	}
+	return &drives.Entry{
+		ID:      fileID,
+		Name:    fileID,
+		Size:    info.Size(),
+		IsDir:   info.IsDir(),
+		ModTime: info.ModTime(),
+	}, nil
+}
+
+func (d *Driver) StreamURL(ctx context.Context, fileID string) (*drives.StreamLink, error) {
+	path, err := d.VideoPath(fileID)
+	if err != nil {
+		return nil, err
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		return nil, err
+	}
+	if info.IsDir() || info.Size() == 0 {
+		return nil, os.ErrNotExist
+	}
+	return &drives.StreamLink{
+		URL:     path,
+		Expires: time.Now().Add(24 * time.Hour),
+	}, nil
+}
+
+func (d *Driver) Upload(context.Context, string, string, io.Reader, int64) (string, error) {
+	return "", drives.ErrNotSupported
+}
+
+func (d *Driver) EnsureDir(context.Context, string) (string, error) {
+	return "", drives.ErrNotSupported
+}
+
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	videoPath, err := d.VideoPath(fileID)
+	if err != nil {
+		return err
+	}
+	info, err := os.Stat(videoPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			removeThumbCandidates(d.ThumbPath, strings.TrimSuffix(fileID, filepath.Ext(fileID)))
+			return nil
+		}
+		return err
+	}
+	if info.IsDir() {
+		return errors.New("scriptcrawler: refusing to remove directory")
+	}
+	if err := os.Remove(videoPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	removeThumbCandidates(d.ThumbPath, strings.TrimSuffix(fileID, filepath.Ext(fileID)))
+	return nil
+}
+
+func removeThumbCandidates(pathFor func(string) (string, error), stem string) {
+	stem = strings.TrimSpace(stem)
+	if stem == "" {
+		return
+	}
+	for _, ext := range []string{".jpg", ".jpeg", ".png", ".webp"} {
+		path, err := pathFor(stem + ext)
+		if err != nil {
+			continue
+		}
+		_ = os.Remove(path)
+	}
+}
+
+func safeJoin(root, fileID string) (string, error) {
+	id := strings.TrimSpace(fileID)
+	if id == "" || filepath.Base(id) != id {
+		return "", errors.New("scriptcrawler: invalid file id")
+	}
+	if strings.TrimSpace(root) == "" {
+		return "", errors.New("scriptcrawler: empty root")
+	}
+	rootAbs, err := filepath.Abs(root)
+	if err != nil {
+		return "", err
+	}
+	pathAbs, err := filepath.Abs(filepath.Join(rootAbs, id))
+	if err != nil {
+		return "", err
+	}
+	if pathAbs != rootAbs && !strings.HasPrefix(pathAbs, rootAbs+string(os.PathSeparator)) {
+		return "", errors.New("scriptcrawler: file id escapes root")
+	}
+	return pathAbs, nil
+}
+
+var _ drives.Drive = (*Driver)(nil)
+var _ drives.Remover = (*Driver)(nil)

backend/internal/drives/scriptcrawler/dryrun.go

@@ -0,0 +1,405 @@
+package scriptcrawler
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+)
+
+// DryRun 在不入库的前提下试跑一个爬虫脚本：临时目录里生成 job.json，
+// 启动脚本进程，拿到第一条（或前 MaxItems 条）item 事件后立即停止，
+// 再对视频直链做一次小范围探测，验证脚本"能不能爬取到视频"。
+// 用于后台导入脚本后的"测试脚本"按钮。
+
+const (
+	defaultDryRunTimeout  = 2 * time.Minute
+	dryRunLogTailLines    = 60
+	dryRunMediaProbeLimit = 20 * time.Second
+	dryRunStopGrace       = 100 * time.Millisecond
+)
+
+type DryRunConfig struct {
+	PythonPath string
+	ScriptPath string
+	ProxyURL   string
+	ConfigJSON string
+	// MaxItems 收到多少条 item 后停止脚本，默认 1。
+	MaxItems int
+	// Timeout 整个试跑的硬上限，默认 2 分钟。
+	Timeout time.Duration
+	// SkipMediaProbe 跳过视频直链可达性探测（单测注入用）。
+	SkipMediaProbe bool
+	HTTPClient     *http.Client
+}
+
+type DryRunItem struct {
+	Title          string `json:"title"`
+	SourceID       string `json:"sourceId,omitempty"`
+	MediaURL       string `json:"mediaUrl,omitempty"`
+	MediaLocalFile string `json:"mediaLocalFile,omitempty"`
+	ThumbnailURL   string `json:"thumbnailUrl,omitempty"`
+	DetailURL      string `json:"detailUrl,omitempty"`
+}
+
+type DryRunMediaCheck struct {
+	OK            bool   `json:"ok"`
+	Status        int    `json:"status,omitempty"`
+	ContentType   string `json:"contentType,omitempty"`
+	ContentLength int64  `json:"contentLengthBytes,omitempty"`
+	Error         string `json:"error,omitempty"`
+}
+
+type DryRunResult struct {
+	OK         bool              `json:"ok"`
+	Items      []DryRunItem      `json:"items"`
+	MediaCheck *DryRunMediaCheck `json:"mediaCheck,omitempty"`
+	Error      string            `json:"error,omitempty"`
+	Log        []string          `json:"log,omitempty"`
+	DurationMs int64             `json:"durationMs"`
+}
+
+type dryRunLogTail struct {
+	mu      sync.Mutex
+	lines   []string
+	partial string
+}
+
+func newDryRunLogTail() *dryRunLogTail {
+	return &dryRunLogTail{lines: make([]string, 0, dryRunLogTailLines)}
+}
+
+func (t *dryRunLogTail) Write(p []byte) (int, error) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	chunk := strings.ReplaceAll(string(p), "\r\n", "\n")
+	parts := strings.Split(t.partial+chunk, "\n")
+	t.partial = parts[len(parts)-1]
+	for _, line := range parts[:len(parts)-1] {
+		t.appendLocked(line)
+	}
+	return len(p), nil
+}
+
+func (t *dryRunLogTail) snapshot() []string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	lines := append([]string{}, t.lines...)
+	if partial := strings.TrimSpace(t.partial); partial != "" {
+		lines = appendDryRunLogLine(lines, partial)
+	}
+	return lines
+}
+
+func (t *dryRunLogTail) appendLocked(line string) {
+	t.lines = appendDryRunLogLine(t.lines, line)
+}
+
+func appendDryRunLogLine(lines []string, line string) []string {
+	line = strings.TrimSpace(line)
+	if line == "" {
+		return lines
+	}
+	if len(lines) >= dryRunLogTailLines {
+		lines = lines[1:]
+	}
+	return append(lines, line)
+}
+
+func DryRun(ctx context.Context, cfg DryRunConfig) *DryRunResult {
+	started := time.Now()
+	result := &DryRunResult{Items: []DryRunItem{}}
+	defer func() { result.DurationMs = time.Since(started).Milliseconds() }()
+
+	scriptPath := strings.TrimSpace(cfg.ScriptPath)
+	if scriptPath == "" {
+		result.Error = "脚本路径为空，请先导入脚本"
+		return result
+	}
+	if _, err := os.Stat(scriptPath); err != nil {
+		result.Error = fmt.Sprintf("脚本不存在: %v", err)
+		return result
+	}
+	pythonPath := strings.TrimSpace(cfg.PythonPath)
+	if pythonPath == "" {
+		pythonPath = "python3"
+	}
+	maxItems := cfg.MaxItems
+	if maxItems <= 0 {
+		maxItems = 1
+	}
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = defaultDryRunTimeout
+	}
+
+	tmpDir, err := os.MkdirTemp("", "crawler-dryrun-")
+	if err != nil {
+		result.Error = fmt.Sprintf("创建临时目录失败: %v", err)
+		return result
+	}
+	defer os.RemoveAll(tmpDir)
+
+	outputDir := filepath.Join(tmpDir, "output")
+	if err := os.MkdirAll(outputDir, 0o755); err != nil {
+		result.Error = fmt.Sprintf("创建输出目录失败: %v", err)
+		return result
+	}
+	seenPath := filepath.Join(tmpDir, "seen.txt")
+	if err := os.WriteFile(seenPath, nil, 0o644); err != nil {
+		result.Error = fmt.Sprintf("写入 seen 文件失败: %v", err)
+		return result
+	}
+
+	configJSON := json.RawMessage([]byte("{}"))
+	if raw := strings.TrimSpace(cfg.ConfigJSON); raw != "" {
+		if !json.Valid([]byte(raw)) {
+			result.Error = "自定义配置必须是合法 JSON"
+			return result
+		}
+		configJSON = json.RawMessage(raw)
+	}
+	job := Job{
+		Protocol:          "crawler.v1",
+		Mode:              "crawl",
+		RunID:             "dryrun-" + started.UTC().Format("20060102T150405Z"),
+		CrawlerID:         "dryrun",
+		TargetNew:         maxItems,
+		SeenSourceIDsFile: seenPath,
+		OutputDir:         outputDir,
+		Config:            configJSON,
+		Network:           JobNetwork{ProxyURL: strings.TrimSpace(cfg.ProxyURL)},
+	}
+	jobPath := filepath.Join(tmpDir, "job.json")
+	jobData, err := json.MarshalIndent(job, "", "  ")
+	if err != nil {
+		result.Error = fmt.Sprintf("生成 job 文件失败: %v", err)
+		return result
+	}
+	if err := os.WriteFile(jobPath, jobData, 0o600); err != nil {
+		result.Error = fmt.Sprintf("写入 job 文件失败: %v", err)
+		return result
+	}
+
+	runCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	cmd := exec.CommandContext(runCtx, pythonPath, scriptPath, "--job", jobPath)
+	cmd.Dir = filepath.Dir(scriptPath)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	cmd.Cancel = func() error {
+		return killDryRunProcess(cmd)
+	}
+	// 超时或提前 kill 后，脚本派生的子进程可能仍持有 stdout/stderr 管道；
+	// WaitDelay 强制在宽限期后关闭管道，避免读取端永久阻塞。
+	cmd.WaitDelay = 3 * time.Second
+	if proxyURL := strings.TrimSpace(cfg.ProxyURL); proxyURL != "" {
+		cmd.Env = append(os.Environ(),
+			"HTTP_PROXY="+proxyURL,
+			"HTTPS_PROXY="+proxyURL,
+			"http_proxy="+proxyURL,
+			"https_proxy="+proxyURL,
+			"NO_PROXY=",
+			"no_proxy=",
+		)
+	}
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		result.Error = fmt.Sprintf("启动脚本失败: %v", err)
+		return result
+	}
+	logTail := newDryRunLogTail()
+	cmd.Stderr = logTail
+	if err := cmd.Start(); err != nil {
+		_ = stdout.Close()
+		result.Error = fmt.Sprintf("启动脚本失败: %v", err)
+		return result
+	}
+
+	items := []DryRunItem{}
+	var firstMediaHeaders map[string]string
+	parseFailures := 0
+	scanner := bufio.NewScanner(stdout)
+	scanner.Buffer(make([]byte, 64*1024), 4*1024*1024)
+	for scanner.Scan() {
+		if runCtx.Err() != nil {
+			break
+		}
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		var event Event
+		if err := json.Unmarshal([]byte(line), &event); err != nil {
+			parseFailures++
+			continue
+		}
+		eventType := strings.ToLower(strings.TrimSpace(event.Type))
+		item := event.normalizedItem()
+		if eventType == "" && item.hasPayload() {
+			eventType = "item"
+		}
+		if eventType != "item" {
+			continue
+		}
+		normalized, _, err := normalizeItemForImport(item)
+		if err != nil {
+			result.Error = fmt.Sprintf("item 字段不完整: %v", err)
+			continue
+		}
+		mediaURL := strings.TrimSpace(normalized.Media.URL)
+		if len(items) == 0 {
+			firstMediaHeaders = normalized.Media.Headers
+		}
+		items = append(items, DryRunItem{
+			Title:          strings.TrimSpace(normalized.Title),
+			SourceID:       strings.TrimSpace(item.SourceID),
+			MediaURL:       mediaURL,
+			MediaLocalFile: strings.TrimSpace(normalized.Media.LocalFile),
+			ThumbnailURL:   strings.TrimSpace(normalized.Thumbnail.URL),
+			DetailURL:      strings.TrimSpace(normalized.DetailURL),
+		})
+		if len(items) >= maxItems {
+			break
+		}
+	}
+	// 拿够了就停掉脚本，避免它继续翻页。给已经自然结束的脚本一个很短
+	// 的宽限期，让 stderr 日志先被管道读完，避免 dry-run 回显偶发为空。
+	waitDone := make(chan struct{})
+	go func() {
+		_ = cmd.Wait()
+		close(waitDone)
+	}()
+	select {
+	case <-waitDone:
+	case <-time.After(dryRunStopGrace):
+		_ = killDryRunProcess(cmd)
+		<-waitDone
+	}
+
+	result.Log = logTail.snapshot()
+	result.Items = items
+
+	if len(items) == 0 {
+		if result.Error == "" {
+			switch {
+			case runCtx.Err() != nil && ctx.Err() == nil:
+				result.Error = fmt.Sprintf("测试超时（%s），脚本没有输出任何视频", timeout)
+			case parseFailures > 0:
+				result.Error = "脚本 stdout 不是合法的 crawler.v1 JSON Lines（日志应输出到 stderr）"
+			default:
+				result.Error = "脚本退出但没有输出任何视频"
+			}
+		}
+		return result
+	}
+	result.Error = ""
+
+	first := items[0]
+	switch {
+	case cfg.SkipMediaProbe:
+		result.OK = true
+	case first.MediaLocalFile != "":
+		// 脚本自己下载到 output_dir 的模式：试跑用的是临时目录，
+		// 文件已随目录清理，能输出合法 local_file 即视为通过。
+		result.OK = true
+	default:
+		check := probeMediaURL(ctx, cfg, first, firstMediaHeaders)
+		result.MediaCheck = check
+		result.OK = check.OK
+	}
+	return result
+}
+
+func killDryRunProcess(cmd *exec.Cmd) error {
+	if cmd == nil || cmd.Process == nil {
+		return nil
+	}
+	if err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL); err != nil {
+		if err == syscall.ESRCH {
+			return nil
+		}
+		return cmd.Process.Kill()
+	}
+	return nil
+}
+
+// probeMediaURL 对视频直链发一个 Range: bytes=0-0 的小请求，
+// 验证直链可达（带上脚本给的防盗链 headers 和代理）。
+func probeMediaURL(ctx context.Context, cfg DryRunConfig, item DryRunItem, mediaHeaders map[string]string) *DryRunMediaCheck {
+	check := &DryRunMediaCheck{}
+	if item.MediaURL == "" {
+		check.Error = "item 没有视频直链"
+		return check
+	}
+
+	client := cfg.HTTPClient
+	if client == nil {
+		transport := &http.Transport{
+			Proxy:                 http.ProxyFromEnvironment,
+			ResponseHeaderTimeout: dryRunMediaProbeLimit,
+		}
+		if err := configureExplicitProxy(transport, cfg.ProxyURL); err != nil {
+			check.Error = fmt.Sprintf("代理配置无效: %v", err)
+			return check
+		}
+		client = &http.Client{Transport: transport}
+	}
+
+	probeCtx, cancel := context.WithTimeout(ctx, dryRunMediaProbeLimit)
+	defer cancel()
+	req, err := http.NewRequestWithContext(probeCtx, http.MethodGet, item.MediaURL, nil)
+	if err != nil {
+		check.Error = fmt.Sprintf("视频直链无效: %v", err)
+		return check
+	}
+	req.Header.Set("User-Agent", defaultUserAgent)
+	req.Header.Set("Range", "bytes=0-0")
+	if item.DetailURL != "" {
+		req.Header.Set("Referer", item.DetailURL)
+	}
+	for k, v := range mediaHeaders {
+		k = strings.TrimSpace(k)
+		if k == "" {
+			continue
+		}
+		req.Header.Set(k, v)
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		check.Error = fmt.Sprintf("视频直链请求失败: %v", err)
+		return check
+	}
+	defer resp.Body.Close()
+
+	check.Status = resp.StatusCode
+	check.ContentType = resp.Header.Get("Content-Type")
+	if cr := resp.Header.Get("Content-Range"); cr != "" {
+		// Content-Range: bytes 0-0/12345 → 取总大小
+		if idx := strings.LastIndex(cr, "/"); idx >= 0 {
+			var total int64
+			if _, err := fmt.Sscanf(cr[idx+1:], "%d", &total); err == nil {
+				check.ContentLength = total
+			}
+		}
+	}
+	if check.ContentLength == 0 && resp.StatusCode == http.StatusOK {
+		check.ContentLength = resp.ContentLength
+	}
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusPartialContent {
+		check.Error = fmt.Sprintf("视频直链返回 HTTP %d", resp.StatusCode)
+		return check
+	}
+	check.OK = true
+	return check
+}

backend/internal/drives/scriptcrawler/dryrun_test.go

@@ -0,0 +1,176 @@
+package scriptcrawler
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func writeDryRunScript(t *testing.T, body string) string {
+	t.Helper()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "crawler.sh")
+	if err := os.WriteFile(path, []byte("#!/bin/sh\n"+body), 0o755); err != nil {
+		t.Fatalf("write script: %v", err)
+	}
+	return path
+}
+
+func TestDryRunCollectsFirstItem(t *testing.T) {
+	script := writeDryRunScript(t, `
+echo '[log] fetching list page' >&2
+echo '{"type":"item","item":{"title":"Test Video","media_url":"https://cdn.example.test/v.mp4","source_id":"123","thumbnail_url":"https://cdn.example.test/t.jpg"}}'
+echo '{"type":"done","stats":{"emitted":1}}'
+`)
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath:     "/bin/sh",
+		ScriptPath:     script,
+		SkipMediaProbe: true,
+	})
+	if !result.OK {
+		t.Fatalf("ok = false, error = %q, log = %v", result.Error, result.Log)
+	}
+	if len(result.Items) != 1 {
+		t.Fatalf("items = %d, want 1", len(result.Items))
+	}
+	item := result.Items[0]
+	if item.Title != "Test Video" || item.MediaURL != "https://cdn.example.test/v.mp4" || item.SourceID != "123" {
+		t.Fatalf("item = %+v", item)
+	}
+	if len(result.Log) == 0 || !strings.Contains(result.Log[0], "fetching list page") {
+		t.Fatalf("log tail = %v, want stderr captured", result.Log)
+	}
+}
+
+func TestDryRunCapturesStderrWhenStoppingAfterFirstItem(t *testing.T) {
+	script := writeDryRunScript(t, `
+echo '[log] first item ready' >&2
+echo '{"type":"item","item":{"title":"Early Stop Video","media_url":"https://cdn.example.test/v.mp4","source_id":"early-stop"}}'
+sleep 30
+`)
+	start := time.Now()
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath:     "/bin/sh",
+		ScriptPath:     script,
+		SkipMediaProbe: true,
+	})
+	if !result.OK {
+		t.Fatalf("ok = false, error = %q, log = %v", result.Error, result.Log)
+	}
+	if elapsed := time.Since(start); elapsed > 5*time.Second {
+		t.Fatalf("dry run took %s, script was not stopped after first item", elapsed)
+	}
+	if len(result.Log) == 0 || !strings.Contains(result.Log[0], "first item ready") {
+		t.Fatalf("log tail = %v, want stderr captured before early stop", result.Log)
+	}
+}
+
+func TestDryRunProbesMediaURL(t *testing.T) {
+	var gotRange, gotReferer string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotRange = r.Header.Get("Range")
+		gotReferer = r.Header.Get("Referer")
+		w.Header().Set("Content-Type", "video/mp4")
+		w.Header().Set("Content-Range", "bytes 0-0/4096")
+		w.WriteHeader(http.StatusPartialContent)
+		_, _ = w.Write([]byte("x"))
+	}))
+	t.Cleanup(srv.Close)
+
+	script := writeDryRunScript(t, fmt.Sprintf(
+		`echo '{"type":"item","title":"Probe Video","media_url":"%s/v.mp4","detail_url":"https://example.test/view"}'`,
+		srv.URL,
+	))
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath: "/bin/sh",
+		ScriptPath: script,
+	})
+	if !result.OK {
+		t.Fatalf("ok = false, error = %q, mediaCheck = %+v", result.Error, result.MediaCheck)
+	}
+	if result.MediaCheck == nil || !result.MediaCheck.OK {
+		t.Fatalf("mediaCheck = %+v, want ok", result.MediaCheck)
+	}
+	if result.MediaCheck.Status != http.StatusPartialContent || result.MediaCheck.ContentLength != 4096 {
+		t.Fatalf("mediaCheck = %+v, want 206 with total 4096", result.MediaCheck)
+	}
+	if gotRange != "bytes=0-0" || gotReferer != "https://example.test/view" {
+		t.Fatalf("probe headers range=%q referer=%q", gotRange, gotReferer)
+	}
+}
+
+func TestDryRunReportsBrokenMediaURL(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "forbidden", http.StatusForbidden)
+	}))
+	t.Cleanup(srv.Close)
+
+	script := writeDryRunScript(t, fmt.Sprintf(
+		`echo '{"type":"item","title":"Dead Link","media_url":"%s/v.mp4"}'`,
+		srv.URL,
+	))
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath: "/bin/sh",
+		ScriptPath: script,
+	})
+	if result.OK {
+		t.Fatal("ok = true, want false for HTTP 403 media url")
+	}
+	if result.MediaCheck == nil || result.MediaCheck.OK || result.MediaCheck.Status != http.StatusForbidden {
+		t.Fatalf("mediaCheck = %+v, want failed 403", result.MediaCheck)
+	}
+	if len(result.Items) != 1 {
+		t.Fatalf("items = %d, want item still returned for debugging", len(result.Items))
+	}
+}
+
+func TestDryRunRejectsNonJSONStdout(t *testing.T) {
+	script := writeDryRunScript(t, `echo 'plain text progress output'`)
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath:     "/bin/sh",
+		ScriptPath:     script,
+		SkipMediaProbe: true,
+	})
+	if result.OK {
+		t.Fatal("ok = true, want false for non-JSON stdout")
+	}
+	if !strings.Contains(result.Error, "JSON Lines") {
+		t.Fatalf("error = %q, want JSON Lines hint", result.Error)
+	}
+}
+
+func TestDryRunTimesOut(t *testing.T) {
+	script := writeDryRunScript(t, `sleep 30`)
+	start := time.Now()
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath:     "/bin/sh",
+		ScriptPath:     script,
+		Timeout:        2 * time.Second,
+		SkipMediaProbe: true,
+	})
+	if result.OK {
+		t.Fatal("ok = true, want false on timeout")
+	}
+	if !strings.Contains(result.Error, "超时") {
+		t.Fatalf("error = %q, want timeout message", result.Error)
+	}
+	if elapsed := time.Since(start); elapsed > 10*time.Second {
+		t.Fatalf("dry run took %s, script was not killed", elapsed)
+	}
+}
+
+func TestDryRunMissingScript(t *testing.T) {
+	result := DryRun(context.Background(), DryRunConfig{
+		PythonPath: "/bin/sh",
+		ScriptPath: filepath.Join(t.TempDir(), "missing.py"),
+	})
+	if result.OK || result.Error == "" {
+		t.Fatalf("result = %+v, want error for missing script", result)
+	}
+}

backend/internal/drives/scriptcrawler/metadata.go

@@ -0,0 +1,117 @@
+package scriptcrawler
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const maxCrawlerNameRunes = 80
+
+type Metadata struct {
+	Name string `json:"name"`
+}
+
+func ReadMetadata(scriptPath string) (Metadata, error) {
+	scriptPath = strings.TrimSpace(scriptPath)
+	if scriptPath == "" {
+		return Metadata{}, errors.New("脚本路径为空")
+	}
+	if filepath.Ext(scriptPath) != ".py" {
+		return Metadata{}, errors.New("目前只支持 .py 爬虫脚本")
+	}
+	data, err := os.ReadFile(scriptPath)
+	if err != nil {
+		return Metadata{}, fmt.Errorf("读取脚本失败: %w", err)
+	}
+	return ExtractMetadata(string(data))
+}
+
+func ExtractMetadata(source string) (Metadata, error) {
+	for _, line := range strings.Split(source, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		if !strings.HasPrefix(trimmed, "CRAWLER_NAME") {
+			continue
+		}
+		left, right, ok := strings.Cut(trimmed, "=")
+		if !ok || strings.TrimSpace(left) != "CRAWLER_NAME" {
+			continue
+		}
+		name, ok := parsePythonStringLiteral(right)
+		if !ok {
+			return Metadata{}, errors.New(`CRAWLER_NAME 必须是字符串字面量，例如 CRAWLER_NAME = "示例爬虫"`)
+		}
+		name = strings.TrimSpace(name)
+		if name == "" {
+			return Metadata{}, errors.New("CRAWLER_NAME 不能为空")
+		}
+		if len([]rune(name)) > maxCrawlerNameRunes {
+			return Metadata{}, fmt.Errorf("CRAWLER_NAME 不能超过 %d 个字符", maxCrawlerNameRunes)
+		}
+		return Metadata{Name: name}, nil
+	}
+	return Metadata{}, errors.New(`脚本必须声明 CRAWLER_NAME，例如 CRAWLER_NAME = "示例爬虫"`)
+}
+
+func parsePythonStringLiteral(raw string) (string, bool) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return "", false
+	}
+	rawString := false
+	for len(s) > 0 {
+		switch s[0] {
+		case 'r', 'R':
+			rawString = true
+			s = strings.TrimSpace(s[1:])
+		case 'u', 'U', 'b', 'B':
+			s = strings.TrimSpace(s[1:])
+		default:
+			goto parseQuote
+		}
+	}
+
+parseQuote:
+	if len(s) < 2 || (s[0] != '"' && s[0] != '\'') {
+		return "", false
+	}
+	quote := s[0]
+	var b strings.Builder
+	escaped := false
+	for i := 1; i < len(s); i++ {
+		ch := s[i]
+		if escaped {
+			switch {
+			case rawString:
+				b.WriteByte('\\')
+				b.WriteByte(ch)
+			case ch == 'n':
+				b.WriteByte('\n')
+			case ch == 'r':
+				b.WriteByte('\r')
+			case ch == 't':
+				b.WriteByte('\t')
+			case ch == '\\' || ch == quote || ch == '"' || ch == '\'':
+				b.WriteByte(ch)
+			default:
+				b.WriteByte(ch)
+			}
+			escaped = false
+			continue
+		}
+		if ch == '\\' {
+			escaped = true
+			continue
+		}
+		if ch == quote {
+			return b.String(), true
+		}
+		b.WriteByte(ch)
+	}
+	return "", false
+}

backend/internal/drives/scriptcrawler/metadata_test.go

@@ -0,0 +1,39 @@
+package scriptcrawler
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestExtractMetadataReadsCrawlerName(t *testing.T) {
+	meta, err := ExtractMetadata(`
+# comment
+CRAWLER_NAME = "示例爬虫"
+`)
+	if err != nil {
+		t.Fatalf("extract metadata: %v", err)
+	}
+	if meta.Name != "示例爬虫" {
+		t.Fatalf("name = %q", meta.Name)
+	}
+}
+
+func TestExtractMetadataRejectsMissingCrawlerName(t *testing.T) {
+	_, err := ExtractMetadata(`print("hello")`)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "CRAWLER_NAME") {
+		t.Fatalf("error = %v, want CRAWLER_NAME guidance", err)
+	}
+}
+
+func TestExtractMetadataRejectsEmptyCrawlerName(t *testing.T) {
+	_, err := ExtractMetadata(`CRAWLER_NAME = "  "`)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "不能为空") {
+		t.Fatalf("error = %v, want empty-name error", err)
+	}
+}

backend/internal/drives/scriptcrawler/neardupe.go

@@ -0,0 +1,70 @@
+package scriptcrawler
+
+import (
+	"context"
+	"log"
+	"os"
+	"strings"
+
+	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/mediaasset"
+	"github.com/video-site/backend/internal/mediasim"
+)
+
+const (
+	nearDuplicateTitleThreshold           = 0.90
+	nearDuplicateSSIMThreshold            = 0.95
+	nearDuplicateDurationToleranceSeconds = 2
+	nearDuplicateCandidateLimit           = 200
+)
+
+type nearDuplicateMatch struct {
+	video           *catalog.Video
+	titleSimilarity float64
+	thumbnailSSIM   float64
+}
+
+func (c *Crawler) findNearDuplicateVideo(ctx context.Context, source *catalog.Video, sourceThumbPath string) (*nearDuplicateMatch, error) {
+	if c == nil || c.cfg.Catalog == nil || source == nil {
+		return nil, nil
+	}
+	sourceThumbPath = strings.TrimSpace(sourceThumbPath)
+	commonThumbDir := strings.TrimSpace(c.cfg.CommonThumbDir)
+	if sourceThumbPath == "" || commonThumbDir == "" || strings.TrimSpace(source.Title) == "" || source.DurationSeconds <= 0 {
+		return nil, nil
+	}
+	if _, err := os.Stat(sourceThumbPath); err != nil {
+		return nil, nil
+	}
+
+	candidates, err := c.cfg.Catalog.ListNearDuplicateVideoCandidates(ctx, source, nearDuplicateDurationToleranceSeconds, nearDuplicateCandidateLimit)
+	if err != nil {
+		return nil, err
+	}
+	for _, candidate := range candidates {
+		if candidate == nil || candidate.ID == source.ID {
+			continue
+		}
+		titleScore := mediasim.TitleSimilarity(source.Title, candidate.Title)
+		if titleScore < nearDuplicateTitleThreshold {
+			continue
+		}
+		candidateThumbPath := mediaasset.ThumbnailPathInDir(commonThumbDir, candidate.ID)
+		if _, err := os.Stat(candidateThumbPath); err != nil {
+			continue
+		}
+		ssimScore, err := mediasim.ImageSSIM(sourceThumbPath, candidateThumbPath)
+		if err != nil {
+			log.Printf("[scriptcrawler] drive=%s source_id=%s candidate=%s thumbnail ssim failed: %v", c.cfg.Driver.ID(), source.ID, candidate.ID, err)
+			continue
+		}
+		if ssimScore >= nearDuplicateSSIMThreshold {
+			return &nearDuplicateMatch{
+				video:           candidate,
+				titleSimilarity: titleScore,
+				thumbnailSSIM:   ssimScore,
+			}, nil
+		}
+	}
+	return nil, nil
+}

backend/internal/drives/spider91/crawler.go

@@ -1,936 +0,0 @@
-package spider91
-
-import (
-	"bufio"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"log"
-	"net/http"
-	"net/url"
-	"os"
-	"os/exec"
-	"path"
-	"path/filepath"
-	"regexp"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/video-site/backend/internal/catalog"
-)
-
-// 默认 author/tag 标签，便于在前端筛选 spider91 来源的视频。
-const DefaultAuthor = "91porn"
-const DefaultTag = "91porn"
-
-// DefaultTargetNew 是凌晨任务默认的"凑够这么多新视频"目标数。
-const DefaultTargetNew = 15
-
-// 视频下载、列表页请求的 UA 沿用爬虫脚本里那一套，避免触发 Cloudflare 风控。
-const downloadUA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
-
-// CrawlerConfig 是 Crawler 的依赖注入。
-type CrawlerConfig struct {
-	// Driver 是已挂载的 spider91 driver；crawler 用它的 VideoPath / ThumbPath 写入文件。
-	Driver *Driver
-	// Catalog 用于查重和入库。
-	Catalog *catalog.Catalog
-	// PythonPath 是用来跑爬虫脚本的解释器，通常是 "python3"。
-	PythonPath string
-	// ScriptPath 是 spider_91porn.py 的绝对路径。
-	ScriptPath string
-	// WorkDir 是跑 Python 时的 cwd；为空表示沿用当前进程工作目录。
-	WorkDir string
-	// CommonThumbDir 是 backend 的 data/previews/thumbs 目录；
-	// crawler 会把封面再复制一份到 <CommonThumbDir>/<videoID>.jpg，
-	// 让 /p/thumb/{videoID} 路由命中本地文件。
-	CommonThumbDir string
-	// HTTPClient 用于下载视频和封面；为空时使用内置默认 client。
-	HTTPClient *http.Client
-	// ProxyURL 可选的下载代理 URL（如 "http://127.0.0.1:7890"）。
-	// 不为空则用它作为 HTTP/HTTPS 代理；为空则走 http.ProxyFromEnvironment（读 HTTPS_PROXY / HTTP_PROXY / NO_PROXY）。
-	// 91porn CDN 节点位于海外，国内服务器直连通常很慢，需要走代理。
-	ProxyURL string
-	// SpiderTimeout 限制单次爬虫脚本运行时间。
-	SpiderTimeout time.Duration
-	// DownloadTimeout 限制单条视频/封面下载的耗时。
-	DownloadTimeout time.Duration
-
-	// OnNewVideo 是新视频成功入库后的回调，用于触发 teaser worker。
-	OnNewVideo func(v *catalog.Video)
-}
-
-// Crawler 把 Python 爬虫产出包装成 catalog 入库流程。
-type Crawler struct {
-	cfg CrawlerConfig
-	// runMu 保证同一个 Crawler 实例不会并发跑两次。
-	runMu sync.Mutex
-}
-
-// NewCrawler 构造 Crawler。
-func NewCrawler(cfg CrawlerConfig) *Crawler {
-	if cfg.SpiderTimeout <= 0 {
-		cfg.SpiderTimeout = 15 * time.Minute
-	}
-	if cfg.DownloadTimeout <= 0 {
-		cfg.DownloadTimeout = 30 * time.Minute
-	}
-	if cfg.HTTPClient == nil {
-		// 选 proxy 函数：显式 ProxyURL > 环境变量 > 直连
-		proxyFn := http.ProxyFromEnvironment
-		if strings.TrimSpace(cfg.ProxyURL) != "" {
-			if u, err := url.Parse(cfg.ProxyURL); err == nil {
-				proxyFn = http.ProxyURL(u)
-			} else {
-				log.Printf("[spider91] invalid proxy URL %q, falling back to env: %v", cfg.ProxyURL, err)
-			}
-		}
-		cfg.HTTPClient = &http.Client{
-			// 不限制总下载时长，靠 ctx 控制；只挡 dial / handshake / header
-			Timeout: 0,
-			Transport: &http.Transport{
-				Proxy:                 proxyFn,
-				ResponseHeaderTimeout: 60 * time.Second,
-				MaxIdleConns:          10,
-				IdleConnTimeout:       90 * time.Second,
-			},
-		}
-	}
-	return &Crawler{cfg: cfg}
-}
-
-// CrawlResult 汇总一次 RunOnce 的结果。
-type CrawlResult struct {
-	// TargetNew 是本次 RunOnce 的目标新增数（来自 drive.Credentials.target_new）。
-	TargetNew int
-	// TotalEntries 是 Python 输出 JSON 里的视频条数（已被 spider 端去重过的新视频）。
-	TotalEntries int
-	// NewVideos 是真正下载完并入库的新视频数。
-	NewVideos int
-	// Skipped 是 Go 侧二次校验时发现已存在的（理论上 Python 侧已经过滤过，正常情况下应为 0）。
-	Skipped int
-	// Failed 是下载或入库失败的条数。
-	Failed int
-	// SeenSnapshot 调用 Python 时实际写出的已知视频 ID 数量。
-	SeenSnapshot int
-	StartedAt    time.Time
-	FinishedAt   time.Time
-	OutputJSON   string
-	SeenFile     string
-}
-
-// spiderVideoEntry 对应 spider_91porn.py 输出 JSON 中的单条视频。
-type spiderVideoEntry struct {
-	Title     string `json:"title"`
-	ThumbURL  string `json:"thumb_url"`
-	VideoURL  string `json:"video_url"`
-	Viewkey   string `json:"viewkey"`
-	SourceID  string `json:"source_id"`
-	DetailURL string `json:"detail_url"`
-}
-
-// RunOnce 执行一次"跑爬虫 → 下载 → 入库"流程：
-//  1. 从 catalog 拉取本 drive 已存在的 91 源视频 ID 列表，写到临时文件
-//  2. 启动 Python 爬虫（--target-new + --seen-viewkeys-file + --stream-output），
-//     Python 每解析出一个 video 直链就把 entry 当作一行 JSON 写到 stdout。
-//  3. Go 端 bufio.Scanner 按行读：每行立即下载视频和封面、入库。
-//     这样 "Python 翻页找下一个" 与 "Go 下载当前一个" 在时间上重叠，缩短整轮耗时；
-//     更重要的是不会让前几个下载耽误后面签名链接 e= 过期。
-//  4. 全部消费完 + 子进程退出 → 返回 CrawlResult。teaser 不在此处入队，
-//     由调用方 (App.runSpider91Crawl) 在 RunOnce 后统一调 enqueueDriveGeneration。
-//
-// targetNew <= 0 会被规范化成 spider91DefaultTargetNew（15）。
-func (c *Crawler) RunOnce(ctx context.Context, targetNew int) (*CrawlResult, error) {
-	c.runMu.Lock()
-	defer c.runMu.Unlock()
-
-	if c.cfg.Driver == nil {
-		return nil, errors.New("spider91 crawler: driver not set")
-	}
-	if c.cfg.Catalog == nil {
-		return nil, errors.New("spider91 crawler: catalog not set")
-	}
-	if strings.TrimSpace(c.cfg.PythonPath) == "" || strings.TrimSpace(c.cfg.ScriptPath) == "" {
-		return nil, errors.New("spider91 crawler: python_path / script_path required")
-	}
-	if _, err := os.Stat(c.cfg.ScriptPath); err != nil {
-		return nil, fmt.Errorf("spider91 crawler: script not found: %w", err)
-	}
-	if targetNew <= 0 {
-		targetNew = DefaultTargetNew
-	}
-
-	if err := c.cfg.Driver.Init(ctx); err != nil {
-		return nil, fmt.Errorf("spider91 crawler: driver init: %w", err)
-	}
-
-	result := &CrawlResult{TargetNew: targetNew, StartedAt: time.Now()}
-	defer func() { result.FinishedAt = time.Now() }()
-
-	// 1. 准备 .crawl/ 目录 + 已知源视频 ID 列表
-	//
-	// 关键：路径必须用绝对路径，因为 Python 子进程的 cwd 我们设成了脚本所在目录
-	// （为了让 Python 用 site-packages 里的 requests 等），传相对路径会被 Python
-	// 当作相对它自己的 cwd 来解释，落在错的目录下，Go 这边再回头找又找不到。
-	rootDir, err := filepath.Abs(c.cfg.Driver.RootDir())
-	if err != nil {
-		return result, fmt.Errorf("spider91 crawler: abs root dir: %w", err)
-	}
-	crawlDir := filepath.Join(rootDir, ".crawl")
-	if err := os.MkdirAll(crawlDir, 0o755); err != nil {
-		return result, fmt.Errorf("spider91 crawler: mkdir crawl: %w", err)
-	}
-	timestamp := time.Now().UTC().Format("20060102T150405Z")
-	outputPath := filepath.Join(crawlDir, fmt.Sprintf("target-%d-%s.json", targetNew, timestamp))
-	seenPath := filepath.Join(crawlDir, fmt.Sprintf("seen-%s.txt", timestamp))
-	result.OutputJSON = outputPath
-	result.SeenFile = seenPath
-
-	seenCount, err := c.writeSeenViewkeys(ctx, seenPath)
-	if err != nil {
-		return result, fmt.Errorf("spider91 crawler: build seen list: %w", err)
-	}
-	result.SeenSnapshot = seenCount
-
-	// 2-3. 启动 Python 爬虫（流式 stdout 协议），并边读边处理。
-	//
-	// 协议：Python 每解析出一个 video 的直链就把 entry JSON 写到 stdout 一行，
-	// 立即 flush；本端 bufio.Scanner 收到一行就立即 processOne 下载视频和封面。
-	// 这样把 "Python 等所有视频解析完 + Go 顺序下载 N 个" 重叠成 "Python 翻页找下一个的同时
-	// Go 在下载当前一个"，缩短总耗时；更重要的是把每条直链 e= 过期时间窗用满 ——
-	// 不会因为 Go 在下前面 7 个时让后面 8 个的签名超时。
-	cmd, stdout, err := c.startSpiderTargetNew(ctx, targetNew, seenPath, outputPath)
-	if err != nil {
-		return result, fmt.Errorf("spider91 crawler: spider start: %w", err)
-	}
-
-	scanner := bufio.NewScanner(stdout)
-	scanner.Buffer(make([]byte, 64*1024), 4*1024*1024) // 单条 entry 远小于 4 MB；保险加大上限
-	for scanner.Scan() {
-		if err := ctx.Err(); err != nil {
-			_ = cmd.Process.Kill()
-			break
-		}
-		line := strings.TrimSpace(scanner.Text())
-		if line == "" {
-			continue
-		}
-		var item spiderVideoEntry
-		if jerr := json.Unmarshal([]byte(line), &item); jerr != nil {
-			log.Printf("[spider91] drive=%s stdout parse: %v line=%q", c.cfg.Driver.ID(), jerr, line)
-			continue
-		}
-		result.TotalEntries++
-		sourceID := sourceIDForItem(item)
-		if sourceID == "" || strings.TrimSpace(item.VideoURL) == "" {
-			result.Failed++
-			continue
-		}
-		if result.NewVideos >= targetNew {
-			// Python 侧已用 target_new 控制；这里再兜底防止脚本异常多输出
-			break
-		}
-		videoID := buildVideoID(c.cfg.Driver.ID(), sourceID)
-		if existing, _ := c.cfg.Catalog.GetVideo(ctx, videoID); existing != nil {
-			result.Skipped++
-			continue
-		}
-		if perr := c.processOne(ctx, videoID, item); perr != nil {
-			log.Printf("[spider91] drive=%s viewkey=%s source_id=%s failed: %v", c.cfg.Driver.ID(), item.Viewkey, sourceID, perr)
-			result.Failed++
-			continue
-		}
-		result.NewVideos++
-	}
-	if scerr := scanner.Err(); scerr != nil {
-		log.Printf("[spider91] drive=%s stdout scan: %v", c.cfg.Driver.ID(), scerr)
-	}
-	if werr := cmd.Wait(); werr != nil {
-		// 子进程被我们 Kill 是预期；其它错误（exit code != 0）记录日志但不当致命错误，
-		// 因为流式模式下 stdout 已读完，能拿到的视频已经处理。
-		if ctx.Err() == nil {
-			log.Printf("[spider91] drive=%s spider exit: %v", c.cfg.Driver.ID(), werr)
-		}
-	}
-	return result, nil
-}
-
-// writeSeenViewkeys 把当前 drive 下已入库的 91 源视频 ID 写到 path，供 Python 脚本读取。
-//
-// 注意：不能用 ListVideoFileIDsByDrive（按 drive_id 查），因为 spider91
-// 视频被 spider91migrate 迁移到 PikPak 后 drive_id 已经不再是这个 drive。
-// 改用 ListSpider91Viewkeys：它按 video.id 前缀（"spider91-<driveID>-"）查，
-// 不受迁移影响。函数名保留历史叫法，实际返回的是 ID 后缀；新数据使用 mp4 源 ID。
-func (c *Crawler) writeSeenViewkeys(ctx context.Context, path string) (int, error) {
-	seenIDs, err := c.cfg.Catalog.ListSpider91Viewkeys(ctx, c.cfg.Driver.ID())
-	if err != nil {
-		return 0, err
-	}
-	seen := make(map[string]struct{}, len(seenIDs))
-	for _, id := range seenIDs {
-		id = strings.TrimSpace(id)
-		if id == "" {
-			continue
-		}
-		seen[id] = struct{}{}
-	}
-
-	tmp := path + ".part"
-	f, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o644)
-	if err != nil {
-		return 0, err
-	}
-	for id := range seen {
-		if _, err := f.WriteString(id + "\n"); err != nil {
-			_ = f.Close()
-			_ = os.Remove(tmp)
-			return 0, err
-		}
-	}
-	if err := f.Close(); err != nil {
-		_ = os.Remove(tmp)
-		return 0, err
-	}
-	if err := os.Rename(tmp, path); err != nil {
-		_ = os.Remove(tmp)
-		return 0, err
-	}
-	return len(seen), nil
-}
-
-// runSpiderTargetNew 启动 Python 子进程（--target-new + --seen-viewkeys-file
-// + --stream-output）。返回 cmd 和 stdout 的 reader；调用方按行 JSON 消费 stdout，
-// 每读到一行就立即 processOne，下完再读下一行。Python 的日志被引到 stderr，
-// 由本函数转发到 backend log，不影响 stdout 的 JSONL 协议。
-//
-// 使用方负责调 cmd.Wait()，并 close stdout reader。
-func (c *Crawler) startSpiderTargetNew(ctx context.Context, targetNew int, seenPath, outputPath string) (*exec.Cmd, io.ReadCloser, error) {
-	args := []string{
-		c.cfg.ScriptPath,
-		"--target-new", fmt.Sprintf("%d", targetNew),
-		"--seen-viewkeys-file", seenPath,
-		"--output", outputPath,
-		"--no-resume",
-		"--quiet",
-		"--stream-output",
-	}
-	// 子进程的 ctx 走外层 ctx 即可，不再额外加 SpiderTimeout —— 流式模式下
-	// 单个视频的下载在 Go 端做超时控制（DownloadTimeout）；爬虫脚本主要时间在
-	// 列表/详情页 + 网络等待，整轮上限通过外层 ctx 控制更准确。
-	cmd := exec.CommandContext(ctx, c.cfg.PythonPath, args...)
-	if c.cfg.WorkDir != "" {
-		cmd.Dir = c.cfg.WorkDir
-	}
-	stdout, err := cmd.StdoutPipe()
-	if err != nil {
-		return nil, nil, fmt.Errorf("stdout pipe: %w", err)
-	}
-	stderr, err := cmd.StderrPipe()
-	if err != nil {
-		_ = stdout.Close()
-		return nil, nil, fmt.Errorf("stderr pipe: %w", err)
-	}
-	log.Printf("[spider91] drive=%s exec %s --target-new=%d --seen=%s --output=%s",
-		c.cfg.Driver.ID(), c.cfg.ScriptPath, targetNew, seenPath, outputPath)
-	if err := cmd.Start(); err != nil {
-		_ = stdout.Close()
-		_ = stderr.Close()
-		return nil, nil, fmt.Errorf("start: %w", err)
-	}
-	// stderr 转发到 backend log。子进程退出时 reader 自动 EOF，goroutine 自然结束。
-	go forwardSpiderLog(c.cfg.Driver.ID(), stderr)
-	return cmd, stdout, nil
-}
-
-// forwardSpiderLog 把 Python stderr 逐行转发到 backend log，便于调试。
-func forwardSpiderLog(driveID string, r io.Reader) {
-	scanner := bufio.NewScanner(r)
-	scanner.Buffer(make([]byte, 64*1024), 1024*1024)
-	for scanner.Scan() {
-		line := scanner.Text()
-		if strings.TrimSpace(line) == "" {
-			continue
-		}
-		log.Printf("[spider91:py] drive=%s %s", driveID, line)
-	}
-}
-
-// processOne 处理单个 91 源视频：下载视频 + 封面 + 复制封面 + 入库。
-// 任一步失败会清理已写入的临时文件，不留半成品。
-func (c *Crawler) processOne(ctx context.Context, videoID string, item spiderVideoEntry) error {
-	viewkey := item.Viewkey
-	sourceID := sourceIDForItem(item)
-	if sourceID == "" {
-		return errors.New("empty numeric source id")
-	}
-
-	videoURL := strings.TrimSpace(item.VideoURL)
-	videoSourceID := sourceIDFromVideoURL(videoURL)
-	if videoSourceID == "" {
-		return fmt.Errorf("video url has no numeric source id: %s", videoURL)
-	}
-	if videoSourceID != sourceID {
-		return fmt.Errorf("video source id mismatch: got %s want %s", videoSourceID, sourceID)
-	}
-	thumbURL := normalizeThumbURLForSource(item.ThumbURL, sourceID)
-
-	// 视频文件后缀按直链 URL 真实后缀来定，避免直链返回的不是 mp4 时存错容器。
-	videoExt := detectVideoExt(videoURL)
-	videoFile := sourceID + videoExt
-	// 封面后缀同理，但 91porn 的封面绝大多数是 jpg；URL 提示其它格式时尊重之。
-	thumbFile := sourceID + detectThumbExt(thumbURL)
-
-	videoPath, err := c.cfg.Driver.VideoPath(videoFile)
-	if err != nil {
-		return err
-	}
-	thumbPath, err := c.cfg.Driver.ThumbPath(thumbFile)
-	if err != nil {
-		return err
-	}
-
-	// 视频先下载（必须）；失败直接退出。
-	videoSize, err := c.downloadVideoAtomicWithRefresh(ctx, item, videoPath, videoURL, sourceID)
-	if err != nil {
-		return fmt.Errorf("download video: %w", err)
-	}
-
-	// 封面下载失败不致命，视频本身仍入库；下方在 UpsertVideo 后会把
-	// thumbnail_status 显式标 'failed'（spider91 drive 的 thumb worker 按设计
-	// 不处理 spider91 视频，没人能"兜底"）。
-	thumbReady := false
-	if strings.TrimSpace(thumbURL) != "" {
-		thumbCtx, cancel := c.downloadAttemptContext(ctx)
-		_, err := c.downloadAtomic(thumbCtx, thumbURL, thumbPath, item.DetailURL)
-		cancel()
-		if err != nil {
-			log.Printf("[spider91] drive=%s viewkey=%s source_id=%s thumb download failed: %v", c.cfg.Driver.ID(), viewkey, sourceID, err)
-		} else {
-			thumbReady = true
-		}
-	}
-
-	// 把封面复制到 backend 的标准 thumbs 目录，让 /p/thumb/{videoID} 直接命中。
-	if thumbReady && c.cfg.CommonThumbDir != "" {
-		if err := os.MkdirAll(c.cfg.CommonThumbDir, 0o755); err != nil {
-			log.Printf("[spider91] drive=%s mkdir common thumbs: %v", c.cfg.Driver.ID(), err)
-			thumbReady = false
-		} else {
-			dst := filepath.Join(c.cfg.CommonThumbDir, videoID+".jpg")
-			if err := copyFileAtomic(thumbPath, dst); err != nil {
-				log.Printf("[spider91] drive=%s viewkey=%s source_id=%s copy thumb to common dir: %v", c.cfg.Driver.ID(), viewkey, sourceID, err)
-				thumbReady = false
-			}
-		}
-	}
-
-	// 入库
-	now := time.Now()
-	v := &catalog.Video{
-		ID:            videoID,
-		DriveID:       c.cfg.Driver.ID(),
-		FileID:        videoFile,
-		FileName:      videoFile,
-		Title:         strings.TrimSpace(item.Title),
-		Author:        DefaultAuthor,
-		Tags:          []string{DefaultTag},
-		Ext:           strings.TrimPrefix(videoExt, "."),
-		Quality:       "HD",
-		Size:          videoSize,
-		PreviewStatus: "pending",
-		PublishedAt:   now,
-		CreatedAt:     now,
-		UpdatedAt:     now,
-	}
-	if v.Title == "" {
-		v.Title = sourceID
-	}
-	if thumbReady {
-		// 设了 ThumbnailURL 后 thumb worker 会跳过这条视频，
-		// 不再尝试用 ffmpeg 抽帧（封面已经是网站原图）。
-		v.ThumbnailURL = "/p/thumb/" + v.ID
-	}
-	if err := c.cfg.Catalog.UpsertVideo(ctx, v); err != nil {
-		// 入库失败 → 把刚下载的文件清理掉，避免占盘且下次还要清
-		_ = os.Remove(videoPath)
-		_ = os.Remove(thumbPath)
-		return fmt.Errorf("upsert video: %w", err)
-	}
-	if !thumbReady {
-		// 网站封面下载失败的视频：spider91 drive 的 thumb worker 按设计不
-		// 处理 spider91 视频（封面应是网站原图直接保存），所以没人接手。
-		// 显式标 'failed' 让 CountVideosNeedingThumbnail 排除（条件 status
-		// != 'failed'），否则 enqueueDriveGeneration → waitForThumbnailsBeforePreview
-		// 会因为 count > 0 把 teaser 入队永远卡在等待循环里。
-		_ = c.cfg.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{
-			ThumbnailStatus: "failed",
-		})
-	}
-	if c.cfg.OnNewVideo != nil {
-		c.cfg.OnNewVideo(v)
-	}
-	log.Printf("[spider91] drive=%s viewkey=%s source_id=%s ok title=%q size=%d", c.cfg.Driver.ID(), viewkey, sourceID, v.Title, v.Size)
-	return nil
-}
-
-func (c *Crawler) downloadVideoAtomicWithRefresh(ctx context.Context, item spiderVideoEntry, dst, firstURL, expectedSourceID string) (int64, error) {
-	videoURL := strings.TrimSpace(firstURL)
-	if videoURL == "" {
-		videoURL = strings.TrimSpace(item.VideoURL)
-	}
-	var lastErr error
-	for attempt := 1; attempt <= 3; attempt++ {
-		attemptCtx, cancel := c.downloadAttemptContext(ctx)
-		size, err := c.downloadAtomic(attemptCtx, videoURL, dst, item.DetailURL)
-		cancel()
-		if err == nil {
-			return size, nil
-		}
-		lastErr = err
-		if ctx.Err() != nil || !shouldRefreshSpider91VideoURL(err) {
-			return 0, err
-		}
-		fresh, refreshErr := c.resolveFreshVideoURL(ctx, item)
-		if refreshErr != nil {
-			return 0, fmt.Errorf("%w; refresh video url: %v", err, refreshErr)
-		}
-		if fresh == "" || fresh == videoURL {
-			return 0, err
-		}
-		freshSourceID := sourceIDFromVideoURL(fresh)
-		if freshSourceID == "" {
-			return 0, fmt.Errorf("%w; refreshed video url has no numeric source id: %s", err, fresh)
-		}
-		if expectedSourceID != "" && freshSourceID != expectedSourceID {
-			return 0, fmt.Errorf("%w; refreshed video source id mismatch: got %s want %s", err, freshSourceID, expectedSourceID)
-		}
-		_ = os.Remove(dst + ".part")
-		log.Printf("[spider91] drive=%s viewkey=%s source_id=%s download attempt=%d failed (%v); refreshed video url and retrying",
-			c.cfg.Driver.ID(), item.Viewkey, expectedSourceID, attempt, err)
-		videoURL = fresh
-	}
-	return 0, lastErr
-}
-
-func (c *Crawler) downloadAttemptContext(ctx context.Context) (context.Context, context.CancelFunc) {
-	if c.cfg.DownloadTimeout <= 0 {
-		return ctx, func() {}
-	}
-	return context.WithTimeout(ctx, c.cfg.DownloadTimeout)
-}
-
-// downloadAtomic 下载 url 到 dst，先写到 dst.part 再 rename，避免半截文件。
-// 返回最终文件大小。
-func (c *Crawler) downloadAtomic(ctx context.Context, src, dst, referer string) (int64, error) {
-	if strings.TrimSpace(src) == "" {
-		return 0, errors.New("empty url")
-	}
-	if _, err := url.Parse(src); err != nil {
-		return 0, fmt.Errorf("parse url: %w", err)
-	}
-	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return 0, err
-	}
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, src, nil)
-	if err != nil {
-		return 0, err
-	}
-	req.Header.Set("User-Agent", downloadUA)
-	if referer != "" {
-		req.Header.Set("Referer", referer)
-	}
-
-	resp, err := c.cfg.HTTPClient.Do(req)
-	if err != nil {
-		return 0, err
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return 0, &downloadHTTPError{StatusCode: resp.StatusCode}
-	}
-
-	tmp := dst + ".part"
-	out, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o644)
-	if err != nil {
-		return 0, err
-	}
-	written, copyErr := io.Copy(out, resp.Body)
-	closeErr := out.Close()
-	if copyErr != nil {
-		_ = os.Remove(tmp)
-		return 0, copyErr
-	}
-	if closeErr != nil {
-		_ = os.Remove(tmp)
-		return 0, closeErr
-	}
-	if written <= 0 {
-		_ = os.Remove(tmp)
-		return 0, errors.New("empty body")
-	}
-	if err := os.Rename(tmp, dst); err != nil {
-		_ = os.Remove(tmp)
-		return 0, err
-	}
-	return written, nil
-}
-
-type downloadHTTPError struct {
-	StatusCode int
-}
-
-func (e *downloadHTTPError) Error() string {
-	if e == nil {
-		return "http error"
-	}
-	return fmt.Sprintf("http %d", e.StatusCode)
-}
-
-func shouldRefreshSpider91VideoURL(err error) bool {
-	if err == nil {
-		return false
-	}
-	if errors.Is(err, context.Canceled) {
-		return false
-	}
-	if errors.Is(err, context.DeadlineExceeded) {
-		return true
-	}
-	var httpErr *downloadHTTPError
-	if errors.As(err, &httpErr) {
-		switch httpErr.StatusCode {
-		case http.StatusForbidden, http.StatusNotFound, http.StatusGone, http.StatusRequestedRangeNotSatisfiable,
-			http.StatusTooManyRequests, http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
-			return true
-		default:
-			return false
-		}
-	}
-	text := strings.ToLower(err.Error())
-	return strings.Contains(text, "unexpected eof") ||
-		strings.Contains(text, "connection reset") ||
-		strings.Contains(text, "connection refused") ||
-		strings.Contains(text, "broken pipe") ||
-		strings.Contains(text, "server closed") ||
-		strings.Contains(text, "timeout")
-}
-
-func (c *Crawler) resolveFreshVideoURL(ctx context.Context, item spiderVideoEntry) (string, error) {
-	detailURL := strings.TrimSpace(item.DetailURL)
-	if detailURL == "" {
-		return "", errors.New("empty detail url")
-	}
-	cookieHeader := "mode=d"
-	if warmURL := spider91ListURLForDetail(detailURL); warmURL != "" {
-		if cookies, err := c.fetchSpider91WarmCookies(ctx, warmURL, detailURL); err == nil {
-			cookieHeader = spider91CookieHeader(cookies)
-		} else {
-			log.Printf("[spider91] drive=%s viewkey=%s warm session failed: %v", c.cfg.Driver.ID(), item.Viewkey, err)
-		}
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, detailURL, nil)
-	if err != nil {
-		return "", err
-	}
-	req.Header.Set("User-Agent", downloadUA)
-	req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
-	req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9")
-	req.Header.Set("Cookie", cookieHeader)
-	resp, err := c.cfg.HTTPClient.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return "", &downloadHTTPError{StatusCode: resp.StatusCode}
-	}
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 4*1024*1024))
-	if err != nil {
-		return "", err
-	}
-	videoURL := parseSpider91VideoURL(string(body))
-	if videoURL == "" {
-		return "", errors.New("video url not found in detail page")
-	}
-	return videoURL, nil
-}
-
-func (c *Crawler) fetchSpider91WarmCookies(ctx context.Context, warmURL, referer string) ([]*http.Cookie, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, warmURL, nil)
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("User-Agent", downloadUA)
-	req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
-	req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9")
-	req.Header.Set("Cookie", "mode=d")
-	if referer != "" {
-		req.Header.Set("Referer", referer)
-	}
-	resp, err := c.cfg.HTTPClient.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-	_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 64*1024))
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return nil, &downloadHTTPError{StatusCode: resp.StatusCode}
-	}
-	return resp.Cookies(), nil
-}
-
-func spider91ListURLForDetail(detailURL string) string {
-	u, err := url.Parse(strings.TrimSpace(detailURL))
-	if err != nil || u == nil || u.Scheme == "" || u.Host == "" {
-		return ""
-	}
-	if !strings.Contains(strings.ToLower(u.Host), "91porn.com") {
-		return ""
-	}
-	q := u.Query()
-	page := strings.TrimSpace(q.Get("page"))
-	category := strings.TrimSpace(q.Get("category"))
-	viewtype := strings.TrimSpace(q.Get("viewtype"))
-	if page == "" || category == "" || viewtype == "" {
-		return ""
-	}
-	listURL := *u
-	listURL.Path = "/v.php"
-	listQuery := url.Values{}
-	listQuery.Set("category", category)
-	listQuery.Set("viewtype", viewtype)
-	listQuery.Set("page", page)
-	listURL.RawQuery = listQuery.Encode()
-	listURL.Fragment = ""
-	return listURL.String()
-}
-
-func spider91CookieHeader(cookies []*http.Cookie) string {
-	values := []string{"mode=d"}
-	seen := map[string]bool{"mode": true}
-	for _, cookie := range cookies {
-		if cookie == nil || strings.TrimSpace(cookie.Name) == "" || seen[cookie.Name] {
-			continue
-		}
-		seen[cookie.Name] = true
-		values = append(values, cookie.Name+"="+cookie.Value)
-	}
-	return strings.Join(values, "; ")
-}
-
-var (
-	strencode2RE = regexp.MustCompile(`strencode2\(["']([^"']+)["']\)`)
-	srcAttrRE    = regexp.MustCompile(`src=['"]([^'"]+)['"]`)
-	mp4URLRE     = regexp.MustCompile(`https?://[^\s"'<>]+\.mp4[^\s"'<>]*`)
-)
-
-func parseSpider91VideoURL(html string) string {
-	if html == "" {
-		return ""
-	}
-	if match := strencode2RE.FindStringSubmatch(html); len(match) == 2 {
-		if decoded, err := url.PathUnescape(match[1]); err == nil {
-			if src := srcAttrRE.FindStringSubmatch(decoded); len(src) == 2 {
-				return normalizeHTTPURLSlashes(src[1])
-			}
-		}
-	}
-	if match := mp4URLRE.FindString(html); match != "" {
-		lower := strings.ToLower(match)
-		if !strings.Contains(lower, "kwai") && !strings.Contains(lower, "ad-") {
-			return match
-		}
-	}
-	return ""
-}
-
-func normalizeHTTPURLSlashes(rawURL string) string {
-	u, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || u == nil || u.Scheme == "" || u.Host == "" {
-		return rawURL
-	}
-	for strings.Contains(u.Path, "//") {
-		u.Path = strings.ReplaceAll(u.Path, "//", "/")
-	}
-	return u.String()
-}
-
-func sourceIDForItem(item spiderVideoEntry) string {
-	if id := sanitizeSourceID(item.SourceID); isNumericSourceID(id) {
-		return id
-	}
-	if id := sourceIDFromVideoURL(item.VideoURL); id != "" {
-		return id
-	}
-	if id := sourceIDFromThumbURL(item.ThumbURL); id != "" {
-		return id
-	}
-	return ""
-}
-
-func sourceIDFromVideoURL(rawURL string) string {
-	u, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || u == nil {
-		return ""
-	}
-	base := path.Base(u.Path)
-	ext := strings.ToLower(path.Ext(base))
-	switch ext {
-	case ".mp4", ".m4v", ".mov", ".webm", ".mkv", ".avi", ".flv":
-	default:
-		return ""
-	}
-	id := sanitizeSourceID(strings.TrimSuffix(base, ext))
-	if !isNumericSourceID(id) {
-		return ""
-	}
-	return id
-}
-
-func sourceIDFromThumbURL(rawURL string) string {
-	u, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || u == nil {
-		return ""
-	}
-	base := path.Base(u.Path)
-	ext := strings.ToLower(path.Ext(base))
-	switch ext {
-	case ".jpg", ".jpeg", ".png", ".webp", ".gif":
-	default:
-		return ""
-	}
-	id := sanitizeSourceID(strings.TrimSuffix(base, ext))
-	if !isNumericSourceID(id) {
-		return ""
-	}
-	return id
-}
-
-func sanitizeSourceID(raw string) string {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return ""
-	}
-	var b strings.Builder
-	for _, r := range raw {
-		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '_' || r == '-' {
-			b.WriteRune(r)
-		}
-	}
-	return b.String()
-}
-
-func isNumericSourceID(id string) bool {
-	if id == "" {
-		return false
-	}
-	for _, r := range id {
-		if r < '0' || r > '9' {
-			return false
-		}
-	}
-	return true
-}
-
-func normalizeThumbURLForSource(rawURL, sourceID string) string {
-	sourceID = sanitizeSourceID(sourceID)
-	if strings.TrimSpace(rawURL) == "" || sourceID == "" {
-		return rawURL
-	}
-	u, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || u == nil || u.Scheme == "" || u.Host == "" {
-		return rawURL
-	}
-	base := path.Base(u.Path)
-	ext := strings.ToLower(path.Ext(base))
-	switch ext {
-	case ".jpg", ".jpeg", ".png", ".webp", ".gif":
-	default:
-		return rawURL
-	}
-	dir := path.Dir(u.Path)
-	if dir == "." || dir == "/" || !strings.HasSuffix(dir, "/thumb") {
-		return rawURL
-	}
-	u.Path = path.Join(dir, sourceID+".jpg")
-	u.RawQuery = ""
-	u.Fragment = ""
-	return u.String()
-}
-
-// copyFileAtomic 把 src 复制到 dst，先写 .part 再 rename。
-func copyFileAtomic(src, dst string) error {
-	in, err := os.Open(src)
-	if err != nil {
-		return err
-	}
-	defer in.Close()
-	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return err
-	}
-	tmp := dst + ".part"
-	out, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o644)
-	if err != nil {
-		return err
-	}
-	if _, err := io.Copy(out, in); err != nil {
-		_ = out.Close()
-		_ = os.Remove(tmp)
-		return err
-	}
-	if err := out.Close(); err != nil {
-		_ = os.Remove(tmp)
-		return err
-	}
-	return os.Rename(tmp, dst)
-}
-
-// BuildVideoID 给定 driveID + 91 源视频 ID，按统一规则生成 catalog 中 videos.id。
-// 与 scanner 用法一致：<kind>-<driveID>-<fileID>。
-func BuildVideoID(driveID, sourceID string) string {
-	return buildVideoID(driveID, sourceID)
-}
-
-func buildVideoID(driveID, sourceID string) string {
-	return Kind + "-" + driveID + "-" + sourceID
-}
-
-// detectVideoExt 从直链 URL 推断视频文件后缀。
-//
-// 91porn 直链路径形如 https://.../mp43/xxxx.mp4?st=...，path.Ext("xxxx.mp4") = ".mp4"。
-// 但任何爬虫都可能拿到 .flv / .m3u8 / 没扩展名等情况；这里维护一个白名单：
-//   - .mp4 / .webm / .mkv / .mov / .m4v / .flv / .avi → 直接用
-//   - .m3u8 / .ts → 是流媒体清单，不能直接当单文件视频保存，回退到 .mp4，让上层察觉到下载结果异常
-//   - 其它 → .mp4 兜底
-func detectVideoExt(rawURL string) string {
-	u, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || u == nil {
-		return ".mp4"
-	}
-	base := path.Base(u.Path)
-	ext := strings.ToLower(path.Ext(base))
-	switch ext {
-	case ".mp4", ".webm", ".mkv", ".mov", ".m4v", ".flv", ".avi":
-		return ext
-	}
-	return ".mp4"
-}
-
-// detectThumbExt 从封面 URL 推断后缀。默认 .jpg。
-func detectThumbExt(rawURL string) string {
-	u, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || u == nil {
-		return ".jpg"
-	}
-	base := path.Base(u.Path)
-	ext := strings.ToLower(path.Ext(base))
-	switch ext {
-	case ".jpg", ".jpeg", ".png", ".webp", ".gif":
-		return ext
-	}
-	return ".jpg"
-}

backend/internal/drives/spider91/crawler_test.go

@@ -1,661 +0,0 @@
-package spider91
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"net/url"
-	"os"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/video-site/backend/internal/catalog"
-)
-
-// TestCrawlerRunOnceFullFlow 用一个伪 python 脚本 + httptest 服务器
-// 把 Crawler.RunOnce 的完整流程跑一遍：脚本生成 JSON、下载视频和封面、入库、
-// 重复运行跳过已存在的 91 源视频 ID。
-func TestCrawlerRunOnceFullFlow(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("shell-based fake script only on unix")
-	}
-
-	tmp := t.TempDir()
-
-	// 1. 假 HTTP 服务器：根据路径返回视频数据或封面数据
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case strings.Contains(r.URL.Path, "120001.mp4"):
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("FAKEVIDEO1"))
-		case strings.Contains(r.URL.Path, "120002.mp4"):
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("FAKEVIDEO2BYTES"))
-		case strings.Contains(r.URL.Path, "/thumb/120001.jpg"):
-			w.Header().Set("Content-Type", "image/jpeg")
-			_, _ = w.Write([]byte("\xff\xd8\xff\xe0fakejpg1"))
-		case strings.Contains(r.URL.Path, "/thumb/120002.jpg"):
-			w.Header().Set("Content-Type", "image/jpeg")
-			_, _ = w.Write([]byte("\xff\xd8\xff\xe0fakejpg2"))
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer srv.Close()
-
-	// 2. 假 python 脚本：解析 --output / --stream-output 参数，
-	//    在 stream 模式下逐行 echo 每条视频的 JSON 到 stdout（模拟 Python 端 stream），
-	//    同时仍写 --output 文件作归档。
-	videoEntries := []map[string]string{
-		{
-			"title":      "Video One",
-			"thumb_url":  srv.URL + "/thumb/not-120001.jpg",
-			"video_url":  srv.URL + "/videos/120001.mp4",
-			"viewkey":    "vk-001",
-			"detail_url": srv.URL + "/v.php?viewkey=vk-001",
-		},
-		{
-			"title":      "Video Two",
-			"thumb_url":  srv.URL + "/thumb/not-120002.jpg",
-			"video_url":  srv.URL + "/videos/120002.mp4",
-			"viewkey":    "vk-002",
-			"detail_url": srv.URL + "/v.php?viewkey=vk-002",
-		},
-	}
-	scriptPath := filepath.Join(tmp, "fake_spider.sh")
-	scriptBody := buildFakeSpiderScript(videoEntries)
-	if err := os.WriteFile(scriptPath, []byte(scriptBody), 0o755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	// 3. 准备 catalog + driver + crawler
-	dbPath := filepath.Join(tmp, "test.db")
-	cat, err := catalog.Open(dbPath)
-	if err != nil {
-		t.Fatalf("open catalog: %v", err)
-	}
-	defer cat.Close()
-
-	driveID := "spider91-test"
-	rootDir := filepath.Join(tmp, "spider91", driveID)
-	commonThumbs := filepath.Join(tmp, "previews", "thumbs")
-	drv := New(Config{ID: driveID, RootDir: rootDir})
-
-	// 把 drive 也写入 catalog（Crawler 不直接读，但 main 真实流程会写）
-	if err := cat.UpsertDrive(context.Background(), &catalog.Drive{
-		ID:   driveID,
-		Kind: Kind,
-		Name: "test crawler",
-	}); err != nil {
-		t.Fatalf("upsert drive: %v", err)
-	}
-
-	var newVideos []*catalog.Video
-	c := NewCrawler(CrawlerConfig{
-		Driver:          drv,
-		Catalog:         cat,
-		PythonPath:      "sh",
-		ScriptPath:      scriptPath,
-		CommonThumbDir:  commonThumbs,
-		SpiderTimeout:   10 * time.Second,
-		DownloadTimeout: 10 * time.Second,
-		OnNewVideo: func(v *catalog.Video) {
-			newVideos = append(newVideos, v)
-		},
-	})
-
-	// 4. 第一次 RunOnce：应该新入库 2 条
-	res, err := c.RunOnce(context.Background(), 15)
-	if err != nil {
-		t.Fatalf("RunOnce: %v", err)
-	}
-	if res.NewVideos != 2 || res.Skipped != 0 || res.Failed != 0 {
-		t.Fatalf("first run result: new=%d skipped=%d failed=%d, want 2/0/0",
-			res.NewVideos, res.Skipped, res.Failed)
-	}
-	if res.TargetNew != 15 {
-		t.Fatalf("first run TargetNew = %d, want 15", res.TargetNew)
-	}
-	if res.SeenSnapshot != 0 {
-		t.Fatalf("first run SeenSnapshot = %d, want 0 (catalog empty before first run)", res.SeenSnapshot)
-	}
-	if len(newVideos) != 2 {
-		t.Fatalf("OnNewVideo called %d times, want 2", len(newVideos))
-	}
-
-	// 5. 检查文件落盘
-	for _, item := range []struct {
-		sourceID string
-		size     int64
-	}{
-		{"120001", 10},
-		{"120002", 15},
-	} {
-		videoPath := filepath.Join(rootDir, "videos", item.sourceID+".mp4")
-		info, err := os.Stat(videoPath)
-		if err != nil {
-			t.Fatalf("video %s missing: %v", item.sourceID, err)
-		}
-		if info.Size() != item.size {
-			t.Fatalf("video %s size = %d, want %d", item.sourceID, info.Size(), item.size)
-		}
-
-		thumbPath := filepath.Join(rootDir, "thumbs", item.sourceID+".jpg")
-		if _, err := os.Stat(thumbPath); err != nil {
-			t.Fatalf("thumb %s missing: %v", item.sourceID, err)
-		}
-
-		// 复制到 common thumbs 目录的副本，名字按 videoID 来
-		videoID := BuildVideoID(driveID, item.sourceID)
-		commonThumb := filepath.Join(commonThumbs, videoID+".jpg")
-		if _, err := os.Stat(commonThumb); err != nil {
-			t.Fatalf("common thumb %s missing: %v", commonThumb, err)
-		}
-	}
-
-	// 6. 检查 catalog 入库
-	for _, sourceID := range []string{"120001", "120002"} {
-		videoID := BuildVideoID(driveID, sourceID)
-		v, err := cat.GetVideo(context.Background(), videoID)
-		if err != nil {
-			t.Fatalf("GetVideo %s: %v", videoID, err)
-		}
-		if v.DriveID != driveID {
-			t.Fatalf("video %s drive_id = %q want %q", videoID, v.DriveID, driveID)
-		}
-		if v.FileID != sourceID+".mp4" {
-			t.Fatalf("video %s file_id = %q want %q", videoID, v.FileID, sourceID+".mp4")
-		}
-		if v.ThumbnailURL == "" {
-			t.Fatalf("video %s ThumbnailURL empty (cover should be ready)", videoID)
-		}
-		if v.Author != DefaultAuthor {
-			t.Fatalf("video %s author = %q want %q", videoID, v.Author, DefaultAuthor)
-		}
-		// 每条视频都应该带 "91porn" 标签（UpsertVideo 路径自动同步 tags 表）
-		hasDefaultTag := false
-		for _, tag := range v.Tags {
-			if tag == DefaultTag {
-				hasDefaultTag = true
-				break
-			}
-		}
-		if !hasDefaultTag {
-			t.Fatalf("video %s tags = %v, want contain %q", videoID, v.Tags, DefaultTag)
-		}
-	}
-
-	// 7. 第二次 RunOnce：源视频 ID 已存在 → 全部 skipped，无新文件下载
-	newVideos = nil
-	res2, err := c.RunOnce(context.Background(), 15)
-	if err != nil {
-		t.Fatalf("second RunOnce: %v", err)
-	}
-	if res2.NewVideos != 0 {
-		t.Fatalf("second run NewVideos = %d, want 0", res2.NewVideos)
-	}
-	if res2.Skipped != 2 {
-		t.Fatalf("second run Skipped = %d, want 2", res2.Skipped)
-	}
-	// 第二次运行时 catalog 里已经有 2 条，seen snapshot 应该写出 2 个源视频 ID
-	if res2.SeenSnapshot != 2 {
-		t.Fatalf("second run SeenSnapshot = %d, want 2", res2.SeenSnapshot)
-	}
-	if len(newVideos) != 0 {
-		t.Fatalf("second run OnNewVideo fired %d times, want 0", len(newVideos))
-	}
-}
-
-// TestCrawlerRunOnceMissingScript 报错而不是 panic。
-func TestCrawlerRunOnceMissingScript(t *testing.T) {
-	tmp := t.TempDir()
-	cat, err := catalog.Open(filepath.Join(tmp, "x.db"))
-	if err != nil {
-		t.Fatalf("catalog: %v", err)
-	}
-	defer cat.Close()
-	drv := New(Config{ID: "x", RootDir: filepath.Join(tmp, "x")})
-
-	c := NewCrawler(CrawlerConfig{
-		Driver:     drv,
-		Catalog:    cat,
-		PythonPath: "python3",
-		ScriptPath: filepath.Join(tmp, "does-not-exist.py"),
-	})
-
-	if _, err := c.RunOnce(context.Background(), 1); err == nil {
-		t.Fatalf("expected error for missing script")
-	}
-}
-
-// TestCrawlerThumbDownloadFailureMarksStatusFailed 验证：网站封面下载失败时
-// crawler 把 thumbnail_status 显式标 'failed'，避免 enqueueDriveGeneration 的
-// waitForThumbnailsBeforePreview 因为 count > 0 把 teaser 卡死等待。
-//
-// 历史 bug：之前 thumb 下载失败仅打 log，url=”, status 走 schema DEFAULT 'pending'。
-// CountVideosNeedingThumbnail 条件是 url=” AND status != 'failed' → count=1。
-// spider91 drive 的 thumb worker 按设计不处理 spider91 视频 → 没人会改 status。
-// 结果 teaser 永远卡在 [preview] waiting for 1 thumbnails before teaser generation。
-func TestCrawlerThumbDownloadFailureMarksStatusFailed(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("shell-based fake script only on unix")
-	}
-	tmp := t.TempDir()
-
-	// 假 HTTP 服务器：thumb 路径返回 500，video 正常返回字节。
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case strings.Contains(r.URL.Path, "120101.mp4"):
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("FAKEVIDEO"))
-		case strings.Contains(r.URL.Path, "120101.jpg"):
-			http.Error(w, "broken", http.StatusInternalServerError)
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer srv.Close()
-
-	videoEntries := []map[string]string{
-		{
-			"title":      "Thumb Failure Video",
-			"thumb_url":  srv.URL + "/thumb/120101.jpg",
-			"video_url":  srv.URL + "/videos/120101.mp4",
-			"viewkey":    "vk-thumb-fail",
-			"detail_url": srv.URL + "/v.php?viewkey=vk-thumb-fail",
-		},
-	}
-	scriptPath := filepath.Join(tmp, "fake.sh")
-	if err := os.WriteFile(scriptPath, []byte(buildFakeSpiderScript(videoEntries)), 0o755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	cat, err := catalog.Open(filepath.Join(tmp, "test.db"))
-	if err != nil {
-		t.Fatalf("catalog: %v", err)
-	}
-	defer cat.Close()
-
-	driveID := "thumbfail-drive"
-	drv := New(Config{ID: driveID, RootDir: filepath.Join(tmp, "spider91", driveID)})
-	if err := cat.UpsertDrive(context.Background(), &catalog.Drive{
-		ID: driveID, Kind: Kind, Name: "thumbfail",
-	}); err != nil {
-		t.Fatalf("upsert drive: %v", err)
-	}
-
-	c := NewCrawler(CrawlerConfig{
-		Driver:          drv,
-		Catalog:         cat,
-		PythonPath:      "sh",
-		ScriptPath:      scriptPath,
-		CommonThumbDir:  filepath.Join(tmp, "previews", "thumbs"),
-		SpiderTimeout:   10 * time.Second,
-		DownloadTimeout: 10 * time.Second,
-	})
-
-	res, err := c.RunOnce(context.Background(), 5)
-	if err != nil {
-		t.Fatalf("RunOnce: %v", err)
-	}
-	if res.NewVideos != 1 {
-		t.Fatalf("expected 1 new video, got %d (failed=%d)", res.NewVideos, res.Failed)
-	}
-
-	got, err := cat.GetVideo(context.Background(), "spider91-"+driveID+"-120101")
-	if err != nil {
-		t.Fatalf("get video: %v", err)
-	}
-	if got.ThumbnailURL != "" {
-		t.Errorf("ThumbnailURL = %q, want empty (download failed)", got.ThumbnailURL)
-	}
-
-	// 关键断言：CountVideosNeedingThumbnail 应该返回 0。
-	// 该函数的 SQL 条件是 `url = '' AND status != 'failed'`；如果 crawler 没把
-	// status 标 'failed'（schema DEFAULT 'pending'），count 就会是 1，外层
-	// waitForThumbnailsBeforePreview 会因为 count > 0 把 teaser 卡死等待。
-	count, err := cat.CountVideosNeedingThumbnail(context.Background(), driveID)
-	if err != nil {
-		t.Fatalf("count: %v", err)
-	}
-	if count != 0 {
-		t.Fatalf("CountVideosNeedingThumbnail = %d, want 0 (status should be 'failed' to unblock teaser worker)", count)
-	}
-}
-
-func TestCrawlerUsesCrawlerVideoURLForFirstDownload(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("shell-based fake script only on unix")
-	}
-	tmp := t.TempDir()
-
-	var detailRequests int32
-	var originalRequests int32
-	var wrongRequests int32
-	var srv *httptest.Server
-	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/v.php":
-			atomic.AddInt32(&detailRequests, 1)
-			_, _ = w.Write([]byte(spider91DetailHTML(srv.URL + "/videos/856305.mp4?token=wrong")))
-		case r.URL.Path == "/videos/120201.mp4" && r.URL.Query().Get("token") == "original":
-			atomic.AddInt32(&originalRequests, 1)
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("ORIGINALVIDEO"))
-		case r.URL.Path == "/videos/856305.mp4":
-			atomic.AddInt32(&wrongRequests, 1)
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("WRONGVIDEO"))
-		case r.URL.Path == "/thumb/120201.jpg":
-			w.Header().Set("Content-Type", "image/jpeg")
-			_, _ = w.Write([]byte("\xff\xd8\xff\xe0thumb"))
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer srv.Close()
-
-	entry := map[string]string{
-		"title":      "Use Original URL First",
-		"thumb_url":  srv.URL + "/thumb/wrong-thumb.jpg",
-		"video_url":  srv.URL + "/videos/120201.mp4?token=original",
-		"viewkey":    "vk-use-original",
-		"detail_url": srv.URL + "/v.php?viewkey=vk-use-original",
-	}
-	cat, drv, scriptPath := seedCrawlerTestDeps(t, tmp, "use-original-drive", []map[string]string{entry})
-	c := NewCrawler(CrawlerConfig{
-		Driver:          drv,
-		Catalog:         cat,
-		PythonPath:      "sh",
-		ScriptPath:      scriptPath,
-		CommonThumbDir:  filepath.Join(tmp, "previews", "thumbs"),
-		SpiderTimeout:   10 * time.Second,
-		DownloadTimeout: 10 * time.Second,
-	})
-
-	res, err := c.RunOnce(context.Background(), 1)
-	if err != nil {
-		t.Fatalf("RunOnce: %v", err)
-	}
-	if res.NewVideos != 1 || res.Failed != 0 {
-		t.Fatalf("result new=%d failed=%d, want 1/0", res.NewVideos, res.Failed)
-	}
-	if got := atomic.LoadInt32(&detailRequests); got != 0 {
-		t.Fatalf("detail requests = %d, want 0 (first download should use crawler URL)", got)
-	}
-	if got := atomic.LoadInt32(&originalRequests); got != 1 {
-		t.Fatalf("original URL requests = %d, want 1", got)
-	}
-	if got := atomic.LoadInt32(&wrongRequests); got != 0 {
-		t.Fatalf("wrong source URL requests = %d, want 0", got)
-	}
-	info, err := os.Stat(filepath.Join(drv.RootDir(), "videos", "120201.mp4"))
-	if err != nil {
-		t.Fatalf("original video missing: %v", err)
-	}
-	if info.Size() != int64(len("ORIGINALVIDEO")) {
-		t.Fatalf("original video size = %d, want %d", info.Size(), len("ORIGINALVIDEO"))
-	}
-}
-
-func TestCrawlerRefreshesVideoURLAfterExpiredDownload(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("shell-based fake script only on unix")
-	}
-	tmp := t.TempDir()
-
-	var detailRequests int32
-	var staleRequests int32
-	var freshRequests int32
-	var srv *httptest.Server
-	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/v.php":
-			n := atomic.AddInt32(&detailRequests, 1)
-			videoURL := srv.URL + "/videos/120202.mp4?token=stale"
-			if n > 1 {
-				videoURL = srv.URL + "/videos/120202.mp4?token=fresh"
-			}
-			_, _ = w.Write([]byte(spider91DetailHTML(videoURL)))
-		case r.URL.Path == "/videos/120202.mp4" && r.URL.Query().Get("token") == "stale":
-			atomic.AddInt32(&staleRequests, 1)
-			http.Error(w, "expired", http.StatusForbidden)
-		case r.URL.Path == "/videos/120202.mp4" && r.URL.Query().Get("token") == "fresh":
-			atomic.AddInt32(&freshRequests, 1)
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("REFRESHEDVIDEO"))
-		case r.URL.Path == "/thumb/120202.jpg":
-			w.Header().Set("Content-Type", "image/jpeg")
-			_, _ = w.Write([]byte("\xff\xd8\xff\xe0thumb"))
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer srv.Close()
-
-	entry := map[string]string{
-		"title":      "Refresh After Expired Download",
-		"thumb_url":  srv.URL + "/thumb/wrong-thumb.jpg",
-		"video_url":  srv.URL + "/videos/120202.mp4?token=old",
-		"viewkey":    "vk-refresh-after",
-		"detail_url": srv.URL + "/v.php?viewkey=vk-refresh-after",
-	}
-	cat, drv, scriptPath := seedCrawlerTestDeps(t, tmp, "refresh-after-drive", []map[string]string{entry})
-	c := NewCrawler(CrawlerConfig{
-		Driver:          drv,
-		Catalog:         cat,
-		PythonPath:      "sh",
-		ScriptPath:      scriptPath,
-		CommonThumbDir:  filepath.Join(tmp, "previews", "thumbs"),
-		SpiderTimeout:   10 * time.Second,
-		DownloadTimeout: 10 * time.Second,
-	})
-
-	res, err := c.RunOnce(context.Background(), 1)
-	if err != nil {
-		t.Fatalf("RunOnce: %v", err)
-	}
-	if res.NewVideos != 1 || res.Failed != 0 {
-		t.Fatalf("result new=%d failed=%d, want 1/0", res.NewVideos, res.Failed)
-	}
-	if got := atomic.LoadInt32(&detailRequests); got < 2 {
-		t.Fatalf("detail requests = %d, want at least 2 (initial refresh + retry refresh)", got)
-	}
-	if got := atomic.LoadInt32(&staleRequests); got != 1 {
-		t.Fatalf("stale URL requests = %d, want 1", got)
-	}
-	if got := atomic.LoadInt32(&freshRequests); got != 1 {
-		t.Fatalf("fresh URL requests = %d, want 1", got)
-	}
-	info, err := os.Stat(filepath.Join(drv.RootDir(), "videos", "120202.mp4"))
-	if err != nil {
-		t.Fatalf("refreshed video missing: %v", err)
-	}
-	if info.Size() != int64(len("REFRESHEDVIDEO")) {
-		t.Fatalf("refreshed video size = %d, want %d", info.Size(), len("REFRESHEDVIDEO"))
-	}
-}
-
-func TestCrawlerRejectsRefreshedSourceIDMismatch(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("shell-based fake script only on unix")
-	}
-	tmp := t.TempDir()
-
-	var srv *httptest.Server
-	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/v.php":
-			_, _ = w.Write([]byte(spider91DetailHTML(srv.URL + "/videos/856305.mp4?token=fresh")))
-		case r.URL.Path == "/videos/1203058.mp4":
-			http.Error(w, "expired", http.StatusForbidden)
-		case r.URL.Path == "/videos/856305.mp4":
-			w.Header().Set("Content-Type", "video/mp4")
-			_, _ = w.Write([]byte("WRONGVIDEO"))
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer srv.Close()
-
-	entry := map[string]string{
-		"title":      "Source ID Mismatch",
-		"thumb_url":  srv.URL + "/thumb/1203058.jpg",
-		"video_url":  srv.URL + "/videos/1203058.mp4?token=old",
-		"viewkey":    "86fd91cce1f2e1a154cc",
-		"source_id":  "1203058",
-		"detail_url": srv.URL + "/v.php?viewkey=86fd91cce1f2e1a154cc",
-	}
-	cat, drv, scriptPath := seedCrawlerTestDeps(t, tmp, "mismatch-drive", []map[string]string{entry})
-	c := NewCrawler(CrawlerConfig{
-		Driver:          drv,
-		Catalog:         cat,
-		PythonPath:      "sh",
-		ScriptPath:      scriptPath,
-		CommonThumbDir:  filepath.Join(tmp, "previews", "thumbs"),
-		SpiderTimeout:   10 * time.Second,
-		DownloadTimeout: 10 * time.Second,
-	})
-
-	res, err := c.RunOnce(context.Background(), 1)
-	if err != nil {
-		t.Fatalf("RunOnce: %v", err)
-	}
-	if res.NewVideos != 0 || res.Failed != 1 {
-		t.Fatalf("result new=%d failed=%d, want 0/1", res.NewVideos, res.Failed)
-	}
-	if _, err := os.Stat(filepath.Join(drv.RootDir(), "videos", "1203058.mp4")); !os.IsNotExist(err) {
-		t.Fatalf("mismatched source file should not be written, stat err=%v", err)
-	}
-	if v, _ := cat.GetVideo(context.Background(), BuildVideoID(drv.ID(), "1203058")); v != nil {
-		t.Fatalf("mismatched video should not be inserted: %+v", v)
-	}
-}
-
-func TestSourceIDForItemRequiresNumericSourceID(t *testing.T) {
-	if got := sourceIDForItem(spiderVideoEntry{
-		Viewkey:  "86fd91cce1f2e1a154cc",
-		VideoURL: "https://cdn.example/videos/1203058.mp4?token=x",
-	}); got != "1203058" {
-		t.Fatalf("sourceIDForItem(video url) = %q, want 1203058", got)
-	}
-	if got := sourceIDForItem(spiderVideoEntry{
-		Viewkey:  "86fd91cce1f2e1a154cc",
-		ThumbURL: "https://img.example/thumb/1203058.jpg",
-	}); got != "1203058" {
-		t.Fatalf("sourceIDForItem(thumb url) = %q, want 1203058", got)
-	}
-	if got := sourceIDForItem(spiderVideoEntry{
-		Viewkey:  "86fd91cce1f2e1a154cc",
-		SourceID: "not-numeric",
-		VideoURL: "https://cdn.example/videos/video.mp4",
-	}); got != "" {
-		t.Fatalf("sourceIDForItem(non numeric) = %q, want empty", got)
-	}
-}
-
-func TestNormalizeThumbURLForSource(t *testing.T) {
-	got := normalizeThumbURLForSource("https://img.example/thumb/856305.jpg?x=1#frag", "1203058")
-	want := "https://img.example/thumb/1203058.jpg"
-	if got != want {
-		t.Fatalf("normalizeThumbURLForSource = %q, want %q", got, want)
-	}
-}
-
-func TestSpider91ListURLForDetail(t *testing.T) {
-	got := spider91ListURLForDetail("https://www.91porn.com/view_video.php?viewkey=abc&page=5&c=furum&viewtype=basic&category=top")
-	want := "https://www.91porn.com/v.php?category=top&page=5&viewtype=basic"
-	if got != want {
-		t.Fatalf("spider91ListURLForDetail = %q, want %q", got, want)
-	}
-	if got := spider91ListURLForDetail("http://127.0.0.1/v.php?viewkey=abc&page=5&viewtype=basic&category=top"); got != "" {
-		t.Fatalf("spider91ListURLForDetail(localhost) = %q, want empty", got)
-	}
-}
-
-func TestSpider91CookieHeader(t *testing.T) {
-	got := spider91CookieHeader([]*http.Cookie{
-		{Name: "CLIPSHARE", Value: "abc"},
-		{Name: "ga", Value: "def"},
-		{Name: "mode", Value: "m"},
-	})
-	want := "mode=d; CLIPSHARE=abc; ga=def"
-	if got != want {
-		t.Fatalf("spider91CookieHeader = %q, want %q", got, want)
-	}
-}
-
-func spider91DetailHTML(videoURL string) string {
-	fragment := `<video><source src="` + videoURL + `" type="video/mp4"></video>`
-	return `document.write(strencode2("` + url.PathEscape(fragment) + `"));`
-}
-
-func seedCrawlerTestDeps(t *testing.T, tmp, driveID string, entries []map[string]string) (*catalog.Catalog, *Driver, string) {
-	t.Helper()
-	scriptPath := filepath.Join(tmp, driveID+"-fake.sh")
-	if err := os.WriteFile(scriptPath, []byte(buildFakeSpiderScript(entries)), 0o755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-	cat, err := catalog.Open(filepath.Join(tmp, driveID+".db"))
-	if err != nil {
-		t.Fatalf("catalog: %v", err)
-	}
-	t.Cleanup(func() {
-		if err := cat.Close(); err != nil {
-			t.Fatalf("close catalog: %v", err)
-		}
-	})
-	drv := New(Config{ID: driveID, RootDir: filepath.Join(tmp, "spider91", driveID)})
-	if err := cat.UpsertDrive(context.Background(), &catalog.Drive{
-		ID: driveID, Kind: Kind, Name: driveID,
-	}); err != nil {
-		t.Fatalf("upsert drive: %v", err)
-	}
-	return cat, drv, scriptPath
-}
-
-// buildFakeSpiderScript 生成一个伪 python 脚本（其实是 sh）。
-//
-// 行为：
-//   - 解析 --output FILE / --stream-output 两个 flag
-//   - --stream-output 时：逐行输出每个 entry 的 JSON 到 stdout 并 flush
-//   - --output 时：把完整 JSON 数据写到 FILE（向后兼容，且作归档）
-//
-// 用 sh 来写是为了避免 Python 依赖。每条 entry 的 JSON 用 Go marshal 出来后嵌入。
-func buildFakeSpiderScript(entries []map[string]string) string {
-	var sb strings.Builder
-	sb.WriteString("#!/bin/sh\n")
-	sb.WriteString("out=\"\"; stream=0\n")
-	sb.WriteString("while [ $# -gt 0 ]; do case \"$1\" in --output) out=\"$2\"; shift 2;; --stream-output) stream=1; shift;; *) shift;; esac; done\n")
-
-	// stream 模式：逐行 echo
-	sb.WriteString("if [ \"$stream\" = \"1\" ]; then\n")
-	for _, e := range entries {
-		raw, _ := json.Marshal(e)
-		// 用单引号 here-string 形式确保 JSON 中的双引号原样出来
-		sb.WriteString("  cat <<'STREAM_EOF'\n")
-		sb.Write(raw)
-		sb.WriteString("\nSTREAM_EOF\n")
-	}
-	sb.WriteString("fi\n")
-
-	// 写 --output 文件（带完整 wrapper）
-	sb.WriteString("if [ -n \"$out\" ]; then\n")
-	sb.WriteString("  mkdir -p \"$(dirname \"$out\")\" 2>/dev/null\n")
-	sb.WriteString("  cat > \"$out\" <<'OUT_EOF'\n")
-	wrapper := map[string]any{
-		"crawl_time":   "2026-01-01T00:00:00",
-		"total_videos": len(entries),
-		"videos":       entries,
-	}
-	wrapped, _ := json.MarshalIndent(wrapper, "", "  ")
-	sb.Write(wrapped)
-	sb.WriteString("\nOUT_EOF\n")
-	sb.WriteString("fi\n")
-	return sb.String()
-}

backend/internal/drives/spider91/driver.go

@@ -1,194 +0,0 @@
-// Package spider91 把 91porn 爬虫的产物（本地下载好的视频和封面）
-// 包装成一个 drives.Drive 实现，让它跟其它网盘一样可以挂载到 catalog 上。
-//
-// 与其它 drive 不同的是：
-//   - 数据来源不是云盘 API，而是 Python 子进程跑 spider_91porn.py 后下载到本地
-//   - StreamURL 直接返回本地文件路径，由 api.handleSpider91Video 用 http.ServeFile 服务
-//   - List/Stat 用于 GC 兜底（按本地文件名列出 videos/ 目录）
-package spider91
-
-import (
-	"context"
-	"errors"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-	"time"
-
-	"github.com/video-site/backend/internal/drives"
-)
-
-// Kind 是该 drive 的类型代号，写到 catalog.drives.kind。
-const Kind = "spider91"
-
-// Config 创建 Driver 所需的配置。
-type Config struct {
-	// ID 是 catalog 中的 drive id，driver 用它隔离每个 spider91 实例的本地目录。
-	ID string
-	// RootDir 是该 drive 在磁盘上的根目录，driver 会在下面创建 videos/ 和 thumbs/。
-	// 一般由 backend 拼成 <data_dir>/spider91/<driveID>/。
-	RootDir string
-}
-
-// Driver 实现 drives.Drive。
-type Driver struct {
-	id      string
-	rootDir string
-}
-
-// New 构造一个 Driver。
-func New(c Config) *Driver {
-	return &Driver{
-		id:      c.ID,
-		rootDir: c.RootDir,
-	}
-}
-
-// Kind 返回 "spider91"。
-func (d *Driver) Kind() string { return Kind }
-
-// ID 返回 catalog 中的 drive id。
-func (d *Driver) ID() string { return d.id }
-
-// RootID 返回根目录的逻辑 ID。spider91 没有真正的目录结构，
-// 这里固定返回 "/" 占位，调用方实际不会用它去 List 子目录。
-func (d *Driver) RootID() string { return "/" }
-
-// Init 确保 rootDir/videos 和 rootDir/thumbs 存在。
-func (d *Driver) Init(ctx context.Context) error {
-	if strings.TrimSpace(d.rootDir) == "" {
-		return errors.New("spider91: empty rootDir")
-	}
-	for _, sub := range []string{"videos", "thumbs"} {
-		if err := os.MkdirAll(filepath.Join(d.rootDir, sub), 0o755); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// VideosDir 返回视频文件存放目录的绝对路径。
-func (d *Driver) VideosDir() string { return filepath.Join(d.rootDir, "videos") }
-
-// ThumbsDir 返回封面文件存放目录的绝对路径。
-func (d *Driver) ThumbsDir() string { return filepath.Join(d.rootDir, "thumbs") }
-
-// RootDir 返回 driver 的存储根。
-func (d *Driver) RootDir() string { return d.rootDir }
-
-// VideoPath 返回某个视频文件的绝对路径，并校验路径不会逃出 videos/ 目录。
-func (d *Driver) VideoPath(fileID string) (string, error) {
-	return safeJoin(d.VideosDir(), fileID)
-}
-
-// ThumbPath 返回某个封面文件的绝对路径。
-func (d *Driver) ThumbPath(fileID string) (string, error) {
-	return safeJoin(d.ThumbsDir(), fileID)
-}
-
-// List 列出 videos/ 目录下的视频文件，便于上层做 GC 兜底；
-// dirID 当前会被忽略，spider91 没有目录树。
-func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error) {
-	entries, err := os.ReadDir(d.VideosDir())
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil, nil
-		}
-		return nil, err
-	}
-	out := make([]drives.Entry, 0, len(entries))
-	for _, e := range entries {
-		if e.IsDir() {
-			continue
-		}
-		info, err := e.Info()
-		if err != nil {
-			continue
-		}
-		out = append(out, drives.Entry{
-			ID:      e.Name(),
-			Name:    e.Name(),
-			Size:    info.Size(),
-			IsDir:   false,
-			ModTime: info.ModTime(),
-		})
-	}
-	return out, nil
-}
-
-// Stat 查询单个视频文件的元数据。
-func (d *Driver) Stat(ctx context.Context, fileID string) (*drives.Entry, error) {
-	path, err := d.VideoPath(fileID)
-	if err != nil {
-		return nil, err
-	}
-	info, err := os.Stat(path)
-	if err != nil {
-		return nil, err
-	}
-	return &drives.Entry{
-		ID:      fileID,
-		Name:    fileID,
-		Size:    info.Size(),
-		IsDir:   info.IsDir(),
-		ModTime: info.ModTime(),
-	}, nil
-}
-
-// StreamURL 返回本地视频文件路径，给 ffmpeg / 上层服务使用。
-// 注意：proxy.serve 不能直接处理本地路径，回放要走 api.handleSpider91Video。
-// teaser/封面 worker 通过 localPreviewLink 兜底走本地文件，刚好兼容 path 形式的 URL。
-func (d *Driver) StreamURL(ctx context.Context, fileID string) (*drives.StreamLink, error) {
-	path, err := d.VideoPath(fileID)
-	if err != nil {
-		return nil, err
-	}
-	info, err := os.Stat(path)
-	if err != nil {
-		return nil, err
-	}
-	if info.IsDir() || info.Size() == 0 {
-		return nil, os.ErrNotExist
-	}
-	return &drives.StreamLink{
-		URL:     path,
-		Expires: time.Now().Add(24 * time.Hour),
-	}, nil
-}
-
-// Upload 不支持：上传由 crawler 自己完成，不通过 Drive 接口。
-func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error) {
-	return "", drives.ErrNotSupported
-}
-
-// EnsureDir 不支持。
-func (d *Driver) EnsureDir(ctx context.Context, pathFromRoot string) (string, error) {
-	return "", drives.ErrNotSupported
-}
-
-// safeJoin 把 fileID 拼到 root 下，保证最终路径不会逃出 root。
-// fileID 必须是单纯的文件名（不含 / 或 .. 等组件）。
-func safeJoin(root, fileID string) (string, error) {
-	id := strings.TrimSpace(fileID)
-	if id == "" || filepath.Base(id) != id {
-		return "", errors.New("spider91: invalid file id")
-	}
-	if root == "" {
-		return "", errors.New("spider91: empty root dir")
-	}
-	rootAbs, err := filepath.Abs(root)
-	if err != nil {
-		return "", err
-	}
-	pathAbs, err := filepath.Abs(filepath.Join(rootAbs, id))
-	if err != nil {
-		return "", err
-	}
-	if pathAbs != rootAbs && !strings.HasPrefix(pathAbs, rootAbs+string(os.PathSeparator)) {
-		return "", errors.New("spider91: file id escapes root")
-	}
-	return pathAbs, nil
-}
-
-var _ drives.Drive = (*Driver)(nil)

backend/internal/drives/spider91/driver_test.go

@@ -1,149 +0,0 @@
-package spider91
-
-import (
-	"context"
-	"errors"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-func TestDriverInitCreatesSubdirs(t *testing.T) {
-	dir := t.TempDir()
-	d := New(Config{ID: "test", RootDir: filepath.Join(dir, "drive1")})
-	if err := d.Init(context.Background()); err != nil {
-		t.Fatalf("init: %v", err)
-	}
-	for _, sub := range []string{"videos", "thumbs"} {
-		info, err := os.Stat(filepath.Join(dir, "drive1", sub))
-		if err != nil {
-			t.Fatalf("stat %s: %v", sub, err)
-		}
-		if !info.IsDir() {
-			t.Fatalf("%s is not a dir", sub)
-		}
-	}
-}
-
-func TestDriverInitRejectsEmptyRoot(t *testing.T) {
-	d := New(Config{ID: "test", RootDir: ""})
-	if err := d.Init(context.Background()); err == nil {
-		t.Fatalf("expected error for empty root")
-	}
-}
-
-func TestVideoPathRejectsTraversal(t *testing.T) {
-	dir := t.TempDir()
-	d := New(Config{ID: "test", RootDir: dir})
-	if err := d.Init(context.Background()); err != nil {
-		t.Fatalf("init: %v", err)
-	}
-	cases := []string{
-		"",
-		"   ",
-		"../etc/passwd",
-		"sub/dir.mp4",
-		"./abc.mp4",
-	}
-	for _, c := range cases {
-		if _, err := d.VideoPath(c); err == nil {
-			t.Fatalf("VideoPath(%q) accepted, want error", c)
-		}
-		if _, err := d.ThumbPath(c); err == nil {
-			t.Fatalf("ThumbPath(%q) accepted, want error", c)
-		}
-	}
-}
-
-func TestVideoPathHappy(t *testing.T) {
-	dir := t.TempDir()
-	d := New(Config{ID: "test", RootDir: dir})
-	if err := d.Init(context.Background()); err != nil {
-		t.Fatalf("init: %v", err)
-	}
-	got, err := d.VideoPath("abc.mp4")
-	if err != nil {
-		t.Fatalf("VideoPath: %v", err)
-	}
-	want := filepath.Join(dir, "videos", "abc.mp4")
-	wantAbs, _ := filepath.Abs(want)
-	if got != wantAbs {
-		t.Fatalf("VideoPath: got %q want %q", got, wantAbs)
-	}
-}
-
-func TestListReturnsFiles(t *testing.T) {
-	dir := t.TempDir()
-	d := New(Config{ID: "test", RootDir: dir})
-	if err := d.Init(context.Background()); err != nil {
-		t.Fatalf("init: %v", err)
-	}
-	mustWrite(t, filepath.Join(d.VideosDir(), "abc.mp4"), "data")
-	mustWrite(t, filepath.Join(d.VideosDir(), "def.mp4"), "x")
-
-	entries, err := d.List(context.Background(), "/")
-	if err != nil {
-		t.Fatalf("List: %v", err)
-	}
-	if len(entries) != 2 {
-		t.Fatalf("List len = %d, want 2", len(entries))
-	}
-	names := map[string]int64{}
-	for _, e := range entries {
-		names[e.Name] = e.Size
-	}
-	if names["abc.mp4"] != 4 || names["def.mp4"] != 1 {
-		t.Fatalf("unexpected entries: %+v", names)
-	}
-}
-
-func TestStreamURLReturnsLocalPath(t *testing.T) {
-	dir := t.TempDir()
-	d := New(Config{ID: "test", RootDir: dir})
-	if err := d.Init(context.Background()); err != nil {
-		t.Fatalf("init: %v", err)
-	}
-	mustWrite(t, filepath.Join(d.VideosDir(), "abc.mp4"), "videodata")
-
-	link, err := d.StreamURL(context.Background(), "abc.mp4")
-	if err != nil {
-		t.Fatalf("StreamURL: %v", err)
-	}
-	if !strings.HasSuffix(link.URL, "videos/abc.mp4") {
-		t.Fatalf("StreamURL.URL = %q, want suffix videos/abc.mp4", link.URL)
-	}
-}
-
-func TestStreamURLEmptyFile(t *testing.T) {
-	dir := t.TempDir()
-	d := New(Config{ID: "test", RootDir: dir})
-	if err := d.Init(context.Background()); err != nil {
-		t.Fatalf("init: %v", err)
-	}
-	mustWrite(t, filepath.Join(d.VideosDir(), "abc.mp4"), "")
-	if _, err := d.StreamURL(context.Background(), "abc.mp4"); !errors.Is(err, os.ErrNotExist) {
-		t.Fatalf("empty file should return os.ErrNotExist, got %v", err)
-	}
-}
-
-func TestBuildVideoIDStable(t *testing.T) {
-	id1 := BuildVideoID("crawler1", "abc")
-	id2 := BuildVideoID("crawler1", "abc")
-	if id1 != id2 {
-		t.Fatalf("BuildVideoID not deterministic")
-	}
-	if id1 != "spider91-crawler1-abc" {
-		t.Fatalf("BuildVideoID format unexpected: %q", id1)
-	}
-}
-
-func mustWrite(t *testing.T, path, content string) {
-	t.Helper()
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-		t.Fatalf("mkdir: %v", err)
-	}
-	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
-		t.Fatalf("write: %v", err)
-	}
-}

backend/internal/drives/spider91/ext_test.go

@@ -1,55 +0,0 @@
-package spider91
-
-import "testing"
-
-func TestDetectVideoExt(t *testing.T) {
-	tests := []struct {
-		name string
-		url  string
-		want string
-	}{
-		{"mp4 with token", "https://cdn.example.com/mp43/abc.mp4?st=xyz&e=12345", ".mp4"},
-		{"webm", "https://cdn.example.com/path/video.webm?token=1", ".webm"},
-		{"mkv", "https://cdn.example.com/path/foo.mkv", ".mkv"},
-		{"mov", "https://cdn.example.com/path/foo.mov?x=1", ".mov"},
-		{"flv", "https://cdn.example.com/path/foo.flv", ".flv"},
-		{"m4v", "https://cdn.example.com/path/foo.m4v", ".m4v"},
-		{"avi", "https://cdn.example.com/path/foo.avi", ".avi"},
-		{"m3u8 fallback to mp4", "https://cdn.example.com/path/playlist.m3u8", ".mp4"},
-		{"ts fallback to mp4", "https://cdn.example.com/path/seg001.ts", ".mp4"},
-		{"unknown ext fallback", "https://cdn.example.com/path/foo.weird", ".mp4"},
-		{"no ext fallback", "https://cdn.example.com/v.php?id=12345", ".mp4"},
-		{"empty url", "", ".mp4"},
-		{"uppercase", "https://cdn.example.com/path/FOO.MP4?token=1", ".mp4"},
-	}
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			got := detectVideoExt(tc.url)
-			if got != tc.want {
-				t.Fatalf("detectVideoExt(%q) = %q, want %q", tc.url, got, tc.want)
-			}
-		})
-	}
-}
-
-func TestDetectThumbExt(t *testing.T) {
-	tests := []struct {
-		url  string
-		want string
-	}{
-		{"https://cdn.example.com/thumb/foo.jpg", ".jpg"},
-		{"https://cdn.example.com/thumb/foo.jpeg", ".jpeg"},
-		{"https://cdn.example.com/thumb/foo.png", ".png"},
-		{"https://cdn.example.com/thumb/foo.webp", ".webp"},
-		{"https://cdn.example.com/thumb/foo.gif", ".gif"},
-		{"https://cdn.example.com/thumb/foo.svg", ".jpg"}, // not in whitelist
-		{"https://cdn.example.com/thumb/no-ext", ".jpg"},
-		{"", ".jpg"},
-	}
-	for _, tc := range tests {
-		got := detectThumbExt(tc.url)
-		if got != tc.want {
-			t.Fatalf("detectThumbExt(%q) = %q, want %q", tc.url, got, tc.want)
-		}
-	}
-}

backend/internal/drives/wopan/driver.go

@@ -2,19 +2,23 @@ package wopan
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
+	"log"
 	"net/http"
 	"os"
 	"path"
 	"strings"
+	"sync"
 	"time"
 
 	sdk "github.com/OpenListTeam/wopan-sdk-go"
+	"github.com/go-resty/resty/v2"
 	"github.com/video-site/backend/internal/drives"
 )
 
-// Driver 封装联通沃盘
+// Driver 封装联通网盘
 type Driver struct {
 	id            string
 	rootID        string
@@ -23,14 +27,24 @@ type Driver struct {
 	refreshToken  string
 	client        *sdk.WoClient
 	onTokenUpdate func(access, refresh string)
+	uploadTempDir string
+
+	listMu       sync.Mutex
+	lastListAt   time.Time
+	listInterval time.Duration
+	listCooldown time.Duration
+
+	fileIDMu sync.RWMutex
+	fidToID  map[string]string
 }
 
 type Config struct {
-	ID           string
-	AccessToken  string
-	RefreshToken string
-	FamilyID     string // 空则走个人空间，有值则走家庭空间
-	RootID       string // 根目录 ID，默认 "0"
+	ID            string
+	AccessToken   string
+	RefreshToken  string
+	FamilyID      string // 空则走个人空间，有值则走家庭空间
+	RootID        string // 根目录 ID，默认 "0"
+	UploadTempDir string
 	// 当 SDK 刷新 token 时回调，便于持久化
 	OnTokenUpdate func(access, refresh string)
 }
@@ -47,6 +61,10 @@ func New(c Config) *Driver {
 		accessToken:   c.AccessToken,
 		refreshToken:  c.RefreshToken,
 		onTokenUpdate: c.OnTokenUpdate,
+		uploadTempDir: strings.TrimSpace(c.UploadTempDir),
+		listInterval:  800 * time.Millisecond,
+		listCooldown:  5 * time.Minute,
+		fidToID:       make(map[string]string),
 	}
 }
 
@@ -78,15 +96,41 @@ func (d *Driver) spaceType() string {
 }
 
 func (d *Driver) List(ctx context.Context, dirID string) ([]drives.Entry, error) {
+	d.listMu.Lock()
+	defer d.listMu.Unlock()
+
 	var result []drives.Entry
 	pageNum := 0
 	pageSize := 100
 	for {
-		data, err := d.client.QueryAllFiles(d.spaceType(), dirID, pageNum, pageSize, 0, d.familyID)
-		if err != nil {
-			return nil, fmt.Errorf("wopan list: %w", err)
+		var data *sdk.QueryAllFilesData
+		for attempt := 0; ; attempt++ {
+			if err := d.waitForListSlotLocked(ctx); err != nil {
+				return nil, err
+			}
+			var err error
+			data, err = d.client.QueryAllFiles(d.spaceType(), dirID, pageNum, pageSize, 0, d.familyID, func(req *resty.Request) {
+				req.SetContext(ctx)
+			})
+			if err == nil {
+				break
+			}
+			err = wopanRequestError("list", err)
+			wait, ok := drives.RateLimitRetryAfter(err)
+			if !ok {
+				return nil, err
+			}
+			if wait <= 0 {
+				wait = d.listCooldown
+			}
+			log.Printf("[wopan] list cooling down drive=%s dir=%s page=%d cooldown=%s attempt=%d err=%v",
+				d.id, dirID, pageNum, wait, attempt+1, err)
+			if err := sleepContext(ctx, wait); err != nil {
+				return nil, err
+			}
 		}
 		for _, f := range data.Files {
+			d.rememberFileID(f)
 			result = append(result, fileToEntry(f, dirID))
 		}
 		if len(data.Files) < pageSize {
@@ -103,9 +147,11 @@ func (d *Driver) Stat(ctx context.Context, fileID string) (*drives.Entry, error)
 }
 
 func (d *Driver) StreamURL(ctx context.Context, fileID string) (*drives.StreamLink, error) {
-	data, err := d.client.GetDownloadUrlV2([]string{fileID})
+	data, err := d.client.GetDownloadUrlV2([]string{fileID}, func(req *resty.Request) {
+		req.SetContext(ctx)
+	})
 	if err != nil {
-		return nil, fmt.Errorf("wopan download url: %w", err)
+		return nil, wopanRequestError("download url", err)
 	}
 	if len(data.List) == 0 {
 		return nil, fmt.Errorf("wopan download url: empty response")
@@ -119,7 +165,12 @@ func (d *Driver) StreamURL(ctx context.Context, fileID string) (*drives.StreamLi
 
 func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader, size int64) (string, error) {
 	// wopan SDK 要求 *os.File，先把流落到临时文件再上传
-	tmp, err := os.CreateTemp("", "wopan-upload-*.tmp")
+	if d.uploadTempDir != "" {
+		if err := os.MkdirAll(d.uploadTempDir, 0o755); err != nil {
+			return "", fmt.Errorf("wopan upload: create tmp dir: %w", err)
+		}
+	}
+	tmp, err := os.CreateTemp(d.uploadTempDir, "wopan-upload-*.tmp")
 	if err != nil {
 		return "", err
 	}
@@ -142,9 +193,151 @@ func (d *Driver) Upload(ctx context.Context, parentID, name string, r io.Reader,
 	if err != nil {
 		return "", fmt.Errorf("wopan upload: %w", err)
 	}
+	if fid != "" {
+		if objectID, err := d.findDeleteFileIDInParent(ctx, parentID, drives.SourceFile{
+			FileID: fid,
+			Name:   name,
+			Size:   size,
+		}); err == nil {
+			d.rememberFIDMapping(fid, objectID)
+		} else {
+			log.Printf("[wopan] upload drive=%s parent=%s fid=%s resolve object id: %v", d.id, parentID, fid, err)
+		}
+	}
 	return fid, nil
 }
 
+func (d *Driver) Rename(ctx context.Context, fileID, newName string) error {
+	if d.client == nil {
+		return fmt.Errorf("wopan rename: driver not initialized")
+	}
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return fmt.Errorf("wopan rename: empty file id")
+	}
+	newName = strings.TrimSpace(newName)
+	if newName == "" {
+		return fmt.Errorf("wopan rename: empty new name")
+	}
+	renameID := fileID
+	if cached := d.cachedDeleteFileID(fileID); cached != "" {
+		renameID = cached
+	}
+	if err := d.client.RenameFileOrDirectory(d.spaceType(), 1, renameID, newName, d.familyID, func(req *resty.Request) {
+		req.SetContext(ctx)
+	}); err != nil {
+		return wopanRequestError("rename", err)
+	}
+	return nil
+}
+
+func (d *Driver) Remove(ctx context.Context, fileID string) error {
+	if d.client == nil {
+		return fmt.Errorf("wopan remove: driver not initialized")
+	}
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return fmt.Errorf("wopan remove: empty file id")
+	}
+	deleteID := fileID
+	if cached := d.cachedDeleteFileID(fileID); cached != "" {
+		deleteID = cached
+	}
+	if err := d.deleteFileByObjectID(ctx, deleteID); err != nil {
+		return fmt.Errorf("wopan remove: %w", err)
+	}
+	return nil
+}
+
+func (d *Driver) RemoveSource(ctx context.Context, source drives.SourceFile) error {
+	if d.client == nil {
+		return fmt.Errorf("wopan remove: driver not initialized")
+	}
+	fileID := strings.TrimSpace(source.FileID)
+	if fileID == "" {
+		return fmt.Errorf("wopan remove: empty file id")
+	}
+	deleteID, err := d.resolveDeleteFileID(ctx, source)
+	if err != nil {
+		return err
+	}
+	if err := d.deleteFileByObjectID(ctx, deleteID); err != nil {
+		return fmt.Errorf("wopan remove: %w", err)
+	}
+	return nil
+}
+
+func (d *Driver) deleteFileByObjectID(ctx context.Context, fileID string) error {
+	if err := d.client.DeleteFile(d.spaceType(), nil, []string{fileID}, func(req *resty.Request) {
+		req.SetContext(ctx)
+	}); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (d *Driver) resolveDeleteFileID(ctx context.Context, source drives.SourceFile) (string, error) {
+	fileID := strings.TrimSpace(source.FileID)
+	if fileID == "" {
+		return "", fmt.Errorf("wopan remove: empty file id")
+	}
+	if cached := d.cachedDeleteFileID(fileID); cached != "" {
+		return cached, nil
+	}
+	parentID := strings.TrimSpace(source.ParentID)
+	if parentID == "" {
+		return fileID, nil
+	}
+	return d.findDeleteFileIDInParent(ctx, parentID, source)
+}
+
+func (d *Driver) findDeleteFileIDInParent(ctx context.Context, parentID string, source drives.SourceFile) (string, error) {
+	d.listMu.Lock()
+	defer d.listMu.Unlock()
+
+	pageNum := 0
+	pageSize := 100
+	for {
+		var data *sdk.QueryAllFilesData
+		for attempt := 0; ; attempt++ {
+			if err := d.waitForListSlotLocked(ctx); err != nil {
+				return "", err
+			}
+			var err error
+			data, err = d.client.QueryAllFiles(d.spaceType(), parentID, pageNum, pageSize, 0, d.familyID, func(req *resty.Request) {
+				req.SetContext(ctx)
+			})
+			if err == nil {
+				break
+			}
+			err = wopanRequestError("resolve delete id", err)
+			wait, ok := drives.RateLimitRetryAfter(err)
+			if !ok {
+				return "", err
+			}
+			if wait <= 0 {
+				wait = d.listCooldown
+			}
+			log.Printf("[wopan] resolve delete id cooling down drive=%s parent=%s page=%d cooldown=%s attempt=%d err=%v",
+				d.id, parentID, pageNum, wait, attempt+1, err)
+			if err := sleepContext(ctx, wait); err != nil {
+				return "", err
+			}
+		}
+		for _, f := range data.Files {
+			d.rememberFileID(f)
+			if id, ok := deleteFileIDFromWopanFile(f, source); ok {
+				return id, nil
+			}
+		}
+		if len(data.Files) < pageSize {
+			break
+		}
+		pageNum++
+	}
+	return "", fmt.Errorf("wopan remove: source file %q not found under parent %q", source.FileID, parentID)
+}
+
 func (d *Driver) EnsureDir(ctx context.Context, pathFromRoot string) (string, error) {
 	parts := splitPath(pathFromRoot)
 	currentID := d.rootID
@@ -154,9 +347,11 @@ func (d *Driver) EnsureDir(ctx context.Context, pathFromRoot string) (string, er
 			return "", err
 		}
 		if childID == "" {
-			resp, err := d.client.CreateDirectory(d.spaceType(), currentID, name, d.familyID)
+			resp, err := d.client.CreateDirectory(d.spaceType(), currentID, name, d.familyID, func(req *resty.Request) {
+				req.SetContext(ctx)
+			})
 			if err != nil {
-				return "", fmt.Errorf("wopan mkdir %s: %w", name, err)
+				return "", wopanRequestError("mkdir "+name, err)
 			}
 			childID = resp.Id
 		}
@@ -190,9 +385,12 @@ func fileToEntry(f *sdk.File, parentID string) drives.Entry {
 	mod, _ := time.Parse("2006-01-02 15:04:05", f.CreateTime)
 	name := f.Name
 	isDir := f.Type == 0
-	id := f.Fid
+	id := f.Id
+	if !isDir && f.Fid != "" {
+		id = f.Fid
+	}
 	if id == "" {
-		id = f.Id
+		id = f.Fid
 	}
 	if isDir && !strings.HasSuffix(name, "/") {
 		// 不改 name，只标志
@@ -208,6 +406,128 @@ func fileToEntry(f *sdk.File, parentID string) drives.Entry {
 	}
 }
 
+func (d *Driver) rememberFileID(f *sdk.File) {
+	if f == nil || f.Type == 0 {
+		return
+	}
+	objectID := strings.TrimSpace(f.Id)
+	fid := strings.TrimSpace(f.Fid)
+	if objectID == "" {
+		return
+	}
+	d.fileIDMu.Lock()
+	if d.fidToID == nil {
+		d.fidToID = make(map[string]string)
+	}
+	d.fidToID[objectID] = objectID
+	if fid != "" {
+		d.fidToID[fid] = objectID
+	}
+	d.fileIDMu.Unlock()
+}
+
+func (d *Driver) rememberFIDMapping(fid, objectID string) {
+	fid = strings.TrimSpace(fid)
+	objectID = strings.TrimSpace(objectID)
+	if fid == "" || objectID == "" {
+		return
+	}
+	d.fileIDMu.Lock()
+	if d.fidToID == nil {
+		d.fidToID = make(map[string]string)
+	}
+	d.fidToID[fid] = objectID
+	d.fidToID[objectID] = objectID
+	d.fileIDMu.Unlock()
+}
+
+func (d *Driver) cachedDeleteFileID(fileID string) string {
+	fileID = strings.TrimSpace(fileID)
+	if fileID == "" {
+		return ""
+	}
+	d.fileIDMu.RLock()
+	defer d.fileIDMu.RUnlock()
+	return strings.TrimSpace(d.fidToID[fileID])
+}
+
+func deleteFileIDFromWopanFile(f *sdk.File, source drives.SourceFile) (string, bool) {
+	if f == nil || f.Type == 0 {
+		return "", false
+	}
+	sourceID := strings.TrimSpace(source.FileID)
+	if sourceID == "" {
+		return "", false
+	}
+	objectID := strings.TrimSpace(f.Id)
+	fid := strings.TrimSpace(f.Fid)
+	if objectID == "" {
+		return "", false
+	}
+	if sourceID != objectID && sourceID != fid {
+		return "", false
+	}
+	return objectID, true
+}
+
+func (d *Driver) waitForListSlotLocked(ctx context.Context) error {
+	if d.listInterval <= 0 || d.lastListAt.IsZero() {
+		d.lastListAt = time.Now()
+		return ctx.Err()
+	}
+	next := d.lastListAt.Add(d.listInterval)
+	now := time.Now()
+	if now.Before(next) {
+		if err := sleepContext(ctx, next.Sub(now)); err != nil {
+			return err
+		}
+	}
+	d.lastListAt = time.Now()
+	return ctx.Err()
+}
+
+func sleepContext(ctx context.Context, d time.Duration) error {
+	if d <= 0 {
+		return ctx.Err()
+	}
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func wopanRequestError(step string, err error) error {
+	if err == nil {
+		return nil
+	}
+	wrapped := fmt.Errorf("wopan %s: %w", step, err)
+	if isWopanRateLimitError(err) {
+		return &drives.RateLimitError{
+			Provider: "wopan",
+			Err:      wrapped,
+		}
+	}
+	return wrapped
+}
+
+func isWopanRateLimitError(err error) bool {
+	if err == nil || errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return false
+	}
+	return drives.ErrorMentionsHTTPStatus(err,
+		http.StatusTooManyRequests,
+		http.StatusInternalServerError,
+		http.StatusBadGateway,
+		http.StatusServiceUnavailable,
+		http.StatusGatewayTimeout,
+		509,
+	)
+}
+
 func guessMime(name string) string {
 	ext := strings.ToLower(path.Ext(name))
 	switch ext {
@@ -229,3 +549,5 @@ func guessMime(name string) string {
 
 // 确保实现接口
 var _ drives.Drive = (*Driver)(nil)
+var _ drives.Remover = (*Driver)(nil)
+var _ drives.SourceRemover = (*Driver)(nil)

backend/internal/drives/wopan/driver_test.go

@@ -0,0 +1,113 @@
+package wopan
+
+import (
+	"errors"
+	"testing"
+
+	sdk "github.com/OpenListTeam/wopan-sdk-go"
+	"github.com/video-site/backend/internal/drives"
+)
+
+func TestFileToEntryUsesDirectoryIDAndFileFID(t *testing.T) {
+	dir := fileToEntry(&sdk.File{
+		Id:   "dir-object-id",
+		Fid:  "0",
+		Type: 0,
+		Name: "collection",
+	}, "root")
+	if !dir.IsDir {
+		t.Fatal("directory entry IsDir = false")
+	}
+	if dir.ID != "dir-object-id" {
+		t.Fatalf("directory id = %q, want object id", dir.ID)
+	}
+
+	file := fileToEntry(&sdk.File{
+		Id:   "file-object-id",
+		Fid:  "fid/with/slash",
+		Type: 1,
+		Name: "clip.mp4",
+		Size: 123,
+	}, "dir-object-id")
+	if file.IsDir {
+		t.Fatal("file entry IsDir = true")
+	}
+	if file.ID != "fid/with/slash" {
+		t.Fatalf("file id = %q, want fid for download", file.ID)
+	}
+}
+
+func TestDeleteFileIDFromWopanFileUsesObjectIDForFID(t *testing.T) {
+	got, ok := deleteFileIDFromWopanFile(&sdk.File{
+		Id:   "file-object-id",
+		Fid:  "fid/with/slash",
+		Type: 1,
+		Name: "clip.mp4",
+		Size: 123,
+	}, drives.SourceFile{
+		FileID: "fid/with/slash",
+		Name:   "clip.mp4",
+		Size:   123,
+	})
+	if !ok {
+		t.Fatal("delete file id not resolved")
+	}
+	if got != "file-object-id" {
+		t.Fatalf("delete file id = %q, want object id", got)
+	}
+}
+
+func TestDeleteFileIDFromWopanFileAcceptsObjectID(t *testing.T) {
+	got, ok := deleteFileIDFromWopanFile(&sdk.File{
+		Id:   "file-object-id",
+		Fid:  "fid-1",
+		Type: 1,
+		Name: "clip.mp4",
+		Size: 123,
+	}, drives.SourceFile{
+		FileID: "file-object-id",
+		Name:   "clip.mp4",
+		Size:   123,
+	})
+	if !ok {
+		t.Fatal("delete file id not resolved")
+	}
+	if got != "file-object-id" {
+		t.Fatalf("delete file id = %q, want object id", got)
+	}
+}
+
+func TestDeleteFileIDFromWopanFileRejectsIDMismatch(t *testing.T) {
+	if _, ok := deleteFileIDFromWopanFile(&sdk.File{
+		Id:   "file-object-id",
+		Fid:  "fid-1",
+		Type: 1,
+		Name: "clip.mp4",
+		Size: 123,
+	}, drives.SourceFile{
+		FileID: "other-fid",
+		Name:   "clip.mp4",
+		Size:   123,
+	}); ok {
+		t.Fatal("delete file id resolved despite id mismatch")
+	}
+}
+
+func TestWopanRequestErrorWrapsRateLimit(t *testing.T) {
+	err := wopanRequestError("list", errors.New("request failed with status: 429 Too Many Requests"))
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.Provider != "wopan" {
+		t.Fatalf("provider = %q, want wopan", rateLimit.Provider)
+	}
+}
+
+func TestWopanRequestErrorLeavesNormalErrors(t *testing.T) {
+	err := wopanRequestError("download url", errors.New("invalid access token"))
+	var rateLimit *drives.RateLimitError
+	if errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want non-rate-limit error", err)
+	}
+}

backend/internal/drives/wopan/qr.go

@@ -0,0 +1,349 @@
+package wopan
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-resty/resty/v2"
+)
+
+const (
+	defaultQRCodeAPIBase = "https://panservice.mail.wo.cn/wohome/open/v1/QRCode"
+	defaultQRCodeClient  = "1001000021"
+)
+
+type QRConfig struct {
+	APIBaseURL string
+	HTTPClient *http.Client
+	Now        func() time.Time
+}
+
+type QRClient struct {
+	apiBase string
+	client  *resty.Client
+	now     func() time.Time
+}
+
+type QRCodeSession struct {
+	UUID           string `json:"uuid"`
+	QRImageDataURL string `json:"qrImageDataUrl"`
+	ExpiresAt      string `json:"expiresAt,omitempty"`
+}
+
+type QRCodeStatus struct {
+	State        int    `json:"state"`
+	StatusText   string `json:"statusText"`
+	AccessToken  string `json:"accessToken,omitempty"`
+	RefreshToken string `json:"refreshToken,omitempty"`
+	FamilyID     string `json:"familyID,omitempty"`
+}
+
+func NewQRClient(c QRConfig) *QRClient {
+	apiBase := strings.TrimRight(strings.TrimSpace(c.APIBaseURL), "/")
+	if apiBase == "" {
+		apiBase = defaultQRCodeAPIBase
+	}
+	httpClient := c.HTTPClient
+	if httpClient == nil {
+		httpClient = &http.Client{Timeout: 20 * time.Second}
+	}
+	now := c.Now
+	if now == nil {
+		now = time.Now
+	}
+	return &QRClient{
+		apiBase: apiBase,
+		client: resty.NewWithClient(httpClient).
+			SetTimeout(20*time.Second).
+			SetHeader("Accept", "application/json"),
+		now: now,
+	}
+}
+
+func (c *QRClient) Generate(ctx context.Context) (QRCodeSession, error) {
+	var envelope qrEnvelope
+	res, err := c.request(ctx).
+		SetResult(&envelope).
+		Get(c.apiBase + "/generate")
+	if err != nil {
+		return QRCodeSession{}, err
+	}
+	if res.IsError() {
+		return QRCodeSession{}, qrAPIError(envelope.message(), res.StatusCode())
+	}
+
+	var result qrGenerateResult
+	if err := decodeResult(envelope.Result, &result); err != nil {
+		return QRCodeSession{}, err
+	}
+	result.UUID = strings.TrimSpace(result.UUID)
+	result.Image = strings.TrimSpace(result.Image)
+	if result.UUID == "" {
+		return QRCodeSession{}, errors.New("wopan qr: empty uuid")
+	}
+	if result.Image == "" {
+		return QRCodeSession{}, errors.New("wopan qr: empty image")
+	}
+	return QRCodeSession{
+		UUID:           result.UUID,
+		QRImageDataURL: qrImageDataURL(result.Image),
+		ExpiresAt:      c.now().Add(60 * time.Second).Format(time.RFC3339),
+	}, nil
+}
+
+func (c *QRClient) Poll(ctx context.Context, uuid string) (QRCodeStatus, error) {
+	uuid = strings.TrimSpace(uuid)
+	if uuid == "" {
+		return QRCodeStatus{}, errors.New("uuid is required")
+	}
+
+	var envelope qrEnvelope
+	res, err := c.request(ctx).
+		SetQueryParam("uuid", uuid).
+		SetResult(&envelope).
+		Get(c.apiBase + "/query")
+	if err != nil {
+		return QRCodeStatus{}, err
+	}
+	if res.IsError() {
+		return QRCodeStatus{}, qrAPIError(envelope.message(), res.StatusCode())
+	}
+
+	result, err := decodeResultMap(envelope.Result)
+	if err != nil {
+		return QRCodeStatus{}, err
+	}
+	state := intValue(result["state"])
+	status := QRCodeStatus{
+		State:      state,
+		StatusText: qrStateText(state),
+	}
+	if state != 3 {
+		return status, nil
+	}
+
+	status.AccessToken = findStringByKeys(result, "access_token", "accessToken", "token", "tokenValue")
+	status.RefreshToken = findStringByKeys(result, "refresh_token", "refreshToken")
+	status.FamilyID = findStringByKeys(result, "family_id", "familyId", "familyID", "defaultFamilyId", "defaultHomeId", "homeId")
+	if status.AccessToken == "" || status.RefreshToken == "" {
+		missing := make([]string, 0, 2)
+		if status.AccessToken == "" {
+			missing = append(missing, "access_token")
+		}
+		if status.RefreshToken == "" {
+			missing = append(missing, "refresh_token")
+		}
+		return QRCodeStatus{}, fmt.Errorf("wopan qr: login succeeded but missing %s; available keys: %s",
+			strings.Join(missing, ", "), strings.Join(collectJSONKeys(result), ", "))
+	}
+	return status, nil
+}
+
+func (c *QRClient) request(ctx context.Context) *resty.Request {
+	return c.client.R().
+		SetContext(ctx).
+		SetHeaders(map[string]string{
+			"client-id":       defaultQRCodeClient,
+			"x-yp-client-id":  defaultQRCodeClient,
+			"Accept":          "application/json",
+			"Accept-Language": "zh-CN,zh;q=0.9",
+		})
+}
+
+type qrEnvelope struct {
+	Meta    qrMeta          `json:"meta"`
+	Result  json.RawMessage `json:"result"`
+	Code    any             `json:"code,omitempty"`
+	Message string          `json:"message,omitempty"`
+	Msg     string          `json:"msg,omitempty"`
+}
+
+type qrMeta struct {
+	Code    any    `json:"code,omitempty"`
+	Message string `json:"message,omitempty"`
+	Msg     string `json:"msg,omitempty"`
+}
+
+type qrGenerateResult struct {
+	UUID  string `json:"uuid"`
+	Image string `json:"image"`
+}
+
+func (e qrEnvelope) message() string {
+	for _, s := range []string{e.Message, e.Msg, e.Meta.Message, e.Meta.Msg} {
+		if strings.TrimSpace(s) != "" {
+			return strings.TrimSpace(s)
+		}
+	}
+	return ""
+}
+
+func decodeResult(raw json.RawMessage, dst any) error {
+	if len(raw) == 0 || string(raw) == "null" {
+		return errors.New("wopan qr: empty result")
+	}
+	if err := json.Unmarshal(raw, dst); err != nil {
+		return fmt.Errorf("wopan qr: decode result: %w", err)
+	}
+	return nil
+}
+
+func decodeResultMap(raw json.RawMessage) (map[string]any, error) {
+	var result map[string]any
+	if err := decodeResult(raw, &result); err != nil {
+		return nil, err
+	}
+	if result == nil {
+		return nil, errors.New("wopan qr: empty result")
+	}
+	return result, nil
+}
+
+func qrImageDataURL(image string) string {
+	image = strings.TrimSpace(image)
+	if strings.HasPrefix(strings.ToLower(image), "data:image/") {
+		return image
+	}
+	return "data:image/png;base64," + image
+}
+
+func qrAPIError(message string, httpStatus int) error {
+	message = strings.TrimSpace(message)
+	if message == "" {
+		message = fmt.Sprintf("HTTP %d", httpStatus)
+	}
+	return errors.New(message)
+}
+
+func qrStateText(state int) string {
+	switch state {
+	case 1:
+		return "等待扫码"
+	case 2:
+		return "已扫码，请在联通网盘 App 确认"
+	case 3:
+		return "登录成功"
+	case 4:
+		return "二维码已过期"
+	default:
+		return "未知状态"
+	}
+}
+
+func intValue(v any) int {
+	switch x := v.(type) {
+	case int:
+		return x
+	case int64:
+		return int(x)
+	case float64:
+		return int(x)
+	case json.Number:
+		n, _ := x.Int64()
+		return int(n)
+	case string:
+		n, _ := strconv.Atoi(strings.TrimSpace(x))
+		return n
+	default:
+		return 0
+	}
+}
+
+func findStringByKeys(v any, keys ...string) string {
+	targets := make(map[string]struct{}, len(keys))
+	for _, key := range keys {
+		targets[normalizeJSONKey(key)] = struct{}{}
+	}
+	return findStringByNormalizedKeys(v, targets)
+}
+
+func findStringByNormalizedKeys(v any, targets map[string]struct{}) string {
+	switch x := v.(type) {
+	case map[string]any:
+		for key, value := range x {
+			if _, ok := targets[normalizeJSONKey(key)]; ok {
+				if s := stringValue(value); s != "" {
+					return s
+				}
+			}
+		}
+		for _, value := range x {
+			if s := findStringByNormalizedKeys(value, targets); s != "" {
+				return s
+			}
+		}
+	case []any:
+		for _, value := range x {
+			if s := findStringByNormalizedKeys(value, targets); s != "" {
+				return s
+			}
+		}
+	}
+	return ""
+}
+
+func stringValue(v any) string {
+	switch x := v.(type) {
+	case string:
+		return strings.TrimSpace(x)
+	case int:
+		return strconv.Itoa(x)
+	case int64:
+		return strconv.FormatInt(x, 10)
+	case float64:
+		if x == float64(int64(x)) {
+			return strconv.FormatInt(int64(x), 10)
+		}
+		return strconv.FormatFloat(x, 'f', -1, 64)
+	case json.Number:
+		return strings.TrimSpace(x.String())
+	default:
+		return ""
+	}
+}
+
+func normalizeJSONKey(key string) string {
+	key = strings.ToLower(strings.TrimSpace(key))
+	key = strings.ReplaceAll(key, "_", "")
+	key = strings.ReplaceAll(key, "-", "")
+	key = strings.ReplaceAll(key, " ", "")
+	return key
+}
+
+func collectJSONKeys(v any) []string {
+	seen := map[string]struct{}{}
+	var walk func(any)
+	walk = func(value any) {
+		switch x := value.(type) {
+		case map[string]any:
+			for key, child := range x {
+				if strings.TrimSpace(key) != "" {
+					seen[key] = struct{}{}
+				}
+				walk(child)
+			}
+		case []any:
+			for _, child := range x {
+				walk(child)
+			}
+		}
+	}
+	walk(v)
+
+	keys := make([]string, 0, len(seen))
+	for key := range seen {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	if len(keys) > 16 {
+		keys = append(keys[:16], "...")
+	}
+	return keys
+}

backend/internal/drives/wopan/qr_test.go

@@ -0,0 +1,128 @@
+package wopan
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestQRCodeGenerateUsesServiceImage(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/QRCode/generate" {
+			http.NotFound(w, r)
+			return
+		}
+		if r.Header.Get("client-id") != defaultQRCodeClient {
+			t.Fatalf("client-id = %q, want %q", r.Header.Get("client-id"), defaultQRCodeClient)
+		}
+		if r.Header.Get("x-yp-client-id") != defaultQRCodeClient {
+			t.Fatalf("x-yp-client-id = %q, want %q", r.Header.Get("x-yp-client-id"), defaultQRCodeClient)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"meta": map[string]string{"code": "0000", "message": "ok"},
+			"result": map[string]string{
+				"uuid":  "uuid-1",
+				"image": "iVBORw0KGgo=",
+			},
+		})
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{APIBaseURL: api.URL + "/QRCode"}).Generate(context.Background())
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+	if got.UUID != "uuid-1" {
+		t.Fatalf("uuid = %q, want uuid-1", got.UUID)
+	}
+	if got.QRImageDataURL != "data:image/png;base64,iVBORw0KGgo=" {
+		t.Fatalf("qrImageDataUrl = %q, want PNG data URL", got.QRImageDataURL)
+	}
+	if got.ExpiresAt == "" {
+		t.Fatalf("expiresAt is empty")
+	}
+}
+
+func TestQRCodePollPending(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/QRCode/query" {
+			http.NotFound(w, r)
+			return
+		}
+		if r.URL.Query().Get("uuid") != "uuid-1" {
+			t.Fatalf("uuid query = %q, want uuid-1", r.URL.Query().Get("uuid"))
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"meta": map[string]string{"code": "0000", "message": "ok"},
+			"result": map[string]any{
+				"state":        1,
+				"token":        nil,
+				"refreshToken": nil,
+			},
+		})
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{APIBaseURL: api.URL + "/QRCode"}).Poll(context.Background(), "uuid-1")
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if got.State != 1 || got.StatusText != "等待扫码" || got.AccessToken != "" || got.RefreshToken != "" {
+		t.Fatalf("status = %#v, want pending without tokens", got)
+	}
+}
+
+func TestQRCodePollSuccessMapsTokenFields(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/QRCode/query" {
+			http.NotFound(w, r)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"meta": map[string]string{"code": "0000", "message": "ok"},
+			"result": map[string]any{
+				"state":        3,
+				"token":        "access-1",
+				"refreshToken": "refresh-1",
+			},
+		})
+	}))
+	t.Cleanup(api.Close)
+
+	got, err := NewQRClient(QRConfig{APIBaseURL: api.URL + "/QRCode"}).Poll(context.Background(), "uuid-1")
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if got.State != 3 || got.AccessToken != "access-1" || got.RefreshToken != "refresh-1" {
+		t.Fatalf("status = %#v, want token and refreshToken mapped", got)
+	}
+}
+
+func TestQRCodePollSuccessReportsMissingTokenKeys(t *testing.T) {
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"meta": map[string]string{"code": "0000", "message": "ok"},
+			"result": map[string]any{
+				"state": 3,
+				"user":  map[string]string{"name": "demo"},
+			},
+		})
+	}))
+	t.Cleanup(api.Close)
+
+	_, err := NewQRClient(QRConfig{APIBaseURL: api.URL + "/QRCode"}).Poll(context.Background(), "uuid-1")
+	if err == nil {
+		t.Fatal("Poll() error is nil, want missing token error")
+	}
+	if !strings.Contains(err.Error(), "missing access_token, refresh_token") ||
+		!strings.Contains(err.Error(), "available keys") {
+		t.Fatalf("error = %q, want missing token keys", err.Error())
+	}
+}

backend/internal/fingerprint/worker.go

@@ -0,0 +1,553 @@
+package fingerprint
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/drives"
+)
+
+const (
+	defaultSampleSizeBytes int64 = 512 * 1024
+	defaultFullHashMaxSize int64 = 8 * 1024 * 1024
+	defaultCooldown              = 5 * time.Minute
+	defaultWorkerQueueSize       = 10000
+)
+
+type Config struct {
+	SampleSizeBytes   int64
+	FullHashMaxSize   int64
+	RateLimitCooldown time.Duration
+	HTTPClient        *http.Client
+}
+
+type Worker struct {
+	Catalog *catalog.Catalog
+	Drive   drives.Drive
+	Config  Config
+
+	ch       chan *catalog.Video
+	queue    videoQueue
+	activity taskActivity
+	cooldown cooldownState
+	http     *http.Client
+}
+
+type TaskStatus struct {
+	State         string
+	CurrentTitle  string
+	QueueLength   int
+	CooldownUntil time.Time
+}
+
+func NewWorker(cat *catalog.Catalog, drv drives.Drive, cfg Config) *Worker {
+	hc := cfg.HTTPClient
+	if hc == nil {
+		hc = &http.Client{Timeout: 0}
+	}
+	if cfg.SampleSizeBytes <= 0 {
+		cfg.SampleSizeBytes = defaultSampleSizeBytes
+	}
+	if cfg.FullHashMaxSize <= 0 {
+		cfg.FullHashMaxSize = defaultFullHashMaxSize
+	}
+	if cfg.RateLimitCooldown <= 0 {
+		cfg.RateLimitCooldown = defaultCooldown
+	}
+	return &Worker{
+		Catalog: cat,
+		Drive:   drv,
+		Config:  cfg,
+		ch:      make(chan *catalog.Video, defaultWorkerQueueSize),
+		http:    hc,
+	}
+}
+
+func (w *Worker) Enqueue(v *catalog.Video) bool {
+	if v == nil {
+		return false
+	}
+	if !w.queue.reserve(v.ID) {
+		return true
+	}
+	select {
+	case w.ch <- v:
+		return true
+	default:
+		w.queue.release(v.ID)
+		return false
+	}
+}
+
+func (w *Worker) EnqueueBlocking(ctx context.Context, v *catalog.Video) bool {
+	if v == nil {
+		return false
+	}
+	if !w.queue.reserve(v.ID) {
+		return true
+	}
+	select {
+	case w.ch <- v:
+		return true
+	case <-ctx.Done():
+		w.queue.release(v.ID)
+		return false
+	}
+}
+
+func (w *Worker) Run(ctx context.Context) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case v := <-w.ch:
+			w.processQueued(ctx, v)
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(500 * time.Millisecond):
+			}
+		}
+	}
+}
+
+func (w *Worker) Status() TaskStatus {
+	if w == nil {
+		return TaskStatus{State: "idle"}
+	}
+	currentID, currentTitle := w.activity.current()
+	status := TaskStatus{
+		State:        "idle",
+		CurrentTitle: currentTitle,
+		QueueLength:  w.queue.lengthExcluding(currentID),
+	}
+	if until, ok := w.cooldown.active(time.Now()); ok {
+		status.State = "cooling"
+		status.CooldownUntil = until
+		return status
+	}
+	if currentID != "" {
+		status.State = "generating"
+		return status
+	}
+	if status.QueueLength > 0 {
+		status.State = "queued"
+	}
+	return status
+}
+
+// WaitIdle blocks until the fingerprint queue is empty and no item is being processed.
+func (w *Worker) WaitIdle(ctx context.Context) error {
+	if w == nil {
+		return nil
+	}
+	if w.queue.lengthExcluding("") == 0 {
+		return nil
+	}
+	ticker := time.NewTicker(200 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-ticker.C:
+			if w.queue.lengthExcluding("") == 0 {
+				return nil
+			}
+		}
+	}
+}
+
+func (w *Worker) processQueued(ctx context.Context, v *catalog.Video) {
+	defer w.queue.release(v.ID)
+	if w.Catalog == nil || w.Drive == nil || v == nil || v.ID == "" {
+		return
+	}
+	current, err := w.Catalog.GetVideo(ctx, v.ID)
+	if err != nil {
+		return
+	}
+	if current.SampledSHA256 != "" || current.FingerprintStatus == "ready" || current.Hidden {
+		return
+	}
+	w.activity.start(current)
+	defer w.activity.done()
+	sum, err := Compute(ctx, w.Drive, current, w.Config, w.http)
+	if err != nil {
+		var rl *drives.RateLimitError
+		if errors.As(err, &rl) {
+			wait := rl.RetryAfter
+			if wait <= 0 {
+				wait = w.Config.RateLimitCooldown
+			}
+			until := time.Now().Add(wait)
+			w.cooldown.set(until)
+			log.Printf("[fingerprint] drive=%s rate limited; keep video=%s pending and cool down for %s: %v", w.Drive.ID(), current.ID, wait, err)
+			sleepContext(ctx, wait)
+			w.cooldown.clear(until)
+			return
+		}
+		log.Printf("[fingerprint] video=%s failed: %v", current.ID, err)
+		_ = w.Catalog.UpdateVideoFingerprint(ctx, current.ID, "", "failed", err.Error())
+		return
+	}
+	if err := w.Catalog.UpdateVideoFingerprint(ctx, current.ID, sum, "ready", ""); err != nil {
+		log.Printf("[fingerprint] update video=%s: %v", current.ID, err)
+		return
+	}
+	log.Printf("[fingerprint] video=%s ready sampled_sha256=%s", current.ID, sum)
+}
+
+func Compute(ctx context.Context, drv drives.Drive, v *catalog.Video, cfg Config, hc *http.Client) (string, error) {
+	if drv == nil {
+		return "", errors.New("fingerprint: nil drive")
+	}
+	if v == nil {
+		return "", errors.New("fingerprint: nil video")
+	}
+	if v.Size <= 0 {
+		return "", errors.New("fingerprint: video size is empty")
+	}
+	if cfg.SampleSizeBytes <= 0 {
+		cfg.SampleSizeBytes = defaultSampleSizeBytes
+	}
+	if cfg.FullHashMaxSize <= 0 {
+		cfg.FullHashMaxSize = defaultFullHashMaxSize
+	}
+	if hc == nil {
+		hc = &http.Client{Timeout: 0}
+	}
+	link, err := drv.StreamURL(ctx, v.FileID)
+	if err != nil {
+		return "", fmt.Errorf("fingerprint: stream url: %w", err)
+	}
+	if link == nil || strings.TrimSpace(link.URL) == "" {
+		return "", errors.New("fingerprint: empty stream url")
+	}
+	ranges := sampleRanges(v.Size, cfg.SampleSizeBytes, cfg.FullHashMaxSize)
+	h := sha256.New()
+	writeHashHeader(h, v.Size, ranges)
+	for _, r := range ranges {
+		data, err := readRange(ctx, hc, link, r)
+		if err != nil {
+			return "", err
+		}
+		if int64(len(data)) != r.length {
+			return "", fmt.Errorf("fingerprint: short sample at %d: got %d want %d", r.start, len(data), r.length)
+		}
+		_, _ = h.Write([]byte(fmt.Sprintf("offset=%d length=%d\n", r.start, r.length)))
+		_, _ = h.Write(data)
+		_, _ = h.Write([]byte("\n"))
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+type byteRange struct {
+	start  int64
+	length int64
+}
+
+func sampleRanges(size, sampleSize, fullHashMax int64) []byteRange {
+	if size <= fullHashMax {
+		return []byteRange{{start: 0, length: size}}
+	}
+	if sampleSize > size {
+		sampleSize = size
+	}
+	maxStart := size - sampleSize
+	percents := []int64{0, 20, 40, 60, 80}
+	out := make([]byteRange, 0, len(percents))
+	seen := make(map[int64]struct{}, len(percents))
+	for _, pct := range percents {
+		start := maxStart * pct / 100
+		if _, ok := seen[start]; ok {
+			continue
+		}
+		seen[start] = struct{}{}
+		out = append(out, byteRange{start: start, length: sampleSize})
+	}
+	return out
+}
+
+func writeHashHeader(w io.Writer, size int64, ranges []byteRange) {
+	_, _ = fmt.Fprintf(w, "video-site-sampled-sha256-v1\nsize=%d\nsamples=%d\n", size, len(ranges))
+}
+
+func readRange(ctx context.Context, hc *http.Client, link *drives.StreamLink, r byteRange) ([]byte, error) {
+	u, err := url.Parse(link.URL)
+	if err == nil && (u.Scheme == "http" || u.Scheme == "https") {
+		return readHTTPRange(ctx, hc, link, r)
+	}
+	path := link.URL
+	if err == nil && u.Scheme == "file" {
+		path = u.Path
+	}
+	return readLocalRange(path, r)
+}
+
+func readLocalRange(path string, r byteRange) ([]byte, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("fingerprint: open local stream: %w", err)
+	}
+	defer f.Close()
+	buf := make([]byte, r.length)
+	n, err := f.ReadAt(buf, r.start)
+	if err != nil && !errors.Is(err, io.EOF) {
+		return nil, fmt.Errorf("fingerprint: read local sample: %w", err)
+	}
+	if int64(n) != r.length {
+		return nil, fmt.Errorf("fingerprint: read local sample at %d: got %d want %d", r.start, n, r.length)
+	}
+	return buf, nil
+}
+
+func readHTTPRange(ctx context.Context, hc *http.Client, link *drives.StreamLink, r byteRange) ([]byte, error) {
+	end := r.start + r.length - 1
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, link.URL, nil)
+	if err != nil {
+		return nil, err
+	}
+	for k, vs := range link.Headers {
+		for _, v := range vs {
+			req.Header.Add(k, v)
+		}
+	}
+	req.Header.Set("Range", fmt.Sprintf("bytes=%d-%d", r.start, end))
+	resp, err := hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("fingerprint: read remote sample: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusTooManyRequests {
+		return nil, &drives.RateLimitError{
+			Provider:   "fingerprint",
+			RetryAfter: parseRetryAfter(resp.Header.Get("Retry-After")),
+			Err:        fmt.Errorf("remote sample rate limited: status=%d", resp.StatusCode),
+		}
+	}
+	if resp.StatusCode != http.StatusPartialContent {
+		if resp.StatusCode == http.StatusOK && r.start == 0 {
+			data, err := io.ReadAll(io.LimitReader(resp.Body, r.length+1))
+			if err != nil {
+				return nil, err
+			}
+			if int64(len(data)) == r.length {
+				return data, nil
+			}
+		}
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
+		if remoteRangeResponseLooksRateLimited(link.URL, resp.StatusCode, body) {
+			return nil, &drives.RateLimitError{
+				Provider:   "fingerprint",
+				RetryAfter: parseRetryAfter(resp.Header.Get("Retry-After")),
+				Err:        fmt.Errorf("remote sample rate limited: status=%d body=%s", resp.StatusCode, strings.TrimSpace(string(body))),
+			}
+		}
+		return nil, fmt.Errorf("fingerprint: range request got status=%d for bytes=%d-%d", resp.StatusCode, r.start, end)
+	}
+	return io.ReadAll(io.LimitReader(resp.Body, r.length))
+}
+
+func remoteRangeResponseLooksRateLimited(rawURL string, status int, body []byte) bool {
+	if status == http.StatusTooManyRequests {
+		return true
+	}
+	if isWopanMediaURL(rawURL) && (status == http.StatusForbidden || status == http.StatusTooManyRequests ||
+		status == http.StatusInternalServerError || status == http.StatusBadGateway ||
+		status == http.StatusServiceUnavailable || status == http.StatusGatewayTimeout ||
+		status == 509) {
+		return true
+	}
+	if isGuangYaPanMediaURL(rawURL) && (status == http.StatusForbidden || status == http.StatusTooManyRequests ||
+		status == http.StatusInternalServerError || status == http.StatusBadGateway ||
+		status == http.StatusServiceUnavailable || status == http.StatusGatewayTimeout ||
+		status == 509) {
+		return true
+	}
+	if status == http.StatusForbidden && isGoogleDriveMediaURL(rawURL) {
+		return true
+	}
+	return false
+}
+
+func isWopanMediaURL(rawURL string) bool {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return false
+	}
+	host := strings.ToLower(u.Hostname())
+	path := strings.ToLower(u.Path)
+	return (strings.HasSuffix(host, "pan.wo.cn") ||
+		strings.HasSuffix(host, "smartont.net") ||
+		strings.Contains(host, "wo.cn")) &&
+		strings.Contains(path, "/openapi/download")
+}
+
+func isGuangYaPanMediaURL(rawURL string) bool {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return false
+	}
+	host := strings.ToLower(u.Hostname())
+	return strings.HasSuffix(host, "guangyacdn.com") ||
+		strings.HasSuffix(host, "guangyapan.com")
+}
+
+func isGoogleDriveMediaURL(rawURL string) bool {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return false
+	}
+	host := strings.ToLower(u.Host)
+	path := strings.ToLower(u.Path)
+	return strings.Contains(host, "googleapis.com") && strings.Contains(path, "/drive/")
+}
+
+func parseRetryAfter(raw string) time.Duration {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return 0
+	}
+	if seconds, err := strconv.Atoi(raw); err == nil && seconds > 0 {
+		return time.Duration(seconds) * time.Second
+	}
+	if when, err := http.ParseTime(raw); err == nil {
+		d := time.Until(when)
+		if d > 0 {
+			return d
+		}
+	}
+	return 0
+}
+
+func sleepContext(ctx context.Context, d time.Duration) bool {
+	if d <= 0 {
+		return true
+	}
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return false
+	case <-timer.C:
+		return true
+	}
+}
+
+type taskActivity struct {
+	mu           sync.Mutex
+	currentID    string
+	currentTitle string
+}
+
+func (a *taskActivity) start(v *catalog.Video) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if v == nil {
+		a.currentID = ""
+		a.currentTitle = ""
+		return
+	}
+	a.currentID = v.ID
+	a.currentTitle = v.Title
+}
+
+func (a *taskActivity) done() {
+	a.mu.Lock()
+	a.currentID = ""
+	a.currentTitle = ""
+	a.mu.Unlock()
+}
+
+func (a *taskActivity) current() (string, string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return a.currentID, a.currentTitle
+}
+
+type cooldownState struct {
+	mu    sync.Mutex
+	until time.Time
+}
+
+func (s *cooldownState) set(until time.Time) {
+	s.mu.Lock()
+	s.until = until
+	s.mu.Unlock()
+}
+
+func (s *cooldownState) clear(until time.Time) {
+	s.mu.Lock()
+	if s.until.Equal(until) {
+		s.until = time.Time{}
+	}
+	s.mu.Unlock()
+}
+
+func (s *cooldownState) active(now time.Time) (time.Time, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.until.IsZero() || !s.until.After(now) {
+		return time.Time{}, false
+	}
+	return s.until, true
+}
+
+type videoQueue struct {
+	mu  sync.Mutex
+	ids map[string]struct{}
+}
+
+func (q *videoQueue) reserve(id string) bool {
+	if id == "" {
+		return true
+	}
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	if q.ids == nil {
+		q.ids = make(map[string]struct{})
+	}
+	if _, ok := q.ids[id]; ok {
+		return false
+	}
+	q.ids[id] = struct{}{}
+	return true
+}
+
+func (q *videoQueue) release(id string) {
+	if id == "" {
+		return
+	}
+	q.mu.Lock()
+	delete(q.ids, id)
+	q.mu.Unlock()
+}
+
+func (q *videoQueue) lengthExcluding(currentID string) int {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	n := len(q.ids)
+	if currentID != "" {
+		if _, ok := q.ids[currentID]; ok {
+			n--
+		}
+	}
+	if n < 0 {
+		return 0
+	}
+	return n
+}

backend/internal/fingerprint/worker_test.go

@@ -0,0 +1,182 @@
+package fingerprint
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/video-site/backend/internal/catalog"
+	"github.com/video-site/backend/internal/drives"
+)
+
+func TestComputeLocalFilesWithSameContentMatch(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	body := []byte("same video bytes")
+	a := filepath.Join(dir, "a.mp4")
+	b := filepath.Join(dir, "b.mp4")
+	if err := os.WriteFile(a, body, 0o644); err != nil {
+		t.Fatalf("write a: %v", err)
+	}
+	if err := os.WriteFile(b, body, 0o644); err != nil {
+		t.Fatalf("write b: %v", err)
+	}
+
+	sumA, err := Compute(ctx, &fakeDrive{paths: map[string]string{"a": a}}, &catalog.Video{ID: "a", FileID: "a", Size: int64(len(body))}, Config{}, nil)
+	if err != nil {
+		t.Fatalf("compute a: %v", err)
+	}
+	sumB, err := Compute(ctx, &fakeDrive{paths: map[string]string{"b": b}}, &catalog.Video{ID: "b", FileID: "b", Size: int64(len(body))}, Config{}, nil)
+	if err != nil {
+		t.Fatalf("compute b: %v", err)
+	}
+	if sumA == "" || sumA != sumB {
+		t.Fatalf("fingerprints = %q / %q, want same non-empty", sumA, sumB)
+	}
+}
+
+func TestComputeRemoteUsesRangeSamples(t *testing.T) {
+	ctx := context.Background()
+	data := make([]byte, 10*1024*1024)
+	for i := range data {
+		data[i] = byte(i % 251)
+	}
+	var ranges []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		rawRange := r.Header.Get("Range")
+		ranges = append(ranges, rawRange)
+		var start, end int
+		if _, err := fmt.Sscanf(rawRange, "bytes=%d-%d", &start, &end); err != nil {
+			t.Fatalf("bad range %q: %v", rawRange, err)
+		}
+		w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, end, len(data)))
+		w.WriteHeader(http.StatusPartialContent)
+		_, _ = w.Write(data[start : end+1])
+	}))
+	defer srv.Close()
+
+	drv := &fakeDrive{paths: map[string]string{"remote": srv.URL + "/video.mp4"}}
+	sum, err := Compute(ctx, drv, &catalog.Video{ID: "remote", FileID: "remote", Size: int64(len(data))}, Config{
+		SampleSizeBytes: 4,
+		FullHashMaxSize: 8,
+		HTTPClient:      srv.Client(),
+	}, srv.Client())
+	if err != nil {
+		t.Fatalf("compute remote: %v", err)
+	}
+	if sum == "" {
+		t.Fatal("fingerprint should not be empty")
+	}
+	want := []string{
+		"bytes=0-3",
+		"bytes=2097151-2097154",
+		"bytes=4194302-4194305",
+		"bytes=6291453-6291456",
+		"bytes=8388604-8388607",
+	}
+	if fmt.Sprint(ranges) != fmt.Sprint(want) {
+		t.Fatalf("ranges = %#v, want %#v", ranges, want)
+	}
+}
+
+func TestComputeRemote429ReturnsRateLimit(t *testing.T) {
+	ctx := context.Background()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Retry-After", "60")
+		w.WriteHeader(http.StatusTooManyRequests)
+		_, _ = w.Write([]byte(`{"error":{"code":429}}`))
+	}))
+	defer srv.Close()
+
+	drv := &fakeDrive{paths: map[string]string{"remote": srv.URL + "/video.mp4"}}
+	_, err := Compute(ctx, drv, &catalog.Video{ID: "remote", FileID: "remote", Size: 1024 * 1024}, Config{
+		SampleSizeBytes: 4,
+		FullHashMaxSize: 8,
+		HTTPClient:      srv.Client(),
+	}, srv.Client())
+	if err == nil {
+		t.Fatal("compute succeeded, want rate limit")
+	}
+	var rateLimit *drives.RateLimitError
+	if !errors.As(err, &rateLimit) {
+		t.Fatalf("error = %T %[1]v, want RateLimitError", err)
+	}
+	if rateLimit.RetryAfter != time.Minute {
+		t.Fatalf("retry after = %s, want 1m", rateLimit.RetryAfter)
+	}
+}
+
+func TestWopanRemoteRangeErrorsLookRateLimited(t *testing.T) {
+	for _, tc := range []struct {
+		rawURL string
+		status int
+	}{
+		{rawURL: "https://gxdownload.pan.wo.cn:8445/openapi/download?fid=encoded", status: http.StatusForbidden},
+		{rawURL: "https://du.smartont.net:8445/openapi/download?fid=encoded", status: http.StatusServiceUnavailable},
+		{rawURL: "https://du.smartont.net:8445/openapi/download?fid=encoded", status: 509},
+	} {
+		if !remoteRangeResponseLooksRateLimited(tc.rawURL, tc.status, nil) {
+			t.Fatalf("remoteRangeResponseLooksRateLimited(%q, %d) = false, want true", tc.rawURL, tc.status)
+		}
+	}
+	if remoteRangeResponseLooksRateLimited("https://example.com/video.mp4", http.StatusForbidden, nil) {
+		t.Fatal("generic 403 should not be treated as wopan rate limit")
+	}
+}
+
+func TestGuangYaPanRemoteRangeErrorsLookRateLimited(t *testing.T) {
+	for _, tc := range []struct {
+		rawURL string
+		status int
+	}{
+		{rawURL: "https://txgz02-httpdown.guangyacdn.com/download/?fid=encoded", status: http.StatusForbidden},
+		{rawURL: "https://txgz02-httpdown.guangyacdn.com/download/?fid=encoded", status: http.StatusServiceUnavailable},
+		{rawURL: "https://txgz02-httpdown.guangyacdn.com/download/?fid=encoded", status: 509},
+	} {
+		if !remoteRangeResponseLooksRateLimited(tc.rawURL, tc.status, nil) {
+			t.Fatalf("remoteRangeResponseLooksRateLimited(%q, %d) = false, want true", tc.rawURL, tc.status)
+		}
+	}
+	if remoteRangeResponseLooksRateLimited("https://example.com/video.mp4", http.StatusForbidden, nil) {
+		t.Fatal("generic 403 should not be treated as guangyapan rate limit")
+	}
+}
+
+func TestGoogleDriveRemoteRangeForbiddenLooksRateLimitedByURL(t *testing.T) {
+	if !remoteRangeResponseLooksRateLimited("https://www.googleapis.com/drive/v3/files/file-1?alt=media", http.StatusForbidden, nil) {
+		t.Fatal("google drive media 403 should be treated as rate limit by URL and status")
+	}
+}
+
+type fakeDrive struct {
+	paths map[string]string
+}
+
+func (d *fakeDrive) Kind() string { return "fake" }
+func (d *fakeDrive) ID() string   { return "fake" }
+func (d *fakeDrive) Init(context.Context) error {
+	return nil
+}
+func (d *fakeDrive) List(context.Context, string) ([]drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *fakeDrive) Stat(context.Context, string) (*drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *fakeDrive) StreamURL(_ context.Context, fileID string) (*drives.StreamLink, error) {
+	return &drives.StreamLink{URL: d.paths[fileID], Expires: time.Now().Add(time.Minute)}, nil
+}
+func (d *fakeDrive) Upload(context.Context, string, string, io.Reader, int64) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *fakeDrive) EnsureDir(context.Context, string) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *fakeDrive) RootID() string { return "root" }

backend/internal/mediaasset/paths.go

@@ -0,0 +1,69 @@
+package mediaasset
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"path/filepath"
+	"strings"
+)
+
+const maxPlainStemBytes = 180
+const maxLegacyFilenameBytes = 255
+
+func PreviewPath(localDir, videoID string) string {
+	return filepath.Join(localDir, PreviewFilename(videoID))
+}
+
+func ThumbnailPath(localDir, videoID string) string {
+	return ThumbnailPathInDir(filepath.Join(localDir, "thumbs"), videoID)
+}
+
+func ThumbnailPathInDir(thumbDir, videoID string) string {
+	return filepath.Join(thumbDir, ThumbnailFilename(videoID))
+}
+
+func PreviewPathCandidates(localDir, videoID string) []string {
+	return pathCandidates(localDir, videoID, ".mp4", "")
+}
+
+func ThumbnailPathCandidates(localDir, videoID string) []string {
+	return pathCandidates(localDir, videoID, ".jpg", "thumbs")
+}
+
+func PreviewFilename(videoID string) string {
+	return safeFilename(videoID, ".mp4")
+}
+
+func ThumbnailFilename(videoID string) string {
+	return safeFilename(videoID, ".jpg")
+}
+
+func pathCandidates(localDir, videoID, ext, subdir string) []string {
+	safe := safeFilename(videoID, ext)
+	legacy := videoID + ext
+	base := localDir
+	if subdir != "" {
+		base = filepath.Join(base, subdir)
+	}
+	out := []string{filepath.Join(base, safe)}
+	if legacy != safe && isPlainSafeStem(videoID) && len([]byte(legacy)) <= maxLegacyFilenameBytes {
+		out = append(out, filepath.Join(base, legacy))
+	}
+	return out
+}
+
+func safeFilename(videoID, ext string) string {
+	if isPlainSafeStem(videoID) && len([]byte(videoID))+len(ext) <= maxPlainStemBytes {
+		return videoID + ext
+	}
+	sum := sha256.Sum256([]byte(videoID))
+	return "v-" + hex.EncodeToString(sum[:]) + ext
+}
+
+func isPlainSafeStem(value string) bool {
+	value = strings.TrimSpace(value)
+	if value == "" || value == "." || value == ".." {
+		return false
+	}
+	return !strings.ContainsAny(value, `/\`+"\x00")
+}

backend/internal/mediaasset/paths_test.go

@@ -0,0 +1,56 @@
+package mediaasset
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestFilenamesKeepShortSafeIDs(t *testing.T) {
+	if got := ThumbnailFilename("video-1"); got != "video-1.jpg" {
+		t.Fatalf("thumbnail filename = %q, want video-1.jpg", got)
+	}
+	if got := PreviewFilename("video-1"); got != "video-1.mp4" {
+		t.Fatalf("preview filename = %q, want video-1.mp4", got)
+	}
+}
+
+func TestFilenamesHashLongOrUnsafeIDs(t *testing.T) {
+	longID := "localstorage-" + strings.Repeat("x", 240)
+	got := ThumbnailFilename(longID)
+	if !strings.HasPrefix(got, "v-") || !strings.HasSuffix(got, ".jpg") {
+		t.Fatalf("thumbnail filename = %q, want hashed jpg", got)
+	}
+	if len([]byte(got)) >= len([]byte(longID+".jpg")) {
+		t.Fatalf("thumbnail filename = %q should be shorter than original id", got)
+	}
+
+	unsafe := ThumbnailFilename("dir/video")
+	if unsafe == "dir/video.jpg" || strings.ContainsAny(unsafe, `/\`) {
+		t.Fatalf("unsafe thumbnail filename = %q, want hashed single filename", unsafe)
+	}
+}
+
+func TestThumbnailPathCandidatesIncludeLegacyForHashedIDs(t *testing.T) {
+	localDir := t.TempDir()
+	mediumID := "localstorage-" + strings.Repeat("x", 190)
+	got := ThumbnailPathCandidates(localDir, mediumID)
+	if len(got) != 2 {
+		t.Fatalf("candidates = %#v, want hashed and legacy paths", got)
+	}
+	if got[0] != ThumbnailPath(localDir, mediumID) {
+		t.Fatalf("first candidate = %q, want safe path %q", got[0], ThumbnailPath(localDir, mediumID))
+	}
+	if filepath.Base(got[1]) != mediumID+".jpg" {
+		t.Fatalf("legacy candidate = %q, want original id jpg", got[1])
+	}
+}
+
+func TestThumbnailPathCandidatesSkipOverlongLegacy(t *testing.T) {
+	localDir := t.TempDir()
+	longID := "localstorage-" + strings.Repeat("x", 240)
+	got := ThumbnailPathCandidates(localDir, longID)
+	if len(got) != 1 {
+		t.Fatalf("candidates = %#v, want only hashed path for overlong id", got)
+	}
+}

backend/internal/mediasim/similarity.go

@@ -0,0 +1,280 @@
+package mediasim
+
+import (
+	"image"
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
+	"math"
+	"os"
+	"strings"
+	"unicode"
+)
+
+const (
+	ssimSampleSize    = 96
+	minCoreTitleRunes = 12
+)
+
+var titleCoreSeparators = []string{
+	" - ",
+	" -- ",
+	" — ",
+	" – ",
+	" ｜ ",
+	" | ",
+	"＿",
+	"_",
+	"－",
+	"—",
+	"–",
+	"-",
+	"|",
+}
+
+// TitleSimilarity returns the best normalized Levenshtein similarity in [0, 1]
+// between the full titles and their leading core title segments.
+func TitleSimilarity(a, b string) float64 {
+	leftVariants := titleVariants(a)
+	rightVariants := titleVariants(b)
+	if len(leftVariants) == 0 && len(rightVariants) == 0 {
+		return 1
+	}
+	if len(leftVariants) == 0 || len(rightVariants) == 0 {
+		return 0
+	}
+	best := 0.0
+	for _, left := range leftVariants {
+		for _, right := range rightVariants {
+			score := normalizedLevenshteinSimilarity(left, right)
+			if score > best {
+				best = score
+			}
+		}
+	}
+	return best
+}
+
+// TitleKeys returns the normalized full title and core-title variants used by
+// TitleSimilarity. It is intended for cheap caller-side prefiltering before
+// running the heavier Levenshtein comparison.
+func TitleKeys(value string) []string {
+	return append([]string(nil), titleVariants(value)...)
+}
+
+func normalizedLevenshteinSimilarity(left, right string) float64 {
+	leftRunes := []rune(left)
+	rightRunes := []rune(right)
+	if len(leftRunes) == 0 && len(rightRunes) == 0 {
+		return 1
+	}
+	if len(leftRunes) == 0 || len(rightRunes) == 0 {
+		return 0
+	}
+	maxLen := len(leftRunes)
+	if len(rightRunes) > maxLen {
+		maxLen = len(rightRunes)
+	}
+	return 1 - float64(levenshtein(leftRunes, rightRunes))/float64(maxLen)
+}
+
+func titleVariants(value string) []string {
+	full := normalizeTitle(value)
+	if full == "" {
+		return nil
+	}
+	out := appendTitleVariant(nil, full)
+	if core := normalizeTitleCore(value); core != "" && core != full {
+		out = appendTitleVariant(out, core)
+	}
+	for _, tail := range titleTailVariants(value) {
+		normalized := normalizeTitle(tail)
+		if len([]rune(normalized)) >= minCoreTitleRunes {
+			out = appendTitleVariant(out, normalized)
+		}
+	}
+	return out
+}
+
+func appendTitleVariant(out []string, value string) []string {
+	for _, existing := range out {
+		if existing == value {
+			return out
+		}
+	}
+	return append(out, value)
+}
+
+func titleTailVariants(value string) []string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil
+	}
+	var out []string
+	for _, sep := range []string{"@", "＠"} {
+		if idx := strings.LastIndex(value, sep); idx >= 0 && idx+len(sep) < len(value) {
+			out = append(out, strings.TrimSpace(value[idx+len(sep):]))
+		}
+	}
+	return out
+}
+
+func normalizeTitleCore(value string) string {
+	head := strings.TrimSpace(value)
+	for _, sep := range titleCoreSeparators {
+		if idx := strings.Index(head, sep); idx > 0 {
+			head = strings.TrimSpace(head[:idx])
+			break
+		}
+	}
+	normalized := normalizeTitle(head)
+	if len([]rune(normalized)) < minCoreTitleRunes {
+		return ""
+	}
+	return normalized
+}
+
+func normalizeTitle(value string) string {
+	value = strings.ToLower(strings.TrimSpace(value))
+	for _, ext := range []string{".mp4", ".m4v", ".mkv", ".mov", ".avi", ".webm", ".ts", ".m3u8"} {
+		if strings.HasSuffix(value, ext) {
+			value = strings.TrimSuffix(value, ext)
+			break
+		}
+	}
+	var b strings.Builder
+	for _, r := range value {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			b.WriteRune(r)
+		}
+	}
+	if b.Len() > 0 {
+		return b.String()
+	}
+	return strings.Join(strings.Fields(value), "")
+}
+
+func levenshtein(a, b []rune) int {
+	if len(a) < len(b) {
+		a, b = b, a
+	}
+	previous := make([]int, len(b)+1)
+	current := make([]int, len(b)+1)
+	for j := range previous {
+		previous[j] = j
+	}
+	for i := 1; i <= len(a); i++ {
+		current[0] = i
+		for j := 1; j <= len(b); j++ {
+			cost := 0
+			if a[i-1] != b[j-1] {
+				cost = 1
+			}
+			current[j] = minInt(
+				previous[j]+1,
+				current[j-1]+1,
+				previous[j-1]+cost,
+			)
+		}
+		previous, current = current, previous
+	}
+	return previous[len(b)]
+}
+
+func minInt(values ...int) int {
+	min := values[0]
+	for _, value := range values[1:] {
+		if value < min {
+			min = value
+		}
+	}
+	return min
+}
+
+// ImageSSIM compares two local images using luminance SSIM over a fixed grid.
+func ImageSSIM(leftPath, rightPath string) (float64, error) {
+	left, err := decodeImage(leftPath)
+	if err != nil {
+		return 0, err
+	}
+	right, err := decodeImage(rightPath)
+	if err != nil {
+		return 0, err
+	}
+	return SSIM(left, right), nil
+}
+
+func decodeImage(path string) (image.Image, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	img, _, err := image.Decode(f)
+	if err != nil {
+		return nil, err
+	}
+	return img, nil
+}
+
+// SSIM compares two images after nearest-neighbor sampling onto the same grid.
+func SSIM(left, right image.Image) float64 {
+	if left == nil || right == nil {
+		return 0
+	}
+	leftSamples := grayscaleSamples(left, ssimSampleSize, ssimSampleSize)
+	rightSamples := grayscaleSamples(right, ssimSampleSize, ssimSampleSize)
+	if len(leftSamples) == 0 || len(leftSamples) != len(rightSamples) {
+		return 0
+	}
+
+	var leftMean, rightMean float64
+	for i := range leftSamples {
+		leftMean += leftSamples[i]
+		rightMean += rightSamples[i]
+	}
+	n := float64(len(leftSamples))
+	leftMean /= n
+	rightMean /= n
+
+	var leftVariance, rightVariance, covariance float64
+	for i := range leftSamples {
+		leftDelta := leftSamples[i] - leftMean
+		rightDelta := rightSamples[i] - rightMean
+		leftVariance += leftDelta * leftDelta
+		rightVariance += rightDelta * rightDelta
+		covariance += leftDelta * rightDelta
+	}
+	leftVariance /= n
+	rightVariance /= n
+	covariance /= n
+
+	const c1 = 6.5025  // (0.01 * 255)^2
+	const c2 = 58.5225 // (0.03 * 255)^2
+	denominator := (leftMean*leftMean + rightMean*rightMean + c1) * (leftVariance + rightVariance + c2)
+	if denominator == 0 {
+		return 0
+	}
+	score := ((2*leftMean*rightMean + c1) * (2*covariance + c2)) / denominator
+	if math.IsNaN(score) || math.IsInf(score, 0) {
+		return 0
+	}
+	return score
+}
+
+func grayscaleSamples(img image.Image, width, height int) []float64 {
+	bounds := img.Bounds()
+	if bounds.Dx() <= 0 || bounds.Dy() <= 0 || width <= 0 || height <= 0 {
+		return nil
+	}
+	out := make([]float64, 0, width*height)
+	for y := 0; y < height; y++ {
+		sourceY := bounds.Min.Y + y*bounds.Dy()/height
+		for x := 0; x < width; x++ {
+			sourceX := bounds.Min.X + x*bounds.Dx()/width
+			r, g, b, _ := img.At(sourceX, sourceY).RGBA()
+			out = append(out, 0.299*float64(r>>8)+0.587*float64(g>>8)+0.114*float64(b>>8))
+		}
+	}
+	return out
+}

backend/internal/mediasim/similarity_test.go

@@ -0,0 +1,64 @@
+package mediasim
+
+import (
+	"image"
+	"image/color"
+	"testing"
+)
+
+func TestTitleSimilarityNormalizesPunctuationAndWhitespace(t *testing.T) {
+	score := TitleSimilarity("AB-123  测试视频.mp4", "ab123测试视频")
+	if score < 0.90 {
+		t.Fatalf("similarity = %.3f, want >= 0.90", score)
+	}
+}
+
+func TestTitleSimilarityUsesLeadingCoreTitle(t *testing.T) {
+	score := TitleSimilarity(
+		"反差极品大二女友，叫声可射～，“射进小骚逼里面～” - 性感小皮鞭",
+		"反差极品大二女友，叫声可射～，“射进小骚逼里面～”",
+	)
+	if score < 0.99 {
+		t.Fatalf("similarity = %.3f, want core-title match", score)
+	}
+}
+
+func TestTitleSimilarityDoesNotMatchBySharedSuffixOnly(t *testing.T) {
+	score := TitleSimilarity(
+		"高颜值大学生宿舍自拍视频完整流出 - 同一个来源",
+		"户外旅行风景记录城市夜景合集 - 同一个来源",
+	)
+	if score >= 0.90 {
+		t.Fatalf("similarity = %.3f, want < 0.90", score)
+	}
+}
+
+func TestTitleSimilarityRejectsDifferentTitles(t *testing.T) {
+	score := TitleSimilarity("完全不同的视频标题", "another unrelated movie")
+	if score >= 0.90 {
+		t.Fatalf("similarity = %.3f, want < 0.90", score)
+	}
+}
+
+func TestSSIMScoresIdenticalAndDifferentImages(t *testing.T) {
+	red := solidImage(color.RGBA{R: 220, G: 20, B: 20, A: 255})
+	redAgain := solidImage(color.RGBA{R: 220, G: 20, B: 20, A: 255})
+	blue := solidImage(color.RGBA{R: 20, G: 20, B: 220, A: 255})
+
+	if score := SSIM(red, redAgain); score < 0.999 {
+		t.Fatalf("identical SSIM = %.6f, want close to 1", score)
+	}
+	if score := SSIM(red, blue); score >= 0.95 {
+		t.Fatalf("different SSIM = %.6f, want < 0.95", score)
+	}
+}
+
+func solidImage(c color.RGBA) image.Image {
+	img := image.NewRGBA(image.Rect(0, 0, 32, 32))
+	for y := 0; y < 32; y++ {
+		for x := 0; x < 32; x++ {
+			img.SetRGBA(x, y, c)
+		}
+	}
+	return img
+}

backend/internal/nightly/runner.go

@@ -1,17 +1,19 @@
 // Package nightly orchestrates the single nightly maintenance pipeline that
-// replaces the legacy scanLoop / crawlerLoop / spider91 migrator periodic loop.
+// replaces the legacy scanLoop / crawlerLoop / crawler upload periodic loop.
 //
 // Pipeline (fired once per day at cron_hour, also via TriggerNow for admin
 // "扫描所有网盘"):
 //
-//	Phase 1: for each non-spider91 cloud drive
-//	           scan + delete-detection + enqueue thumb + enqueue teaser
-//	         wait until all thumb / teaser queues are idle
-//	Phase 2: if any spider91 drive configured
-//	           crawl + enqueue teaser for new videos
-//	         wait until teaser queues are idle
-//	Phase 3: spider91 → cloud migration (single sweep, captcha cooldown still
+//	Phase 1: for each non-crawler cloud drive
+//	           scan + delete-detection + enqueue thumb + enqueue preview video
+//	         wait until all thumb / preview-video queues are idle
+//	Phase 2: if any script crawler configured
+//	           crawl + enqueue preview video for new videos
+//	         wait until preview-video queues are idle
+//	Phase 3: crawler local video → cloud upload (single sweep, captcha cooldown still
 //	         honored within this call)
+//	Phase 4: full-library duplicate video maintenance:
+//	         exact size+sampled_sha256 dedupe, then title/duration/thumbnail dedupe
 //
 // A 6h soft deadline guards each pipeline run; phases check deadline at their
 // boundaries and exit cleanly if exceeded (no in-flight ffmpeg / upload is
@@ -62,38 +64,58 @@ type Config struct {
 	MaxDuration time.Duration
 
 	// ListScanTargets returns the drive IDs to run Phase 1 on, in deterministic
-	// order. Should exclude spider91 and localupload drives.
+	// order. Should exclude crawler and localupload drives.
 	ListScanTargets func(ctx context.Context) []string
 
 	// RunScan synchronously runs scan + cleanup + enqueueDriveGeneration for
 	// one drive. Errors are expected to be logged inside, not surfaced.
 	RunScan func(ctx context.Context, driveID string)
 
-	// ListSpider91Drives returns spider91 drive IDs to crawl in Phase 2.
-	// Returns empty slice when no spider91 drive is configured.
-	ListSpider91Drives func(ctx context.Context) []string
+	// ListCrawlerDrives returns script crawler drive IDs to crawl in Phase 2.
+	// Returns empty slice when no crawler is configured.
+	ListCrawlerDrives func(ctx context.Context) []string
 
-	// RunSpider91Crawl synchronously runs one crawl cycle (downloads + thumbs +
-	// teaser enqueue) for a single spider91 drive.
-	RunSpider91Crawl func(ctx context.Context, driveID string)
+	// RunCrawlerCrawl synchronously runs one crawl cycle (downloads + thumbs +
+	// preview-video enqueue) for a single crawler drive.
+	RunCrawlerCrawl func(ctx context.Context, driveID string)
 
-	// WaitPreviewQueuesIdle blocks until both the thumbnail and teaser queues
+	// WaitPreviewQueuesIdle blocks until both the thumbnail and preview-video queues
 	// across all drives are drained (queue empty + no in-flight task). It must
 	// honor ctx cancellation.
 	WaitPreviewQueuesIdle func(ctx context.Context) error
 
-	// RunMigration runs spider91migrate.Migrator.RunOnce for Phase 3.
+	// RunMigration runs crawlerupload.Migrator.RunOnce for Phase 3.
 	RunMigration func(ctx context.Context) error
 
+	// RunDedupeAssetCleanup runs full-library duplicate video maintenance. It
+	// removes duplicate catalog rows and local generated assets, but never
+	// deletes cloud source files.
+	RunDedupeAssetCleanup func(ctx context.Context) error
+
 	// Now is injected for tests; nil → time.Now.
 	Now func() time.Time
 }
 
+type Status struct {
+	State          string
+	Running        bool
+	Queued         bool
+	StartedAt      time.Time
+	LastFinishedAt time.Time
+}
+
 // Runner drives the nightly pipeline.
 type Runner struct {
 	cfg     Config
 	trigger chan struct{} // buffered(1); manual "run now"
 	runMu   sync.Mutex    // prevents overlapping pipeline runs
+
+	stateMu        sync.Mutex
+	running        bool
+	queued         bool
+	startedAt      time.Time
+	lastFinishedAt time.Time
+	currentCancel  context.CancelFunc
 }
 
 // New constructs a Runner. cfg is shallow-copied; defaults are applied.
@@ -131,13 +153,75 @@ func (r *Runner) Run(ctx context.Context) {
 	}
 }
 
-// TriggerNow asks the running loop to fire a pipeline ASAP. If a pipeline is
-// already in progress (or another trigger is already pending), the request
-// is dropped — the in-progress run will absorb the intent.
-func (r *Runner) TriggerNow() {
+// TriggerNow asks the running loop to fire a pipeline ASAP. Only one manual
+// trigger can be active at a time: if a pipeline is already running or waiting
+// in the trigger channel, the request is ignored and returns false.
+func (r *Runner) TriggerNow() bool {
+	r.stateMu.Lock()
+	if r.running || r.queued {
+		r.stateMu.Unlock()
+		return false
+	}
+	r.queued = true
+	r.stateMu.Unlock()
+
 	select {
 	case r.trigger <- struct{}{}:
+		return true
 	default:
+		r.stateMu.Lock()
+		r.queued = false
+		r.stateMu.Unlock()
+		return false
+	}
+}
+
+// StopCurrent cancels the currently running pipeline and drops one queued
+// manual trigger, if present. It returns true when there was something to stop.
+func (r *Runner) StopCurrent() bool {
+	r.stateMu.Lock()
+	wasRunning := r.running
+	wasQueued := r.queued
+	cancel := r.currentCancel
+	r.queued = false
+	r.stateMu.Unlock()
+
+	if wasQueued {
+		select {
+		case <-r.trigger:
+		default:
+		}
+	}
+	if cancel != nil {
+		cancel()
+	}
+	return wasRunning || wasQueued || cancel != nil
+}
+
+func (r *Runner) Status() Status {
+	r.stateMu.Lock()
+	running := r.running
+	queued := r.queued
+	startedAt := r.startedAt
+	lastFinishedAt := r.lastFinishedAt
+	r.stateMu.Unlock()
+
+	state := "idle"
+	switch {
+	case running && queued:
+		state = "running_queued"
+	case running:
+		state = "running"
+	case queued:
+		state = "queued"
+	}
+
+	return Status{
+		State:          state,
+		Running:        running,
+		Queued:         queued,
+		StartedAt:      startedAt,
+		LastFinishedAt: lastFinishedAt,
 	}
 }
 
@@ -171,13 +255,28 @@ func shouldRun(now time.Time, lastRunDate string) bool {
 //
 // 流水线没有总耗时上限：一直跑到 ctx 取消（进程退出）或所有 phase 完成。
 func (r *Runner) runPipelineLocked(ctx context.Context, manual bool) {
+	if manual {
+		r.stateMu.Lock()
+		queued := r.queued
+		r.stateMu.Unlock()
+		if !queued {
+			log.Printf("[nightly] manual trigger was canceled before start")
+			return
+		}
+	}
 	if !r.runMu.TryLock() {
 		log.Printf("[nightly] another pipeline is already running, skipping this trigger")
 		return
 	}
-	defer r.runMu.Unlock()
 
 	started := r.cfg.Now()
+	runCtx, cancel := context.WithCancel(ctx)
+	r.markStarted(started, cancel)
+	defer func() {
+		cancel()
+		r.markFinished(r.cfg.Now())
+		r.runMu.Unlock()
+	}()
 
 	mode := "scheduled"
 	if manual {
@@ -185,7 +284,7 @@ func (r *Runner) runPipelineLocked(ctx context.Context, manual bool) {
 	}
 	log.Printf("[nightly] pipeline (%s) start", mode)
 
-	r.runPipeline(ctx)
+	r.runPipeline(runCtx)
 
 	finished := r.cfg.Now()
 	log.Printf("[nightly] pipeline (%s) finish; took=%s", mode, finished.Sub(started).Round(time.Second))
@@ -199,6 +298,24 @@ func (r *Runner) runPipelineLocked(ctx context.Context, manual bool) {
 	}
 }
 
+func (r *Runner) markStarted(started time.Time, cancel context.CancelFunc) {
+	r.stateMu.Lock()
+	defer r.stateMu.Unlock()
+	r.running = true
+	r.queued = false
+	r.startedAt = started
+	r.currentCancel = cancel
+}
+
+func (r *Runner) markFinished(finished time.Time) {
+	r.stateMu.Lock()
+	defer r.stateMu.Unlock()
+	r.running = false
+	r.startedAt = time.Time{}
+	r.lastFinishedAt = finished
+	r.currentCancel = nil
+}
+
 // runPipeline executes the three phases. It returns when the pipeline finishes
 // OR ctx is done (deadline / cancel). Errors are logged but not propagated —
 // each phase is best-effort; downstream phases still attempt to run unless ctx
@@ -234,22 +351,23 @@ func (r *Runner) runPipeline(ctx context.Context) {
 	if r.checkDeadline(ctx, "phase 2") {
 		return
 	}
-	spiderIDs := []string{}
-	if r.cfg.ListSpider91Drives != nil {
-		spiderIDs = r.cfg.ListSpider91Drives(ctx)
+	crawlerIDs := []string{}
+	if r.cfg.ListCrawlerDrives != nil {
+		crawlerIDs = r.cfg.ListCrawlerDrives(ctx)
 	}
-	if len(spiderIDs) == 0 {
-		log.Printf("[nightly] phase 2/3 skipped: no spider91 drive configured")
+	if len(crawlerIDs) == 0 {
+		log.Printf("[nightly] phase 2/3 skipped: no crawler configured")
+		r.runDedupeAssetCleanupPhase(ctx)
 		return
 	}
-	log.Printf("[nightly] phase 2: crawling %d spider91 drive(s)", len(spiderIDs))
-	for _, id := range spiderIDs {
+	log.Printf("[nightly] phase 2: crawling %d crawler drive(s)", len(crawlerIDs))
+	for _, id := range crawlerIDs {
 		if ctx.Err() != nil {
 			log.Printf("[nightly] phase 2 aborted by ctx: %v", ctx.Err())
 			return
 		}
 		log.Printf("[nightly] phase 2: crawling drive=%s", id)
-		r.cfg.RunSpider91Crawl(ctx, id)
+		r.cfg.RunCrawlerCrawl(ctx, id)
 	}
 	log.Printf("[nightly] phase 2: waiting for teaser queue to drain")
 	if err := r.waitIdle(ctx, "phase 2"); err != nil {
@@ -260,12 +378,14 @@ func (r *Runner) runPipeline(ctx context.Context) {
 	if r.checkDeadline(ctx, "phase 3") {
 		return
 	}
-	log.Printf("[nightly] phase 3: spider91 migration")
+	log.Printf("[nightly] phase 3: crawler upload")
 	if r.cfg.RunMigration != nil {
 		if err := r.cfg.RunMigration(ctx); err != nil {
 			log.Printf("[nightly] phase 3 migration: %v", err)
 		}
 	}
+
+	r.runDedupeAssetCleanupPhase(ctx)
 }
 
 // checkDeadline returns true when ctx is already done (runner shutting down or
@@ -291,6 +411,19 @@ func (r *Runner) waitIdle(ctx context.Context, phase string) error {
 	return nil
 }
 
+func (r *Runner) runDedupeAssetCleanupPhase(ctx context.Context) {
+	if r.checkDeadline(ctx, "phase 4") {
+		return
+	}
+	if r.cfg.RunDedupeAssetCleanup == nil {
+		return
+	}
+	log.Printf("[nightly] phase 4: duplicate video maintenance")
+	if err := r.cfg.RunDedupeAssetCleanup(ctx); err != nil {
+		log.Printf("[nightly] phase 4 duplicate video maintenance: %v", err)
+	}
+}
+
 // readLastRunDate reads the persisted last_run_date or returns "" when unset.
 func (r *Runner) readLastRunDate(ctx context.Context) (string, error) {
 	if r.cfg.Settings == nil {

backend/internal/nightly/runner_test.go

@@ -99,11 +99,11 @@ func TestRunPipelineHonoursPhaseOrder(t *testing.T) {
 		RunScan: func(_ context.Context, id string) {
 			rec.push("scan:" + id)
 		},
-		ListSpider91Drives: func(context.Context) []string {
-			rec.push("list-spider")
+		ListCrawlerDrives: func(context.Context) []string {
+			rec.push("list-crawler")
 			return []string{"sp-1"}
 		},
-		RunSpider91Crawl: func(_ context.Context, id string) {
+		RunCrawlerCrawl: func(_ context.Context, id string) {
 			rec.push("crawl:" + id)
 		},
 		WaitPreviewQueuesIdle: func(context.Context) error {
@@ -114,6 +114,10 @@ func TestRunPipelineHonoursPhaseOrder(t *testing.T) {
 			rec.push("migrate")
 			return nil
 		},
+		RunDedupeAssetCleanup: func(context.Context) error {
+			rec.push("dedupe-cleanup")
+			return nil
+		},
 	})
 
 	r.runPipeline(context.Background())
@@ -124,10 +128,11 @@ func TestRunPipelineHonoursPhaseOrder(t *testing.T) {
 		"scan:drive-a",
 		"scan:drive-b",
 		"wait-idle", // after phase 1
-		"list-spider",
+		"list-crawler",
 		"crawl:sp-1",
 		"wait-idle", // after phase 2
 		"migrate",
+		"dedupe-cleanup",
 	}
 	if len(got) != len(want) {
 		t.Fatalf("call sequence len = %d, want %d; got=%v", len(got), len(want), got)
@@ -139,15 +144,15 @@ func TestRunPipelineHonoursPhaseOrder(t *testing.T) {
 	}
 }
 
-func TestRunPipelineSkipsMigrationWhenNoSpider91(t *testing.T) {
+func TestRunPipelineSkipsMigrationWhenNoCrawler(t *testing.T) {
 	rec := &recorder{}
 
 	r := New(Config{
-		Settings:           newStubSettings(),
-		ListScanTargets:    func(context.Context) []string { return []string{"drive-a"} },
-		RunScan:            func(_ context.Context, id string) { rec.push("scan:" + id) },
-		ListSpider91Drives: func(context.Context) []string { return nil },
-		RunSpider91Crawl:   func(_ context.Context, id string) { rec.push("crawl:" + id) },
+		Settings:          newStubSettings(),
+		ListScanTargets:   func(context.Context) []string { return []string{"drive-a"} },
+		RunScan:           func(_ context.Context, id string) { rec.push("scan:" + id) },
+		ListCrawlerDrives: func(context.Context) []string { return nil },
+		RunCrawlerCrawl:   func(_ context.Context, id string) { rec.push("crawl:" + id) },
 		WaitPreviewQueuesIdle: func(context.Context) error {
 			rec.push("wait-idle")
 			return nil
@@ -156,15 +161,28 @@ func TestRunPipelineSkipsMigrationWhenNoSpider91(t *testing.T) {
 			rec.push("migrate")
 			return nil
 		},
+		RunDedupeAssetCleanup: func(context.Context) error {
+			rec.push("dedupe-cleanup")
+			return nil
+		},
 	})
 
 	r.runPipeline(context.Background())
 
 	for _, c := range rec.snapshot() {
 		if c == "migrate" || c == "crawl:sp-1" {
-			t.Fatalf("phase 2/3 should be skipped when no spider91 drive, got call %q", c)
+			t.Fatalf("phase 2/3 should be skipped when no crawler, got call %q", c)
 		}
 	}
+	foundCleanup := false
+	for _, c := range rec.snapshot() {
+		if c == "dedupe-cleanup" {
+			foundCleanup = true
+		}
+	}
+	if !foundCleanup {
+		t.Fatalf("dedupe cleanup should still run when crawler is absent; calls=%v", rec.snapshot())
+	}
 }
 
 func TestRunPipelineExitsWhenContextCancelledMidPhase(t *testing.T) {
@@ -182,10 +200,11 @@ func TestRunPipelineExitsWhenContextCancelledMidPhase(t *testing.T) {
 				cancel()
 			}
 		},
-		ListSpider91Drives:    func(context.Context) []string { return []string{"x"} },
-		RunSpider91Crawl:      func(context.Context, string) { rec.push("crawl") },
+		ListCrawlerDrives:     func(context.Context) []string { return []string{"x"} },
+		RunCrawlerCrawl:       func(context.Context, string) { rec.push("crawl") },
 		WaitPreviewQueuesIdle: func(context.Context) error { rec.push("wait-idle"); return nil },
 		RunMigration:          func(context.Context) error { rec.push("migrate"); return nil },
+		RunDedupeAssetCleanup: func(context.Context) error { rec.push("dedupe-cleanup"); return nil },
 	})
 
 	r.runPipeline(ctx)
@@ -200,6 +219,9 @@ func TestRunPipelineExitsWhenContextCancelledMidPhase(t *testing.T) {
 		if c == "crawl" || c == "migrate" {
 			t.Fatalf("subsequent phase should not run after cancel, got call %q", c)
 		}
+		if c == "dedupe-cleanup" {
+			t.Fatalf("dedupe cleanup should not run after cancel, got call %q", c)
+		}
 	}
 }
 
@@ -267,12 +289,12 @@ func TestCtxCancelPreventsLaterPhases(t *testing.T) {
 		WaitPreviewQueuesIdle: func(ctx context.Context) error {
 			return ctx.Err()
 		},
-		ListSpider91Drives: func(context.Context) []string {
-			rec.push("list-spider")
+		ListCrawlerDrives: func(context.Context) []string {
+			rec.push("list-crawler")
 			return []string{"x"}
 		},
-		RunSpider91Crawl: func(context.Context, string) { rec.push("crawl") },
-		RunMigration:     func(context.Context) error { rec.push("migrate"); return nil },
+		RunCrawlerCrawl: func(context.Context, string) { rec.push("crawl") },
+		RunMigration:    func(context.Context) error { rec.push("migrate"); return nil },
 	})
 
 	ctx, cancel := context.WithCancel(context.Background())
@@ -281,7 +303,7 @@ func TestCtxCancelPreventsLaterPhases(t *testing.T) {
 	r.runPipeline(ctx)
 
 	for _, c := range rec.snapshot() {
-		if c == "crawl" || c == "migrate" || c == "list-spider" {
+		if c == "crawl" || c == "migrate" || c == "list-crawler" {
 			t.Fatalf("later phase should not run after ctx done; got %q", c)
 		}
 	}
@@ -290,11 +312,14 @@ func TestCtxCancelPreventsLaterPhases(t *testing.T) {
 func TestTriggerNowIsNonBlocking(t *testing.T) {
 	r := New(Config{Settings: newStubSettings()})
 	// fill the trigger channel
-	r.TriggerNow()
+	if !r.TriggerNow() {
+		t.Fatal("first TriggerNow should be accepted")
+	}
 	// Second call must not block
 	done := make(chan struct{})
+	var accepted bool
 	go func() {
-		r.TriggerNow()
+		accepted = r.TriggerNow()
 		close(done)
 	}()
 	select {
@@ -302,4 +327,153 @@ func TestTriggerNowIsNonBlocking(t *testing.T) {
 	case <-time.After(100 * time.Millisecond):
 		t.Fatal("TriggerNow blocked when channel is full")
 	}
+	if accepted {
+		t.Fatal("second TriggerNow should be ignored when trigger channel is full")
+	}
+}
+
+func TestStatusTracksQueuedRunningAndFinished(t *testing.T) {
+	blockScan := make(chan struct{})
+	scanStarted := make(chan struct{})
+	var startedOnce sync.Once
+	r := New(Config{
+		Settings: newStubSettings(),
+		ListScanTargets: func(context.Context) []string {
+			return []string{"drive"}
+		},
+		RunScan: func(context.Context, string) {
+			startedOnce.Do(func() { close(scanStarted) })
+			<-blockScan
+		},
+	})
+
+	if got := r.Status(); got.State != "idle" || got.Running || got.Queued {
+		t.Fatalf("initial status = %#v, want idle", got)
+	}
+
+	if !r.TriggerNow() {
+		t.Fatal("TriggerNow should queue a manual run")
+	}
+	if got := r.Status(); got.State != "queued" || got.Running || !got.Queued {
+		t.Fatalf("queued status = %#v, want queued", got)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go r.Run(ctx)
+
+	select {
+	case <-scanStarted:
+	case <-time.After(time.Second):
+		t.Fatal("pipeline did not start")
+	}
+
+	if got := r.Status(); got.State != "running" || !got.Running || got.Queued || got.StartedAt.IsZero() {
+		t.Fatalf("running status = %#v, want running with startedAt", got)
+	}
+
+	if r.TriggerNow() {
+		t.Fatal("TriggerNow during a run should be ignored")
+	}
+	if got := r.Status(); got.State != "running" || !got.Running || got.Queued {
+		t.Fatalf("status after ignored trigger = %#v, want running", got)
+	}
+
+	close(blockScan)
+	deadline := time.After(time.Second)
+	for {
+		got := r.Status()
+		if !got.Running && !got.Queued && !got.LastFinishedAt.IsZero() {
+			return
+		}
+		select {
+		case <-deadline:
+			t.Fatalf("status did not finish; got=%#v", got)
+		default:
+			time.Sleep(10 * time.Millisecond)
+		}
+	}
+}
+
+func TestStopCurrentCancelsRunningPipeline(t *testing.T) {
+	scanStarted := make(chan struct{})
+	scanCanceled := make(chan struct{})
+	var startedOnce sync.Once
+	r := New(Config{
+		Settings: newStubSettings(),
+		ListScanTargets: func(context.Context) []string {
+			return []string{"drive"}
+		},
+		RunScan: func(ctx context.Context, _ string) {
+			startedOnce.Do(func() { close(scanStarted) })
+			<-ctx.Done()
+			close(scanCanceled)
+		},
+	})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go r.Run(ctx)
+
+	if !r.TriggerNow() {
+		t.Fatal("TriggerNow should queue a manual run")
+	}
+	select {
+	case <-scanStarted:
+	case <-time.After(time.Second):
+		t.Fatal("pipeline did not start")
+	}
+
+	if !r.StopCurrent() {
+		t.Fatal("StopCurrent should report a running pipeline")
+	}
+	select {
+	case <-scanCanceled:
+	case <-time.After(time.Second):
+		t.Fatal("StopCurrent did not cancel pipeline context")
+	}
+}
+
+func TestStopCurrentDropsQueuedTrigger(t *testing.T) {
+	r := New(Config{Settings: newStubSettings()})
+	if !r.TriggerNow() {
+		t.Fatal("TriggerNow should queue a manual run")
+	}
+	if !r.StopCurrent() {
+		t.Fatal("StopCurrent should report a queued pipeline")
+	}
+	if got := r.Status(); got.State != "idle" || got.Running || got.Queued {
+		t.Fatalf("status = %#v, want idle after dropping queued trigger", got)
+	}
+	if !r.TriggerNow() {
+		t.Fatal("TriggerNow should accept a new request after queued stop")
+	}
+}
+
+func TestTriggerNowAcceptsOnlyOneConcurrentRequest(t *testing.T) {
+	r := New(Config{Settings: newStubSettings()})
+
+	const callers = 16
+	start := make(chan struct{})
+	results := make(chan bool, callers)
+	for i := 0; i < callers; i++ {
+		go func() {
+			<-start
+			results <- r.TriggerNow()
+		}()
+	}
+	close(start)
+
+	accepted := 0
+	for i := 0; i < callers; i++ {
+		if <-results {
+			accepted++
+		}
+	}
+	if accepted != 1 {
+		t.Fatalf("accepted triggers = %d, want 1", accepted)
+	}
+	if got := r.Status(); got.State != "queued" || got.Running || !got.Queued {
+		t.Fatalf("status = %#v, want one queued trigger", got)
+	}
 }

backend/internal/preview/ffmpeg.go

@@ -1,6 +1,7 @@
 package preview
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
@@ -20,15 +21,16 @@ import (
 
 	"github.com/video-site/backend/internal/catalog"
 	"github.com/video-site/backend/internal/drives"
+	"github.com/video-site/backend/internal/mediaasset"
 )
 
 type Config struct {
 	FFmpegPath      string
 	FFprobePath     string
-	DurationSeconds int // 兼容旧配置；当前 teaser 每段固定 3 秒
+	DurationSeconds int // 兼容旧配置；当前预览视频每段固定 3 秒
 	Width           int
 	Segments        int    // 兼容旧配置；当前 30 秒及以上视频固定使用 4 段
-	LocalDir        string // 本地 teaser 和封面目录
+	LocalDir        string // 本地预览视频和封面目录
 }
 
 type Generator struct {
@@ -235,23 +237,43 @@ func appendUniqueStart(starts []float64, start, eachSec float64) []float64 {
 	return append(starts, start)
 }
 
-// thumbnailOffsets 选封面抽帧的时间点（秒）。独立于 teaser。
-func thumbnailOffsets() []float64 {
-	return []float64{5, 1, 0}
+// thumbnailOffsets 选封面抽帧的时间点（秒）。独立于预览视频。
+// 默认取视频中间帧；时长未知时退回早期帧。
+func thumbnailOffsets(duration float64) []float64 {
+	if duration <= 0 {
+		return []float64{5, 1, 0}
+	}
+	mid := duration / 2
+	out := []float64{mid}
+	for _, fallback := range []float64{5, 1, 0} {
+		if !containsOffset(out, fallback) {
+			out = append(out, fallback)
+		}
+	}
+	return out
+}
+
+func containsOffset(offsets []float64, target float64) bool {
+	for _, offset := range offsets {
+		if math.Abs(offset-target) < 0.01 {
+			return true
+		}
+	}
+	return false
 }
 
 // --- 封面 ---
 
-// GenerateThumbnail 抽一张 jpg 封面。默认从第 5 秒抽帧，失败时回退到更早时间点。
+// GenerateThumbnail 抽一张 jpg 封面。默认从视频中间抽帧，失败时回退到更早时间点。
 func (g *Generator) GenerateThumbnail(ctx context.Context, link *drives.StreamLink, videoID string, duration float64) (string, error) {
 	dir := filepath.Join(g.cfg.LocalDir, "thumbs")
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return "", err
 	}
-	dst := filepath.Join(dir, videoID+".jpg")
+	dst := mediaasset.ThumbnailPath(g.cfg.LocalDir, videoID)
 
 	var lastErr error
-	offsets := thumbnailOffsets()
+	offsets := thumbnailOffsets(duration)
 	for i, offset := range offsets {
 		if i > 0 {
 			_ = os.Remove(dst)
@@ -289,7 +311,7 @@ func (g *Generator) generateThumbnailAtOffset(ctx context.Context, link *drives.
 	args = append(args,
 		"-i", ffmpegLink.URL,
 		"-frames:v", "1",
-		"-vf", fmt.Sprintf("scale=%d:-2", g.cfg.Width),
+		"-vf", thumbnailVideoFilter(g.cfg.Width),
 		"-q:v", "3",
 		"-y", dst,
 	)
@@ -307,6 +329,12 @@ func (g *Generator) generateThumbnailAtOffset(ctx context.Context, link *drives.
 	return nil
 }
 
+func thumbnailVideoFilter(width int) string {
+	// FFmpeg 7 rejects non-full-range YUV for MJPEG/JPEG output. Force the
+	// scaled frame into a JPEG-friendly full-range pixel format before encode.
+	return fmt.Sprintf("scale=%d:-2:out_range=pc,format=yuvj420p", width)
+}
+
 func thumbnailOffsetFallbackAllowed(err error) bool {
 	if err == nil {
 		return false
@@ -339,9 +367,15 @@ func (g *Generator) Probe(ctx context.Context, link *drives.StreamLink) (float64
 	args = append(args, ffmpegLink.URL)
 
 	cmd := exec.CommandContext(ctx2, g.cfg.FFprobePath, args...)
-	out, err := cmd.CombinedOutput()
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
 	if err != nil {
-		return 0, ffmpegCommandError("ffprobe", err, out)
+		errOut := stderr.Bytes()
+		if len(errOut) == 0 {
+			errOut = out
+		}
+		return 0, ffmpegCommandError("ffprobe", err, errOut)
 	}
 	raw := strings.TrimSpace(string(out))
 	if raw == "" || raw == "N/A" {
@@ -350,9 +384,9 @@ func (g *Generator) Probe(ctx context.Context, link *drives.StreamLink) (float64
 	return strconv.ParseFloat(raw, 64)
 }
 
-// --- Teaser ---
+// --- 预览视频 ---
 
-// Generate 拉取 teaser 到本地临时文件，返回路径。
+// Generate 拉取预览视频到本地临时文件，返回路径。
 // 根据 Config.Segments 和视频时长决定是单段还是多段拼接。
 func (g *Generator) Generate(ctx context.Context, link *drives.StreamLink, duration float64) (string, error) {
 	return g.generate(ctx, duration, func(int) (*drives.StreamLink, error) {
@@ -918,21 +952,17 @@ func redactURLs(text string) string {
 }
 
 func ffmpegOutputLooksRateLimited(output []byte) bool {
-	text := strings.ToLower(string(output))
-	if !strings.Contains(text, "429") {
-		return false
-	}
-	return strings.Contains(text, "too many requests") ||
-		strings.Contains(text, "rate limit") ||
-		strings.Contains(text, "rate-limit") ||
-		strings.Contains(text, "server returned 429")
+	return drives.TextMentionsHTTPStatus(string(output), http.StatusTooManyRequests)
 }
 
 // --- 本地落盘 ---
 
 // MoveToLocal 把临时文件改名到稳定位置，返回最终路径
 func (g *Generator) MoveToLocal(tmpPath, videoID string) (string, error) {
-	dst := filepath.Join(g.cfg.LocalDir, videoID+".mp4")
+	if err := os.MkdirAll(g.cfg.LocalDir, 0o755); err != nil {
+		return "", err
+	}
+	dst := mediaasset.PreviewPath(g.cfg.LocalDir, videoID)
 	if err := os.Rename(tmpPath, dst); err != nil {
 		// 跨盘 rename 可能失败，fallback 到 copy
 		if cerr := copyFile(tmpPath, dst); cerr != nil {
@@ -968,7 +998,6 @@ type Worker struct {
 	queue   videoQueue
 
 	RateLimitCooldown time.Duration
-	BeforeTask        func(context.Context) bool
 	rateLimit         rateLimitState
 	activity          taskActivity
 }
@@ -978,7 +1007,7 @@ func NewWorker(gen TeaserGenerator, cat *catalog.Catalog, drv drives.Drive) *Wor
 		Gen:     gen,
 		Catalog: cat,
 		Drive:   drv,
-		ch:      make(chan *catalog.Video, 4096),
+		ch:      make(chan *catalog.Video, defaultWorkerQueueSize),
 	}
 }
 
@@ -1027,10 +1056,10 @@ type ThumbWorker struct {
 }
 
 const (
-	defaultTransientMediaCooldown            = 5 * time.Minute
-	defaultGenerationRateLimitCooldown       = 5 * time.Minute
-	maxPreviewTeaserSizeBytes          int64 = 5 * 1024 * 1024 * 1024
-	previewStatusSkipped                     = "skipped"
+	defaultTransientMediaCooldown         = 5 * time.Minute
+	defaultGenerationRateLimitCooldown    = 5 * time.Minute
+	defaultThumbTransientMediaMaxFailures = 3
+	defaultWorkerQueueSize                = 10000
 )
 
 type rateLimitState struct {
@@ -1085,6 +1114,19 @@ func (q *videoQueue) release(v *catalog.Video) {
 	q.mu.Unlock()
 }
 
+func (q *videoQueue) idsSnapshot() []string {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	if len(q.ids) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(q.ids))
+	for id := range q.ids {
+		out = append(out, id)
+	}
+	return out
+}
+
 func (q *videoQueue) lengthExcluding(currentID string) int {
 	q.mu.Lock()
 	defer q.mu.Unlock()
@@ -1168,7 +1210,7 @@ func NewThumbWorker(gen ThumbnailGenerator, cat *catalog.Catalog, drv drives.Dri
 		Gen:     gen,
 		Catalog: cat,
 		Drive:   drv,
-		ch:      make(chan *catalog.Video, 4096),
+		ch:      make(chan *catalog.Video, defaultWorkerQueueSize),
 	}
 }
 
@@ -1212,6 +1254,13 @@ func (w *Worker) Status() TaskStatus {
 	return taskStatus(&w.activity, &w.rateLimit, w.queue.lengthExcluding(currentID))
 }
 
+func (w *Worker) ActiveVideoIDs() []string {
+	if w == nil {
+		return nil
+	}
+	return w.queue.idsSnapshot()
+}
+
 func (w *ThumbWorker) Status() TaskStatus {
 	if w == nil {
 		return TaskStatus{State: "idle"}
@@ -1323,26 +1372,32 @@ func (w *ThumbWorker) Run(ctx context.Context) {
 
 func (w *Worker) processQueued(ctx context.Context, v *catalog.Video) {
 	defer w.queue.release(v)
-	if w.BeforeTask != nil && !w.BeforeTask(ctx) {
+	if w.Catalog == nil || v == nil || v.ID == "" {
 		return
 	}
-
-	w.activity.start(v)
+	current, err := w.Catalog.GetVideo(ctx, v.ID)
+	if err != nil || current.Hidden {
+		return
+	}
+	w.activity.start(current)
 	defer w.activity.done()
 	if !waitForRateLimitCooldown(ctx, &w.rateLimit, "preview", w.Drive) {
 		return
 	}
-	w.process(ctx, v)
+	w.process(ctx, current)
 }
 
 func (w *ThumbWorker) processQueued(ctx context.Context, v *catalog.Video) {
-	defer w.queue.release(v)
 	w.activity.start(v)
-	defer w.activity.done()
-	if !waitForRateLimitCooldown(ctx, &w.rateLimit, "thumb", w.Drive) {
-		return
+	retry := false
+	if waitForRateLimitCooldown(ctx, &w.rateLimit, "thumb", w.Drive) {
+		retry = w.process(ctx, v)
+	}
+	w.activity.done()
+	w.queue.release(v)
+	if retry && ctx.Err() == nil {
+		w.EnqueueBlocking(ctx, v)
 	}
-	w.process(ctx, v)
 }
 
 func waitForRateLimitCooldown(ctx context.Context, state *rateLimitState, label string, drive drives.Drive) bool {
@@ -1382,11 +1437,17 @@ func (w *Worker) skipIfRateLimited(v *catalog.Video) bool {
 }
 
 func (w *Worker) pauseForRateLimit(err error, step, title string) bool {
-	_, ok := drives.RateLimitRetryAfter(err)
+	wait, ok := drives.RateLimitRetryAfter(err)
 	if !ok {
 		return false
 	}
-	until := w.rateLimit.pause(time.Now(), defaultGenerationRateLimitCooldown)
+	if wait <= 0 {
+		wait = w.RateLimitCooldown
+		if wait <= 0 {
+			wait = defaultGenerationRateLimitCooldown
+		}
+	}
+	until := w.rateLimit.pause(time.Now(), wait)
 	log.Printf("[preview] drive=%s rate-limited until=%s step=%s video=%s: %v", w.Drive.ID(), until.Format(time.RFC3339), step, title, err)
 	return true
 }
@@ -1415,24 +1476,49 @@ func (w *ThumbWorker) skipIfRateLimited(v *catalog.Video) bool {
 }
 
 func (w *ThumbWorker) pauseForRateLimit(err error, step, title string) bool {
-	_, ok := drives.RateLimitRetryAfter(err)
+	wait, ok := drives.RateLimitRetryAfter(err)
 	if !ok {
 		return false
 	}
-	until := w.rateLimit.pause(time.Now(), defaultGenerationRateLimitCooldown)
+	if wait <= 0 {
+		wait = w.RateLimitCooldown
+		if wait <= 0 {
+			wait = defaultGenerationRateLimitCooldown
+		}
+	}
+	until := w.rateLimit.pause(time.Now(), wait)
 	log.Printf("[thumb] drive=%s rate-limited until=%s step=%s video=%s: %v", w.Drive.ID(), until.Format(time.RFC3339), step, title, err)
 	return true
 }
 
-func (w *ThumbWorker) pauseForRecoverableError(err error, step, title string) bool {
+func (w *ThumbWorker) pauseForRecoverableError(ctx context.Context, v *catalog.Video, err error, step string) bool {
+	title := ""
+	videoID := ""
+	if v != nil {
+		title = v.Title
+		videoID = v.ID
+	}
 	if w.pauseForRateLimit(err, step, title) {
 		return true
 	}
 	if !driveErrorShouldCooldown(w.Drive, err) {
 		return false
 	}
+	failures := 1
+	if w.Catalog != nil && videoID != "" {
+		count, countErr := w.Catalog.IncrementThumbnailFailures(ctx, videoID)
+		if countErr != nil {
+			log.Printf("[thumb] drive=%s transient media source error count failed step=%s video=%s: %v", w.Drive.ID(), step, title, countErr)
+		} else {
+			failures = count
+		}
+	}
+	if failures >= defaultThumbTransientMediaMaxFailures {
+		log.Printf("[thumb] drive=%s transient media source error reached retry limit failures=%d/%d step=%s video=%s: %v", w.Drive.ID(), failures, defaultThumbTransientMediaMaxFailures, step, title, err)
+		return false
+	}
 	until := w.rateLimit.pause(time.Now(), w.RateLimitCooldown)
-	log.Printf("[thumb] drive=%s transient media source error until=%s step=%s video=%s: %v", w.Drive.ID(), until.Format(time.RFC3339), step, title, err)
+	log.Printf("[thumb] drive=%s transient media source error until=%s failures=%d/%d step=%s video=%s: %v", w.Drive.ID(), until.Format(time.RFC3339), failures, defaultThumbTransientMediaMaxFailures, step, title, err)
 	return true
 }
 
@@ -1442,90 +1528,144 @@ func driveErrorShouldCooldown(d drives.Drive, err error) bool {
 	}
 	switch d.Kind() {
 	case "p115":
-		text := strings.ToLower(err.Error())
-		return strings.Contains(text, "server returned 403") ||
-			strings.Contains(text, "403 forbidden") ||
-			strings.Contains(text, "server returned 405") ||
-			strings.Contains(text, "405 method") ||
-			strings.Contains(text, "access denied") ||
-			strings.Contains(text, "moov atom not found") ||
-			strings.Contains(text, "partial file") ||
-			strings.Contains(text, "request has been blocked") ||
-			strings.Contains(text, "访问被阻断")
+		return drives.ErrorMentionsHTTPStatus(err, http.StatusForbidden, http.StatusMethodNotAllowed, http.StatusTooManyRequests)
 	case "pikpak":
-		// PikPak 在 teaser / 封面生成阶段（取链或拉直链字节）可能命中：
-		//   - error_code=10  操作频繁
-		//   - HTTP 429 / 5xx / 509 限流和服务端不可用
-		//   - 通用文本：rate limit / too many requests / blocked
-		// 命中时让 worker 冷却 5 分钟，避免连续请求加重风控。
-		text := strings.ToLower(err.Error())
-		return strings.Contains(text, "error_code=10") ||
-			strings.Contains(text, "操作频繁") ||
-			strings.Contains(text, "429") ||
-			strings.Contains(text, "http 500") ||
-			strings.Contains(text, "http 502") ||
-			strings.Contains(text, "http 503") ||
-			strings.Contains(text, "http 504") ||
-			strings.Contains(text, "http 509") ||
-			strings.Contains(text, "too many request") ||
-			strings.Contains(text, "too many requests") ||
-			strings.Contains(text, "rate limit") ||
-			strings.Contains(text, "blocked") ||
-			strings.Contains(text, "moov atom not found") ||
-			strings.Contains(text, "partial file") ||
-			strings.Contains(text, "service unavailable")
+		return drives.ErrorMentionsHTTPStatus(err, http.StatusTooManyRequests, http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout, 509)
+	case "p123":
+		return drives.ErrorMentionsHTTPStatus(err, http.StatusForbidden, http.StatusTooManyRequests, http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout)
+	case "wopan":
+		return drives.ErrorMentionsHTTPStatus(err, http.StatusForbidden, http.StatusTooManyRequests, http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout, 509)
+	case "guangyapan":
+		return drives.ErrorMentionsHTTPStatus(err, http.StatusForbidden, http.StatusTooManyRequests, http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout, 509)
+	case "googledrive":
+		return drives.ErrorMentionsHTTPStatus(err, http.StatusForbidden, http.StatusTooManyRequests, http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout)
 	}
 	return false
 }
 
-func (w *ThumbWorker) process(ctx context.Context, v *catalog.Video) {
+func (w *ThumbWorker) process(ctx context.Context, v *catalog.Video) bool {
 	if w.skipIfRateLimited(v) {
-		return
+		return false
 	}
-	if current, err := w.Catalog.GetVideo(ctx, v.ID); err == nil {
-		if current.ThumbnailURL != "" {
-			_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{ThumbnailStatus: "ready"})
-			return
+	if w.Catalog == nil || v == nil || v.ID == "" {
+		return false
+	}
+	queued := v
+	loaded, err := w.Catalog.GetVideo(ctx, v.ID)
+	if err != nil || loaded.Hidden {
+		return false
+	}
+	if loaded.PreviewLocal == "" {
+		loaded.PreviewLocal = queued.PreviewLocal
+	}
+	current := loaded
+	v = loaded
+	if loaded.ThumbnailURL != "" && loaded.DurationSeconds > 0 {
+		_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{ThumbnailStatus: "ready"})
+		return false
+	}
+	if current.ThumbnailURL != "" {
+		durationBackfillFailed := false
+		if current.DurationSeconds <= 0 {
+			link, err := w.streamLink(ctx, current)
+			if err != nil {
+				if w.pauseForRecoverableError(ctx, current, err, "streamURL") {
+					return true
+				}
+				log.Printf("[thumb] probe streamURL %s: %v", current.Title, err)
+				durationBackfillFailed = true
+			} else if w.probeDuration(ctx, current, link) {
+				return true
+			} else if current.DurationSeconds <= 0 {
+				durationBackfillFailed = true
+			}
 		}
+		if durationBackfillFailed {
+			log.Printf("[thumb] skip duration backfill %s: thumbnail already exists but duration could not be probed", current.Title)
+			_ = w.Catalog.UpdateVideoMeta(ctx, current.ID, catalog.VideoMetaPatch{ThumbnailStatus: "skipped"})
+			return false
+		}
+		_ = w.Catalog.UpdateVideoMeta(ctx, current.ID, catalog.VideoMetaPatch{ThumbnailStatus: "ready"})
+		return false
 	}
 	_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{ThumbnailStatus: "pending"})
-	link, err := w.Drive.StreamURL(ctx, v.FileID)
+	link, err := w.streamLink(ctx, v)
 	if err != nil {
-		if localLink, ok := localPreviewLink(v); ok {
-			link = localLink
-		} else {
-			if w.pauseForRecoverableError(err, "streamURL", v.Title) {
-				return
-			}
-			log.Printf("[thumb] streamURL %s: %v", v.Title, err)
-			_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{ThumbnailStatus: "failed"})
-			return
+		if w.pauseForRecoverableError(ctx, v, err, "streamURL") {
+			return true
 		}
+		log.Printf("[thumb] streamURL %s: %v", v.Title, err)
+		_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{ThumbnailStatus: "failed"})
+		return false
+	}
+	if w.probeDuration(ctx, v, link) {
+		return true
 	}
 
 	if err := w.generateThumbnailFromLink(ctx, v, link); err != nil {
 		if localLink, ok := localPreviewLink(v); ok && link.URL != localLink.URL {
+			if w.probeDuration(ctx, v, localLink) {
+				return true
+			}
 			if localErr := w.generateThumbnailFromLink(ctx, v, localLink); localErr == nil {
-				return
+				return false
 			}
 		}
-		if w.pauseForRecoverableError(err, "generate", v.Title) {
-			return
+		if w.pauseForRecoverableError(ctx, v, err, "generate") {
+			return true
 		}
 		log.Printf("[thumb] generate %s: %v", v.Title, err)
 		_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{ThumbnailStatus: "failed"})
-		return
+		return false
 	}
+	return false
+}
+
+func (w *ThumbWorker) streamLink(ctx context.Context, v *catalog.Video) (*drives.StreamLink, error) {
+	link, err := w.Drive.StreamURL(ctx, v.FileID)
+	if err == nil {
+		return link, nil
+	}
+	if localLink, ok := localPreviewLink(v); ok {
+		return localLink, nil
+	}
+	return nil, err
+}
+
+func (w *ThumbWorker) probeDuration(ctx context.Context, v *catalog.Video, link *drives.StreamLink) bool {
+	if v.DurationSeconds > 0 {
+		return false
+	}
+	dur, err := w.Gen.Probe(ctx, link)
+	if err == nil {
+		if dur > 0 {
+			v.DurationSeconds = int(dur)
+			_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{
+				DurationSeconds: int(dur),
+			})
+		}
+		return false
+	}
+	if w.pauseForRecoverableError(ctx, v, err, "probe") {
+		return true
+	}
+	log.Printf("[thumb] probe %s: %v", v.Title, err)
+	return false
 }
 
 func (w *ThumbWorker) generateThumbnailFromLink(ctx context.Context, v *catalog.Video, link *drives.StreamLink) error {
-	if _, err := w.Gen.GenerateThumbnail(ctx, link, v.ID, 0); err != nil {
+	local, err := w.Gen.GenerateThumbnail(ctx, link, v.ID, float64(v.DurationSeconds))
+	if err != nil {
 		return err
 	}
-	_ = w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{
+	if err := w.Catalog.UpdateVideoMeta(ctx, v.ID, catalog.VideoMetaPatch{
 		ThumbnailURL:    "/p/thumb/" + v.ID,
 		ThumbnailStatus: "ready",
-	})
+	}); err != nil {
+		_ = os.Remove(local)
+		log.Printf("[thumb] update %s after generate: %v", v.Title, err)
+		return nil
+	}
 	log.Printf("[thumb] ready %s", v.Title)
 	return nil
 }
@@ -1543,15 +1683,6 @@ func localPreviewLink(v *catalog.Video) (*drives.StreamLink, bool) {
 }
 
 func (w *Worker) process(ctx context.Context, v *catalog.Video) {
-	if shouldSkipTeaser(v) {
-		removePreviousLocalTeaser(v.PreviewLocal, "")
-		if err := w.Catalog.UpdatePreview(ctx, v.ID, "", previewStatusSkipped); err != nil {
-			log.Printf("[preview] skip %s: update status: %v", v.Title, err)
-			return
-		}
-		log.Printf("[preview] skip %s: size=%d exceeds 5GiB teaser limit", v.Title, v.Size)
-		return
-	}
 	if w.skipIfRateLimited(v) {
 		return
 	}
@@ -1578,7 +1709,7 @@ func (w *Worker) process(ctx context.Context, v *catalog.Video) {
 		}
 	}
 
-	// 2) teaser
+	// 2) 预览视频
 	tmp, err := w.generateTeaser(ctx, v, link, duration)
 	if err != nil {
 		if w.pauseForRecoverableError(err, "generate", v.Title) {
@@ -1596,14 +1727,14 @@ func (w *Worker) process(ctx context.Context, v *catalog.Video) {
 	}
 
 	removePreviousLocalTeaser(v.PreviewLocal, local)
-	w.Catalog.UpdatePreview(ctx, v.ID, local, "ready")
+	if err := w.Catalog.UpdatePreview(ctx, v.ID, local, "ready"); err != nil {
+		removePreviousLocalTeaser(local, "")
+		log.Printf("[preview] update %s after generate: %v", v.Title, err)
+		return
+	}
 	log.Printf("[preview] ready %s (duration=%.1fs)", v.Title, duration)
 }
 
-func shouldSkipTeaser(v *catalog.Video) bool {
-	return v != nil && v.Size > maxPreviewTeaserSizeBytes
-}
-
 func (w *Worker) generateTeaser(ctx context.Context, v *catalog.Video, link *drives.StreamLink, duration float64) (string, error) {
 	gen, ok := w.Gen.(refreshingTeaserGenerator)
 	if !ok || w.Drive == nil || w.Drive.Kind() != "p115" {

backend/internal/preview/ffmpeg_test.go

@@ -5,6 +5,8 @@ import (
 	"errors"
 	"math"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -95,6 +97,24 @@ func TestTinyVideoPreviewPlanUsesWholeVideoAsSingleSegment(t *testing.T) {
 	}
 }
 
+func TestProbeIgnoresStderrWarnings(t *testing.T) {
+	dir := t.TempDir()
+	ffprobePath := filepath.Join(dir, "ffprobe")
+	script := "#!/bin/sh\nprintf '%s\\n' 'h264 warning' >&2\nprintf '%s\\n' '364.800000'\n"
+	if err := os.WriteFile(ffprobePath, []byte(script), 0o755); err != nil {
+		t.Fatalf("write ffprobe stub: %v", err)
+	}
+
+	gen := New(Config{FFprobePath: ffprobePath})
+	got, err := gen.Probe(context.Background(), &drives.StreamLink{URL: filepath.Join(dir, "video.mp4")})
+	if err != nil {
+		t.Fatalf("probe: %v", err)
+	}
+	if got != 364.8 {
+		t.Fatalf("duration = %v, want 364.8", got)
+	}
+}
+
 func TestTeaserCandidateStartsKeepPrimaryAndAddFallbacks(t *testing.T) {
 	primary := []float64{10.2, 64.65, 119.1, 173.55}
 	got := teaserCandidateStarts(204, primary, 3)
@@ -148,16 +168,39 @@ func TestMediumAndLongVideosStillRequirePlannedTeaserSegments(t *testing.T) {
 	}
 }
 
-func TestThumbnailOffsetsUseFiveSecondsWithEarlyFallbacks(t *testing.T) {
-	got := thumbnailOffsets()
-	want := []float64{5, 1, 0}
-	if len(got) != len(want) {
-		t.Fatalf("offsets = %#v, want %#v", got, want)
+func TestThumbnailOffsetsPreferMiddleFrame(t *testing.T) {
+	tests := []struct {
+		name     string
+		duration float64
+		want     []float64
+	}{
+		{name: "unknown duration", duration: 0, want: []float64{5, 1, 0}},
+		{name: "long video", duration: 2804.9, want: []float64{1402.45, 5, 1, 0}},
+		{name: "short video", duration: 8.9, want: []float64{4.45, 5, 1, 0}},
+		{name: "middle equals fallback", duration: 10, want: []float64{5, 1, 0}},
 	}
-	for i := range want {
-		if got[i] != want[i] {
-			t.Fatalf("offset[%d] = %.2f, want %.2f", i, got[i], want[i])
-		}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := thumbnailOffsets(tt.duration)
+			if len(got) != len(tt.want) {
+				t.Fatalf("offsets = %#v, want %#v", got, tt.want)
+			}
+			for i := range tt.want {
+				if math.Abs(got[i]-tt.want[i]) > 0.001 {
+					t.Fatalf("offset[%d] = %.2f, want %.2f", i, got[i], tt.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestThumbnailVideoFilterUsesFullRangeJPEGPixelFormat(t *testing.T) {
+	got := thumbnailVideoFilter(480)
+	if !strings.Contains(got, "scale=480:-2:out_range=pc") {
+		t.Fatalf("thumbnail filter = %q, want full-range scale output", got)
+	}
+	if !strings.Contains(got, "format=yuvj420p") {
+		t.Fatalf("thumbnail filter = %q, want JPEG-friendly pixel format", got)
 	}
 }
 

backend/internal/preview/worker_test.go

@@ -13,11 +13,11 @@ import (
 	"github.com/video-site/backend/internal/drives"
 )
 
-func TestThumbWorkerUpdatesThumbnailWithoutChangingPreviewStatus(t *testing.T) {
+func TestThumbWorkerUpdatesThumbnailAndDurationWithoutChangingPreviewStatus(t *testing.T) {
 	ctx := context.Background()
 	cat, video := seedPreviewTestVideo(t, "thumb-worker-video")
 
-	gen := &fakeThumbGenerator{}
+	gen := &fakeThumbGenerator{probeDuration: 42}
 	drv := &previewFakeDrive{}
 	worker := NewThumbWorker(gen, cat, drv)
 
@@ -33,23 +33,131 @@ func TestThumbWorkerUpdatesThumbnailWithoutChangingPreviewStatus(t *testing.T) {
 	if got.PreviewStatus != "pending" {
 		t.Fatalf("preview status = %q, want pending", got.PreviewStatus)
 	}
-	if got.DurationSeconds != 0 {
-		t.Fatalf("duration = %d, want unchanged", got.DurationSeconds)
+	if got.DurationSeconds != 42 {
+		t.Fatalf("duration = %d, want probed duration", got.DurationSeconds)
 	}
 	if gen.thumbnailVideoID != video.ID {
 		t.Fatalf("thumbnail video id = %q, want %q", gen.thumbnailVideoID, video.ID)
 	}
-	if gen.thumbnailDuration != 0 {
-		t.Fatalf("thumbnail duration = %.1f, want fixed-offset thumbnail generation", gen.thumbnailDuration)
+	if gen.thumbnailDuration != 42 {
+		t.Fatalf("thumbnail duration = %.1f, want probed duration", gen.thumbnailDuration)
 	}
-	if gen.probeCalls != 0 {
-		t.Fatalf("probe calls = %d, want 0 for thumbnail generation", gen.probeCalls)
+	if gen.probeCalls != 1 {
+		t.Fatalf("probe calls = %d, want 1 for thumbnail generation", gen.probeCalls)
 	}
 	if drv.streamFileID != video.FileID {
 		t.Fatalf("stream file id = %q, want %q", drv.streamFileID, video.FileID)
 	}
 }
 
+func TestThumbWorkerBackfillsDurationWhenThumbnailAlreadyExists(t *testing.T) {
+	ctx := context.Background()
+	cat, video := seedPreviewTestVideo(t, "thumb-worker-existing-thumbnail")
+	video.ThumbnailURL = "/p/thumb/" + video.ID
+	if err := cat.UpsertVideo(ctx, video); err != nil {
+		t.Fatalf("update video: %v", err)
+	}
+
+	gen := &fakeThumbGenerator{probeDuration: 19}
+	drv := &previewFakeDrive{}
+	worker := NewThumbWorker(gen, cat, drv)
+
+	worker.process(ctx, video)
+
+	got, err := cat.GetVideo(ctx, video.ID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.DurationSeconds != 19 {
+		t.Fatalf("duration = %d, want probed duration", got.DurationSeconds)
+	}
+	if got.ThumbnailURL != "/p/thumb/"+video.ID {
+		t.Fatalf("thumbnail = %q, want unchanged existing thumbnail", got.ThumbnailURL)
+	}
+	ready, err := cat.ListVideosByThumbnailStatus(ctx, video.DriveID, "ready", 0)
+	if err != nil {
+		t.Fatalf("list ready thumbnails: %v", err)
+	}
+	if len(ready) != 1 || ready[0].ID != video.ID {
+		t.Fatalf("ready thumbnails = %#v, want only %s", ready, video.ID)
+	}
+	if gen.probeCalls != 1 {
+		t.Fatalf("probe calls = %d, want 1", gen.probeCalls)
+	}
+	if gen.thumbnailVideoID != "" {
+		t.Fatalf("thumbnail generation video id = %q, want no regeneration", gen.thumbnailVideoID)
+	}
+}
+
+func TestThumbWorkerGeneratesThumbnailForCrawlerLikeVideoID(t *testing.T) {
+	ctx := context.Background()
+	cat, video := seedPreviewTestVideo(t, "scriptcrawler-crawler-main-source001")
+
+	gen := &fakeThumbGenerator{probeDuration: 42}
+	drv := &previewFakeDrive{kind: "pikpak"}
+	worker := NewThumbWorker(gen, cat, drv)
+
+	worker.process(ctx, video)
+
+	got, err := cat.GetVideo(ctx, video.ID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.ThumbnailURL != "/p/thumb/"+video.ID {
+		t.Fatalf("thumbnail = %q, want generated thumb URL", got.ThumbnailURL)
+	}
+	ready, err := cat.ListVideosByThumbnailStatus(ctx, video.DriveID, "ready", 0)
+	if err != nil {
+		t.Fatalf("list ready thumbnails: %v", err)
+	}
+	if len(ready) != 1 || ready[0].ID != video.ID {
+		t.Fatalf("ready thumbnails = %#v, want only %s", ready, video.ID)
+	}
+	if gen.probeCalls != 1 || gen.generateCalls != 1 {
+		t.Fatalf("generator calls probe=%d generate=%d, want one thumbnail generation", gen.probeCalls, gen.generateCalls)
+	}
+}
+
+func TestThumbWorkerSkipsDurationBackfillWhenExistingThumbnailCannotBeProbed(t *testing.T) {
+	ctx := context.Background()
+	cat, video := seedPreviewTestVideo(t, "thumb-worker-existing-thumbnail-probe-fails")
+	video.ThumbnailURL = "/p/thumb/" + video.ID
+	if err := cat.UpsertVideo(ctx, video); err != nil {
+		t.Fatalf("update video: %v", err)
+	}
+
+	gen := &fakeThumbGenerator{probeErr: errors.New("invalid media")}
+	drv := &previewFakeDrive{}
+	worker := NewThumbWorker(gen, cat, drv)
+
+	worker.process(ctx, video)
+
+	got, err := cat.GetVideo(ctx, video.ID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.ThumbnailURL != "/p/thumb/"+video.ID {
+		t.Fatalf("thumbnail = %q, want unchanged existing thumbnail", got.ThumbnailURL)
+	}
+	if got.DurationSeconds != 0 {
+		t.Fatalf("duration = %d, want still unknown", got.DurationSeconds)
+	}
+	skipped, err := cat.ListVideosByThumbnailStatus(ctx, video.DriveID, "skipped", 0)
+	if err != nil {
+		t.Fatalf("list skipped thumbnails: %v", err)
+	}
+	if len(skipped) != 1 || skipped[0].ID != video.ID {
+		t.Fatalf("skipped thumbnails = %#v, want only %s", skipped, video.ID)
+	}
+	missing, err := cat.CountVideosNeedingThumbnail(ctx, video.DriveID)
+	if err != nil {
+		t.Fatalf("count videos needing thumbnail: %v", err)
+	}
+	if missing != 0 {
+		t.Fatalf("missing thumbnails = %d, want 0 after duration backfill is skipped", missing)
+	}
+}
+
 func TestThumbWorkerFallsBackToLocalPreviewWhenDriveStreamFails(t *testing.T) {
 	ctx := context.Background()
 	cat, video := seedPreviewTestVideo(t, "thumb-worker-local-preview")
@@ -241,42 +349,10 @@ func TestPreviewWorkerNeverCallsDriveUploadOrEnsureDir(t *testing.T) {
 	}
 }
 
-func TestPreviewWorkerSkipsTeaserForVideoLargerThanFiveGiB(t *testing.T) {
+func TestPreviewWorkerGeneratesTeaserForLargeVideo(t *testing.T) {
 	ctx := context.Background()
 	cat, video := seedPreviewTestVideo(t, "preview-large-video")
-	video.Size = maxPreviewTeaserSizeBytes + 1
-	if err := cat.UpsertVideo(ctx, video); err != nil {
-		t.Fatalf("update video: %v", err)
-	}
-
-	gen := &fakeTeaserGenerator{}
-	drv := &previewFakeDrive{}
-	worker := NewWorker(gen, cat, drv)
-
-	worker.process(ctx, video)
-
-	got, err := cat.GetVideo(ctx, video.ID)
-	if err != nil {
-		t.Fatalf("get video: %v", err)
-	}
-	if got.PreviewStatus != previewStatusSkipped {
-		t.Fatalf("preview status = %q, want skipped", got.PreviewStatus)
-	}
-	if got.PreviewLocal != "" {
-		t.Fatalf("preview local = %q, want empty", got.PreviewLocal)
-	}
-	if drv.streamCalls != 0 {
-		t.Fatalf("stream calls = %d, want 0", drv.streamCalls)
-	}
-	if gen.generateCalls != 0 {
-		t.Fatalf("generate calls = %d, want 0", gen.generateCalls)
-	}
-}
-
-func TestPreviewWorkerGeneratesTeaserAtFiveGiBBoundary(t *testing.T) {
-	ctx := context.Background()
-	cat, video := seedPreviewTestVideo(t, "preview-five-gib-video")
-	video.Size = maxPreviewTeaserSizeBytes
+	video.Size = 6 * 1024 * 1024 * 1024
 	if err := cat.UpsertVideo(ctx, video); err != nil {
 		t.Fatalf("update video: %v", err)
 	}
@@ -334,7 +410,7 @@ func TestPreviewWorkerRateLimitLeavesCurrentPendingAndSkipsNextVideo(t *testing.
 	if gen.generateCalls != 1 {
 		t.Fatalf("generate calls = %d, want 1", gen.generateCalls)
 	}
-	assertCooldownAround(t, worker.Status().CooldownUntil, before, 5*time.Minute)
+	assertCooldownAround(t, worker.Status().CooldownUntil, before, 2*time.Hour)
 
 	gen.generateErr = nil
 	worker.process(ctx, &second)
@@ -350,7 +426,7 @@ func TestPreviewWorkerRateLimitLeavesCurrentPendingAndSkipsNextVideo(t *testing.
 	}
 }
 
-func TestThumbWorkerRateLimitCoolsDownFiveMinutes(t *testing.T) {
+func TestThumbWorkerRateLimitHonorsRetryAfter(t *testing.T) {
 	ctx := context.Background()
 	cat, video := seedPreviewTestVideo(t, "thumb-rate-limit")
 
@@ -374,7 +450,97 @@ func TestThumbWorkerRateLimitCoolsDownFiveMinutes(t *testing.T) {
 	if got.ThumbnailURL != "" {
 		t.Fatalf("thumbnail = %q, want unchanged after rate limit", got.ThumbnailURL)
 	}
-	assertCooldownAround(t, worker.Status().CooldownUntil, before, 5*time.Minute)
+	assertCooldownAround(t, worker.Status().CooldownUntil, before, 2*time.Hour)
+}
+
+func TestThumbWorkerP115MessageOnlyErrorFailsWithoutCooldown(t *testing.T) {
+	ctx := context.Background()
+	cat, video := seedPreviewTestVideo(t, "thumb-p115-message-only")
+
+	gen := &fakeThumbGenerator{
+		generateErr: errors.New("ffmpeg thumb: exit status 183, stderr: partial file Cannot determine format of input 0:0 after EOF"),
+	}
+	drv := &previewFakeDrive{kind: "p115"}
+	worker := NewThumbWorker(gen, cat, drv)
+
+	worker.process(ctx, video)
+
+	failed, err := cat.ListVideosByThumbnailStatus(ctx, video.DriveID, "failed", 0)
+	if err != nil {
+		t.Fatalf("list failed thumbnails: %v", err)
+	}
+	if len(failed) != 1 || failed[0].ID != video.ID {
+		t.Fatalf("failed thumbnails = %#v, want only %s", failed, video.ID)
+	}
+	if !worker.Status().CooldownUntil.IsZero() {
+		t.Fatalf("cooldown until = %s, want no cooldown for message-only media error", worker.Status().CooldownUntil)
+	}
+	if gen.generateCalls != 1 {
+		t.Fatalf("generate calls = %d, want 1", gen.generateCalls)
+	}
+}
+
+func TestThumbWorkerDoesNotRequeueP115MessageOnlyError(t *testing.T) {
+	ctx := context.Background()
+	cat, video := seedPreviewTestVideo(t, "thumb-p115-no-requeue")
+
+	gen := &fakeThumbGenerator{
+		generateErr: errors.New("ffmpeg thumb: partial file Cannot determine format of input 0:0 after EOF"),
+	}
+	drv := &previewFakeDrive{kind: "p115"}
+	worker := NewThumbWorker(gen, cat, drv)
+
+	worker.processQueued(ctx, video)
+
+	select {
+	case queued := <-worker.ch:
+		t.Fatalf("unexpected requeued video id = %q", queued.ID)
+	default:
+	}
+
+	got, err := cat.GetVideo(ctx, video.ID)
+	if err != nil {
+		t.Fatalf("get video: %v", err)
+	}
+	if got.ThumbnailURL != "" {
+		t.Fatalf("thumbnail = %q, want empty after message-only failure", got.ThumbnailURL)
+	}
+	failed, err := cat.ListVideosByThumbnailStatus(ctx, video.DriveID, "failed", 0)
+	if err != nil {
+		t.Fatalf("list failed thumbnails: %v", err)
+	}
+	if len(failed) != 1 || failed[0].ID != video.ID {
+		t.Fatalf("failed thumbnails = %#v, want only %s", failed, video.ID)
+	}
+}
+
+func TestThumbWorkerPikPakMoovAtomErrorFailsWithoutCooldown(t *testing.T) {
+	ctx := context.Background()
+	cat, video := seedPreviewTestVideo(t, "thumb-pikpak-missing-moov")
+
+	mediaErr := errors.New("ffprobe: exit status 1, stderr: moov atom not found Invalid data found when processing input")
+	gen := &fakeThumbGenerator{
+		probeErr:    mediaErr,
+		generateErr: mediaErr,
+	}
+	drv := &previewFakeDrive{kind: "pikpak"}
+	worker := NewThumbWorker(gen, cat, drv)
+
+	worker.process(ctx, video)
+
+	failed, err := cat.ListVideosByThumbnailStatus(ctx, video.DriveID, "failed", 0)
+	if err != nil {
+		t.Fatalf("list failed thumbnails: %v", err)
+	}
+	if len(failed) != 1 || failed[0].ID != video.ID {
+		t.Fatalf("failed thumbnails = %#v, want only %s", failed, video.ID)
+	}
+	if !worker.Status().CooldownUntil.IsZero() {
+		t.Fatalf("cooldown until = %s, want no cooldown for invalid PikPak MP4", worker.Status().CooldownUntil)
+	}
+	if gen.generateCalls != 1 {
+		t.Fatalf("generate calls = %d, want 1", gen.generateCalls)
+	}
 }
 
 func TestPreviewWorkerP115TransientErrorKeepsVideoPending(t *testing.T) {
@@ -401,6 +567,86 @@ func TestPreviewWorkerP115TransientErrorKeepsVideoPending(t *testing.T) {
 	}
 }
 
+func TestP123TransientErrorsShouldCooldown(t *testing.T) {
+	drv := &previewFakeDrive{kind: "p123"}
+	for _, err := range []error{
+		errors.New("Server returned 403 Forbidden"),
+		errors.New("http 503 service unavailable"),
+	} {
+		if !driveErrorShouldCooldown(drv, err) {
+			t.Fatalf("driveErrorShouldCooldown(%v) = false, want true", err)
+		}
+	}
+	if driveErrorShouldCooldown(drv, errors.New("请求太频繁")) {
+		t.Fatal("message-only throttling text should not trigger p123 cooldown")
+	}
+	if driveErrorShouldCooldown(drv, errors.New("invalid credential")) {
+		t.Fatal("invalid credential should not trigger p123 cooldown")
+	}
+}
+
+func TestWopanTransientErrorsShouldCooldown(t *testing.T) {
+	drv := &previewFakeDrive{kind: "wopan"}
+	for _, err := range []error{
+		errors.New("ffmpeg: Server returned 403 Forbidden"),
+		errors.New("wopan download url: request failed with status: 429 Too Many Requests"),
+		errors.New("http 503 service unavailable"),
+	} {
+		if !driveErrorShouldCooldown(drv, err) {
+			t.Fatalf("driveErrorShouldCooldown(%v) = false, want true", err)
+		}
+	}
+	if driveErrorShouldCooldown(drv, errors.New("操作频繁，请稍后重试")) {
+		t.Fatal("message-only throttling text should not trigger wopan cooldown")
+	}
+	if driveErrorShouldCooldown(drv, errors.New("invalid access token")) {
+		t.Fatal("invalid access token should not trigger wopan cooldown")
+	}
+}
+
+func TestGuangYaPanTransientErrorsShouldCooldown(t *testing.T) {
+	drv := &previewFakeDrive{kind: "guangyapan"}
+	for _, err := range []error{
+		errors.New("ffmpeg: Server returned 403 Forbidden"),
+		errors.New("guangyapan api rate limited: status=429 msg=操作频繁，请稍后重试"),
+		errors.New("http 503 service unavailable"),
+	} {
+		if !driveErrorShouldCooldown(drv, err) {
+			t.Fatalf("driveErrorShouldCooldown(%v) = false, want true", err)
+		}
+	}
+	if driveErrorShouldCooldown(drv, errors.New("操作频繁，请稍后重试")) {
+		t.Fatal("message-only throttling text should not trigger guangyapan cooldown")
+	}
+	if driveErrorShouldCooldown(drv, errors.New("invalid access token")) {
+		t.Fatal("invalid access token should not trigger guangyapan cooldown")
+	}
+}
+
+func TestGoogleDriveMediaErrorsShouldCooldown(t *testing.T) {
+	drv := &previewFakeDrive{kind: "googledrive"}
+	for _, err := range []error{
+		errors.New("ffmpeg: Server returned 403 Forbidden"),
+		errors.New("http 503 service unavailable"),
+	} {
+		if !driveErrorShouldCooldown(drv, err) {
+			t.Fatalf("driveErrorShouldCooldown(%v) = false, want true", err)
+		}
+	}
+	for _, err := range []error{
+		errors.New("google drive api error: usageLimits userRateLimitExceeded"),
+		errors.New("downloadQuotaExceeded: The download quota for this file has been exceeded"),
+		errors.New("sharingRateLimitExceeded"),
+	} {
+		if driveErrorShouldCooldown(drv, err) {
+			t.Fatalf("message-only google drive error %v should not trigger cooldown", err)
+		}
+	}
+	if driveErrorShouldCooldown(drv, errors.New("invalid credentials")) {
+		t.Fatal("invalid credentials should not trigger googledrive cooldown")
+	}
+}
+
 func assertCooldownAround(t *testing.T, until time.Time, before time.Time, want time.Duration) {
 	t.Helper()
 	if until.IsZero() {
@@ -469,15 +715,22 @@ type fakeThumbGenerator struct {
 	thumbnailDuration float64
 	thumbnailURL      string
 	probeCalls        int
+	generateCalls     int
+	probeDuration     float64
+	probeErr          error
 	generateErr       error
 }
 
 func (g *fakeThumbGenerator) Probe(context.Context, *drives.StreamLink) (float64, error) {
 	g.probeCalls++
-	return 42, nil
+	if g.probeErr != nil {
+		return 0, g.probeErr
+	}
+	return g.probeDuration, nil
 }
 
 func (g *fakeThumbGenerator) GenerateThumbnail(_ context.Context, link *drives.StreamLink, videoID string, duration float64) (string, error) {
+	g.generateCalls++
 	g.thumbnailVideoID = videoID
 	g.thumbnailDuration = duration
 	if link != nil {
@@ -568,7 +821,6 @@ func (d *previewFakeDrive) EnsureDir(context.Context, string) (string, error) {
 }
 func (d *previewFakeDrive) RootID() string { return "root" }
 
-
 func TestWorkerWaitIdleReturnsImmediatelyWhenQueueEmpty(t *testing.T) {
 	worker := NewWorker(&fakeTeaserGenerator{}, nil, &previewFakeDrive{})
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)

backend/internal/proxy/proxy.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"path/filepath"
 	"sync"
 	"time"
 
@@ -144,13 +145,21 @@ func (p *Proxy) ServeStream(w http.ResponseWriter, r *http.Request, driveID, fil
 //     302 之后浏览器用自己的 UA 直连，CDN 仍然认签名
 //   - pikpak：与 OpenList 一致，WebContentLink / media link 都是自签 URL，
 //     CDN 不校验请求头，直连可获得最佳带宽并避免占用 backend 出站
+//   - onedrive：Microsoft Graph 返回的 @microsoft.graph.downloadUrl 是短期
+//     免鉴权下载 URL，不需要后端继续代传视频字节
+//   - p123：123网盘 download_info 返回的下载页会再跳 CDN；driver 已在后端
+//     先解出最终 Location，浏览器可直接 302 到该短期地址
+//   - wopan：联通网盘 GetDownloadUrlV2 返回的是短期直链，OpenList 也是直接
+//     将该 URL 交给客户端使用；不需要后端持续代传视频字节
+//   - guangyapan：光鸭 get_res_download_url 返回 signedURL / downloadUrl，
+//     浏览器可直接访问，不需要后端持续代传视频字节
 //
-// 其余网盘（如 OneDrive / 沃盘 / 夸克等）仍走反代，因为它们的下载
+// 其余网盘（如夸克等）仍走反代，因为它们的下载
 // 链接通常需要随请求带上后端持有的 Cookie / Authorization / Range
 // 的特殊处理，浏览器拿不到这些上下文。
 func shouldRedirect(d drives.Drive) bool {
 	switch d.Kind() {
-	case "p115", "pikpak":
+	case "p115", "pikpak", "onedrive", "p123", "wopan", "guangyapan":
 		return true
 	}
 	return false
@@ -169,6 +178,11 @@ func (p *Proxy) serve(w http.ResponseWriter, r *http.Request, link *drives.Strea
 		http.Error(w, "bad upstream url", http.StatusBadGateway)
 		return
 	}
+	if localPath, ok := localFilePath(u, link.URL); ok {
+		w.Header().Set("Cache-Control", "private, max-age=300")
+		http.ServeFile(w, r, localPath)
+		return
+	}
 	req, err := http.NewRequestWithContext(r.Context(), r.Method, u.String(), nil)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
@@ -206,11 +220,24 @@ func (p *Proxy) serve(w http.ResponseWriter, r *http.Request, link *drives.Strea
 	_, _ = io.Copy(w, resp.Body)
 }
 
-// ServeLocal 服务本地 teaser 文件
+// ServeLocal 服务本地预览视频文件
 func (p *Proxy) ServeLocal(w http.ResponseWriter, r *http.Request, path string) {
 	http.ServeFile(w, r, path)
 }
 
+func localFilePath(u *url.URL, raw string) (string, bool) {
+	if u == nil {
+		return "", false
+	}
+	if u.Scheme == "file" && u.Path != "" {
+		return u.Path, true
+	}
+	if u.Scheme == "" && u.Host == "" && filepath.IsAbs(raw) {
+		return raw, true
+	}
+	return "", false
+}
+
 var errDriveNotFound = &httpError{Code: http.StatusNotFound, Msg: "drive not found"}
 
 type httpError struct {

backend/internal/proxy/proxy_test.go

@@ -5,6 +5,8 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"testing"
 	"time"
 
@@ -149,6 +151,136 @@ func TestServeStreamPikPakSetsRedirectHeaders(t *testing.T) {
 	}
 }
 
+func TestServeStreamRedirectsOneDrive(t *testing.T) {
+	reg := NewRegistry()
+	drv := &proxyFakeSimpleDrive{
+		kind: "onedrive",
+		url:  "https://public.onedrive.example/video.mp4",
+	}
+	reg.Set("onedrive", drv)
+
+	p := New(reg)
+	req := httptest.NewRequest(http.MethodGet, "/p/stream/onedrive/file-1", nil)
+	rr := httptest.NewRecorder()
+
+	p.ServeStream(rr, req, "onedrive", "file-1")
+
+	if rr.Code != http.StatusFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusFound)
+	}
+	if got := rr.Header().Get("Location"); got != "https://public.onedrive.example/video.mp4" {
+		t.Fatalf("Location = %q", got)
+	}
+	if drv.calls != 1 {
+		t.Fatalf("link calls = %d, want 1", drv.calls)
+	}
+}
+
+func TestServeStreamRedirectsP123(t *testing.T) {
+	reg := NewRegistry()
+	drv := &proxyFakeSimpleDrive{
+		kind: "p123",
+		url:  "https://cdn.123pan.example/video.mp4",
+	}
+	reg.Set("p123", drv)
+
+	p := New(reg)
+	req := httptest.NewRequest(http.MethodGet, "/p/stream/p123/file-1", nil)
+	rr := httptest.NewRecorder()
+
+	p.ServeStream(rr, req, "p123", "file-1")
+
+	if rr.Code != http.StatusFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusFound)
+	}
+	if got := rr.Header().Get("Location"); got != "https://cdn.123pan.example/video.mp4" {
+		t.Fatalf("Location = %q", got)
+	}
+	if drv.calls != 1 {
+		t.Fatalf("link calls = %d, want 1", drv.calls)
+	}
+}
+
+func TestServeStreamRedirectsWopan(t *testing.T) {
+	reg := NewRegistry()
+	drv := &proxyFakeSimpleDrive{
+		kind: "wopan",
+		url:  "https://du.smartont.net:8445/openapi/download?fid=encoded",
+	}
+	reg.Set("wopan", drv)
+
+	p := New(reg)
+	req := httptest.NewRequest(http.MethodGet, "/p/stream/wopan/file-1", nil)
+	rr := httptest.NewRecorder()
+
+	p.ServeStream(rr, req, "wopan", "file-1")
+
+	if rr.Code != http.StatusFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusFound)
+	}
+	if got := rr.Header().Get("Location"); got != "https://du.smartont.net:8445/openapi/download?fid=encoded" {
+		t.Fatalf("Location = %q", got)
+	}
+	if drv.calls != 1 {
+		t.Fatalf("link calls = %d, want 1", drv.calls)
+	}
+}
+
+func TestServeStreamRedirectsGuangYaPan(t *testing.T) {
+	reg := NewRegistry()
+	drv := &proxyFakeSimpleDrive{
+		kind: "guangyapan",
+		url:  "https://cdn.guangyapan.example/video.mp4?sign=encoded",
+	}
+	reg.Set("guangyapan", drv)
+
+	p := New(reg)
+	req := httptest.NewRequest(http.MethodGet, "/p/stream/guangyapan/file-1", nil)
+	rr := httptest.NewRecorder()
+
+	p.ServeStream(rr, req, "guangyapan", "file-1")
+
+	if rr.Code != http.StatusFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusFound)
+	}
+	if got := rr.Header().Get("Location"); got != "https://cdn.guangyapan.example/video.mp4?sign=encoded" {
+		t.Fatalf("Location = %q", got)
+	}
+	if drv.calls != 1 {
+		t.Fatalf("link calls = %d, want 1", drv.calls)
+	}
+}
+
+func TestServeStreamServesLocalFilePath(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "video.mp4")
+	if err := os.WriteFile(path, []byte("0123456789"), 0o644); err != nil {
+		t.Fatalf("write local file: %v", err)
+	}
+	reg := NewRegistry()
+	drv := &proxyFakeSimpleDrive{
+		kind: "localstorage",
+		url:  path,
+	}
+	reg.Set("local", drv)
+
+	p := New(reg)
+	req := httptest.NewRequest(http.MethodGet, "/p/stream/local/file-1", nil)
+	req.Header.Set("Range", "bytes=2-5")
+	rr := httptest.NewRecorder()
+
+	p.ServeStream(rr, req, "local", "file-1")
+
+	if rr.Code != http.StatusPartialContent {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusPartialContent)
+	}
+	if got := rr.Body.String(); got != "2345" {
+		t.Fatalf("body = %q, want range bytes", got)
+	}
+	if drv.calls != 1 {
+		t.Fatalf("link calls = %d, want 1", drv.calls)
+	}
+}
+
 func requestPikPak(t *testing.T, p *Proxy, driveID, fileID, ua string) {
 	t.Helper()
 	req := httptest.NewRequest(http.MethodGet, "/p/stream/"+driveID+"/"+fileID, nil)
@@ -192,3 +324,36 @@ func (d *proxyFakePikPakDrive) EnsureDir(context.Context, string) (string, error
 	return "", drives.ErrNotSupported
 }
 func (d *proxyFakePikPakDrive) RootID() string { return "0" }
+
+type proxyFakeSimpleDrive struct {
+	kind  string
+	url   string
+	calls int
+}
+
+func (d *proxyFakeSimpleDrive) Kind() string { return d.kind }
+func (d *proxyFakeSimpleDrive) ID() string   { return d.kind }
+func (d *proxyFakeSimpleDrive) Init(context.Context) error {
+	return nil
+}
+func (d *proxyFakeSimpleDrive) List(context.Context, string) ([]drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *proxyFakeSimpleDrive) Stat(context.Context, string) (*drives.Entry, error) {
+	return nil, drives.ErrNotSupported
+}
+func (d *proxyFakeSimpleDrive) StreamURL(context.Context, string) (*drives.StreamLink, error) {
+	d.calls++
+	return &drives.StreamLink{
+		URL:     d.url,
+		Headers: http.Header{},
+		Expires: time.Now().Add(10 * time.Minute),
+	}, nil
+}
+func (d *proxyFakeSimpleDrive) Upload(context.Context, string, string, io.Reader, int64) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *proxyFakeSimpleDrive) EnsureDir(context.Context, string) (string, error) {
+	return "", drives.ErrNotSupported
+}
+func (d *proxyFakeSimpleDrive) RootID() string { return "0" }

backend/internal/scanner/filename.go

@@ -16,11 +16,11 @@ type ParsedName struct {
 }
 
 var (
-	reTags   = regexp.MustCompile(`^\s*\[([^\]]+)\]\s*`) // [tag1,tag2]
+	reTags   = regexp.MustCompile(`^\s*\[([^\]]+)\]\s*`) // [前缀]
 	reAuthor = regexp.MustCompile(`\s*-\s*([^-]+?)\s*$`) // - author
 )
 
-// Parse 按约定解析：[tag1,tag2] 标题 - 作者.ext
+// Parse 按约定解析：[前缀] 标题 - 作者.ext
 // 任何字段缺失都能降级
 func Parse(filename string) ParsedName {
 	name := strings.TrimSuffix(filename, path.Ext(filename))

backend/internal/scanner/scanner.go

@@ -2,6 +2,7 @@ package scanner
 
 import (
 	"context"
+	"encoding/base64"
 	"fmt"
 	"log"
 	"path"
@@ -23,8 +24,10 @@ type Scanner struct {
 	//
 	// nil / 空集合 → 行为等同于不跳过任何目录。
 	SkipDirIDs map[string]struct{}
-	// 回调：新视频被加入后触发 teaser 生成
+	// 回调：新视频被加入后触发预览视频生成
 	OnNewVideo func(v *catalog.Video)
+	// OnProgress 在扫描进度变化时触发。回调只应读取 Stats 里的计数，不应修改 map 字段。
+	OnProgress func(stats Stats)
 	// ProgressInterval 控制扫描内部 heartbeat 的最小输出间隔。
 	// 0 → 默认 30s；< 0 → 关闭 heartbeat（仅留外层 start / done 两行）。
 	// heartbeat 单行格式：
@@ -91,6 +94,9 @@ func (s *Scanner) Run(ctx context.Context, startDirID string) (Stats, error) {
 		driveID = s.Drive.ID()
 	}
 	progress := func(currentDir string) {
+		if s.OnProgress != nil {
+			s.OnProgress(stats)
+		}
 		if interval < 0 {
 			return
 		}
@@ -127,8 +133,11 @@ func (s *Scanner) walk(ctx context.Context, dirID, dirName string, stats *Stats,
 	}
 
 	for _, e := range entries {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
 		if e.IsDir {
-			// 跳过 previews 目录，避免扫到自己生成的 teaser
+			// 跳过 previews 目录，避免扫到自己生成的预览视频
 			if strings.EqualFold(e.Name, "previews") {
 				continue
 			}
@@ -137,13 +146,15 @@ func (s *Scanner) walk(ctx context.Context, dirID, dirName string, stats *Stats,
 				continue
 			}
 			if err := s.walk(ctx, e.ID, e.Name, stats, progress); err != nil {
+				if ctxErr := ctx.Err(); ctxErr != nil {
+					return ctxErr
+				}
 				stats.Errors++
 				log.Printf("[scanner] walk %s error: %v", e.Name, err)
 			}
 			continue
 		}
 
-		stats.Scanned++
 		ext := strings.ToLower(path.Ext(e.Name))
 		if !s.Exts[ext] {
 			continue
@@ -151,9 +162,22 @@ func (s *Scanner) walk(ctx context.Context, dirID, dirName string, stats *Stats,
 		if e.Size <= 0 {
 			continue
 		}
+		stats.Scanned++
+		progress(dirName)
 		stats.SeenFileIDs[e.ID] = struct{}{}
 
-		id := s.Drive.Kind() + "-" + s.Drive.ID() + "-" + e.ID
+		id := s.Drive.Kind() + "-" + s.Drive.ID() + "-" + videoIDFilePart(e.ID)
+		if deleted, err := s.Catalog.IsDeletedVideoCandidate(ctx, id, s.Drive.ID(), e.ID, e.Hash, e.Name, e.Size); err != nil {
+			if ctxErr := ctx.Err(); ctxErr != nil {
+				return ctxErr
+			}
+			stats.Errors++
+			log.Printf("[scanner] check deleted video %s error: %v", id, err)
+			continue
+		} else if deleted {
+			continue
+		}
+
 		parsed := Parse(e.Name)
 		if parsed.Title == "" {
 			parsed.Title = strings.TrimSuffix(e.Name, ext)
@@ -162,45 +186,55 @@ func (s *Scanner) walk(ctx context.Context, dirID, dirName string, stats *Stats,
 		if matched, err := s.Catalog.MatchTags(ctx, e.Name+" "+dirName+" "+parsed.Author); err == nil {
 			tags = mergeTags(tags, matched)
 		}
-		if label, ok, err := s.Catalog.EnsureCollectionTag(ctx, dirName); err == nil && ok {
-			tags = mergeTags(tags, []string{label})
+		if err := ctx.Err(); err != nil {
+			return err
 		}
 
 		existing, _ := s.Catalog.GetVideo(ctx, id)
+		if err := ctx.Err(); err != nil {
+			return err
+		}
 		if existing != nil {
 			patch := catalog.VideoMetaPatch{}
 			if e.Hash != "" && existing.ContentHash == "" {
 				patch.ContentHash = e.Hash
 				existing.ContentHash = e.Hash
 			}
-			if e.Name != "" && existing.FileName == "" {
+			if e.Name != "" && existing.FileName != e.Name {
 				patch.FileName = e.Name
 				existing.FileName = e.Name
+				patch.Title = parsed.Title
+				patch.TitleSet = true
+				patch.Author = parsed.Author
+				patch.AuthorSet = true
 			}
-			// 已存在但轻量元数据空缺时，顺便补齐。
-			if existing.Category == "" && dirName != "" {
-				patch.Category = dirName
-			}
-			if existing.ThumbnailURL == "" && e.ThumbnailURL != "" {
-				patch.ThumbnailURL = e.ThumbnailURL
-			}
-			if patch.Category != "" || patch.ThumbnailURL != "" || patch.ContentHash != "" || patch.FileName != "" {
+			if patch.ContentHash != "" || patch.FileName != "" || patch.TitleSet || patch.AuthorSet {
 				_ = s.Catalog.UpdateVideoMeta(ctx, id, patch)
+				if err := ctx.Err(); err != nil {
+					return err
+				}
 			}
 			if dup := s.findDuplicate(ctx, e.Hash, e.Name, e.Size, id); dup != nil {
-				s.backfillDuplicateThumbnail(ctx, dup, e.ThumbnailURL)
 				continue
 			}
+			if err := ctx.Err(); err != nil {
+				return err
+			}
 			if !sameTags(existing.Tags, tags) {
 				_ = s.Catalog.SetAutoVideoTags(ctx, id, tags)
+				if err := ctx.Err(); err != nil {
+					return err
+				}
 			}
 			continue
 		}
 
 		if dup := s.findDuplicate(ctx, e.Hash, e.Name, e.Size, id); dup != nil {
-			s.backfillDuplicateThumbnail(ctx, dup, e.ThumbnailURL)
 			continue
 		}
+		if err := ctx.Err(); err != nil {
+			return err
+		}
 
 		now := time.Now()
 		v := &catalog.Video{
@@ -216,18 +250,23 @@ func (s *Scanner) walk(ctx context.Context, dirID, dirName string, stats *Stats,
 			Ext:           strings.TrimPrefix(ext, "."),
 			Quality:       "HD",
 			Size:          e.Size,
-			ThumbnailURL:  e.ThumbnailURL,
 			PreviewStatus: "pending",
-			Category:      dirName,
 			PublishedAt:   now,
 			CreatedAt:     now,
 			UpdatedAt:     now,
 		}
 		if err := s.Catalog.UpsertVideo(ctx, v); err != nil {
+			if ctxErr := ctx.Err(); ctxErr != nil {
+				return ctxErr
+			}
 			log.Printf("[scanner] upsert %s error: %v", v.Title, err)
 			continue
 		}
+		if err := ctx.Err(); err != nil {
+			return err
+		}
 		stats.Added++
+		progress(dirName)
 		if s.OnNewVideo != nil {
 			s.OnNewVideo(v)
 		}
@@ -268,13 +307,6 @@ func (s *Scanner) findDuplicateByFileSignature(ctx context.Context, fileName str
 	return dup
 }
 
-func (s *Scanner) backfillDuplicateThumbnail(ctx context.Context, canonical *catalog.Video, thumbnailURL string) {
-	if canonical.ThumbnailURL != "" || thumbnailURL == "" {
-		return
-	}
-	_ = s.Catalog.UpdateVideoMeta(ctx, canonical.ID, catalog.VideoMetaPatch{ThumbnailURL: thumbnailURL})
-}
-
 func sameTags(a, b []string) bool {
 	if len(a) != len(b) {
 		return false
@@ -301,3 +333,10 @@ func mergeTags(lists ...[]string) []string {
 	}
 	return out
 }
+
+func videoIDFilePart(fileID string) string {
+	if !strings.ContainsAny(fileID, `/\`+"\x00") {
+		return fileID
+	}
+	return "b64_" + base64.RawURLEncoding.EncodeToString([]byte(fileID))
+}