平台功能（自研）可视化配置
邮件配置
邮件配置把 SMTP 参数从 application.yml 搬到数据库，管理员在页面上即可完成发件邮箱的切换。MailConfig 每次发信都会重新读取配置，所以保存后立即生效。
邮件配置（截图占位）
/images/docs/settings-email.png建议 1920 × 1080，截 SMTP 主机、端口、账号与发件人。
配置项
| 配置项 | 配置键 | 默认 | 说明 |
|---|---|---|---|
| 邮箱功能开关 | mail.enabled | true | 关闭后所有发信直接跳过 |
| SMTP 服务器 | mail.host | smtp.qq.com | 服务商 SMTP 地址 |
| SMTP 端口 | mail.port | 465 | SSL 常用 465，STARTTLS 常用 587 |
| 邮箱账号 | mail.user | — | 完整邮箱地址 |
| 邮箱密码 | mail.pass | — | 密码或授权码，建议使用授权码 |
| 发件人地址 | mail.from | — | user@example.com 或 Name <user@example.com> |
| 是否需要认证 | mail.auth | true | 多数服务商必须开启 |
| 使用 STARTTLS | mail.starttlsEnable | false | 与 SSL 二选一 |
| 使用 SSL | mail.sslEnable | true | 465 端口通常开启 |
| SMTP 超时 | mail.timeout | 25000 | 单位毫秒 |
| 连接超时 | mail.connectionTimeout | 25000 | 单位毫秒 |
常见服务商参数
| 服务商 | Host | Port | 加密 |
|---|---|---|---|
| QQ 邮箱 | smtp.qq.com | 465 | SSL，密码填授权码 |
| 163 邮箱 | smtp.163.com | 465 | SSL，密码填授权码 |
| 阿里云企业邮箱 | smtp.qiye.aliyun.com | 465 | SSL |
| Gmail | smtp.gmail.com | 465 | SSL，需要应用专用密码 |
| Outlook | smtp.office365.com | 587 | STARTTLS |
授权码不是登录密码。QQ / 163 邮箱需要在网页端「设置 → 账户」中开启 SMTP 服务并生成授权码。
发信链路
业务代码 → MailService → MailConfig.createMailAccount()
→ 读取 sys_config(email) → 构建 MailAccount → 发送MailConfig 的行为：
- 配置为空或
mail.enabled != true时返回null，调用方跳过发信； - 任何异常（端口非法、字段缺失）都被捕获并返回
null，不会让业务请求失败； - 不做连接池，每次发信建立连接，适合低频通知场景。
使用场景
- 注册 / 找回密码验证码；
- 系统通知、告警；
- 应用内业务邮件（通过平台
MailService或应用自己的实现）。
发送记录可在「日志管理 → 消息发送日志」查看（取决于业务是否写入 sys_message_log）。
测试配置
保存后建议立即验证：
- 在「消息中心」创建一条测试消息并发布；
- 或调用业务侧的发信接口；
- 查看「消息发送日志」，确认状态为成功；
- 检查收件箱与垃圾邮件目录。
安全
mail.pass属于敏感配置，列表接口不返回明文；查看明文需要额外权限。- 不要把授权码提交到 Git、截图或工单。
- 生产与测试使用不同发件账号，避免测试邮件污染正式域名信誉。
排错
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 保存成功但收不到邮件 | 未开启 SMTP 服务 | 到邮箱网页端开启并生成授权码 |
Could not connect to SMTP host | 端口 / 加密方式不匹配 | 465 + SSL，或 587 + STARTTLS |
535 Authentication failed | 使用了登录密码 | 改用授权码 |
| 发件人地址被拒 | mail.from 与账号不一致 | 多数服务商要求 From 等于登录账号 |
| 超时 | 服务器出网受限 | 检查 465/587 出站策略与 DNS |
日志显示 mail.enabled=false | 开关关闭 | 打开开关并保存 |