Files
Thing/src-tauri/src/editor/backup.rs
T
2026-10-10 14:29:48 +08:00

382 lines
15 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 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<u8>, 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<BackupReport, String> {
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<Vec<String>, 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<Vec<BackupSnapshot>, 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<BackupReport>), 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<u64, String> {
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<String> = (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);
}
}