fix(cloudsave): degrade when local state is unavailable

本次修复在启动前预检本机 state 目录；当 anchor/state/root_state 等本机状态路径不可用时，仅禁用本次会话云存档，不再阻断整个应用启动。

云存档 provider、bootstrap/import/export/upload/download、角色 tombstone 与 Workshop tombstone 链路都会跳过坏 state；存储位置写入/迁移动作在 local_state_unavailable 时返回 409，避免污染 root_state 或 migration checkpoint。

同时补充错误诊断、入口禁用、i18n、设计文档和单元回归覆盖，保持 cloudsave/state 不参与存储迁移。

Author: yiyiyiyiGKY

app/main_server.py

@@ -75,6 +75,7 @@ def _get_app_root():
     MaintenanceModeError,
     ROOT_MODE_NORMAL,
     bootstrap_local_cloudsave_environment,
+    is_cloudsave_disabled,
     is_write_fence_active,
     maintenance_error_payload,
     set_root_mode,
@@ -2031,21 +2032,25 @@ async def _ensure_main_server_runtime_initialized(*, reason: str) -> bool:
             return False
 
         try:
-            bootstrap_local_cloudsave_environment(_config_manager)
-            import_result = None
-            try:
-                import_result = await _run_cloudsave_manager_action(
-                    "import_if_needed",
-                    reason="main_server_startup",
-                    budget_seconds=10.0,
-                )
-                logger.info("Steam Auto-Cloud startup import: %s", import_result)
-            except CloudsaveDeadlineExceeded:
-                logger.warning(
-                    "Steam Auto-Cloud startup import exceeded 10.0s budget before applying runtime changes; continuing with local runtime state"
-                )
-            except Exception as e:
-                logger.warning(f"Steam Auto-Cloud startup import failed: {e}")
+            if is_cloudsave_disabled():
+                logger.warning("Steam Auto-Cloud startup skipped because cloudsave is disabled for this session")
+                import_result = None
+            else:
+                bootstrap_local_cloudsave_environment(_config_manager)
+                import_result = None
+                try:
+                    import_result = await _run_cloudsave_manager_action(
+                        "import_if_needed",
+                        reason="main_server_startup",
+                        budget_seconds=10.0,
+                    )
+                    logger.info("Steam Auto-Cloud startup import: %s", import_result)
+                except CloudsaveDeadlineExceeded:
+                    logger.warning(
+                        "Steam Auto-Cloud startup import exceeded 10.0s budget before applying runtime changes; continuing with local runtime state"
+                    )
+                except Exception as e:
+                    logger.warning(f"Steam Auto-Cloud startup import failed: {e}")
 
             await initialize_character_data()
             await _sync_memory_server_after_startup_import(import_result)
@@ -2097,8 +2102,10 @@ async def _ensure_main_server_runtime_initialized(*, reason: str) -> bool:
             except Exception as e:
                 logger.warning(f"全局语言初始化失败（不影响启动）: {e}")
 
