# SMTP 配置
{% hint style="success" %}
对应的[官方文档地址](https://bitwarden.com/help/smtp-configurations/)
{% endhint %}
本指南涵盖 Bitwarden 自托管服务器的 SMTP（简单邮件传输协议）设置和常见配置问题。SMTP 通过 `api`、`identity`、`admin` 和 `notifications` 容器协同处理。所有设置均在 `global.override.env` 中配置。
{% hint style="info" %}
自托管部署中必须配置 SMTP，因为它是发送[来自 Bitwarden 的电子邮件](/docs/security/trusted-communications/emails-from-bitwarden-servers.md)和便于[系统管理员门户](/docs/self-hosting/system-administrator-portal.md)访问所必需的。
{% endhint %}
## 配置位置
通过访问 `global.override.env` 文件来管理和更新您的 SMTP 设置。
## SMTP 设置最佳实践
### 使用端口 587 用于电子邮件提交
端口 587 是默认的电子邮件提交端口。该端口是电子邮件提交的行业标准，支持 TLS 加密，并遵循 IETF 指南。
{% hint style="info" %}
除非您有特定的技术要求以及获得托管提供商的明确批准，否则请始终将 Bitwarden 配置为使用端口 587。
{% endhint %}
### 避免端口 25 用于应用程序电子邮件
端口 25 不应用于 Bitwarden 电子邮件配置，也不适用于应用程序级别的电子邮件提交。此端口仅用于服务器到服务器的 SMTP 中继，它通常会被住宅 ISP 和云托管提供商屏蔽。
## 安全配置最佳实践
### 启用 TLS 加密
始终使用 TLS 加密来保护电子邮件内容和凭据：
```systemd
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=false
globalSettings__mail__smtp__startTls=true
```
端口 587 默认通过 `startTls` 使用 TLS。使用 `startTls` 时，请设置 `ssl=false` 。
### 证书处理
对于生产环境，请确保您的 SMTP 服务器拥有有效且受信任的 SSL/TLS 证书。对于使用自签名证书的故障排除、开发或测试环境，您可以使用：
```systemd
globalSettings__mail__smtp__trustServer=true
```
{% hint style="danger" %}
仅在受控的开发环境中使用 `trustServer=true` 。对于生产系统，请始终使用经过正确验证的证书，以防止中间人 (MitM) 攻击。
{% endhint %}
### 验证服务器证书
配置 Bitwarden 以验证您的服务器证书：
{% tabs %}
{% tab title="Docker" %}
1. 将您的根 CA 证书复制到 `./bwdata/ca-certificates` 中。
2. 运行 `./bitwarden.sh restart` 命令将证书应用到您的容器并重启服务器。
{% endtab %}
{% tab title="Helm" %}
1. 在您的 `my-values.yaml` 配置文件中，设置值 `caCertificate.enabled: true` 。
2. 创建一个包含证书文件的 ConfigMap 对象。最简单的方法是在 `my-values.yaml` 文件中添加 `preInstall` [RawManifest](/docs/self-hosting/deploy-and-configure/helm/add-rawmanifest-files.md)，如下例所示：
```yaml
rawManifests:
preInstall:
- kind: ConfigMap
apiVersion: v1
metadata:
name: cacert
data:
rootca.crt: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
postInstall:
```
{% endtab %}
{% endtabs %}
## 推荐配置
该部分演示了在设置自托管环境时可参考的常见 SMTP 配置。
### 标准企业 SMTP 配置
以下是一个标准 SMTP 配置示例：
```systemd
globalSettings__mail__replyToEmail=no-reply@yourdomain.com
globalSettings__mail__smtp__host=mail.yourdomain.com
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=false
globalSettings__mail__smtp__startTls=true
globalSettings__mail__smtp__username=bitwarden@yourdomain.com
globalSettings__mail__smtp__password=your-secure-password
```
### Office 365 配置示例
对于使用 Microsoft Office 365 的组织：
```systemd
globalSettings__mail__replyToEmail=bitwarden@yourdomain.com
globalSettings__mail__smtp__host=smtp.office365.com
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=false
globalSettings__mail__smtp__username=bitwarden@yourdomain.com
globalSettings__mail__smtp__password=your-secure-password
```
Microsoft 建议使用专用服务账户，而不是个人电子邮箱。有关详细的设置指南，请参考[配置多功能设备](https://learn.microsoft.com/zh-cn/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365)或应用程序的 Microsoft 文档。
### 应用配置更改
配置更改需要重启服务器才能生效。请将配置更改应用到 `global.override.env` ，然后执行重启以应用更改：
```shellscript
./bitwarden.sh restart
```
{% hint style="info" %}
仅重启单个容器将不会应用配置更改。
{% endhint %}
### 验证容器健康状况
在部署到生产环境之前，务必验证所有容器是否运行正常：
```shellscript
docker ps
```
### 测试 SMTP 连接
上线前，请从 API 容器内测试 SMTP 连接，以确保网络路径畅通且身份验证正常工作。
1、访问 API 容器：
```shellscript
sudo docker ps
sudo docker exec -it sh
```
2、安装测试工具：
```shellscript
apk update
apk add busybox-extras
```
3、测试连接性：
```shellscript
telnet 587
```
成功的连接表明网络连接和防火墙规则已正确配置。
### 监控电子邮件日志
定期审查以下位置的电子邮件相关日志，以便及早发现问题：
* `./bwdata/logs/admin/`
* `./bwdata/logs/api/`
* `./bwdata/logs/identity/`
* `./bwdata/logs/notifications/`
在生产环境中实施电子邮件发送失败的日志监控或警报。
## 其他配置选项
Bitwarden 支持额外的 [SMTP 环境](/docs/self-hosting/deploy-and-configure/configuration-options/environment-variables.md#optional-variables)变量。请根据您组织的需求审查这些选项以自定义电子邮件行为。
## 摘要检查清单
在部署 Bitwarden SMTP 配置之前，请检查以下最佳实践：
* 已配置用于电子邮件提交的端口（例如端口 587）
* 已启用 TLS 加密
* 已配置强大且唯一的 SMTP 凭据
* 已设置专门的回复地址
* 通过 API 容器测试了连接性
* 所有容器均显示为健康
* 通过服务器完全重启应用了配置
* 已实施日志监控
* 正在使用有效的 SSL/TLS 证书（生产环境）
* 文档已使用配置详细信息更新
---
# 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://help.ppgg.in/docs/self-hosting/deploy-and-configure/configuration-options/smtp-onfigurations.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.