Duplicity 3.2.2 配置参数详解

目标：系统讲清 Duplicity 的两套配置体系——环境变量（加密口令、后端凭据、缓存目录）与命令选项（加密、过滤、性能、网络、存储后端专属），逐项给出官方默认值与实测行为，并给出可直接落地的生产备份模板。本文选项默认值以官方最新稳定版 3.2.2 实测 --help 输出为准，与 0.8.21 的差异单列对照。安装过程见 《Ubuntu 22.04 安装 Duplicity 指南》，命令体系见 《Duplicity 常用 CLI 命令详解》。

一、环境信息

• 操作系统：Ubuntu 22.04，x86_64
• Duplicity：3.2.2（pip 源码安装，版本自报 October 14, 2026；选项默认值实测自 duplicity --help），对照版本 0.8.21（apt 安装）
• GnuPG：gpg (GnuPG) 2.2.27
• 演示数据与备份目标：/srv/data → file:///srv/backups
• 演示 GPG 密钥：Backup Demo <root@backup.local>，口令 q1w2e3r4，密钥 ID 3712F37EFEC688C984FAC7A72786982B41DDD4A7

二、前置条件

Duplicity 是纯 CLI 工具，没有配置文件：所有配置通过「命令行选项 + 环境变量」在每次调用时给定，定时任务场景用包装脚本固化参数（见第七节模板）。因此阅读本文只需：

1. 已按 《Ubuntu 22.04 安装 Duplicity 指南》安装并验证 duplicity --version 正常；
2. 已有一把 GPG 密钥（或决定用 --no-encryption 纯压缩模式）；
3. 已明确备份源目录与目标 URL（后端 URL 语法见本篇 4.2 节）。

三、参数查看与修改方式

3.1 三个层级的帮助入口

3.2.2 的帮助体系与 0.8.x 有代差：总览帮助变短，每个动作（backup/restore/...）都有专属帮助。实测：

duplicity --help | head -25

实测回显（3.2.2）：

duplicity 3.2.2 October 14, 2026

usage: duplicity backup [options] source_path target_url
       duplicity cleanup [options] target_url
       duplicity collection-status [options] target_url
       duplicity full [options] source_path target_url
       duplicity incremental [options] source_path target_url
       duplicity list-current-files [options] target_url
       duplicity remove-all-but-n-full [options] count target_url
       duplicity remove-all-inc-of-but-n-full [options] count target_url
       duplicity remove-older-than [options] remove_time target_url
       duplicity restore [options] source_url target_path
       duplicity verify [options] source_url target_path

duplicity --help-backup | head -8

实测回显（3.2.2）：

usage: duplicity backup [options] source_path target_url
       duplicity full [options] source_path target_url
       duplicity incremental [options] source_path target_url

💡 说明：--help-backup、--help-restore、--help-urls、--help-cleanup 等 13 个分动作帮助是 3.x 新增入口，查某动作可用选项不必再翻 200 行总览；0.8.21 只有单一 --help（168 行）与 man page。

3.2 环境变量的传入方式

环境变量支持三种写法（语义等价，定时任务用第一种）：

# 1) 命令前缀（单次生效）
PASSPHRASE='q1w2e3r4' duplicity full /srv/data file:///srv/backups

# 2) shell 导出（会话生效）
export PASSPHRASE='q1w2e3r4'
duplicity full /srv/data file:///srv/backups

# 3) 包装脚本内联（定时任务推荐，见第七节）

四、参数总览

4.1 环境变量一览

💡 说明：官方 man page 的 ENVIRONMENT VARIABLES 与 URL FORMAT 节（https://duplicity.gitlab.io/stable/duplicity.1.html，查询日期 2026-10-22）明确了两条凭据原则：① URL 中 user[:password] 的密码段可省略，由对应环境变量提供；② 3.x 起支持 BACKEND_PASSWORD=mypassword duplicity /local/dir ftp://user@other.host/some_dir 的通用写法。各云后端的专属变量名以 man page 对应后端小节为准，本文不逐一复述易变清单。

实测验证（口令错误时的标准报错，呼应 PASSPHRASE 的重要性）：

PASSPHRASE='wrongpass' duplicity verify file:///srv/backups /srv/data 2>&1 | head -7

实测回显：

Local and Remote metadata are synchronized, no sync needed.
Last full backup date: Wed Oct 21 17:43:18 2026
GPGError: GPG Failed, see log below:
===== Begin GnuPG log =====
gpg: AES256.CFB encrypted data
gpg: encrypted with 1 passphrase
gpg: decryption failed: Bad session key
===== End GnuPG log =====

