Vaultwarden 搭建教程：自建密码库与浏览器插件对接

摘要

Vaultwarden 是用 Rust 实现的轻量密码管理服务端，兼容主流密码管理客户端，资源占用远低于官方服务端，适合个人和小团队自建。本文完成 Vaultwarden 的部署，涵盖 HTTPS 强制要求的原因、Docker 部署、关闭开放注册、浏览器插件与手机端对接、以及密码库这类高价值数据的备份与恢复演练。

一、自建密码库前必须明确的三件事

密码库和其他自托管服务不同，它存的是访问一切系统的钥匙。动手前先确认三点。

第一，HTTPS 不是可选项。 客户端与服务端之间传输的是加密后的密码库数据，但会话令牌、账号标识等信息仍需保护。更关键的是，主流密码管理客户端出于安全考虑，在非 HTTPS 环境下会拒绝连接或限制功能。所以域名和证书必须先准备好，不能用 IP 加端口凑合。

第二，可用性直接影响日常。 服务器宕机时你将无法取用任何密码。建议在手机客户端开启离线缓存，这样即使服务端不可达也能查看已同步的条目。同时不要把云账号密码本身只存在这个库里——万一需要登录控制台排障，会陷入死锁。

第三，备份比什么都重要。 密码库数据丢失意味着所有账号凭据丢失，且无法通过任何方式找回。备份和恢复演练必须在正式使用前完成，而不是等到出事再说。

二、配置要求

Vaultwarden 是这一批自托管服务里资源需求最低的。

数据库默认使用 SQLite，对个人和小团队完全够用。用户数较多时可以改用 PostgreSQL 或 MySQL，但多数场景没有必要。

需要放通的端口：

服务本身监听的端口不需要对公网放通，由反向代理转发即可。

三、准备域名与解析

在域名服务商处添加 A 记录指向服务器公网 IP：

解析生效后验证：

dig +short vault.example.com

返回 IP 与服务器公网 IP 一致才能继续。

服务器位于中国内地且使用域名对外提供服务时，需要先完成 ICP 备案。

四、部署 Vaultwarden

mkdir -p ~/apps/vaultwarden && cd ~/apps/vaultwarden

编写 compose.yaml：

services:
  vaultwarden:
    image: vaultwarden/server:1.32.7
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./data:/data
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "true"
      INVITATIONS_ALLOWED: "true"
      ADMIN_TOKEN: "替换为随机长字符串"
      WEBSOCKET_ENABLED: "true"
      TZ: Asia/Shanghai
    restart: unless-stopped

几处配置的说明：

• 127.0.0.1:8080:80 把端口只绑定到本机回环地址，外部无法直接访问，必须经过反向代理。这比绑定到 0.0.0.0 更安全。
• DOMAIN 必须填写完整的 https 地址。这个值影响客户端连接和部分功能的链接生成，填错会导致异常。
• SIGNUPS_ALLOWED 先设为 true 以便注册第一个账号，注册完成后必须改为 false，这一步后面会讲。
• ADMIN_TOKEN 用于访问管理后台。生成一个足够随机的值：

openssl rand -base64 48

• 镜像版本固定为具体版本号，不使用滚动标签。

启动服务：

docker compose up -d
docker compose ps
docker compose logs vaultwarden --tail 30

五、配置反向代理与 HTTPS

以 Caddy 为例：

vault.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy 会自动申请证书并处理长连接协议升级。Vaultwarden 的实时同步依赖长连接，使用 Nginx 时需要手动补充协议升级相关请求头。

重载配置：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

验证证书已签发：

curl -I https://vault.example.com

应返回 200 且无证书告警。

六、注册账号并关闭开放注册

这是整个部署中最关键的安全步骤，很多人配完就忘了。

第一步，注册你的账号

在浏览器访问 https://vault.example.com，点击创建账号。

设置主密码时要特别认真：主密码是解密整个密码库的唯一钥匙，服务端不保存它，也无法找回。丢失主密码等于丢失所有数据。建议使用足够长的短语式密码，并把它单独记录在安全的物理位置。

第二步，立即关闭开放注册

账号创建完成后，编辑 compose.yaml，把 SIGNUPS_ALLOWED 改为 false：

      SIGNUPS_ALLOWED: "false"

重启服务：

docker compose up -d

这一步不能省。 保持开放注册意味着任何扫描到你域名的人都能在你的服务器上创建账号。密码服务的域名很容易被识别，开放注册状态下被注册是迟早的事。

