Plakar 社区版 1.1.8 常用 CLI 命令与工具详解

目标：把 Plakar 社区版 1.1.8 的日常命令一次讲透——备份、浏览、检索、对比、校验、恢复、复制、删除、清理、归档、同步与集成包管理，每条命令配真实参数组合与实测回显，并给出「误删源数据 → 快照恢复」的故障演练全记录。全部命令与输出在 Ubuntu 22.04.5 LTS（x86_64）+ Plakar v1.1.8 实测通过，实测日期 2026-10-30。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
软件版本：Plakar v1.1.8（社区版，deb 包版本号 1.1.8-1，plakar version 回显 plakar/v1.1.8）
实测仓库：/srv/backups（本地 Kloset 仓库，加密，口令经 PLAKAR_PASSPHRASE=q1w2e3r4 注入）；备份源目录 /srv/demo-docs
实测快照：f7e99ead（/srv/demo-docs 全目录）、225488c3（/srv/demo-docs/configs 子目录）、ec109d75（带 nightly 标签的重复备份）等
实测日期：2026-10-30

二、工具概览

plakar 是单一二进制，所有能力通过子命令提供。按用途分组：

分组	子命令	用途
仓库与快照管理	`create` / `at` / `info` / `ls` / `backup` / `store`	建库、定位仓库、查看元数据、列快照、备份、仓库别名
内容浏览与恢复	`locate` / `cat` / `digest` / `diff` / `restore` / `destination`	检索、读取、校验、对比、恢复
快照维护	`dup` / `rm` / `prune` / `check` / `maintenance` / `policy`	复制、删除、按策略清理、完整性校验、仓库维护、保留策略
归档与同步	`archive` / `ptar` / `sync`	归档交付、自包含加密归档、仓库间同步
服务与集成	`server` / `ui` / `source` / `pkg`	远程仓库端点、Web 界面、备份源定义、集成包管理
辅助	`version` / `help` / `man`	版本、内置帮助（man 渲染）

三条通用约定（全文适用）：

仓库定位：plakar at <location> <子命令>，location 可以是本地路径、http://host:9876、或 @store 别名（别名机制见配置篇 5.2 节）；
内建帮助：plakar help <子命令> 直接渲染对应 man 页（如 plakar help backup），无需 man-db；
删除类命令两阶段：rm / prune 默认只预演（dry-run），必须追加 -apply 才真正执行。

三、前置条件

已按《Ubuntu 22.04 安装 Plakar 社区版 1.1.8 指南》完成安装；
已建仓库并完成首次备份（export PLAKAR_PASSPHRASE=q1w2e3r4 后 plakar at /srv/backups create）；
快照元数据、仓库目录结构与数据管道参数的原理性解读见《Plakar 社区版 1.1.8 介绍与选型指南》第三、四章，本文不再展开。

四、仓库与快照管理命令详解

4.1 at 与 create：仓库定位与建库

create 建库、at 定位仓库，用法与加密参数详见配置篇 5.1 节。要点：create 成功静默返回（rc=0）；后续所有命令都以 plakar at /srv/backups <子命令> 形式执行，或用环境变量 PLAKAR_REPOSITORY 省略前缀。

4.2 backup：创建快照

实测带命名与标签备份（回显含恢复路径确认行与耗时汇总）：

$ plakar at /srv/backups backup -name prod-docs /srv/demo-docs
f7e99ead: OK ✓ /srv/demo-docs/docs/report-v1.bin
f7e99ead: backup completed without errors in 21.834503ms (in: 0 B, out: 979 KiB)

重复备份因去重几乎零成本（in: 0 B 表示没有新数据块入库）。带 -tag 的备份在 ls 中可见标签：

$ plakar at /srv/backups ls -tags nightly
2026-10-30T11:46:57Z   ec109d75   792 KiB        0s /srv/demo-docs tags=nightly
2026-10-30T11:45:34Z   b0239ef3   791 KiB        0s /srv/demo-docs

