Push Notification Automation:触发器工作流 + 数据模型

为 SaaS 构建 push notification automation:拆解五类触发器、工作流序列引擎与记录每次注册和投递的 D1 数据模型,用 (enrollment, step) 幂等锁消灭重复推送与静默丢失,附完整 SQLite/D1 schema 与 Cloudflare Workers cron 代码。

Huifer
Huifer
October 26, 202610 min read
其他语言:Deutsch · English

本文由 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_idwebhook 重放时重复注册
状态变更某行越过阈值发票逾期,配额超限entity_id + 状态状态抖动导致每天重复触发
定时Cron tick周一 09:00 的摘要cron 槽位 + 用户重叠的 cron 运行导致重复发送
不活跃某个事件的缺席连续 14 天没有会话user_id + 间隔窗口用户已经回来了,通知才触发
迟到/补录事件乱序到达离线期间订阅续期供应商去重 ID静默丢失或重复发送

右列的失败模式是结构性分析,不是实测基准——它们正是我的序列表设计出来要使之不可能发生的状态。Webhook 重复并不是假设:Stripe 自己的 webhook 文档告诉你,端点必须容忍同一事件被投递不止一次,所以你的触发器层必须在注册任何人之前先去重。

工作流序列引擎:步骤、延迟与幂等性

序列(email 圈子说的 drip campaign)是一个带延迟的有序步骤列表。工作流是更大的机器:触发器 → 条件 → 一条或多条序列。**注册(enrollment)**是工作流内部每个用户的状态机:属于哪条序列、走到哪一步、下一步何时到期。

我把序列定义为数据而不是代码,因为我每周都要编辑它们,为了改一句文案就重新部署一个 Worker 是坏味道:

ts
// 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

这是人们跳过、然后重写两遍的那一层。五张表承载整个系统:

sql
-- 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 规范将该订阅描述为已消失,所以删掉那一行,让重新订阅自然发生。

ts
// 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 之上——然后决定是自己构建这层通知能力,还是从一个已经内置它的起点开始。