Notion 与 Better Stack / Statuspage / UptimeRobot 站点可用性监控、故障通告联动与 SLA 复盘闭环实战

2026 年 11 月 21 日

一、为什么 SaaS 运维与客服团队需要将 Uptime 监控与 Notion SLA 台账打通? #

对于对外提供在线服务的 SaaS 产品、API 开放平台与跨境独立站而言,接口宕机、SSL 证书过期或区域 CDN 节点丢包都会直接触发客户工单激增与合同 SLA(服务等级协议)赔付风险。尽管团队通常已经接入了 Better Stack(Uptime)、Atlassian Statuspage 或 UptimeRobot 进行外部合成拨测,但在跨部门协同中依然普遍存在三个断层:

  1. 监控告警、对外公告与客户赔偿台账彼此割裂:监控工具发出报警后,研发在内部排查,客服却不知道该在对外公告页写什么口径;月底大客户要求核对上月可用率是否跌破 99.9% 时,运维只能临时翻找告警邮件手工加总停机分钟数;
  2. 内部排障细节误泄露到外部状态页:为了省事把研发排障文档直接公开给客户查阅,容易暴露服务器拓扑、第三方依赖或内部操作失误细节;
  3. 缺少“错误预算(Error Budget)”前置预警:如果当月 99.9% 可用率对应的 43.2 分钟容错额度已经被消耗掉 80%,团队若无量化看板提示,很容易在后续常规发布中再次触发 SLA 违约。

不同于侧重应用异常堆栈追踪与值班轮替的 Sentry / PagerDuty 线上故障应急响应架构,Better Stack / Statuspage / UptimeRobot 与 Notion 的深度联动聚焦于外部拨测可用率核算、客户状态通告隔离与月度 SLA 履约治理:

方案维度 人工截图记录宕机时长 仅依赖监控平台邮件告警 直接公开内部排障文档 Uptime 监控 + Notion 三表 SLA 闭环(推荐)
故障时长统计精度 依赖人工估测,极易漏算分钟数 仅展示单次告警,缺少跨月聚合 手工填写文本,无法汇总计算 Webhook 自动记录起止时间戳并精确核算分钟
对外公告信息隔离 人工反复确认措辞,响应滞后 无法直接转化为客户沟通话术 高危(易泄露内部堆栈与根因) 脱敏公开摘要字段与内部复盘正文物理隔离
SLA 错误预算管控 月末事后被动算总账 缺少合同 SLA 阈值对比视图 无结构化指标公式支撑 Formula 2.0 实时扣减 Error Budget 并预警
跨部门协同与归档 客服与商务无法及时获取进展 研发以外人员通常没有监控后台权限 缺乏结构化状态流转 Notion 看板同步最新进度,自动关联月度复盘

二、四步搭建“受监控服务 × 故障流水 × 月度 SLA 台账”三表治理架构 #

参照 Notion 企业级数据库架构设计规范 与 关系和汇总官方指南,建议搭建 受监控服务台账(DB_Monitored_Services)、可用性故障流水库(DB_Uptime_Incidents) 与 月度 SLA 核算台账(DB_SLA_Monthly_Ledger) 的三表联动架构。

步骤 1:规范三表核心字段与幂等主键设计 #

为避免监控平台在网络抖动或 Webhook 重试时生成重复故障卡片,故障表必须以 {provider}:incident:{incident_id} 作为幂等主键,月度台账以 {service_slug}:{YYYY-MM} 绑定周期统计:

所属数据库 属性名称 属性类型 工程规范与业务用途
DB_Monitored_Services Service_Name Title 对外服务名称(如 Core OpenAPI Gateway)
DB_Monitored_Services Service_Slug Rich Text 监控平台映射标识(如 api-gateway-prod)
DB_Monitored_Services Target_SLA_Pct Number 合同承诺月度可用率(小数制,如 0.999 代表 99.9%)
DB_Uptime_Incidents Incident_Title Title 故障标题(如 [BetterStack] EU 节点 502 超时)
DB_Uptime_Incidents Incident_Key Rich Text 幂等主键:{provider}:incident:{external_id}
DB_Uptime_Incidents Service_Relation Relation 双向关联至 DB_Monitored_Services
DB_Uptime_Incidents SLA_Ledger_Rel Relation 关联至当月 DB_SLA_Monthly_Ledger 记录
DB_Uptime_Incidents Incident_Status Select Investigating / Identified / Monitoring / Resolved
DB_Uptime_Incidents Started_At Date 外部拨测首次连续失败的 UTC 时间戳
DB_Uptime_Incidents Resolved_At Date 拨测连续恢复健康的 UTC 时间戳
DB_Uptime_Incidents Downtime_Minutes Number 本次计入 SLA 的有效中断分钟数(由网关精确计算)
DB_Uptime_Incidents Public_Notice Rich Text 经脱敏的客户公告口径(与内部复盘正文隔离)
DB_SLA_Monthly_Ledger Ledger_Key Rich Text 幂等主键:{service_slug}:{YYYY-MM}
DB_SLA_Monthly_Ledger Month_Total_Minutes Number 当月总自然分钟数(如 30 天为 43200)

