本指南详细介绍了如何在私有环境下部署和配置 Vaultwarden，包括开启并安全访问管理界面、配置 Gmail SMTP 邮箱实现邀请与通知功能、常见排错方法，以及如何新建组织和实现密码条目的共享。通过实际操作与截图讲解，帮助你高效搭建并管理适合家庭和小团队的密码服务系统。

使用Vaultwarden的高级特性需要开启管理界面来设置。Vaultwarden的部署请参考 Docker部署Vaultwarden 。

一、访问与配置管理后台

假设Vaultwarden的访问地址是https://example.com，管理界面在访问地址后加/admin。输入Admin_Token来访问管理界面。

1.1 生成Admin_Token

现在依然可以使用明文的密码来访问管理界面，但是Vaultwarden建议使用加密的密码来访问。可以参考官方文档secure the admin token。其中vaultwarden是你容器的名字，输入设置的密码，至少8位，确认密码。最后生成admin token，将其放入到环境变量之中。

bash
docker exec -it vaultwarden /vaultwarden hash
Generate an Argon2id PHC string using the 'bitwarden' preset:

Password: 
Confirm Password: 

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$LNuRR3K0232FW68U36aFCNsLGB5dmn079GJLFI1M088$NGkD4RrnStvRidXfI71sb7sglCU/ov0oCgpyhWsXyJo'

Generation of the Argon2id PHC string took: 182.049239ms

Vaultwarden推荐的方法不会让Admin Token暴露在Docker Compose的环境变量里，密码还是自己设置的密码，但是环境变量使用的是密码的哈希。

1.2 管理后台访问排查

但是我也遇到了一些问题，就是无法通过这个新的密码来访问管理界面。这是因为第一次安装Vaultwarden之后，会在容器内生成配置文件，路径是/data/config.json。最开始设置的环境变量会被写到这个文件里。只要不删除数据持久卷，每次启动或是重新生成容器都会加载这个配置文件。这个配置文件的优先级比Docker Compose里环境变量的优先级要高。

在这个配置文件内修改参数，然后重启容器重新加载配置，就可以访问后台的管理界面了。除了这个Admin Token外，这个配置文件还包含其他的配置。当我们进入到管理界面后，在管理界面进行的修改并保存后是会写到这个配置文件里的。

二、配置邮箱实现邀请与通知

正常我们私有部署的Vaultwarden是给自己或是家人朋友用，并不希望任何人都可以注册和使用。所以一般在注册完自己的管理员账号后，都关闭注册功能。但是如果你希望家人和朋友使用的时候，不可能每次都去管理界面设置。这时候我们可以使用邮件邀请的方式来添加新的用户，这就是需要用到一个邮箱来发送这些邀请邮件。此外，其他的一些功能，譬如重置密码都需要用到邮箱。虽然自己可以搭一个邮箱的服务器，但是并没有太大的必要，除非用户非常多，而且你还有其他的应用也会频繁地用到邮箱服务。所以本着多一事不如少一事的风格，我们就利用已有的邮箱地址。

我们这里只进行邮件的发送而不需要接收邮件，所以只需要设置SMTP。这里我使用我的Gmail来进行设置。

2.1 管理后台设置 SMTP

首先使用设置的密文密码来登录管理界面。

在设置里找到SMTP。

点开SMTP设置，你需要准备你的Gmail账号和App Password。

这个App Password是给生成的给应用使用的，一般情况下你的谷歌账号都会开启二次认证。而这个App Password则可以直接用于应用访问你的谷歌邮箱。所以谷歌也是不推荐使用这个App Password的。如果是我们自己写的应用，需要调用谷歌邮箱的API，则需要注册你的应用并生成密钥，这里略过不提。如果你在这里使用了你的邮箱登陆密码，则会出现BadCredential的报错。

2.2 生成 Gmail App Password

点击Create and manage your app passwords 链接。

设置APP的名字，再点击生成就出现了16位的APP Password。

再返回刚才的链接，你也可以选择删除这个APP Password。

2.3 测试邮件发送

在SMTP设置的页面上，最后有一个Test SMTP的选项，填入你的其他的邮箱地址，再点击发送。发送成功的通知如下。如果失败则会有相应的报错信息，再进行排错。

在测试邮箱里会收到如下一封邮件。

2.4 查看容器日志排错

有任何报错都在日志里显示出来，成功就会返回200 OK的状态。

bash
[2025-08-12 06:59:13.534][request][INFO] POST /admin/test/smtp

[2025-08-12 06:59:15.588][vaultwarden::mail][ERROR] SMTP 5xx error: permanent error (535): 5.7.8 Username and Password not accepted. For more information, go to5.7.8  https://support.google.com/mail/?p=BadCredentials d9443c01a7336-241e899a51esm293151375ad.115 - gsmtp - Authentication credentials invalid

[2025-08-12 06:59:15.589][response][INFO] (test_smtp) POST /admin/test/smtp application/json => 400 Bad Request

省略......

[2025-08-12 07:01:19.174][request][INFO] POST /admin/test/smtp

[2025-08-12 07:01:23.312][response][INFO] (test_smtp) POST /admin/test/smtp application/json => 200 OK

2.5 防火墙放行 SMTP 端口

在配置中我们使用的是587接口，所以我们需要在防火墙里放行587接口。我使用的是腾讯云的轻量服务器，在控制台里选择防火墙，新建规则，然后放行587号端口。

因为我的Vaultwarden是在Nginx后面，我还曾想是否会影响到Vaultwarden的邮箱发送，因为Nginx只监听80和443端口。后来证明它属实不影响邮件的发送功能，因为Nginx只处理HTTP或是HTTPS的流量。

2.6 容器网络排查

但是我也踩雷的地方是，我Vaultwarden使用一个内部容器网络连接到Nginx，而只有Nginx可以有互联网的访问权限。所以，当其他配置都设置好之后，依然是无法发送邮件，但是报错的原因是无法解析Gmail的SMTP服务器地址。而容器默认使用主机服务器的DNS服务器，通常都是云服务商的内网DNS服务器。所以问题不在DNS服务器上，作为一个临时的解决方案，我把Vaultwarden的容器又加入到一个有互联网访问权限的容器网络中，然后问题迎刃而解。