-name、-tag、-ignore、-dry-run、-check 等全部行为参数的语义表见配置篇 5.5 节。

4.3 ls：快照列表与文件清单

不带参数列出快照级清单（时间/短 ID/逻辑大小/耗时/路径）：

$ plakar at /srv/backups ls
2026-10-30T11:58:47Z   f7e99ead   792 KiB        0s /srv/demo-docs
2026-10-30T11:57:13Z   225488c3      52 B        0s /srv/demo-docs/configs

对单个快照递归列出文件明细（权限、属主、类型标记 L 为符号链接）：

$ plakar at /srv/backups ls f7e99ead
2026-10-30T11:43:42Z drwxr-xr-x     root     root  4.0 KiB /srv/demo-docs/configs
2026-10-30T11:43:42Z -rw-r--r--     root     root     52 B /srv/demo-docs/configs/site.conf
2026-10-30T11:43:42Z drwxr-xr-x     root     root  4.0 KiB /srv/demo-docs/docs
2026-10-30T11:43:42Z -rw-r--r--     root     root   23 KiB /srv/demo-docs/docs/numbers.txt
2026-10-30T11:43:42Z Lrwxrwxrwx     root     root     29 B /srv/demo-docs/docs/readme-link.md -> /srv/demo-docs/docs/readme.md
2026-10-30T11:43:42Z -rw-r--r--     root     root     56 B /srv/demo-docs/docs/readme.md
2026-10-30T11:43:42Z -rw-r--r--     root     root  256 KiB /srv/demo-docs/docs/report-v1.bin
2026-10-30T11:43:42Z drwxr-xr-x     root     root  4.0 KiB /srv/demo-docs/photos
2026-10-30T11:43:42Z -rw-r--r--     root     root  512 KiB /srv/demo-docs/photos/img-001.raw

4.4 info：仓库与快照元数据

info 不带参数输出仓库级参数（分块/哈希/压缩/加密全套与仓库统计），带快照 ID 输出该快照完整元数据（VFS 根哈希、Importer、Context 命令行、Summary 统计）。⚠️ 注意命令形式是 info <快照ID>——实测 info snapshot <ID> 会报 plakar: too many arguments。完整回显与逐段解读见介绍篇 3.3/3.4 节。

五、内容浏览与恢复命令详解

5.1 locate：跨快照路径搜索

不指定快照时在全仓库搜索路径模式，返回「快照:路径」对：

$ plakar at /srv/backups locate site.conf
f7e99ead:/srv/demo-docs/configs/site.conf
225488c3:/srv/demo-docs/configs/site.conf

5.2 cat：直接读取快照内文件

不用恢复、直接输出快照内文件内容：

$ plakar at /srv/backups cat f7e99ead:/srv/demo-docs/docs/readme.md
Plakar is an open-source backup solution by PlakarKorp. UPDATED-FOR-DIFF-TEST

5.3 digest：单文件摘要校验

对快照内文件计算 SHA256，可与源文件 sha256sum 对账：

$ plakar at /srv/backups digest f7e99ead:/srv/demo-docs/docs/readme.md
SHA256 (/srv/demo-docs/docs/readme.md) = 9b9d99e7bd52a7f6fd0db2679e52e2f590e39003b1f470d5e428ca5825a89be9

5.4 diff：跨快照对比

对文本文件输出 unified diff（改动行以 +/- 标注）：

$ plakar at /srv/backups diff b0239ef3:docs/readme.md ec109d75:docs/readme.md
--- b0239ef3:/srv/demo-docs/docs/readme.md
+++ ec109d75:/srv/demo-docs/docs/readme.md
@@ -1,2 +1,2 @@
-Plakar is an open-source backup solution by PlakarKorp.
+Plakar is an open-source backup solution by PlakarKorp. UPDATED-FOR-DIFF-TEST

对二进制文件给出 differ 判定，对目录列出同名子目录：

$ plakar at /srv/backups diff b0239ef3:/srv/demo-docs/docs/report-v1.bin ec109d75:/srv/demo-docs/docs/report-v1.bin
Binary files /srv/demo-docs/docs/report-v1.bin and /srv/demo-docs/docs/report-v1.bin differ

