ntfy 渐进式 Web 应用（PWA）完整指南：安装、后台推送与自托管配置

ntfy 渐进式 Web 应用PWA完整指南安装、后台推送与自托管配置【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy导读ntfy 本身没有原生桌面客户端但它以 Progressive Web AppPWA 目录可以同时安装到桌面端和移动端。安装后ntfy Web 应用会拥有独立的启动器入口Windows 快捷方式、macOS 应用、Linux 启动器图标、iOS 主屏幕图标、Android 启动器图标、独立窗口、推送通知以及带未读消息计数的应用角标。本文基于 docs/subscribe/pwa.md 讲解 PWA 的安装方式、后台通知机制并结合仓库源码说明其工作原埋与自托管场景下的 Web Push 配置要求。读完本文你将掌握各平台安装 ntfy PWA 的具体步骤、后台通知在各浏览器的可用性差异以及如何为自己的服务器正确配置 Web Push 以支持 PWA。注意本文所描述的行为基于当前仓库快照的源码与文档部分浏览器兼容性信息以官方文档为准。什么是 ntfy PWA为什么没有原生桌面应用也能获得原生体验ntfy 官方不提供原生桌面客户端而是把 Web 应用做成 PWA从而获得接近原生的能力。安装 PWA 后用户可以获得以下能力对应 docs/subscribe/pwa.md 中的描述独立启动入口Windows 上的快捷方式、macOS 上的应用、Linux 上的启动器快捷方式、iOS 主屏幕图标、Android 启动器图标独立窗口以独立应用窗口运行而非浏览器标签页推送通知基于 Web Push 的后台通知详见下文后台通知一节未读角标应用图标上显示未读通知数量通过setAppBadgeAPI 实现见 web/public/sw.js。从源码结构看PWA 的构成要素在仓库中有完整对应Web 应用入口 web/index.html 中通过link relmanifest href/manifest.webmanifest /声明 Web App Manifestweb/index.html并预加载了苹果图标、mask icon、favicon 等资源服务工作者Service Worker由 web/public/sw.js 实现负责预缓存、Web Push 消息处理、通知点击处理与应用角标更新Service Worker 注册逻辑在 web/src/registerSW.js每 60 分钟检查一次更新intervalMS 60 * 60 * 1000见 web/src/registerSW.js生产环境的 Manifest 由 Go 服务器动态生成路由定义在 server/server.gowebAppManifestPath /manifest.webmanifest且只有启用 Web Push 时才提供服务见 server/server.go通过ensureWebPushEnabled中间件包裹。浏览器与平台支持矩阵Web 应用安装的官方支持情况如下细节可参考 caniuse 的 Web App Manifest 兼容表浏览器支持平台ChromeAndroid、Windows、Linux、macOSSafariiOS 16.4、macOS 14FirefoxAndroid以及通过 PWA for Firefox 扩展 支持 Windows/LinuxEdgeWindows需要特别强调的是自托管服务器必须配置 Web PushPWA 才能正常工作docs/subscribe/pwa.md 原文说明。这是因为 PWA 的独立窗口体验依赖 Manifest 与 Service Worker而这两者在 server/server.go 中都受到ensureWebPushEnabled保护。因此本文最后专门给出自托管场景的 Web Push 完整配置方案。安装 ntfy PWA各平台分步指南Chrome 桌面端Windows / Linux / macOS在 Chrome 中打开 ntfy Web 应用点击地址栏的安装应用install app图标即可安装并注册该 Web 应用。安装完成后应用会出现在你的应用抽屉app drawer中Safari on macOSmacOS Sonoma 14在 macOS 上的 Safari 中点击共享Share菜单然后选择Add to Dock添加到程序坞。此功能要求 macOS Sonoma14或更高版本Chrome / Firefox on AndroidChrome on Android有两种安装方式点击屏幕底部的添加到主屏幕Add to Home Screen横幅在菜单中选择安装应用Install app然后在弹出窗口中点击安装Install。安装完成后应用会出现在应用抽屉和主屏幕上Firefox on Android在菜单中选择安装Install然后在弹出窗口中点击添加Add即可在主屏幕添加图标Safari on iOS在 iOS 的 Safari 中点击共享Share菜单然后点击添加到主屏幕Add to Home Screen后台通知Background Notifications机制与使用规则安装 PWA 后后台通知默认开启且不可关闭根据 docs/subscribe/pwa.md 的说明通过 Web Push 的后台通知在应用安装后默认开启且无法关闭否则通知无法可靠投递。如果你不想收到某些话题的通知可以静音mute对应话题。从源码看静音机制由 web/src/app/SubscriptionManager.js 管理Web Push 话题列表查询时排除了mutedUntil 0的话题见 web/src/app/SubscriptionManager.js 与 web/src/app/SubscriptionManager.js并通过setMutedUntil写入静音截止时间见 web/src/app/SubscriptionManager.js。也就是说静音一个话题后该话题的新消息将不再触发后台推送。桌面端与移动端的接收差异桌面端通常需要保持浏览器或 Web 应用打开才能收到通知但 ntfy 标签页本身不需要处于前台不要求激活状态移动端不需要打开 Web 应用即可收到通知。更细粒度的行为差异浏览器运行 / 未运行时的通知能力在 docs/subscribe/web.md 中有详细对照表要点如下浏览器平台浏览器运行中浏览器未运行限制条件Chrome桌面✅❌—Firefox桌面✅❌—Edge桌面✅❌—Opera桌面✅❌—Safari桌面✅✅需 Safari 16.1、macOS 13 VenturaChromeAndroid✅✅—FirefoxAndroid✅✅—SafariiOS⚠️⚠️需 iOS 16.4仅当应用添加到主屏幕使用率低于 1% 的浏览器未列出更多信息参考 Push API 兼容性。后台通知的底层原理Service Worker 处理 Web Push后台通知之所以能在 Web 应用未打开时工作核心在于浏览器会唤醒注册的 Service Worker 来处理推送事件。ntfy 的服务工作者 web/public/sw.js 实现了完整的处理链路接收推送push事件监听器解析数据后交给handlePush分发web/public/sw.js事件路由根据消息事件类型message/message_delete/message_clear及订阅过期事件subscription_expiring分别处理web/public/sw.js展示通知立即调用showNotification展示系统通知并将消息写入 IndexedDBdb.notifications同时更新角标数量setAppBadgeweb/public/sw.js播放声音由于 Service Worker 无法播放声音它会通过BroadcastChannel向正在运行的 Web 应用广播消息由应用侧负责播放提示音web/public/sw.js 与 web/public/sw.js通知点击notificationclick事件处理用户点击通知与操作按钮view / http 动作支持聚焦已打开的话题页、新开窗口以及执行 HTTP 动作web/public/sw.js 与 web/public/sw.js。从 web/src/app/SubscriptionManager.js 的注释可以推断Web Push 话题列表会排除内部话题与被静音的话题且必须将mutedUntil纳入 Dexie 的where()查询否则实时查询不会响应静音状态的变更——这解释了静音即停止后台推送这一行为背后的实现约束。自托管服务器的前置条件若你自托管 ntfy 服务器需要先满足以下前提PWA 与后台通知才能工作HTTPSWeb 应用必须通过 HTTPS 提供服务且需要有效证书——Service Worker 不会在证书不受信任的来源上运行见 docs/config.md启用 Web Push否则/manifest.webmanifest与 Service Worker 均不可用见 server/server.go同源限制Web Push 只支持同一台服务器——你不能在主题位于其他服务器时通过当前 Web 应用订阅 Web Push这是 Push API 不允许同一来源存在多个推送服务器的限制所致见 docs/config.md。为自托管服务器配置 Web PushPWA 工作的前提Web Push 允许 ntfy 在 Web 应用甚至浏览器取决于平台关闭时也能收到推送通知。启用后用户可以在 Web 应用的Settings设置标签页中为话题开启后台通知。此后 ntfy 会把发布的消息转发到浏览器提供的推送端点如fcm.googleapis.com再转发给浏览器见 docs/config.md。配置 Web Push 需要三样东西VAPID 密钥对通过ntfy webpush keys命令生成订阅数据库用于跟踪浏览器的订阅端点管理员邮箱发送给推送服务提供方。生成 VAPID 密钥首先在服务器上运行$ ntfy webpush keys Web Push keys generated. ...写入配置文件然后把生成的密钥与相关配置填入server.ymlweb-push-public-key: AA1234BBCCddvveekaabcdfqwertyuiopasdfghjklzxcvbnm1234567890 web-push-private-key: AA2BB1234567890abcdefzxcvbnm1234567890 web-push-file: /var/cache/ntfy/webpush.db web-push-email-address: sysadminexample.com各参数含义如下对应 docs/config.md参数说明web-push-public-key生成的 VAPID 公钥web-push-private-key生成的 VAPID 私钥web-push-file存储浏览器订阅端点的数据库文件设置database-url时不需要web-push-email-address发送给推送服务提供方的管理员邮箱web-push-startup-queries启动时对订阅数据库执行的 SQL 查询可选web-push-expiry-warning-duration未使用订阅发送过期警告前的时长默认55dweb-push-expiry-duration未使用订阅过期被删除前的时长默认60d这些参数也可以通过环境变量如NTFY_WEB_PUSH_PUBLIC_KEY、NTFY_WEB_PUSH_FILE等或命令行参数如--web-push-public-key等设置完整清单见 docs/config.md 的参数表。订阅存储与过期机制web-push-file用于在本地 SQLite 数据库中存储推送订阅如果设置了database-urlPostgreSQL订阅则存储在 PostgreSQL 中此时不需要web-push-file。未使用的订阅会在 55 天后收到警告60 天后自动过期默认值。如果网关返回错误例如用户取消订阅后的410 Gone订阅也会被自动移除见 docs/config.md。Web 应用会在启动时以及定时刷新订阅但web-push-file必须跨重启持久化如果该文件被删除或丢失所有未打开的 Web 应用将无法收到新的 Web Push 通知直到用户重新打开应用。两个重要的运维提醒不要随意更换公钥/私钥对浏览器只允许每个来源绑定一个服务器身份公钥如果更换密钥对客户端将无法再通过 Web Push 订阅直到用户手动清除通知权限见 docs/config.md订阅过期警告如果应用超过一周未打开后台通知会被暂停重新打开应用即可恢复暂停前会收到警告通知见 docs/subscribe/web.md。总结ntfy 通过 PWA 形式补齐了无原生桌面应用的短板让用户在 Windows、macOS、Linux、Android、iOS 上都能获得带独立窗口、推送通知与未读角标的类原生体验。安装方式因平台而异Chrome 安装图标、Safari 的 Add to Dock / Add to Home Screen、Firefox 菜单安装等但底层依赖统一的 Web App Manifest、Service Worker 与 Web Push 三件套——其中前两者的提供在 server/server.go 中与 Web Push 的启用状态强绑定因此自托管用户务必先按 docs/config.md 的指引生成 VAPID 密钥、配置订阅数据库与管理员邮箱。安装后后台通知默认开启且不可关闭但可以通过静音话题来控制通知范围桌面端一般需要浏览器或应用保持打开移动端则无需打开应用即可接收。【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考