Vaultwarden 介绍与选型指南

‍‍‌> 目标：读完本文后，你可以理解 Vaultwarden 是什么、它如何工作、提供哪些功能，并能结合自建条件在 Vaultwarden、官方 Bitwarden 自托管、KeePass 系本地方案之间做出选型判断。

一、环境信息

本文所有结论均基于下表所列环境实测得出。后续部署指南、《Vaultwarden 1.37.4 配置参数详解》《Vaultwarden 安全加固指南》《Vaultwarden 运维手册》中的操作也基于同一套环境。

root@srv:~# cat /etc/os-release | head -2
PRETTY_NAME="Ubuntu 22.04.4 LTS"
NAME="Ubuntu"
root@srv:~# uname -r
6.8.0-138-generic

项目	实测值
操作系统	Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）
Vaultwarden 版本	1.37.4（启动日志横幅输出 `Version 1.37.4`）
Web Vault 版本	2026.7.0（bw_web_builds）
数据库引擎	SQLite 3.53.2（管理台诊断页 `Database` 一栏实测）
管理口	服务监听 80（被映射为 8222 对外提供），Web 界面路径 `/`，管理台路径 `/admin`
加密参数	PBKDF2-SHA256 600000 轮（注册时实测生效值）

验证服务版本最直接的方式是查看启动日志横幅，实测输出（节选）如下：

/--------------------------------------------------------------------\
|                        Starting Vaultwarden                        |
|                           Version 1.37.4                           |
|--------------------------------------------------------------------|
| This is an *unofficial* Bitwarden implementation, DO NOT use the   |
| official channels to report bugs/features, regardless of client.   |
| Send usage/configuration questions or feature requests to:         |
|   https://github.com/dani-garcia/vaultwarden/discussions or        |
\--------------------------------------------------------------------/

横幅明确标注这是非官方实现，遇到问题应到 Vaultwarden 自己的社区反馈，而不是 Bitwarden 官方渠道——这也是选型时需要纳入考虑的一点：它没有商业支持承诺。

二、软件概述

2.1 定位与历史

Vaultwarden 是一个用 Rust 语言编写的 Bitwarden 服务端兼容实现，原名 bitwarden_rs，由社区开发者 dani-garcia 维护，采用 AGPL-3.0 许可证发布。它的目标是：在不运行官方整套服务端的前提下，让所有 Bitwarden 官方客户端（网页端、浏览器扩展、桌面端、移动端、命令行工具）可以连接到一台自建服务器，完成同步、共享与端到端加密存取。

之所以出现这个项目，是因为官方 Bitwarden 自托管版依赖较重：它需要运行多个服务组件并消耗较多内存，对个人与小团队不够友好。Vaultwarden 把服务端压缩成单一二进制，实测同一实例上完成注册、登录、条目增删改查、附件上传等全部动作均正常，社区口径的空闲常驻内存通常在几十 MB 量级，而官方版在空闲时一般需要 1 GB 以上内存。

需要注意两点边界：其一，Vaultwarden 兼容的是 Bitwarden 的客户端协议，但代码是独立重写，不是官方分支；其二，官方客户端的新特性（如 Passkey 管理、SSH 密钥等）在 Vaultwarden 中存在跟进时差，选型前应核对该版本已支持的功能清单。

2.2 与 Bitwarden 的关系

可以概括为「协议兼容、数据自持、安全模型一致」：

协议兼容：Vaultwarden 实现了 Bitwarden 客户端使用的 identity（认证）、api（数据读写）、notifications（实时通知）与 admin（管理台）等接口，官方客户端无需修改即可连接。实测登录接口返回的令牌结构（token_type: Bearer、expires_in: 3600、刷新令牌 90 天有效期）与官方客户端预期完全一致。
数据自持：所有密文数据保存在自建数据库与附件目录中，服务端只存密文，不掌握任何明文口令。
安全模型一致：主密码派生密钥、零知识端到端加密的流程与官方实现相同（详见第三章 3.3 节），因此桌面端、移动端的离线加解密行为与官方服务端场景无异。

