企业官网建设流程全解析

Automatisch 接入 Notion 完整指南：OAuth 集成创建、连接配置与源码级原理解析

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch

本指南以 Automatisch 官方文档 Notion 连接配置说明 为骨架，完整讲解在 Notion 侧创建 OAuth 集成、在 Automatisch 侧完成连接建立的每一个步骤，并结合 Notion 应用后端源码 揭示 OAuth 授权、凭证校验与连接复用的底层原理。读完本文，你将能够在自己的 Automatisch 实例中独立完成 Notion 连接配置，并理解连接建立后的请求是如何携带令牌访问 Notion API 的。

准备工作：你需要什么

在开始配置之前，请确认你具备以下条件：

• 一个可登录的 Notion 账户，且对目标 Workspace 拥有创建集成的权限；
• 一个已成功安装并运行的 Automatisch 实例（本地开发环境或自托管部署均可）；
• 浏览器可以正常访问 Notion 的集成管理页面（notion.so/my-integrations）与你的 Automatisch Web 界面。

:::info 本文以 Automatisch 仓库内 Notion 应用模块（packages/backend/src/apps/notion）为事实依据。若你使用的 Automatisch 版本较新，界面文案可能略有差异，但配置流程与参数含义保持一致。 :::

第一步：在 Notion 创建 OAuth Integration

1. 打开 Notion 的 My integrations 页面，点击页面上的New integration按钮，进入集成创建流程。
2. 在Name字段填写你的集成名称（例如Automatisch），点击Submit按钮提交。
3. 通过侧边栏进入Capabilities页面。
4. 在User capabilities区域勾选Read user information without email addresses选项，然后保存更改。该权限用于 Automatisch 在建立连接后读取当前用户信息（详见后文"凭证校验"一节）。
5. 通过侧边栏进入Distribution页面。
6. 勾选Make this integration public复选框，使集成对 OAuth 流程公开可用。
7. 在Organization information区域填写必要的组织信息字段（组织名、网站等，按 Notion 表单要求填写即可）。
8. 将 Automatisch 提供的OAuth Redirect URL粘贴到 Notion 的Redirect URIs字段中。
9. 点击Submit按钮提交。
10. 在弹出的确认对话框中点击Continue，确认将集成设为公开。

第 6、10 步的"公开化"处理是 Notion OAuth 集成的硬性要求：只有公开的集成才能参与 OAuth 授权码流程；私有的集成只能通过 Notion 侧手动授权的方式使用，无法由 Automatisch 发起授权跳转。

第二步：在 Automatisch 中填写 OAuth 凭证

回到 Automatisch Web 界面，在添加 Notion 连接的对话框（{你的实例域名}/app/notion/connections/add）中，你会看到三个字段。它们由后端 auth 字段定义 声明：

操作顺序：

1. 复制 Automatisch 显示框内的OAuth Redirect URL（可点击复制图标），粘贴到 Notion 的 Redirect URIs 输入框中。
2. 回到 Notion 集成页面，复制OAuth client ID和OAuth client secret两个值。
3. 在 Automatisch 中分别粘贴为Client ID与Client Secret。
4. 点击Submit按钮提交。

凭证字段的源码级说明

从源码结构看，这三个字段具备如下特性，理解它们有助于排查连接问题：

• OAuth Redirect URL 是只读字段（readOnly: true），其值由模板变量{WEB_APP_URL}在部署时动态渲染。也就是说，只要你的 Automatisch 实例外部访问地址确定，该回调地址就是固定的——Notion 侧配置的 Redirect URI 必须与它逐字符完全一致（包括https与结尾路径），否则 OAuth 授权会因回调地址不匹配而失败。
• Client ID 与 Client Secret 都是必填且可编辑的普通字段（required: true,readOnly: false）。Automatisch 会将其加密存储并用于后续的 OAuth token 交换。

第三步：完成授权与连接建立

填写完凭证并点击提交后，Automatisch 会自动触发 OAuth 授权码流程，整个过程由后端 generate-auth-url.js 与 verify-credentials.js 两个函数驱动：

1. 生成授权 URL

Automatisch 将用户重定向到 Notion 授权端点：

https://api.notion.com/v1/oauth/authorize?client_id=<Client ID>&redirect_uri=<OAuth Redirect URL>&response_type=code&owner=user

从源码看，generateAuthUrl会从 auth 字段定义中取出oAuthRedirectUrl的实际值，连同用户填写的clientId一起拼装查询参数，其中response_type固定为code、owner固定为user（即按"用户级授权"方式申请访问）。client_secret在此阶段不会出现在 URL 中——它只在下一步的 token 交换中作为 Basic 认证凭据使用。

2. Notion 用户授权

