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

2242 lines
80 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Sakura 项目 — 登录与认证状态验证 完整文档
> 本文档汇总项目所有模块(桌面端、云端、手机端、管理后台)中**登录相关**和**验证登录状态**的代码。
> 不包括:下载器、画廊、插件系统、代理池等非认证逻辑。
---
## 目录
1. [架构总览](#1-架构总览)
2. [桌面端 (pixiv_app) — Pixiv 登录 & Cookie 管理](#2-桌面端-pixiv_app--pixiv-登录--cookie-管理)
3. [桌面端 (pixiv_app) — Sakura Cloud Token 管理](#3-桌面端-pixiv_app--sakura-cloud-token-管理)
4. [桌面端 (pixiv_app) — X (Twitter) 登录检测](#4-桌面端-pixiv_app--x-twitter-登录检测)
5. [桌面端 (pixiv_app) — 关注同步中的认证](#5-桌面端-pixiv_app--关注同步中的认证)
6. [桌面端 (pixiv_app) — Gallery API 中的认证接口](#6-桌面端-pixiv_app--gallery-api-中的认证接口)
7. [云端 (sakura_cloud) — JWT 安全核心](#7-云端-sakura_cloud--jwt-安全核心)
8. [云端 (sakura_cloud) — 认证依赖注入](#8-云端-sakura_cloud--认证依赖注入)
9. [云端 (sakura_cloud) — 认证 API 端点](#9-云端-sakura_cloud--认证-api-端点)
10. [云端 (sakura_cloud) — 管理员登录](#10-云端-sakura_cloud--管理员登录)
11. [云端 (sakura_cloud) — 数据模型 & 请求模型](#11-云端-sakura_cloud--数据模型--请求模型)
12. [手机端 (sakura_mobile) — Flutter 认证](#12-手机端-sakura_mobile--flutter-认证)
13. [管理后台 (sakura_admin_web) — Vue 认证](#13-管理后台-sakura_admin_web--vue-认证)
14. [认证流程总结](#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. 桌面端 (pixiv_app) — Pixiv 登录 & Cookie 管理
### 2.1 核心认证客户端
**文件:** `pixiv_app/core/auth.py`
```python
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`(关键方法摘录)
```python
# ── 类成员变量(__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` 方法摘要)
```python
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`
```python
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` 类关键方法)
```python
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`
```python
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`
```python
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) — 关注同步中的认证
### 5.1 Pixiv 关注同步使用 Cookie 验证身份
**文件:** `pixiv_app/core/origin_follow_sync.py`
```python
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 可能已失效:无法识别当前登录账号。")
```
---
## 6. 桌面端 (pixiv_app) — Gallery API 中的认证接口
### 6.1 WebUI 的 Cookie 导入 & 会话状态 API
**文件:** `pixiv_app/services/gallery_api.py`
```python
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`
```python
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`
```python
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`
```python
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`
```python
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`
```python
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`
```python
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`
```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`
```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`
```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`
```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`
```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`
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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`
```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 | 客户端主动调用 |