Vaultwarden 数据备份与恢复

[!info] related notes [[vaultwarden|Vaultwarden]] Docker Compose 容器升级步骤 Debian 部署 Homepage 和 Vaultwarden 数据备份 MOC

目标

得到一份可恢复的 Vaultwarden 全量备份：换机或磁盘损坏后，能在新环境重建出完全一致、可正常登录的服务。成功标准是「恢复后用原主密码登录，条目、附件、组织均完好」。

前置条件

• Vaultwarden 以 Docker 部署，数据目录挂载在宿主机（本例 /opt/docker/vaultwarden/data）。
• 有一个异地存储位置（移动硬盘 / NAS / 云盘）。
• 主密码本身不在备份范围内（它只在你脑中/纸质保险柜里）——见 [[vaultwarden|自托管守则]]。

需要备份什么

整个 data 目录即可，关键内容：

内容	说明
db.sqlite3（及 -wal/-shm）	主数据库：账户、条目、组织
attachments/	条目附件
sends/	Send 的文件数据
rsa_key.pem / rsa_key.*	令牌签名密钥，丢失会使已登录会话失效
config.json	管理后台（admin）运行时配置

附件、Sends 的密文与数据库是配套的，必须一起备份，缺一会导致恢复后附件打不开。

步骤

1. 停止容器以获得一致快照（推荐）

SQLite 在写入时直接打包可能拿到不一致状态。最稳妥是短暂停机：

cd /opt/docker
docker compose stop vaultwarden

若不能停机，可改用在线备份：docker exec vaultwarden sqlite3 /data/db.sqlite3 ".backup '/data/db-backup.sqlite3'"，再打包目录。

2. 打包数据目录

sudo tar czf ~/vaultwarden-backup-$(date +%F-%H%M).tar.gz -C /opt/docker/vaultwarden data

3. 重新启动服务

docker compose start vaultwarden

4. 加密并异地保存

# 用 GPG 对称加密后再外传（会提示输入口令）
gpg -c ~/vaultwarden-backup-*.tar.gz
# 然后复制 .gpg 到移动硬盘 / 云盘 / NAS

5. 定时自动备份（可选）

用 crontab -e 每天凌晨备份并只保留近 7 份：

0 3 * * * tar czf /backup/vw-$(date +\%F).tar.gz -C /opt/docker/vaultwarden data && find /backup -name 'vw-*.tar.gz' -mtime +7 -delete

验证与恢复

验证备份可用（在另一台机或临时目录）：

mkdir -p /tmp/vw-restore && tar xzf ~/vaultwarden-backup-*.tar.gz -C /tmp/vw-restore
ls /tmp/vw-restore/data   # 应看到 db.sqlite3、attachments 等

恢复到新环境：

# 1. 部署好同样的 compose 与目录结构（见部署指南）
docker compose stop vaultwarden
# 2. 用备份覆盖 data 目录
sudo rm -rf /opt/docker/vaultwarden/data
sudo tar xzf vaultwarden-backup-xxxx.tar.gz -C /opt/docker/vaultwarden
# 3. 启动并用原主密码登录验证
docker compose up -d vaultwarden

常见问题

• 恢复后附件/Send 打不开：备份时漏了 attachments/ 或 sends/，务必整目录打包。
• 恢复后所有人被强制重新登录：rsa_key 变化会使旧令牌失效，属正常，重新登录即可。
• 版本不一致导致客户端报错：新环境 Vaultwarden 版本过旧，见 vaultwarden-prelogin-404，升级后再验证。
• 直接热拷贝 SQLite 损坏：未停机也未用 .backup，改用上面的在线备份命令。