Plakar 社区版 1.1.8 配置参数详解

目标：讲清 Plakar 社区版 1.1.8 的完整配置面——它没有传统意义的单一主配置文件，配置分散在「仓库参数（create 时固化）、stores/policies/sources/destinations 四类 YAML 配置、环境变量、命令行覆盖」四个层面。本文逐层给出参数语义、默认值与实测验证，并给出可直接落地的生产配置模板。全部命令与输出在 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（本地文件系统后端，加密仓库）、/srv/backups-mirror（对端仓库）、http://127.0.0.1:9876（远端端点）
• 演示口令：q1w2e3r4（演示账号口径；生产环境务必使用高强度独立口令）
• 实测日期：2026-10-30

二、前置条件

• 已按《Ubuntu 22.04 安装 Plakar 社区版 1.1.8 指南》完成安装并跑通建库与首次备份；
• 熟悉仓库（Kloset store）与快照（snapshot）基本概念，见《Plakar 社区版 1.1.8 介绍与选型指南》第三章；
• 本文配置操作均以 root 实测；涉及 $HOME 的路径以 /root 为准。

三、配置体系总览：参数查看与修改方式

3.1 四类配置面 + 仓库参数

Plakar 的配置不收敛在一个文件里，按作用域分五处：

仓库参数一旦在 plakar create 时确定（分块、哈希、压缩、加密全套），后续无法对既有仓库原地修改；官方的路径是新建仓库再 sync from 迁移（见安装指南 3.3 节）。其余四类配置都是「当前用户的声明式配置」，随时可改，立即生效。

3.2 配置文件落点实测

一台装好并使用过的 Plakar 主机，配置与缓存文件实测清单：

/root/.config/plakar/stores.yml
/root/.config/plakar/policies.yml
/root/.config/plakar/sources.yml
/root/.config/plakar/destinations.yml
/root/.cache/plakar/crash-cached.log
/root/.cache/plakar/cookies/1.0.0/.first-run
/root/.cache/plakar/last-update-check
/root/.cache/plakar/2.0.0/scan/8f173218c41846c229948e04ed08a5d0d83eee3b509fde0222aec0704a6397c9/marker.format-version.000001.013

~/.config/plakar/ 下四个 YAML 是配置主体（未配置的文件可能不存在或为空）；~/.cache/plakar/ 是运行缓存（扫描缓存、更新检查记录、崩溃日志），不属于配置，可安全清理但会重建。

3.3 查看与修改的统一命令形态

stores、sources、destinations、policies 四个配置面共用同一套子命令（以 plakar store --help 与各 man 页为准）：

add name [option=value ...]   新建条目（option=value 附加参数）
set name [option=value ...]   修改条目参数（可多对）
unset name [option ...]       删除条目的某个参数
rm name                       删除条目
show [-json] [-yaml] [-secrets]  查看配置（默认 YAML，-json/-yaml 控制格式）

两点实测行为需要注意：

• add/set 成功时静默返回（退出码 0，无回显），确认手段是 show；
• show 默认对敏感值（如 passphrase）打码显示为 ********，加 -secrets 才显示明文。

四、参数总览

4.1 仓库级参数（CONFIG，create 固化）

plakar info 查看仓库全套参数（完整回显见介绍篇 3.4 节），逐项列表：

这些参数在 plakar create 时按内置默认值写入仓库 CONFIG 文件，create 不提供调整分块/压缩/加密强度的选项（man 页仅有 -plaintext 一个选项，见 5.1 节）。

4.2 配置文件参数（四类 YAML）

4.3 环境变量

4.4 常用命令行覆盖参数

配置文件与环境变量之外，命令行还有一层覆盖：plakar backup -o option=value 可直接向 source 连接器传参，man 页明确「The given option takes precedence over the configuration file」（命令行优先于配置文件）。适合临时改参数而不动配置文件。

五、核心参数分类详解

5.1 仓库创建与加密参数

plakar create 的完整选项只有一个（man 页原文）：

plakar create [-plaintext]

-plaintext
    Disable transparent encryption for the repository. If specified, the
    repository will not use encryption.

即：默认创建加密仓库（4.1 节全套加密参数自动生效）；加 -plaintext 则创建不加密的仓库。口令经环境变量 PLAKAR_PASSPHRASE 注入（或交互输入、-keyfile 文件注入）。实测创建加密仓库：

$ export PLAKAR_PASSPHRASE=q1w2e3r4
$ plakar at /srv/backups create
$ echo $?
0

create 成功时静默返回。若既无环境变量又无终端（如被调度器拉起），实测报错：

repository passphrase: 
plakar: inappropriate ioctl for device

口令强度决定了加密仓库的安全下限，Argon2id 参数（time=4、memory=262144、thread=1）是仓库内置默认，不随用户口令复杂度变化。

5.2 stores.yml：仓库别名

用别名替代每次敲完整 location。实测注册两个本地仓库与一个远端端点（add 均静默，show 查看结果）：

