Files
SakuraHub/docs/login-and-auth.md
T
2026-11-16 20:45:22 +08:00

80 KiB
Raw Blame History

Sakura 项目 — 登录与认证状态验证 完整文档

本文档汇总项目所有模块(桌面端、云端、手机端、管理后台)中登录相关和验证登录状态的代码。
不包括:下载器、画廊、插件系统、代理池等非认证逻辑。


目录

  1. 架构总览
  2. 桌面端 (pixiv_app) — Pixiv 登录 & Cookie 管理
  3. 桌面端 (pixiv_app) — Sakura Cloud Token 管理
  4. 桌面端 (pixiv_app) — X (Twitter) 登录检测
  5. 桌面端 (pixiv_app) — 关注同步中的认证
  6. 桌面端 (pixiv_app) — Gallery API 中的认证接口
  7. 云端 (sakura_cloud) — JWT 安全核心
  8. 云端 (sakura_cloud) — 认证依赖注入
  9. 云端 (sakura_cloud) — 认证 API 端点
  10. 云端 (sakura_cloud) — 管理员登录
  11. 云端 (sakura_cloud) — 数据模型 & 请求模型
  12. 手机端 (sakura_mobile) — Flutter 认证
  13. 管理后台 (sakura_admin_web) — Vue 认证
  14. 认证流程总结

1. 架构总览

┌──────────────────────────────────────────────────────────────┐
│                      认证体系架构                              │
├──────────────┬──────────────────┬────────────────────────────┤
│  桌面端       │   云端 API        │   手机端 / 管理后台           │
│  (Python)    │   (FastAPI)      │   (Flutter / Vue)           │
├──────────────┼──────────────────┼────────────────────────────┤
│ Pixiv Cookie │  JWT Bearer      │  JWT Bearer Token           │
│ + 密码登录    │  access+refresh  │  SharedPreferences 持久化    │
│              │  token_version   │  sessionStorage 持久化        │
│ Sakura Cloud │  即时吊销         │  Axios 拦截器自动刷新          │
│ JWT Token    │  HS256 签名       │  Router Guard 路由守卫        │
│ X Playwright │  pbkdf2/bcrypt   │                             │
│ 持久化会话    │  密码哈希         │                             │
└──────────────┴──────────────────┴────────────────────────────┘

2.1 核心认证客户端

文件: pixiv_app/core/auth.py

from __future__ import annotations

import html
import json
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from urllib.parse import urlencode

import requests

from pixiv_app.core.downloader import USER_AGENT, build_headers


LOGIN_PAGE_URL = "https://accounts.pixiv.net/login"
LOGIN_AJAX_URL = "https://accounts.pixiv.net/ajax/login?lang=zh"
VALIDATE_URL = "https://www.pixiv.net/setting_user.php"


@dataclass
class AuthResult:
    success: bool
    message: str
    cookie: str = ""
    requires_verification: bool = False
    user_name: str = ""
    user_id: str = ""


class SessionStore:
    """本地 JSON 文件持久化会话(Cookie、云同步 Token 等)。"""

    def __init__(self, path: str | Path = "pixiv_app_session.json") -> None:
        self.path = Path(path)

    def load(self) -> dict[str, Any]:
        if not self.path.exists():
            return {}
        try:
            return json.loads(self.path.read_text(encoding="utf-8"))
        except Exception:
            return {}

    def save(self, payload: dict[str, Any]) -> None:
        self.path.write_text(
            json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
        )


class PixivAuthClient:
    """Pixiv 认证客户端:Cookie 验证 + 账号密码登录。"""

    def __init__(self) -> None:
        self.timeout = 20

    # ── Cookie 验证 ──────────────────────────────────────────

    def validate_cookie(self, cookie: str) -> AuthResult:
        """
        验证 Cookie 是否有效。
        原理:用 Cookie 访问 Pixiv 设置页,若被重定向到登录页则失效。
        """
        cookie = cookie.strip()
        if not cookie:
            return AuthResult(False, "Cookie 为空,请先填写或登录。")

        session = requests.Session()
        session.headers.update(
            build_headers(cookie=cookie, referer="https://www.pixiv.net/")
        )
        try:
            response = session.get(
                VALIDATE_URL, allow_redirects=True, timeout=self.timeout
            )
            final_url = response.url
            # 被重定向到登录页 = Cookie 失效
            if "return_to=" in final_url or "accounts.pixiv.net" in final_url:
                return AuthResult(False, "当前 Cookie 已失效或未登录,请更新会话。")
            user_id, user_name = self._extract_user_info(response.text)
            return AuthResult(
                True, "Cookie 有效,可直接开始抓取。",
                cookie=cookie, user_name=user_name, user_id=user_id,
            )
        except Exception as exc:
            return AuthResult(False, f"Cookie 检测失败: {exc}")

    # ── 账号密码登录 ──────────────────────────────────────────

    def login_with_password(self, login_id: str, password: str) -> AuthResult:
        """
        Pixiv 账号密码登录。
        流程:获取 CSRF Token → POST 登录 → 提取 Cookie → 验证 Cookie。
        """
        login_id = login_id.strip()
        password = password.strip()
        if not login_id or not password:
            return AuthResult(False, "账号和密码都不能为空。")

        session = requests.Session()
        session.headers.update({
            "User-Agent": USER_AGENT,
            "Accept": "application/json, text/plain, */*",
            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
            "Origin": "https://accounts.pixiv.net",
            "Referer": LOGIN_PAGE_URL,
            "X-Requested-With": "XMLHttpRequest",
        })

        try:
            # 1. 获取 CSRF token
            login_page = session.get(LOGIN_PAGE_URL, timeout=self.timeout)
            login_page.raise_for_status()
            tt = self._extract_tt(login_page.text)

            # 2. 构造登录请求
            payload = {
                "login_id": login_id,
                "password": password,
                "source": "accounts",
                "app_ios": "0",
                "ref": "",
                "return_to": "https://www.pixiv.net/",
                "g_recaptcha_response": "",
                "recaptcha_enterprise_score_token": "",
            }
            headers = dict(session.headers)
            if tt:
                headers["X-CSRF-Token"] = tt

            response = session.post(
                LOGIN_AJAX_URL,
                data=urlencode(payload),
                headers={**headers, "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8"},
                timeout=self.timeout,
            )
            response.raise_for_status()
            body = response.json()

            # 3. 检查登录结果
            if isinstance(body, dict) and body.get("body", {}).get("success"):
                cookie = self._cookies_to_header(session.cookies)
                validation = self.validate_cookie(cookie)
                if validation.success:
                    validation.message = "账号密码登录成功,会话已可用。"
                    return validation
                return AuthResult(
                    True, "登录接口返回成功,但会话校验未完全通过,请手动检测。",
                    cookie=cookie,
                )

            # 4. 处理需要额外验证的情况
            body_payload = body.get("body", {}) if isinstance(body, dict) else {}
            errors = body_payload.get("errors", {}) if isinstance(body_payload, dict) else {}
            if (
                errors.get("recaptcha")
                or body_payload.get("requireExtraVerification")
                or body_payload.get("requireTwoFactorAuthentication")
            ):
                return AuthResult(
                    False,
                    "Pixiv 要求额外验证或二步验证,程序无法静默完成。请改用 Cookie 登录。",
                    requires_verification=True,
                )
            message = self._flatten_error_message(errors) or "账号密码登录失败"
            return AuthResult(False, message)
        except Exception as exc:
            return AuthResult(False, f"账号密码登录失败: {exc}")

    # ── CSRF Token 提取 ──────────────────────────────────────

    def _extract_tt(self, html_text: str) -> str:
        """从 Pixiv 登录页提取 CSRF token (pixivAccount.tt)。"""
        match = re.search(r'"pixivAccount\.tt":"([^"]+)"', html_text)
        return match.group(1) if match else ""

    # ── 用户信息提取 ──────────────────────────────────────────

    def _extract_user_info(self, html_text: str) -> tuple[str, str]:
        """从页面 HTML 中正则提取 user_id 和 user_name。"""
        user_id = ""
        user_name = ""
        patterns = [
            r'"userData":\{"id":"(\d+)","pixivId":"[^"]*","name":"([^"]+)"',
            r'"user_id":"(\d+)".*?"name":"([^"]+)"',
        ]
        for pattern in patterns:
            match = re.search(pattern, html_text)
            if match:
                user_id = match.group(1)
                user_name = html.unescape(match.group(2))
                break
        return user_id, user_name

    # ── 工具方法 ──────────────────────────────────────────────

    def _flatten_error_message(self, errors: dict[str, Any]) -> str:
        messages: list[str] = []
        for key, value in errors.items():
            if isinstance(value, str) and value.strip():
                messages.append(f"{key}: {value}")
            elif isinstance(value, list):
                text_items = [str(item).strip() for item in value if str(item).strip()]
                if text_items:
                    messages.append(f"{key}: {'; '.join(text_items)}")
        return " | ".join(messages)

    def _cookies_to_header(self, jar: requests.cookies.RequestsCookieJar) -> str:
        parts = [f"{cookie.name}={cookie.value}" for cookie in jar]
        return "; ".join(parts)