4.2 目标 URL 与后端参数的关系

后端 URL 语法（3.2.2 实测 duplicity --help-urls 节选）：

  file:///some_dir
  s3://other.host[:port]/bucket_name[/prefix]
  sftp://user[:password]@other.host[:port]/some_dir
  swift://container_name
  webdav://user[:password]@other.host/some_dir
  rclone://remote:/some_dir
  multi://{some_dir}

💡 技术拓展：备份目标的后端选择本身就是「配置」的一部分——本地盘 file://、对象存储 s3://swift://、远端主机 sftp://、多目标聚合 multi://。选型维度是带宽（增量是否跨网）、信任边界（是否需 GPG 端加密）与成本（云存储层级），完整后端矩阵见 《Duplicity 介绍与选型指南》第 3.2 节。

五、核心命令选项分类详解

以下按使用场景分七类，默认值全部来自 3.2.2 --help 实测输出；标注「0.8.21 差异」的行为在两版环境实测过。

5.1 加密与签名类

实测 --no-encryption 的产物差异：

duplicity --no-encryption /srv/data file:///srv/backups-plain
ls /srv/backups-plain

实测回显：

duplicity-full-signatures.20261021T174326Z.sigtar.gz
duplicity-full.20261021T174326Z.manifest
duplicity-full.20261021T174326Z.vol1.difftar.gz

💡 说明：关闭加密后 .gpg 后缀消失，manifest 直接是明文。生产环境除非备份盘本身物理安全且只做中转，否则不建议 --no-encryption——GPG 对称加密对 500MB 级数据集的开销在秒级，可忽略。

5.2 文件过滤类（备份范围）

实测过滤行为（** 匹配任意层级路径）：

duplicity --exclude '**/photos' --no-encryption /srv/data file:///srv/backups-exclude

实测回显（统计节选）：

SourceFiles 3
NewFiles 3

💡 说明：源目录共 7 个文件，排除 photos 目录（含 3 个文件）后只备 3 个（目录项 docs、photos 目录节点与 readme.txt 计入规则见 D1 篇 list-current-files 演示）。shell 模式优先级：命令行中先出现的模式优先，--include 与 --exclude 可混排实现「白名单」逻辑——例如先 --include /srv/data/docs 再 --exclude /srv/data 即只备 docs。

5.3 卷与性能类

实测 --archive-dir 与 --name 的联动（缓存目录从 hash 变为可读名）：

PASSPHRASE='q1w2e3r4' duplicity --archive-dir /root/mycache --name mytest \
  collection-status file:///srv/backups 2>&1 | grep 'Archive dir'

实测回显：

Archive dir: /root/mycache/mytest

💡 说明：默认缓存目录是「源路径 + 目标 URL」的 MD5 hash（如 /root/.cache/duplicity/58fb6bfee477db35c5792612a5de2147），多任务场景难以分辨；生产模板用 --name 起可读名。--volsize 在数据量小于卷上限时仍只产生单卷（实测 524KB 数据集 --volsize 1 依旧 vol1 单卷），调小 volsize 的意义在于大备份集的分片粒度与断点续传。

实测 debug 日志级别（-v 取值 0-9 或 e/w/n/i/d）：

PASSPHRASE='q1w2e3r4' duplicity -v 9 collection-status file:///srv/backups 2>&1 | head -4

实测回显：

Using archive dir: /root/.cache/duplicity/58fb6bfee477db35c5792612a5de2147
Using backup name: 58fb6bfee477db35c5792612a5de2147
GPG binary is gpg, version (2, 2, 27)
Import of duplicity.backends.adbackend Succeeded

5.4 存储后端专属类（S3 为例）

💡 说明：--file-prefix 是同一桶跑多个备份集的关键配置——对象存储桶内所有 duplicity 文件混在一起会互相「认亲」，给每个任务配唯一前缀（如 --file-prefix web1-）即可同桶共存。Azure/B2/Swift 等其余后端专属参数同见 --help 与 man page 各后端小节。

5.5 恢复与比对类

时间格式实测（-t 支持 ISO 串与相对量，还原到全量完成时刻附近）：

PASSPHRASE='q1w2e3r4' duplicity restore -t '2026-10-21T17:42:20' \
  file:///srv/backups /srv/restore-t
cat /srv/restore-t/docs/readme.txt

实测回显：

Local and Remote metadata are synchronized, no sync needed.
Last full backup date: Wed Oct 21 17:42:17 2026
hello duplicity v1

5.6 清理与生命周期类