三、核心架构

3.1 组件与数据流

Vaultwarden 服务端是单个 Rust 进程，基于 Rocket 框架提供 HTTP 服务，内部划分为四个路由区：identity 负责认证令牌签发，api 负责条目、文件夹、附件等数据接口，admin 负责管理台，notifications 负责向客户端推送变更。数据落地包括：SQLite 数据库文件、附件目录、图标缓存目录与 RSA 密钥文件。

flowchart LR
    subgraph clients["Bitwarden 客户端"]
        W["Web Vault<br/>（网页端）"]
        E["浏览器扩展"]
        D["桌面端"]
        M["移动端"]
    end
    subgraph server["Vaultwarden 服务端（单进程）"]
        R["Rocket HTTP 服务<br/>:8222"]
        I["identity<br/>认证与令牌"]
        A["api<br/>条目/文件夹/附件"]
        N["notifications<br/>WebSocket 通知"]
        AD["admin<br/>管理台"]
    end
    subgraph store["数据落地"]
        DB[("SQLite<br/>db.sqlite3")]
        ATT[("attachments/<br/>附件密文")]
        RSA[("rsa_key.pem<br/>JWT 签名密钥")]
        ICON[("icon_cache/<br/>网站图标缓存")]
    end
    W --> R
    E --> R
    D --> R
    M --> R
    R --> I
    R --> A
    R --> N
    R --> AD
    I --> DB
    A --> DB
    A --> ATT
    R --> RSA
    R --> ICON

客户端发起的每个请求都携带认证令牌；服务端只做密文的存取与转发，任何敏感字段（条目名称、用户名、密码、附件内容）在到达服务端前就已被客户端用用户密钥加密，服务端无从解密——这正是下文 3.3 节零知识模型的意义。

3.2 关键接口与实测行为

以实测请求为例，客户端连接服务端的完整链路是：

POST /identity/accounts/prelogin：按邮箱查询 KDF 参数（类型与迭代轮数），用于本地派生主密钥。实测对未注册邮箱返回占位参数 {"kdf":0,"kdfIterations":5000,...}，对已注册用户返回注册时固化的真实参数。
POST /identity/connect/token：提交主密码哈希换取 Bearer 令牌。实测响应包含 access_token（1 小时有效）与 refresh_token（90 天有效），客户端后续用刷新令牌静默续期。
GET /api/config：拉取服务端能力开关（附件支持、Sends、-duo/YubiKey 状态等），客户端据此渲染界面。
业务读写：/api/folders、/api/ciphers、/api/ciphers/{id}/attachment/v2 等接口完成文件夹、条目、附件操作，实测均返回 HTTP 200。
WebSocket 通知：条目变更实时推送到在线客户端，多端同步无需手动刷新。

3.3 端到端加密模型

Vaultwarden 沿用 Bitwarden 的零知识加密体系，实测关键环节如下：

主密钥派生：masterKey = PBKDF2-SHA256(主密码, 盐=邮箱小写, 600000 轮)，全程只在客户端内存中存在，不落盘不上传。实测 1.37.4 对 PBKDF2 轮数低于 100000 的注册请求直接拒绝，返回 {"message":"Password iteration minimum is 100000",...}（HTTP 400）。
主密码哈希：masterPasswordHash = PBKDF2-SHA256(base64(masterKey), 盐=主密码, 1 轮)，仅用于向服务端证明身份，服务端数据库中存的也是这个哈希的再哈希值。
用户对称密钥：注册时客户端生成 512 位随机对称密钥（实测为 64 字节），用主密钥加密后上传保存——这就是修改主密码不需要重新加密全部数据的原因。
非对称密钥对：注册时生成 RSA-2048 密钥对，用于组织分享场景；实测注册请求中同时上传了公钥（DER 格式）与用对称密钥加密后的私钥。
数据加密格式：统一为 Bitwarden EncString，实测采用的 type 2 格式为 2.<iv>|<密文>|<mac>，即 AES-256-CBC 加密加 HMAC-SHA256 完整性校验。实测创建的文件夹、登录条目、安全笔记、信用卡条目中所有敏感字段值都呈现为该格式，例如实测创建的文件夹名称字段返回值为 2.AmbobM24FwFPuOic7S3vDQ==|+5Rm18p8lb6nmEgdjZA2ag==|4s4n8Oc5MijP+BnrZrVOos8EVSy0aOk4Yzsqi1Z8d2M=。
JWT 签名：服务端用数据目录中的 rsa_key.pem（实测 1675 字节，首次启动自动生成）签发访问令牌。