2.2 GUI 中的 Pixiv 登录与会话管理

文件: pixiv_app/gui/app.py(关键方法摘录)

# ── 类成员变量(__init__ 中初始化) ─────────────────────────────

LOGIN_MODE_MAP = {
    "Cookie 登录": "cookie",
    "账号密码登录": "password",
}

self.login_mode_var = ctk.StringVar(value="Cookie 登录")
self.auth_status_var = ctk.StringVar(
    value="未登录,推荐导入 cookies.txt;也可尝试账号密码登录。"
)
self.cookie_json: list[dict] = []
self.cookie_header = ""
self.auth_client = PixivAuthClient()
self.session_store = SessionStore(app_session_file())

# ── Cookie 获取(优先级:JSON → Header → 磁盘) ─────────────────

def get_active_cookie(self) -> str:
    payload = self.session_store.load()
    cookies = self.cookie_json or payload.get("cookie_json") or []
    if cookies:
        try:
            return cookies_to_header(list(cookies), ("pixiv.net",))
        except Exception:
            pass
    if self.cookie_header:
        return self.cookie_header
    return str(payload.get("cookie", "")).strip()

# ── Cookie 导入 ────────────────────────────────────────────────

def import_cookie_txt(self) -> None:
    """文件对话框导入 cookies.txt / JSON,按域名分类保存"""
    path = filedialog.askopenfilename(
        title="导入 Cookie txt",
        filetypes=[("Cookie files", "*.txt *.json"), ...],
    )
    if not path:
        return
    try:
        text = Path(path).read_text(encoding="utf-8-sig")
    except UnicodeDecodeError:
        text = Path(path).read_text(encoding="utf-8", errors="replace")
    cookies = parse_cookie_text(text)

    # 按平台分类
    pixiv_cookies = (
        cookies_to_playwright(cookies, ("pixiv.net",))
        if has_cookie_domain(cookies, ("pixiv.net,")) else []
    )
    x_cookies = (
        cookies_to_playwright(cookies, ("x.com", "twitter.com"))
        if has_cookie_domain(cookies, ("x.com", "twitter.com")) else []
    )

    self.cookie_json = cookies
    self.cookie_header = (
        cookies_to_header(pixiv_cookies, ("pixiv.net",)) if pixiv_cookies else ""
    )
    self.login_mode_var.set("Cookie 登录")
    self.update_login_mode_ui("Cookie 登录")

    if x_cookies:
        save_playwright_cookies(x_cookies, runtime_path("x_cookies.json"))
    self.save_session()

# ── 会话持久化 ─────────────────────────────────────────────────

def save_session(self) -> None:
    cookie = self.get_active_cookie()
    cloud_config = self.get_cloud_sync_config()
    payload = {
        "login_mode": self.LOGIN_MODE_MAP.get(self.login_mode_var.get(), "cookie"),
        "cookie": cookie,
        "cookie_json": self.cookie_json,
        "login_id": self.login_id_entry.get().strip(),
        "cloud_sync": cloud_config,
        "saved_at": time.strftime("%Y-%m-%d %H:%M:%S"),
    }
    self.session_store.save(payload)

def load_saved_session(self, silent: bool = False) -> None:
    """启动时从磁盘恢复会话(Pixiv Cookie + Cloud Token)"""
    payload = self.session_store.load()
    if not payload:
        return
    # 恢复 Pixiv 会话
    self.cookie_json = list(payload.get("cookie_json") or [])
    self.cookie_header = str(payload.get("cookie", "") or "")
    self.login_id_entry.insert(0, str(payload.get("login_id", "")))

    # 恢复 Cloud 会话
    cloud = payload.get("cloud_sync") if isinstance(payload.get("cloud_sync"), dict) else {}
    self.cloud_base_url = str(cloud.get("base_url") or DEFAULT_CLOUD_API)
    self.cloud_access_token = str(cloud.get("access_token") or "")
    self.cloud_refresh_token = str(cloud.get("refresh_token") or "")
    CloudSession().configure(
        base_url=self.cloud_base_url,
        access_token=self.cloud_access_token,
        refresh_token=self.cloud_refresh_token,
        enabled=bool(cloud.get("enabled", False)),
    )
    CloudSession().add_listener(self._on_cloud_token_refreshed)

# ── Cookie 验证 ────────────────────────────────────────────────

def validate_session(self) -> None:
    """线程中调用 auth_client.validate_cookie()"""
    cookie = self.get_active_cookie()
    if not cookie:
        messagebox.showerror("检测失败", "当前没有 Cookie 可检测。")
        return
    self.auth_status_var.set("正在检测当前会话...")

    def worker() -> None:
        result = self.auth_client.validate_cookie(cookie)
        self.enqueue_ui(self.apply_auth_result, result, False)

    threading.Thread(target=worker, daemon=True).start()

# ── 密码登录 ───────────────────────────────────────────────────

def login_with_password(self) -> None:
    login_id = self.login_id_entry.get().strip()
    password = self.password_entry.get().strip()
    if not login_id or not password:
        messagebox.showerror("登录失败", "请先填写账号和密码。")
        return
    self.auth_status_var.set("正在尝试账号密码登录...")

    def worker() -> None:
        result = self.auth_client.login_with_password(login_id, password)
        self.enqueue_ui(self.apply_auth_result, result, True)

    threading.Thread(target=worker, daemon=True).start()

def apply_auth_result(self, result: AuthResult, from_password_login: bool) -> None:
    """统一处理认证结果:更新 UI、保存会话"""
    self.auth_status_var.set(result.message)
    if result.success and result.cookie:
        self.cookie_json = []
        self.cookie_header = result.cookie
        self.set_cookie_indicator("账号密码登录已生成 Cookie header")
        if from_password_login:
            self.login_mode_var.set("Cookie 登录")
            self.update_login_mode_ui("Cookie 登录")
        self.save_session()

2.3 GUI 中的云同步登录对话框

文件: pixiv_app/gui/app.py(open_cloud_auth_dialog 方法摘要)

def open_cloud_auth_dialog(self) -> None:
    """Sakura Cloud 账号管理窗口:登录 / 注册 / 获取 Token 三个标签页"""

    # ── 登录标签页 ──────────────────────────────────────────
    def do_login() -> None:
        email = login_email.get().strip()
        password = login_password.get()
        # ...
        def worker() -> None:
            resp = requests.post(
                f"{api_addr}/api/v1/auth/login",
                json={"username_or_email": email, "password": password},
                timeout=15,
            )
            if resp.status_code == 200:
                data = resp.json()
                token = data.get("data", {}).get("access_token")
                if token:
                    self.cloud_access_token = str(token).strip()
                    refresh = (data.get("data", {}).get("refresh_token") or "")
                    if refresh:
                        self.cloud_refresh_token = str(refresh).strip()
                    # 同步到全局单例
                    CloudSession().configure(
                        base_url=self.cloud_base_url,
                        access_token=self.cloud_access_token,
                        refresh_token=self.cloud_refresh_token,
                        enabled=True,
                    )
                    self.cloud_sync_enabled_var.set(True)
                    self.save_session()
        threading.Thread(target=worker, daemon=True).start()

    # ── 注册标签页 ──────────────────────────────────────────
    def do_register() -> None:
        # POST /api/v1/auth/register
        resp = requests.post(
            f"{api_addr}/api/v1/auth/register",
            json={"username": username, "email": email, "password": password},
            timeout=15,
        )
        if resp.status_code == 201:
            # 注册成功,切换到登录页

def test_cloud_connection(self) -> None:
    """测试云连接:GET /api/v1/users/me 验证 Token 有效性"""
    def worker() -> None:
        resp = requests.get(
            f"{api_url}/api/v1/users/me",
            headers={"Authorization": f"Bearer {token}"},
            timeout=10,
        )
        if resp.status_code == 200:
            user = resp.json().get("data", {})
            username = user.get("username", "未知")
            self.cloud_status_var.set(f"连接成功!用户:{username}")