步骤 2:配置 Better Stack / Statuspage / UptimeRobot Webhook 订阅与验签 #

  1. Better Stack Uptime:在 Integrations -> Webhooks 中添加企业网关端点,订阅 incident.started 与 incident.resolved 事件,记录共享签名密钥用于请求来源校验;
  2. Atlassian Statuspage:在 Notifications -> Webhook 配置组件变更回调,将外部状态页组件 ID 映射到 Notion 的 Service_Slug;
  3. UptimeRobot:配置 Alert Contact 为 Webhook 类型,强制以 POST JSON 载荷携带 monitorID、alertType(1 为宕机、2 为恢复)与 alertDateTime。

步骤 3:严格隔离内部排查正文与对外客户状态页口径 #

在企业安全治理中(参考 Notion 公开页面与防泄露指南),切勿把包含内部数据库 IP、报错堆栈的 Notion 故障页直接共享给外部客户。正确做法是:

  • 仅将 Public_Notice(脱敏公告字段,例如“部分欧洲节点响应延迟,正在切换备用流量”)通过网关同步回写 Statuspage 公开状态页;
  • 详细的故障时间线、抓包日志与整改 Action Items 全部保留在受成员权限保护的 Notion 故障页正文中,对外完全不可见。

步骤 4:统一 Notion-Version: 2026-03-11 写入故障预警与月度聚合关联 #

所有 Notion API 调用显式携带请求头 Notion-Version: 2026-03-11(升级规范详见 Notion Views API 与 2026-03-11 实战)。当新故障触发或某服务当月累计中断时长导致错误预算消耗超过 80% 时,网关自动通过 Blocks API position: { type: "start" } 在对应服务台账页顶部置顶红色高亮 callout 警示块,提醒发布负责人立即开启变更冻结。


三、Node.js 生产级 Webhook 网关实战:签名校验、时长结算与 2026-03-11 幂等入库 #

以下 Node.js(Express)生产代码演示如何接收可用性监控 Webhook 回调、验证请求签名、自动查找或初始化当月 DB_SLA_Monthly_Ledger 记录、计算精确停机分钟数,并在高优先级故障发生时通过 Notion-Version: 2026-03-11 完成置顶预警(限流重试机制详见 Notion API 速率限制与容错架构):

// uptime_status_gateway.js — Node.js 18+ Uptime 监控与 Notion SLA 同步网关
const crypto = require('node:crypto');
const express = require('express');

const app = express();
const NOTION_TOKEN = process.env.NOTION_TOKEN;
const SERVICES_DS_ID = process.env.NOTION_SERVICES_DS_ID;
const INCIDENTS_DS_ID = process.env.NOTION_INCIDENTS_DS_ID;
const LEDGER_DS_ID = process.env.NOTION_SLA_LEDGER_DS_ID;
const WEBHOOK_SECRET = process.env.UPTIME_WEBHOOK_SECRET;

app.use('/webhook/uptime', express.raw({ type: 'application/json' }));