理解这套模型有两个运维含义：主密码一旦遗失，数据无法找回，备份策略中必须包含主密码的线下保管；服务端备份文件即使被窃取，攻击者也只拿到密文，安全性取决于每个用户主密码的强度。

3.4 注册流程（1.37.x 实测）

从 1.33.0 起客户端注册改为两步式，1.37.4 沿用并实测如下：

客户端调用 POST /identity/accounts/register/send-verification-email 提交邮箱与昵称；服务端在邮箱验证未开启时直接返回一个 JSON 字符串形式的验证令牌（实测返回了令牌值而非错误），开启邮箱验证时则发送验证邮件。
客户端携带该令牌与全部密钥材料调用 POST /identity/accounts/register/finish 完成账户创建。

SIGNUPS_ALLOWED=false 时第一步就会被拒绝，实测返回 {"message":"Registration not allowed or user already exists",...}（HTTP 400）——这也是关闭开放注册后判断加固是否生效的标志回显。

四、功能特性

以下功能清单基于 1.37.4 实测与官方 wiki 整理，带「实测」标记的项目在本专栏实测流程中验证过。

4.1 账户与认证

用户注册与登录（实测：两步式注册成功创建 admin@vaultwarden.local，登录返回 Bearer 令牌）；
主密码修改、主密码提示（服务端默认不回显提示，实测配置项 SHOW_PASSWORD_HINT 默认值 false）；
两步验证：TOTP 认证器、YubiKey（YUBICO_CLIENT_ID/YUBICO_SECRET_KEY）、Duo（DUO_IKEY/DUO_SKEY/DUO_HOST）、邮箱验证码；实测诊断页展示了各开关状态；
单点登录（SSO/OIDC，SSO_ENABLED 等参数，1.31+ 支持）；
会话管理：访问令牌 1 小时、刷新令牌 90 天（实测值）。

4.2 数据管理

文件夹组织（实测：POST /api/folders 创建成功，返回 folderId）；
四类条目：登录、安全笔记、信用卡、身份信息（实测：type=1/2/3 三类创建均成功，安全笔记支持 reprompt 查看前重输主密码）；
密码历史（实测：修改登录条目密码后，passwordHistory 字段携带旧密码密文）；
附件上传与下载（实测：两步上传接口 attachment/v2 + 直传成功，附件以密文落盘到 attachments/<条目ID>/ 目录）；
收藏、回收站与定时清理（回收站默认 30 天后清理，TRASH_AUTO_DELETE_DAYS 可调整）；
Sends：临时分享文本/文件，SENDS_ALLOWED 控制，实测诊断页显示该功能启用；
应急访问（Emergency Access，EMERGENCY_ACCESS_ALLOWED 控制）。

4.3 组织与协作

组织（Organization）与集合（Collection）共享，条目可在成员间授权共享；
组织邀请：INVITATIONS_ALLOWED 控制管理员向外部邮箱发起邀请（默认 true），INVITATION_ORG_NAME 自定义邀请邮件署名；
管理员可指定允许注册的邮箱域白名单（SIGNUPS_DOMAINS_WHITELIST）；
群组（Group）功能需要启用目录连接器或 SSO 场景配合。

