本文由 Huifer 撰写,TanStack Ship 的独立开发者与维护者。自 2022 年起,我一直在 TanStack Start + Cloudflare Workers + D1 上运行 email automation,而 push 是我最后才接入的渠道——因为触发器与数据模型的工作完全相同,但 push 的投递规则毫不留情。这篇文章就是我现在动手前必看的那套 schema 与工作流设计。凡是缺乏可信测量的地方,我会直说,而不是引用一个数字。
已验证来源: TanStack Start 文档 · web.dev push notifications · Cloudflare Workers 文档 · MDN Push API · RFC 8030 — Web Push protocol · RFC 8292 — VAPID
最后更新:2026-10-26 · 更新日志
Push Notification Automation:触发器工作流 + 数据模型
Push notification automation 是这样一个系统:它把一个事件——一次注册、一次状态变更、一次定时触发、一段沉默——变成一条经过排队、去重、权限校验的 web push 消息。它由三层构成:触发器模型、工作流序列引擎和通知数据模型。本文将定义每一层,并给出实现它们的 D1 schema 与 Workers 代码。它写给正在决定自己的 SaaS 技术栈必须原生处理哪些能力的独立创始人与全栈开发者——如果你在评估 boilerplate 而不是从零开始构建,看看哪些 SaaS 模板包含了这套能力。
如果你搜索的是 "push notification automation trigger workflow sequence",你真正要找的是这三层之间的接线方式——那我们就先把它们精确地命名出来。
TL;DR
- Push notification automation = 触发器 + 序列 + 数据模型。跳过任何一层,你都会得到重复推送或静默丢失。
- 先设计触发器类别(用户操作、状态变更、定时、不活跃),再把它们编码为去重事件。
- 幂等性是整个游戏的关键:每个 (enrollment, step) 上的唯一约束,能胜过我遇到过的所有重试 bug。
- Web push 本身已经标准化,发送免费——真正的成本是状态管理,不是供应商费用。
定义(供引用): Push notification automation 是一种实践:从定义好的触发器出发,把 web push 消息经由序列化工作流发出,背后由一个记录订阅、注册与投递结果的数据模型支撑,从而让每条通知恰好触发一次。
关于数据来源的一点说明:在我们的 Search Console 数据(用户自报,28 天窗口)中,这个查询簇目前把我们的 email marketing automation 指南排在平均位置 5.4,展示 32 次——这意味着读者带着对 push 答案的期待来到那篇 email 文章。本文就是那个答案。两个渠道共享触发器与数据模型层;只有投递不同。
触发器模型:启动一条 push 的五类事件
触发器是任何宣告"这个用户现在应该收到一条通知"的东西。在生产环境中,我发现让触发器直接对发送器说话是一个错误。每个触发器都应该先写入一条事件,并携带去重键,而所有下游逻辑只读事件——绝不读原始 webhook 或原始 cron tick。这一点对 push 比对 email 更重要,因为 push 投递是即时且用户可见的;一条重复推送就是你用户通知中心里的一个 UX bug。
| 触发器类别 | 何时触发 | 示例 | 去重键 | 典型失败模式 |
|---|---|---|---|---|
| 用户操作 | 产品内的显式事件 | 发布了一个版本,完成了一项任务 | event_id | webhook 重放时重复注册 |
| 状态变更 | 某行越过阈值 | 发票逾期,配额超限 | entity_id + 状态 | 状态抖动导致每天重复触发 |
| 定时 | Cron tick | 周一 09:00 的摘要 | cron 槽位 + 用户 | 重叠的 cron 运行导致重复发送 |
| 不活跃 | 某个事件的缺席 | 连续 14 天没有会话 | user_id + 间隔窗口 | 用户已经回来了,通知才触发 |
| 迟到/补录 | 事件乱序到达 | 离线期间订阅续期 | 供应商去重 ID | 静默丢失或重复发送 |
右列的失败模式是结构性分析,不是实测基准——它们正是我的序列表设计出来要使之不可能发生的状态。Webhook 重复并不是假设:Stripe 自己的 webhook 文档告诉你,端点必须容忍同一事件被投递不止一次,所以你的触发器层必须在注册任何人之前先去重。
工作流序列引擎:步骤、延迟与幂等性
序列(email 圈子说的 drip campaign)是一个带延迟的有序步骤列表。工作流是更大的机器:触发器 → 条件 → 一条或多条序列。**注册(enrollment)**是工作流内部每个用户的状态机:属于哪条序列、走到哪一步、下一步何时到期。
我把序列定义为数据而不是代码,因为我每周都要编辑它们,为了改一句文案就重新部署一个 Worker 是坏味道:
// sequences.ts — push notification automation sequence definition
export type SequenceStep = {
index: number
offsetMinutes: number // delay from enrollment time
templateId: string
requireAll: string[] // conditions that must still hold when the step fires
}
export const trialEndingSequence: SequenceStep[] = [
{ index: 0, offsetMinutes: 0, templateId: "trial-day-2", requireAll: ["trial_active"] },
{ index: 1, offsetMinutes: 60 * 48, templateId: "trial-last-day", requireAll: ["trial_active"] },
{ index: 2, offsetMinutes: 60 * 24, templateId: "trial-expired", requireAll: ["trial_expired"] },
]
为什么序列会在重试时出错
运行器本身很无聊:查询 next_due_at <= now 的注册,检查 requireAll 条件,发送,推进游标。不无聊的是平台重试你时会发生什么。Cloudflare Cron Triggers 可能再次调用你的 handler,而任何 HTTP 发送都可能在 push 服务已经接收消息之后才超时。没有硬性护栏,你就会把"试用今天到期"这条 push 发两遍——而在别人的通知托盘里没有撤销按钮。
我的规则:**投递行就是锁。**向 notification_deliveries 插入一行,主键为 (enrollment_id, step_index, endpoint),并在同一个 D1 batch 中推进游标——D1 batch 作为单个事务运行,所以两个写入要么都提交,要么都不提交。重试到来时,主键插入失败,代码路径把这一点视为"已经发过",然后推进游标。一个约束替代了一整类分布式系统的焦虑。
通知数据模型:一个能扛住重试的 D1 schema
这是人们跳过、然后重写两遍的那一层。五张表承载整个系统:
-- SQLite/D1 schema for push notification automation
CREATE TABLE push_subscriptions (
user_id TEXT NOT NULL,
endpoint TEXT PRIMARY KEY,
p256dh TEXT NOT NULL,
auth TEXT NOT NULL,
user_agent TEXT,
created_at INTEGER NOT NULL,
last_seen_at INTEGER
);
CREATE TABLE sequences (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
trigger_event TEXT NOT NULL, -- e.g. 'trial.started'
active INTEGER NOT NULL DEFAULT 1
);
CREATE TABLE sequence_steps (
sequence_id TEXT NOT NULL,
"index" INTEGER NOT NULL, -- 'index' is a reserved word in SQLite: quote it
offset_minutes INTEGER NOT NULL,
template_id TEXT NOT NULL,
require_all TEXT NOT NULL, -- JSON array of condition keys
PRIMARY KEY (sequence_id, "index")
);
CREATE TABLE sequence_enrollments (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
sequence_id TEXT NOT NULL,
cursor INTEGER NOT NULL DEFAULT 0,
next_due_at INTEGER NOT NULL,
status TEXT NOT NULL, -- active | done | exited
UNIQUE (user_id, sequence_id) -- one enrollment per user per sequence
);
CREATE TABLE notification_deliveries (
enrollment_id TEXT NOT NULL,
step_index INTEGER NOT NULL,
endpoint TEXT NOT NULL,
sent_at INTEGER NOT NULL,
push_status INTEGER, -- HTTP status returned by the push service
PRIMARY KEY (enrollment_id, step_index, endpoint) -- the idempotency lock
);
每张表为你换来什么:
push_subscriptions— 浏览器授权的 endpoint 加上加密密钥(Push API 的订阅载荷)。一个用户可以有多行——笔记本和手机是不同的 endpoint。sequences/sequence_steps— 以数据形式存在的工作流定义,所以 drip campaign 无需部署即可编辑。sequence_enrollments— 每用户状态机。UNIQUE (user_id, sequence_id)约束让重放的触发器事件变成空操作,而不是第二次注册。notification_deliveries— 审计日志与幂等锁合一。当你问"这条发过吗?",答案是一次查询,不是一次猜测。
注意 sequence_steps 中 "index" 的引号:index 在 SQLite 中是保留字,不加引号的列会让你的 migration 失败。我是用最烦人的方式学到这一点的。
投递:VAPID、service worker 与 Workers cron 运行器
投递层是整个系统中标准化程度最高的部分,这是好消息:Web Push 协议(RFC 8030)定义了服务器如何把消息交给 push 服务,VAPID(RFC 8292)定义了你的服务器如何表明身份,而载荷加密有自己的 RFC,中介永远看不到明文。web.dev push overview 讲述浏览器侧:service worker 接收 push 并展示通知。一次成功的提交返回 HTTP 201;当你超过速率限制时,push 服务可能返回 429,这正是我的运行器每分钟批量处理 100 条注册而不是一次倾倒整个队列的原因。
有两个平台现实需要围绕它们做设计,两者都有文档:在 iOS 与 iPadOS 16.4 及更高版本上,web push 只对用户已添加到主屏幕的网站生效,见 Apple 的 web push 文档——所以预期 iOS 的注册量只是桌面端的一个零头,并且不要把它当成 bug。而且订阅会过期:当 push 服务回答 404 或 410 时,Push API 规范将该订阅描述为已消失,所以删掉那一行,让重新订阅自然发生。
// worker/cron.ts — Cloudflare Workers Cron Trigger (runs every minute)
import { sendNotification } from "web-push"; // VAPID-signed per RFC 8292
export default {
async scheduled(_controller: unknown, env: Env): Promise<void> {
const now = Date.now();
const due = await env.DB.prepare(`
SELECT e.id, e.user_id, e.sequence_id, e.cursor,
s.template_id, s.require_all
FROM sequence_enrollments e
JOIN sequence_steps s
ON s.sequence_id = e.sequence_id AND s."index" = e.cursor
WHERE e.status = 'active' AND e.next_due_at <= ?
LIMIT 100
`).bind(now).all();
for (const row of due.results) {
const sub = await env.DB.prepare(
"SELECT endpoint, p256dh, auth FROM push_subscriptions WHERE user_id = ?"
).bind(row.user_id).first();
if (!sub) { await markExited(env, row.id); continue; }
try {
await sendNotification(
{ endpoint: sub.endpoint, keys: { p256dh: sub.p256dh, auth: sub.auth } },
JSON.stringify({ templateId: row.template_id, seq: row.sequence_id }),
{ vapidDetails: {
subject: "mailto:you@example.com",
publicKey: env.VAPID_PUBLIC_KEY,
privateKey: env.VAPID_PRIVATE_KEY,
}},
);
await recordDeliveryAndAdvance(env, row.id, row.cursor, sub.endpoint, 201);
} catch (err: any) {
if (err?.statusCode === 404 || err?.statusCode === 410) {
// Subscription gone — prune; the user re-subscribes when they return
await env.DB.prepare("DELETE FROM push_subscriptions WHERE endpoint = ?")
.bind(sub.endpoint).run();
}
// Anything else: leave the cursor in place; the next cron run retries
}
}
},
};
一条诚实的部署说明:流行的 web-push 包是面向 Node 的。在 Workers 上,我在 nodejs_compat 下运行它;另一种选择是一个更小的 VAPID 与加密辅助库。为这个细节预留一个晚上——它是整个技术栈中唯一一处文档之间互相矛盾的地方。
你的技术栈包含这个吗?买家决策清单
本文支持的买家决策是这样的:**push automation 的大部分是状态管理,不是发送。**发送本身是约 40 行标准化代码。其余的一切——权限流程、事件去重、注册状态、重试、清理——才是 SaaS boilerplate 要么内置、要么逼你自己构建的能力。在选择技术栈之前,检查这些:
- 一个在用户手势时(而不是页面加载时)请求通知权限的权限提示流程
- VAPID 密钥管理作为环境配置,而不是硬编码值
- 触发器事件写入去重的事件表(不只是内存)
- 一个具备幂等投递与重试行为的序列运行器
- 一份可以查询的投递日志,以及对过期订阅的清理
- 服务器端的 cron/定时执行,让序列在浏览器关闭后仍然存活
如果你的当前技术栈在其中三项或以上不合格,你就差一次集成就要重写这篇文章。这正是值得在承诺之前评估的取舍:浏览 TanStack 模板看看哪个 starter 包含通知基础设施,然后在你确认该能力确实存在之后,再查看模板定价与许可条款。许可价格是次要的,状态层是否开箱即用才是首要的。
局限性、披露,以及我没有测量的东西
**披露:**我维护 TanStack Ship,所以指向我自己模板的链接构成重大利益关联,在此明确声明。我从本文引用的第三方服务中不赚取任何收入,文中也没有任何联盟链接。
诚实地标注的局限性:
- *Measured:*本文没有任何一项。我刻意不从自己的资产中引用任何打开率、点击率或投递百分比——我没有一个敢公开辩护的测量体系,而一个编造出来的数字比没有数字更糟。在你期待一个基准的地方,把它当作 [needs source]。
- *User-provided:*Search Console 数据(28 天内展示 32 次,平均位置 5.4)来自我们自己的资产,描述的是发现行为,不是通知性能。
- *Documented/structural:*RFC 行为、iOS 主屏幕要求、201/429/404/410 状态语义、D1 事务保证,均已在上方引用一手文档。
- Estimated:"预期 iOS 注册量只是桌面端的零头"这一说法是基于主屏幕安装要求的设计假设,不是实测比例。
- 这套 schema 是为 SQLite/D1 语义设计的;移植到 Postgres 会改变引号规则与事务包装,但不改变模型本身。
FAQ:push notification automation
什么是 push notification automation?
它是一个事件驱动系统,无需人工发送即可发出 web push 消息:触发器(用户操作、状态变更、定时或不活跃)创建一条去重事件,工作流把用户注册进一条序列,数据模型跟踪每次注册与投递,让每条通知恰好触发一次。
Push drip campaign 与 email drip campaign 有什么不同?
触发器与数据模型层几乎完全相同;不同在投递。Push 受权限约束、生命周期短,最适合"试用即将到期""配额超限"这类时间敏感的状态,而 email 承载长内容,并且不依赖浏览器会话。大多数产品让两个渠道跑在同一条事件总线上。
Web push notification 在 iOS 上能用吗?
能用,自 iOS 与 iPadOS 16.4 起——但只对用户已添加到主屏幕的 web 应用生效,而且用户必须在安装之后授予通知权限。桌面版 Chrome、Edge 和 Firefox 对普通网站支持 web push,所以 iOS 是那个约束,不是标准本身。
决策,一句话
Push notification automation 是一个状态管理问题:把触发器建模为去重事件,把注册状态放进你的数据库,并用每步一把的锁让投递幂等。具体的下一步行动:预览模板——它们构建于 TanStack Start + Cloudflare Workers + D1 之上——然后决定是自己构建这层通知能力,还是从一个已经内置它的起点开始。