szx/NewSzxcn-Email
1
0
Fork 0
Code Issues Pull Requests Actions 55 Packages Projects Releases Wiki Activity

feat: harden Telegram mail notifications
Docker Release / Check web and api (push) Waiting to run
Details
Docker Release / Resolve release tag (push) Blocked by required conditions
Details
Docker Release / Build and publish all-in-one (push) Blocked by required conditions
Details
Docker Release / Build and publish api (push) Blocked by required conditions
Details
Docker Release / Build and publish web (push) Blocked by required conditions
Details
Docker Release / Build and publish dovecot (push) Blocked by required conditions
Details
Docker Release / Build and publish postfix (push) Blocked by required conditions
Details
Docker Release / Build and publish rspamd (push) Blocked by required conditions
Details
Docker Release / Create GitHub release (push) Blocked by required conditions
Details

Browse Source
This commit is contained in:
zxyszx
2026-08-06 17:13:08 +08:00
parent 4c90c1de44
commit 635ab02b29
16 changed files with 1099 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/GUIDE.md
+9 -6
View File
@@ -64,13 +64,16 @@ DNS 生效通常需要几分钟到数小时。系统只能检测记录，不能
管理员可以把每封新收邮件的概要发送到自己的 Telegram 私聊：
1. 使用 `@BotFather` 创建一个邮件通知机器人并取得 Bot Token。
2. 在 Telegram 中打开机器人，发送 `/start`。
3. 进入“管理后台 -> 系统设置 -> 通知”。
4. 填写 Bot Token，点击“自动获取”取得私聊 Chat ID。
5. 选择正文显示方式并点击“测试通知”。
6. 测试成功后开启“私聊新邮件通知”，保存设置。
2. 进入“管理后台 -> 系统设置 -> 通知”，填写 Bot Token。
3. 点击“安全绑定”生成一次性绑定码，再点击“打开机器人”。
4. 在机器人会话中发送页面生成的绑定码，然后点击“完成绑定”。
5. 勾选需要通知的邮箱；需要接收未注册地址邮件时，另行勾选“未知收件”。
6. 选择正文显示方式并点击“测试通知”。
7. 测试成功后开启“私聊新邮件通知”，保存设置。
通知会显示发件人、收件邮箱、主题、收件时间、正文和附件名称。Telegram 连接失败不会影响邮局收件，系统会保留通知任务并自动重试。Bot Token 不会在设置页面重新显示；以后修改其他设置时，Token 输入框留空即可保留原值。
一次性绑定码有效期为 10 分钟，只会匹配发送了该绑定码的私聊账号。通知会显示主题、发件人、收件邮箱、服务器收件时间、正文和附件摘要；识别到唯一高可信验证码时，会高亮显示并提供“复制验证码”按钮。外部 IMAP 第一次同步导入的历史邮件不会发送通知，后续新邮件才会通知。
Telegram 连接失败不会影响邮局收件。系统会保留通知任务并自动重试；关闭通知、更换机器人、更换私聊账号或修改通知邮箱范围时，尚未发送的旧任务会被清除。Telegram Bot API 不提供客户端幂等键，因此网络超时发生在 Telegram 已收到请求但服务器未收到响应时，极少数通知可能重复发送。Bot Token 不会在设置页面重新显示；以后修改其他设置时，Token 输入框留空即可保留原值。
邮件通知机器人只负责部署实例的私聊提醒。项目版本频道通知由 GitHub Release 工作流统一发送，不需要在每台服务器重复配置。
docs/ISSUE_LEDGER.md
+27
View File
@@ -40,6 +40,7 @@
| NSX-20260805-003 | 2026-08-05 | 已完成 | 前端/UI/布局稳定性 | 邮箱页与设置页侧栏宽度/边框位置不一致 | S3 | v1.2.14 | 随 v1.2.14 发布 |
| NSX-20260806-004 | 2026-08-06 | 已完成 | 前端/UI/响应式布局 | “全部邮箱”选择器右侧存在复制按钮空白占位 | S3 | v1.2.15 | 随 v1.2.15 发布 |
| NSX-20260806-005 | 2026-08-06 | 已完成 | 后端/通知；前端/设置；部署运维/CI | Telegram 私聊邮件通知与 Release 频道通知 | S3 | v1.2.16 | 随 v1.2.16 发布 |
| NSX-20260806-006 | 2026-08-06 | 已完成 | 后端/通知；邮件核心；前端/设置；质量复核 | Telegram 邮件通知安全、验证码复制和可靠性复核 | S2 | v1.2.17 | 随 v1.2.17 发布 |
## NSX-20260804-001
@@ -225,3 +226,29 @@
| 2026-08-06 | 已配置仓库频道通知密钥并完成频道实发测试；真实 Bot Token 未写入源码。 |
| 2026-08-06 | 完成密钥隐藏、网络错误脱敏、通知失败隔离和 Release 重跑去重复核，状态流转为已完成。 |
| 2026-08-06 | v1.2.16 检查、六个 Docker 镜像、GitHub Release 和 Telegram 频道通知全部成功。 |
## NSX-20260806-006
| 字段 | 内容 |
| --- | --- |
| 编号 | NSX-20260806-006 |
| 日期 | 2026-08-06 |
| 状态 | 已完成 |
| 模块 | 后端/通知；邮件核心；前端/设置；质量复核 |
| 现象 | 原自动获取 Chat ID 可能匹配错误私聊；通知范围默认覆盖全部本地邮箱；关闭后重开可能补发旧任务；收件邮箱、正文编码、长度预算、错误重试和验证码复制不完整。 |
| 根因 | 通知功能首版只覆盖基础发送，没有建立安全配对、显式邮箱范围、发送租约、Telegram 错误分类和统一的 MIME/正文规范化流程。 |
| 实现 | 使用 10 分钟一次性绑定码；通知范围改为显式邮箱和未知收件选择；目的地或范围变化时事务清理旧任务；增加发送租约、Telegram 消息编号、送达后正文清除、400 纯文本降级、429 `retry_after`、401/403 停止重试；新增验证码评分与 `copy_text` 按钮、全消息长度预算、附件清理、GBK 等正文字符集解码和伪 HTML 清理。 |
| 收件链路 | 修正实际收件地址解析；本地互发、未知收件和后续外部 IMAP 新邮件统一通知；首次外部 IMAP 历史导入不通知；收信规则先执行，垃圾邮件和已删除邮件不通知。 |
| 兼容性 | 数据库仅增加可空闲迁移列和设置项；现有 Bot Token 保留且不回传；升级后管理员邮箱自动成为默认通知范围，已开启通知的实例继续包含未知收件。 |
| 目标版本 | v1.2.17 |
| 测试结果 | Telegram 专项测试、Go 全量测试、`go vet`、竞态检测、前端 shadcn 检查和生产构建通过；桌面端与移动端页面视觉验收通过。 |
| 发布状态 | 随 v1.2.17 发布。 |
### 历史
| 时间 | 记录 |
| --- | --- |
| 2026-08-06 | 完成通知全链路复核，确认安全绑定、旧队列、收件地址、来源覆盖、长度预算、错误分类和 MIME 处理问题。 |
| 2026-08-06 | 用户确认继续修改，并明确保留现有机器人 Token。 |
| 2026-08-06 | 完成实现和自动化回归，状态流转为待验收。 |
| 2026-08-06 | 完成桌面端与移动端页面验收及最终回归，状态流转为已完成。 |