先说清楚:密码库为什么值得自建
密码管理器是数字生活的命门:所有账号的钥匙都锁在一个库里。这个库放在厂商云端,方便,但你要信任厂商的服务器、订阅政策和账号风控;放在自己手里,信任对象就只剩自己这台 VPS。
Bitwarden 官方服务端功能全,但部署偏重(多个容器加 SQL Server 级别的数据库)。Vaultwarden 是社区用 Rust 重写的轻量实现,完整兼容 Bitwarden 的 API 和全部官方客户端,个人使用还能直接用上组织共享、文件附件等原本的付费功能,一个容器、一个 SQLite 文件、几十 MB 内存就能跑。对个人和小家庭来说,Vaultwarden 是自建密码库的最优解,没有之一。
主线:Compose 部署 → 配好域名与 HTTPS → 创建账号后立即关注册 → 设管理员令牌 → 客户端接入 → 备份这个「命门」目录。
Compose 部署
services: vaultwarden: image: vaultwarden/server:latest container_name: vaultwarden restart: unless-stopped environment: DOMAIN: "https://vault.example.com" SIGNUPS_ALLOWED: "true" INVITATIONS_ALLOWED: "false" TZ: Asia/Shanghai volumes: - ./vw-data:/data ports: - "127.0.0.1:8080:80"启动:
mkdir -p ~/vaultwarden && cd ~/vaultwardendocker compose up -d所有数据都在 ./vw-data 一个目录里:db.sqlite3 是密码库数据库,attachments/ 是文件附件,rsa_key.pem 是加密相关密钥。这个目录就是你的全部身家,后面备份篇会再强调。
在 Nginx Proxy Manager 里给 vault.example.com 加一条 Proxy Host,转发到 127.0.0.1:8080,开启 Websockets Support 并申请 SSL 证书(方法见 Nginx Proxy Manager:所有自建服务的统一入口)。
WARNINGVaultwarden 必须走 HTTPS,明文 HTTP 下 Web 端会直接拒绝注册和登录。这是因为浏览器只在安全上下文里提供密码库依赖的加密 API。先把证书配好、确认
https://能打开,再进行下一步,不要在 HTTP 上折腾为什么按钮点不动。
创建账号,然后立刻关门
浏览器打开 https://vault.example.com,点「创建账户」,用你的常用邮箱和一个足够长的主密码注册。主密码是整个密码库的最后一道锁,Vaultwarden 服务端存的只是加密后的数据,主密码忘了,库里的数据谁都救不回来,包括你自己。建议用一句长短语,并把主密码本身离线记在安全的地方。
账号能正常登录、同步没问题之后,马上把注册关掉。改 Compose 环境变量:
SIGNUPS_ALLOWED: "false"然后 docker compose up -d 让配置生效。之后再有人打开这个地址,只会看到登录框,注册入口消失。需要给家人开账号时,临时改回 true 注册完再关,或者用管理员后台发邀请。
设置管理员令牌
Vaultwarden 有一个隐藏的管理后台 /admin,能看用户列表、发邀请、查配置。开启方式是设置 ADMIN_TOKEN。不要用明文短密码,官方推荐用 Argon2 哈希。生成方法:
docker run --rm -it vaultwarden/server /vaultwarden hash按提示输入你的管理员密码,它会输出一段 $argon2id$... 开头的哈希值,填进 Compose:
ADMIN_TOKEN: "$argon2id$v=19$m=65540,t=3,p=4$..."重启后访问 https://vault.example.com/admin,用刚设置的管理员密码进入。注意这个后台权限极高,能直接删用户,令牌本身要当主密码同等级别保管。更进一步的访问控制思路见 自建服务安全加固:最小暴露与访问控制。
常用配置项汇总:
| 环境变量 | 作用 | 推荐值 |
|---|---|---|
| DOMAIN | 对外访问地址 | https://vault.example.com |
| SIGNUPS_ALLOWED | 是否开放注册 | 建号后改 false |
| INVITATIONS_ALLOWED | 是否允许邀请加入组织 | 按需,默认 false |
| ADMIN_TOKEN | 管理后台令牌 | Argon2 哈希值 |
| SMTP_HOST 等 | 邮件发送(邀请、验证码) | 有邮箱需求再配 |
| IP_HEADER | 反代后获取真实 IP 的请求头 | 默认 X-Real-IP 即可 |
客户端接入:全平台用官方 Bitwarden
Vaultwarden 最大的好处是不用装任何第三方客户端,Bitwarden 官方客户端全部原生支持自托管:
| 平台 | 客户端 | 接入方式 |
|---|---|---|
| Windows / macOS / Linux | Bitwarden 桌面端 | 登录界面点「自托管」,填服务器地址 |
| iOS / Android | Bitwarden App | 登录页右上角设置 → 自托管服务器地址 |
| 浏览器 | Bitwarden 扩展 | 设置 → 自托管环境,填 https://vault.example.com |
| 网页 | 直接打开域名 | Web Vault,无需安装 |
每个客户端第一次登录时,在输邮箱之前先找到「自托管 / Self-hosted」选项,把服务器地址填成你的域名,再正常登录。之后自动填充、同步、指纹/面容解锁都与官方云完全一致。
进阶玩法:
- 两步验证:在 Web 端账户设置里开 TOTP 两步验证,并保存好恢复代码;
- 家庭共享:Web 端新建「组织」,把家人邀请进来,共享文件夹里的密码全家可用,个人条目仍各自私密;
- 紧急访问/导出:定期在 Web 端导出一份加密备份(选「密码保护导出」),离线保存,作为最后的保险。
从旧密码管理方式迁过来
大多数人不是从零开始用密码库的,密码散落在浏览器、备忘录或者另一个密码管理器里。迁移到 Vaultwarden 的路径很顺滑:
- 从浏览器导出:Chrome / Edge / Firefox 的密码管理页面都能导出 CSV 明文文件;
- 在 Web Vault 里导入:「工具 → 导入数据」,格式选对应的浏览器或通用 CSV,一次性全部灌进来;
- 整理:导入后按网站逐个登录验证,顺手把弱密码、重复密码全改掉——迁移是最好的「密码卫生大扫除」时机,平时没动力干这件事;
- 销毁导出文件:CSV 是明文,导完确认无误后立即彻底删除,不要让它躺在下载文件夹里,那等于把全部密码明文放在桌面上。
另外两个值得知道的功能:
- Bitwarden Send:需要临时把一段文本或一个文件安全地发给别人时,在客户端里建一个 Send,生成带密码和过期时间的链接,对方打开即焚,比聊天软件里直接发密码体面得多;
- 密码健康报告:Web Vault 的「报告」里有弱密码、重复密码、已泄露密码检查(泄露检查会联网查询公开泄露库的哈希,介意的话可以不用),每季度跑一遍,慢慢把老账号的密码都换成随机生成的强密码。
给家人接入时的建议姿势:先在自己的账号里把组织和共享文件夹建好,再邀请家人注册(临时开注册或用管理后台邀请),手把手教他们在手机上装好 App 并开启生物识别解锁。密码库的推广难点从来不是技术,是让家人养成「新密码随手存进去」的习惯,前两周多提醒几次就好。
备份:这一个目录不能丢
Vaultwarden 的备份异常简单也异常重要:停容器或不停容器,把整个 vw-data 目录打包带走即可。但注意 SQLite 在写入瞬间直接拷贝可能拷到一半状态,最稳妥的做法是先 docker compose stop 再打包,或者用 sqlite3 的 .backup 命令做热备。完整的定时备份脚本和异地保存方案见 自建服务备份与迁移实战,请务必把这个目录纳入其中——密码库是所有自建服务里唯一「丢了就真的全完了」的数据。
常见问题与排障
1. 打开页面点注册/登录没反应或报错
先查是不是 HTTPS:地址栏必须是 https:// 且证书有效。再查 DOMAIN 环境变量是否与实际访问地址完全一致,不一致会导致部分请求被重定向到错误地址。
2. 客户端提示无法连接服务器 确认客户端里填的是自托管地址而不是用的官方账号体系;手机端还要检查 App 是否被系统省电策略限制后台。反代侧确认 NPM 里这条 Host 开了 WebSocket 支持,新版客户端的实时同步(增删密码立即推送到其他设备)依赖它。
3. 图标不显示、附件上传失败
网站图标抓取走的是服务端出网,VPS 出站受限时会失败,不影响核心功能。附件失败先查 vw-data 目录权限和磁盘空间,再查 NPM 是否限制了请求体大小,可在 NPM 的高级配置里加 client_max_body_size 50m;。
4. 忘了管理员令牌
改 Compose 里的 ADMIN_TOKEN 为新的明文或哈希,重启容器即可重置。注意这同时说明:能碰到服务器的人就能重置一切,服务器本身的安全才是根。
5. 登录时提示设备验证邮件收不到 新设备登录验证依赖邮件配置。没配 SMTP 时,可以在管理后台关闭新设备验证要求,或者干脆把 SMTP 配好——自建服务里凡是涉及账号的,配一个发信邮箱都值得。
6. 一台设备改了密码,其他设备迟迟不同步 先确认各客户端登录的都是同一个自托管地址(有人会误连到官方云,账号同名但数据完全两套);再检查服务器时间是否准确,时间漂移会导致同步令牌校验异常;最后在客户端里手动下拉刷新一次。反代层如果给 API 路径加了缓存规则,也会造成这种假象,密码库这类动态服务不要进任何缓存。
7. 能不能在库里存通行密钥(Passkey) 可以。Bitwarden 客户端支持把网站的 Passkey 直接存进密码库,Vaultwarden 作为服务端完整兼容。在支持 Passkey 的网站上注册时选「保存到 Bitwarden」即可,之后在任何登录了你自建库的设备上都能调用。把 Passkey 和密码放在同一个库里管理,省去了再单独维护一套凭据的麻烦。
8. 升级之后打不开,先别慌
Vaultwarden 升级偶尔会做数据库结构迁移,第一次启动慢是正常的,看日志等它跑完。真起不来就回滚:停容器,把镜像 tag 换回旧版本号,再把备份的 vw-data 放回去启动。所以升级前的动作永远是先备份、再 pull,这句话在本系列里已经出现很多次了,对密码库尤其成立。
小结
Vaultwarden 是投入产出比最高的自建服务之一:一个容器、几十 MB 内存,换来全平台密码同步和完整的数据自主权。部署本身十分钟的事,真正的功夫在规矩上——HTTPS 先行、注册随开随关、管理员令牌用哈希、主密码足够长、vw-data 必须备份。这几条守住了,它就是你所有自建服务里最让人安心的一个。