# Restic 跨平台备份与 rsync 同步手册
> 适用场景：在 Windows / Debian 上使用 Restic 做本地加密备份，再用 rsync 将仓库单向同步到其他目录（本地磁盘、外接盘、网盘挂载目录等）。
>
> 核心原则：**Restic 负责加密、去重、快照；rsync 负责单向搬运仓库文件。**
---
## 目录
- [一、环境准备](#一环境准备)
- [二、Restic 仓库初始化](#二restic-仓库初始化)
- [三、执行备份](#三执行备份)
- [四、使用 rsync 同步仓库](#四使用-rsync-同步仓库)
- [五、恢复验证](#五恢复验证)
- [六、自动化建议](#六自动化建议)
- [七、常见缺陷与注意事项](#七常见缺陷与注意事项)
- [附录：常用命令速查](#附录常用命令速查)
---
## 一、环境准备
### 1.1 安装 Restic
**Windows**
- 官方 Release 下载 `restic_*_windows_amd64.zip`，解压后把 `restic.exe` 放到 `C:\Windows\System32`（需管理员），或任意目录后用完整路径调用。
**Debian**
```bash
sudo apt update
sudo apt install -y restic
```
验证：
```bash
restic version
```
### 1.2 安装 rsync
**Windows**
rsync 在 Windows 无原生支持，推荐用 **WSL**。安装 WSL 后，在 WSL 终端里通过 `/mnt/c`、`/mnt/d` 访问 Windows 盘符。
或者使用robocopy替代，robocopy用法如下：
robocopy <源目录> <目标目录> [文件] [选项]
```bash
robocopy F:\restic-repo G:\backup-mirror\restic-repo /E /MIR /R:2 /W:1 /NP /NFL /NDL /UNILOG:C:\restic\sync.log
```
参数与作用
- /E 复制所有子目录，包括空目录
- /MIR 镜像模式：使目标与源完全一致（相当于 rsync 的 --delete）
- /R:2 失败重试 2 次（默认 100 万次，必须限制）
- /W:1 重试间隔 1 秒
- /NP 不显示进度百分比
- /NFL /NDL 不列出文件/目录名，减少日志噪音
- /UNILOG 输出 Unicode 日志到指定文件
- 注意事项：
- /MIR 会删除目标端多余的文件。如果你暂时不想删除（想保留冗余文件），去掉 /MIR，改用 /E 即可。
- Robocopy 有长路径限制（超过 250 字符的文件名可能被跳过且不报错）。如果你的 Restic 仓库路径都很短，这不是问题。
**Debian**
```bash
sudo apt install -y rsync
```
### 1.3 创建密码文件
Restic 仓库密码是唯一解密凭证，丢失无法恢复。
**Windows（PowerShell，管理员）**
#windows下直接写入txt文件即可
**Debian**
```bash
sudo mkdir -p /etc/restic
echo 'YourStrongPassword' | sudo tee /etc/restic/restic-pw > /dev/null
sudo chmod 600 /etc/restic/restic-pw
```
> 安全提示：不要把密码直接写在脚本、环境变量或命令历史里。
---
## 二、Restic 仓库初始化
### 2.1 规划路径
示例：
| 平台 | 源目录 | 本地仓库 |
|---|---|---|
| Windows | `D:\Documents`、`E:\Projects` | `F:\restic-repo` |
| Debian | `/home/user/data`、`/var/www` | `/backup/restic-repo` |
### 2.2 初始化仓库
**Windows**
```powershell
restic -r F:\restic-repo --password-file C:\restic\restic-pw init
```
**Debian**
```bash
restic -r /backup/restic-repo --password-file /etc/restic/restic-pw init
```
初始化后会生成 `config`、`data/`、`index/`、`keys/`、`snapshots/` 等目录。
### 2.3 机械硬盘优化：pack 大小
机械硬盘建议把 pack 大小从默认 16 MiB 调到 **64 MiB**，减少碎片、提升顺序读写。
**Windows**
```powershell
$env:TMP = "F:\restic-temp"
$env:TEMP = "F:\restic-temp"
New-Item -ItemType Directory -Force -Path F:\restic-temp | Out-Null
```
**Debian**
```bash
export TMPDIR=/backup/restic-temp
mkdir -p /backup/restic-temp
```
> Windows 上 Restic 只认 `TMP` / `TEMP`，不认 `TMPDIR`。
>
> 临时空间估算：`pack 大小 × (连接数 + 1)`。本地后端默认连接数约 2，64 MiB pack 至少预留约 192 MiB。
---
## 三、执行备份
### 3.1 首次全量备份
**Windows**
```powershell
restic -r F:\restic-repo --password-file C:\restic\restic-pw `
backup --pack-size 64 `
D:\Documents E:\Projects `
--exclude="*.tmp" --exclude="D:/Documents/cache"
```
**Debian**
```bash
restic -r /backup/restic-repo --password-file /etc/restic/restic-pw \
backup --pack-size 64 \
/home/user/data /var/www \
--exclude="*.log" --exclude="/var/www/cache"
```
> 注意：`--pack-size` 是 `backup` 子命令的选项，必须放在 `backup` 之后。
### 3.2 后续增量备份
命令与首次相同。Restic 会自动识别已有快照，只上传新增或变化的数据块。
### 3.3 查看快照
```bash
restic -r <repo> --password-file <pwfile> snapshots
```
### 3.4 清理旧快照与回收空间
```bash
# 保留最近 7 天、最近 4 周、最近 6 月
restic -r <repo> --password-file <pwfile> forget \
--keep-daily 7 --keep-weekly 4 --keep-monthly 6
# 真正删除未引用数据并合并小 pack
restic -r <repo> --password-file <pwfile> prune
```
> `prune` 会重写部分 pack，rsync 下次会整包重传这些新文件。
---
## 四、使用 rsync 同步仓库
### 4.1 核心原则
- rsync 是**单向**的：只从源仓库复制到目标目录。
- Restic 仓库里的 pack/index/snapshot 一旦生成就不再局部修改，所以 rsync 的文件级增量足够高效。
- **绝对禁止** rsync 与 `restic backup` / `restic prune` 同时运行。
- 推荐顺序：**backup → forget/prune → rsync**。这样目标端能同步到删除结果。
### 4.2 同步命令
**Windows（在 WSL 中执行）**
```bash
# 本地 Windows 目录之间同步
rsync -avP --no-perms --no-owner --no-group \
/mnt/f/restic-repo/ /mnt/g/backup-mirror/restic-repo/
# 同步到远程主机
rsync -avP --no-perms --no-owner --no-group -e ssh \
/mnt/f/restic-repo/ user@remote:/backup/restic-repo/
```
**Debian**
```bash
# 本地同步
rsync -avP /backup/restic-repo/ /mnt/external/restic-repo/
# 远程同步
rsync -avP -e ssh /backup/restic-repo/ user@remote:/backup/restic-repo/
```
**参数说明**
| 参数 | 作用 |
|---|---|
| `-a` | 归档模式，保留权限、时间戳等 |
| `-v` | 详细输出 |
| `-P` | 显示进度 + 断点续传 |
| `-z` | 压缩传输，对已压缩 pack 无意义，建议省略 |
| `--delete` | 让目标与源完全一致，删除目标多余文件（慎用） |
| `--no-perms --no-owner --no-group` | WSL 跨 NTFS 时避免权限报错 |
> 尾部斜杠：`/repo/` 同步目录内容；`/repo` 会在目标端创建同名子目录。
>
> 如果希望 prune 后目标端也回收空间，需要加 `--delete`，但必须确保源仓库稳定、没有正在运行的 Restic 写操作。
### 4.3 prune 后的传输量
日常增量备份后，rsync 只传新增文件。`prune` 后，Restic 会重写部分 pack，这些新 pack 对 rsync 是全新文件，需要整包传输。这是正常现象。
---
## 五、恢复验证
### 5.1 查看快照与文件
```bash
restic -r <repo> --password-file <pwfile> snapshots
restic -r <repo> --password-file <pwfile> ls latest
```
### 5.2 恢复
```bash
# 恢复整个快照
restic -r <repo> --password-file <pwfile> restore latest --target /restore/destination
# 只恢复指定路径
restic -r <repo> --password-file <pwfile> restore <快照>:<快照内的子路径> --target <恢复的目标位置>
#或者使用--include 来筛选要恢复的文件，路径同样要写成快照内的格式（以 / 开头）例如：
restic -r <repo> --password-file <pwfile> restore latest \
--target /restore/destination --include /path/to/file
```
### 5.3 仓库检查
```bash
# 快速检查元数据
restic -r <repo> --password-file <pwfile> check
# 完整读取校验（耗流量、耗时，但最可靠）
restic -r <repo> --password-file <pwfile> check --read-data
```
### 5.4 从网盘/镜像恢复
如果 rsync 的目标是网盘挂载目录，恢复时先把仓库从网盘同步回本地磁盘，再执行 `restic restore`。不要把网盘挂载目录直接当 Restic 仓库使用，以免 API 限速或文件锁导致异常。
---
## 六、自动化建议
### 6.1 Windows 任务计划
创建 `C:\restic\backup.ps1`：
```powershell
$env:TMP = "F:\restic-temp"
$env:TEMP = "F:\restic-temp"
# 1. 备份
restic -r F:\restic-repo --password-file C:\restic\restic-pw `
backup --pack-size 64 D:\Documents E:\Projects
# 2. 清理旧快照（可选）
restic -r F:\restic-repo --password-file C:\restic\restic-pw `
forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6
# 3. 回收空间（可选，耗时）
restic -r F:\restic-repo --password-file C:\restic\restic-pw prune
# 4. 同步镜像（必须在上面的 Restic 操作全部结束后）
wsl rsync -avP --no-perms --no-owner --no-group `
/mnt/f/restic-repo/ /mnt/g/backup-mirror/restic-repo/
```
在“任务计划程序”中设置每日运行，并确保上一次任务未结束时不会并发启动。
### 6.2 Debian systemd timer
创建 `/usr/local/bin/restic-backup.sh`：
```bash
#!/bin/bash
set -e
export TMPDIR=/backup/restic-temp
REPO=/backup/restic-repo
PW=/etc/restic/restic-pw
MIRROR=/mnt/external/restic-repo
# 1. 备份
restic -r "$REPO" --password-file "$PW" \
backup --pack-size 64 /home/user/data /var/www
# 2. 清理旧快照（可选）
restic -r "$REPO" --password-file "$PW" \
forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6
# 3. 回收空间（可选）
restic -r "$REPO" --password-file "$PW" prune
# 4. 同步镜像
rsync -avP "$REPO/" "$MIRROR/"
```
赋予执行权限：
```bash
sudo chmod +x /usr/local/bin/restic-backup.sh
```
创建 `/etc/systemd/system/restic-backup.service`：
```ini
[Unit]
Description=Restic Backup
After=network.target
[Service]
Type=oneshot
ExecStart=/usr/local/bin/restic-backup.sh
```
创建 `/etc/systemd/system/restic-backup.timer`：
```ini
[Unit]
Description=Daily Restic Backup
[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true
[Install]
WantedBy=timers.target
```
启用：
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now restic-backup.timer
```
### 6.3 关键纪律
- rsync 与 Restic 写操作必须串行。
- 不要在 rsync 过程中运行 `restic backup` 或 `restic prune`。
- 如果 Restic 异常中断，可用 `restic unlock` 清除残留锁。
---
## 七、常见缺陷与注意事项
1. **`--pack-size` 位置**：它是 `backup` 子命令选项，应写成 `restic ... backup --pack-size 64 ...`，不要放在 `backup` 前面。
2. **Windows 临时目录**：Restic 只认 `TMP` / `TEMP`，不认 `TMPDIR`。
3. **WSL 中 rsync 权限**：跨 NTFS 时建议加 `--no-perms --no-owner --no-group`，避免权限报错。
4. **rsync 与 prune 并发**：会导致上传不完整或目标端残留旧文件。必须串行。
5. **`--delete` 慎用**：它能回收目标端空间，但源仓库必须稳定。确认方向正确再使用。
6. **prune 后传输量变大**：新 pack 会被 rsync 整包重传，属于正常代价。
7. **密码文件权限**：Windows 用 `icacls`，Debian 用 `chmod 600`。密码丢失无法恢复。
8. **systemd 脚本缺失**：本版已补全 `restic-backup.sh` 示例。
9. **Windows 任务计划不完整**：本版已补全 backup + forget + prune + rsync 的完整脚本。
10. **网盘挂载目录**：不建议直接作为 Restic 仓库，建议先本地备份，再 rsync 到网盘挂载目录。
11. **Restic 锁**：异常中断后可能残留锁，用 `restic unlock` 处理。
12. **恢复验证**：定期执行 `restic check`，重要数据建议 `--read-data`。
---
## 附录：常用命令速查
| 操作 | Windows | Debian |
|---|---|---|
| 初始化 | `restic -r F:\restic-repo --password-file C:\restic\restic-pw init` | `restic -r /backup/restic-repo --password-file /etc/restic/restic-pw init` |
| 备份 | `restic -r F:\restic-repo --password-file C:\restic\restic-pw backup --pack-size 64 D:\Documents` | `restic -r /backup/restic-repo --password-file /etc/restic/restic-pw backup --pack-size 64 /home/user/data` |
| 查看快照 | `restic -r F:\restic-repo --password-file C:\restic\restic-pw snapshots` | 替换路径同上 |
| 恢复 | `restic -r F:\restic-repo --password-file C:\restic\restic-pw restore latest --target F:\restore` | 替换路径同上 |
| rsync 同步 | `rsync -avP --no-perms --no-owner --no-group /mnt/f/restic-repo/ /mnt/g/mirror/` | `rsync -avP /backup/restic-repo/ /mnt/ext/mirror/` |
| 检查 | `restic -r F:\restic-repo --password-file C:\restic\restic-pw check` | 替换路径同上 |
| 解锁 | `restic -r F:\restic-repo --password-file C:\restic\restic-pw unlock` | 替换路径同上 |
附软件包