-            current_root_state = _config_manager.load_root_state()
-            if should_write_root_mode_normal_after_startup(current_root_state):
+            current_root_state = None if is_cloudsave_disabled() else _config_manager.load_root_state()
+            if current_root_state is None:
+                logger.warning("跳过 ROOT_MODE_NORMAL 写入：cloudsave 已为本次会话禁用")
+            elif should_write_root_mode_normal_after_startup(current_root_state):
                 try:
                     set_root_mode(
                         _config_manager,

app/memory_server.py

@@ -80,6 +80,7 @@
     MaintenanceModeError,
     ROOT_MODE_NORMAL,
     bootstrap_local_cloudsave_environment,
+    is_cloudsave_disabled,
     maintenance_error_payload,
     set_root_mode,
     should_write_root_mode_normal_after_startup,
@@ -2940,11 +2941,14 @@ async def ensure_memory_server_runtime_initialized(*, reason: str = "") -> bool:
             return False
 
         bootstrap_ok = False
-        try:
-            bootstrap_local_cloudsave_environment(_config_manager)
-            bootstrap_ok = True
-        except Exception as e:
-            logger.warning(f"[Memory] cloudsave 环境 bootstrap 失败，后续 cloudsave 相关操作可能降级: {e}")
+        if is_cloudsave_disabled():
+            logger.warning("[Memory] 跳过 cloudsave 环境 bootstrap：cloudsave 已为本次会话禁用")
+        else:
+            try:
+                bootstrap_local_cloudsave_environment(_config_manager)
+                bootstrap_ok = True
+            except Exception as e:
+                logger.warning(f"[Memory] cloudsave 环境 bootstrap 失败，后续 cloudsave 相关操作可能降级: {e}")
 
         try:
             from memory import migrate_to_character_dirs

docs/design/cloud-save-sync-optimization-plan.md

@@ -85,17 +85,31 @@
 
 执行顺序：
 
-1. `bootstrap_local_cloudsave_environment()`。
-2. `CloudSaveManager.import_if_needed(reason="launcher_phase0_prelaunch_import")`。
-3. root mode 切回 `normal`。
-4. 发送 `cloudsave_bootstrap_ready` 事件。
+1. launcher 先在 fence 外校验本机 `state/` 目录可创建/可写。
+2. 进入 `cloud_apply_fence(mode="bootstrap_importing")`。
+3. `bootstrap_local_cloudsave_environment()` 创建/校验 `state/` 与 `cloudsave/` 基础骨架，并执行 legacy/recovery 启动逻辑。
+4. `CloudSaveManager.import_if_needed(reason="launcher_phase0_prelaunch_import")`，真正应用快照仍在 fence 内执行。
+5. root mode 切回 `normal`。
+6. 发送 `cloudsave_bootstrap_ready` 事件。
 
 事件脱敏契约：`import_result` 只允许：
 
 - `success`
 - `action`
 - `requested_reason`
 
+若本机 `state/` 初始化失败（例如 `%LOCALAPPDATA%/N.E.K.O`、其 `state/` 或 state JSON 被同名文件/目录占用、不可写或被安全软件拦截），launcher 不得再尝试写入 `maintenance_readonly`，因为这会再次依赖同一个不可用的 `state/`。
+
+当前降级口径：
+
+- 设置 `NEKO_CLOUDSAVE_DISABLED=local_state_unavailable`，本次会话禁用 cloudsave bootstrap/import/export 与 write fence。
+- main_server / memory_server 继续按本地运行时真源启动，不自动应用 Steam `cloudsave/` 快照。
+- 云存档接口与页面应显示 provider unavailable / disabled，不再读取坏的本机 state。
+- 普通角色、配置、记忆等本地运行时写入不应被 cloudsave state 问题拖垮。
+- 存储位置只读状态接口可继续返回 disabled 诊断；需要写 `root_state` / migration checkpoint 的存储迁移动作必须拒绝执行，避免坏 `state/` 再污染迁移控制面。
+
+关闭 Steam Cloud 不会影响该本机状态目录初始化；降级只是保证用户能先启动应用，仍应提示用户修复 `anchor_root` / `local_state_dir` / `failed_path` 指向的本机路径。
+
 ### 4.2 main_server 直启兜底
 
 - startup 会再做一次 `bootstrap + import_if_needed(reason="main_server_startup")`。

launcher.py

@@ -266,6 +266,8 @@ def _maybe_reexec_into_project_venv(project_dir: str) -> None:
     set_port_probe_reuse,
 )
 from utils.cloudsave_runtime import (
+    CLOUDSAVE_DISABLED_ENV,
+    CLOUDSAVE_DISABLED_LOCAL_STATE_UNAVAILABLE,
     ROOT_MODE_BOOTSTRAP_IMPORTING,
     ROOT_MODE_MAINTENANCE_READONLY,
     ROOT_MODE_NORMAL,
@@ -1903,6 +1905,12 @@ def _prepare_cloudsave_runtime_for_launch() -> dict:
     reset_config_manager_cache()
     config_manager = get_config_manager(APP_NAME, migrate=False)
 
+    if not config_manager.ensure_local_state_directory():
+        diagnostic = getattr(config_manager, "_last_local_state_directory_error", None)
+        if diagnostic is not None:
+            raise diagnostic
+        raise OSError("failed to ensure local state directory")
+
     with cloud_apply_fence(
         config_manager,
         mode=ROOT_MODE_BOOTSTRAP_IMPORTING,
@@ -1952,6 +1960,18 @@ def _prepare_cloudsave_runtime_for_launch() -> dict:
     }
 
 
+def _is_local_state_directory_error(exc) -> bool:
+    if bool(getattr(exc, "local_state_directory_error", False)):
+        return True
+    cause = getattr(exc, "__cause__", None)
+    if cause is not None and cause is not exc:
+        return _is_local_state_directory_error(cause)
+    context = getattr(exc, "__context__", None)
+    if context is not None and context is not exc:
+        return _is_local_state_directory_error(context)
+    return False
+
+
 def main():
     """主函数"""
     # 支持 multiprocessing 在 Windows 上的打包
@@ -1990,17 +2010,24 @@ def main():
         try:
             _prepare_cloudsave_runtime_for_launch()
         except Exception as e:
-            try:
-                _config_manager = get_config_manager(APP_NAME)
-                set_root_mode(
-                    _config_manager,
-                    ROOT_MODE_MAINTENANCE_READONLY,
-                    last_migration_result=f"launcher_phase0_bootstrap_failed:{e}",
-                )
-            except Exception:
-                pass
-            report_startup_failure(f"Startup failed: cloudsave bootstrap error: {e}")
-            return 1
+            if not _is_local_state_directory_error(e):
+                try:
+                    _config_manager = get_config_manager(APP_NAME)
+                    set_root_mode(
+                        _config_manager,
+                        ROOT_MODE_MAINTENANCE_READONLY,
+                        last_migration_result=f"launcher_phase0_bootstrap_failed:{e}",
+                    )
+                except Exception:
+                    pass
+                report_startup_failure(f"Startup failed: cloudsave bootstrap error: {e}")
+                return 1
+            os.environ[CLOUDSAVE_DISABLED_ENV] = CLOUDSAVE_DISABLED_LOCAL_STATE_UNAVAILABLE
+            print(
+                "[Launcher] Cloudsave disabled for this session because local state is unavailable: "
+                f"{e}",
+                flush=True,
+            )
 
         # 自动安装 Playwright Chromium（browser-use 依赖）
         _ensure_playwright_browsers()

main_routers/characters_router.py

@@ -121,7 +121,7 @@
     list_persona_presets,
 )
 from utils.url_utils import encode_url_path