$ plakar store add localbak location=/srv/backups
$ plakar store add mirror location=/srv/backups-mirror
$ plakar store add remote location=http://127.0.0.1:9876
$ plakar store show
mirror:
    location: /srv/backups-mirror
localbak:
    location: /srv/backups
remote:
    location: http://127.0.0.1:9876

为别名补配口令（set 后 show 自动打码）：

$ plakar store set localbak passphrase=q1w2e3r4
$ plakar store set mirror passphrase=q1w2e3r4
$ plakar store show
localbak:
    location: /srv/backups
    passphrase: '********'
mirror:
    location: /srv/backups-mirror
    passphrase: '********'

此后 plakar at @localbak ls 即等价于 plakar at /srv/backups ls。配置落盘的 stores.yml 实测内容：

version: v1.0.0
stores:
    localbak:
        location: /srv/backups
        passphrase: q1w2e3r4
    mirror:
        location: /srv/backups-mirror
        passphrase: q1w2e3r4
    remote:
        location: http://127.0.0.1:9876

⚠️ 安全提示：passphrase 在 stores.yml 中是明文落盘（show 打码只保护终端显示，不保护磁盘文件）。把口令写进 stores.yml 换来的是免交互便利，请确保该文件所属用户的 home 目录权限收紧（本文实测环境为 root 单用户主机）。更稳妥的方式是不落盘口令，调度任务里用环境变量注入；官方定时备份指南还给出生产推荐形态——store set <名> passphrase_cmd="<命令>"，由密钥管理器（如 gopass）在运行时输出口令，密钥完全不落盘。

5.3 policies.yml：保留策略（prune 用）

策略定义「 prune 时每类周期最多留几份快照」。实测创建每日保留 1 份的策略：

$ plakar policy add onepd periods.day.cap=1
$ plakar policy show
onepd:
    periods:
        day:
            cap: 1

用该策略对仓库做 prune（默认 dry-run，先预演）：

$ plakar at /srv/backups prune -policy onepd
prune: would keep 1 and delete 2 snapshot(s), run with -apply to proceed
keep     2026-10-30T11:57:13Z   225488c3      52 B /srv/demo-docs/configs tags=tmp  match=day:2026-10-30 rank=1 cap=1
delete   2026-10-30T11:46:57Z   ec109d75   792 KiB /srv/demo-docs tags=nightly      match=day:2026-10-30 rank=2 cap=1
delete   2026-10-30T11:45:34Z   b0239ef3   791 KiB /srv/demo-docs                   match=day:2026-10-30 rank=3 cap=1

预演结果按 match=day:2026-10-30 归组并给 rank，cap=1 只留 rank 1。确认后 -apply 实删，实测回显：

info: prune: removal of b0239ef3 completed successfully
info: prune: removal of ec109d75 completed successfully

删 2 留 1，ls 只剩 225488c3。

参数书写形式的两个实测排错点：

• key 写法错误：plakar policy add keep2 keep-last=2 实测报 plakar: failed to set key "keep-last": invalid key——策略参数不接受 keep-last 这种 key，必须用 periods.<day|week|month>.cap 结构；
• 名字不存在：plakar at /srv/backups prune -policy keep2 实测报 plakar: policy "keep2" not found——策略按名字引用，先 policy show 核对。

策略参数的完整可选项对应 plakar-query(7) 的同名 flag（man 页原文：「The available options as described in plakar-query(7): each option corresponds the similarly named flag」），即可按快照的 name/tag/category 等条件过滤后再套 cap。

5.4 sources.yml 与 destinations.yml：备份源与恢复目标

两者结构对称（man 页同构），子命令均为 add/check/import/ping/rm/set/show/unset：

定义后，备份用 plakar backup @name 引用源；@name:/path 形式可覆盖路径（以 / 开头整体替换，否则追加）。import -rclone 可直接把存量 rclone 远端配置转成 Plakar 源，迁移成本低。敏感参数（如 S3 的 access_key/secret_access_key）经 add/set 写入后，show 默认不显示，需 -secrets 才回显。

5.5 备份行为参数

plakar backup 的行为参数（man 页全量选项，常用项如下）：

标签除命令行 -tag 外，可用环境变量 PLAKAR_TAGS 统一注入（被 -tag 覆盖）。

5.6 服务端与 UI 参数

plakar server（远程仓库端点）：

实测启动回显：

$ plakar at /srv/backups server -listen 0.0.0.0:9876
info: listening on http://0.0.0.0:9876

man 页注意事项（CAVEATS）：指定 host 名时，服务端只使用其解析到的其中一个 IP，优先 IPv4。man 页示例还给出在远端仓库上起服务端的用法：plakar at sftp://example.org server。

plakar ui（本地 Web 界面）：

实测启动回显：

$ plakar at /srv/backups ui -addr 0.0.0.0:8146 -no-auth -no-spawn
launching webUI at http://0.0.0.0:8146

服务端 -allow-delete 默认关闭、UI -no-auth 需显式开启——两个「危险默认值反向」的设计都把安全侧作为缺省，生产使用时先按需放开。

