邮件

这一篇覆盖后台的”邮件投递”

邮件配置不在 config.toml 里，全在 管理 -> 系统设置 -> 邮件投递。 只要你准备开放注册、找回密码或邮箱改绑，就要先把这一组配通——先配通邮件，再开放注册。

哪些功能依赖邮件：

• 公开注册后的邮箱激活
• 登录页里的找回密码
• 用户在 设置 -> 安全 里改绑邮箱
• 外部认证无法直接匹配本地账号时的邮箱验证
• 登录二次验证里的邮箱验证码 MFA
• 管理员发测试邮件

入口：

管理 -> 系统设置 -> 邮件投递

推荐顺序

1. 填 SMTP 服务器、端口、加密方式
2. 按需填用户名和密码
3. 填发件人地址和发件人名称
4. 先发一封测试邮件给自己
5. 再去试注册激活、密码重置、邮箱改绑
6. 如果要开启外部认证邮箱验证或邮箱验证码 MFA，再分别走一次真实流程

顺序反了的代价

先开放公开注册再补邮件，结果就是一批用户账号已经创建出来，但收不到激活邮件，全部卡在”等待激活”。

选项一览

选项	用途
mail_smtp_host	SMTP 服务器地址
mail_smtp_port	SMTP 端口，默认 587
mail_security	加密方式；465 通常隐式 SSL/TLS，其他端口走 STARTTLS
mail_smtp_username	SMTP 登录用户名
mail_smtp_password	SMTP 登录密码
mail_from_address	收件人看到的发件邮箱
mail_from_name	收件人看到的发件人名称

用户名密码的处理

• SMTP 不需要认证 —— 两个都留空
• 需要认证 —— 两个一起填，避免只填写其中一个

如果你平时不管邮件系统：把 SMTP 简单理解成”发信服务器连接信息”。

怎么确认邮件真的能发出去

邮件投递 页面里有 发送测试邮件 按钮。

常见用法：

• 直接发给当前管理员邮箱
• 临时改成另一个外部邮箱，确认非内网域名也能收到

测试通过后，再做两件事：

1. 到登录页试一次”注册并收激活邮件”或”找回密码”
2. 确认 管理 -> 系统设置 -> 站点配置 -> 公开站点地址 已经填对

邮件模版能改什么

当前内置 7 组模版：

• 注册激活
• 邮箱改绑确认
• 密码重置
• 密码重置结果通知
• 旧邮箱变更通知
• 外部登录邮箱验证
• 登录邮箱验证码

每组都能分别改：

• 主题
• 邮件正文（HTML）

不用自己猜变量名

页面右侧会列出当前模版可用的魔法变量，照着填就行。

公开站点地址 为什么要一起配

激活链接、密码重置链接、邮箱改绑确认链接都要生成能从外部打开的地址。

如果实际访问地址是：

https://drive.example.com

就到这里设置：

管理 -> 系统设置 -> 站点配置 -> 公开站点地址

如果同一个实例有多个公开入口，可以在列表里逐项填进去。邮件这类没有当前浏览器 Host 的后台流程会使用第一项作为默认来源，所以把最希望用户点击的默认来源放在最前面。

只填站点根地址

不要带路径，不要带 /api，就只填到来源层，例如 https://drive.example.com。

没配好时会出现什么

现象	大概是哪一步出问题
新用户能注册但收不到激活邮件	SMTP 连不通，或被收件方拒收
找回密码按钮能点，邮箱里没重置链接	同上，或者没填 公开站点地址
用户能发起改绑但新邮箱收不到确认	同上
外部登录走到邮箱验证但收不到邮件	SMTP 没配通，或外部登录邮箱验证模版/公开站点地址不对
MFA 页能点发送邮箱验证码但收不到	SMTP 没配通，或登录邮箱验证码模版被改坏
测试邮件失败	SMTP 配置不对，或网络出口不通

排查清单：

1. SMTP 主机、端口、加密、账号密码
2. 发件邮箱地址是否被 SMTP 服务允许
3. 公开站点地址 是否改成外部真实 HTTP(S) 来源；如果有多个入口，邮件默认来源是否放在第一行
4. 收件箱、垃圾箱都翻一次
5. 邮件恢复正常后，重新发激活邮件或改绑确认邮件