function verifySignature(rawBody, signatureHeader) {
  if (!signatureHeader || !WEBHOOK_SECRET) return false;
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
  const provided = signatureHeader.replace(/^sha256=/, '').trim();
  if (expected.length !== provided.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

async function notionRequest(path, method = 'GET', body = null, attempt = 0) {
  const res = await fetch(`https://api.notion.com/v1${path}`, {
    method,
    headers: {
      'Authorization': `Bearer ${NOTION_TOKEN}`,
      'Notion-Version': '2026-03-11',
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  if (res.status === 429 && attempt < 4) {
    const retryAfter = Number(res.headers.get('retry-after') || '1') * 1000;
    const jitter = Math.floor(Math.random() * 250);
    await new Promise((r) => setTimeout(r, retryAfter + 350 * (2 ** attempt) + jitter));
    return notionRequest(path, method, body, attempt + 1);
  }
  if (!res.ok) {
    throw new Error(`Notion API ${res.status}: ${await res.text()}`);
  }
  return res.json();
}

function getMonthTotalMinutes(isoDateStr) {
  const dt = new Date(isoDateStr);
  const year = dt.getUTCFullYear();
  const month = dt.getUTCMonth(); // 0-indexed
  const daysInMonth = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
  return {
    monthKey: `${year}-${String(month + 1).padStart(2, '0')}`,
    totalMinutes: daysInMonth * 24 * 60,
  };
}

async function ensureMonthlyLedger(servicePageId, serviceSlug, startedAtIso) {
  const { monthKey, totalMinutes } = getMonthTotalMinutes(startedAtIso);
  const ledgerKey = `${serviceSlug}:${monthKey}`;

  const existing = await notionRequest(`/data_sources/${LEDGER_DS_ID}/query`, 'POST', {
    filter: { property: 'Ledger_Key', rich_text: { equals: ledgerKey } },
    page_size: 1,
  });
  if (existing.results?.length) {
    return existing.results[0].id;
  }

  const created = await notionRequest('/pages', 'POST', {
    parent: { type: 'data_source_id', data_source_id: LEDGER_DS_ID },
    properties: {
      Name: { title: [{ text: { content: `[${monthKey}] ${serviceSlug} SLA 台账` } }] },
      Ledger_Key: { rich_text: [{ text: { content: ledgerKey } }] },
      Service_Relation: { relation: [{ id: servicePageId }] },
      Month_Total_Minutes: { number: totalMinutes },
    },
  });
  return created.id;
}

async function upsertUptimeIncident(event) {
  const { provider, externalId, serviceSlug, title, status, startedAt, resolvedAt, publicNotice } = event;
  const incidentKey = `${provider}:incident:${externalId}`;

  // 1. 匹配受监控服务主档
  const srvRes = await notionRequest(`/data_sources/${SERVICES_DS_ID}/query`, 'POST', {
    filter: { property: 'Service_Slug', rich_text: { equals: serviceSlug } },
    page_size: 1,
  });
  const servicePage = srvRes.results?.[0];
  if (!servicePage) return { skipped: true, reason: 'unknown_service_slug' };

  const ledgerPageId = await ensureMonthlyLedger(servicePage.id, serviceSlug, startedAt);

  // 2. 计算中断时长(保留两位小数,未恢复时先记 0)
  let downtimeMinutes = 0;
  if (startedAt && resolvedAt) {
    const diffMs = Math.max(0, new Date(resolvedAt).getTime() - new Date(startedAt).getTime());
    downtimeMinutes = Math.round((diffMs / 60000) * 100) / 100;
  }

  const properties = {
    Incident_Title: { title: [{ text: { content: title } }] },
    Incident_Key: { rich_text: [{ text: { content: incidentKey } }] },
    Service_Relation: { relation: [{ id: servicePage.id }] },
    SLA_Ledger_Rel: { relation: [{ id: ledgerPageId }] },
    Incident_Status: { select: { name: status } },
    Started_At: { date: { start: startedAt } },
    Downtime_Minutes: { number: downtimeMinutes },
  };
  if (resolvedAt) {
    properties.Resolved_At = { date: { start: resolvedAt } };
  }
  if (publicNotice) {
    properties.Public_Notice = { rich_text: [{ text: { content: publicNotice.slice(0, 1800) } }] };
  }

  // 3. 按 Incident_Key 幂等查重并写入
  const existing = await notionRequest(`/data_sources/${INCIDENTS_DS_ID}/query`, 'POST', {
    filter: { property: 'Incident_Key', rich_text: { equals: incidentKey } },
    page_size: 1,
  });

  let incidentPageId;
  if (existing.results?.length) {
    incidentPageId = existing.results[0].id;
    await notionRequest(`/pages/${incidentPageId}`, 'PATCH', { properties });
  } else {
    const created = await notionRequest('/pages', 'POST', {
      parent: { type: 'data_source_id', data_source_id: INCIDENTS_DS_ID },
      properties,
    });
    incidentPageId = created.id;

    // 4. 首次建单即在服务主页置顶红色故障状态提示,提醒发布冻结
    if (status !== 'Resolved') {
      await notionRequest(`/blocks/${servicePage.id}/children`, 'PATCH', {
        position: { type: 'start' },
        children: [
          {
            object: 'block',
            type: 'callout',
            callout: {
              icon: { type: 'emoji', emoji: '🚨' },
              color: 'red_background',
              rich_text: [
                {
                  type: 'text',
                  text: {
                    content: `[可用性告警] ${title}(开始于 ${startedAt}),请暂停非紧急变更并核对外部状态页通告口径。`,
                  },
                },
              ],
            },
          },
        ],
      });
    }
  }
  return { incidentPageId, downtimeMinutes };
}

app.post('/webhook/uptime', async (req, res) => {
  const sig = req.headers['x-uptime-signature'];
  if (!verifySignature(req.body, sig)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  try {
    const payload = JSON.parse(req.body.toString('utf8'));
    const result = await upsertUptimeIncident(payload);
    return res.status(200).json({ ok: true, result });
  } catch (err) {
    return res.status(500).json({ error: err.message });
  }
});

app.listen(process.env.PORT || 3000);

四、Formula 2.0 实战:月度可用率核算与 Error Budget 错误预算门禁 #

在 DB_SLA_Monthly_Ledger 中新增 Formula 2.0 属性 可用率与错误预算门禁(完整语法见 Notion Formula 2.0 速查手册 与 官方公式教程)。该公式自动读取当月所有关联故障的中断分钟数(含尚未恢复的进行中故障实时按 dateBetween 估算耗时),对比服务目标 Target_SLA_Pct,实时输出剩余错误预算(Error Budget)与违约红线状态:

lets(
  incidents, prop("Uptime_Incidents"),
  totalMins, if(empty(prop("Month_Total_Minutes")), 43200, prop("Month_Total_Minutes")),
  targetSla, if(empty(prop("Service_Relation").first()), 0.999, prop("Service_Relation").first().prop("Target_SLA_Pct")),
  allowedBudgetMins, round((1 - targetSla) * totalMins * 10) / 10,

  closedDown, incidents
    .filter(current.prop("Incident_Status") == "Resolved")
    .map(current.prop("Downtime_Minutes"))
    .sum(),
  activeDown, incidents
    .filter(current.prop("Incident_Status") != "Resolved")
    .map(dateBetween(now(), current.prop("Started_At"), "minutes"))
    .sum(),

  usedMins, round((closedDown + activeDown) * 10) / 10,
  remainMins, round((allowedBudgetMins - usedMins) * 10) / 10,
  actualSlaPct, round(((totalMins - usedMins) / totalMins) * 100000) / 1000,
  hasActive, incidents.some(current.prop("Incident_Status") != "Resolved"),

  ifs(
    hasActive,
      style("🔥 故障中断进行中 · 本月已累计宕机 " + format(usedMins) + "m(可用率 " + format(actualSlaPct) + "%)", "red", "bold", "red_background"),
    remainMins < 0,
      style("🚨 SLA 违约(可用率 " + format(actualSlaPct) + "%):已透支预算 " + format(abs(remainMins)) + " 分钟", "red", "bold", "red_background"),
    allowedBudgetMins > 0 && remainMins / allowedBudgetMins <= 0.2,
      style("⚠️ 错误预算余量不足 20%(余 " + format(remainMins) + "m):建议冻结高风险发布", "orange", "bold"),
    style("🟢 可用性达标(" + format(actualSlaPct) + "%)· 剩余预算 " + format(remainMins) + " 分钟", "green", "bold")
  )
)

五、站点可用性监控集成 Notion 常见故障排查 #

在落地 Uptime 监控与 Notion SLA 闭环的过程中,SRE 团队高频遇到的四类问题及根治策略如下(更多报错诊断见 Notion 常见报错与故障诊断手册):

  1. 多个区域的探针同时报警,导致同一场故障的停机分钟数被翻倍累加:例如美国与欧洲节点同时触发超时,生成两张故障卡后月度停机分钟翻倍。解法:在监控工具中开启多节点协同判定(如至少 2 个区域连续失败 2 次才触发一个 Incident),并在 Notion 网关中按主故障 ID 聚合,避免同一事故重复计入 Downtime_Minutes。
  2. Webhook 恢复回调偶发丢失,导致 Formula 一直把历史故障按进行中计算:如果 Resolved 回调因网络抖动未送达,Formula 中的 dateBetween(now(), Started_At, "minutes") 会不断膨胀。解法:配置每小时定时兜底巡检任务,拉取 Better Stack / UptimeRobot 过去 24 小时已关闭的事件状态并补刷回 Notion;Webhook 处理流程参照 Notion Integration Webhooks 实时订阅实战。
  3. 跨月跨天故障导致月度 SLA 归属失真:如 11 月 30 日 23:50 开始、次月 1 日 00:15 恢复的故障,全部计入某一个月会导致当月预算误判。解法:在结算脚本中判断 Started_At 与 Resolved_At 是否跨 UTC 月份边界,若跨月则按自然月零点拆分为两条分别归属于当月与次月 Ledger_Key 的分段耗时记录。
  4. 短时间高频状态抖动(Flapping)触发 Notion API 429 限流:当上游网络出现间歇性丢包时,短时间内反复发来 Down / Up 回调。解法:在网关层引入 60 秒防抖去重窗口,并对所有写库请求接入带 Retry-After 退避的异步队列(架构参考 Notion API 速率限制与容错架构)。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。