# 3.SMTP 配置 {% hint style="success" %} 对应的[官方页面地址](https://github.com/dani-garcia/vaultwarden/wiki/SMTP-Configuration) {% endhint %} {% hint style="danger" %} **注意**：v1.25.0 版本之前的 Vaultwarden 有一个关于 SSL 和 TLS 的漏洞/误导性的配置设置项。这已在测试版和新发布的版本中得到修复。 旧设置项是 `SMTP_SSL` 和 `SMTP_EXPLICIT_TLS`。 新设置项是 `SMTP_SECURITY`，它具有以下可用选项：`starttls`、`force_tls` 以及 `off`。 * `SMTP_SECURITY=starttls` 等同于 `SMTP_SSL=true` * `SMTP_SECURITY=force_tls` 等同于 `SMTP_EXPLICIT_TLS=true` {% endhint %} {% hint style="info" %} 若您选择不配置 SMTP，当您通过网页密码库、浏览器扩展和移动 App 以外的方式（如 Bitwarden CLI）登录时，Vaultwarden 可能无法发送验证电子邮件，并可能拒绝验证请求。要规避此行为，请在您的账户中设置双重验证。请参阅： {% endhint %} *** 您可以配置 Vaultwarden 通过 SMTP 代理来发送电子邮件： ```shell docker run -d --name vaultwarden \ -e SMTP_HOST=smtp.domain.tld \ -e SMTP_FROM=vaultwarden@domain.tld \ -e SMTP_PORT=587 \ -e SMTP_SECURITY=starttls \ -e SMTP_USERNAME=myusername \ -e SMTP_PASSWORD=MyPassw0rd \ -v /vw-data/:/data/ \ -p 80:80 \ vaultwarden/server:latest ``` 从 v1.25.0 开始，用于 SMTP SSL/TLS 配置的环境变量已更新为 `SMTP_SECURITY`（之前的有误导性，参阅[错误 #851](https://github.com/dani-garcia/vaultwarden/issues/851)）。当 `SMTP_SECURIT` 设置为 `starttls` 时（这是默认值），将仅接受 TLSv1.1 和 TLSv1.2 协议，并且 `SMTP_PORT` 默认为`587`。如果设置为 `off`，`SMTP_PORT` 则默认设置为 `25` 并将尝试加密（2020 年 3 月 12 日之前的代码不会尝试加密）。这是非常不安全的，仅在您知道您在做什么时才使用此设置。要以隐式模式（强制 TLS）运行 SMTP，请将 `SMTP_SECURITY` 设置为 `force_tls`。如果您不登录也可以发送电子邮件，简单地将 `SMTP_USERNAME` 和 `SMTP_PASSWORD` 设置为空即可。 请注意，如果启用了 SMTP 和邀请，邀请将通过电子邮件发送给新用户。您必须使用 Vaultwarden 实例的基础 URL 来设置 `DOMAIN` 配置项，以生成正确的邀请链接： ```shell docker run -d --name vaultwarden \ ... -e DOMAIN=https://vault.example.com \ ... ``` 用户邀请链接有效期为 5 天，过期后需要重新发送邀请。 ## SMTP 服务器 正确配置 SMTP 服务器/中继并不是一件容易的事。Vaultwarden 使用的邮件程序库也不是最容易排除故障的。所以，除非您特别有兴趣自己设置，否则使用外部服务可能会更简单。 这里有几个对于大部分使用场景来说已经足够的免费服务： * [~~SendGrid~~](https://sendgrid.com)~~（每天 100 封电子邮件）~~ * [MailJet](https://www.mailjet.com)（每天 200 封电子邮件） * [SendinBlue](https://www.sendinblue.com/)（每天 200 封电子邮件） * [SMTP2GO](https://www.smtp2go.com/)（每月 1000 封电子邮件） ## 一些知名服务的默认设置 ### 通用 邮件服务器侦听端口 25 主要只是为了接受来自其他邮件服务器的邮件，并且仅用于它们是最终位置的邮件。此外，许多互联网提供商会阻止传出端口 25 以防止垃圾邮件。大多数需要登录的邮件服务器使用端口 587 或端口 465。端口 587 称为提交端口，大多数时候只能在使用用户名和密码时使用。在客户端和服务器之间的通信期间，端口 587 开始时未加密然后升级为 TLS 加密连接。端口 465 从一开始就是 SSL 加密的，该端口根本没有纯文本通信。 针对每一种端口的常见设置： * 对于使用端口 465 的邮件服务器 ```systemd SMTP_PORT=465 SMTP_SECURITY=force_tls ``` * 对于使用端口 587（有时候是 25）的邮件服务器 ```systemd SMTP_PORT=587 SMTP_SECURITY=starttls ``` * 对于根本不支持加密的邮件服务器 ```systemd SMTP_PORT=25 SMTP_SECURITY=off ``` ### HELO 主机名 默认情况下，机器的主机名被用来作为 HELO 命令中的主机名。要覆盖它，您可以在配置中设置 `HELO_NAME`。 ### Google/Gmail 您需要为 Vaultwarden 生成应用专用密码才能使用 Gmail。按照此处的步骤操作：[使用应用专用密码登录](https://support.google.com/accounts/answer/185833?hl=zh-Hans\&ref_topic=7189145)~~（自 2022 年 5 月 30 日起不可用）~~，最后您会得到一个密码（中间有空格但无需使用，只是为了方便输入），使用这个密码。 {% hint style="info" %} 如果这个无法完成（由于您的安全设置），您可以参阅下面有关 [OAuth2 支持](#oauth2-support)的部分以获取更多信息。 {% endhint %} StartTLS： ```systemd # Domains: gmail.com, googlemail.com SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_SECURITY=starttls SMTP_FROM=user@gmail.tld SMTP_USERNAME=user@gmail.tld SMTP_PASSWORD=Less-Secure-App-Passw0rd ``` FullSSL： ```systemd # Domains: gmail.com, googlemail.com SMTP_HOST=smtp.gmail.com SMTP_PORT=465 SMTP_SECURITY=force_tls SMTP_FROM=user@gmail.tld SMTP_USERNAME=user@gmail.tld SMTP_PASSWORD=Less-Secure-App-Passw0rd ``` 另请参阅：[Using Lettre With Gmail](https://web.archive.org/web/20210925161633/https://webewizard.com/2019/09/17/Using-Lettre-With-Gmail/) ### Hotmail/Outlook/Office365 {% hint style="danger" %} 由于微软要求支持 OAuth2，下面的方法将不再起作用。有关详细信息，请参阅[下面的故障排除](#troubleshooting)。 {% endhint %} ```systemd # Domains: hotmail.com, outlook.com, office365.com SMTP_HOST=smtp-mail.outlook.com SMTP_PORT=587 SMTP_SECURITY=starttls SMTP_FROM=user@hotmail.tld SMTP_USERNAME=user@hotmail.tld SMTP_PASSWORD=MyPassw0rd SMTP_AUTH_MECHANISM="Login" ``` ### SendGrid 将 `` 替换为从 SendGrid 生成的以 `SG` 开头的 API-Key。还要确保 API-Key 具有完整的 `Mail Send` 权限，否则您无法使用此密钥登录。 StartTLS： ```systemd SMTP_HOST=smtp.sendgrid.net SMTP_PORT=587 SMTP_SECURITY=starttls SMTP_USERNAME=apikey SMTP_PASSWORD= SMTP_AUTH_MECHANISM="Login" SMTP_FROM=user@domain.tld ``` FullSSL： ```systemd SMTP_HOST=smtp.sendgrid.net SMTP_PORT=465 SMTP_SECURITY=force_tls SMTP_USERNAME=apikey SMTP_PASSWORD= SMTP_AUTH_MECHANISM="Login" SMTP_FROM=user@domain.tld ``` ## 带特殊字符的密码 如果您想在密码中使用一些特殊字符，可能需要对其中的一些字符进行转义，以免混淆环境变量解析器。 例如，可以使用 `\` 或 `'` 或 `"`，但在实际使用的时候，需要对它们进行转义。如果您使用特殊字符，最好总是使用单引号将密码括起来。 我们以下面这个密码为例：`~^",a.%\,'}b&@|/c!1(#}` 它包含了一些可能会破坏环境变量解析的字符，比如 `\`、`'` 和 `"`。单个 `\` 通常用于转义其他字符，因此如果您想使用单个 `\`，则需要键入 `\\`。 此外，引号 `'` 和 `"` 可能会引起一些问题，因此让我们将此密码括在单引号中并转义特殊字符。为了让上面的密码起作用，我们需要输入 `'~^",a.%\\,\'}b&@|/c!1(#}'`，在这里你看到我们转义了 `\` 和 `'` 字符并使用单引号将整个密码括了起来。所以：`~^",a.%\,'}b&@|/c!1(#}` 变成了 `'~^",a.%\\,\'}b&@|/c!1(#}'`。 ## 使用已弃用的 `SMTP_SSL` 和 `SMTP_EXPLICIT_TLS` SMTP 环境变量（适用于 v1.24.0 及更低版本） 您可以配置 Vaultwarden 通过 SMTP 代理来发送电子邮件： ```shell docker run -d --name vaultwarden \ -e SMTP_HOST= \ -e SMTP_FROM= \ -e SMTP_PORT=587 \ -e SMTP_SSL=true \ -e SMTP_USERNAME= \ -e SMTP_PASSWORD= \ -v /vw-data/:/data/ \ -p 80:80 \ vaultwarden/server:latest ``` 当 `SMTP_SSL` 设置为 `true` 时（这是默认值），将仅接受 TLSv1.1 和 TLSv1.2 协议，并且 `SMTP_PORT` 默认为`587`（等同于 `SMTP_SECURITY=starttls`）。如果设置为 `false`，`SMTP_PORT` 则默认设置为 `25` 并将尝试加密（2020 年 3 月 12 日之前的代码不会尝试加密）（等同于 `SMTP_SECURITY=off`）。这是非常不安全的，仅在您知道您在做什么时才使用此设置。要以隐式模式（强制 TLS）运行 SMTP，请将 `SMTP_EXPLICIT_TLS` 设置为 `true`（等同于 `SMTP_SECURITY=force_tls`）。如果您不登录也可以发送电子邮件，简单地将 `SMTP_USERNAME` 和 `SMTP_PASSWORD` 设置为空即可。 {% hint style="info" %} **注意**：如果您在 v1.25.0 及更高版本上使用 `SMTP_SSL` 和 `SMTP_EXPLICIT_TLS` 设置，Vaultwarden 会对已弃用的设置产生的错误进行忽略。 {% endhint %} ## 故障排除 人们经常遇到 Vaultwarden 连接 SMTP 服务器的问题。大多数情况下，是因为错误的配置或 ISP/主机屏蔽了端口或 IP。 检查您是否可以访问 SMTP 服务器的一些基本步骤是通过在您运行 Vaultwarden（无论是使用 Docker 还是作为一个独立的二进制文件）的主机上运行以下命令来完成。 {% hint style="info" %} **注意**：将 `smtp.google.com` 和 `587`、`465` 或 `25` 替换为与您的 SMTP 服务器对应的主机和端口。 {% endhint %} 这些命令的输出应该是 `0`，如果它返回的不是 `0`，就意味着连接到此服务器时有问题。 ```bash # 首先通过检查对 google.com 的 HTTPS 访问来确认是否可以使用此检查 timeout 5 bash -c 'cat < /dev/null > /dev/tcp/www.google.com/443'; echo $? # 检查 SMTP 提交端口 587 timeout 5 bash -c 'cat < /dev/null > /dev/tcp/smtp.gmail.com/587'; echo $? # 检查 SMTP SSL 端口 465 timeout 5 bash -c 'cat < /dev/null > /dev/tcp/smtp.gmail.com/465'; echo $? # 检查默认 SMTP 端口 25 timeout 5 bash -c 'cat < /dev/null > /dev/tcp/smtp.gmail.com/25'; echo $? # 或者使用一个叫做 nc 的工具（这个工具并不总是在主机上或容器内可用） nc -vz smtp.gmail.com 587 ``` 要从 docker 容器内部检查，请首先在 docker 主机上运行以下命令以登录到容器。在下面的示例中，我假设容器名称是 `vaultwarden`，将其更改为您使用的容器名称。运行下面的命令后，再运行上述命令之一以从容器内部检查访问性。 ```bash docker exec -it vaultwarden sh ``` ### OAuth2 支持 如果您收到以下错误消息： > No compatible authentication mechanism was found（未找到兼容的身份验证机制） 这很可能是因为 Microsoft（以及某些用例的 Google Mail）已切换到 OAuth2（参阅 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)）作为唯一受支持的身份验证方法，而我们（暂时）还不支持，即使 lettre crate 已经有对它的非标准支持（参阅 [#4518](https://github.com/dani-garcia/vaultwarden/discussions/4518#discussioncomment-9196455)）。 推荐的处理方法（如果您不想或可以使用不同的 SMTP 服务器）是设置 [email-oauth2-proxy](https://github.com/simonrob/email-oauth2-proxy)。 ## 使用 `sendmail`（非 Docker） 如果您的系统上已经有一个正在运行的 SMTP 服务器（例如 Postfix），并且您在没有 docker 的情况下安装了 Vaultwarden，那么还需要一些额外的步骤来允许服务器通过 sendmail 使用您的 SMTP 服务器： * 在 Vaultwarden 配置文件（通常是 `/etc/vaultwarden.env`）中，设置 `USE_SENDMAIL=true` * 在同一文件中，设置 `SMTP_FROM=user@example.com`（替换为您自己的！）变量，因为它也被 sendmail 使用 * 以 `root` 用户身份（或使用 `sudo`），使用 `gpasswd -a vaultwarden postdrop` 命令将 `vaultwarden` 用户加入到 `postdrop` 组 * 使用 `systemctl edit vaultwarden` 编辑 vaultwarden systemd 服务然后在 `[Service]` 部分添加如下两行： ```systemd RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_LOCAL AF_NETLINK ReadWritePaths=/var/lib/vaultwarden /var/log/vaultwarden.log /var/spool/postfix/maildrop ``` 最后，别忘了使用 `systemctl restart vaultwarden` 重启服务。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://rs.ppgg.in/configuration/smtp-configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.