# 云同步 401 自动刷新 Token 修复 **日期**: 2026-06-22 **问题**: 桌面端 `POST /api/v1/sync/check` 持续返回 401,无重试/续期机制 **根因**: `CloudSyncConfig` 只存 `access_token`,无 `refresh_token` 和自动续期逻辑 --- ## 修改文件清单 | 文件 | 改动类型 | |------|----------| | `pixiv_app/core/cloud_sync.py` | 核心:加 refresh_token、401 自动刷新、token 更新回调 | | `pixiv_app/gui/app.py` | 存储/加载/传递 refresh_token,回调持久化 | | `pixiv_app/core/gallery_service.py` | 传递 refresh_token | | `pixiv_app/core/origin_follow_sync.py` | 传递 refresh_token | | `pixiv_app/core/x_media_service.py` | 传递 refresh_token | --- ## 改动详情 ### 1. `pixiv_app/core/cloud_sync.py` #### 1.1 `CloudSyncConfig` — 加 `refresh_token` 字段 **改动前**: ```python @dataclass class CloudSyncConfig: base_url: str access_token: str chunk_size: int = 5 * 1024 * 1024 timeout: float = 60.0 ``` **改动后**: ```python @dataclass class CloudSyncConfig: base_url: str access_token: str refresh_token: str = "" chunk_size: int = 5 * 1024 * 1024 timeout: float = 60.0 ``` #### 1.2 `SakuraCloudClient.__init__` — 加 `on_token_refreshed` 回调 **改动前**: ```python class SakuraCloudClient: def __init__(self, config: CloudSyncConfig) -> 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}"}) ``` **改动后**: ```python class SakuraCloudClient: def __init__(self, config: CloudSyncConfig, *, on_token_refreshed: callable | None = None) -> 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._on_token_refreshed = on_token_refreshed self._refresh_lock = False # 防止并发刷新 ``` #### 1.3 `_post` — 加 401 自动刷新 + 重试 **改动前**: ```python def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]: response = self.session.post(f"{self.base_url}{path}", json=payload, timeout=self.config.timeout) return self._unwrap(response) ``` **改动后**: ```python def _post(self, path: str, payload: dict[str, Any], *, _retry_on_401: bool = True) -> dict[str, Any]: response = self.session.post(f"{self.base_url}{path}", json=payload, timeout=self.config.timeout) if response.status_code == 401 and _retry_on_401: refreshed = self._try_refresh_token() if refreshed: return self._post(path, payload, _retry_on_401=False) return self._unwrap(response) ``` #### 1.4 新增 `_try_refresh_token` 方法 **新增代码**: ```python def _try_refresh_token(self) -> bool: """用 refresh_token 换取新的 access_token。成功返回 True 并通知上层持久化。""" refresh = self.config.refresh_token.strip() if not refresh or self._refresh_lock: return False self._refresh_lock = True try: resp = self.session.post( f"{self.base_url}/api/v1/auth/refresh", json={"refresh_token": refresh}, timeout=self.config.timeout, ) if resp.status_code != 200: 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: return False self.config.access_token = new_access self.session.headers.update({"Authorization": f"Bearer {new_access}"}) if new_refresh: self.config.refresh_token = new_refresh if self._on_token_refreshed: try: self._on_token_refreshed(self.config.access_token, self.config.refresh_token) except Exception: pass # 持久化失败不阻塞业务 return True except Exception: return False finally: self._refresh_lock = False ``` --- ### 2. `pixiv_app/gui/app.py` #### 2.1 新增 `cloud_refresh_token` 实例变量 **改动前**: ```python self.cloud_access_token = "" ``` **改动后**: ```python self.cloud_access_token = "" self.cloud_refresh_token = "" ``` #### 2.2 `get_cloud_sync_config` — 加 `refresh_token` **改动前**: ```python def get_cloud_sync_config(self) -> dict: return { "enabled": bool(self.cloud_sync_enabled_var.get()), "base_url": (self.cloud_base_url or DEFAULT_CLOUD_API).strip(), "access_token": self.cloud_access_token.strip(), } ``` **改动后**: ```python def get_cloud_sync_config(self) -> dict: return { "enabled": bool(self.cloud_sync_enabled_var.get()), "base_url": (self.cloud_base_url or DEFAULT_CLOUD_API).strip(), "access_token": self.cloud_access_token.strip(), "refresh_token": self.cloud_refresh_token.strip(), } ``` #### 2.3 登录成功时捕获 `refresh_token` **改动前**: ```python token = data.get("data", {}).get("access_token") if token: self.cloud_access_token = str(token).strip() self.enqueue_ui(self.cloud_status_var.set, "登录成功,云同步凭证已自动保存") ``` **改动后**: ```python 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() self.enqueue_ui(self.cloud_status_var.set, "登录成功,云同步凭证已自动保存") ``` #### 2.4 `restore_session` 加载 refresh_token **改动前**: ```python self.cloud_access_token = str(cloud.get("access_token") or "") if self.cloud_access_token: ``` **改动后**: ```python self.cloud_access_token = str(cloud.get("access_token") or "") self.cloud_refresh_token = str(cloud.get("refresh_token") or "") if self.cloud_access_token: ``` #### 2.5 新增 `_on_cloud_token_refreshed` 回调 + 更新 `create_sync_manager` **改动前**: ```python def create_sync_manager(self) -> SyncManager | None: config = self.get_cloud_sync_config() if not (config.get("enabled") and config.get("base_url") and config.get("access_token")): return None return SyncManager( SakuraCloudClient( CloudSyncConfig( base_url=str(config["base_url"]), access_token=str(config["access_token"]), ) ) ) ``` **改动后**: ```python def _on_cloud_token_refreshed(self, new_access: str, new_refresh: str) -> None: """Token 自动刷新后更新内存并持久化到本地会话文件。""" self.cloud_access_token = new_access if new_refresh: self.cloud_refresh_token = new_refresh self.enqueue_ui(self.cloud_status_var.set, "云同步 Token 已自动续期") self.enqueue_ui(self.save_session) def create_sync_manager(self) -> SyncManager | None: config = self.get_cloud_sync_config() if not (config.get("enabled") and config.get("base_url") and config.get("access_token")): return None return SyncManager( SakuraCloudClient( CloudSyncConfig( base_url=str(config["base_url"]), access_token=str(config["access_token"]), refresh_token=str(config.get("refresh_token") or ""), ), on_token_refreshed=self._on_cloud_token_refreshed, ) ) ``` --- ### 3. `pixiv_app/core/gallery_service.py` **改动前**: ```python return SyncManager( SakuraCloudClient( CloudSyncConfig( base_url=base_url, access_token=access_token, ) ) ) ``` **改动后**: ```python return SyncManager( SakuraCloudClient( CloudSyncConfig( base_url=base_url, access_token=access_token, refresh_token=str(cloud.get("refresh_token") or ""), ) ) ) ``` --- ### 4. `pixiv_app/core/origin_follow_sync.py` 同 gallery_service.py,仅加 `refresh_token` 行。 ### 5. `pixiv_app/core/x_media_service.py` 同 gallery_service.py,仅加 `refresh_token` 行。 --- ## 工作流程 ``` POST /api/v1/sync/check ├── 200 → 正常返回 └── 401 ├── refresh_token 为空? → 抛异常(旧 token 永久失效) ├── 正在刷新中? → 抛异常(防并发) └── POST /api/v1/auth/refresh ├── 200 → 更新内存 token → 回调持久化 → 重试原请求 └── 非200 → 抛异常(refresh 也过期了,需重新登录) ``` ## 兼容性 - `refresh_token` 默认值 `""` — 不传也能正常工作(旧行为) - `on_token_refreshed` 可选 — 不传也不影响其他调用方 - 现有的 `ConfigCloudSync` 构造方式全兼容