Scert/doc/邮件通知配置说明.md

邮件通知配置说明

1. 配置目的

Scert 的证书申请、续期、部署和校验任务完成后，可以通过第三方邮件服务 API 或 SMTP 服务发送通知。Scert 只实现出站通知客户端，不实现 SMTP、IMAP、POP3 邮件服务器端；HTTP 邮件 API 和 SMTP 出站通知均已接入。

2. HTTP 邮件服务配置

配置项	说明	默认值
email_http_enabled	是否启用 HTTP 邮件通知	false
email_provider	第三方服务标识	空
email_endpoint	第三方服务基础地址，必须使用 HTTP 或 HTTPS	空
email_http_path	请求路径	/api/email/send
email_http_auth_mode	none、bearer、hmac_sha256 或 session	none
email_http_login_path	会话认证模式的登录请求路径	/api/login
email_http_credential_ref	凭据引用，不填写明文 Token 或密钥	空
email_http_headers	自定义请求头 JSON 对象	{}

email_endpoint 与 email_http_path 分开保存。例如 Smail 服务可以配置基础地址为 https://mail.example.com，请求路径使用 /api/email/send。

Bearer Token 或 HMAC-SHA256 的实际密钥必须由凭据存储管理，配置文件只保存 secret:// 等形式的引用。自定义请求头不能覆盖 Authorization、Cookie、Origin、Referer、Content-Type、Accept、X-CSRF-Token、X-Scert-Signature、X-Scert-Request-Id 和 X-Scert-Timestamp 等安全请求头。

3. Smail 接口适配说明

Smail 的发送接口为：

POST /api/email/send
Content-Type: application/json

请求体沿用 Smail 的英文字段名，包括 from、to、cc、bcc、subject、text、html 和 attrs。Scert 的通知发送器应将证书任务事件转换为邮件标题、纯文本正文和 HTML 正文。

Smail 当前接口需要登录会话 Cookie、smail_csrf Cookie、X-CSRF-Token 请求头和同源 Origin 请求头。Scert 的 session 认证模式会使用凭据存储中的账号和密码调用配置的登录路径，读取登录响应中的会话 Cookie，并在发送邮件时携带会话、CSRF 和同源请求头；密码不会写入请求日志、普通配置文件或错误信息。

4. 通知内容配置

配置项	说明
email_event_mode	detailed 表示发送详细事件，unified 表示发送统一事件
email_include_deployment_details	是否包含服务器部署明细
email_include_certificate_serial	是否包含证书序列号
email_include_management_url	是否包含管理后台链接
email_sender_name	发件人名称，默认 Scert
email_sender_email	发件人地址，留空时使用超级管理员绑定邮箱
recipients	收件人列表；未填写时自动使用超级管理员绑定邮箱

5. 超时与重试

配置项	说明	默认值
email_timeout_secs	单次通知请求超时时间	10
email_retry_count	失败后的重试次数	3
email_retry_intervals_secs	每次重试前等待的秒数	30,120,600

重试间隔数量必须与重试次数一致。HTTP 通知发送器应将所有 2xx 响应视为请求成功，其他状态码进入重试或失败流程，并记录请求 ID 和最终错误。

6. 当前实现边界

当前阶段已完成邮件通知配置的保存、校验、初始化接口、CLI/Web 表单接入、HTTP 通知发送器和 SMTP 出站通知发送器。SMTP 支持 plain、starttls 和 implicit_tls 三种连接模式；生产环境建议使用 STARTTLS 或隐式 TLS。Smail 登录会话可通过 session 认证模式自动建立和刷新。

7. 当前开发状态补充

当前版本已经接入 HTTP 邮件通知发送器，支持以下能力：

• 按证书申请、续期、导入和部署结果生成通知事件。
• 按 Smail /api/email/send 接口格式发送 JSON 请求。
• 支持 none、bearer、hmac_sha256 和 session 四种 HTTP 认证模式。
• session 模式支持配置登录路径；收到 HTTP 401、403 或对应业务错误码时，会在重试前重新登录并使用新会话发送。
• 使用加密凭据存储读取 Bearer Token 或 HMAC 签名密钥，配置文件只保存凭据引用。
• 使用 X-Scert-Request-Id、X-Scert-Timestamp 请求头，并禁止自定义请求头覆盖安全头。
• 将所有 2xx 响应视为成功，其他响应按重试配置处理。
• 证书工作流会在任务成功、失败或部署错误后触发通知；通知发送失败会写入 Scert 日志，不覆盖原证书任务结果。

SMTP 出站通知已经接入。初始化界面和 CLI 可以配置 SMTP 主机、端口、用户名、凭据引用、连接模式和明文认证开关；SMTP 密码只保存到加密敏感信息存储，配置文件仅保存 secret:// 凭据引用。明文连接认证默认拒绝，只有明确启用 SMTP 明文认证 后才允许。CLI 可使用 scert config set-secret --key notification.smtp_password 保存敏感值。SMTP 是出站连接，Scert 不需要开放 SMTP 入站端口。Smail 登录会话的自动适配已通过 session 模式接入，仍需在目标部署环境使用实际凭据进行上线前复核。