Chatto Web Push 通知完全指南：从 VAPID 配置到订阅管理与故障排查

Chatto Web Push 通知完全指南：从 VAPID 配置到订阅管理与故障排查

【免费下载链接】chattoA fully-featured team and group chat application that you can easily selfhost.项目地址: https://gitcode.com/gh_mirrors/chatt/chatto

Chatto 是一款功能完整的团队群聊应用，支持轻松自托管，其内置的Web Push 通知功能可在浏览器标签页关闭时，通过 W3C Web Push 标准把消息推送到你的桌面或已安装的 PWA 设备。本文带你完成 Web Push 订阅管理的全流程：生成 VAPID 密钥、配置 Chatto、启用设备订阅、发送测试通知，并覆盖常见故障排查方法。

为什么需要 Web Push 通知 📬

普通网页通知只能在浏览器打开时生效。启用 Web Push 后，Chatto 的服务器可以直接向浏览器推送服务发送加密消息，实现：

• 标签页关闭仍收到消息：私聊、@提及、回复和关注的线程回复都能触达设备
• 多设备同步订阅：同一账号最多支持 16 个活跃订阅端点
• PWA 徽标与高优先级投递：重要通知可点亮应用图标徽标并唤醒休眠手机

Chatto 的设计原则是"推送只是触发器"：点击推送会跳转到对应房间、线程或私聊，真正的已读/删除状态始终以应用内的持久化通知为准。

Web Push 工作原理（3 步看懂）

1. 服务器生成 VAPID 密钥对：管理员配置一次，服务器即成为唯一有权向用户推送消息的实体，不经过任何第三方中转
2. 浏览器创建订阅：用户在通知设置中授权后，浏览器为每个启用了推送的服务器各创建一个订阅（使用该服务器自己的 VAPID 公钥）
3. 服务器直连推送：有新通知时，服务器直接向浏览器推送端点发送加密负载，点击后直达相关会话

💡 关键认知：Chatto 的推送建立在持久化通知系统之上——只有投递模式为"推送通知"的通知才会产生推送，保证"你在应用通知列表里能找到的，才可能推送给你"。

第一步：生成 VAPID 密钥（最快配置方法）

VAPID（Web Application Server Push 标识）是 Web Push 的行业标准。生成密钥只需一条命令：

npx web-push generate-vapid-keys

也可以在 docker-compose 示例的环境变量模板 中查看 Chatto 提供的 VAPID 配置示例注释。

第二步：在 Chatto 中配置推送（两种等价方式）

Chatto 的推送配置定义在 integrations.go 中，提供 TOML 和环境变量两种配置方式：

TOML 方式：

[push] enabled = true vapid_public_key = "<你的公钥>" vapid_private_key = "<你的私钥>" vapid_subject = "mailto:admin@example.com"

环境变量方式：设置上表对应的CHATTO_PUSH_*变量即可。

⚠️三个重要提示：

• vapid_subject使用mailto:邮箱或 HTTPS 联系 URL，供推送服务商联系管理员
• 私钥必须保密且保持稳定：更换密钥会使已存在的浏览器订阅全部失效
• 未配置 VAPID 时，Chatto 会完全隐藏推送界面，用户不会看到任何推送入口

完整环境变量参考见 environment-variables.mdx。

第三步：用户在设备上启用 Web Push 订阅

管理员配置完成后，成员端的启用流程非常直观：

1. 打开设置 → 通知面板，只要已注册的任一服务器支持推送，面板就会显示"启用推送"操作
2. 点击后弹出浏览器/系统权限提示——点击"允许"即完成授权
3. Chatto 自动为每个支持推送的已认证服务器创建独立订阅并上报存储

授权状态的三种走向（来自 FDR-013 设计规范）：

每次重新打开 Chatto 时，应用会幂等地刷新各服务器存储的订阅——这是自动修复"浏览器在更新中轮换订阅"的关键机制。同一浏览器在多个账号间切换时，推送只投递给最近注册的账号，避免消息串号。

推送订阅的管理能力

Chatto 为订阅管理提供了完整的 API，定义见 push_notifications.proto：

• Subscribe：存储或更新当前用户的浏览器订阅（授权后由前端 pushNotifications.ts 自动调用）
• Unsubscribe：按端点移除订阅，幂等——删除不存在的端点也会成功
• SendTestNotification：向当前账号的所有订阅发送测试通知，每账号 10 秒内限一次

客户端还内置了完善的订阅生命周期保护：

• 退出登录、禁用推送或删除服务器时，会先写入跨标签页暂停标记，再取消注册，防止其他标签页在半途"复活"旧订阅
• 浏览器推送端点过期时（推送服务商返回 404/410），服务器自动清理失效记录
• 删除账号时，所有推送订阅随账号删除事实一并清除，并可跨崩溃重试修复

故障排查清单 🔧

遇到问题时按以下顺序排查，覆盖 90% 的情况：

运维侧自查清单（来自官方指南）：

1. 确认webserver.url设置为公共HTTPS源（推送强制 HTTPS，且不支持重定向、不经过代理）
2. 确认代理保留了 Service Worker 路径可达
3. 各准备一个桌面浏览器 + 一个移动端已安装 PWA 做双端验证
4. 向成员说明：推送按设备生效，且完全自愿开启

核心机制速览（进阶理解）

• 高紧急度投递：用户可见的推送请求 high urgency，让手机推送服务及时唤醒休眠设备；但勿扰或 DND 状态下推送会被抑制
• 发送前重校验：推送发出前服务器会确认通知仍未读、目标消息仍存在、订阅仍归该用户所有——避免"已读消息的幽灵推送"
• 去重策略：某次推送只要任一设备端点接收成功，就不会因另一台设备失败而重试整套设备，防止健康设备重复响铃
• 安全边界：推送端点必须是绝对 HTTPS 公网地址，连接前实时解析并拒绝内网/特殊地址，杜绝 SSRF 风险

完整行为细节可阅读 FDR-013: Web Push Notifications，操作向指南见 notifications-web-push.mdx。

总结 ✅

Chatto 的 Web Push 通知把"自托管"和"标准 Web Push"结合得很干净：管理员一次性配置 VAPID 密钥，成员按设备自愿授权，订阅的创建、刷新、失效清理、账号删除联动全部自动化。记住三件事——密钥保持稳定、HTTPS 全覆盖、iOS 需要安装 PWA——你就能为团队交付一条可靠的消息推送链路。

【免费下载链接】chattoA fully-featured team and group chat application that you can easily selfhost.项目地址: https://gitcode.com/gh_mirrors/chatt/chatto