Notion OAuth 2.0 公开集成(Public Integration)开发与多租户 SaaS 上架实战:从授权换取 Token、AES-256 加密托管、Refresh Token 无感轮换到 Formula 2.0 多租户健康监控闭环

2026 年 11 月 18 日

一、从“单工作区内部脚本”迈向“多租户商业 SaaS 集成” #

许多开发者在初探 Notion API 时,往往会从单一工作区的 Internal Integration(内部集成) 起步:手动生成一个静态 Token,写入 .env 环境变量,再去数据库右上角逐一点击 Connections 绑定。这种方式虽然适合团队自用脚本,但一旦你要面向外部客户发布商业 SaaS 产品(例如 AI 知识库同步器、财务发票自动归档插件、表单收集SaaS、BI 数据看板连接器),内部集成方案就会立刻遇到三大瓶颈:

  1. 无法跨工作区一键授权:客户不可能复制粘贴 32 位数据库 ID 并手动配置开发者的静态密钥;
  2. 缺乏模板零配置初始化能力:新客户授权后,往往需要自动把标准化的 Notion 数据库模板复制到其工作区中;
  3. 多租户凭据安全与 Token 轮换缺失:在数百家企业租户并发调用场景下,需要严格的 OAuth 2.0 密钥加密托管、Token 刷新与异常解绑回收治理。

为此,Notion 官方提供了面向全网用户的 Public Integration(公开集成) 体系。完整的架构链路如下:

[ Notion OAuth 2.0 多租户 SaaS 公开集成与运营监控架构 ]

  ┌─────────────────────┐   1. 点击「Connect to Notion」引导至 /v1/oauth/authorize
  │   外部企业租户用户    ├──────────────────────────────────────────┐
  └─────────────────────┘                                          ▼
                                                    ┌─────────────────────────────┐
                                                    │  Notion OAuth 授权同意页     │
                                                    │  • 选择授权范围与可访问页面   │
                                                    │  • 一键复制预设模板(可选)     │
                                                    └──────────────┬──────────────┘
                                                                   │ 2. 携带 code 回调 Redirect URI
                                                                   ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                        SaaS 多租户中继后端 (Node.js / Edge)                    │
  │  • Basic Auth 换取 access_token、refresh_token 与 duplicated_template_id      │
  │  • 使用 KMS / AES-256-GCM 加密落盘,按 workspace_id 隔离租户队列               │
  │  • 定时扫描即将过期 Token 并执行 grant_type=refresh_token 无感轮换             │
  └──────────────────────────────────────┬───────────────────────────────────────┘
                                         │ 3. 实时回写租户连接状态与配额指标
                                         ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                  Notion 内部 SaaS 运维控制台 (DB_OAuth_Tenants)                │
  │  • 记录租户授权页面数、Token 到期状态、429 限流次数与 Formula 2.0 SLA 预警雷达   │
  └──────────────────────────────────────────────────────────────────────────────┘

二、选型对比:Internal Integration vs Public Integration vs 第三方连接平台 #

在立项开发之前,技术负责人应根据产品形态与客户体量评估接口选型(基础创建流程参阅 创建 Notion API 集成指南):

对比维度 Internal Integration(内部集成) Public Integration(OAuth 2.0 公开集成) Zapier / Make 第三方托管连接器
授权范围与分发方式 仅限开发者所在单一工作区内部使用 支持任意外部 Notion 工作区一键 OAuth 授权接入 依赖用户在第三方平台登录并手动配置 Trigger
授权凭据机制 静态永不过期 secret_xxx Token 标准 access_token + refresh_token 轮换体系 由第三方平台代管 Token,开发者无法直接获取
模板自动克隆能力 不支持(需人工提前建库并授权) 原生支持在授权页一键复制开发者公开模板并直接返回页面 ID 不支持自动注入复杂关联库模板
多租户并发限流隔离 全脚本共享单一 Integration 配额池 按单个授权工作区独立计算限流配额(约 3 req/s) 受限于第三方平台任务配额与轮询延迟(1~15 分钟)
平台审核与合规门槛 免审核,创建即用 需提交 Notion App Directory 审核并配置最小权限(Capabilities) 免开发者审核,但 SaaS 客户会产生额外订阅成本
适用商业场景 企业内部 ERP/OA 同步、自用脚本 独立 SaaS 产品、对外商业插件、多客户托管服务 快速 MVP 验证、无后端研发资源的运营团队

三、分步骤实操:构建生产级 Notion OAuth 2.0 多租户服务端 #