3. 桌面端 (pixiv_app) — Sakura Cloud Token 管理

3.1 CloudSession 全局单例

文件: pixiv_app/core/cloud_sync.py

import base64
import json
import logging
import threading
import time
from collections.abc import Callable
from typing import Any

import requests

logger = logging.getLogger(__name__)


# ── JWT exp 解码 ────────────────────────────────────────────────

def _decode_jwt_exp(token: str) -> float:
    """解码 JWT payload 中的 exp 字段,返回 Unix 时间戳。"""
    if not token or "." not in token:
        return 0.0
    try:
        payload = token.split(".")[1]
        payload += "=" * (4 - len(payload) % 4)
        decoded = json.loads(base64.urlsafe_b64decode(payload))
        return float(decoded.get("exp", 0))
    except Exception:
        return 0.0


# ── Token 持久化到磁盘 ──────────────────────────────────────────

def persist_cloud_session_tokens(access_token: str, refresh_token: str = "") -> None:
    """将刷新后的 Token 写回桌面会话文件。"""
    from pixiv_app.core.auth import SessionStore
    from pixiv_app.core.paths import app_session_file

    store = SessionStore(app_session_file())
    payload = store.load()
    cloud = payload.get("cloud_sync") if isinstance(payload.get("cloud_sync"), dict) else {}
    cloud["access_token"] = access_token
    if refresh_token:
        cloud["refresh_token"] = refresh_token
    payload["cloud_sync"] = cloud
    store.save(payload)


# ── CloudSession 全局单例 ───────────────────────────────────────

class CloudSession:
    """
    全局单例,统一管理云同步 Token 的读写、刷新与持久化。
    所有需要访问 Sakura Cloud API 的模块都通过此单例获取配置和创建客户端。
    """

    _instance: CloudSession | None = None
    _instance_lock = threading.Lock()

    def __new__(cls) -> CloudSession:
        if cls._instance is None:
            with cls._instance_lock:
                if cls._instance is None:
                    instance = super().__new__(cls)
                    instance._base_url = ""
                    instance._access_token = ""
                    instance._refresh_token = ""
                    instance._enabled = False
                    instance._refresh_lock = threading.Lock()
                    instance._listeners: list[Callable[[str, str], None]] = []
                    instance._last_refresh_time = 0.0
                    cls._instance = instance
        return cls._instance

    # ── 配置入口 ────────────────────────────────────────────

    def configure(self, *, base_url="", access_token="", refresh_token="", enabled=False):
        """GUI 启动/登录/保存会话时调用,同步最新 token 到全局单例。"""
        self._base_url = (base_url or "").strip()
        self._access_token = (access_token or "").strip()
        self._refresh_token = (refresh_token or "").strip()
        self._enabled = bool(enabled)

    def load_from_disk(self) -> dict[str, Any]:
        """从磁盘会话文件读取云端配置并应用到单例。"""
        from pixiv_app.core.auth import SessionStore
        from pixiv_app.core.paths import app_session_file

        store = SessionStore(app_session_file())
        payload = store.load()
        cloud = payload.get("cloud_sync") if isinstance(payload.get("cloud_sync"), dict) else {}
        self.configure(
            base_url=str(cloud.get("base_url") or ""),
            access_token=str(cloud.get("access_token") or ""),
            refresh_token=str(cloud.get("refresh_token") or ""),
            enabled=bool(cloud.get("enabled", False)),
        )
        return payload

    @property
    def enabled(self) -> bool:
        """云同步是否完全可用(启用 + 有 base_url + 有 access_token)。"""
        return self._enabled and bool(self._base_url) and bool(self._access_token)

    # ── Config 快照 ─────────────────────────────────────────

    def get_config(self) -> CloudSyncConfig:
        """
        返回当前 token 的 CloudSyncConfig 快照。
        若 access_token 即将过期(< 5 分钟),主动触发刷新。
        """
        if self._access_token and self._is_expired_or_near(threshold_seconds=300):
            self.try_refresh()
        return CloudSyncConfig(
            base_url=self._base_url,
            access_token=self._access_token,
            refresh_token=self._refresh_token,
        )

    # ── 监听者管理 ──────────────────────────────────────────

    def add_listener(self, callback: Callable[[str, str], None]) -> None:
        """注册 token 刷新回调(如 GUI 的 _on_cloud_token_refreshed)。"""
        if callback not in self._listeners:
            self._listeners.append(callback)

    def remove_listener(self, callback: Callable[[str, str], None]) -> None:
        try:
            self._listeners.remove(callback)
        except ValueError:
            pass

    def notify_listeners(self, access_token: str, refresh_token: str) -> None:
        """通知所有监听者 token 已更新。"""
        for callback in self._listeners:
            try:
                callback(access_token, refresh_token)
            except Exception:
                logger.exception("CloudSession listener failed")

    # ── Token 刷新(核心) ──────────────────────────────────

    def try_refresh(self) -> bool:
        """
        统一刷新入口。使用全局锁防止并发重复刷新。
        Returns: True=成功, False=失败(token 已清空并通知监听者)
        """
        refresh = self._refresh_token
        if not refresh:
            return False

        with self._refresh_lock:
            refresh = self._refresh_token
            if not refresh:
                return False

            # 距上次刷新不足 5 秒,跳过(防抖)
            elapsed = time.time() - self._last_refresh_time
            if elapsed < 5.0 and self._access_token:
                return True

            try:
                resp = requests.post(
                    f"{self._base_url}/api/v1/auth/refresh",
                    json={"refresh_token": refresh},
                    timeout=30.0,
                )
                if resp.status_code != 200:
                    self._on_refresh_failed()
                    return False

                body = resp.json()
                data = body.get("data", body) if isinstance(body, dict) else {}
                new_access = (data.get("access_token") or "").strip()
                new_refresh = (data.get("refresh_token") or "").strip()

                if not new_access:
                    self._on_refresh_failed()
                    return False

                self._access_token = new_access
                if new_refresh:
                    self._refresh_token = new_refresh
                self._last_refresh_time = time.time()
                self._persist()
                self.notify_listeners(self._access_token, self._refresh_token)
                return True

            except Exception:
                logger.exception("CloudSession refresh error")
                self._on_refresh_failed()
                return False

    def _on_refresh_failed(self) -> None:
        """刷新失败:清空 token + 写盘 + 通知监听者。"""
        self._access_token = ""
        self._refresh_token = ""
        self._last_refresh_time = time.time()
        self._persist()
        self.notify_listeners("", "")

    def _persist(self) -> None:
        try:
            persist_cloud_session_tokens(self._access_token, self._refresh_token)
        except Exception:
            logger.exception("CloudSession persist to disk failed")

    # ── JWT 过期判断 ────────────────────────────────────────

    def _is_expired_or_near(self, threshold_seconds: int = 300) -> bool:
        exp = _decode_jwt_exp(self._access_token)
        if exp <= 0:
            return False
        return (exp - threshold_seconds) <= time.time()

3.2 SakuraCloudClient 的 401 自动重试

文件: pixiv_app/core/cloud_sync.py(SakuraCloudClient 类关键方法)

class SakuraCloudClient:
    def __init__(self, config: CloudSyncConfig, *, cloud_session=None):
        self.config = config
        self.base_url = config.base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({"Authorization": f"Bearer {config.access_token}"})
        self._cloud_session = cloud_session

    def _request(self, method, path, *, json=None, data=None,
                 files=None, _retry_on_401=True) -> requests.Response:
        url = f"{self.base_url}{path}"
        response = self.session.request(
            method, url, json=json, data=data, files=files,
            timeout=self.config.timeout,
        )
        # 401 自动刷新 token 并重试一次
        if response.status_code == 401 and _retry_on_401 and self._try_refresh_token():
            response = self.session.request(
                method, url, json=json, data=data, files=files,
                timeout=self.config.timeout,
            )
        return response

    def _try_refresh_token(self) -> bool:
        """委托给全局 CloudSession 或本地处理 token 刷新。"""
        if self._cloud_session is not None:
            ok = self._cloud_session.try_refresh()
            if ok:
                new_config = self._cloud_session.get_config()
                self.config.access_token = new_config.access_token
                self.config.refresh_token = new_config.refresh_token
                self.session.headers.update(
                    {"Authorization": f"Bearer {new_config.access_token}"}
                )
            return ok

        # 旧路径(向后兼容)
        refresh = self.config.refresh_token.strip()
        if not refresh:
            return False
        # ... POST /api/v1/auth/refresh 并更新本地 config ...