$ plakar at /srv/backups diff b0239ef3 ec109d75
Common subdirectories: configs and configs
Common subdirectories: docs and docs
Common subdirectories: photos and photos

「两个时间点之间到底改了什么」不再需要整包还原，一条 diff 即可回答。

5.5 restore：恢复与故障演练

restore -to <目录> <快照>:<路径> 把快照内容写入目标目录（内容直接落目录，不再嵌套源路径层级）：

$ plakar at /srv/backups restore -to /tmp/restore-test f7e99ead:/srv/demo-docs/docs
f7e99ead: OK ✓ /
f7e99ead: OK ✓ /readme-link.md
f7e99ead: OK ✓ /numbers.txt
f7e99ead: OK ✓ /readme.md
f7e99ead: OK ✓ /report-v1.bin

故障演练：源目录被误删后的整体恢复。实测过程（回显照抄）：

=== 误删 /srv/demo-docs/docs 与 photos（只剩 configs）===
/srv/demo-docs:
total 4
drwxr-xr-x 2 root root 4096 Oct 30 11:43 configs

=== restore 回原路径 ===
f7e99ead: OK ✓ /docs/numbers.txt
f7e99ead: OK ✓ /docs/report-v1.bin
f7e99ead: OK ✓ /photos/img-001.raw

=== 恢复后逐字节比对 ===
/srv/demo-docs/docs:
total 284
-rw-r--r-- 1 root root  23893 Oct 30 11:43 numbers.txt
lrwxrwxrwx 1 root root     29 Oct 30 11:43 readme-link.md -> /srv/demo-docs/docs/readme.md
-rw-r--r-- 1 root root     78 Oct 30 11:46 readme.md
-rw-r--r-- 1 root root 262144 Oct 30 11:46 report-v1.bin

/srv/demo-docs/photos:
total 512
-rw-r--r-- 1 root root 524288 Oct 30 11:43 img-001.raw
CMP_IDENTICAL

最终比对结果 CMP_IDENTICAL（逐字节一致），符号链接也完整还原。

5.6 check：快照完整性校验

对快照逐文件校验哈希与 MAC，无需还原。全仓库校验实测回显：

$ plakar at /srv/backups check
f7e99ead: OK ✓ /srv/demo-docs
f7e99ead: OK ✓ /srv/demo-docs/configs
f7e99ead: OK ✓ /srv/demo-docs/configs/site.conf
f7e99ead: OK ✓ /srv/demo-docs/docs
f7e99ead: OK ✓ /srv/demo-docs/docs/numbers.txt
f7e99ead: OK ✓ /srv/demo-docs/docs/readme-link.md
f7e99ead: OK ✓ /srv/demo-docs/docs/readme.md
f7e99ead: OK ✓ /srv/demo-docs/docs/report-v1.bin
f7e99ead: OK ✓ /srv/demo-docs/photos
f7e99ead: OK ✓ /srv/demo-docs/photos/img-001.raw
f7e99ead: check completed without errors in 6.874727ms (in: 287 KiB, out: 0 B)
225488c3: OK ✓ /srv/demo-docs/configs
225488c3: OK ✓ /srv/demo-docs/configs/site.conf
225488c3: check completed without errors in 904.328µs (in: 2.3 KiB, out: 0 B)

man 页另提供 -fast（跳过 MAC 验证、仅做结构校验，实测同样通过）与 -no-verify（跳过签名验证）。支持 plakar-query(7) 的位置过滤参数，可只校验指定快照或路径。

六、快照维护与归档命令详解

6.1 dup：复制快照

dup 复制既有快照为新快照（不重新扫描源目录），用于「为不同保留策略生成独立快照」。实测 271 微秒完成——全部数据块命中既有块，只写新元数据：