步骤 1:在开发者后台升级 Public Integration 并配置最小权限 #

  1. 登录 Notion Developers 门户(权限配置规范参考 管理 API 集成),新建集成并切换到 Distribution 标签页,开启 Make integration public;
  2. 填写 OAuth Domain & URIs:配置正式环境的 Redirect URI(必须为 HTTPS,本地联调可使用 http://localhost:3000/api/notion/callback),并在页面底部获取 OAuth client ID 与 OAuth client secret;
  3. 遵循最小权限原则勾选 Capabilities:
    • 若插件仅需同步阅读记录或渲染站点(如无头 CMS),严禁勾选 Insert content 或 Update content,仅保留 Read content;
    • 若不需要读取团队成员个人邮箱,关闭 Read user information including email addresses,可大幅降低企业客户的隐私顾虑并提升官方上架审核通过率;
  4. 若希望新客户授权后自动拥有一套预设多维数据库,先将模板页面设置为公开可复制(参考 复制公开页面指南),并在提交授权链接或后台配置中绑定对应模板。

步骤 2:实现 Authorization Code 换取 Token 与 AES-256-GCM 加密存储 #

当客户在你的 SaaS 界面点击绑定 Notion 时,先生成带随机防 CSRF state 参数的授权 URL: https://api.notion.com/v1/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&owner=user&redirect_uri=ENCODED_URI&state=RANDOM_STATE

用户点击允许并挑选授权页面后,Notion 会回调你的服务端并附带一次性 code。注意:换取 Token 必须使用 HTTP Basic Auth(将 client_id:client_secret 进行 Base64 编码放入 Authorization 请求头):

// Node.js 生产级示例:Notion OAuth 2.0 回调换取 Token、解析模板 ID 与 AES-256-GCM 加密托管
import crypto from "node:crypto";

const CLIENT_ID = process.env.NOTION_OAUTH_CLIENT_ID;
const CLIENT_SECRET = process.env.NOTION_OAUTH_CLIENT_SECRET;
const REDIRECT_URI = process.env.NOTION_REDIRECT_URI;
const MASTER_KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY_HEX, "hex"); // 32 bytes

