作者： Vaultwarden 1.37.4 双重身份验证配置指南
详解 Vaultwarden 1.37.4 中 TOTP、FIDO2、YubiKey 及 Duo 的配置方法。本文涵盖通过组织策略强制开启双步登录的步骤，以及在用户被锁定时安全恢复访问权限的实操方案，助你正确配置 VPS 环境下的安全策略。
Vaultwarden 1.37.4 中双重身份验证的涵盖范围
在 1.37.4 版本中，Vaultwarden 双重身份验证支持五种第二因素：身份验证器应用（TOTP，基于时间的一次性密码）、电子邮件验证码、FIDO2 WebAuthn 安全密钥、YubiKey OTP 以及 Duo。身份验证器应用无需任何服务器端设置。其余四种方式均要求服务器具备相应配置：可用的邮件服务、正确的 DOMAIN（需通过 HTTPS）、Yubico 凭据或 Duo 凭据。
1.37.4 版本的配置中没有强制所有用户开启第二因素的设置。强制执行需通过组织策略中的双步登录设置实现，Bitwarden 帮助页面将其称为“要求双步登录”（Require two-step login）。该策略仅涵盖组织成员。一旦启用，它还会撤销当前未配置第二因素的成员的访问权限。
本指南假设 Vaultwarden 已在 Docker Compose 下运行，且位于配置了有效证书的反向代理之后。如果尚未完成此步骤，请先参考 在 VPS 上安装 Vaultwarden，完成后再返回此处。下文中的所有设置均为环境变量。所有名称和默认值均源自 1.37.4 版本的 .env.template 及源代码。Vaultwarden Wiki 未按版本划分，且仅包含 WebAuthn 和 YubiKey 的相关页面，因此源代码是此处更可靠的参考来源。
在进行任何更改前锁定版本
截至 2026 年 10 月 28 日，最新的标记版本为 1.37.4，发布于 2026 年 10 月 5 日。其发行说明列出了七项安全公告，其中一项被评为高危，并建议所有用户尽快更新。请锁定该标签而非 latest，以确保你运行的行为与此处描述的一致。在复制标签前，请检查发布页面是否有更新的版本。
services:
vaultwarden:
image: vaultwarden/server:1.37.4
restart: unless-stopped
env_file: vaultwarden.env
volumes:
- ./vw-data:/data
# keep your existing ports, networks and proxy labels as they areenv_file 行可将 SMTP 密码和 Duo 客户端密钥等敏感信息排除在 compose 文件之外。在 docker-compose.yml 旁边创建 vaultwarden.env 并限制其权限，因为它将存储凭据：
touch vaultwarden.env
chmod 600 vaultwarden.env如果你的现有设置位于 environment: 下，请将新变量添加到该文件中。请统一存放位置，以免混淆生效的配置值。
1.37.4 版本中的七条升级说明有两条涉及双因素认证。Duo DUO_USE_IFRAME 设置已被移除，如果你的文件中仍包含该项，请将其删除。新增了用于恢复代码登录的电子邮件模板 email/recover_twofactor。请先按照 备份与恢复 Vaultwarden 中的说明复制一份 /data，因为没有备份的回滚操作存在风险。
应用更改并检查容器是否恢复运行
在执行以下各节的更改后，请运行这些命令。docker compose config 会打印填充环境变量后的最终文件，以便在重启前发现拼写错误。up -d 会因环境变量变更而重新创建容器。
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail 50 vaultwardendocker compose ps 应显示 vaultwarden 服务正在运行。Vaultwarden 在启动时会检查配置，某些错误的 2FA 设置组合会导致其无法启动。如果服务持续重启，请先阅读日志。以下各节提供了针对这些情况的 1.37.4 版本错误文本。
身份验证器应用 (TOTP)：无需配置
TOTP 开箱即用。用户只需使用 Aegis 或 2FAS 等身份验证器应用扫描网页保管库中的二维码即可。
TOTP 验证码由共享密钥和当前时间按 30 秒步长计算得出。这意味着服务器时钟至关重要。Docker 容器使用宿主机时钟，因此请检查宿主机：
timedatectl正常的宿主机应显示 System clock synchronized: yes。如果显示 no，则所有验证码都会因时间偏差而被判定为无效。
默认情况下，Vaultwarden 也会接受上一个和下一个 30 秒步长的验证码，以容忍手机与服务器之间微小的时间差异。该功能的开关为 AUTHENTICATOR_DISABLE_TIME_DRIFT，默认值为 false。将其设置为 true 将使上一个和下一个步长的验证码失效。除非有特殊理由，否则请保持默认设置，否则手机时间若有几秒偏差，在每个步长的临界点都会导致验证失败。
电子邮件验证码需要可用的 SMTP
当配置了邮件服务后，电子邮件双重登录功能会自动开启。在 1.37.4 版本源码中，只要启用了 SMTP 且设置了 SMTP_HOST 或 USE_SENDMAIL，该功能即被激活。模板说明指出，需要 SMTP_FROM 配合上述两者之一才能启用邮件服务。
SMTP_HOST=smtp.example.com
SMTP_FROM=vaultwarden@example.com
SMTP_FROM_NAME=Vaultwarden
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USERNAME=vaultwarden@example.com
SMTP_PASSWORD=your-smtp-passwordSMTP_SECURITY 的默认值为 starttls，默认端口为 587。force_tls 模式默认使用 465 端口。如果设置了 SMTP_USERNAME，则必须配置 SMTP_PASSWORD。
在 1.37.4 版本中，电子邮件验证码的默认设置为 6 位数字（EMAIL_TOKEN_SIZE），有效期为 600 秒（EMAIL_EXPIRATION_TIME），允许尝试 3 次，超过次数后令牌将重置并需要重新发送邮件（EMAIL_ATTEMPTS_LIMIT）。请保持长度为 6 位。模板提示，无论此项设置如何，客户端均默认按 6 位数字处理。
有两个可选设置将电子邮件验证码与注册流程关联，两者默认均为 false。模板将 EMAIL_2FA_ENFORCE_ON_VERIFIED_INVITE 描述为“无论组织策略如何，均在注册时设置电子邮件双重验证”。它将 EMAIL_2FA_AUTO_FALLBACK 描述为“在需要时自动将电子邮件双重验证设置为备用提供程序”。这两项均依赖于电子邮件双重验证，若该功能关闭，1.37.4 版本将拒绝这些设置。
在五种验证因子中，电子邮件的安全性最低。发送到邮箱的验证码，其安全性取决于该邮箱的密码强度。建议将其作为备用方案，并引导用户优先使用身份验证器应用或安全密钥。
FIDO2 WebAuthn 需要 HTTPS 和匹配的域名
安全密钥与站点地址绑定。FIDO2 WebAuthn 的维基页面指出，Vaultwarden 必须通过 HTTPS 提供服务并使用有效的证书。它还要求必须将 DOMAIN 设置为您访问 Vaultwarden 时使用的相同地址，包括 https://，如果端口不是 443，还需包含端口号。
DOMAIN=https://vw.example.com该模板提供了另外两种有效的格式：带有端口的 https://vw.domain.tld:8443，以及带有路径的 https://domain.tld/vw。它还警告称，如果 DOMAIN 与用户打开的地址不匹配，不仅会破坏安全密钥功能，附件下载和电子邮件中的链接也可能失效。
常见的错误是使用第二个主机名。DOMAIN 设置为 https://vw.example.com，但有些人会通过 https://vault.example.com 访问，因为代理对两者都有响应。该第二个名称与 DOMAIN 不匹配，因此安全密钥无法在该地址下工作。请选择一个名称，将其设置在 DOMAIN 中，并在代理层将另一个名称重定向到该地址。关于更广泛的 HTTPS 和代理设置，请参阅 自托管 Vaultwarden 的安全性分析。
YubiKey OTP 需要 Yubico API 凭据
YubiKey OTP 是一种通过触摸密钥输入长效一次性验证码的模式。它独立于 FIDO2，许多 YubiKey 同时支持这两种模式。OTP 需要从 Yubico 获取客户端 ID 和密钥：
YUBICO_CLIENT_ID=11111
YUBICO_SECRET_KEY=AAAAAAAAAAAAAAAAAAAAAAAA上述内容为模板占位符，并非实际可用的值。YUBICO_SERVER 为可选配置。若不设置，Vaultwarden 将使用默认的 YubiCloud 服务器。请同时设置这两个值，或均不设置。若仅设置其中一个且启用了 Yubico 支持，1.37.4 版本将拒绝启动，并报错提示必须同时设置 YUBICO_CLIENT_ID 和 YUBICO_SECRET_KEY 才能支持 YubiKey OTP。
如果所有用户均可注册 FIDO2 密钥，则可能完全无需使用 OTP。FIDO2 无需第三方凭据，这意味着服务器上可以减少一个密钥存储。
Duo 需要来自 Duo 管理面板的三个值
全实例 Duo（模板中称为“全局 Duo 支持”）需要这三个值。它们来自您在 Duo 管理面板中创建的应用程序。请按照 Duo 的官方文档完成该部分的配置。
DUO_IKEY=<Client ID>
DUO_SKEY=<Client Secret>
DUO_HOST=<API Hostname>如果启用了全局 Duo 支持，但三个值中仅设置了部分，配置校验将失败并报错 All Duo options need to be set for global Duo support。将这三个值全部留空是有效的；此时用户需自行配置其 Duo 凭据。请记住 1.37.4 版本的升级说明：DUO_USE_IFRAME 已不再存在，因此请将其删除，不要从旧配置文件中迁移该项。
能否强制所有 Vaultwarden 用户使用 2FA？
服务器设置无法实现此功能。1.37.4 版本的 config.rs 和 .env.template 不包含要求使用第二验证因素的全局开关。最接近的选项是 EMAIL_2FA_ENFORCE_ON_VERIFIED_INVITE，它仅用于设置电子邮件验证码。这是 1.37.4 版本的现状，因此在假设该情况依然存在前，请查阅后续版本的发布说明。
有两个设置容易被误认为是强制执行。DISABLE_2FA_REMEMBER=true 会强制已启用第二验证因素的用户在每次登录时进行验证。“记住我”复选框虽然可见，但会被忽略。对于未设置第二验证因素的用户，此设置无效。SIGNUPS_ALLOWED 默认为 true，新账户在注册时除非自动设置了电子邮件 2FA，否则不会启用第二验证因素。因此，开放注册的公共实例会不断创建不受任何策略约束的账户。
强制执行是针对两步登录的组织策略。它仅适用于启用该策略的组织成员。不属于任何组织的个人账户不受此约束。如果希望覆盖所有用户，则每个用户都必须加入启用了该策略的组织。
启用策略后，未开启 2FA 的成员会发生什么
这是最容易让人感到意外的部分，请在保存策略前仔细阅读。在 1.37.4 版本中，一旦保存并启用两步登录策略，强制执行将立即生效。所有未开启第二验证因素且权限低于管理员（Admin）的已确认成员，其访问权限都将被撤销。在 Vaultwarden 的角色层级中，这意味着经理（Manager）和用户（User）角色都会受到影响。所有者（Owner）和管理员（Admin）则会被跳过。如果已配置邮件服务，每位被撤销权限的成员都会收到一封电子邮件。如果强制执行过程中出现错误，策略将不会被保存。
Bitwarden 的文档描述了相同的效果：非所有者或管理员的成员访问权限会被撤销，他们会收到邮件通知，且必须在合规后才能恢复访问权限。“已撤销”（Revoked）是一种成员状态。成员不会被从组织中移除，但会失去对组织内项目的访问权限。
策略启用后将持续生效。只要策略处于开启状态，任何未开启第二验证因素且权限低于管理员的成员，都无法被确认、恢复或更改成员身份，除非通过 EMAIL_2FA_AUTO_FALLBACK=true 成功为其已验证的电子邮箱激活邮件 2FA。1.37.4 版本中的错误遵循 Cannot <action> because 2FA is required (membership <id>) 模式。如果成员之后移除了最后一个第二验证因素，强制执行将再次触发，其访问权限会被再次撤销。
请按以下顺序执行部署：
- 确保所有者和管理员已开启第二验证因素，因为策略不会对其进行检查。
- 告知成员截止日期，以及服务器支持的验证方式。
- 给成员留出注册时间，然后再开启策略。
- 成员完成注册后，恢复其被撤销的权限。系统会阻止恢复权限低于管理员且仍未开启第二验证因素的成员，除非通过自动邮件回退机制成功激活了验证。
恢复代码：使用后的实际效果
每位开启两步登录的用户都拥有一个恢复代码。只有在用户再次输入主密码后，Web 保险库才会显示该代码。请告知用户将其抄写或打印出来，并存放在保险库之外。如果恢复代码存储在它所解锁的保险库内，则毫无用处。
在登录时使用该代码，其作用远不止于允许登录。在 1.37.4 版本中，它会移除该用户的所有第二重验证因素，清除所有“记住此设备”的令牌，重新运行组织策略检查，记录相关事件，并清除已存储的恢复代码。输入代码时的空格和字母大小写不影响结果，因为系统在比对前会去除空格并将其转换为小写。
这会产生两个后果。首先，用户在恢复后既没有第二重验证因素，也没有恢复代码，因此必须重新注册以获取新代码。其次，如果用户所属的组织启用了相关策略且其权限低于管理员，策略检查会撤销其访问权限，直到用户重新注册并被恢复为止。
如果已配置邮件服务，1.37.4 版本还会向用户发送邮件。邮件模板的主题为 Two-Step Login Recovered From <ip>，正文说明账户的两步登录功能已通过使用账户恢复代码被禁用。如果用户收到该邮件但并未本人使用代码，应立即更改主密码。邮件发送失败仅会被记录，登录操作仍会继续完成。
管理员如何移除被锁定用户的双重身份验证 (2FA)
如果用户丢失了手机且没有恢复代码，管理员仍可提供协助。1.37.4 版本的管理页面提供了一个“移除所有 2FA”按钮，该按钮仅在启用了两步登录的用户账户下显示。此操作会删除该用户的所有第二身份验证因子，清除其“记住设备”的令牌，运行组织策略检查，并清除其恢复代码。
除非 DISABLE_ADMIN_TOKEN=true 绕过了内置身份验证，否则管理页面需要 ADMIN_TOKEN。如果两者均未设置，管理面板将被禁用。模板建议使用 Argon2 PHC 字符串而非明文令牌，Vaultwarden 安全指南 涵盖了如何保护该页面。
在点击该按钮之前，请通过攻击者无法控制的渠道确认对方身份。仅凭一封邮件就移除某人的第二身份验证因子，正是双重身份验证旨在防范的攻击方式。
点击按钮后，系统将应用与使用恢复代码时相同的策略规则。如果组织启用了相关策略，经理或用户可能会被立即撤销权限。请让用户在移除后立即注册新的身份验证因子，然后恢复其成员资格。
管理员移除操作仅用于解决丢失第二身份验证因子的问题。它不会让其他人获得保险库的访问权限。如果您希望受信任的人员能够在紧急情况下访问某人的保险库，请使用另一项功能：Vaultwarden 紧急访问。
可选：针对未完成第二步验证的登录发送警报
INCOMPLETE_2FA_TIME_LIMIT 默认值为 3 分钟。如果登录通过了主密码验证，但在该时间内未完成第二步验证，Vaultwarden 会向用户发送电子邮件。如果用户并未尝试登录，则说明他人已获知其主密码。将其设置为 0 可关闭此功能。INCOMPLETE_2FA_SCHEDULE 默认每分钟执行一次检查。这两项功能均需配置可用的邮件服务才能生效。
为何更改双重身份验证（2FA）会导致登录失败及其原因分析
添加 YubiKey 或 Duo 后容器陷入重启循环。 缺少某个必需组的值。运行 docker compose logs --tail 50 vaultwarden 并查找上述 Yubico 或 Duo 错误。docker compose config 可显示实际到达容器的值。
安全密钥注册在某个主机名上失败，但在另一个主机名上正常。 DOMAIN 与浏览器中的地址不匹配。请修复主机名，或在代理层将第二个域名重定向到第一个域名。
无法收到电子邮件验证码。 邮件传输服务未正常工作。在请求验证码后，检查日志中的 SMTP 错误。随后根据端口检查 SMTP_SECURITY：使用 587 端口时检查 starttls，使用 465 端口时检查 force_tls。
所有 TOTP 验证码均被拒绝。 主机时钟不准确，或 AUTHENTICATOR_DISABLE_TIME_DRIFT=true 移除了容差设置。timedatectl 可用于排查时钟问题。
成员突然失去对共享项目的访问权限。 两步登录策略在启用时或成员移除最后一个辅助验证方式时撤销了其权限。成员重新注册验证方式后，即可恢复其成员资格。
FAQ
我可以在 Vaultwarden 中强制所有用户使用双重身份验证吗？
在 1.37.4 版本中，无法通过服务器设置实现。其配置中没有全局开关。强制执行需通过组织策略中的两步登录设置，且仅涵盖该组织的成员。该策略不会检查所有者和管理员，因此请确保他们手动完成注册。
开启两步登录策略后，现有成员会怎样？
在 Vaultwarden 1.37.4 中，策略保存的瞬间，所有未配置第二因素且级别低于管理员的已确认成员将被撤销权限。如果配置了邮件服务，系统会向他们发送邮件。他们仍保留在组织内，但无法访问组织内的项目。在他们注册第二因素后，其成员资格可被恢复。
为什么在我的 Vaultwarden 服务器上注册安全密钥会失败？
FIDO2 WebAuthn 需要使用有效证书的 HTTPS 连接。DOMAIN 必须与用户访问的实际地址完全一致，包括 https:// 以及除 443 以外的任何端口。如果用户通过第二个主机名访问保险库，安全密钥将无法使用。请仅使用一个主机名，并将其他主机名重定向至该地址。
使用 Vaultwarden 恢复代码时会发生什么？
它会移除账户上的所有第二因素并清除已记住的设备。该代码使用后即失效，因此必须重新开启两步登录以获取新代码。如果配置了邮件服务，1.37.4 版本会向用户发送相关邮件。如果你所在的组织启用了两步登录策略且你的级别低于管理员，在重新注册之前，你的权限将被撤销。
Vaultwarden 管理员可以重置用户的 2FA 吗？
可以。在设置了 ADMIN_TOKEN 的情况下，1.37.4 版本的管理页面会为已启用两步登录的用户显示“移除所有 2FA”按钮。它会删除用户的所有第二因素及其恢复代码。请务必先核实用户身份，并要求其立即重新注册，因为组织策略可能会在重置后立即撤销其权限。