安装 Vaultwarden:HTTPS 与备份
使用 Docker 和 Caddy 在 Debian 或 Ubuntu 上托管 Vaultwarden:强制 HTTPS、关闭注册、哈希处理的管理令牌、更新、备份以及恢复测试。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何在您自己的服务器上托管 Vaultwarden,这是一个与 Bitwarden 应用兼容的轻量级服务器。Vaultwarden 在 Docker 中运行,只能在本地访问,再由 Caddy 通过 HTTPS 对外发布。
完成本指南后,您的密码库将通过 https://vault.您的域名.com 响应,没有邀请任何人都无法注册,管理令牌以哈希形式保存,并且每天都有一份备份,您也已验证过它可以恢复。
订购服务器
本指南适用于由您自行管理的服务器:
前提条件
- 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器
- 使用具有
sudo权限的用户进行 SSH 访问 - Docker Engine 和 Docker Compose,已按照指南安装 Docker Engine 和 Docker Compose安装
- Caddy,已按照指南使用 Caddy 反向代理并自动启用 HTTPS安装
- 一个由您管理 DNS 区域的域名
- 您电脑的公网 IP 地址,用于限制管理页面的访问
使用的端口
| 端口 | 方向 | 作用 | 是否需要开放 |
|---|---|---|---|
| 80/tcp | 入站 | 证书验证以及重定向到 HTTPS | 是 |
| 443/tcp | 入站 | 通过 HTTPS 访问密码库 | 是 |
| 443/udp | 入站 | HTTP/3 | 建议开放 |
| 8222/tcp | 本地 | Vaultwarden,仅限 127.0.0.1 |
否 |
步骤 1:准备域名和防火墙
为 vault.您的域名.com 创建一条指向 您的服务器IP 的 A 记录。如果您的域名由 HostMyServers 管理,请参阅指南创建 A 记录。
如果您使用 UFW,请允许 Web 端口:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status如果 UFW 尚未启用,请先按照指南配置 UFW 防火墙并避免失去 SSH 访问操作。
由 Docker 发布的端口会绕过 UFW 规则。因此,步骤 3 的 Compose 文件将 Vaultwarden 发布在 127.0.0.1 上:无论您的规则如何,它都无法从互联网访问。
步骤 2:创建经过哈希处理的管理令牌
/admin 页面用于管理实例上的账户。它由一个令牌保护,您只会以 Argon2 指纹的形式保存该令牌。
创建应用文件夹,然后生成一个长而随机的管理密码:
sudo mkdir -p /opt/vaultwarden
cd /opt/vaultwarden
openssl rand -base64 32请将该密码保存在密码库之外,例如另一个密码管理器或离线介质中。即使密码库不可用,您也需要它来登录 /admin。
接着计算它的指纹。该命令会要求您输入两次密码:
sudo docker run --rm -it vaultwarden/server:1.37.5 /vaultwarden hash它会显示如下形式的一行:
ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'创建 .env 文件:
sudo nano /opt/vaultwarden/.env将指纹粘贴进去,用单引号括起来,且不要将 $ 重复写两次:
VAULTWARDEN_ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'保护该文件:
sudo chmod 600 /opt/vaultwarden/.env步骤 3:编写 Compose 文件
sudo nano /opt/vaultwarden/compose.yamlservices:
vaultwarden:
image: vaultwarden/server:1.37.5
container_name: vaultwarden
restart: unless-stopped
environment:
DOMAIN: "https://vault.您的域名.com"
SIGNUPS_ALLOWED: "false"
ADMIN_TOKEN: "${VAULTWARDEN_ADMIN_TOKEN}"
volumes:
- ./vw-data:/data
ports:
- "127.0.0.1:8222:80"| 参数 | 作用 |
|---|---|
image |
固定的版本,更新时由您有意识地修改 |
DOMAIN |
准确的公开地址,包含 https:// |
SIGNUPS_ALLOWED |
false 会在首次启动时就关闭自由注册 |
ADMIN_TOKEN |
从 .env 读取的指纹 |
127.0.0.1:8222:80 |
仅能从服务器本身访问的端口 |
检查结果,然后启动服务:
cd /opt/vaultwarden
sudo docker compose config --quiet
sudo docker compose up -d
sudo docker compose ps
curl -fsS http://127.0.0.1:8222/alive最后一条命令会返回一个带引号的日期。大约一分钟后,docker compose ps 的状态列会显示 healthy。
步骤 4:通过 Caddy 发布密码库
将此站点添加到 /etc/caddy/Caddyfile;如果您使用了导入方式,则添加到 /etc/caddy/sites/ 中的某个文件:
vault.您的域名.com {
encode zstd gzip
@admin_denied {
path /admin /admin/*
not client_ip 您的IP
}
abort @admin_denied
reverse_proxy 127.0.0.1:8222 {
header_up X-Real-IP {remote_host}
}
}只有 您的IP 可以访问 /admin:其他连接会被直接断开,不返回任何响应。如果您通过 IPv6 访问互联网,请在 client_ip 之后也加上您的 IPv6 地址。X-Real-IP 请求头可让 Vaultwarden 在日志中记录访客的真实地址。
验证并应用配置:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy验证结果
curl -I http://vault.您的域名.com
curl -fsS https://vault.您的域名.com/alive
sudo ss -ltnp | grep 8222第一条命令应返回指向 HTTPS 的 308 重定向,第二条应返回一个日期。第三条应显示 127.0.0.1:8222,且不出现任何公网地址。
从您的电脑访问 http://您的服务器IP:8222 应当没有响应。从未使用 您的IP 的连接(例如使用移动数据的手机)访问 https://vault.您的域名.com/admin 应当失败。
步骤 5:通过邀请创建您的账户
由于注册已关闭,第一个账户需要通过管理员的邀请创建。
- 在
您的IP上打开https://vault.您的域名.com/admin。 - 输入步骤 2 中生成的密码,而不是它的指纹。
- 在 Users 选项卡中,使用 Invite User 区块并填入您的电子邮箱地址。
- 没有 SMTP 服务器时不会发送任何邮件。请直接打开
https://vault.您的域名.com/#/signup,并使用同一个邮箱地址注册。 - 选择一个长且唯一的主密码,然后登录。
随后,请在账户的安全设置中启用一种两步登录方式,并将其恢复代码保存在密码库之外。
在 Bitwarden 的桌面、移动或浏览器应用中,请在登录界面选择自托管服务器,然后填入 https://vault.您的域名.com。
步骤 6:缩小攻击面
账户创建完成后,请在 environment 中添加下面这一行,使组织成员无法再邀请新用户:
INVITATIONS_ALLOWED: "false"如果您不再使用管理页面,请删除 compose.yaml 中的 ADMIN_TOKEN 行来禁用它。如果 vw-data/config.json 文件存在,也请确认其中没有 admin_token 键。然后应用更改:
cd /opt/vaultwarden
sudo docker compose up -d以后若要邀请新成员,请临时恢复 ADMIN_TOKEN,删除 INVITATIONS_ALLOWED,然后以同样的方式重新创建容器。
更新 Vaultwarden
请查阅发行说明,使用下一节创建的服务执行一次备份,然后修改 compose.yaml 中的版本号:
cd /opt/vaultwarden
sudo systemctl start vaultwarden-backup.service
sudo nano compose.yaml
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs --tail=50 vaultwarden自 1.37.5 版本起,无效的配置值会导致无法启动。如果容器不断重启,请查看其日志。
自动备份
下面的脚本使用 Vaultwarden 内置的命令创建一份一致的数据库副本,然后归档有用的文件。图标缓存会被有意忽略。
sudo nano /usr/local/sbin/vaultwarden-backup.sh#!/bin/sh
set -eu
umask 077
APP_DIR=/opt/vaultwarden
DEST=/var/backups/vaultwarden
STAMP=$(date +%F-%H%M)
WORK=$(mktemp -d)
trap 'rm -rf "$WORK"' EXIT
mkdir -p "$DEST" "$WORK/data"
cd "$APP_DIR"
docker compose exec -T vaultwarden /vaultwarden backup
DB=$(ls -1t vw-data/db_*.sqlite3 | head -n 1)
mv "$DB" "$WORK/data/db.sqlite3"
for item in vw-data/attachments vw-data/sends vw-data/config.json vw-data/rsa_key*; do
if [ -e "$item" ]; then
cp -a "$item" "$WORK/data/"
fi
done
cp -a compose.yaml .env "$WORK/"
tar -czf "$DEST/vaultwarden-$STAMP.tar.gz" -C "$WORK" .
find "$DEST" -name 'vaultwarden-*.tar.gz' -mtime +14 -delete创建服务 /etc/systemd/system/vaultwarden-backup.service:
[Unit]
Description=Vaultwarden backup
Requires=docker.service
After=docker.service
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/vaultwarden-backup.sh然后创建定时器 /etc/systemd/system/vaultwarden-backup.timer:
[Unit]
Description=Daily Vaultwarden backup
[Timer]
OnCalendar=*-*-* 03:15:00
RandomizedDelaySec=15m
Persistent=true
[Install]
WantedBy=timers.target全部启用,并运行第一次备份:
sudo chmod 700 /usr/local/sbin/vaultwarden-backup.sh
sudo systemctl daemon-reload
sudo systemctl enable --now vaultwarden-backup.timer
sudo systemctl start vaultwarden-backup.service
sudo ls -lh /var/backups/vaultwarden归档在服务器上保留 14 天,这并不能防止服务器本身丢失。请定期将它们复制到其他位置。其中尤其包含 .env 和密钥 rsa_key.pem:如果目标位置不在您的控制之下,请对其加密,例如使用 gpg --symmetric --cipher-algo AES256 archive.tar.gz。
| 项目 | 内容 | 备份 |
|---|---|---|
db.sqlite3 |
账户、加密的密码库、组织 | 必须备份 |
attachments/ |
附件 | 必须备份 |
rsa_key* |
会话签名 | 建议备份 |
config.json |
从 /admin 保存的设置 |
建议备份 |
sends/ |
Send 文件 | 可选 |
icon_cache/ |
网站图标 | 无需备份 |
测试恢复
只有能够恢复的备份才有价值。此测试会在另一个端口上运行一份隔离的副本,不会影响正在运行的实例。
解压最新的归档并检查数据库:
sudo apt install -y sqlite3
sudo install -d -m 700 /root/vw-restore-test
sudo sh -c 'tar -xzf "$(ls -1t /var/backups/vaultwarden/*.tar.gz | head -n 1)" -C /root/vw-restore-test'
sudo sqlite3 /root/vw-restore-test/data/db.sqlite3 'PRAGMA integrity_check;'最后一条命令应显示 ok。然后启动副本:
sudo docker run -d --rm --name vaultwarden-restore-test \
-e DOMAIN=http://localhost:8223 \
-e SIGNUPS_ALLOWED=false \
-v /root/vw-restore-test/data:/data \
-p 127.0.0.1:8223:80 \
vaultwarden/server:1.37.5
curl -fsS http://127.0.0.1:8223/alive在您的电脑上打开 SSH 隧道:
ssh -L 8223:127.0.0.1:8223 您的用户名@您的服务器IP打开 http://localhost:8223,用您的账户登录,然后检查一条最近的条目和一个附件能否正常打开。浏览器将 localhost 视为安全上下文,因此无需证书即可进行此测试。
关闭隧道,然后删除副本:
sudo docker stop vaultwarden-restore-test
sudo rm -rf /root/vw-restore-test每次重大变更之后都要重新进行此测试,并且至少每季度一次。
在生产环境中恢复
请将归档名称替换为您选择的备份名称。在新服务器上,请先从归档的根目录将 compose.yaml 和 .env 恢复到 /opt/vaultwarden。
ARCHIVE=/var/backups/vaultwarden/vaultwarden-2026-11-18-0315.tar.gz
cd /opt/vaultwarden
sudo docker compose down
sudo mv vw-data "vw-data.old-$(date +%F)"
sudo install -d -m 700 /root/vw-restore
sudo tar -xzf "$ARCHIVE" -C /root/vw-restore
sudo cp -a /root/vw-restore/data /opt/vaultwarden/vw-data
sudo docker compose up -d
sudo rm -rf /root/vw-restore请先登录并检查数据,再删除旧的 vw-data.old-* 文件夹。
故障排除
The "argon2id" variable is not set
Docker Compose 试图解析指纹中的 $。指纹必须放在 .env 中并用单引号括起来,而 compose.yaml 只能引用 ${VAULTWARDEN_ADMIN_TOKEN}。请用 sudo docker compose config 检查结果:其中的 $ 会显示为两个,这在该处是正常的。
The configured Argon2 PHC in ADMIN_TOKEN is invalid
Vaultwarden 收到的值不正确,通常是由于 .env 中多了引号或 $ 被写成了两个。请进行检查:
sudo docker exec vaultwarden printenv ADMIN_TOKEN输出应以 $argon2id$ 开头,且不带引号。
Invalid admin token, please try again.
请输入原始密码,而不是指纹。如果您已丢失密码,请重新执行步骤 2 生成新的密码,然后用 sudo docker compose up -d 重新创建容器。
You are using a plain text ADMIN_TOKEN which is insecure
Vaultwarden 读取到的仍是明文令牌。多数情况下是 config.json 的优先级高于 compose.yaml:
sudo grep admin_token /opt/vaultwarden/vw-data/config.json此时请在 /admin 页面的 Admin token/Argon2 PHC 字段中替换令牌。
The admin panel is disabled
没有配置任何令牌。请检查 compose.yaml 的 ADMIN_TOKEN 行和 .env 的内容,然后重新创建容器。
/admin 无响应
很可能是您电脑的 IP 地址发生了变化。请修改 Caddyfile 中的 client_ip,然后验证并重新加载 Caddy。
Registration not allowed or user already exists
您输入的地址与任何待处理的邀请都不匹配,或者该账户已存在。请在 /admin 的 Users 选项卡中检查该地址。如果 INVITATIONS_ALLOWED 的值为 false,请在注册期间暂时删除这一行。
修改的变量没有任何效果
如果 vw-data/config.json 存在,它会覆盖环境变量。请在 /admin 中修改该设置,或在容器停止的状态下从该文件中删除相应的键。
密码库无法打开,或提示需要 HTTPS
请确认您使用的是 https:// 地址,并且 DOMAIN 中的内容与该地址完全一致。不支持通过 http://您的服务器IP 访问。
浏览器中出现 502 错误
Caddy 无法连接到容器:
cd /opt/vaultwarden
sudo docker compose ps
sudo docker compose logs --tail=50 vaultwarden
curl -fsS http://127.0.0.1:8222/alive