This commit is contained in:
zhongluofeng committed 2026-10-10 14:29:48 +08:00
1 parent ad987111a3
commit c9e61f38c5
89 files changed
+11775 -3155

No files matched your search

+381
View File
@@ -0,0 +1,381 @@
//! 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);
}
}