Undefined-bot 3.18.10__tar.gz → 3.19.0__tar.gz

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/CHANGELOG.md

@@ -1,3 +1,16 @@
+## v3.19.0 控制台登录态持久化
+
+本版本让 WebUI 控制台的登录态在进程重启后继续有效，并把登录有效期从 8 小时延长到 30 天；活跃使用的会话会自动续期，浏览器关闭重开也不再要求重新登录。
+
+- 会话落盘：服务端会话表写入 `data/cache/webui_sessions.json`（权限 0600），启动时自动恢复；过期条目在加载和写盘时清理，文件损坏只告警，不影响控制台启动。
+- 有效期延长：session 与 refresh token 从 8 小时延长到 30 天，access token 保持 15 分钟并由前端自动刷新；session 剩余不足一半时滑动续期，持续使用不会掉线。
+- 前端存储：WebUI 令牌从 `sessionStorage` 改为 `localStorage`，浏览器或控制台重启后仍然保留；自动迁移旧版本遗留的令牌，登出时一并清理。
+- Cookie 同步：`undefined_webui` 与 `undefined_webui_token` 的 `max_age` 均设为 30 天；刷新轮换只重置 `undefined_webui_token`，`undefined_webui` 保持登录时的 30 天期限。
+- 刷新安全：refresh token 轮换改为加锁原子操作，旧 token 立即失效；会话文件只保存密码指纹，修改管理密码（含直接编辑 `config.toml` 后重启）会作废旧登录态。
+- 测试覆盖：新增会话持久化、滑动续期、密码变更失效与重启恢复测试。
+
+---
+
 ## v3.18.10 群聊出错静默处理
 
 本版本新增群聊出错时的发言边界：bot 自行发起且未被要求的失败直接静默结束，用户明确要求的失败只回一句简短状态，不再主动认领、道歉或解释错误详情；同时把规则提升为与说话风格同级的 P1 顶层小节，并在多处同步重申。

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Undefined-bot
-Version: 3.18.10
+Version: 3.19.0
 Summary: QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11.
 Project-URL: Repository, https://github.com/69gg/Undefined
 Project-URL: Issues, https://github.com/69gg/Undefined/issues

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.18.10"
+version = "3.19.0"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/__init__.py

@@ -24,7 +24,7 @@ if TYPE_CHECKING:
     from .skills.registry import BaseRegistry as BaseRegistry
     from .skills.tools import ToolRegistry as ToolRegistry
 
-__version__: str = "3.18.10"
+__version__: str = "3.19.0"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/utils/paths.py

@@ -18,6 +18,7 @@ DOWNLOAD_CACHE_DIR: Path = CACHE_DIR / "downloads"
 TEXT_FILE_CACHE_DIR: Path = CACHE_DIR / "text_files"
 URL_FILE_CACHE_DIR: Path = CACHE_DIR / "url_files"
 WEBUI_FILE_CACHE_DIR: Path = CACHE_DIR / "webui_files"
+WEBUI_SESSIONS_FILE: Path = CACHE_DIR / "webui_sessions.json"
 ATTACHMENT_REGISTRY_FILE: Path = DATA_DIR / "attachment_registry.json"
 WEBCHAT_DIR: Path = DATA_DIR / "webchat"
 WEBCHAT_CONVERSATIONS_DIR: Path = WEBCHAT_DIR / "conversations"

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/webui/app.py

@@ -17,6 +17,7 @@ from Undefined.config import (
 )
 from Undefined.utils.cors import is_allowed_cors_origin, normalize_origin
 from Undefined.utils import io as async_io
+from Undefined.utils.paths import WEBUI_SESSIONS_FILE
 from Undefined.utils.self_update import resolve_repo_root
 from .core import BotProcessController, SessionStore
 from .routes import routes
@@ -296,12 +297,14 @@ def create_app(*, redirect_to_config_once: bool = False) -> web.Application:
         middlewares=[cors_middleware, gzip_middleware, security_headers_middleware]
     )
 
-    # 初始化核心组件
-    app[SESSION_STORE_APP_KEY] = SessionStore()
-
     # 配置 WebUI 设置热重载
     config_manager = get_config_manager()