3.3 GUI Token 刷新回调

文件: pixiv_app/gui/app.py

def _on_cloud_token_refreshed(self, new_access: str, new_refresh: str) -> None:
    """
    Token 刷新回调(注册为 CloudSession 监听者)。
    成功:更新 GUI 字段 + 持久化到磁盘。
    失败(空 token):清除状态并提示过期。
    """
    if not new_access:
        self.cloud_access_token = ""
        self.cloud_refresh_token = ""
        self.cloud_sync_enabled_var.set(False)
        self.cloud_status_var.set("云同步会话已过期,请重新登录云端账号")
        return

    self.cloud_access_token = new_access
    if new_refresh:
        self.cloud_refresh_token = new_refresh
    self.cloud_status_var.set("云同步 Token 已自动续期")

    # 写回磁盘
    try:
        payload = self.session_store.load()
        cloud = payload.get("cloud_sync") if isinstance(payload.get("cloud_sync"), dict) else {}
        cloud["access_token"] = new_access
        if new_refresh:
            cloud["refresh_token"] = new_refresh
        payload["cloud_sync"] = cloud
        self.session_store.save(payload)
    except Exception:
        self.save_session()

def cloud_sync_active(self) -> bool:
    """判断云同步是否已完全配置。"""
    config = self.get_cloud_sync_config()
    return bool(config.get("enabled") and config.get("base_url") and config.get("access_token"))

4. 桌面端 (pixiv_app) — X (Twitter) 登录检测

4.1 XAuthManager 登录状态检测

文件: pixiv_app/services/x_auth_manager.py

class XAuthManager:
    """
    基于 Playwright 持久化 Chromium Profile 的 X (Twitter) 会话管理。
    会话自动从磁盘恢复(user_data_dir),登录检测通过 DOM 启发式判断。
    """

    HOME_URL = "https://x.com/home"
    LOGIN_FLOW_HINT = "https://x.com/i/flow/login"

    async def is_logged_in(self, *, page=None, navigate=True) -> bool:
        """
        启发式登录检测(DOM + URL):
        - 访问首页,检查 URL 是否被重定向到登录/注册页
        - 检查已登录特有的 DOM 元素
        - 检查 "Sign in to X" 访客墙文本
        """
        p = page if page is not None else await self.get_page()

        if navigate:
            await p.goto(self.HOME_URL, wait_until="domcontentloaded", timeout=45_000)
            await asyncio.sleep(0.6)

        # 1. URL 检查:在登录/注册页 = 未登录
        url = (p.url or "").lower()
        if any(x in url for x in ("/i/flow/login", "/i/flow/signup", "/login")):
            return False

        # 2. 已登录 DOM 元素检查
        logged_in_selectors = (
            '[data-testid="SideNav_AccountSwitcher_Button"]',
            '[data-testid="AppTabBar_Home_Link"]',
            '[data-testid="primaryColumn"]',
            '[data-testid="tweet"]',
        )
        for sel in logged_in_selectors:
            try:
                el = await p.wait_for_selector(sel, timeout=2500, state="visible")
                if el:
                    return True
            except Exception:
                continue

        # 3. 访客墙检查
        try:
            guest = p.get_by_text("Sign in to X", exact=False)
            if await guest.count() and await guest.first.is_visible(timeout=800):
                return False
        except Exception:
            pass

        return False

    async def session_healthy(self) -> bool:
        """带重试的登录状态检测。"""
        for attempt in range(self._max_health_retries):
            try:
                return await self.is_logged_in()
            except Exception:
                if attempt == self._max_health_retries - 1:
                    raise
        return False

5. 桌面端 (pixiv_app) — 关注同步中的认证

文件: pixiv_app/core/origin_follow_sync.py

def sync_pixiv(self, *, progress=None) -> OriginFollowSyncResult:
    """同步 Pixiv 关注列表到本地和云端。"""
    # 从磁盘读取 Pixiv Cookie
    cookie = str(
        SessionStore(app_session_file()).load().get("cookie", "")
    ).strip()
    if not cookie:
        raise ValueError("Pixiv Cookie 不存在,请先导入或保存 Pixiv 登录态。")

    result = OriginFollowSyncResult(platform="pixiv")
    session = create_session(cookie)
    try:
        # 用 Cookie 识别当前登录用户
        user_id = self._fetch_pixiv_current_user_id(session, cookie)
        follows = self._fetch_pixiv_following(session, cookie, user_id, result)
    finally:
        session.close()
    self._upsert_pixiv_local(follows, result)
    self._sync_cloud(follows, result)  # 使用 CloudSession Token
    return result

def _fetch_pixiv_current_user_id(self, session, cookie: str) -> str:
    """通过 AJAX API 或首页 HTML 提取当前登录用户 ID。"""
    # 尝试 AJAX 接口
    for url in (
        "https://www.pixiv.net/ajax/user/self?lang=zh",
        "https://www.pixiv.net/ajax/user/self",
    ):
        try:
            payload = request_json(session, url, cookie=cookie)
            body = payload.get("body") if isinstance(payload, dict) else {}
            user_id = _first_text(body, "userId", "id")
            if user_id:
                return user_id
        except Exception:
            continue
    # Fallback: 从首页 HTML 提取
    try:
        response = session.get("https://www.pixiv.net/", timeout=30)
        response.raise_for_status()
        match = re.search(
            r'"userData"\s*:\s*\{[^}]*"id"\s*:\s*"?(?P<id>\d+)"?',
            response.text,
        )
        if match:
            return match.group("id")
    except Exception:
        pass
    raise ValueError("Pixiv Cookie 可能已失效:无法识别当前登录账号。")

文件: pixiv_app/services/gallery_api.py

def _handle_cookie_import(self, payload: dict) -> dict:
    """POST /api/cookies/import — WebUI 导入 Cookie"""
    platform = str(payload.get("platform", "")).strip().lower()
    text = str(payload.get("text", ""))

    if platform in {"pixiv", "px"}:
        cookies = parse_cookie_text(text)
        pixiv_cookies = cookies_to_playwright(cookies, ("pixiv.net",))
        header = cookies_to_header(pixiv_cookies, ("pixiv.net",))
        store = SessionStore(app_session_file())
        session_payload = store.load()
        session_payload.update({
            "login_mode": "cookie",
            "cookie": header,
            "cookie_json": pixiv_cookies,
            "login_id": "",
            "saved_at": time.strftime("%Y-%m-%d %H:%M:%S"),
        })
        store.save(session_payload)
        return {"platform": "pixiv", "count": len(pixiv_cookies), ...}

    if platform in {"x", "twitter"}:
        result = self.x_media_service.import_cookie_text(text)
        return result

def _handle_session_status(self) -> dict:
    """GET /api/session/status — 返回当前登录状态"""
    payload = SessionStore(app_session_file()).load()
    cloud = payload.get("cloud_sync") if isinstance(payload.get("cloud_sync"), dict) else {}
    return {
        "pixiv": {
            "has_cookie": bool(pixiv_cookie or cookie_json),
            "saved_at": str(payload.get("saved_at") or ""),
            "login_mode": str(payload.get("login_mode") or ""),
        },
        "cloud": {
            "enabled": bool(cloud.get("enabled")),
            "has_token": bool(str(cloud.get("access_token") or "").strip()),
            "base_url": str(cloud.get("base_url") or "").strip(),
        },
    }

7. 云端 (sakura_cloud) — JWT 安全核心

7.1 JWT 创建与验证 + 密码哈希

文件: sakura_cloud/core/security.py

from datetime import datetime, timedelta, timezone
from typing import Any

from jose import JWTError, jwt
from passlib.context import CryptContext

from sakura_cloud.core.config import settings

# ── 密码哈希 ────────────────────────────────────────────────────

pwd_context = CryptContext(schemes=["pbkdf2_sha256", "bcrypt"], deprecated="auto")

def hash_password(password: str) -> str:
    return pwd_context.hash(password)

def verify_password(password: str, password_hash: str) -> bool:
    return pwd_context.verify(password, password_hash)

# ── JWT 创建 ────────────────────────────────────────────────────

