//! zip 快照备份:整库打包上传 + 远端轮转 + 恢复。 //! //! # 为什么「快照」比「双向同步」更该先做 //! //! 规划 §3.6 的判断:对「只是要个备份」的用户,一次上传一个完整 zip 比双向同步 //! **可靠得多** —— 同步要考虑冲突、删除传播、时钟偏差;快照只有一个动作(上传), //! 失败就是失败,不会在半途产生「一半新一半旧」的库。 //! //! 因此本模块与 `webdav/sync.rs` 是两条独立路径,用的是同一个客户端。 //! //! # 打包内容 //! //! 库内全部 `.md` 与 `assets/` 下的附件,外加一份 `thing-notes-manifest.json` //! (记录快照时间、文件数、格式版本)。**不打包 `.editor/`**:里面是索引与同步基线, //! 属于本机私有数据,跟着快照跑到另一台机器上只会误导那边的基线判断。 //! //! # 轮转 //! //! 上传后列出远端 `backups/` 下的快照,按**文件名里的时间戳**倒序保留 //! [`WebdavSettings::backup_keep`] 份,其余删除。用文件名排序而不是远端 mtime: //! 各家服务端的 mtime 精度与时钟都不一致,而文件名是我们自己写的、单调递增。 use std::io::Write; use std::path::{Path, PathBuf}; use super::webdav::client::WebdavClient; use crate::editor::library; use crate::editor::types::{BackupReport, BackupSnapshot, WebdavSettings}; /// 远端存放快照的目录(相对远端根)。 pub const BACKUP_DIR: &str = "backups"; /// 快照文件名前缀。 const SNAPSHOT_PREFIX: &str = "thing-notes-"; /// 清单文件名(打包进 zip,供恢复时校验)。 const MANIFEST_NAME: &str = "thing-notes-manifest.json"; /// 快照清单。 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] #[serde(rename_all = "camelCase")] struct SnapshotManifest { version: u32, created_at: String, files: u32, } /// 打包库根为 zip 字节流(不触网,便于单测)。 pub fn build_snapshot(root: &Path) -> Result<(Vec, u32), String> { library::ensure_library(root)?; let cursor = std::io::Cursor::new(Vec::new()); let mut writer = zip::ZipWriter::new(cursor); let options: zip::write::FileOptions<'_, ()> = zip::write::FileOptions::default() .compression_method(zip::CompressionMethod::Deflated); let mut files = 0u32; for entry in walkdir::WalkDir::new(root) .max_depth(library::MAX_DEPTH) .into_iter() .filter_map(Result::ok) { if !entry.file_type().is_file() { continue; } let rel = library::rel_string(root, entry.path()); if rel.is_empty() { continue; } // `.editor/` 是本机私有数据(索引 + 同步基线),不进快照 if rel.split('/').any(|part| part.starts_with('.')) { continue; } let bytes = match std::fs::read(entry.path()) { Ok(bytes) => bytes, Err(e) => { crate::logger::log_warn("editor", &format!("快照跳过 {rel}(读取失败: {e})")); continue; } }; writer .start_file(rel.clone(), options) .map_err(|e| format!("写入快照条目失败: {e}"))?; writer .write_all(&bytes) .map_err(|e| format!("写入快照内容失败: {e}"))?; files += 1; } // 清单最后写:它要记录真实打包到的文件数 let manifest = SnapshotManifest { version: 1, created_at: chrono::Local::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true), files, }; let manifest_bytes = serde_json::to_vec_pretty(&manifest) .map_err(|e| format!("序列化快照清单失败: {e}"))?; writer .start_file(MANIFEST_NAME, options) .map_err(|e| format!("写入快照清单失败: {e}"))?; writer .write_all(&manifest_bytes) .map_err(|e| format!("写入快照清单内容失败: {e}"))?; let cursor = writer.finish().map_err(|e| format!("完成快照打包失败: {e}"))?; Ok((cursor.into_inner(), files)) } /// 上传一份快照并做轮转。返回备份报告。 pub fn upload_snapshot( root: &Path, settings: &WebdavSettings, client: &WebdavClient, ) -> Result { let (bytes, files) = build_snapshot(root)?; let name = format!( "{SNAPSHOT_PREFIX}{}.zip", chrono::Local::now().format("%Y%m%d-%H%M%S") ); let remote_path = format!("{BACKUP_DIR}/{name}"); client.put(&remote_path, bytes.clone())?; let pruned = prune_snapshots(client, settings.backup_keep)?; Ok(BackupReport { name, bytes: bytes.len() as u64, files, pruned, }) } /// 轮转:只保留最新的 `keep` 份。 pub fn prune_snapshots(client: &WebdavClient, keep: u32) -> Result, String> { let keep = keep.max(1) as usize; let mut snapshots = list_snapshots(client)?; if snapshots.len() <= keep { return Ok(Vec::new()); } // 文件名里的时间戳是 `%Y%m%d-%H%M%S`,字典序即时间序 snapshots.sort_by(|a, b| a.name.cmp(&b.name)); let outdated = snapshots.len() - keep; let mut pruned = Vec::new(); for snapshot in snapshots.into_iter().take(outdated) { if let Err(e) = client.delete(&format!("{BACKUP_DIR}/{}", snapshot.name)) { crate::logger::log_warn("editor", &format!("删除旧快照 {} 失败: {e}", snapshot.name)); continue; } pruned.push(snapshot.name); } Ok(pruned) } /// 列出远端已有的快照。 pub fn list_snapshots(client: &WebdavClient) -> Result, String> { let entries = client.list(BACKUP_DIR)?; let Some(entries) = entries else { return Ok(Vec::new()); }; Ok(entries .into_iter() .filter(|entry| !entry.is_dir) .filter(|entry| { entry .rel_path .rsplit('/') .next() .map(|name| name.starts_with(SNAPSHOT_PREFIX) && name.ends_with(".zip")) .unwrap_or(false) }) .map(|entry| BackupSnapshot { name: entry .rel_path .rsplit('/') .next() .unwrap_or_default() .to_string(), size: entry.size, modified: entry.modified, }) .collect()) } /// 从快照恢复(**不覆盖已存在的本地文件**)。 /// /// 保守策略的理由:恢复的典型场景是「换机器」或「误删了几篇」。前者的本地基本是空的, /// 后者的本地有用户最近的工作 —— 覆盖会把「误删之前写的东西」一起冲掉。 /// 需要时用户可以先在资源管理器里移走旧库,再恢复。 pub fn restore_snapshot( root: &Path, client: &WebdavClient, name: &str, ) -> Result<(u32, u32), String> { if name.contains('/') || name.contains('\\') || name.contains("..") { return Err("快照名不合法".to_string()); } let bytes = client.get(&format!("{BACKUP_DIR}/{name}"))?; let mut archive = zip::ZipArchive::new(std::io::Cursor::new(bytes)) .map_err(|e| format!("读取快照失败: {e}"))?; let mut written = 0u32; let mut kept = 0u32; for index in 0..archive.len() { let mut file = archive .by_index(index) .map_err(|e| format!("读取快照条目失败: {e}"))?; let Some(entry_path) = file.enclosed_name().map(|p| p.to_path_buf()) else { // `enclosed_name` 会拒绝 `..` 与绝对路径 —— 恶意快照不能写到库外 crate::logger::log_warn("editor", "快照里有越界路径,已跳过"); continue; }; let rel = entry_path.to_string_lossy().replace('\\', "/"); if rel == MANIFEST_NAME || file.is_dir() { continue; } let target = library::safe_join(root, &rel)?; if target.exists() { kept += 1; continue; } if let Some(parent) = target.parent() { std::fs::create_dir_all(parent).map_err(|e| format!("创建目录失败: {e}"))?; } let mut out = Vec::new(); std::io::Read::read_to_end(&mut file, &mut out) .map_err(|e| format!("读取快照内容失败: {e}"))?; std::fs::write(&target, out).map_err(|e| format!("写入 {rel} 失败: {e}"))?; written += 1; } Ok((written, kept)) } /// 一次完整的「同步 + 备份」会话入口(命令层用)。 /// /// 返回(同步报告, 可选备份报告)。`with_backup` 为真时在同步之后追加一次快照 —— /// 「先同步再备份」的顺序是刻意的:备份应当是**同步之后的一致状态**, /// 而不是把一次半途失败的同步结果定格下来。 pub fn sync_then_backup( root: &Path, settings: &WebdavSettings, client: &WebdavClient, app: &tauri::AppHandle, with_backup: bool, ) -> Result<(super::webdav::sync::SyncReport, Option), String> { let (plan, mut state, remote) = super::webdav::sync::build_plan(root, settings, client)?; let runner = super::webdav::sync::SyncRunner::new(client, root, app, plan.actions.len()); let report = runner.run(&plan, &mut state, &remote); // 只有「没有失败」时才推进基线:失败的一轮如果把基线写下去, // 那些没传成功的文件会被当成「已同步」,下次同步就静默漏掉了 if report.failed == 0 { state.last_sync = chrono::Local::now().timestamp_millis().max(0) as u64; if let Err(e) = state.save(root) { crate::logger::log_warn("editor", &format!("保存同步基线失败: {e}")); } } else { crate::logger::log_warn( "editor", &format!("本轮有 {} 条失败,不推进同步基线", report.failed), ); // 仍然保存「成功的那些」:SyncState 是按条更新的,未处理的条目保持旧基线, // 于是下一轮会把它们重新算作差异并重试 if let Err(e) = state.save(root) { crate::logger::log_warn("editor", &format!("保存同步基线失败: {e}")); } } let backup = if with_backup { Some(upload_snapshot(root, settings, client)?) } else { None }; Ok((report, backup)) } /// 本地临时快照目录(供「导出快照到本地」与调试用)。 /// /// 与 [`upload_snapshot`] 共用 [`build_snapshot`],区别只是落盘而不是上传 —— /// 「我要一份备份,但不想连远端」是个很常见的诉求(比如先手动拷到网盘)。 pub fn snapshot_to_file(root: &Path, dest: &Path) -> Result { let (bytes, _) = build_snapshot(root)?; if let Some(parent) = dest.parent() { std::fs::create_dir_all(parent).map_err(|e| format!("创建目录失败: {e}"))?; } std::fs::write(dest, &bytes).map_err(|e| format!("写入快照失败: {e}"))?; Ok(bytes.len() as u64) } /// 库根的默认快照落点(用户点「导出快照到本地」时用)。 pub fn default_snapshot_path(root: &Path) -> PathBuf { root.join(format!( "{SNAPSHOT_PREFIX}{}.zip", chrono::Local::now().format("%Y%m%d-%H%M%S") )) } #[cfg(test)] mod tests { use super::*; fn temp_root(tag: &str) -> PathBuf { let root = std::env::temp_dir().join(format!("thing-notes-backup-{tag}-{}", std::process::id())); let _ = std::fs::remove_dir_all(&root); std::fs::create_dir_all(root.join("assets")).unwrap(); root } #[test] fn snapshot_excludes_private_dir() { let root = temp_root("build"); std::fs::write(root.join("a.md"), "# A").unwrap(); std::fs::create_dir_all(root.join("sub")).unwrap(); std::fs::write(root.join("sub/b.md"), "# B").unwrap(); std::fs::write(root.join("assets/pic.png"), [1u8, 2, 3]).unwrap(); std::fs::create_dir_all(root.join(".editor")).unwrap(); std::fs::write(root.join(".editor/editor.db"), "索引不该进快照").unwrap(); let (bytes, files) = build_snapshot(&root).unwrap(); assert_eq!(files, 3, "两篇笔记 + 一个附件"); assert!(!bytes.is_empty()); let mut archive = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap(); let names: Vec = (0..archive.len()) .map(|i| archive.by_index(i).unwrap().name().to_string()) .collect(); assert!(names.contains(&"a.md".to_string()), "{names:?}"); assert!(names.contains(&"sub/b.md".to_string()), "{names:?}"); assert!(names.contains(&"assets/pic.png".to_string()), "{names:?}"); assert!(names.contains(&MANIFEST_NAME.to_string()), "{names:?}"); assert!( !names.iter().any(|n| n.starts_with(".editor")), "私有目录不该进快照: {names:?}" ); let _ = std::fs::remove_dir_all(&root); } #[test] fn restore_does_not_overwrite_existing_files() { let root = temp_root("restore"); std::fs::write(root.join("a.md"), "新版").unwrap(); std::fs::write(root.join("b.md"), "旧版").unwrap(); let (bytes, _) = build_snapshot(&root).unwrap(); let _ = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); std::fs::write(root.join("a.md"), "本机已有内容").unwrap(); // 直接走「解包到库根」的那段逻辑(用本地 zip 代替远端下载) let mut archive = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap(); let mut kept = 0u32; for index in 0..archive.len() { let mut file = archive.by_index(index).unwrap(); let Some(path) = file.enclosed_name().map(|p| p.to_path_buf()) else { continue; }; let rel = path.to_string_lossy().replace('\\', "/"); if rel == MANIFEST_NAME || file.is_dir() { continue; } let target = library::safe_join(&root, &rel).unwrap(); if target.exists() { kept += 1; continue; } let mut out = Vec::new(); std::io::Read::read_to_end(&mut file, &mut out).unwrap(); std::fs::write(&target, out).unwrap(); } assert_eq!(kept, 1, "已存在的 a.md 应被跳过"); assert_eq!(std::fs::read_to_string(root.join("a.md")).unwrap(), "本机已有内容"); assert_eq!(std::fs::read_to_string(root.join("b.md")).unwrap(), "旧版"); let _ = std::fs::remove_dir_all(&root); } #[test] fn snapshot_file_writing() { let root = temp_root("to-file"); std::fs::write(root.join("a.md"), "# A").unwrap(); let dest = root.join("out.zip"); let size = snapshot_to_file(&root, &dest).unwrap(); assert!(size > 0); assert!(dest.is_file()); let _ = std::fs::remove_dir_all(&root); } }