中文

应用程序

安装 Vaultwarden:HTTPS 与备份

使用 Docker 和 Caddy 在 Debian 或 Ubuntu 上托管 Vaultwarden:强制 HTTPS、关闭注册、哈希处理的管理令牌、更新、备份以及恢复测试。

阅读约 9 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何在您自己的服务器上托管 Vaultwarden,这是一个与 Bitwarden 应用兼容的轻量级服务器。Vaultwarden 在 Docker 中运行,只能在本地访问,再由 Caddy 通过 HTTPS 对外发布。

完成本指南后,您的密码库将通过 https://vault.您的域名.com 响应,没有邀请任何人都无法注册,管理令牌以哈希形式保存,并且每天都有一份备份,您也已验证过它可以恢复。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

使用的端口

端口 方向 作用 是否需要开放
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.yaml
YAML
services:
  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/ 中的某个文件:

caddyfile
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:通过邀请创建您的账户

由于注册已关闭,第一个账户需要通过管理员的邀请创建。

  1. 在 您的IP 上打开 https://vault.您的域名.com/admin。
  2. 输入步骤 2 中生成的密码,而不是它的指纹。
  3. 在 Users 选项卡中,使用 Invite User 区块并填入您的电子邮箱地址。
  4. 没有 SMTP 服务器时不会发送任何邮件。请直接打开 https://vault.您的域名.com/#/signup,并使用同一个邮箱地址注册。
  5. 选择一个长且唯一的主密码,然后登录。

随后,请在账户的安全设置中启用一种两步登录方式,并将其恢复代码保存在密码库之外。

在 Bitwarden 的桌面、移动或浏览器应用中,请在登录界面选择自托管服务器,然后填入 https://vault.您的域名.com。

步骤 6:缩小攻击面

账户创建完成后,请在 environment 中添加下面这一行,使组织成员无法再邀请新用户:

YAML
      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

参考资料