-from utils.cloudsave_runtime import MaintenanceModeError, assert_cloudsave_writable
+from utils.cloudsave_runtime import MaintenanceModeError, assert_cloudsave_writable, is_cloudsave_disabled
 from config import (
     MEMORY_SERVER_PORT,
     TFLINK_UPLOAD_URL,
@@ -1494,6 +1494,9 @@ def _restore_snapshot_paths(records) -> None:
 
 
 def _build_character_tombstones_state(config_manager, character_name: str) -> dict:
+    if is_cloudsave_disabled():
+        return config_manager.build_default_character_tombstones_state()
+
     cloud_state = config_manager.load_cloudsave_local_state()
     sequence_number = max(1, int(cloud_state.get("next_sequence_number") or 1))
     tombstone_state = config_manager.load_character_tombstones_state()
@@ -3591,7 +3594,8 @@ async def delete_catgirl(name: str):
         tombstone_snapshot = None
         memory_server_reloaded = False
         try:
-            tombstone_snapshot = copy.deepcopy(_config_manager.load_character_tombstones_state())
+            if not is_cloudsave_disabled():
+                tombstone_snapshot = copy.deepcopy(_config_manager.load_character_tombstones_state())
 
             removed_memory_paths = await asyncio.to_thread(
                 delete_character_memory_storage, _config_manager, name
@@ -3605,10 +3609,11 @@ async def delete_catgirl(name: str):
             if meta_path.exists():
                 await asyncio.to_thread(meta_path.unlink)
 
-            await asyncio.to_thread(
-                _config_manager.save_character_tombstones_state,
-                _build_character_tombstones_state(_config_manager, name),
-            )
+            if not is_cloudsave_disabled():
+                await asyncio.to_thread(
+                    _config_manager.save_character_tombstones_state,
+                    _build_character_tombstones_state(_config_manager, name),
+                )
 
             # 删除角色配置
             del characters['猫娘'][name]

main_routers/storage_location_router.py

@@ -33,7 +33,13 @@
     get_request_app_shutdown,
     get_release_storage_startup_barrier,
 )
-from utils.cloudsave_runtime import ROOT_MODE_MAINTENANCE_READONLY, ROOT_MODE_NORMAL, set_root_mode
+from utils.cloudsave_runtime import (
+    ROOT_MODE_MAINTENANCE_READONLY,
+    ROOT_MODE_NORMAL,
+    cloudsave_disabled_reason,
+    is_cloudsave_disabled_due_to_local_state_unavailable,
+    set_root_mode,
+)
 from utils.storage_location_bootstrap import (
     STORAGE_STARTUP_BLOCKING_REASONS,
     STORAGE_STATUS_POLL_INTERVAL_MS,
@@ -113,6 +119,19 @@ def _set_no_cache_headers(response: Response) -> None:
     response.headers["Expires"] = "0"
 
 
+def _reject_storage_mutation_when_cloudsave_disabled(response: Response) -> dict[str, Any] | None:
+    if not is_cloudsave_disabled_due_to_local_state_unavailable():
+        return None
+    response.status_code = 409
+    return {
+        "ok": False,
+        "error_code": "cloudsave_local_state_unavailable",
+        "error": "本机状态目录不可用，当前会话已禁用云存档。请先修复本机 state 路径后重启应用，再进行存储位置变更。",
+        "cloudsave_disabled": True,
+        "cloudsave_disabled_reason": cloudsave_disabled_reason(),
+    }
+
+
 def _normalize_optional_path(value: Any) -> str:
     raw_value = str(value or "").strip()
     if not raw_value:
@@ -1081,6 +1100,10 @@ async def post_storage_location_exit(request: Request, response: Response):
             "error": "缺少存储退出确认标记。",
         }
 
+    disabled_response = _reject_storage_mutation_when_cloudsave_disabled(response)
+    if disabled_response is not None:
+        return disabled_response
+
     config_manager = _get_storage_config_manager()
     bootstrap_payload = build_storage_location_bootstrap_payload(config_manager)
     blocking_reason = str(bootstrap_payload.get("blocking_reason") or "").strip()
@@ -1216,6 +1239,10 @@ async def _post_storage_location_retained_source_cleanup_locked(
 ):
     _set_no_cache_headers(response)
 
+    disabled_response = _reject_storage_mutation_when_cloudsave_disabled(response)
+    if disabled_response is not None:
+        return disabled_response
+
     config_manager = _get_storage_config_manager()
     notice = _build_completed_migration_notice(
         config_manager,
@@ -1300,6 +1327,10 @@ async def _post_storage_location_select_locked(
 ):
     _set_no_cache_headers(response)
 
+    disabled_response = _reject_storage_mutation_when_cloudsave_disabled(response)
+    if disabled_response is not None:
+        return disabled_response
+
     config_manager = _get_storage_config_manager()
     current_root = normalize_runtime_root(config_manager.app_docs_dir)
     anchor_root = compute_anchor_root(config_manager, current_root=current_root)
@@ -1508,6 +1539,10 @@ async def post_storage_location_preflight(
 ):
     _set_no_cache_headers(response)
 
+    disabled_response = _reject_storage_mutation_when_cloudsave_disabled(response)
+    if disabled_response is not None:
+        return disabled_response
+
     config_manager = _get_storage_config_manager()
     current_root = normalize_runtime_root(config_manager.app_docs_dir)
     anchor_root = compute_anchor_root(config_manager, current_root=current_root)
@@ -1587,6 +1622,10 @@ async def _post_storage_location_restart_locked(
 ):
     _set_no_cache_headers(response)
 
+    disabled_response = _reject_storage_mutation_when_cloudsave_disabled(response)
+    if disabled_response is not None:
+        return disabled_response
+
     config_manager = _get_storage_config_manager()
     current_root = normalize_runtime_root(config_manager.app_docs_dir)
     anchor_root = compute_anchor_root(config_manager, current_root=current_root)

main_routers/workshop_router.py

@@ -31,7 +31,7 @@
 from fastapi.responses import FileResponse, JSONResponse
 
 from .shared_state import ensure_steamworks as get_steamworks, get_config_manager, get_initialize_character_data
-from utils.cloudsave_runtime import MaintenanceModeError, is_write_fence_active
+from utils.cloudsave_runtime import MaintenanceModeError, is_cloudsave_disabled, is_write_fence_active
 from utils.file_utils import atomic_write_json, atomic_write_json_async, read_json_async
 from utils.workshop_utils import (
     ensure_workshop_folder_exists,
@@ -236,6 +236,9 @@ def _read_first_line(path: str, encoding: str = 'utf-8') -> str:
 
 def _load_deleted_character_names(config_mgr) -> set[str]:
     deleted_names: set[str] = set()
+    if is_cloudsave_disabled():
+        return deleted_names
+
     try:
         tombstone_state = config_mgr.load_character_tombstones_state()
     except Exception as exc:
@@ -253,6 +256,9 @@ def _load_deleted_character_names(config_mgr) -> set[str]:
 
 def _remove_deleted_character_tombstones(config_mgr, character_names: list[str]) -> list[str]:
     """移除手动恢复角色对应的 tombstone，避免后续同步继续把它当作已删除。"""
+    if is_cloudsave_disabled():
+        return []
+
     target_names = {str(name or "").strip() for name in character_names}
     target_names.discard("")
     if not target_names:
@@ -283,6 +289,15 @@ def _remove_deleted_character_tombstones(config_mgr, character_names: list[str])
     return removed_names
 
 
+def _write_deleted_character_tombstone(config_mgr, character_name: str, build_tombstone_state) -> bool:
+    if is_cloudsave_disabled():
+        return False
+
+    tombstone_state = build_tombstone_state(config_mgr, character_name)
+    config_mgr.save_character_tombstones_state(tombstone_state)
+    return True
+
+
 def _derive_workshop_origin_display_name(raw_model_name: str, fallback_name: str) -> str:
     normalized_name = str(raw_model_name or "").strip().replace("\\", "/")
     if not normalized_name:
@@ -3382,9 +3397,11 @@ async def _delete_memory_with_retry(name: str) -> list:
                     )
 
             async def _write_tombstone(name: str) -> None:
-                tombstone_state = _build_character_tombstones_state(config_mgr, name)
                 await asyncio.to_thread(
-                    config_mgr.save_character_tombstones_state, tombstone_state
+                    _write_deleted_character_tombstone,
+                    config_mgr,
+                    name,
+                    _build_character_tombstones_state,
                 )
 
             async def _remove_one(name: str) -> None: