Chatto Web Push 通知完全指南从 VAPID 配置到订阅管理与故障排查【免费下载链接】chattoA fully-featured team and group chat application that you can easily selfhost.项目地址: https://gitcode.com/gh_mirrors/chatt/chattoChatto 是一款功能完整的团队群聊应用支持轻松自托管其内置的Web Push 通知功能可在浏览器标签页关闭时通过 W3C Web Push 标准把消息推送到你的桌面或已安装的 PWA 设备。本文带你完成 Web Push 订阅管理的全流程生成 VAPID 密钥、配置 Chatto、启用设备订阅、发送测试通知并覆盖常见故障排查方法。为什么需要 Web Push 通知 普通网页通知只能在浏览器打开时生效。启用 Web Push 后Chatto 的服务器可以直接向浏览器推送服务发送加密消息实现标签页关闭仍收到消息私聊、提及、回复和关注的线程回复都能触达设备多设备同步订阅同一账号最多支持 16 个活跃订阅端点PWA 徽标与高优先级投递重要通知可点亮应用图标徽标并唤醒休眠手机Chatto 的设计原则是推送只是触发器点击推送会跳转到对应房间、线程或私聊真正的已读/删除状态始终以应用内的持久化通知为准。Web Push 工作原理3 步看懂服务器生成 VAPID 密钥对管理员配置一次服务器即成为唯一有权向用户推送消息的实体不经过任何第三方中转浏览器创建订阅用户在通知设置中授权后浏览器为每个启用了推送的服务器各创建一个订阅使用该服务器自己的 VAPID 公钥服务器直连推送有新通知时服务器直接向浏览器推送端点发送加密负载点击后直达相关会话 关键认知Chatto 的推送建立在持久化通知系统之上——只有投递模式为推送通知的通知才会产生推送保证你在应用通知列表里能找到的才可能推送给你。第一步生成 VAPID 密钥最快配置方法VAPIDWeb Application Server Push 标识是 Web Push 的行业标准。生成密钥只需一条命令npx web-push generate-vapid-keys也可以在 docker-compose 示例的环境变量模板 中查看 Chatto 提供的 VAPID 配置示例注释。第二步在 Chatto 中配置推送两种等价方式Chatto 的推送配置定义在 integrations.go 中提供 TOML 和环境变量两种配置方式配置项TOML环境变量启用开关push.enabledCHATTO_PUSH_ENABLEDVAPID 公钥push.vapid_public_keyCHATTO_PUSH_VAPID_PUBLIC_KEYVAPID 私钥push.vapid_private_keyCHATTO_PUSH_VAPID_PRIVATE_KEY联系人push.vapid_subjectCHATTO_PUSH_VAPID_SUBJECTTOML 方式[push] enabled true vapid_public_key 你的公钥 vapid_private_key 你的私钥 vapid_subject mailto:adminexample.com环境变量方式设置上表对应的CHATTO_PUSH_*变量即可。⚠️三个重要提示vapid_subject使用mailto:邮箱或 HTTPS 联系 URL供推送服务商联系管理员私钥必须保密且保持稳定更换密钥会使已存在的浏览器订阅全部失效未配置 VAPID 时Chatto 会完全隐藏推送界面用户不会看到任何推送入口完整环境变量参考见 environment-variables.mdx。第三步用户在设备上启用 Web Push 订阅管理员配置完成后成员端的启用流程非常直观打开设置 → 通知面板只要已注册的任一服务器支持推送面板就会显示启用推送操作点击后弹出浏览器/系统权限提示——点击允许即完成授权Chatto 自动为每个支持推送的已认证服务器创建独立订阅并上报存储授权状态的三种走向来自 FDR-013 设计规范用户操作后续行为点击允许立即为各服务器创建订阅忽略/关闭提示启用推送按钮保持可见随时可再试明确拒绝按钮隐藏需到浏览器或系统设置中重新开启每次重新打开 Chatto 时应用会幂等地刷新各服务器存储的订阅——这是自动修复浏览器在更新中轮换订阅的关键机制。同一浏览器在多个账号间切换时推送只投递给最近注册的账号避免消息串号。推送订阅的管理能力Chatto 为订阅管理提供了完整的 API定义见 push_notifications.protoSubscribe存储或更新当前用户的浏览器订阅授权后由前端 pushNotifications.ts 自动调用Unsubscribe按端点移除订阅幂等——删除不存在的端点也会成功SendTestNotification向当前账号的所有订阅发送测试通知每账号 10 秒内限一次客户端还内置了完善的订阅生命周期保护退出登录、禁用推送或删除服务器时会先写入跨标签页暂停标记再取消注册防止其他标签页在半途复活旧订阅浏览器推送端点过期时推送服务商返回 404/410服务器自动清理失效记录删除账号时所有推送订阅随账号删除事实一并清除并可跨崩溃重试修复故障排查清单 遇到问题时按以下顺序排查覆盖 90% 的情况现象可能原因解决方法通知设置里看不到推送选项服务器未配置 VAPID 密钥检查push.enabled和三个vapid_*项是否齐全并重启授权成功但收不到推送测试账号权限受限用普通成员账号测试而不是仅用所有者账号桌面能收、手机收不到iOS 未安装为 PWAiOS/iPadOS 仅支持添加到主屏幕的 Web AppSafari 标签页可能收不到推送跳转到错误域名自定义域名未加入允许来源将推送目标源加入webserver.allowed_origins偶尔收不到重要消息处于勿扰模式或通知策略为 Badge勿扰不丢弃通知但抑制推送确认对应行的策略至少为推送通知更换密钥后推送全失效密钥轮换使旧订阅作废属预期行为用户重新打开 Chatto 会触发订阅刷新无需手动处理运维侧自查清单来自官方指南确认webserver.url设置为公共HTTPS源推送强制 HTTPS且不支持重定向、不经过代理确认代理保留了 Service Worker 路径可达各准备一个桌面浏览器 一个移动端已安装 PWA 做双端验证向成员说明推送按设备生效且完全自愿开启核心机制速览进阶理解高紧急度投递用户可见的推送请求 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考