-    app[SETTINGS_APP_KEY] = load_webui_settings()
+    settings = load_webui_settings()
+    app[SETTINGS_APP_KEY] = settings
+    # 会话落盘：控制台重启后浏览器无需重新登录；密码变更时旧会话自动失效。
+    app[SESSION_STORE_APP_KEY] = SessionStore(
+        storage_path=WEBUI_SESSIONS_FILE, password=settings.password
+    )
     app[BOT_APP_KEY] = BotProcessController(
         stop_timeout_getter=lambda: app[SETTINGS_APP_KEY].stop_timeout_seconds
     )
@@ -323,9 +326,21 @@ def create_app(*, redirect_to_config_once: bool = False) -> web.Application:
         ):
             logger.info("[WebUI] 检测到 WebUI 配置变更，正在热重载设置...")
             # 本次快照已成功读取；后续外部写入不能覆盖已验证的设置。
-            app[SETTINGS_APP_KEY] = WebUISettings.from_config(
-                config, config_exists=True
-            )
+            previous = app[SETTINGS_APP_KEY]
+            updated = WebUISettings.from_config(config, config_exists=True)
+            if updated.password != previous.password:
+                try:
+                    # 先持久化作废旧会话，再启用新密码，避免旧令牌在新密码下仍可用。
+                    app[SESSION_STORE_APP_KEY].set_password(updated.password)
+                except Exception:
+                    # 内存中的旧会话已作废（fail closed）；保留旧设置，
+                    # 下一次配置变更会重试持久化，避免把新密码当作已完全生效。
+                    logger.warning(
+                        "[WebUI] 密码变更后清理旧会话失败，暂不启用新密码",
+                        exc_info=True,
+                    )
+                    return
+            app[SETTINGS_APP_KEY] = updated
 
     config_manager.subscribe(_on_config_change)
 

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/webui/core.py

@@ -1,22 +1,38 @@
 import asyncio
 from collections.abc import Callable
 from dataclasses import dataclass
+import hashlib
+import json
 import logging
 import os
+from pathlib import Path
 import signal
 import subprocess
 import sys
+import threading
 import time
 import secrets
 from typing import Any
 from Undefined.config.webui_settings import DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS
-from Undefined.utils.io import run_cancellation_safe
+from Undefined.utils.io import run_cancellation_safe, write_json_sync
 
 logger = logging.getLogger(__name__)
 
-SESSION_TTL_SECONDS = 8 * 60 * 60
+#: 登录态有效期。控制台属于本地自托管面板，长有效期配合活跃滑动续期，
+#: 让长期使用的浏览器不必反复登录。
+SESSION_TTL_SECONDS = 30 * 24 * 60 * 60
 ACCESS_TOKEN_TTL_SECONDS = 15 * 60
-REFRESH_TOKEN_TTL_SECONDS = 8 * 60 * 60
+REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60
+SESSION_FILE_VERSION = 1
+
+
+def _password_fingerprint(password: str | None) -> str | None:
+    """会话文件只保存密码指纹，用于在密码变更后作废旧登录态。"""
+    if password is None:
+        return None
+    return hashlib.sha256(password.encode("utf-8")).hexdigest()[:16]
+
+
 #: 拉起 Bot 子进程的命令。
 #:
 #: 用**当前解释器**直接跑模块，而不是 ``uv run``：WebUI 自己就跑在这个解释器里，
@@ -35,33 +51,137 @@ class SessionEntry:
 
 
 class SessionStore:
+    """WebUI 会话表。
+
+    传入 ``storage_path`` 时会话会原子写入磁盘，控制台重启后自动恢复，
+    浏览器手里的 cookie / 令牌无需重新登录即可继续使用。
+    """
+
     def __init__(
         self,
         ttl_seconds: int = SESSION_TTL_SECONDS,
         access_ttl_seconds: int = ACCESS_TOKEN_TTL_SECONDS,
         refresh_ttl_seconds: int = REFRESH_TOKEN_TTL_SECONDS,
+        storage_path: Path | None = None,
+        password: str | None = None,
     ) -> None:
         self._ttl_seconds = ttl_seconds
         self._access_ttl_seconds = access_ttl_seconds
         self._refresh_ttl_seconds = refresh_ttl_seconds
