Vaultwarden 项目部署

项目定位：用 Rust 编写的轻量级 Bitwarden 兼容服务端（前身为 bitwarden_rs），可自托管密码管理器，兼容官方 Bitwarden 的网页、浏览器扩展、桌面和手机客户端。
开源协议：AGPL-3.0
声明：Vaultwarden 是第三方非官方项目，与 Bitwarden 公司无隶属关系。
文档依据：项目仓库说明与官方 Wiki（2026 年 11 月），具体参数以官方最新文档为准。

重要提醒：密码库是最敏感的数据。部署前先想清楚三件事：必须启用 HTTPS、必须做异地备份、必须关闭开放注册。

一、功能与特点

二、部署前准备

2.1 环境要求

• 一台 Linux 服务器（VPS、家用服务器、NAS 均可）
• Docker Engine 与 Docker Compose 插件
• 一个域名，并解析到服务器公网 IP（公网使用时）
• 放行 80 与 443 端口（使用反向代理自动签发证书时）
• 个人使用建议 512MB 以上内存，1 核 CPU 即可

2.2 为什么必须 HTTPS

Bitwarden 的网页端和多数客户端依赖浏览器的加密接口，该接口只在安全上下文（HTTPS 或本机 localhost）下可用。用 HTTP 通过 IP 访问时，网页端无法正常创建账号或登录。 因此：

• 局域网测试：可以用 localhost 访问
• 正式使用：必须配置域名 + HTTPS（反向代理）

三、Docker Compose 部署（推荐）

3.1 创建目录

mkdir -p ~/vaultwarden/vw-data
cd ~/vaultwarden

3.2 生成管理后台令牌（强烈建议使用哈希）

管理后台由 ADMIN_TOKEN 保护。不要使用明文弱密码，也不要留空（留空等于禁用后台）。 推荐生成 Argon2 哈希：

# 先临时拉起镜像，在容器内生成哈希（按提示输入两次你自己的强密码）
docker run --rm -it vaultwarden/server:latest /vaultwarden hash

命令会输出形如 $argon2id$v=19$m=65540,t=3,p=4$... 的字符串。把它写入 Compose 时，每个美元符号 $ 要写成两个 $$，否则 Docker Compose 会把它当成变量引用而报错。

也可以把令牌放进 .env 文件，由 Compose 引用，减少转义混乱。

3.3 编写 docker-compose.yml

下面是同时包含 Vaultwarden 与 Caddy 反向代理的完整示例，Caddy 会自动申请并续期证书：

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://你的域名"
      SIGNUPS_ALLOWED: "true"        # 创建完自己的账号后改为 false
      INVITATIONS_ALLOWED: "true"
      ADMIN_TOKEN: "$$argon2id$$v=19$$m=65540,t=3,p=4$$这里替换为你的哈希"
      TZ: "Asia/Shanghai"
    volumes:
      - ./vw-data:/data
    expose:
      - "80"

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config
    depends_on:
      - vaultwarden

说明：

• DOMAIN 必须填写你最终用于访问的完整地址，并以 https 开头，否则附件、邮件链接等功能会异常。
• Vaultwarden 容器只在内部暴露 80 端口，不直接映射到公网，所有流量由 Caddy 接入。
• 生产环境建议把镜像固定到具体版本号，升级时再手动修改，避免意外变更。

3.4 编写 Caddyfile

在同目录创建 Caddyfile：

你的域名 {
    encode zstd gzip
    reverse_proxy vaultwarden:80
}

近期版本的 Vaultwarden 已把实时通知（WebSocket）并入主端口，通常无需再单独代理额外端口。如使用较旧版本，请参照官方 Wiki 的代理示例补充。

3.5 启动

docker compose pull
docker compose up -d
docker compose logs -f

等待证书签发完成后，用浏览器访问你的域名，点击「创建账户」，注册第一个账号。

四、首次配置与安全加固

4.1 创建账号后立即关闭注册

注册好自己（和家人）的账号后，把 SIGNUPS_ALLOWED 改为 "false"，然后重新应用：

docker compose up -d

之后新增用户请通过管理后台邀请，避免陌生人注册。

4.2 管理后台

访问「你的域名/admin」，使用你设置 ADMIN_TOKEN 时输入的原始密码登录（不是哈希串）。后台可以：

• 查看和管理用户、邀请新用户
• 在线修改部分配置，并测试邮件发送
• 查看诊断信息

建议：

