邮件与短信
邮件与短信都走「集成插件」：先在插件页安装并启用一个通道插件，再填凭据，最后打开站点设置里的通知总开关。三个环节少一个，对外就发不出验证码。本文按这个顺序说明入口、字段、留空后果与验证方法。
1. 后台入口
| 页面 | 路径 | 权限 |
|---|---|---|
| 邮件发送（插件列表） | 系统设置 → 集成插件 → 邮件发送 | 列表 integration_plugin.view；安装/改配置/启停 integration_plugin.manage；测试发送 integration_plugin.test |
| 短信发送（插件列表） | 系统设置 → 集成插件 → 短信发送 | 同上 |
| 通知总开关 | 站点内容 → 站点配置 → 站点设置 → 通知总开关 | 页面 site.view，写入 settings.manage |
| 邮件模板 | 站点内容 → 通知与接口 → 邮件模板 | settings.view / settings.manage |
| 短信模板 | 站点内容 → 通知与接口 → 短信模板 | 同上 |
| 邮件日志 / 短信日志 | 日志中心 → 日志管理 → 邮件日志 / 短信日志 | log.list |
插件列表页会扫描 backend/plugins/{domain}/ 下的目录，本地新增插件文件后点「扫描插件」才会出现。安装与启用是两步：点「安装」写入记录，再点「启用」激活运行时。
「发送测试邮件 / 发送测试短信」属于测试接口（integration_plugin.test），限流 10 次/分钟——它会真实发信，只是走了直发通道。没有这个权限的账号在插件详情页点测试会提示无权限。
2. 一个功能域只能启用一个插件
mail、sms 与 captcha、verification 同属「单启用域」。域内已有一个启用插件时再去启用第二个，会直接报「当前功能域已启用「XXX」，请先停用后再启用其他插件」（错误码 42200）。支付与上游不受此限制，可以并存多个。
启用的同时会写一条驱动绑定记录，系统按它决定当前用哪个驱动；绑定找不到时才回退环境变量 MAIL_DRIVER_DEFAULT（默认 smtp）与 SMS_PROVIDER_DEFAULT（默认 aliyun）。所以换短信服务商的标准做法是：先停用旧插件，再启用新插件，不需要改 .env。
3. 邮件通道
可选插件：smtp（Single SMTP，生产用这个）、multi_smtp_round_robin（多 SMTP 轮询）、demo_mail（演示，不连接真实 SMTP）。
smtp 插件字段：
| 字段 | 默认值 | 留空后果 |
|---|---|---|
host SMTP 主机 | 空 | 发送直接抛「邮件接口配置不完整」 |
port SMTP 端口 | 465 | 端口 ≤ 0 同样报配置不完整 |
username SMTP 账号 | 空 | 报配置不完整；同时兼作默认发件人地址 |
password SMTP 密码 | 空 | 报配置不完整（保存后不回显，留空保存表示不改） |
from_address 发件人地址 | 空 | 回退使用 SMTP 账号，保持老配置行为 |
from_name 发件名称 | 空 | 回退当前站点名称 |
encryption 加密方式 | 「自动」 | 自动时按端口推断：465 → SSL，25 → 无，其余 → TLS |
timeout_seconds 超时秒数 | 8 | 无效值同样按 8 秒处理 |
rate_limit_enabled 启用邮箱验证码限流 | 开 | 关闭后单 IP 不再限制验证码请求 |
ip_minute_limit 单 IP 每分钟上限 | 6 | 填 0 表示不限制 |
from_address 与 SMTP 账号可以不同；多数企业邮箱要求两者一致或已授权，不一致会被对方拒收，这属于对端策略，系统不做校验。
multi_smtp_round_robin 用「SMTP 账号列表」（accounts，JSON 类型、标记为密钥）维护多个账号，通过账号管理器维护，失败后自动轮询到下一个可用账号，cooldown_seconds 默认 60 秒，即发送失败的账号冷却 60 秒后才重新参与轮询。它的限流项与 smtp 相同。
邮件模板在「邮件模板」页维护，落到 notification_templates 表，键名前缀为 email_template_subject_、email_template_content_、email_template_enabled_。在后台改过内容或启用开关的模板会被标记为已个性化（is_custom=1），系统升级时不会用新版默认模板覆盖它；没动过的模板会随升级刷新。升级后觉得某封邮件样式没更新，先看这个模板是不是被改过。
4. 短信通道
可选插件四个，能力并不相同：
| 插件 slug | 名称 | 上游产品与接口 |
|---|---|---|
aliyun | 阿里云号码认证 | 号码认证（PNVS）/ SendSmsVerifyCode，免资质，仅中国大陆号码 |
aliyun_sms | 阿里云短信服务 | 短信服务（SMS）/ SendSms，V3 签名，需资质报备与签名、模板审核 |
stay33 | MC云短信 | 按平台 API 信息填用户名与用户密钥 |
demo_sms | Demo 短信 | 只模拟发送结果，用于验证插件流程 |
aliyun 与 aliyun_sms 是阿里云的两个独立产品，控制台、接口、套餐包、签名与模板体系互不相通，模板不能互换。aliyun 的验证码模板由插件按业务场景内置选择（控制台赠送的 100001–100005），因此没有模板 ID 填写项；用错产品会出现「扣了号码认证套餐但短信服务的模板报缺参数」这类错配。
aliyun_sms 字段较多，分四组：
- 凭据：
access_key、secret_key（AccessKey Secret）、sign_name（短信签名，必须是控制台「签名管理」中审核通过的名称）、endpoint（默认dysmsapi.aliyuncs.com，仅专属/国际站接入点才需要改）。 - 验证码模板：
template_code默认模板 ID（必填，形如SMS_123456789，所有场景都回退到它）；code_variable验证码变量名（默认code，必须与模板正文的${...}占位符一致）；expire_variable有效期变量名（留空表示模板里没有该变量，填了但模板没有会被阿里云拒绝）。 - 分场景模板：
template_login、template_change_phone、template_reset_password、template_bind_phone、template_verify_bound_phone，全部可留空，留空即沿用默认模板。只备案了一个模板时只填默认模板即可。 - 限流与高级：
rate_limit_enabled（默认开）、ip_minute_limit（默认6，0 表示不限）、request_timeout（默认 10 秒，范围 3–30）。
code_variable 填错是最常见的一类故障：阿里云会返回「模板参数缺失」，日志里能看到，但短信就是发不出去。
stay33 需要 username、api_key（用户密钥）、sign_name（签名名称，不含外层 【】），发送前需在平台完成签名与实名并确认账号有额度。
5. 短信模板
「短信发送」插件里的模板 ID 是通道侧的编号；系统侧每个通知场景还有自己的模板记录，在「短信模板」页维护，落到 notification_templates 表。对应设置键为 sms_template_content_{code}、sms_template_provider_template_id_{code}、sms_template_enabled_{code}。
provider_template_id 是「这个系统场景用通道的哪个模板」的映射，解析顺序是：本次调用显式传入 → 模板行上存的 provider_template_id → 旧版验证码模板 ID → 回退用系统模板编号本身。所以只配 aliyun_sms 的默认模板、其余留空也能跑通验证码；要用不同场景发不同短信，才需要逐个场景指定通道模板 ID。
6. 验证与排障
按下面顺序验证，每一步都能定位到具体环节：
- 插件详情页点「检测」（
health_check）：校验清单文件、必需的配置项是否齐全，并实例化入口类；入口类自己实现了健康检查时还会返回它的结果。它不联系上游、不发信，只回答「这个插件能不能正常加载」。 - 阿里云短信服务插件配置里的「检测」按钮：一次性只读核验凭据、签名与模板，并比对模板正文的变量名，不发短信、不计费。签名或模板没审核通过会在这里暴露。
- 邮件插件详情页「发送测试邮件」（填收件人邮箱，固定用账号索引 0）或短信插件详情页「发送测试短信」（填手机号）。这一步走驱动直发，绕过通知总开关；如果总开关是关的，成功提示里会明确写出「但站点设置中的『启用邮件通知』当前为关闭状态，对外仍不会发送邮件」，不要把它读成「已经能用了」。
- 打开站点设置里的
email_enabled/sms_enabled。 - 用真实用户走一遍注册或找回密码，然后到「邮件日志」或「短信日志」看记录：日志里带收件人、模板编号、通道模板 ID、状态与错误信息，失败原因就在这里。
# 出问题时先确认队列与调度在跑，通知类任务由心跳驱动
cd /你的项目/backend
php artisan schedule:run常见故障对照：
- 测试成功但用户收不到：通知总开关是关的，或对应模板被停用（
is_enabled为 0）。 - 短信报「模板参数缺失」：
code_variable与通道模板正文的变量名不一致。 - 报「短信驱动 [xxx] 未注册」：启用了插件但没有绑定记录，重新停用再启用一次。
- 邮件报「邮件接口配置不完整」：
host、port、username、password有一项为空。