+        self._storage_path = storage_path
+        self._password_fingerprint = _password_fingerprint(password)
         self._sessions: dict[str, SessionEntry] = {}
+        self._lock = threading.RLock()
+        self._load()
+
+    def _load(self) -> None:
+        path = self._storage_path
+        if path is None:
+            return
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return
+        except (OSError, UnicodeError) as exc:
+            logger.warning("[WebUI] 读取会话文件失败: %s", exc)
+            return
+        try:
+            payload = json.loads(raw)
+        except (ValueError, TypeError):
+            logger.warning("[WebUI] 会话文件损坏，已忽略: %s", path)
+            return
+        if not isinstance(payload, dict):
+            return
+        stored_fingerprint = payload.get("password_fingerprint")
+        if (
+            self._password_fingerprint is not None
+            and stored_fingerprint != self._password_fingerprint
+        ):
+            # 密码已变更（例如直接编辑 config.toml 后重启），旧令牌必须失效。
+            logger.info("[WebUI] 管理密码已变更，清除旧登录会话")
+            # 立即用新指纹覆盖磁盘，避免密码回滚后旧会话重新生效。
+            self._persist()
+            return
+        raw_sessions = payload.get("sessions")
+        if not isinstance(raw_sessions, dict):
+            return
+        now = time.time()
+        for token, value in raw_sessions.items():
+            if not isinstance(token, str) or not token or not isinstance(value, dict):
+                continue
+            try:
+                expires_at = float(value.get("expires_at") or 0)
+            except (TypeError, ValueError):
+                continue
+            kind = str(value.get("kind") or "session")
+            if kind not in {"session", "access", "refresh"} or expires_at <= now:
+                continue
+            self._sessions[token] = SessionEntry(expires_at=expires_at, kind=kind)
+
+    def _payload(self) -> dict[str, object]:
+        now = time.time()
+        return {
+            "version": SESSION_FILE_VERSION,
+            "password_fingerprint": self._password_fingerprint,
+            "sessions": {
+                token: {"expires_at": entry.expires_at, "kind": entry.kind}
+                for token, entry in self._sessions.items()
+                if entry.expires_at > now
+            },
+        }
+
+    def _persist_strict(self) -> None:
+        """写盘失败时向上抛出，供登出/刷新等需要强一致性的路径回滚。"""
+        path = self._storage_path
+        if path is None:
+            return
+        write_json_sync(path, self._payload(), use_lock=False)
+
+    def _prune_expired(self) -> None:
+        now = time.time()
+        for token in [
+            token for token, entry in self._sessions.items() if entry.expires_at <= now
+        ]:
+            self._sessions.pop(token, None)
+
+    def _persist(self) -> None:
+        """登录与校验路径的 best-effort 写盘；磁盘异常只告警。"""
+        try:
+            self._persist_strict()
+        except Exception as exc:  # 磁盘异常不应让登录/校验直接失败
+            logger.warning("[WebUI] 写入会话文件失败: %s", exc)
+            return
+        self._prune_expired()
 
     def create(self, *, ttl_seconds: int | None = None, kind: str = "session") -> str:
         token = secrets.token_urlsafe(32)
         ttl = self._ttl_seconds if ttl_seconds is None else ttl_seconds
-        self._sessions[token] = SessionEntry(expires_at=time.time() + ttl, kind=kind)
+        with self._lock:
+            self._sessions[token] = SessionEntry(
+                expires_at=time.time() + ttl, kind=kind
+            )
+            self._persist()
         return token
 
     def _resolve_entry(self, token: str | None) -> SessionEntry | None:
         if not token:
             return None
