说实话我也曾是那种“一个密码走天下”的人直到某次数据泄露自查才发现自己的账号密码早就躺在某个公开的泄露库里。从那时候起才认真对待密码管理先后试过几款在线密码管理器同步确实方便但把全家密码交给别人服务器这件事始终觉得不踏实。后来转向自建服务器方案一路折腾下来最顺手、维护成本最低的就是轻量级开源密码管理器 Vaultwarden。自建搞定之后手机、电脑、浏览器插件都能无缝同步访问速度不受限数据完全在自己手里这就是所谓的密码自由。这篇文章里我会把 Vaultwarden 从方案选型、服务器准备、Docker 部署、反向代理配置到数据备份、客户端接入、故障排查的完整过程都梳理出来适合想摆脱云密码服务依赖、手上有台闲置小主机或云服务器的朋友直接参考复现。不管你会不会写代码只要具备基本的 Linux 操作能力跟着步骤走基本都能跑起来。1. 为什么我最终选择了自建密码库1.1 云密码服务与自建之间的账先算一笔账。免费的云密码服务确实方便但免费方案往往在设备同步数量上有种种限制跨设备功能也经常被阉割。即使数据加密和隐私政策写得漂亮作为用户你其实没法真正验证它到底怎么处理你的密码库。我见过有人为了全家人的账号安全买了好几年的付费密码服务一年几百块算下来真不便宜而且你还得一直相信对方不出事。密码库这种东西一旦服务方出了问题后果远比丢一个网站账号麻烦。自建方案的逻辑就是把信任模型掌握在自己手里。用一台每天电费几乎可以忽略的小主机换来一个只属于自己的密码库没有设备数量限制没有同步流量限制所有数据都在自己的磁盘上。Vaultwarden 的“轻量级”不是随便说说的它对硬件的要求低到夸张512MB 内存的小机器都能跑得很稳。这意味着它一旦部署好维护成本基本趋近于零——这也是我最终选择它的核心原因。1.2 Vaultwarden 到底是什么很多人听到 Vaultwarden 会先想到 Bitwarden。Bitwarden 本身是一款全平台密码管理器客户端覆盖手机、桌面和浏览器免费且开源。但官方提供的服务端是 .NET 重工程部署起来既庞大又吃资源对个人自建来说负担很重。Vaultwarden 是社区用 Rust 重新实现的兼容服务端API 完全兼容官方客户端但数据存储只用了一个 SQLite 数据库文件整个数据目录非常小备份就是直接拷文件。Vaultwarden 与官方服务端的关系可以理解成“官方客户端的自制替代服务端”。官方客户端能连的协议它几乎都能兼容端到端加密、组织共享、紧急访问、两步验证登录这些核心能力都有。而资源占用只有官方服务端的零头。所以它天然就是为个人、家庭或小团队自建场景准备的。1.3 自建这件事真正的难点在哪自建密码管理器很多人第一反应是“我自己有服务器搭个服务很轻松”。其实真正的难点从来不是跑起一个 Docker 容器而是怎么保证这个服务长期稳定、数据安全、随时可用。密码管理器是那种平时感觉不到存在、一旦出问题就非常要命的服务。要做好这件事至少得覆盖四个维度第一服务本身能跑起来并且跟着容器更新迭代第二访问链路是加密的不能用明文 HTTP 直接裸奔第三数据有备份能应对磁盘损坏和误删第四自己有排查问题的基本手段遇到客户端连不上、同步失败能定位原因。后面的内容我会围绕这四个维度展开每一步都会说明为什么这么做。2. 部署前的需求梳理与方案定型2.1 先想清楚这几个关键问题动手之前我强烈建议你先列一张需求清单。比如我自己的清单是这样的第一能在我所有设备上装上客户端包括手机、电脑和浏览器第二浏览器里能自动填充网页登录表单第三密码库的数据库文件得在我自己手里第四遇到问题我能自己排查而不是找客服第五最好不用花额外的服务费。这张清单直接决定了后续的部署方案。如果你只是收藏几个网址密码随便用个在线保管就行但如果你要把银行卡、邮箱、社交账号、甚至家庭成员的密码都放进去那就必须认真对待。另外还要想清楚要不要多人共用。Vaultwarden 支持组织共享功能可以给家人分一个组织共享家庭共用的账号密码这个能力在选择时一定要考虑进去。2.2 服务器与域名准备Vaultwarden 对服务器的要求是真的低。我用过一台树莓派级别的机器也用过只有 1 核 1G 内存的云服务器跑起来都没压力。系统推荐 Debian 或 Ubuntu因为 Docker 的支持最好遇到问题也容易搜到答案。域名这件事我的建议是尽量准备一个。原因很简单客户端同步时Vaultwarden 需要知道自己的访问地址如果直接暴露 IP 加端口浏览器扩展和手机 App 的证书信任、地址匹配都会很别扭。有域名之后还能挂自动签发的 HTTPS 证书访问体验和安全性完全不是一个级别。如果你实在不想买域名用免费二级域名也凑合但后面配置反向代理时会麻烦不少。2.3 备份的基本思想提前定好备份策略应该在部署之前就想清楚而不是等数据出问题再补救。Vaultwarden 的设计让备份异常简单服务运行中产生的所有数据都集中在一个数据目录里备份就相当于对那个目录做一次快照。这个特性直接决定了它的能维护性——不需要停服务、不需要导出导入只需要在磁盘上复制文件。我会在后面专门讲一套可落地的备份脚本。这里先明确思想密码库数据是不可再生的一旦丢了没有任何客服能帮你恢复。所以备份方案宁可冗余不可缺失。我的习惯是本地定时备份再往对象存储里同步一份异地的备份两条腿走路。3. 完整的 Docker 部署过程3.1 安装 Docker 与 Compose部署的第一步是准备 Docker 环境。以 Debian/Ubuntu 为例最简单的安装方式是用 Docker 官方安装脚本curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh脚本执行完会自动安装 Docker 引擎。接着再安装 Compose 插件apt install docker-compose-plugin安装完成后验证一下版本docker --version docker compose version看到版本号输出就说明环境没问题。这一步我踩过一个坑网上很多老教程还在用docker-compose命令中间有个横杠那是旧版独立的 Compose。新版 Docker 推荐的是docker compose子命令写配置和执行的逻辑是一样的但命令名不同新手照着老教程很容易卡住。3.2 编写编排文件Vaultwarden 官方推荐用 Docker Compose 部署。我会把编排文件放在/opt/vaultwarden目录下下面是完整的内容version: 3 services: vaultwarden: image: vaultwarden/server:latest container_name: vaultwarden restart: unless-stopped environment: DOMAIN: https://vault.example.com ADMIN_TOKEN: 用openssl生成的随机字符串 SIGNUPS_ALLOWED: false WEBSOCKET_ENABLED: true SMTP_HOST: smtp.example.com SMTP_PORT: 587 SMTP_SECURITY: starttls SMTP_FROM: vaultwardenexample.com SMTP_USERNAME: vaultwardenexample.com SMTP_PASSWORD: 你的SMTP密码 volumes: - ./vw-data:/data ports: - 127.0.0.1:8080:80这里有几个关键点需要解释一下否则你只是抄配置不知道里面在干什么。restart: unless-stopped让容器在服务器重启后自动拉起这是密码管理器必须的行为你总不能每次重启服务器后手动 docker start。ports映射成127.0.0.1:8080:80是把容器内的 80 端口只暴露给本机的 8080 端口外部网络无法直接访问这个端口必须经过后面要配置的反向代理。这样做的好处是少一个不设防的攻击面。DOMAIN这个环境变量特别重要。它告诉 Vaultwarden 自己的公网访问地址生成二步验证、邀请链接、客户端推送通知的时候都会用到这个地址。如果填错或者漏填客户端登录后会因为地址不匹配而出现各种诡异问题。ADMIN_TOKEN是管理后台的凭据建议用openssl rand -base64 48生成长度足够且完全随机。3.3 启动容器与初始化编排文件写好后在/opt/vaultwarden目录下执行docker compose pull docker compose up -dpull是拉取最新镜像up -d是后台启动容器。启动后可以用下面的命令查看日志docker compose logs -f日志里如果出现Vaultwarden is ready!之类的信息就说明服务已经起来了。这时候在服务器本地访问一下http://127.0.0.1:8080能看到登录页面就说明 Web 服务器正常。这里要提醒一句如果你是在有防火墙的云服务器上操作记得确认 8080 端口没有对外开放。我用127.0.0.1映射就是为了避免这种情况如果你不小心写成了8080:80相当于把 Vaultwarden 整个暴露在公网上非常危险。3.4 管理员后台与关闭注册容器首次启动后Vaultwarden 默认是允许注册新账号的。这个设置只适合安装测试阶段正式使用前必须关掉。具体的做法就是前面编排文件里的SIGNUPS_ALLOWED: false。但问题来了注册关掉之后你自己怎么创建第一个账号Vaultwarden 的管理后台提供了解决方案。打开https://你的域名/admin输入ADMIN_TOKEN的值进入管理页面然后在“用户管理”里先临时开启注册注册完自己的账号后再关闭。另一种方式是临时把SIGNUPS_ALLOWED改成true重启容器注册完再改回来。两种方法都有人用我个人更倾向于用管理后台操作因为不用重启容器体验更顺。管理后台里还可以做很多事情查看用户列表、禁用异常账号、调整组织配额、打开邮件日志等。第一次部署时建议把这里熟悉一下后面排查问题会经常用到。4. 反向代理与 HTTPS 配置4.1 为什么代理层是必须的Vaultwarden 自带的 Web 服务是纯 HTTP 的密码数据全都走明文传输这显然不能用。哪怕只是内网使用我也建议至少挂一层 TLS。公网环境下没有 HTTPS 的密码管理器就好比把钥匙挂在大门口。反向代理的角色就是把外网的 HTTPS 流量接收下来解密后转发给本机 8080 端口上的 Vaultwarden。域名那边解析到服务器 IP 后代理层负责自动申请和续期证书。这样一来客户端始终面对的是合法的 HTTPS 地址Vaultwarden 本身不需要处理证书逻辑架构非常干净。4.2 两套代理方案怎么选我试过 Nginx 和 Caddy 两种方案都有各自适合的场景。如果你希望配置最精简、自动续期证书不用操心选 Caddy。Caddy 的配置文件极短反向代理加自动 HTTPS 的写法就几行vault.example.com { reverse_proxy 127.0.0.1:8080 }把这段内容保存到CaddyfileCaddy 会自动申请证书并续期一条配置搞定。Caddy 的缺点是一些高级流量控制能力不如 Nginx 灵活但对 Vaultwarden 这种简单场景完全够用。如果你服务器上已经跑了 Nginx或者你喜欢传统 Nginx 的生态那用 Nginx 也没问题。完整配置如下server { listen 443 ssl; server_name vault.example.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /notifications/hub { proxy_pass http://127.0.0.1:8080; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; } }注意第二个location是给 WebSocket 用的。Vaultwarden 的实时通知功能依赖 WebSocket 连接如果代理层不特殊处理升级请求客户端会一直显示掉线或同步失败。4.3 验证代理配置是否正确配置完反向代理后需要检查几件事。第一浏览器访问https://你的域名能正常打开登录页浏览器地址栏显示锁标志。第二打开浏览器的开发者工具切到 Network 面板随便触发一次登录操作确认请求都是 HTTPS 且没有混合内容警告。第三如果客户端已经装好登录后确认可以正常同步。关于证书续期Caddy 会自动处理。Nginx 配合官方签发工具的话要设置定时任务自动更新证书。我见过不少人 Nginx 配置写好后就忘了证书这回事三个月后证书过期客户端全线罢工。如果 Nginx 用的是自动续期方案建议隔几个月确认一次续期任务有没有正常执行。5. 数据备份与恢复实操5.1 数据目录里到底有什么Vaultwarden 的所有数据都在挂载的vw-data目录里。第一次启动后目录下会逐步生成以下内容文件或目录作用优先级db.sqlite3核心数据库账号、密码库条目、组织关系的唯一存储位置必须备份config.json服务配置包含安装时的随机密钥、加密参数必须备份rsa_key/RSA 密钥对用于某些加密数据和邀请令牌的签名验证必须备份attachments/密码库条目中附带的安全附件加密后存储按需备份icon_cache/网站图标缓存属于可再生成数据无需备份备份时最核心的是前三个。尤其是rsa_key这个目录很多人会忽略结果密钥丢了以后部分加密数据无法解析悔都来不及。icon_cache丢了会自动重建不值得占备份空间。5.2 一套可以落地的备份脚本我平时使用的备份脚本逻辑很简单先停掉容器保证数据文件一致然后把整个数据目录打成压缩包最后和之前的每日备份一起做轮换。脚本如下#!/bin/bash # 备份目录 BACKUP_DIR/backup/vaultwarden DATA_DIR/opt/vaultwarden/vw-data DATE$(date %Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR # 停止容器确保数据一致 docker compose -f /opt/vaultwarden/docker-compose.yml stop # 压缩数据目录 tar -czf $BACKUP_DIR/vaultwarden_$DATE.tar.gz -C /opt/vaultwarden vw-data # 恢复容器运行 docker compose -f /opt/vaultwarden/docker-compose.yml start # 清理超过30天的备份 find $BACKUP_DIR -name vaultwarden_*.tar.gz -mtime 30 -delete把脚本存到/usr/local/bin/backup-vaultwarden.sh加执行权限然后加进 crontab0 3 * * * /usr/local/bin/backup-vaultwarden.sh /var/log/vaultwarden_backup.log 21每天凌晨三点自动执行备份。这样即使服务器断电、磁盘损坏最多丢一天的密码变更。这里我要强调一个细节尽量不要直接拷贝运行中的 SQLite 数据库文件。SQLite 在没有 WAL 模式时拷贝过程中可能遇到写入事务导致备份文件损坏。所以我上面脚本选择先stop容器再打包虽然会中断几秒服务但换来的是一份一致可靠的数据。凌晨三点中断几秒,几乎没有任何用户能感知到。5.3 模拟一次完整恢复备份只是手段能恢复才算真正安全。我建议你部署完成后做一个模拟恢复演练。操作流程是这样准备一台新机器装上 Docker创建/opt/vaultwarden目录把备份的压缩包解压进去确认数据目录结构齐全然后启动同样的 Docker Compose 配置。启动完成后浏览器访问地址并用账号登录确认所有密码条目都还在附件可以正常下载。这个演练不复杂半个小时就能走完但能暴露备份文件不完整、路径错误、证书配置遗漏等各种问题。别偷懒密码管理器这种服务恢复演练就是一次保险理赔的提前演习。6. 客户端接入与日常使用6.1 全平台客户端的兼容性Vaultwarden 最大的兼容性优势在于它可以直接使用官方发布的客户端。包括 Windows、macOS、Linux 桌面端iOS 和 Android 端以及 Chrome、Firefox、Edge 的浏览器扩展。这些客户端默认连接官方服务器但在登录界面都有一个“服务器地址”输入框把它改成你的 Vaultwarden 地址即可。这个兼容性意味着你不需要为 Vaultwarden 单独安装任何专用客户端也不用担心客户端更新后接口不兼容的问题。官方客户端是持续维护的Vaultwarden 社区也一直紧跟接口变化。6.2 浏览器扩展配置细节浏览器扩展是我个人使用频率最高的入口。安装官方扩展后点击扩展图标进入设置找到服务器地址字段把https://你的域名填进去保存后重新打开扩展页面就能看到登录界面。有个小细节容易踩坑服务器地址千万不要加路径。很多人习惯性填成https://你的域名/admin结果扩展一直提示服务器地址无效。正确填法就是域名根路径。填好地址登录一次后扩展会把密码库缓存在本地。之后每次浏览器启动扩展会自动向服务器同步一次。配合主密码或者指纹解锁日常使用体验和在线密码服务没有差别。6.3 值得特别注意的功能开关Vaultwarden 管理后台可以细调很多参数。我这里挑几个日常使用中影響最大的开关说明一下。首先是“注册开放”开关正式使用后必须保持关闭。如果家里人有新成员要加入管理后台临时打开注册注册完再关闭这个操作要熟练掌握。其次是两步验证登录。Vaultwarden 支持为账号开启 TOTP 验证开启后每次登录除了密码还需要输入验证码。这个功能一旦开启别人拿到主密码也进不了你的密码库。密码管理器的账号安全层级要比普通网站账号更高开启两步验证的优先级非常高。最后是紧急访问功能。如果你担心自己某天意外没法登录可以为信任的设备开启紧急访问设置一个等待期到期后联系人可以申请访问你的密码库。这个功能对家庭共享场景特别实用。7. 常见问题与排查技巧实录7.1 忘记管理员令牌怎么办ADMIN_TOKEN是进入管理后台的唯一凭证但很多时候配置完就忘了。遇到这种情况直接编辑服务器上的docker-compose.yml把ADMIN_TOKEN改成新生成的随机值然后重新创建容器docker compose up -d --force-recreate注意--force-recreate会基于新配置重建容器但数据目录里的数据不会丢失。改完令牌后旧的管理登录会话会失效重新登录即可。7.2 更新镜像后数据会不会丢不会。更新只涉及镜像层data volume 里的数据完全不触碰。标准更新流程是cd /opt/vaultwarden docker compose pull docker compose up -d执行前建议先做一次手工备份万一新版本有兼容问题可以立刻回滚到旧镜像。docker compose本身不会自动删掉旧镜像所以回滚也很简单docker compose up -d --no-deps vaultwarden:上一个版本号更新这件事最怕的是有人直接在未备份的情况下pull latest后启动结果遇到 bug 再想回退发现旧镜像已经被覆盖了。养成更新前备份的习惯能省去很多不必要的惊吓。7.3 客户端提示同步失败同步失败通常有两个原因。一是反向代理没配置 WebSocket 升级客户端无法维持长连接状态。检查 Nginx 或 Caddy 配置里有没有对应规则按前面的配置补上就好。二是服务器时间不正确TLS 握手会因证书时间校验失败而中断。排查思路是先看容器日志docker compose logs --tail50日志里如果出现WebSocket connection相关错误优先去检查代理层。如果是证书校验错误检查服务器系统时间和证书有效期。7.4 SMTP 始终发不出去开启 SMTP 后最常见的错误是SMTP_SECURITY设置不对。不同的邮件服务商支持的加密方式不同有的用 STARTTLS 在 587 端口有的用隐式 TLS 在 465 端口。Vaultwarden 里这三个参数要配套SMTP_PORT587时SMTP_SECURITY通常填starttlsSMTP_PORT465时SMTP_SECURITY填tls如果填反了会在日志里看到 SSL 握手失败之类的报错。另外注意有些服务商要求SMTP_HOST填域名而非 IP填错了也会导致认证失败。7.5 磁盘空间被图标缓存撑爆icon_cache目录会缓存所有登录网站用到的站点图标。如果密码库里收藏的网站很多图标数量会比较大。正常情况下这个目录能通过配置限制最大容量但如果你发现磁盘快满了最快的清理方式是删除icon_cache目录后重启容器。Vaultwarden 会自动重新生成图标缓存不会影响密码数据。我建议在管理后台开启图标缓存限制或者在容器创建时用 Docker 卷限制挂载目录大小。老设备磁盘本来就小这个细节值得留意。最后说点个人感受。Vaultwarden 跑起来以后给我的感觉就是安静地待在角落几乎不需要存在感。真正需要你操心的无非两件事定时备份以及更新镜像前先看一眼变更说明。如果你手头刚好有一台连图形界面都跑不动的旧电脑或者一块几百兆内存的小主机用它来干这件事可以说是物尽其用。一个下午的折腾换回来日后每一刻的密码自由这笔买卖很划算。