def create_token(
    subject: str, *, token_type: str, expires_delta: timedelta, token_version: int = 0
) -> str:
    """
    创建 JWT Token。
    payload: sub(用户ID), type(access/refresh), tv(token_version 用于即时吊销),
             iss, aud, iat, exp
    """
    now = datetime.now(timezone.utc)
    payload: dict[str, Any] = {
        "sub": subject,
        "type": token_type,
        "tv": token_version,
        "iss": settings.jwt_issuer,
        "aud": settings.jwt_audience,
        "iat": int(now.timestamp()),
        "exp": int((now + expires_delta).timestamp()),
    }
    return jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)

def create_access_token(subject: str, token_version: int = 0) -> str:
    """Access Token: 24 小时有效期"""
    return create_token(
        subject, token_type="access",
        expires_delta=timedelta(hours=settings.jwt_access_token_expire_hours),
        token_version=token_version,
    )

def create_refresh_token(subject: str, token_version: int = 0) -> str:
    """Refresh Token: 30 天有效期"""
    return create_token(
        subject, token_type="refresh",
        expires_delta=timedelta(days=settings.jwt_refresh_token_expire_days),
        token_version=token_version,
    )

# ── JWT 解码与验证 ──────────────────────────────────────────────

def decode_token(token: str) -> dict[str, Any]:
    """
    解码并验证 JWT。
    验证:签名、audience、issuer、exp、type 字段存在且合法。
    """
    try:
        payload = jwt.decode(
            token,
            settings.jwt_secret_key,
            algorithms=[settings.jwt_algorithm],
            audience=settings.jwt_audience,
            issuer=settings.jwt_issuer,
        )
    except JWTError as exc:
        raise ValueError("Invalid token") from exc
    if "exp" not in payload:
        raise ValueError("Invalid token")
    if payload.get("type") not in {"access", "refresh"}:
        raise ValueError("Invalid token")
    return payload

8. 云端 (sakura_cloud) — 认证依赖注入

8.1 get_current_user 认证守卫

文件: sakura_cloud/api/deps.py

from typing import Annotated
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from sqlalchemy.orm import Session

from sakura_cloud.core.config import settings
from sakura_cloud.core.security import decode_token
from sakura_cloud.db.session import get_db
from sakura_cloud.models.user import User, UserRole

# OAuth2 方案:Bearer Token 从 Authorization header 提取
oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.api_prefix}/auth/login")
DbSession = Annotated[Session, Depends(get_db)]


def get_current_user(token: Annotated[str, Depends(oauth2_scheme)], db: DbSession) -> User:
    """
    核心认证守卫。验证链:
    1. 解码 JWT → 2. 验证 type=="access" → 3. 验证 sub 存在
    → 4. 查用户存在 → 5. 验证 is_active → 6. 验证 token_version 匹配
    """
    try:
        payload = decode_token(token)
    except ValueError as exc:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token"
        ) from exc

    if payload.get("type") != "access":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token type"
        )

    user_id = payload.get("sub")
    if not user_id:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token subject"
        )

    user = db.get(User, str(user_id))
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found"
        )
    if not user.is_active:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="User is disabled"
        )

    # token_version 不匹配 = Token 已被吊销
    if int(payload.get("tv") or 0) != int(user.token_version or 0):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Token has been revoked"
        )
    return user


# 类型别名
CurrentUser = Annotated[User, Depends(get_current_user)]


# ── 角色守卫 ────────────────────────────────────────────────────

def require_admin_user(current_user: CurrentUser) -> User:
    if current_user.role not in {UserRole.ADMIN, UserRole.SUPER_ADMIN}:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN, detail="Admin privileges required"
        )
    return current_user

AdminUser = Annotated[User, Depends(require_admin_user)]


def require_super_admin_user(current_user: CurrentUser) -> User:
    if current_user.role != UserRole.SUPER_ADMIN:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Super admin privileges required",
        )
    return current_user

SuperAdminUser = Annotated[User, Depends(require_super_admin_user)]


def assert_owner_or_admin(resource_user_id: str, current_user: User) -> None:
    """资源所有者或管理员可访问。"""
    if resource_user_id == current_user.id:
        return
    if current_user.role in {UserRole.ADMIN, UserRole.SUPER_ADMIN}:
        return
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND, detail="Resource not found"
    )

9. 云端 (sakura_cloud) — 认证 API 端点

9.1 注册 / 登录 / 登出 / 刷新

文件: sakura_cloud/api/v1/endpoints/auth.py

from time import monotonic
from fastapi import APIRouter, HTTPException, Request, status
from sqlalchemy import func, or_, select

from sakura_cloud.api.deps import CurrentUser, DbSession
from sakura_cloud.core.security import (
    create_access_token, create_refresh_token,
    decode_token, hash_password, verify_password,
)
from sakura_cloud.models.user import User
from sakura_cloud.schemas.auth import (
    LoginRequest, RefreshRequest, RegisterRequest, TokenPair,
)
from sakura_cloud.schemas.common import ApiResponse
from sakura_cloud.schemas.user import UserOut

router = APIRouter()
_rate_buckets: dict[str, list[float]] = {}


# ── 简易内存速率限制 ─────────────────────────────────────────

def _rate_limit(request: Request, scope: str, *, limit=5, window_seconds=60) -> None:
    client_ip = request.client.host if request.client else "unknown"
    key = f"{scope}:{client_ip}"
    now = monotonic()
    bucket = [t for t in _rate_buckets.get(key, []) if now - t < window_seconds]
    if len(bucket) >= limit:
        _rate_buckets[key] = bucket
        raise HTTPException(
            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
            detail="Too many requests",
        )
    bucket.append(now)
    _rate_buckets[key] = bucket


# ── POST /auth/register ─────────────────────────────────────

@router.post("/register", response_model=ApiResponse[UserOut],
             status_code=status.HTTP_201_CREATED)
def register(payload: RegisterRequest, request: Request, db: DbSession):
    """注册新用户。无需认证。速率限制:5次/60秒。"""
    _rate_limit(request, "register")
    username = payload.username.strip()
    email = str(payload.email).strip().lower()

    # 检查用户名 / 邮箱唯一性
    exists = db.scalar(
        select(User).where(
            or_(
                func.lower(User.username) == username.lower(),
                func.lower(User.email) == email,
            )
        )
    )
    if exists is not None:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT, detail="注册失败,请检查输入"
        )

    user = User(
        username=username, email=email,
        password_hash=hash_password(payload.password),
    )
    db.add(user)
    db.commit()
    db.refresh(user)
    return ApiResponse(code=201, message="created", data=UserOut.model_validate(user))


# ── POST /auth/login ────────────────────────────────────────

@router.post("/login", response_model=ApiResponse[TokenPair])
def login(payload: LoginRequest, request: Request, db: DbSession):
    """
    用户登录。无需认证。速率限制:5次/60秒。
    成功登录会递增 token_version,使所有旧 Token 立即失效。
    """
    _rate_limit(request, "login")
    login_id = payload.username_or_email.strip()

    # 支持用户名或邮箱登录
    user = db.scalar(
        select(User).where(
            or_(
                func.lower(User.username) == login_id.lower(),
                func.lower(User.email) == login_id.lower(),
            )
        )
    )
    if user is None or not verify_password(payload.password, user.password_hash):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials"
        )

    # 递增 token_version → 吊销所有旧 Token
    user.token_version += 1
    db.commit()
    db.refresh(user)

    tokens = TokenPair(
        access_token=create_access_token(user.id, user.token_version),
        refresh_token=create_refresh_token(user.id, user.token_version),
    )
    return ApiResponse(data=tokens)


# ── POST /auth/logout ───────────────────────────────────────

@router.post("/logout", response_model=ApiResponse[dict[str, bool]])
def logout(current_user: CurrentUser, db: DbSession):
    """
    登出。需要认证。
    递增 token_version → 使所有 Token 立即失效。
    """
    current_user.token_version += 1
    db.commit()
    return ApiResponse(data={"ok": True})


# ── POST /auth/refresh ──────────────────────────────────────

@router.post("/refresh", response_model=ApiResponse[TokenPair])
def refresh(payload: RefreshRequest, request: Request, db: DbSession):
    """
    Token 刷新。无需 Access Token,使用 Refresh Token。
    成功刷新会旋转 Token(递增 token_version),旧 Refresh Token 一次性失效。
    """
    _rate_limit(request, "refresh")

    # 1. 解码并验证 Refresh Token
    try:
        token_payload = decode_token(payload.refresh_token)
    except ValueError as exc:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token"
        ) from exc

    if token_payload.get("type") != "refresh":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token type"
        )

    # 2. 验证用户
    user_id = token_payload.get("sub")
    user = db.get(User, str(user_id)) if user_id else None
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found"
        )
    if not user.is_active:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="User is disabled"
        )

    # 3. 验证 token_version(Refresh Token 是否已被吊销)
    if int(token_payload.get("tv") or 0) != int(user.token_version or 0):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Token has been revoked"
        )

    # 4. 旋转 Token
    user.token_version += 1
    db.commit()
    db.refresh(user)

    tokens = TokenPair(
        access_token=create_access_token(user.id, user.token_version),
        refresh_token=create_refresh_token(user.id, user.token_version),
    )
    return ApiResponse(data=tokens)