-        entry = self._sessions.get(token)
-        if entry is None:
-            return None
-        if entry.expires_at < time.time():
-            self._sessions.pop(token, None)
-            return None
-        return entry
+        with self._lock:
+            entry = self._sessions.get(token)
+            if entry is None:
+                return None
+            now = time.time()
+            if entry.expires_at < now:
+                self._sessions.pop(token, None)
+                self._persist()
+                return None
+            # 活跃会话滑动续期：剩余不足一半时重新计时，长期使用不会掉线。
+            if entry.kind == "session":
+                ttl = self._ttl_seconds
+                if ttl > 0 and entry.expires_at - now < ttl / 2:
+                    entry.expires_at = now + ttl
+                    self._persist()
+            return entry
 
     def is_valid(
         self,
@@ -86,38 +206,96 @@ class SessionStore:
         entry = self._resolve_entry(token)
         return None if entry is None else entry.kind
 
-    def issue_auth_tokens(self) -> dict[str, int | str]:
-        access_token = self.create(
-            ttl_seconds=self._access_ttl_seconds,
-            kind="access",
+    def _issue_auth_tokens_locked(self) -> dict[str, int | str]:
+        now = time.time()
+        access_token = secrets.token_urlsafe(32)
+        refresh_token = secrets.token_urlsafe(32)
+        self._sessions[access_token] = SessionEntry(
+            expires_at=now + self._access_ttl_seconds, kind="access"
         )
-        refresh_token = self.create(
-            ttl_seconds=self._refresh_ttl_seconds,
-            kind="refresh",
+        self._sessions[refresh_token] = SessionEntry(
+            expires_at=now + self._refresh_ttl_seconds, kind="refresh"
         )
         return {
             "access_token": access_token,
             "refresh_token": refresh_token,
             "expires_in": self._access_ttl_seconds,
             "refresh_expires_in": self._refresh_ttl_seconds,
-            "access_token_expires_at": self.get_expiry_ms(access_token),
+            "access_token_expires_at": int((now + self._access_ttl_seconds) * 1000),
         }
 
+    def issue_auth_tokens(self) -> dict[str, int | str]:
+        with self._lock:
+            tokens = self._issue_auth_tokens_locked()
+            self._persist()
+            return tokens
+
     def refresh_auth_tokens(
         self, refresh_token: str | None
     ) -> dict[str, int | str] | None:
-        if not self.is_valid(refresh_token, allowed_kinds={"refresh"}):
+        if not refresh_token:
             return None
-        self.revoke(refresh_token)
-        return self.issue_auth_tokens()
+        with self._lock:
+            entry = self._sessions.get(refresh_token)
+            if entry is None or entry.kind != "refresh":
+                return None
+            if entry.expires_at < time.time():
+                self._sessions.pop(refresh_token, None)
+                try:
+                    self._persist_strict()
+                except Exception:
+                    self._sessions[refresh_token] = entry
+                    raise
+                return None
+            # 旧 refresh token 立即作废并轮换，避免重放。
+            previous = dict(self._sessions)
+            self._sessions.pop(refresh_token, None)
+            tokens = self._issue_auth_tokens_locked()
+            try:
+                self._persist_strict()
+            except Exception:
+                self._sessions = previous
+                raise
+            return tokens
 
     def revoke(self, token: str | None) -> None:
         if not token:
             return
-        self._sessions.pop(token, None)
+        with self._lock:
+            entry = self._sessions.pop(token, None)
+            if entry is None:
+                return
+            try:
+                self._persist_strict()
+            except Exception:
+                self._sessions[token] = entry
+                raise
+
+    def set_password(self, password: str | None) -> None:
+        """密码变更后作废全部旧会话，并更新会话文件中的密码指纹。
+
+        写盘失败时内存中的旧会话保持作废（fail closed），但密码指纹回滚，
+        异常抛给调用方；后续密码重载会重新尝试持久化新指纹。
+        """
+        with self._lock:
+            previous_fingerprint = self._password_fingerprint
+            self._password_fingerprint = _password_fingerprint(password)
+            self._sessions.clear()
+            try:
+                self._persist_strict()
+            except Exception:
+                self._password_fingerprint = previous_fingerprint
+                raise
 
     def clear(self) -> None:
-        self._sessions.clear()
+        with self._lock:
+            previous = dict(self._sessions)
+            self._sessions.clear()
+            try:
+                self._persist_strict()
+            except Exception:
+                self._sessions = previous
+                raise
 
 
 class BotProcessController:

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/webui/routes/_auth.py

@@ -1,4 +1,5 @@
 import asyncio
+import logging
 import tomllib
 
 from aiohttp import web
@@ -7,13 +8,13 @@ from aiohttp.web_response import Response
 from Undefined.config.loader import CONFIG_PATH, DEFAULT_WEBUI_PASSWORD
 from Undefined.config import WebUISettings, get_config_manager
 from Undefined.utils import io as async_io
+from ..core import REFRESH_TOKEN_TTL_SECONDS, SESSION_TTL_SECONDS
 from ..utils.config_io import config_write_lock
 from ._shared import (
     auth_capabilities,
     routes,
     SESSION_COOKIE,
     TOKEN_COOKIE,
-    SESSION_TTL_SECONDS,
     SETTINGS_APP_KEY,
     get_bearer_token,
     get_refresh_token,
@@ -29,6 +30,8 @@ from ._shared import (
 )
 from ..utils import read_config_source, apply_patch, load_comment_map, render_toml
 
+logger = logging.getLogger(__name__)
+
 
 def _build_session_payload(
     request: web.Request, authenticated: bool
@@ -120,7 +123,7 @@ async def login_handler(request: web.Request) -> Response:
             str(auth_tokens["refresh_token"]),
             httponly=True,
             samesite="Lax",
-            max_age=SESSION_TTL_SECONDS,
+            max_age=REFRESH_TOKEN_TTL_SECONDS,
         )
         return resp
 
@@ -154,7 +157,13 @@ async def refresh_handler(request: web.Request) -> Response:
     except Exception:
         data = {}
     refresh_token = get_refresh_token(request, data)
-    tokens = get_session_store(request).refresh_auth_tokens(refresh_token)
+    try:
+        tokens = get_session_store(request).refresh_auth_tokens(refresh_token)
+    except OSError as exc:
+        logger.warning("[WebUI] 刷新令牌时写入会话文件失败: %s", exc)
+        return web.json_response(
+            {"success": False, "error": "Failed to persist session"}, status=500
+        )
     if tokens is None:
         return web.json_response(
             {"success": False, "error": "Unauthorized"}, status=401
@@ -172,7 +181,7 @@ async def refresh_handler(request: web.Request) -> Response:
         str(tokens["refresh_token"]),
         httponly=True,
         samesite="Lax",
-        max_age=SESSION_TTL_SECONDS,
+        max_age=REFRESH_TOKEN_TTL_SECONDS,
     )
     return resp
 
@@ -185,6 +194,7 @@ async def logout_handler(request: web.Request) -> Response:
     except Exception:
         data = {}
     sessions = get_session_store(request)
+    failed = False
     for token in {
         get_valid_auth_token(request),
         request.cookies.get(SESSION_COOKIE),
@@ -192,7 +202,15 @@ async def logout_handler(request: web.Request) -> Response:
         get_refresh_token(request, data),
         get_bearer_token(request),
     }:
-        sessions.revoke(token)
+        try:
+            sessions.revoke(token)
+        except OSError as exc:
+            failed = True
+            logger.warning("[WebUI] 登出时写入会话文件失败: %s", exc)
+    if failed:
+        return web.json_response(
+            {"success": False, "error": "Failed to persist session"}, status=500
+        )
     resp = web.json_response({"success": True})
     resp.del_cookie(SESSION_COOKIE)
     resp.del_cookie(TOKEN_COOKIE)
@@ -264,10 +282,11 @@ async def password_handler(request: web.Request) -> Response:
         await asyncio.to_thread(write_password)
         manager = get_config_manager()
         manager.reload()
+        # 先完成会话失效持久化，再启用新密码；失败时由 500 分支返回。
+        get_session_store(request).set_password(new_password)
         request.app[SETTINGS_APP_KEY] = WebUISettings.from_config(
             manager.load(strict=False), config_exists=True
         )
-        get_session_store(request).clear()
 
     try:
         await async_io.run_cancellation_safe(password_and_reload())
@@ -275,6 +294,12 @@ async def password_handler(request: web.Request) -> Response:
         return web.json_response(
             {"success": False, "error": f"TOML parse error: {exc}"}, status=400
         )
+    except OSError as exc:
+        logger.warning("[WebUI] 更新密码后写入持久化状态失败: %s", exc)
+        return web.json_response(
+            {"success": False, "error": "Failed to persist password change"},
+            status=500,
+        )
 
     resp = web.json_response({"success": True, "message": "Password updated"})
     resp.del_cookie(SESSION_COOKIE)

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/webui/routes/_shared.py

@@ -27,7 +27,6 @@ _PENDING_BOT_AUTOSTART_MARKER = Path("data/cache/pending_bot_autostart")
 
 SESSION_COOKIE = "undefined_webui"
 TOKEN_COOKIE = "undefined_webui_token"
-SESSION_TTL_SECONDS = 8 * 60 * 60
 LOGIN_ATTEMPT_LIMIT = 5
 LOGIN_ATTEMPT_WINDOW = 5 * 60
 LOGIN_BLOCK_SECONDS = 15 * 60

{undefined_bot-3.18.10 → undefined_bot-3.19.0}/src/Undefined/webui/static/js/api.js

@@ -167,10 +167,16 @@ function updateAuthFromPayload(payload) {
 
 let _authRefreshRequest = null;
 
+function unauthorizedError(authFailure) {
+    const error = new Error("Unauthorized");
+    error.authFailure = !!authFailure;
+    return error;
+}
+
 async function refreshAccessToken() {
     const refreshToken = state.authRefreshToken;
     if (!refreshToken) {
-        throw new Error("Unauthorized");
+        throw unauthorizedError(false);
     }
     if (_authRefreshRequest?.token === refreshToken) {
         return _authRefreshRequest.promise;
@@ -194,8 +200,33 @@ async function refreshAccessToken() {
         // 登录或退出可能已替换会话；旧请求不能改写新令牌。
         if (state.authRefreshToken !== refreshToken) return payload;
         if (!response.ok || !updateAuthFromPayload(payload)) {
-            clearStoredAuthTokens();
-            throw new Error("Unauthorized");
+            const storedRefreshToken = readAuthStorage(
+                "undefined_auth_refresh_token",
+            );
+            if (storedRefreshToken && storedRefreshToken !== refreshToken) {
+                // 其他标签页已轮换令牌：跟随共享存储，避免清掉新令牌。
+                const adopted = updateAuthFromPayload({
+                    accessToken: readAuthStorage("undefined_auth_access_token"),
+                    refreshToken: storedRefreshToken,
+                    accessTokenExpiresAt:
+                        Number.parseInt(
+                            readAuthStorage(
+                                "undefined_auth_access_expires_at",
+                            ) || "0",
+                            10,
+                        ) || 0,
+                });
+                // 采用替换令牌后按成功处理，让调用方用新 access token 重试。
+                if (adopted) return payload;
+            }
+            // 只有服务端明确判定登录态失效时才清除令牌；
+            // 5xx 或异常响应属于可重试失败，保留令牌等待下次刷新。
+            if (response.status === 401 || response.status === 403) {
+                clearStoredAuthTokens();
+            }
+            throw unauthorizedError(
+                response.status === 401 || response.status === 403,
+            );
         }
         return payload;
     })();
@@ -215,11 +246,13 @@ async function api(path, options = {}) {
         !!state.authAccessTokenExpiresAt &&
         state.authAccessTokenExpiresAt <= Date.now() + 60_000;
 
+    let refreshFailure = null;
     if (accessExpiringSoon && method !== "OPTIONS") {
         try {
             await refreshAccessToken();
-        } catch (_error) {
-            // ignore and let request surface authorization result
+        } catch (error) {
+            // 记录失败原因，由资源请求结果决定是否降级登录态。
+            refreshFailure = error;
         }
     }
 
@@ -231,15 +264,21 @@ async function api(path, options = {}) {
     ) {
         try {
             await refreshAccessToken();
+            refreshFailure = null;
             res = await apiWithFallback(candidates, {
                 ...options,
                 _skipRefreshRetry: true,
             });
-        } catch (_error) {
+        } catch (error) {
             // refreshAccessToken 只清除仍属于失败请求的令牌。
+            refreshFailure = error;
         }
     }
     if (res.status === 401) {
+        if (refreshFailure && !refreshFailure.authFailure) {
+            // 刷新因网络或服务端故障失败：保留登录态，交回原始 401 响应。
+            return res;
+        }
         state.authenticated = false;
         refreshUI();
         throw new Error("Unauthorized");