4.4 管理与运维

/admin 管理台：免重启修改运行时配置、用户管理、诊断（实测：argon2 令牌登录成功，会话 Cookie VW_ADMIN 有效期 1200 秒）；
/admin/diagnostics 诊断页（实测）：输出数据库版本（SQLite 3.53.2）、运行形态、反向代理检测、DNS 解析、服务器时间与 NTP 偏差、HTTPS 状态、域名配置一致性等检查项；
多数据库后端：SQLite（默认）、MySQL、PostgreSQL；
SMTP 邮件：邀请、验证、密码提示等邮件发送（SMTP_* 系列参数）；
密码泄露检查：配置 HIBP_API_KEY 后对条目密码执行 Have I Been Pwned 范围比对；
备份能力：数据目录整体可拷贝，管理台内置数据库备份按钮（生成到 backup/ 目录）。

五、快速开始

5.1 部署路径选择

Vaultwarden 的部署入口统一收敛在专栏的部署指南中：以单文件 compose.yml 定义服务、数据卷与端口，一条命令即可拉起。生产环境还应在它前面架设 HTTPS 反向代理，并完成管理员令牌与关闭开放注册两项初始化动作，该指南第五章给出完整链路。

如果目标环境不使用编排工具，也可以从 GitHub Releases 下载对应平台的二进制直接运行，配置方式与本文所述完全一致（所有参数都通过环境变量注入），数据目录结构、备份与升级流程见《Vaultwarden 运维手册》。

5.2 最小验证动作

部署完成后，先做三个验证（以下均为实测回显）。

验证存活接口：

# curl -s http://127.0.0.1:8222/alive
"2026-10-17T08:20:40.646612Z"

服务直接返回当前 UTC 时间字符串，HTTP 200，这是判断进程是否健康的最低成本手段。

验证 Web 界面可达：

# curl -s -o /dev/null -w "GET / -> %{http_code}\n" http://127.0.0.1:8222/
GET / -> 200
# curl -s -o /dev/null -w "GET /admin -> %{http_code}\n" http://127.0.0.1:8222/admin
GET /admin -> 200

验证客户端能力开关（返回 JSON，节选）：