• 管理后台若不常用，可在不需要时清空 ADMIN_TOKEN 来禁用。
• 也可以在反向代理层对 /admin 路径做 IP 白名单限制。

4.3 开启二步验证

在每个账号的安全设置中启用 TOTP 或硬件密钥（WebAuthn / FIDO2），并妥善保存恢复码。

4.4 配置邮件（SMTP）

邮件用于账号验证、邀请和部分提醒。在环境变量中添加：

      SMTP_HOST: "你的SMTP服务器"
      SMTP_FROM: "发件地址"
      SMTP_PORT: "587"
      SMTP_SECURITY: "starttls"
      SMTP_USERNAME: "SMTP账号"
      SMTP_PASSWORD: "SMTP密码"

不想自建邮件服务，可使用第三方事务邮件服务的 SMTP 中继。

4.5 其他建议的环境变量

五、客户端接入

1. 安装官方 Bitwarden 的浏览器扩展、桌面端或手机应用。
2. 在登录界面点击「自托管环境」之类的选项（不同客户端文字略有差异）。
3. 在「服务器地址」中填入你的域名（以 https 开头），保存。
4. 使用你在网页端注册的邮箱和主密码登录。

注意：

• 主密码无法找回，遗忘后数据将无法解密，请妥善记忆并离线备份恢复信息。
• 手机端的推送通知需要额外向官方申请推送密钥，不配置也能正常同步，只是实时性稍差。

六、备份与恢复（最关键）

6.1 需要备份的内容

位于 vw-data 目录：

6.2 正确备份 SQLite

不要直接复制正在运行的数据库文件，可能得到损坏的副本。应使用 SQLite 自带的在线备份命令：

mkdir -p ~/vw-backup
sqlite3 ~/vaultwarden/vw-data/db.sqlite3 ".backup '$HOME/vw-backup/db-$(date +%F).sqlite3'"
tar czf ~/vw-backup/files-$(date +%F).tar.gz -C ~/vaultwarden/vw-data attachments sends config.json

若服务器没有 sqlite3 命令，请先安装，或停止容器后再整目录复制。

6.3 自动化与异地

• 用 cron 每天执行一次备份脚本，并保留最近若干份。
• 备份文件同步到异地（另一台机器、对象存储等），并对备份文件加密，因为它包含密码库密文数据。
• 遵循 3-2-1 原则：3 份副本、2 种介质、1 份异地。
• 每隔一段时间做一次恢复演练，确认备份真的可用。

6.4 恢复步骤

1. 停止容器：docker compose down
2. 把备份的数据库、附件等文件放回 vw-data 目录
3. 启动：docker compose up -d
4. 登录验证数据是否完整

七、升级与维护

cd ~/vaultwarden

# 升级前先做一次备份，并查看发布说明
docker compose pull
docker compose up -d

# 清理旧镜像
docker image prune

建议：

• 固定版本号，按需升级，而不是无脑追 latest。
• 密码管理器涉及安全修复，应关注发布说明并及时升级。
• 定期检查证书、磁盘空间与备份任务是否正常。

八、安全与运维建议

1. 只暴露必要端口：容器不直接映射到公网，仅反向代理对外提供 443。
2. 防暴力破解：结合日志与 fail2ban，封禁多次登录失败的 IP。
3. 关闭开放注册：完成建号后立刻关闭。
4. 保护管理后台：使用哈希令牌，必要时限制来源 IP 或平时禁用。
5. 系统更新：保持系统与 Docker 版本更新，配置防火墙。
6. 离线保存关键信息：主密码、二步验证恢复码、管理后台密码，在离线安全位置各留一份。
7. 不要把唯一副本放在同一台机器上：服务器故障或被入侵时，异地备份是最后的保障。

九、常见问题排查

十、命令速查

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart vaultwarden

# 查看日志
docker compose logs -f vaultwarden

# 生成管理令牌哈希
docker run --rm -it vaultwarden/server:latest /vaultwarden hash

# 升级
docker compose pull && docker compose up -d

# 在线备份 SQLite
sqlite3 vw-data/db.sqlite3 ".backup 'db-backup.sqlite3'"

附：项目关键信息

• 项目名称：Vaultwarden（原 bitwarden_rs）
• 仓库作者：dani-garcia
• 主要语言：Rust
• 协议：AGPL-3.0
• 镜像名称：vaultwarden/server
• 容器内数据目录：/data
• 容器内服务端口：80