10. 云端 (sakura_cloud) — 管理员登录

10.1 POST /admin/login

文件: sakura_cloud/api/v1/endpoints/admin.py

from collections import defaultdict, deque

router = APIRouter()
_login_attempts: dict[str, deque[float]] = defaultdict(deque)


def _check_login_rate_limit(request: Request) -> None:
    """管理员登录速率限制。"""
    key = request.client.host if request.client is not None else "unknown"
    now = time.time()
    attempts = _login_attempts[key]
    while attempts and now - attempts[0] > 60:
        attempts.popleft()
    if len(attempts) >= settings.admin_login_rate_limit_per_minute:
        raise HTTPException(
            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
            detail="Too many requests",
        )
    attempts.append(now)


@router.post("/login", response_model=ApiResponse[TokenPair])
def admin_login(payload: AdminLoginRequest, request: Request, db: DbSession):
    """
    管理员登录。无需认证。
    额外检查:用户角色必须是 ADMIN 或 SUPER_ADMIN。
    """
    _check_login_rate_limit(request)
    login_id = payload.username_or_email.strip()
    user = db.scalar(
        select(User).where(
            or_(
                func.lower(User.username) == login_id.lower(),
                func.lower(User.email) == login_id.lower(),
            )
        )
    )
    # 四项校验:用户存在 + 是管理员 + 账号启用 + 密码正确
    if (
        user is None
        or user.role not in {UserRole.ADMIN, UserRole.SUPER_ADMIN}
        or not user.is_active
        or not verify_password(payload.password, user.password_hash)
    ):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid admin credentials"
        )

    # 吊销旧 Token + 签发新 Token
    user.token_version += 1
    db.commit()
    db.refresh(user)

    # 记录审计日志
    write_admin_audit_log(
        db, user, action="admin_login", target_type="user",
        target_id=user.id, request=request,
    )

    return ApiResponse(data=TokenPair(
        access_token=create_access_token(user.id, user.token_version),
        refresh_token=create_refresh_token(user.id, user.token_version),
    ))

11. 云端 (sakura_cloud) — 数据模型 & 请求模型

11.1 User 模型(认证相关字段)

文件: sakura_cloud/models/user.py

class UserRole(str, Enum):
    ADMIN = "admin"
    SUPER_ADMIN = "super_admin"
    USER = "user"

class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
    __tablename__ = "users"

    username: Mapped[str]          # 用户名 (unique)
    email: Mapped[str]             # 邮箱 (unique)
    password_hash: Mapped[str]     # 密码哈希
    role: Mapped[UserRole]         # 角色 (USER/ADMIN/SUPER_ADMIN)
    is_active: Mapped[bool]        # 账号启用状态 (默认 True)
    token_version: Mapped[int]     # Token 版本号 (用于即时吊销, 默认 0)
    # ... 其他字段省略

11.2 认证请求/响应 Schema

文件: sakura_cloud/schemas/auth.py

from pydantic import BaseModel, EmailStr, Field, field_validator