⚠️ 注意：清理命令不带 --force 时只打印将要删除的清单（dry-run 语义），这是安全设计；但反过来，写进 cron 的清理命令忘了 --force 会默默不生效。

5.7 日志与其他

六、0.8.21 与 3.2.2 选项差异对照

两版 --help 逐项比对后的要点差异（均实测）：

💡 说明：3.x 的选项语义大多向后兼容，但两版产物 manifest/sigtar 的内部格式有演进，不建议用 0.8.x 写的备份链由 3.2.2 直接接管增量——升级前完成一次全量重建（官方下载页同样警告混装问题）。

七、生产配置模板

适用于「1-2 台中小型服务器、每日增量 + 每周全量、本地 NAS 或 S3 兼容存储」的场景（8GB 内存、普通 SSD 即可，Duplicity 本身无常驻进程，资源开销集中在备份窗口）。

7.1 环境变量文件

/root/.duplicity-env（权限 600）：

PASSPHRASE='q1w2e3r4'
# 云后端时追加对应凭据，例如 S3：
# AWS_ACCESS_KEY_ID='AKIAEXAMPLE'
# AWS_SECRET_ACCESS_KEY='secretsecret'

7.2 备份脚本

/root/duplicity-backup.sh：

#!/bin/bash
# Duplicity 生产备份模板：每日增量、周日全量、保留 2 条全量链
source /root/.duplicity-env

SRC="/srv/data"
DEST="file:///mnt/nas/backup/srv1"
COMMON="--archive-dir /root/.cache/duplicity --name srv1-data \
  --exclude '**/.cache' --exclude-device-files \
  --volsize 25 --asynchronous-upload --log-file /var/log/duplicity.log --log-timestamp"

# 周日做全量，其余每天增量
if [ "$(date +%u)" = "7" ]; then
  duplicity $COMMON full "$SRC" "$DEST"
else
  duplicity $COMMON incr "$SRC" "$DEST"
fi

# 每轮备份后清理：只保留最近 2 条全量链
duplicity $COMMON remove-all-but-n-full 2 --force "$DEST"

7.3 定时任务

chmod 700 /root/duplicity-backup.sh
crontab -e

crontab 追加（每天 02:30 执行）：

30 2 * * * /root/duplicity-backup.sh

💡 说明：脚本内 --log-file 落 /var/log/duplicity.log 便于巡检；remove-all-but-n-full 2 --force 保证备份目标不会无限增长（保留最近 2 条全量链及其增量）。若目标是对象存储，把 DEST 换成对应 URL 并在环境文件中补凭据即可，脚本其余零改动。

八、常见问题（FAQ）

Q1：PASSPHRASE 没生效，仍然提示输入口令？ 变量只对当前进程及其子进程生效：export 必须与 duplicity 同一 shell 会话；cron 环境变量极简，脚本内必须显式 source /root/.duplicity-env（7.2 节已做）。

Q2：加密模式选对称口令还是公钥？ 对称模式（只配 PASSPHRASE）最简单，但口令随脚本分发；公钥模式（--encrypt-key <key-id>）恢复端只需私钥口令，备份机不存解密能力，安全性更高。生产推荐公钥模式，密钥对管理见 《Ubuntu 22.04 安装 Duplicity 指南》第九节。

Q3：--volsize 调多大合适？ 默认 25MB 适合多数云后端；到 Glacier 等按请求计费的存储可调大到 100-500MB 减少请求数；本地盘无所谓。数据量小于卷大小时始终单卷（实测确认）。

Q4：同一目录换机器恢复报「找不到备份链」？ 换机后本地缓存（archive-dir）为空，duplicity 会先从远端同步元数据（回显第一行 Local and Remote metadata are synchronized, no sync needed 之前多一步同步），属正常现象；确保 --name/--archive-dir 与原机一致可复用缓存。

Q5：如何验证定时清理真的在删旧链？ 清理命令不带 --force 时是 dry-run，先手动跑一次看打印的删除清单，确认后再核对目标目录文件时间戳；完整演示见 《Duplicity 常用 CLI 命令详解》的清理命令实测节。

九、参考链接

• 官方 man page（选项与环境变量权威定义）：https://duplicity.gitlab.io/stable/duplicity.1.html （查询日期 2026-10-22）
• 官网 Download 与版本警告：https://duplicity.us/index.html （查询日期 2026-10-22）
• 本专栏系列：《Duplicity 介绍与选型指南》、《Ubuntu 22.04 安装 Duplicity 指南》、《Duplicity 常用 CLI 命令详解》