需要给家人或同事使用时，通过管理后台发送邀请，而不是重新打开注册。

第三步，开启两步验证

在账号设置中开启两步验证，绑定验证器应用。主密码加两步验证是这类服务的标准配置。

七、客户端对接

浏览器插件

1. 在浏览器扩展商店安装兼容的密码管理插件。
2. 打开插件设置，找到服务器地址或自托管配置项。
3. 填入 https://vault.example.com。
4. 用注册的账号和主密码登录。

关键点是登录前先设置好服务器地址，否则插件会连到默认的官方服务。

手机客户端

1. 安装对应的移动端应用。
2. 在登录页进入设置，填写自托管服务器地址。
3. 登录后开启生物识别解锁，日常使用更方便。
4. 确认离线访问已启用，服务端不可达时仍能查看已同步的条目。

桌面客户端

配置方式与手机端一致，先设服务器地址再登录。

八、验证部署是否成功

服务可通过 HTTPS 访问

curl -I https://vault.example.com

开放注册已关闭：退出登录后访问注册页面，应提示注册已禁用。这一项必须实测确认，仅改了配置不代表已生效。

条目可创建并同步：在网页端新建一条测试记录，然后在浏览器插件中刷新，确认能看到该记录。这验证了多端同步链路。

自动填充可用：访问任意登录页面，确认插件能识别表单并填入凭据。

手机端同步正常：在手机客户端中确认能看到刚创建的记录。

离线访问有效：手机端开启飞行模式，确认仍能查看已同步的条目。这一项关系到服务器故障时的可用性。

九、备份与恢复演练

密码库是所有自托管服务里备份优先级最高的。

备份内容

data 目录包含数据库文件、附件、账号配置和加密密钥，是完整的备份对象：

cd ~/apps/vaultwarden
docker compose stop
sudo tar -czf ~/vault-backup-$(date +%Y%m%d).tar.gz data
docker compose start

停服备份能保证数据一致性。库体积很小，停机时间通常只有几秒。

如果不希望停服，可以用 SQLite 的在线备份方式导出数据库文件，再单独打包附件目录。

备份要放到服务器之外

只存在本机的备份，在服务器故障时会一起消失。把备份同步到对象存储，并注意备份文件本身也包含敏感数据，存储桶权限必须设为私有，建议再加一层本地加密后再上传。

导出为可读格式作为兜底

除了文件备份，建议定期从客户端导出一份加密的库文件，保存在离线介质上。这样即使服务端完全无法恢复，也能通过导入的方式找回数据。导出文件请妥善保管，不要放在容易泄露的位置。

恢复演练必须做

这是最关键的一步。在另一台机器或另一个目录中：

1. 用备份的 data 目录启动一个新的 Vaultwarden 实例。
2. 用原账号和主密码登录。
3. 确认条目完整、附件可下载。

验证通过才能说明备份真正有效。备份能生成不代表能恢复，密码库这类数据没有试错机会。

升级前创建快照：版本升级前给实例创建一份快照。回滚会把整块系统盘恢复到快照时间点，之后的数据变更会被清除，运行中的实例会自动关机。使用存储型套餐的实例不支持创建快照。

十、日常维护建议

• 每周：确认备份任务执行成功。
• 每月：检查服务版本是否有安全更新；查看管理后台的用户列表，确认没有意外账号。
• 每季度：做一次恢复演练；轮换一次管理后台令牌。
• 变更前：创建快照并完成备份。

几条安全底线：开放注册保持关闭；管理后台令牌足够随机且定期更换；账号开启两步验证；主密码单独妥善保管，不要只存在这个库里；服务端保持 HTTPS，不要为图省事用明文访问。

还有一点容易被忽略：不要把这台服务器的 SSH 密钥和云账号密码全部只保存在自建密码库里。服务器出问题时你需要登录控制台排障，凭据只在库里会让你无法进入。至少保留一份独立的紧急访问凭据。

部署完成后，如果还想为多个自建服务配置统一的域名入口和访问控制，或建立更完善的自动备份机制，可以作为下一步方向。

密码库对可用性和数据安全要求较高，运行它的机器建议使用轻量应用服务器并配合快照功能；备份归档可以使用对象存储 COS，注意存储桶权限须设为私有；需要更长有效期或特定品牌证书时，可通过SSL 证书申请后部署。