class RegisterRequest(BaseModel):
    username: str = Field(min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(min_length=8, max_length=128)

    @field_validator("username", mode="before")
    @classmethod
    def normalize_username(cls, value: str) -> str:
        return value.strip() if isinstance(value, str) else value

    @field_validator("email", mode="before")
    @classmethod
    def normalize_email(cls, value: object) -> object:
        return value.strip().lower() if isinstance(value, str) else value


class LoginRequest(BaseModel):
    username_or_email: str
    password: str

    @field_validator("username_or_email", mode="before")
    @classmethod
    def normalize_login_id(cls, value: str) -> str:
        return value.strip() if isinstance(value, str) else value


class RefreshRequest(BaseModel):
    refresh_token: str


class TokenPair(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"

12. 手机端 (sakura_mobile) — Flutter 认证

12.1 会话状态与控制器

文件: sakura_mobile/lib/src/core/session.dart

import 'package:dio/dio.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:shared_preferences/shared_preferences.dart';

import 'api_client.dart';
import 'push_notifications.dart';

// ── 会话状态 ──────────────────────────────────────────────────

class SessionState {
  final String baseUrl;
  final String accessToken;
  final String username;
  final bool loading;
  final String? error;

  const SessionState({
    required this.baseUrl,
    required this.accessToken,
    this.username = '',
    this.loading = false,
    this.error,
  });

  /// 核心登录状态判断:accessToken 非空即视为已登录
  bool get signedIn => accessToken.isNotEmpty;

  SessionState copyWith({...}) { ... }
}

// ── 会话控制器 ────────────────────────────────────────────────

class SessionController extends StateNotifier<SessionState> {
  SessionController()
      : super(const SessionState(
            baseUrl: defaultCloudApi, accessToken: '', loading: true)) {
    _load();
  }

  // SharedPreferences 存储键
  static const _baseUrlKey = 'sakura.baseUrl';
  static const _accessTokenKey = 'sakura.accessToken';
  static const _usernameKey = 'sakura.username';

  // ── 启动时加载会话 ───────────────────────────────────────

  Future<void> _load() async {
    final prefs = await SharedPreferences.getInstance();
    final baseUrl = prefs.getString(_baseUrlKey) ?? defaultCloudApi;
    final accessToken = prefs.getString(_accessTokenKey) ?? '';
    final username = prefs.getString(_usernameKey) ?? '';

    // 验证存储的 Token 是否仍然有效
    final validatedUsername = await _validateStoredSession(
      baseUrl: baseUrl, accessToken: accessToken, username: username,
    );

    state = SessionState(
      baseUrl: baseUrl,
      accessToken: validatedUsername == null ? '' : accessToken,
      username: validatedUsername ?? '',
    );

    if (state.signedIn) {
      await PushNotifications.registerWithSession(
        baseUrl: state.baseUrl, accessToken: state.accessToken,
      );
    }
  }

  SakuraApiClient client() =>
      SakuraApiClient(baseUrl: state.baseUrl, token: state.accessToken);

  // ── 登录 ─────────────────────────────────────────────────

  Future<void> login(String usernameOrEmail, String password) async {
    state = state.copyWith(loading: true, error: null);
    try {
      // 1. 调用登录 API
      final api = SakuraApiClient(baseUrl: state.baseUrl);
      final tokens = await api.login(usernameOrEmail, password);
      final accessToken = tokens['access_token']?.toString() ?? '';

      // 2. 清除旧认证信息
      final prefs = await SharedPreferences.getInstance();
      await _clearAuthPrefs(prefs);

      // 3. 用新 Token 获取当前用户信息
      final authedApi = SakuraApiClient(
          baseUrl: state.baseUrl, token: accessToken);
      final me = await authedApi.me();
      final username = me['username']?.toString() ?? '';

      if (username.isEmpty) {
        throw Exception('登录成功但无法获取用户身份信息。');
      }

      // 4. 持久化到 SharedPreferences
      await prefs.setString(_accessTokenKey, accessToken);
      await prefs.setString(_usernameKey, username);

      state = state.copyWith(
        accessToken: accessToken, username: username,
        loading: false, error: null,
      );

      // 5. 注册推送通知
      await PushNotifications.registerWithSession(
        baseUrl: state.baseUrl, accessToken: accessToken,
      );
    } catch (error) {
      state = state.copyWith(loading: false, error: _friendlyError(error));
    }
  }

  // ── 注册 ─────────────────────────────────────────────────

  Future<void> register(String username, String email, String password) async {
    state = state.copyWith(loading: true, error: null);
    try {
      final api = SakuraApiClient(baseUrl: state.baseUrl);
      await api.register(username, email, password);
      state = state.copyWith(loading: false, error: null);
    } catch (error) {
      state = state.copyWith(loading: false, error: _friendlyError(error));
      rethrow;
    }
  }

  // ── 登出 ─────────────────────────────────────────────────

  Future<void> logout() async {
    await PushNotifications.unregisterWithSession(
      baseUrl: state.baseUrl, accessToken: state.accessToken,
    );
    final prefs = await SharedPreferences.getInstance();
    await _clearAuthPrefs(prefs);
    state = state.copyWith(accessToken: '', username: '', error: null);
  }

  // ── 验证存储的会话(启动时调用) ──────────────────────────

  Future<String?> _validateStoredSession({
    required String baseUrl,
    required String accessToken,
    required String username,
  }) async {
    if (accessToken.isEmpty) return null;

    final prefs = await SharedPreferences.getInstance();
    if (username.isEmpty) {
      await _clearAuthPrefs(prefs);
      return null;
    }

    try {
      // 调用 /api/v1/users/me 验证 Token 是否仍然有效
      final api = SakuraApiClient(baseUrl: baseUrl, token: accessToken);
      final me = await api.me();
      final actualUsername = me['username']?.toString() ?? '';

      if (actualUsername.isEmpty || actualUsername != username) {
        await _clearAuthPrefs(prefs);
        return null;
      }
      return actualUsername;
    } catch (_) {
      // 任何异常(网络错误、401 等)都清除认证状态
      await _clearAuthPrefs(prefs);
      return null;
    }
  }

  Future<void> _clearAuthPrefs(SharedPreferences prefs) async {
    await prefs.remove(_accessTokenKey);
    await prefs.remove(_usernameKey);
  }
}

12.2 API 客户端(Token 管理与登录接口)

文件: sakura_mobile/lib/src/core/api_client.dart

import 'package:dio/dio.dart';

const defaultCloudApi = 'http://api.kunkunxiaomao.top:8000';

class SakuraApiClient {
  SakuraApiClient({String baseUrl = defaultCloudApi, String token = ''})
      : dio = Dio(BaseOptions(
            baseUrl: baseUrl,
            connectTimeout: const Duration(seconds: 12),
            receiveTimeout: const Duration(seconds: 30),
          )) {
    if (token.isNotEmpty) {
      setToken(token);
    }
  }

  final Dio dio;

  // ── Token 管理 ─────────────────────────────────────────────

  String get token {
    final value = dio.options.headers['Authorization']?.toString() ?? '';
    return value.startsWith('Bearer ') ? value.substring(7) : '';
  }

  void setToken(String token) {
    if (token.isEmpty) {
      dio.options.headers.remove('Authorization');
    } else {
      dio.options.headers['Authorization'] = 'Bearer $token';
    }
  }

  Map<String, String> authHeaders() {
    final value = dio.options.headers['Authorization']?.toString();
    return value == null || value.isEmpty
        ? const {}
        : {'Authorization': value};
  }

  // ── 认证 API ────────────────────────────────────────────────

  /// POST /api/v1/auth/login
  Future<Map<String, dynamic>> login(
      String usernameOrEmail, String password) async {
    final response = await dio.post(
      '/api/v1/auth/login',
      data: {'username_or_email': usernameOrEmail, 'password': password},
    );
    return response.data['data'] as Map<String, dynamic>;
  }

  /// POST /api/v1/auth/register
  Future<Map<String, dynamic>> register(
      String username, String email, String password) async {
    final response = await dio.post(
      '/api/v1/auth/register',
      data: {'username': username, 'email': email, 'password': password},
    );
    return response.data['data'] as Map<String, dynamic>;
  }

  /// GET /api/v1/users/me — 获取当前用户信息
  Future<Map<String, dynamic>> me() async { ... }
}

12.3 Riverpod 依赖注入

文件: sakura_mobile/lib/src/core/providers.dart

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'api_client.dart';
import 'session.dart';

// 全局会话状态
final sessionProvider =
    StateNotifierProvider<SessionController, SessionState>(
        (ref) => SessionController());

// API 客户端(随 sessionProvider 变化自动重建)
final apiClientProvider = Provider<SakuraApiClient>((ref) {
  ref.watch(sessionProvider);
  return ref.read(sessionProvider.notifier).client();
});

12.4 登录页面

文件: sakura_mobile/lib/src/pages/login_page.dart

class LoginPage extends ConsumerStatefulWidget { ... }

class _LoginPageState extends ConsumerState<LoginPage>
    with SingleTickerProviderStateMixin {
  // 登录/注册表单提交
  Future<void> _submitLogin() async {
    final loginId = account.text.trim();
    final pwd = password.text;
    if (loginId.isEmpty || pwd.isEmpty) {
      _showMessage('请输入账号和密码。', isError: true);
      return;
    }
    final notifier = ref.read(sessionProvider.notifier);
    notifier.clearError();
    await notifier.login(loginId, pwd);
  }

  Future<void> _submitRegister() async {
    // ... 校验用户名/邮箱/密码 ...
    await notifier.register(username, email, pwd);
    // 注册成功 → 切换到登录标签页
    _tabController.animateTo(0);
  }
}

12.5 首页认证守卫

文件: sakura_mobile/lib/src/pages/home_page.dart

@override
Widget build(BuildContext context) {
  final session = ref.watch(sessionProvider);

  // 加载中 → 显示加载指示器
  if (session.loading) {
    return const Scaffold(
        body: Center(child: CircularProgressIndicator()));
  }

  // 未登录 → 显示登录页
  if (!session.signedIn) {
    return const LoginPage();
  }

  // 已登录 → 显示主界面
  return Scaffold(body: SafeArea(child: AnimatedSwitcher(...)));
}

13. 管理后台 (sakura_admin_web) — Vue 认证

13.1 会话状态管理

文件: sakura_admin_web/src/stores/session.ts

import { reactive } from "vue";

export type Role = "user" | "admin" | "super_admin";

export interface CurrentUser {
  id: string;
  username: string;
  email: string;
  role: Role;
  is_active: boolean;
  storage_used: number;
  storage_limit: number;
}

const ACCESS_KEY = "sakura_access_token";
const REFRESH_KEY = "sakura_refresh_token";

// 响应式认证状态(初始值从 sessionStorage 读取)
export const authState = reactive({
  accessToken: sessionStorage.getItem(ACCESS_KEY) || "",
  refreshToken: sessionStorage.getItem(REFRESH_KEY) || "",
  user: null as CurrentUser | null,
  loading: false,
});

export function saveSession(accessToken: string, refreshToken: string) {
  authState.accessToken = accessToken;
  authState.refreshToken = refreshToken;
  sessionStorage.setItem(ACCESS_KEY, accessToken);
  sessionStorage.setItem(REFRESH_KEY, refreshToken);
}

export function clearSession() {
  authState.accessToken = "";
  authState.refreshToken = "";
  authState.user = null;
  sessionStorage.removeItem(ACCESS_KEY);
  sessionStorage.removeItem(REFRESH_KEY);
}

13.2 认证操作(登录/注册/登出/加载用户)

文件: sakura_admin_web/src/stores/auth.ts

import { apiData, http } from "../api/http";
import { authState, clearSession, saveSession,
         type CurrentUser, type Role } from "./session";

export { authState, clearSession, saveSession };

/** 登录(普通用户 / 管理员) */
export async function login(
    usernameOrEmail: string, password: string, admin = false) {
  const path = admin ? "/admin/login" : "/auth/login";
  const response = await http.post(path, {
    username_or_email: usernameOrEmail, password,
  });
  const tokens = apiData<{ access_token: string; refresh_token: string }>(response);
  saveSession(tokens.access_token, tokens.refresh_token);
  await loadMe();
}

/** 注册后自动登录 */
export async function register(
    username: string, email: string, password: string) {
  await http.post("/auth/register", { username, email, password });
  await login(username, password);
}

/** 加载当前用户信息(GET /me) */
export async function loadMe(force = false) {
  if (authState.user && !force) return authState.user;
  if (!authState.accessToken) return null;
  authState.loading = true;
  try {
    const response = await http.get("/me");
    authState.user = apiData<CurrentUser>(response);
    return authState.user;
  } finally {
    authState.loading = false;
  }
}

/** 登出 */
export async function logout() {
  try {
    await http.post("/auth/logout");
  } finally {
    clearSession();
  }
}

export function isAdmin(role?: Role | null) {
  return role === "admin" || role === "super_admin";
}

13.3 HTTP 拦截器(自动 Bearer Token + 401 刷新)

文件: sakura_admin_web/src/api/http.ts

import axios, { type AxiosError } from "axios";
import { authState, clearSession, saveSession } from "../stores/session";

const API_BASE = import.meta.env.VITE_API_BASE_URL || "/api/v1";

export const http = axios.create({
  baseURL: API_BASE,
  timeout: 15000,
  withCredentials: false,
});

// ── 请求拦截器:自动附加 Bearer Token ──────────────────────────

http.interceptors.request.use((config) => {
  if (authState.accessToken) {
    config.headers.Authorization = `Bearer ${authState.accessToken}`;
  }
  return config;
});

// ── 响应拦截器:401 自动刷新 Token 并重试 ─────────────────────

let refreshing: Promise<void> | null = null;

http.interceptors.response.use(
  (response) => response,
  async (error: AxiosError) => {
    const original = error.config;
    if (
      !original ||
      error.response?.status !== 401 ||
      !authState.refreshToken ||
      original.headers?.["X-Retry"]
    ) {
      throw error;  // 不满足刷新条件,直接抛出
    }

    // 防止并发重复刷新
    refreshing ||= http
      .post("/auth/refresh",
        { refresh_token: authState.refreshToken },
        { headers: { "X-Retry": "1" } }
      )
      .then((response) => {
        const tokens = response.data?.data;
        saveSession(tokens.access_token, tokens.refresh_token);
      })
      .catch((refreshError) => {
        clearSession();  // 刷新失败 → 清除登录态
        throw refreshError;
      })
      .finally(() => {
        refreshing = null;
      });

    await refreshing;

    // 用新 Token 重试原始请求
    original.headers = {
      ...(original.headers as Record<string, string>),
      Authorization: `Bearer ${authState.accessToken}`,
      "X-Retry": "1",
    } as any;
    return http(original);
  }
);

export function apiData<T>(response: { data: { data: T } }): T {
  return response.data.data;
}

13.4 路由守卫

文件: sakura_admin_web/src/router/index.ts

import { createRouter, createWebHistory } from "vue-router";
import { authState, isAdmin, loadMe } from "../stores/auth";

const PUBLIC_PATHS = new Set([
  "/login", "/register", "/forgot-password", "/403", "/404",
]);

function isPublicPath(path: string) {
  return PUBLIC_PATHS.has(path);
}

router.beforeEach(async (to) => {
  // 公开页面:如果已有 Token,尝试加载用户后重定向
  if (isPublicPath(to.path)) {
    if ((to.path === "/login" || to.path === "/register")
        && authState.accessToken) {
      const user = await loadMe().catch(() => null);
      if (user) return isAdmin(user.role) ? "/admin" : "/app";
    }
    return true;
  }

  // 非公开页面:不需要认证则放行
  if (!to.meta.requiresAuth) return true;

  // 需要认证:加载用户信息
  const user = await loadMe().catch(() => null);
  if (!user) {
    // 未认证 → 重定向到登录页
    return { path: "/login", query: { redirect: to.fullPath } };
  }

  // 需要管理员权限
  if (to.meta.requiresAdmin && !isAdmin(authState.user?.role)) {
    return "/403";
  }

  return true;
});

13.5 登录页面

文件: sakura_admin_web/src/views/public/LoginPage.vue

<template>
  <main class="auth-shell">
    <section class="auth-panel">
      <p class="eyebrow">Sakura Cloud</p>
      <h1>登录</h1>
      <form @submit.prevent="submit">
        <label>
          账号或邮箱
          <input v-model.trim="form.username" autocomplete="username" required />
        </label>
        <label>
          密码
          <input v-model="form.password" type="password"
                 autocomplete="current-password" required />
        </label>
        <label class="row small">
          <input v-model="form.admin" type="checkbox" />
          管理员登录
        </label>
        <button class="primary" :disabled="loading">
          {{ loading ? "登录中..." : "登录" }}
        </button>
      </form>
      <p v-if="error" class="error">{{ error }}</p>
      <nav class="auth-links">
        <RouterLink to="/register">注册账号</RouterLink>
        <RouterLink to="/forgot-password">忘记密码</RouterLink>
      </nav>
    </section>
  </main>
</template>

<script setup lang="ts">
import { reactive, ref } from "vue";
import { useRoute, useRouter } from "vue-router";
import { authState, isAdmin, login } from "../../stores/auth";

const router = useRouter();
const route = useRoute();
const loading = ref(false);
const error = ref("");
const form = reactive({ username: "", password: "", admin: false });

async function submit() {
  error.value = "";
  loading.value = true;
  try {
    await login(form.username, form.password, form.admin);
    const redirect = String(route.query.redirect || "");
    await router.push(
      redirect || (isAdmin(authState.user?.role) ? "/admin" : "/app")
    );
  } catch {
    error.value = "账号、密码或权限不正确";
  } finally {
    loading.value = false;
  }
}
</script>

14. 认证流程总结

14.1 Pixiv 认证(桌面端)

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ Cookie 导入   │────▶│ validate_cookie │────▶│ 访问设置页验证     │
│ (cookies.txt) │     │ (AuthClient)    │     │ 是否被重定向       │
└──────────────┘     └─────────────────┘     └──────────────────┘
                             │                        │
                     ┌───────┴───────┐        ┌──────┴──────┐
                     │ 有效 → 保存    │        │ 失效 → 提示  │
                     │ SessionStore  │        │ 重新导入     │
                     └───────────────┘        └─────────────┘

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ 密码登录       │────▶│ 提取 CSRF Token │────▶│ POST 登录 AJAX   │
│               │     │ (_extract_tt)  │     │ + 提取 Cookie    │
└──────────────┘     └─────────────────┘     └──────────────────┘

14.2 Sakura Cloud JWT 认证(全平台)

┌─────────────────────────────────────────────────────────────────┐
│                        Token 生命周期                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  注册                 登录                  使用                   │
│  POST /register ──▶ POST /login ──▶ 返回 TokenPair               │
│                     token_version++      access_token (24h)      │
│                                           refresh_token (30d)    │
│                                                │                 │
│                    ┌───────────────────────────┘                 │
│                    ▼                                             │
│              每次 API 请求                                        │
│              Authorization: Bearer <access_token>                │
│                    │                                             │
│                    ▼                                             │
│              get_current_user()                                  │
│              1. decode_token()        — 验证签名/过期             │
│              2. type == "access"      — 验证 Token 类型           │
│              3. user exists           — 验证用户存在              │
│              4. user.is_active        — 验证账号启用              │
│              5. tv == user.token_version — 验证未吊销            │
│                    │                                             │
│          ┌────────┴────────┐                                     │
│          ▼                 ▼                                     │
│       通过               401/过期                                 │
│                          │                                       │
│                          ▼                                       │
│                    POST /refresh                                 │
│                    token_version++                               │
│                    返回新 TokenPair                               │
│                                                                  │
│  登出 / 改密码 / 管理员操作 → token_version++ → 所有旧 Token 失效  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

14.3 桌面端 Cloud Token 管理流程

GUI 启动
  │
  ▼
load_saved_session()  ← 从 pixiv_app_session.json 读取
  │
  ▼
CloudSession().configure(...)  ← 同步到全局单例
  │
  ▼
CloudSession().add_listener(_on_cloud_token_refreshed)
  │
  ▼
每次创建 SakuraCloudClient 时:
  │
  ├─ CloudSession.get_config()
  │    └─ access_token 临近过期 (< 5min)?
  │         └─ YES → try_refresh()
  │
  ├─ API 请求返回 401?
  │    └─ YES → SakuraCloudClient._try_refresh_token()
  │              └─ 委托给 CloudSession.try_refresh()
  │                   ├─ 成功 → 更新内存 + 写盘 + 通知 GUI
  │                   └─ 失败 → 清空 token + 通知 GUI "已过期"

14.4 各平台 Token 存储方式

平台 存储方式 存储内容
桌面端 (Python) pixiv_app_session.json Pixiv Cookie + Cloud JWT Token Pair + 登录模式
云端 (FastAPI) 无状态(JWT 自包含) Token 内嵌 user_id, token_version, exp
手机端 (Flutter) SharedPreferences sakura.accessToken + sakura.username
管理后台 (Vue) sessionStorage sakura_access_token + sakura_refresh_token

14.5 Token 刷新机制对比

平台 刷新方式 触发条件
桌面端 CloudSession 主动检查 JWT exp 即将过期(< 5min)或 API 返回 401
桌面端 SakuraCloudClient 被动响应 401 API 返回 401
手机端 (Flutter) 无自动刷新 启动时验证,失败则跳转登录页
管理后台 (Vue) Axios 响应拦截器 API 返回 401 + 有 refreshToken
云端 API POST /auth/refresh 客户端主动调用