fix(db): harden database architecture and robust restoration logic

aidyou · aidyou · commit 7dd47280e5b9 · 2026-02-05T21:07:02.000+08:00
- Upgrade database to WAL mode and add busy timeout for better concurrency.
- Implement `MainStore::atomic_restore` to safely replace DB files without corruption.
- Remove redundant database initialization calls that caused production locking.
- Clean up SQLite temporary files (-wal, -shm) before physical restoration.
- Update release notes to v1.2.4 and document database concurrency risks in GEMINI.md.
diff --git a/GEMINI.md b/GEMINI.md
@@ -115,3 +115,15 @@ This section outlines the coding standards, architectural patterns, and workflow
   5. **Correct**: Iteratively fix any issues found during verification.
   6. **Report**: Provide a concise summary of the resolution.
 - **Git Protocol**: Do not proactively stage or commit changes unless explicitly requested by the user.
+
+### 7. Database Concurrency & Deadlock Risks
+To ensure stability in production environments where background services (like CCProxy) and the main UI may access the database simultaneously, follow these rules:
+- **Enable WAL Mode**: Always use `PRAGMA journal_mode=WAL;` to allow multiple readers and one writer to coexist without blocking.
+- **Busy Timeout**: Always set a `busy_timeout` (e.g., 5 seconds) on the SQLite connection to handle transient locks gracefully.
+- **Avoid "Double Open"**: Ensure the database file is opened only once per process. Redundant calls to `Connection::open` on the same file can lead to `readonly database` errors or file corruption in production.
+- **Atomic Restoration**: When performing physical file replacement (restoration):
+    1. **Disconnect**: Close all active connections (or swap with an in-memory DB) to release file handles.
+    2. **Cleanup**: Delete temporary `-wal` and `-shm` files to prevent startup crashes due to file mismatch.
+    3. **Replace**: Physically move/rename the new database file.
+    4. **Reconnect**: Establish a fresh connection and re-enable WAL mode.
+- **Locking Hierarchy**: Be mindful of the `Arc<RwLock<MainStore>>` (Outer) and `Mutex<Connection>` (Inner) hierarchy. Ensure that restoration and high-concurrency operations are performed as single atomic blocks within the outer lock to prevent Rust-level deadlocks.
diff --git a/RELEASE.md b/RELEASE.md
@@ -2,15 +2,18 @@
 
 # Release Notes
 
-## [1.2.3]
+## [1.2.4]
 
 ### 🪄 Improvements
 
+- **Database Architecture Hardening**: Upgraded the database engine to use **WAL (Write-Ahead Logging)** mode and implemented a 5-second **Busy Timeout**. These changes significantly improve concurrency, allowing the background proxy (CCProxy) and the main chat interface to access the database simultaneously without locking issues.
+- **Atomic Restoration with State Preservation**: Completely refactored the database restoration process. The system now performs a safe, atomic "disconnect-replace-reconnect" sequence that prevents file corruption. It also preserves machine-specific settings (window positions, sizes, and network proxy configurations) during restoration, ensuring a seamless experience when migrating data.
 - **Mission-Critical Stability Hardening**: Performed a comprehensive audit and refactoring of the application's startup sequence. All hardcoded `.expect()` and `.unwrap()` calls in critical paths (logging, database path resolution, and window management) have been replaced with graceful error handling. This ensures the application remains operational even in highly restricted environments like Windows Server 2019.
 - **Graceful Logging Fallback**: The logging system now automatically degrades to console-only output if the designated log directory is unwritable or inaccessible, preventing immediate startup crashes.
 
 ### 🐞 Bug Fixes
 
+- **Production Database Locking**: Resolved a critical "attempt to write a readonly database" error in production environments caused by redundant file handle requests during initialization.
 - **Proxy Routing Precedence**: Resolved a critical routing conflict where generic group paths (e.g., `/{group}/...`) could incorrectly intercept specific functional prefixes like `/switch`, `/compat`, or `/compat_mode`. This fix ensures correct dispatching for all access modes and resolves 404 errors when using combined paths.
 - **Compatibility Mode Alias**: Introduced the `compat` shorthand alias as a convenient alternative to `compat_mode` (e.g., `/group/compat/v1/messages`), improving API call ergonomics.
 - **Proxy Statistics Calibration**: Fixed a critical issue where output tokens were reported as 0 in `tool_compat_mode` and `direct_forward` modes. The system now accurately estimates tokens for **Reasoning/Thinking content** and **Tool Call Arguments** across all supported protocols (OpenAI, Claude, Gemini, Ollama).
diff --git a/RELEASE.zh-CN.md b/RELEASE.zh-CN.md
@@ -2,15 +2,18 @@
 
 # 发布日志
 
-## [1.2.3]
+## [1.2.4]
 
 ### 🪄 改进
 
+- **数据库架构加固**：将数据库引擎升级为 **WAL (Write-Ahead Logging)** 模式，并实现了 5 秒的 **Busy Timeout (忙碌重试)**。这些改进显著提升了并发性能，允许后台代理 (CCProxy) 与主聊天界面同时访问数据库而不会发生锁定冲突。
+- **状态保留的原子化还原**：彻底重构了数据库还原流程。系统现在执行安全的原子级“断开-替换-重连”序列，防止了文件损坏。同时，在还原过程中能够自动保留机器特有的设置（如窗口位置、尺寸、网络代理配置等），确保数据迁移后的无缝体验。
 - **启动路径鲁棒性加固**：对应用程序启动序列进行了全面审计和重构。移除了所有在关键路径（如日志系统、数据库路径解析及窗口管理）中硬编码的 `.expect()` 和 `.unwrap()` 调用。这确保了在 Windows Server 2019 等权限高度受限的环境下，程序仍能平稳启动而不会闪退。
 - **日志系统自动降级**：当日志目录不可写或无法访问时，日志系统现在会自动降级为仅控制台输出模式，彻底消除了由于磁盘写入权限导致的启动 Panic。
 
 ### 🐞 修复
 
+- **生产环境数据库锁定修复**：解决了在生产环境下，由于初始化过程中冗余的文件句柄请求导致的“attempt to write a readonly database”关键错误。
 - **代理路由优先级修复**：解决了通配分组路径（如 `/{group}/...`）可能意外拦截 `/switch`、`/compat` 或 `/compat_mode` 等特定功能前缀的冲突问题。该修复确保了所有访问模式都能正确分发，解决了组合路径下可能出现的 404 错误。
 - **兼容模式别名支持**：新增了 `compat` 简写别名作为 `compat_mode` 的便捷替代方案（例如：`/group/compat/v1/messages`），提升了 API 调用的易用性。
 - **代理统计校准**：修复了在 `工具兼容模式` (tool_compat_mode) 和 `直接转发` (direct_forward) 模式下，输出 Token 统计始终为 0 的问题。现在系统能准确估算所有协议（OpenAI、Claude、Gemini、Ollama）中的**推理/思考内容 (Reasoning/Thinking)** 及**工具调用参数**的 Token 消耗。
diff --git a/chatspeed-docs b/chatspeed-docs
@@ -1 +1 @@
-Subproject commit 5461519c877ec169351c3766e5af483cf5e43e14
+Subproject commit 4af42e44a18136d0ac3635636561b4aa48a57d84
diff --git a/src-tauri/src/commands/setting.rs b/src-tauri/src/commands/setting.rs
@@ -32,7 +32,7 @@
 //!
 
 use crate::constants::*;
-use crate::db::{AiModel, AiSkill, MainStore, ModelConfig};
+use crate::db::{AiModel, AiSkill, MainStore, ModelConfig, StoreError};
 use crate::db::{BackupConfig, DbBackup};
 use crate::libs::fs::{self, get_file_name};
 use crate::tray::create_tray;
@@ -710,18 +710,10 @@ fn upload_logo(image_path: String) -> Result<String> {
 // Backup
 // =================================================
 #[tauri::command]
-pub async fn backup_setting(
-    app: AppHandle,
-    backup_dir: Option<String>,
-) -> Result<()> {
+pub async fn backup_setting(app: AppHandle, backup_dir: Option<String>) -> Result<()> {
     let result = tokio::spawn(async move {
-        DbBackup::new(
-            &app,
-            BackupConfig {
-                backup_dir,
-            },
-        )
-        .and_then(|mut backup| backup.backup_to_directory())
+        DbBackup::new(&app, BackupConfig { backup_dir })
+            .and_then(|mut backup| backup.backup_to_directory())
     })
     .await
     .map_err(|e| AppError::General {
@@ -751,75 +743,59 @@ pub async fn restore_setting(
         "proxyPassword",
     ];
 
-    // 2. Backup current machine-specific configurations
-    let mut preserved_configs = HashMap::new();
-    {
-        let config_store = state.read()?;
-        for &key in &machine_specific_keys {
-            if let Some(value) = config_store.config.get_setting(key) {
-                preserved_configs.insert(key.to_string(), value.clone());
-            }
-        }
-    }
+    // 2. Prepare paths and backup instance
+    let theme_dir = HTTP_SERVER_THEME_DIR.read().clone();
+    let upload_dir = HTTP_SERVER_UPLOAD_DIR.read().clone();
+    let schema_dir = SCHEMA_DIR.read().clone();
+    let shared_dir = SHARED_DATA_DIR.read().clone();
+    let static_dir = HTTP_SERVER_DIR.read().clone();
+    let store_dir = STORE_DIR.read().clone();
+    let mcp_sessions_dir = store_dir.join("mcp_sessions");
+    let main_db_path = store_dir.join("chatspeed.db");
 
-    let result = tokio::spawn(async move {
-        let theme_dir = HTTP_SERVER_THEME_DIR.read().clone();
-        let upload_dir = HTTP_SERVER_UPLOAD_DIR.read().clone();
-        let schema_dir = SCHEMA_DIR.read().clone();
-        let shared_dir = SHARED_DATA_DIR.read().clone();
-        let static_dir = HTTP_SERVER_DIR.read().clone();
-        let store_dir = STORE_DIR.read().clone();
-        let mcp_sessions_dir = store_dir.join("mcp_sessions");
-        DbBackup::new(
-            &app,
-            BackupConfig {
-                backup_dir: Some(backup_dir.clone()),
-            },
-        )
-        .and_then(|db_backup| {
-            db_backup.restore_from_directory(
-                &Path::new(&backup_dir),
-                &Path::new(&*theme_dir),
-                &Path::new(&*upload_dir),
-                &Path::new(&mcp_sessions_dir),
-                &Path::new(&*schema_dir),
-                &Path::new(&*shared_dir),
-                &Path::new(&*static_dir),
-            )
-        })
-    })
-    .await
-    .map_err(|e| AppError::General {
-        message: e.to_string(),
-    })?;
+    let db_backup = DbBackup::new(
+        &app,
+        BackupConfig {
+            backup_dir: Some(backup_dir.clone()),
+        },
+    )
+    .map_err(AppError::Db)?;
 
-    result.map_err(AppError::Db)?;
+    // 3. Decrypt database to a temporary file FIRST
+    let backup_db_file = Path::new(&backup_dir).join("chatspeed.db");
+    let temp_db_path = db_backup
+        .decrypt_to_temp(&backup_db_file, &main_db_path)
+        .map_err(AppError::Db)?;
 
-    // 3. Reload the configuration from the newly restored database file
-    let mut config_store = state.write()?;
-    config_store.reload_config().map_err(AppError::Db)?;
-
-    // 4. Restore the preserved configurations to the new database
-    for key in machine_specific_keys {
-        if let Some(value) = preserved_configs.get(key) {
-            config_store.set_config(key, value).map_err(AppError::Db)?;
-        } else {
-            // If the key didn't exist before, ensure it doesn't exist in the restored DB either
-            let _ = config_store.delete_config(key);
-        }
+    // 4. Perform atomic database restoration
+    {
+        let mut config_store = state
+            .write()
+            .map_err(|e| AppError::Db(StoreError::LockError(e.to_string())))?;
+        config_store
+            .atomic_restore(&temp_db_path, &main_db_path, &machine_specific_keys)
+            .map_err(AppError::Db)?;
     }
 
+    // 5. Restore user files (static assets, etc.)
+    db_backup
+        .restore_user_files(
+            &Path::new(&backup_dir).join("user_files.zip"),
+            &Path::new(&*theme_dir),
+            &Path::new(&*upload_dir),
+            &Path::new(&mcp_sessions_dir),
+            &Path::new(&*schema_dir),
+            &Path::new(&*shared_dir),
+            &Path::new(&*static_dir),
+        )
+        .map_err(AppError::Db)?;
+
     Ok(())
 }
 
 #[tauri::command]
 pub fn get_all_backups(app: AppHandle, backup_dir: Option<String>) -> Result<Vec<String>> {
-    let db_backup = DbBackup::new(
-        &app,
-        BackupConfig {
-            backup_dir,
-        },
-    )?;
+    let db_backup = DbBackup::new(&app, BackupConfig { backup_dir })?;
 
     let backups = db_backup.list_backups().map_err(AppError::Db)?;
     Ok(backups
diff --git a/src-tauri/src/db/backup.rs b/src-tauri/src/db/backup.rs
@@ -45,10 +45,12 @@ impl DbBackup {
 
         #[cfg(not(debug_assertions))]
         let app_dir = {
-            let app_local_data_dir = _app
-                .path()
-                .app_data_dir()
-                .map_err(|e| StoreError::TauriError(format!("Failed to retrieve the application data directory: {}", e)))?;
+            let app_local_data_dir = _app.path().app_data_dir().map_err(|e| {
+                StoreError::TauriError(format!(
+                    "Failed to retrieve the application data directory: {}",
+                    e
+                ))
+            })?;
             std::fs::create_dir_all(&app_local_data_dir)
                 .map_err(|e| StoreError::TauriError(e.to_string()))?;
             app_local_data_dir
@@ -116,39 +118,35 @@ impl DbBackup {
         Ok(backup_path)
     }
 
-    /// Restores a single database from a backup file with decryption
-    fn restore_single_db(&self, backup_path: &Path, target_path: &Path) -> Result<(), StoreError> {
+    /// Decrypts a backup database to a temporary file.
+    pub fn decrypt_to_temp(
+        &self,
+        backup_path: &Path,
+        target_path: &Path,
+    ) -> Result<PathBuf, StoreError> {
         if !backup_path.exists() {
             return Err(StoreError::NotFound(
                 t!("db.backup.file_not_found", path = backup_path.display()).to_string(),
             ));
         }
 
-        // 获取备份目录名称（时间格式）
         let backup_dir_name = backup_path
             .parent()
             .and_then(|p| p.file_name())
             .and_then(|n| n.to_str())
             .unwrap_or("unknown");
 
-        // Use streaming decryption for database
         let temp_file = target_path.with_extension("tmp");
         decrypt_database_streaming(backup_path, &temp_file, backup_dir_name)?;
+        Ok(temp_file)
+    }
 
-        // Atomically replace original file
-        fs::rename(&temp_file, target_path).map_err(|e| {
-            error!("Failed to rename temp database file: {}", e);
-            StoreError::IoError(
-                t!(
-                    "db.backup.failed_to_rename_temp_db",
-                    path = target_path.display(),
-                    error = e.to_string()
-                )
-                .to_string(),
-            )
-        })?;
-
-        Ok(())
+    /// Cleans up SQLite temporary files (-wal, -shm) for a given database path.
+    pub fn cleanup_sqlite_temporaries(db_path: &Path) {
+        let wal_path = db_path.with_extension("db-wal");
+        let shm_path = db_path.with_extension("db-shm");
+        let _ = fs::remove_file(wal_path);
+        let _ = fs::remove_file(shm_path);
     }
 
     /// Lists all database backup directories in the backup directory, sorted by modification time.
@@ -260,65 +258,6 @@ impl DbBackup {
         Ok(())
     }
 
-    /// Restores databases and user files from a backup directory
-    ///
-    /// # Arguments
-    ///
-    /// * `backup_dir` - Path to the backup directory
-    /// * `theme_dir` - Path to restore theme files
-    /// * `upload_dir` - Path to restore uploaded files
-    /// * `mcp_sessions_dir` - Path to restore MCP sessions
-    /// * `schema_dir` - Path to restore schema files
-    /// * `shared_dir` - Path to restore shared files
-    /// * `static_dir` - Path to restore static files
-    ///
-    /// # Errors
-    ///
-    /// Returns a `StoreError` if any restore operation fails
-    pub fn restore_from_directory(
-        &self,
-        backup_dir: &Path,
-        theme_dir: &Path,
-        upload_dir: &Path,
-        mcp_sessions_dir: &Path,
-        schema_dir: &Path,
-        shared_dir: &Path,
-        static_dir: &Path,
-    ) -> Result<(), StoreError> {
-        // Verify backup directory exists
-        if !backup_dir.exists() || !backup_dir.is_dir() {
-            return Err(StoreError::NotFound(
-                t!(
-                    "db.backup.dir_not_found_for_restore",
-                    path = backup_dir.display()
-                )
-                .to_string(),
-            ));
-        }
-
-        // Check for chatspeed.db
-        let main_backup = backup_dir.join("chatspeed.db");
-        if main_backup.exists() {
-            self.restore_single_db(&main_backup, &self.main_db_path)?;
-        }
-
-        // Check for user_files.zip
-        let user_files = backup_dir.join("user_files.zip");
-        if user_files.exists() {
-            self.restore_user_files(
-                &user_files,
-                theme_dir,
-                upload_dir,
-                mcp_sessions_dir,
-                schema_dir,
-                shared_dir,
-                static_dir,
-            )?;
-        }
-
-        Ok(())
-    }
-
     /// Restores user files from a backup zip file
     ///
     /// # Arguments
@@ -334,7 +273,7 @@ impl DbBackup {
     /// # Errors
     ///
     /// Returns a `StoreError` if restore operation fails
-    fn restore_user_files(
+    pub fn restore_user_files(
         &self,
         zip_path: &Path,
         theme_dir: &Path,
diff --git a/src-tauri/src/db/main_store.rs b/src-tauri/src/db/main_store.rs
diff --git a/src-tauri/src/db/sql/migrations/manager.rs b/src-tauri/src/db/sql/migrations/manager.rs