5.7 环境变量详解

PLAKAR_REPOSITORY：设置默认仓库，省略 at 前缀。实测设置后直接执行 plakar ls 即列出仓库快照（rc=0，回显与 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

PLAKAR_PASSPHRASE：口令注入首选方式，create 与后续打开仓库都必须能拿到口令。不设且无终端时报 inappropriate ioctl for device（见 5.1 节）。

PLAKAR_TAGS：备份自动打标。与 5.5 节 -tag 的覆盖关系是 man 页明示的「Overridden by the -tag command-line flag」。

六、生产配置模板

6.1 模板场景与基准

适用场景：4~8 GB 内存的单机服务器（VPS/物理机），本地目录 + 远端端点双副本，每日定时备份，NVMe/SSD 或本地 RAID 磁盘。仓库加密参数沿用 create 默认（Argon2id 256 MiB 内存档——prune/backup 高峰期单进程内存预算预留 512 MB 以上为宜）。

6.2 模板内容与落地步骤

第一步：注册仓库别名与口令（口令也可不落 stores.yml，改在 cron 环境注入）：

$ plakar store add prod location=/srv/backups
$ plakar store set prod passphrase=q1w2e3r4
$ plakar store show

第二步：定义保留策略（每日留 7 份、每周留 4 份、每月留 3 份；本模板逐级 cap 写法与 5.3 节实测同构）：

$ plakar policy add keep-prod periods.day.cap=7
$ plakar policy set keep-prod periods.week.cap=4
$ plakar policy set keep-prod periods.month.cap=3
$ plakar policy show keep-prod

第三步：定时任务（cron 形态；口令经环境变量注入，systemd timer 形态见安装指南 8.3 节）：

# /etc/cron.d/plakar-prod：每日 02:30 备份，每周日 03:10 按策略清理
30 2 * * *  root  PLAKAR_PASSPHRASE=q1w2e3r4 /usr/bin/plakar at /srv/backups backup -name prod -tag nightly /srv/data
10 3 * * 0  root  PLAKAR_PASSPHRASE=q1w2e3r4 /usr/bin/plakar at /srv/backups prune -policy keep-prod -apply

第四步（可选）：异地副本——把备份同步到远端仓库端点或 S3/SFTP（集成包需 plakar pkg add 先行安装）：

$ plakar at /srv/backups sync to @remote

模板要点：备份与清理分离（backup 高频、prune 低频）；策略先 dry-run 后 -apply；-name 固定为 prod 便于策略与检索过滤。

七、常见问题（FAQ）

Q1：仓库的分块/压缩/加密参数能改吗？

不能原地改。这些参数在 create 时写入仓库 CONFIG 文件（4.1 节），官方升级路径是新建仓库后 sync from 旧仓库完成迁移，迁移期间旧仓库可继续使用。

Q2：store add / policy add 执行完没有任何输出，成功了吗？

成功。这类配置命令成功时静默返回（退出码 0），用对应的 show 子命令确认；show 默认打码敏感值，核对明文加 -secrets。

Q3：policy add keep2 keep-last=2 报 invalid key？

保留策略的合法 key 是 periods.day.cap 这类结构化字段（5.3 节实测），不支持 keep-last 简写。按 5.3 节形态书写即可。

Q4：stores.yml 里的口令是明文的，有更安全的办法吗？

有：不在 stores.yml 里 set passphrase，改为在调度任务或 shell 环境里注入 PLAKAR_PASSPHRASE（或 -keyfile）。注意 show 的 ******** 打码只作用于终端显示。

Q5：plakar server 默认监听在哪、安全吗？

默认 localhost:9876（man 页 -listen 缺省值）；实测启动为显式传参 -listen 0.0.0.0:9876，回显 info: listening on http://0.0.0.0:9876。跨机访问时建议：配 -token 强制 Bearer 认证、配 -cert/-key 启用 https、防火墙收敛来源；-allow-delete 保持默认关闭。

Q6：备份想临时排除某些文件，不动配置文件怎么做？

命令行加 -ignore "*.log"（可重复）或 -ignore-file <文件>；先用 -dry-run 预演排除结果再正式备份（5.5 节）。

八、参考链接

• 官方仓库（配置相关 man 页：plakar-create/plakar-backup/plakar-source/plakar-destination 等）：https://github.com/PlakarKorp/plakar
• 官方命令参考索引：https://www.plakar.io/docs/community/v1.1.0/references/commands/
• 官方配置导入指南（sources/destinations 的 import 与 rclone 迁移）：https://plakar.io/docs/v1.1.0/guides/importing-configurations/
• 官方定时备份指南：https://www.plakar.io/docs/community/v1.1.0/guides/setup-scheduler-daily-backups/
• 本系列姊妹篇：《Plakar 社区版 1.1.8 介绍与选型指南》、《Ubuntu 22.04 安装 Plakar 社区版 1.1.8 指南》、《Plakar 社区版 1.1.8 常用 CLI 命令与工具详解》。