$ plakar at /srv/backups dup f7e99ead
8f173218: backup completed without errors in 271.388µs (in: 0 B, out: 395 KiB)
$ plakar at /srv/backups ls
2026-10-30T11:47:35Z   8f173218   791 KiB        0s /srv/demo-docs
2026-10-30T11:46:57Z   ec109d75   792 KiB        0s /srv/demo-docs
2026-10-30T11:45:34Z   b0239ef3   791 KiB        0s /srv/demo-docs

6.2 rm：删除快照（两阶段）

rm 默认预演，-apply 才实删。实测删除 dup 出来的重复快照：

$ plakar at /srv/backups rm 8f173218
rm: would remove these 1 snapshot(s), run with -apply to proceed
2026-10-30T11:47:35Z   8f173218   791 KiB        0s /srv/demo-docs
$ plakar at /srv/backups rm 8f173218 -apply
$ plakar at /srv/backups ls
2026-10-30T11:46:57Z   ec109d75   792 KiB        0s /srv/demo-docs
2026-10-30T11:45:34Z   b0239ef3   791 KiB        0s /srv/demo-docs

预演阶段会列出将被删除的快照清单；实删后 ls 确认已移除。快照删除不影响其他快照（数据块按引用计数回收），被删快照的内容仍在其他快照中可用。

6.3 prune：按保留策略批量清理

prune -policy <名> 按配置策略过滤快照（同样默认预演、-apply 实删）。实测按策略删除 2 份留 1 份的全过程见配置篇 5.3 节；按快照 ID 过滤的预演回显形态：

$ plakar at /srv/backups prune <快照ID>
prune: would keep 3 and delete 0 snapshot(s), run with -apply to proceed
keep     2026-10-30T11:57:13Z   225488c3      52 B /srv/demo-docs/configs tags=tmp  reason=matched filters
keep     2026-10-30T11:46:57Z   ec109d75   792 KiB /srv/demo-docs tags=nightly      reason=matched filters
keep     2026-10-30T11:45:34Z   b0239ef3   791 KiB /srv/demo-docs                   reason=matched filters

reason=matched filters 标注每条快照的保留原因，便于审计清理决策。

6.4 maintenance：仓库维护

回收已无引用的数据块并整理 packfiles。实测回显（A1 4.5 节同源）：

maintenance: Coloured 1 packfiles (0 orphaned) for deletion
Coloured packfiles are scheduled to be removed in 7d
maintenance: 0 blobs and 0 packfiles were removed

注意维护回收是延迟执行的（标记后 7 天才真正删除），这为误删快照留了「冷静期」。维护类操作需要仓库排他锁：上一次操作异常中断留下过期锁时，实测报 plakar: Can't take exclusive lock, repository is already locked，删除仓库 locks/ 目录下的锁文件即可恢复。

6.5 archive 与 ptar：快照交付为归档文件

两者都把快照导出为单文件归档：

plakar archive <快照ID> 导出为标准 tar 格式归档，任何 tar 工具可读（用 tar -tf 核对清单的实测见介绍篇 4.8 节）；
plakar ptar <快照ID> 导出为 Kloset 自包含加密格式（ptar），实测导出：

$ plakar at /srv/backups ptar f7e99ead
fd646440: OK ✓ /srv/demo-docs/configs/site.conf
fd646440: OK ✓ /srv/demo-docs/configs
fd646440: OK ✓ /srv/demo-docs/photos/img-001.raw
$ ls -l /srv/share/demo-docs.ptar
-rw------- 1 root root 833378 Oct 30 11:48 /srv/share/demo-docs.ptar

ptar 归档保持加密与完整性校验能力，适合异地冷存与离线交付；sync 亦可把 ptar 作为中转（见 6.6）。

6.6 sync：仓库间同步

sync to/from 在两个 Kloset 仓库之间同步快照，实测从本地别名仓库拉取 2 个快照：

$ plakar at /srv/backups-mirror sync from @localbak
b0239ef3: OK ✓ /srv/demo-docs/docs/report-v1.bin
b0239ef3: synchronize completed without errors in 28.359397ms (in: 4.7 KiB, out: 1.9 MiB)
info: Synchronization of b0239ef3787bcc0850c5689989505bec314f2311370ee625c550e0f92b4728e6 finished
info: sync: synchronization from localhost to localhost completed: 2 snapshots synchronized

