#通知

Luna DevOps 将通知分成两类：管理员维护面向团队的共享通知路由；每位用户维护只属于自己的通知偏好和个人 Webhook 渠道。通知不使用项目资源的“与我相关 / 全部”范围切换，个人与共享入口始终按各自权限独立返回。建议只订阅确实需要处理的失败事件，避免产生过多消息。

#配置平台邮件服务

平台管理员先在“站点设置 → 邮件服务”配置一套全局 SMTP。邮件服务只保存发送连接和发件人，不保存固定收件人；注册验证码和个人邮件通知都会复用它。

填写主机、端口、安全模式、账号、发件地址和发件名称。使用账号认证时还要填写密码，密码只写入 Secret Store，保存后不再回显；后续编辑时留空密码表示继续使用原值。

“个人邮件聚合冷却”只控制个人失败事件邮件。第一封邮件立即发送，冷却期内同一用户的后续事件会合并，并在冷却结束后发送下一封；每封摘要最多包含 20 个事件，超出的事件会保留并在后续冷却周期继续发送。默认 60 秒，可填写 0–3600，其中 0 表示不等待。注册验证码、账号找回、管理员测试邮件和共享 SMTP 渠道不受该设置影响。

保存后填写一个已获授权的测试收件地址并发送测试邮件。如果测试失败，请检查端口与安全模式是否匹配、账号是否允许 SMTP 登录，以及 API 和 Worker 所在网络是否可以连接邮件服务器。

个人通知不会把多个用户合并到同一封邮件的 To、CC 或 BCC 中。平台会根据内部用户 ID 读取该用户的账号邮箱，并为每位用户独立投递，避免泄露其他用户地址。

#配置我的通知

登录后在“账号设置 → 通知”管理本人通知：

1. 选择是否接收邮件；首次使用默认启用。
2. 选择需要订阅的失败事件。
3. 按需从平台预设中添加只属于自己的飞书、Lark、企业微信、钉钉、Slack 或 Discord 渠道。
4. 保存渠道后发送测试消息，再查看个人投递记录。

个人邮件固定发送到账号邮箱，不能填写任意 To、CC 或 BCC，也不需要个人 SMTP 凭据。个人事件邮件使用 HTML 摘要并附带纯文本备用内容，每个事件展示事件类型、项目空间、应用、部署配置等上下文及该类型的关键详情。个人 Webhook 的 Token、Key 等密钥只写入 Secret Store，保存后不会回显；目标地址仍受平台出站安全策略限制，不能访问受保护的内网地址。

当前个人订阅支持以下失败事件：

• build.failed
• release.failed
• hook.failed
• gateway.apply_failed
• certificate.failed
• certificate.expired

个人投递只会发给事件的内部操作者和被操作资源的创建者；两者相同时只投递一次。平台在创建投递和实际发送前都会检查收件人仍有当前项目空间的访问权、账号可用且仍订阅该事件；仅仅是项目成员或平台管理员不会自动收到。Git Webhook 等外部载荷声明的邮箱地址不会用于解析收件人。

个人渠道只接受平台内置预设及其明确声明的 Secret 字段，不开放任意 URL、请求头或 JSON 配置，避免 Webhook Token 明文进入业务数据。

每位用户最多保留 10 个个人渠道。单次个人通知配置请求不能超过 64 KiB，渠道名称最多 160 个字符，每个预设声明的 Secret 最多 4096 个字符；未声明字段会被拒绝。个人渠道测试按用户限制为每分钟 10 次。

#配置团队共享通知

“通知集成”页面只对平台管理员开放，用于维护共享目标和事件路由：

• 共享渠道：团队飞书群、企业微信群、固定 Webhook 或固定邮件组。
• 路由规则：选择哪些平台事件满足条件时发到哪些共享渠道。每条规则必须明确选择一个或多个项目空间；只有管理员主动选择“全部项目”时才允许匹配全平台事件，空范围不会被当作全部。
• 消息模板：需要自定义消息内容时使用的高级配置。
• 投递记录：排查共享投递的状态、尝试次数和错误摘要。

共享 SMTP 渠道仍适合固定邮件组，可以配置 To、CC 和 BCC；它与平台邮件服务的用途不同。平台邮件服务负责按账号邮箱发送个人邮件，共享 SMTP 渠道则由管理员规则发送到预先配置的固定收件人。

创建 Webhook 渠道时优先选择内置集成预设，只填写目标平台要求的 Token、Key 或地址。自定义 Webhook 需要填写请求地址、方法、请求头和 JSON 消息模板。保存后先发送测试消息，再创建路由规则。

如需让通知跳转到平台详情页，请为 API 和 Worker 配置相同的 PUBLIC_BASE_URL。配置后，个人 HTML 邮件中的每个事件会同时提供“查看详情”按钮和可复制的绝对地址；未配置时通知仍可发送，但不会包含平台链接。

#验证通知

#个人通知

1. 确认“账号设置 → 通知”中的邮件开关和事件选择已保存。
2. 对每个个人 Webhook 渠道发送测试消息。
3. 在测试环境以自己的账号触发一个已订阅的失败事件。
4. 在个人投递记录中确认邮件和 Webhook 的终态。

#共享通知

1. 创建共享 Webhook 或 SMTP 渠道并发送测试消息。
2. 创建规则，明确选择项目空间范围、事件和共享渠道；只有确实需要平台级广播时才选择“全部项目”。
3. 在测试环境触发一次匹配事件。
4. 在管理员投递记录中确认状态和错误信息。

不要为了验证通知而在生产环境制造故障。

#常见问题

#没有收到个人邮件

确认全局邮件服务测试成功、账号邮箱正确、个人邮件开关已启用、事件已被选中，而且当前用户是事件的内部操作者或被操作资源的创建者，并且仍有对应项目空间的访问权。若事件发生在上一封个人邮件的聚合冷却期内，请等待冷却结束后再检查下一封邮件。

#Webhook 测试成功，真实事件没有通知

个人渠道需要确认事件已在本人偏好中选中且渠道已启用。共享渠道需要检查规则是否启用、事件类型和过滤条件是否匹配，以及投递记录是否生成。

#投递持续失败

检查凭据、消息模板、目标地址和对方服务状态。网络错误、限流和服务端错误可能自动重试；配置或模板错误通常需要修正后再次测试。

#通知里没有详情链接

确认 API 和 Worker 使用相同且可从用户浏览器访问的 PUBLIC_BASE_URL。