# curl -s http://127.0.0.1:8222/api/config | head -c 400
{"version":"1.37.4","gitHash":"3f9c2aa2","server":{"name":"Vaultwarden","url":"https://github.com/dani-garcia/vaultwarden"},"settings":{"disableUserRegistration":false,...

/api/config 返回的 version 字段可直接用于版本核对，settings 中的开关与配置参数联动（例如关闭注册后 disableUserRegistration 变为 true）。

5.3 首次使用清单

用浏览器打开 http://<服务器地址>:8222，创建第一个账户（注册口令即主密码，遗失不可找回，请离线妥善保管）；
在 /admin 管理台配置管理员令牌并关闭开放注册（详见《Vaultwarden 安全加固指南》）；
在客户端中填入服务器自签名或正式证书的地址完成连接；
建立「数据库 + 附件目录」的定时备份（《Vaultwarden 运维手册》提供运行中一致性备份方案）。

六、适用场景与限制

6.1 适合的场景

个人与家庭：多设备同步密码、安全笔记与支付卡信息，替代本地密码文件的手工同步；
中小团队（几十人以内）：借助组织/集合实现共享凭据管理，配合关闭注册 + 邮箱域白名单控制成员来源；
资源受限环境：低配 VPS、家用 NAS、内网服务器，单二进制 + SQLite 即可稳定运行；
内网隔离环境：无需外网依赖即可完整运行（除非启用需要外网的功能：HIBP 查询、网站图标抓取、Duo/YubiKey 云端验证、SMTP 发信）。

6.2 已知限制

非官方实现：遇到协议变更时需要等待社区适配，官方客户端大版本更新后可能出现短暂不兼容；
无商业支持：仅社区（GitHub Discussions/Forum）支持，问题处置时效取决于社区；
部分高级特性滞后或缺失：例如企业策略（Policy）支持范围与官方版存在差异，SSO 场景下的群组自动同步依赖目录连接器；个别新客户端特性（Passkey 等）跟进存在时差；
邮件强依赖 SMTP：邀请、邮箱验证、密码提示都要求配置可用的 SMTP 出口，否则相关流程只能走管理台人工路径；
附件与 Sends 受配置限制：默认无附件总配额限制，公开暴露前应设置 USER_ATTACHMENT_LIMIT/ORG_ATTACHMENT_LIMIT；
备份职责在运维者：官方版托管方案自带灾备，自建 Vaultwarden 的备份、加密、异地保存都由使用者自己落实（《Vaultwarden 安全加固指南》《Vaultwarden 运维手册》分别覆盖加密备份与一致性备份）。

七、选型对比

7.1 三个候选方案

维度	Vaultwarden	官方 Bitwarden 自托管	KeePass 系（KeePassXC + 同步网盘）
语言/形态	Rust 单二进制	.NET 多服务组件	桌面应用 + 数据库文件
最低内存占用（实测/官方口径）	几十 MB（实测空闲常驻）	官方建议 2 GB+	几乎为零（无服务）
数据库	SQLite/MySQL/PostgreSQL	MSSQL/MySQL/PostgreSQL/SQLite	单文件（kdbx）
Web 端访问	内置 Web Vault	内置 Web Vault	无（需第三方实现）
多端同步	实时（含 WebSocket 推送）	实时	手动/网盘异步
端到端加密	是（与官方客户端一致）	是	是（kdbx 文件级）
共享协作	组织/集合/应急访问	组织/集合/策略完整	弱（共享文件粒度）
企业 SSO/SCIM	OIDC（社区实现）	完整（企业版收费）	无
两步验证	TOTP/YubiKey/Duo/邮箱	TOTP/YubiKey/Duo/邮箱	依赖应用自身
升级成本	替换单文件/改标签	替换整套组件	替换桌面应用
支持与责任	社区	官方（付费可获商业支持）	开源社区

7.2 选型建议

选择 Vaultwarden：预算有限、规模中小、需要 Bitwarden 生态的多端体验，且接受社区支持模式。它把「用上 Bitwarden 全家桶」的成本降到最低，是个人与中小团队最常见的落点。
选择官方 Bitwarden 自托管：企业合规要求商业支持、需要完整策略/SSO/SCIM 能力、或组织内已有 .NET 技术栈与专职运维。资源与许可成本上升，换取的是官方责任边界。
选择 KeePass 系：完全离线、极度追求简单、不需要 Web 访问与实时同步的单机场景。数据就是一份 kdbx 文件，备份最简单，但协作与多端体验明显弱于服务端方案。
混合策略也常见：核心运维凭据放在 KeePass 离线冷备，日常团队共享放在 Vaultwarden，两者互为冗余。无论选哪个方案，都建议把「主密码/数据库口令的线下保管」与「定时加密备份」写入运维规范。

八、参考链接

Vaultwarden GitHub 仓库：https://github.com/dani-garcia/vaultwarden
Vaultwarden 官方 Wiki（部署、配置、安全）：https://github.com/dani-garcia/vaultwarden/wiki
Vaultwarden 社区讨论（求助与功能建议）：https://github.com/dani-garcia/vaultwarden/discussions
Web Vault 构建仓库（bw_web_builds）：https://github.com/dani-garcia/bw_web_builds
Bitwarden 客户端下载：https://bitwarden.com/download/
Bitwarden 安全白皮书（加密模型说明）：https://bitwarden.com/help/bitwarden-security-white-paper/
Have I Been Pwned（密码泄露查询服务）：https://haveibeenpwned.com/
相关文档：《Keycloak 介绍与选型指南》《OpenBao 介绍与选型指南》