同步按块去重，只传对端缺失的数据块（in: 4.7 KiB, out: 1.9 MiB 中 out 为逻辑数据量）。3-2-1 备份策略的异地副本靠它实现；远端 HTTP 端点（plakar server）注册为 store 后同样可 sync。

6.7 pkg：集成包管理

pkg add <名> 安装集成包（S3、SFTP、PostgreSQL、MySQL、etcd、Kubernetes 等备份源与存储后端）、pkg add -u 升级、pkg show 查看（成功静默）。安装后对应能力的 location 形式（如 s3://、sftp://）即可用于 at/source。

七、服务与辅助命令详解

server / ui：远程仓库端点与 Web 界面。全部参数（-listen/-token/-allow-delete、-addr/-no-auth 等）与实测启动回显见配置篇 5.6 节；
source / destination：备份源与恢复目标的命名定义，供 backup @name 引用，参数与子命令详见配置篇 5.4 节；
store：仓库别名管理，见配置篇 5.2 节；
policy：保留策略管理，见配置篇 5.3 节；
version / help：plakar version 回显 plakar/v1.1.8；plakar help <子命令> 内置渲染全部 man 页（39 个手册页随包发布）。

八、注意事项

删除永远是两阶段：rm、prune 不带 -apply 只预演。预演输出就是「即将发生的删除清单」，先看清楚再 -apply 是必须养成的习惯；
维护回收有 7 天延迟：maintenance 标记的孤儿数据块 7 天后才真正删除（6.4 节实测回显），误删快照后尽快发现还有挽回窗口；
口令即一切：加密仓库的口令丢失 = 数据不可恢复，PLAKAR_PASSPHRASE 与 -keyfile 要有妥善的带外保管；
仓库锁：并发操作同一仓库会遇排他锁（Can't take exclusive lock），异常中断后先清理 locks/ 再继续；
info 的命令形式：查快照用 info <快照ID>，info snapshot <ID> 会报 too many arguments；
恢复语义：restore -to <目录> 是「内容落目录」，目标路径不要再套一层源目录名，规划恢复目录时留意。

九、常见问题（FAQ）

Q1：locate 能搜文件内容吗？

不能。locate 按路径模式匹配（实测 locate site.conf 返回「快照:路径」对），搜内容先用 locate 定位文件再 cat 查看；info <快照ID> 的 Summary 有 MIME 与熵值分布可辅助判断快照内容特征。

Q2：怎么确认两个快照之间改了什么？

diff <快照1> <快照2>：文本文件输出 unified diff、二进制给 differ 判定、目录列同名子目录（5.4 节实测回显），无需还原。

Q3：dup 出来的快照占新空间吗？

几乎不占。实测 271.388µs 完成、in: 0 B——数据块全部命中去重，只新增元数据（6.1 节）。

Q4：误删了快照还能救吗？

分两层：数据块在 maintenance 回收前仍物理存在（7 天冷静期）；其他快照若引用相同块，内容不受影响。因此删除类操作后不要立即跑 maintenance -apply 类清理。

Q5：check 很慢怎么办？

用 -fast 跳过 MAC 验证只做结构校验（实测通过），或按 plakar-query 过滤只校验关键快照；完整性疑虑排除后再做全量 check。

十、参考链接

官方命令参考索引（全部子命令）：https://www.plakar.io/docs/community/v1.1.0/references/commands/
官方仓库与 man 页源（39 个手册页）：https://github.com/PlakarKorp/plakar
v1.1.8 Release：https://github.com/PlakarKorp/plakar/releases/tag/v1.1.8
本系列姊妹篇：《Plakar 社区版 1.1.8 介绍与选型指南》、《Ubuntu 22.04 安装 Plakar 社区版 1.1.8 指南》、《Plakar 社区版 1.1.8 配置参数详解》。