Files
SakuraHub/docs/2026-06-22_cloud_sync_401_fix.md
T
2026-11-16 20:45:22 +08:00

9.1 KiB

云同步 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 字段

改动前:

@dataclass
class CloudSyncConfig:
    base_url: str
    access_token: str
    chunk_size: int = 5 * 1024 * 1024
    timeout: float = 60.0

改动后:

@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 回调

改动前:

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}"})

改动后:

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 自动刷新 + 重试

改动前:

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)

改动后:

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 方法

新增代码:

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 实例变量

改动前:

self.cloud_access_token = ""

改动后:

self.cloud_access_token = ""
self.cloud_refresh_token = ""

2.2 get_cloud_sync_config — 加 refresh_token

改动前:

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(),
    }

改动后:

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

改动前:

token = data.get("data", {}).get("access_token")
if token:
    self.cloud_access_token = str(token).strip()
    self.enqueue_ui(self.cloud_status_var.set, "登录成功,云同步凭证已自动保存")

改动后:

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

改动前:

self.cloud_access_token = str(cloud.get("access_token") or "")
if self.cloud_access_token:

改动后:

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

改动前:

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"]),
            )
        )
    )

改动后:

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

改动前:

    return SyncManager(
        SakuraCloudClient(
            CloudSyncConfig(
                base_url=base_url,
                access_token=access_token,
            )
        )
    )

改动后:

    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 构造方式全兼容