// AES-256-GCM 加密多租户敏感 Token
function encryptToken(plainToken) {
  const iv = crypto.randomBytes(12);
  const cipher = crypto.createCipheriv("aes-256-gcm", MASTER_KEY, iv);
  const encrypted = Buffer.concat([cipher.update(plainToken, "utf8"), cipher.final()]);
  const authTag = cipher.getAuthTag();
  return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`;
}

export async function handleNotionOAuthCallback(req, res) {
  const { code, state, error } = req.query;
  if (error) {
    return res.status(400).json({ error: `用户拒绝授权或回调异常: ${error}` });
  }
  // 生产环境务必校验 session 中的 state 与 req.query.state 一致,防止 CSRF 攻击

  const basicAuth = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
  const tokenResp = await fetch("https://api.notion.com/v1/oauth/token", {
    method: "POST",
    headers: {
      "Authorization": `Basic ${basicAuth}`,
      "Content-Type": "application/json",
      "Notion-Version": "2022-06-28"
    },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code,
      redirect_uri: REDIRECT_URI
    })
  });

  if (!tokenResp.ok) {
    const errBody = await tokenResp.text();
    return res.status(tokenResp.status).json({ error: "Notion Token 换取失败", detail: errBody });
  }

  const data = await tokenResp.json();
  // 核心字段:access_token, refresh_token, workspace_id, workspace_name, bot_id, duplicated_template_id
  const encryptedAccessToken = encryptToken(data.access_token);
  const encryptedRefreshToken = data.refresh_token ? encryptToken(data.refresh_token) : null;

  // 将加密凭据与 duplicated_template_id 存入租户表,随后即可零配置向该模板库写入初始数据
  await saveTenantCredentials({
    workspaceId: data.workspace_id,
    workspaceName: data.workspace_name,
    botId: data.bot_id,
    duplicatedTemplateId: data.duplicated_template_id || null,
    encryptedAccessToken,
    encryptedRefreshToken,
    status: "ACTIVE"
  });

  return res.redirect(`/dashboard/integrations?workspace=${encodeURIComponent(data.workspace_name)}`);
}

步骤 3:实现 Refresh Token 无感轮换与 401 失效自动熔断 #

在多租户长期运行过程中,客户可能在工作区设置中主动撤回权限,或者令牌到达刷新周期。后台调度器在调用前或捕获到 HTTP 401 unauthorized 时,应触发 refresh_token 轮换机制(同时配合 Notion API 速率限制与容错架构 做指数退避):

  1. 使用与首次换取相同的 Basic Auth 请求头向 POST /v1/oauth/token 发送 { "grant_type": "refresh_token", "refresh_token": decryptedRefreshToken };
  2. 收到新令牌后,立即原子覆盖数据库中的加密凭据;
  3. 若刷新接口返回 invalid_grant(通常意味着客户在 Notion 端手动 Disconnect 了你的应用),必须立刻将该租户状态标记为 REVOKED 并停止队列重试,避免无效死循环请求消耗系统资源,并向租户发送邮件提醒重新授权。

四、SaaS 多租户运营控制台数据库属性设计(DB_OAuth_Tenants) #

为了方便产研与客户成功团队在内部 Notion 工作区直观掌控全平台租户的授权健康状况,建议建立以下管理属性(字段属性说明参阅 数据库属性完整说明):

属性名称 Notion 属性类型 数据来源 核心运维与风控作用
租户工作区名称 Title OAuth 回调 workspace_name 唯一识别已授权的 B2B 客户团队名称
Workspace_ID Text OAuth 回调 workspace_id 系统级租户隔离主键,用于关联外部账单与日志
套餐层级 Select SaaS 计费系统同步 Free、Pro、Enterprise,决定 API 并发配额权重
连接状态 Status 网关自动回写 正常授权、Token 待轮换、已主动解绑(Revoked)
上次成功轮换时间 Date (含时间) Refresh 定时任务写入 追踪 OAuth 凭证刷新周期,及时发现长期休眠租户
已授权模板库 ID Text duplicated_template_id 记录一键克隆出的目标母页 ID,校验初始化是否成功
近24小时 429 限流次数 Number 网关埋点聚合 监控单租户突发批量写入导致的 API 拥堵风险
连续失败次数 Number 作业队列统计 连续 401/403 失败次数,用于触发自动熔断

五、Formula 2.0 实战公式:多租户 OAuth 连接健康度与熔断雷达 #

在 DB_OAuth_Tenants 中添加 Formula 属性 租户集成健康雷达,借助 lets()、dateBetween() 与 style()(完整函数参考 Formula 2.0 速查手册),自动识别凭证即将到期、频繁触发限流或已失活解绑的异常租户:

lets(
  status, prop("连接状态"),
  lastRefresh, prop("上次成功轮换时间"),
  rate429, if(empty(prop("近24小时 429 限流次数")), 0, prop("近24小时 429 限流次数")),
  failCount, if(empty(prop("连续失败次数")), 0, prop("连续失败次数")),
  templateId, trim(prop("已授权模板库 ID")),
  daysSinceRefresh, if(empty(lastRefresh), 999, dateBetween(now(), lastRefresh, "days")),

  ifs(
    status == "已主动解绑(Revoked)" || failCount >= 5,
      style("⛔ 已熔断 · 授权失效或连续报错 (" + failCount + "次)", "red", "bold"),
    empty(templateId),
      style("🟡 未完成初始化 · 缺少 duplicated_template_id", "orange", "bold"),
    rate429 >= 20,
      style("🔥 限流拥堵 · 近24h触发 " + rate429 + " 次 429 降级", "red"),
    daysSinceRefresh >= 25,
      style("⏳ 建议主动轮换 · 距上次刷新已 " + daysSinceRefresh + " 天", "orange"),
    style("🟢 运行健康 · OAuth 活跃 (" + daysSinceRefresh + "天前刷新)", "green", "bold")
  )
)

六、官方 App Directory 上架审核清单与排障指南 #

若计划将集成提交至 Notion 官方集成市场(App Directory)获取自然流量,发布前务必逐项核对以下技术与合规清单:

  1. 为什么回调返回 duplicated_template_id 为 null? 只有当用户在 OAuth 授权确认页选择了 Use a template provided by the developer 按钮时,Notion 才会克隆模板并返回该 ID;若用户自行点击 Select pages 手动挑选已有页面,该字段为空。因此后端代码中必须兼容“客户既可能克隆模板,也可能手动绑定已有数据库”的双路径分支;
  2. 避免 invalid_grant 与 redirect_uri 严格匹配报错: 换取 Token 时传递的 redirect_uri 必须与授权第一步 URL 参数及开发者后台填写的地址逐字符完全一致(包括尾部斜杠与协议头),且单个 code 仅在短时间内有效且只允许消费一次;
  3. 官方上架审核必备项: 提供独立的隐私政策(Privacy Policy)与服务条款 URL、清晰的未授权与错误态 UI 提示、至少 3 张高清功能演示截图,并验证当客户在 Notion 端移除单页面授权后,SaaS 端能优雅降级而非整站崩溃(更多接口异常排查参阅 Notion 常见报错与故障诊断手册);
  4. 延伸架构参考:

❓ 常见问题与答疑 (FAQ)

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

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