Vaultwarden 部署与使用指南

一个轻量、安全、自托管的密码管理解决方案

##项目简介

Vaultwarden 是 Bitwarden 的非官方 Rust 重写版服务端，与 Bitwarden 官方客户端 100% 兼容，但资源占用极低，适合个人、家庭及小型团队自托管部署。

• GitHub 地址：https://github.com/dani-garcia/vaultwarden
• Bitwarden 客户端下载：https://github.com/bitwarden/mobile/releases

系统要求

Docker 部署

快速启动（测试用）

docker run -d --name vaultwarden \
  -v vaultwarden-data:/data \
  -p 8080:80 \
  -e ADMIN_TOKEN="zws@123!vaultwarden" \
  --restart unless-stopped \
  vaultwarden/server:latest

访问 http://localhost:8080 即可使用。

生产级部署（推荐）

创建 docker-compose.yml：

version: '3'

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      WEBSOCKET_ENABLED: "true"          # 启用实时同步
      SIGNUPS_ALLOWED: "true"            # 允许注册（注册完成后建议改为 false）
      ADMIN_TOKEN: "$argon2id$v=19$m=65536,t=3,p=4$..."  # Argon2 PHC 格式的管理员令牌
      SMTP_HOST: "smtp.qq.com"           # SMTP 邮件服务器（可选，用于密码找回）
      SMTP_FROM: "your-email@qq.com"
      SMTP_PORT: "587"
      SMTP_SECURITY: "starttls"
      SMTP_USERNAME: "your-email@qq.com"
      SMTP_PASSWORD: "your-auth-code"    # QQ 邮箱填写授权码，非密码
    volumes:
      - vaultwarden-data:/data
    ports:
      - "127.0.0.1:8080:80"              # 仅本地监听，通过反向代理暴露

volumes:
  vaultwarden-data:

启动：

docker compose up -d
docker logs -f vaultwarden

生成安全的 ADMIN_TOKEN

切勿使用明文密码！ 使用 Argon2 PHC 字符串：

# 在 Vaultwarden 容器内生成
docker run --rm -it vaultwarden/server:latest vaultwarden hash

# 或使用 argon2 工具
echo -n "你的强密码" | argon2 "$(openssl rand -hex 16)" -id -t 3 -m 16 -p 4 -l 32 -e

将生成的字符串填入 ADMIN_TOKEN。

客户端配置

安卓客户端下载

从 Bitwarden GitHub Releases 下载：

• 官方标准版：com.x8bit.bitwarden.apk（60.5 MB）
• F-Droid 纯净版：com.x8bit.bitwarden-fdroid.apk（66.9 MB，无 Google 服务）
• 校验文件：bw-android-apk-sha256.txt

下载地址：https://github.com/bitwarden/mobile/releases

连接自托管服务端

1. 打开 Bitwarden App → 登录页面点击设置齿轮
2. 选择自托管环境
3. 输入你的 Vaultwarden 地址：https://vault.yourdomain.com
4. 使用注册的账号密码登录

安卓自动填充设置

系统级自动填充（Android 8+）：

手机设置 → 密码与安全/系统 → 自动填充服务 → 选择 Bitwarden

品牌差异：

• 小米/红米：设置 → 密码与安全 → 智能密码管理
• 华为：设置 → 系统和更新 → 语言和输入法 → 自动填充服务
• OPPO/vivo：设置 → 其他设置 → 键盘与输入法 → 自动填充
• 三星：设置 → 常规管理 → 语言和输入 → 自动填充服务

辅助功能模式（兼容性更好）：

Bitwarden App → 设置 → 自动填充 → 使用自动填充辅助功能 → 开启

安全设置

两步验证（2FA）

Web 端 → 设置 → 安全 → 两步登录 → 启用

支持方式：

• 验证器应用（Google Authenticator、Aegis 等）
• YubiKey / FIDO2 安全密钥
• 邮件验证
• Duo Security

⚠️ 务必保存恢复代码！ 丢失 2FA 设备且无恢复代码 = 账户永久锁定。

紧急访问

设置 → 安全 → 紧急访问 → 指定信任联系人

• 设置等待期（如 7 天）
• 紧急情况下联系人可申请接管账户

URI 匹配检测

编辑密码条目 → URI 设置 → 选择匹配模式：

邮件配置（QQ 邮箱示例）

获取授权码：

1. 登录 QQ 邮箱 → 设置 → 账户
2. 开启 SMTP 服务 → 发送短信验证
3. 获得 16 位授权码，填入 Password 字段

备份策略

# 定时备份脚本（加入 crontab）
tar czf /backup/vaultwarden-$(date +%Y%m%d).tar.gz /path/to/vaultwarden/data

数据库为单个 SQLite 文件（data/db.sqlite3），备份简单：

1. 停止容器或确保无写入
2. 复制 data/ 目录
3. 加密后备份到异地存储

常见问题

提示：注册完成后，建议将 SIGNUPS_ALLOWED 设为 false 关闭公开注册，防止未授权用户创建账户。