在 Notion 的授权页面选择目标 Workspace 并确认授权。Notion 会携带授权码code重定向回redirect_uri。

3. 用授权码换取 Access Token

verifyCredentials收到code后，向 Notion 的 token 端点发起POST /v1/oauth/token：

POST https://api.notion.com/v1/oauth/token Authorization: Basic base64("<Client ID>:<Client Secret>") Content-Type: application/json { "redirect_uri": "<OAuth Redirect URL>", "code": "<authorization_code>", "grant_type": "authorization_code" }

注意源码中的两个细节：

• Basic 认证头由clientId + ':' + clientSecret的 Base64 编码构成，因此填错任意一个都会导致 token 交换失败；
• 该请求设置了additionalProperties.skipAddingAuthHeader: true，让全局的addAuthHeader拦截器跳过此请求——这是授权码换 token与携带令牌访问业务 API的关键区分，避免了在 Basic 认证请求上重复附加 Bearer 头。

4. 凭证保存与用户信息回显

换取成功后，Automatisch 将access_token、bot_id、workspace_id、workspace_name、owner等字段存入该连接，并调用 get-current-user.js 请求GET /v1/users/{owner.user.id}获取当前用户名称，最终将连接显示名设为当前用户名 @ Workspace 名（见 verify-credentials.js）。这就是连接列表中能直接看到"某某用户 @ 某某 Workspace"的原因。

完成以上流程后，连接即建立成功。之后便可在 Automatisch 中开始使用 Notion 连接来构建自动化流程。

连接建立后：请求如何携带身份

每次 Automatisch 代表该连接调用 Notion API 时，都会经过 index.js 中声明的beforeRequest钩子：

• add-auth-header.js：若连接中已保存accessToken，自动为请求附加Authorization: Bearer <accessToken>头；这也是上面提到的 token 交换请求通过skipAddingAuthHeader跳过该钩子的原因。
• add-notion-version-header.js：为每次请求附加Notion-Version: 2022-06-28头。Notion API 要求所有请求显式声明 API 版本，该值是当前应用实现所使用的版本。

这两个钩子保证了连接建立后，任何 Notion 动作（Actions）和触发器（Triggers）都能以最小配置直接访问 Notion API，无需在每个步骤中重复填写令牌。

连接可用性检查

Automatisch 在后台会周期性检查已保存连接的可用性，其逻辑位于 is-still-verified.js：通过调用getCurrentUser请求当前用户信息，只要返回的用户id存在，就认为连接依然有效。这意味着：

• 如果集成在 Notion 侧被删除、或用户撤销了授权导致 token 失效，该检查会失败，Automatisch 会标记该连接为异常并提示重新连接；
• 该检查只依赖"能取到用户信息"这一事实，属于轻量级校验。

连接建立后可以做什么

完成连接配置后，你就可以在 Automatisch 流程编辑器中选择 Notion 应用，使用以下能力（参见 docs/pages/apps/notion）：

触发器（Triggers）

• New database items：当所选数据库新增条目时触发；
• Updated database items：当所选数据库中的条目发生更新时触发。

动作（Actions）

• Create database item：在数据库中创建条目；
• Create page：在父页面下创建子页面；
• Find database item：按属性在数据库中查找条目；
• Update database item：更新数据库中的条目。

这些触发器与动作的具体实现分别位于 triggers 与 actions 目录，读者可以按需深入阅读源码。

常见问题排查清单

• 授权页面报 redirect_uri 不匹配：检查 Notion 侧 Redirect URI 与 Automatisch 显示框中的 OAuth Redirect URL 是否逐字符一致（注意协议、域名、端口与结尾斜杠）。
• token 交换阶段报 401/403：确认 Client ID 与 Client Secret 无误，且集成已在 Distribution 页面设置为 public。
• 授权时未显示目标 Workspace：确认当前 Notion 账户对目标 Workspace 拥有创建集成的权限，且集成尚未被删除。
• 连接显示异常或需要重新连接：通常是 token 失效所致，可重新走一遍授权流程；同时确认集成在 Notion 侧仍处于公开状态且 Capabilities 中勾选了读取用户信息权限。

小结

本文完整覆盖了 Automatisch 连接 Notion 的全部配置步骤：从 Notion 侧创建公开 OAuth 集成、复制 Client ID / Client Secret，到在 Automatisch 中填写 OAuth Redirect URL 并完成授权换取令牌。结合 Notion 应用源码 可以看出，整个连接机制围绕"授权码换令牌 → 保存连接凭证 → 自动附加 Bearer 头与版本头"展开，理解这条链路后，你不仅能顺利配置 Notion 连接，也能举一反三地理解 Automatisch 中其他 OAuth 应用的连接原理。

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch