Vaultwarden：Rust 版 Bitwarden 密码库｜自托管部署与使用全指南

密码交给云端 SaaS，总有人不放心。Bitwarden 官方服务端功能完整，但整套跑起来要 PostgreSQL、SQL Server、多个 .NET 服务，一台 2G 内存的小机器基本吃不下。Vaultwarden 就是为这个场景生的：单二进制、Rust 编写、默认 SQLite，一个容器就能顶起整套 Bitwarden 客户端 API。

一、项目介绍

Vaultwarden 的前身是 bitwarden_rs，用 Rust 重写了 Bitwarden 的服务端实现，目标是「在资源有限的机器上跑一个兼容官方客户端的密码库服务」。官方 README 的原话是：an alternative server implementation of the Bitwarden Client API, written in Rust and compatible with official Bitwarden clients。

这意味着你不需要换客户端。手机上的 Bitwarden App、浏览器扩展、桌面端、CLI，全部照常连接，只是服务器地址从 bitwarden.com 换成你自己的域名。

截至本文写作时，仓库有 7 万+ star，主分支最近一次提交在 2026 年 11 月 1 日，仍在高频维护。

二、功能拆解

官方 README 列出的能力清单，可以直接对照着勾：

• 个人保险库（Personal Vault）：登录、条目、文件夹、密码历史，是最基础的一层
• Send：临时分享文本或文件，可设访问次数和过期时间，类似「阅后即焚」
• 附件（Attachments）：条目可以挂文件
• 网站图标（Website icons）：自动抓取站点 favicon，条目列表更好认
• 个人 API Key：给 CLI、自动化脚本用
• 组织（Organizations）：集合（Collections）、密码共享、成员角色、用户组、事件日志、管理员重置密码、目录同步（Directory Connector）、策略（Policies），这一块基本对标团队版
• 多因素认证：验证器 App、邮箱、FIDO2 WebAuthn、YubiKey、Duo 五种
• Emergency Access：紧急联系人，可在你失联后申请接管保险库
• 管理后台（Admin Backend）：/admin 路径下的用户管理、邀请、诊断
• 改造版 Web Vault：容器内已经打包了 bw_web_builds，开箱即用，不用另外部署前端

一句话概括取舍：企业级功能它都有，但省掉了官方服务端那套分布式架构。代价是不支持 Bitwarden 自家的某些云服务集成（比如部分企业 SSO 的高级玩法），换来的是极低的部署成本。

三、官方链接

• GitHub 仓库：https://github.com/dani-garcia/vaultwarden
• 官方 Wiki（配置项最全的文档）：https://github.com/dani-garcia/vaultwarden/wiki
• 容器镜像：vaultwarden/server（Docker Hub / ghcr.io / quay.io 三处同源）
• 反代示例：https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples
• 社区讨论：GitHub Discussions、Matrix 房间 #vaultwarden:matrix.org、Discourse 论坛

注意：官方 README 特别声明——遇到 bug 请反馈给 Vaultwarden，不要走 Bitwarden 官方支持渠道。

四、环境要求

官方推荐用容器镜像部署，这是最省事也最不容易踩坑的路径。

关于 HTTPS，官方 README 用了一段 IMPORTANT 强调：Web Vault 依赖 Web Crypto API，而这个 API 只在安全上下文（HTTPS）下可用。不配 HTTPS，网页版直接打不开，客户端也无法正常登录。官方同时建议在前面挂一层反向代理，而不是让 Vaultwarden 自己处理证书。

所以部署分两步：先起服务，再配反代。下文两条路都会走。

五、部署步骤

方式一：Docker CLI（官方最简路径）

官方给的命令就三行，逐字照抄即可：

docker pull vaultwarden/server:latest

docker run --detach --name vaultwarden \
  --env DOMAIN="https://vw.domain.tld" \
  --volume /vw-data/:/data/ \
  --restart unless-stopped \
  --publish 127.0.0.1:8000:80 \
  vaultwarden/server:latest

三个参数需要按实际情况改：

• DOMAIN 换成你的真实域名，必须带 https://，末尾不要加斜杠；这个值会写进出邮件和 WebAuthn 配置
• /vw-data/ 是宿主机上的持久化目录，官方说明「所有持久数据都保存在这里」，建议换成你习惯的路径，比如 /opt/vaultwarden/data/
• 127.0.0.1:8000:80 表示只监听本机，外部访问统一走反向代理，这样 80 端口不会暴露在公网

执行完 docker ps 看到容器 Up 即可。

方式二：Docker Compose（推荐，便于后续维护）

新建目录并写入 compose.yaml：

mkdir -p /opt/vaultwarden && cd /opt/vaultwarden

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vw.domain.tld"
    volumes:
      - ./vw-data/:/data/
    ports:
      - 127.0.0.1:8000:80

docker compose up -d
docker compose logs -f

这份 compose 与官方 README 完全一致，只把卷路径从绝对路径换成了相对目录 ./vw-data/，方便整目录搬迁。

第三步：配置反向代理

官方只给了反代示例的 Wiki 链接，没有在 README 里绑定某一种方案。这里用 Caddy，因为它申请证书是全自动的：

# Debian/Ubuntu
apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install -y caddy

编辑 /etc/caddy/Caddyfile：

vw.domain.tld {
    reverse_proxy 127.0.0.1:8000
}

systemctl reload caddy

Caddy 会自动申请 Let's Encrypt 证书。域名解析要先指向这台机器的公网 IP，80 和 443 都要放行。

如果你已经有 Nginx，等效配置是这样（注意 X-Real-IP 和 X-Forwarded-For 必须传，否则管理后台看不到真实 IP）：

server {
    listen 443 ssl http2;
    server_name vw.domain.tld;

    ssl_certificate     /etc/letsencrypt/live/vw.domain.tld/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vw.domain.tld/privkey.pem;

    client_max_body_size 525M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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:8000;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

client_max_body_size 必须放开，否则上传附件会 413。WebSocket 那一段是给实时同步用的。

六、配置参数详解

Vaultwarden 的环境变量全部可以直接写在 compose 的 environment 下，也可以用 .env 文件。下面是最常用的一批，完整列表在官方 Wiki 的 Configuration 页。

基础

注册与安全

邮件（找回密码、邀请、二次验证都靠它）

一个可直接抄的完整示例：

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vw.domain.tld"
      SIGNUPS_ALLOWED: "false"
      INVITATIONS_ALLOWED: "true"
      ADMIN_TOKEN: "把 openssl rand -base64 48 的结果贴这里"
      SHOW_PASSWORD_HINT: "false"
      SMTP_HOST: "smtp.example.com"
      SMTP_FROM: "vault@domain.tld"
      SMTP_FROM_NAME: "Vaultwarden"
      SMTP_PORT: "465"
      SMTP_SECURITY: "force_tls"
      SMTP_USERNAME: "vault@domain.tld"
      SMTP_PASSWORD: "邮箱密码或授权码"
    volumes:
      - ./vw-data/:/data/
    ports:
      - 127.0.0.1:8000:80

改完执行 docker compose up -d 让配置生效。

七、启动与运维

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

# 查看日志（排查问题第一现场）
docker compose logs -f --tail=100

# 查看容器资源占用
docker stats vaultwarden

# 确认端口监听
ss -tlnp | grep 8000

日常维护建议：

• 备份：核心就是 vw-data/ 这个目录，里面是 SQLite 数据库和附件。停容器后打包最稳：docker compose stop && tar czf vw-$(date +%F).tar.gz vw-data/ && docker compose start
• 定时任务：docker compose exec vaultwarden /vaultwarden backup 可以在线备份一次，官方镜像内置了这个命令
• 日志切割：compose 的 logs 默认无限增长，生产环境建议在 compose 里加 logging: driver: json-file, options: max-size: 10m, max-file: 3

八、实操验证

部署完成后，按这个顺序验证，能快速定位是哪一层出了问题。

1. 容器是否活着

docker ps --filter name=vaultwarden

状态应为 Up (healthy) 或 Up。

2. 本机直连是否通

curl -I http://127.0.0.1:8000

预期返回 HTTP/1.1 200 OK，并带 content-type: text/html。

3. 域名 + HTTPS 是否通

curl -I https://vw.domain.tld

证书要有效（SSL certificate verify ok）。如果这一步失败但第 2 步成功，问题一定在反代或 DNS。

4. 管理后台是否可进

先设置 ADMIN_TOKEN 并重启，然后访问 https://vw.domain.tld/admin，输入 token 应该能看到用户列表页。

5. 网页版能否注册/登录

打开 https://vw.domain.tld，如果 SIGNUPS_ALLOWED=true，点「创建账户」，填邮箱和主密码。注册成功后应该能直接进入保险库界面。

6. 客户端能否连上

手机装 Bitwarden App → 登录页左上角齿轮 → 「自托管环境」→ 服务器 URL 填 https://vw.domain.tld → 保存后登录。能同步到刚才在网页建的条目，就算整条链路通了。

九、故障排查

网页版白屏 / 一直转圈

九成是 HTTPS 没配对。Web Crypto API 在 HTTP 下不可用，浏览器控制台会报 crypto.subtle is undefined。确认 DOMAIN 带 https://，并且你确实是走 https 访问的。

上传附件报 413

反代的请求体限制太小。Nginx 加 client_max_body_size 525M;，Caddy 默认无限制但如果你在前面又套了一层 CDN，要去 CDN 侧调。

登录后提示「无法连接服务器」/ 一直同步失败

先看容器日志有没有 WebSocket 报错。反代必须放行 /notifications/hub 的 Upgrade 头，否则实时同步不通。上面的 Nginx 配置已经包含这段。

管理后台 404 或提示未启用

ADMIN_TOKEN 没设或设成了空字符串。注意：token 太短也会被拒绝，官方建议至少 48 字符随机串。

邮件发不出去

按顺序查：SMTP_PORT 和 SMTP_SECURITY 是否匹配（465 配 force_tls，587 配 starttls）；云厂商是否封了 25 端口（阿里云、腾讯云默认封禁，需工单申请）；发件域名是否配了 SPF/DKIM。

忘记主密码怎么办

Vaultwarden 本身不存你的主密码，无法帮你找回。如果开了 Emergency Access 且联系人接受邀请，可以由对方发起接管；否则只能管理员在 /admin 里删除该用户重新注册，历史数据不可恢复。这也是为什么主密码一定要单独保管。

数据目录权限报错

容器内以非 root 用户运行，宿主机挂载目录要给对属主：

chown -R 1000:1000 /opt/vaultwarden/vw-data

十、升级、回滚与卸载

升级

官方镜像用 latest 标签，升级就两条命令：

cd /opt/vaultwarden
docker compose pull
docker compose up -d

升级前务必备份 vw-data/。Vaultwarden 的数据库迁移是单向的，跨大版本降级可能读不了旧库。

回滚

latest 没版本号，回滚要指定具体 tag。先看当前版本：

docker compose exec vaultwarden /vaultwarden --version

然后在 compose 里把镜像固定成旧版本，例如 vaultwarden/server:1.32.7，再 docker compose up -d。同时把升级前的 vw-data/ 备份解压覆盖回去。

卸载

cd /opt/vaultwarden
docker compose down
docker rmi vaultwarden/server:latest
rm -rf /opt/vaultwarden

down 默认不删数据卷，vw-data/ 还在。确认数据不再需要后再手动删目录。

十一、商用许可

Vaultwarden 使用 AGPL-3.0 许可证。

要点：

• 可以商用，包括在公司内部部署给员工用，不需要付费，也不需要授权
• 可以修改，但如果把修改版作为网络服务对外提供，必须公开修改后的源码（AGPL 的传染性条款，这是它和 GPL 最主要的区别）
• 可以分发，分发时必须附带许可证和源码
• 不提供任何担保

如果你只是「自己部署一套给团队用」，不修改源码、不对外提供 SaaS 服务，那 AGPL 对你的日常使用没有任何额外约束。

另外提醒一句：Vaultwarden 是 Bitwarden 的非官方实现，官方 README 里明确标注了 disclaimer。它兼容 Bitwarden 客户端 API，但与 Bitwarden 公司无隶属关系，商业采购时如需官方支持合同，还是要走 Bitwarden 官方渠道。