邮箱通知配置

邮箱通知适合保存可检索的告警记录，也适合作为 Telegram 或飞书之外的备用通道。系统通过 SMTP 投递邮件，SMTP 授权码会加密保存，前端不会再次显示明文。

1. 准备邮箱

建议创建专用告警邮箱，不要直接使用个人主邮箱。进入邮箱服务商后台：

1. 开启 SMTP 服务。
2. 启用账号 2FA（如服务商支持）。
3. 创建“应用密码”或“客户端授权码”。
4. 记录 SMTP Host、端口、用户名和发件地址。
5. 准备至少一个收件地址。

SMTP 授权码不是网页登录密码。不要把主账号密码填进通知系统。

2. 选择加密方式

常见组合如下，最终以邮箱服务商后台给出的参数为准：

连接方式	常用端口	SSL	STARTTLS
SMTP over SSL	465	开启	关闭
SMTP + STARTTLS	587	关闭	开启

不要同时开启 SSL 和 STARTTLS。不要在公网使用未加密的 SMTP 登录。

3. 确认服务端加密密钥

熊猫寨工具保存 SMTP 授权码前，需要服务端已经配置持久化主密钥 ARBITRAGE_MASTER_KEY 或 ARBITRAGE_MASTER_KEY_FILE。主密钥缺失时，邮件配置会保持 fail-closed，不能保存或发送。

主密钥必须：

• 保存在仅服务账号可读的 Secret 或权限受控文件中
• 在服务重启和升级后保持不变
• 与数据库分开备份
• 禁止提交到 Git

如果主密钥丢失，旧的加密 SMTP 授权码无法恢复，只能重新配置。

4. 在工具中填写

登录工具后进入“邮件推送”，点击“编辑配置”：

字段	填写内容
SMTP Host	邮箱服务商提供的 SMTP 服务器域名
Port	通常为 465 或 587
用户名	通常是完整邮箱地址，按服务商要求填写
授权码	应用密码或 SMTP 客户端授权码
发件人	允许发信的完整邮箱地址
收件人	一个或多个地址，多个地址用英文逗号分隔
SSL	使用 465 时通常开启
STARTTLS	使用 587 时通常开启

保存后页面应显示 SMTP 地址、发件人和收件人，但不应回显授权码。

5. 发送测试邮件

点击“发送测试邮件”，随后检查：

• 收件箱是否到达
• 垃圾邮件和隔离区是否误拦截
• 发件人名称与地址是否正确
• 邮件主题是否能明确识别为测试告警
• 服务端审计日志是否记录成功，但不包含授权码

测试邮件成功后，再触发一条低风险测试告警，确认真实告警队列也能完成投递。

推荐的告警分级

级别	建议邮件策略
Info	可汇总发送，避免大量邮件
Warning	单独发送，例如条件异常或自动重试
Critical	立即发送，例如单腿成交、Kill Switch、对账失败

不要把所有行情波动都设置成即时邮件，否则真正的严重告警容易被噪声淹没。

常见问题

认证失败

确认使用的是 SMTP 授权码而不是网页登录密码；检查用户名是否必须填写完整邮箱地址，并确认授权码没有首尾空格。

连接超时

检查云服务器安全组和主机防火墙是否允许访问 SMTP 端口。部分云服务商默认限制 25 端口，优先使用邮箱服务商支持的 465 或 587。

TLS 或证书错误

检查 SSL/STARTTLS 是否与端口匹配、系统时间是否正确、系统 CA 证书是否过期。不要通过关闭证书验证来绕过错误。

显示发送成功但未收到

检查垃圾邮件、邮箱规则、发件频率限制和 DMARC/SPF 策略。将专用发件地址加入收件方白名单，并用不同服务商的收件箱交叉测试。

重启后无法解密配置

通常是主密钥发生变化或密钥文件未挂载。恢复原主密钥；如果无法恢复，删除旧配置并重新填写授权码。

上线检查

• [ ] 使用专用发件邮箱和 SMTP 授权码
• [ ] SSL 或 STARTTLS 已启用
• [ ] 主密钥已持久化并安全备份
• [ ] 测试邮件和真实测试告警均已送达
• [ ] 严重告警至少还有一个备用通知通道