SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-10-31

自托管 n8n 连接 Gmail:反向代理与七天失效

了解如何在反向代理后的自托管 n8n 中配置 Gmail OAuth 回调 URL,并解决 Google External 应用处于 Testing 状态时,Gmail 令牌 7 天后失效的问题。

如何将 Gmail 连接到自托管 n8n

要将 Gmail 连接到自托管 n8n,请创建一个类型为 Web application 的 Google OAuth(开放授权)客户端,然后将 n8n 的回调 URL 粘贴到其中。如果服务器位于反向代理之后,只有在将 N8N_EDITOR_BASE_URL 设置为公网 https:// 地址后,该回调 URL 才是正确的。之后还需要处理七天限制。处于 Testing 状态的 External Google 应用在您登录一周后会失去 Gmail 访问权限。

本指南从使用 Docker 和 HTTPS 在 VPS 上自托管 n8n结束的位置开始。您可以通过 https:// 地址打开编辑器,容器前方运行着反向代理。本指南中的所有内容均已针对 2.41.6 版 n8n 进行验证,该版本于 2026 年 10 月 2 日发布,为 2 系列的稳定版本。Google 相关信息已于 2026 年 10 月 4 日根据 Google 文档进行验证。

为什么回调 URL 是自托管配置中的问题

OAuth 通过重定向工作。n8n 将您的浏览器发送到 Google,您批准访问请求。然后,Google 将您的浏览器连同一次性代码发送回 n8n 服务器上的回调 URL。Google 只会重定向到已在 OAuth 客户端中注册的地址。两者必须完全匹配:协议、主机、端口和路径都必须一致。

n8n 的 Google 凭据文档展示了一个回调示例:http://localhost:5678/rest/oauth2-credential/callback。文档没有说明反向代理。未配置其他选项时,自托管 n8n 会显示同一个地址,因此全新安装会将该地址发送给 Google。

在 n8n 2.41.6 中,回调来自 packages/cli/src/services/url.service.ts。实例基础 URL 按以下顺序选择:

  1. 如果已设置,则使用 N8N_EDITOR_BASE_URL。
  2. 否则使用 webhook 基础 URL:先使用 N8N_WEBHOOK_URL,再使用旧变量 WEBHOOK_URL。
  3. 否则根据 N8N_PROTOCOL、N8N_HOST、N8N_PORT 和 N8N_PATH 构建 URL。

然后,n8n 会在末尾添加 /rest/oauth2-credential/callback。同一个函数为两个位置提供 URL:凭据对话框中的重定向 URL,以及 n8n 发送给 Google 的 redirect_uri。对话框中显示的内容,就是 Google 收到的内容。

第 3 条规则容易导致问题。只有当端口是协议的标准端口时,它才会删除端口:http 使用 80,或 https 使用 443。在代理后面,n8n 仍监听 5678。因此,N8N_PROTOCOL=https 加上 N8N_HOST=n8n.example.com 会生成 https://n8n.example.com:5678/rest/oauth2-credential/callback。您的代理不会在该端口上响应,Google 中也没有登记这个 URL。

任一变量都可以修正对话框中的 URL。许多 compose 文件只设置 WEBHOOK_URL。这种情况下,回调已经正确,因为实例基础 URL 会回退到该变量。仍应设置 N8N_EDITOR_BASE_URL。它具有更高优先级,并明确声明您要使用的地址。如果同时设置了两个变量且值不同,n8n 会使用编辑器 URL 作为回调。另请注意,2.41.6 的源代码将 WEBHOOK_URL 标记为已弃用,并用 N8N_WEBHOOK_URL 替代它。

在 compose 文件中设置公网 URL

将公网地址添加到 n8n 服务的 environment 块中,并使用您自己的域名。如果 n8n 运行在子路径下(例如 https://example.com/n8n/),请同时包含该路径。

services:
  n8n:
    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https
      - N8N_EDITOR_BASE_URL=https://n8n.example.com/
      - WEBHOOK_URL=https://n8n.example.com/

使用 up -d 应用更改,不要使用 restart。docker compose restart 只会使用旧环境变量重启现有容器,因此会静默忽略更改。docker compose up -d 会读取更改后的配置并重新创建容器。

docker compose up -d
docker compose exec n8n printenv N8N_EDITOR_BASE_URL

第二条命令应输出您的 https:// 地址。如果服务名称不是 n8n,请使用 compose 文件中的服务名称。末尾带斜杠也可以,因为 n8n 会在添加回调路径前将其删除。

现在打开 n8n,并新建一个 Gmail OAuth2 API 类型的凭据。查看 OAuth Redirect URL 字段。该字段应显示 https://n8n.example.com/rest/oauth2-credential/callback,其中示例域名应替换为您的域名。如果仍显示 localhost 或 :5678,说明容器没有获取到该变量。请先修复此问题,再配置 Google,因为后续每一步都会复制此值。

第 1 步:创建 Google Cloud 项目

使用将拥有该应用的账号登录 Google Cloud 控制台。创建一个便于以后识别的新项目,例如 n8n-gmail。继续之前,确认控制台顶部的项目选择器显示的是新项目。下面的所有设置都属于当前选定的项目,因此很容易配置错误的项目。

Google 经常更改控制台页面的名称。因此,下面的步骤描述的是需要填写的字段,而不是按钮的确切标签。

步骤 2:启用 Gmail API

打开项目的 API 库,搜索 Gmail API 并启用它。如果跳过此步骤,登录仍会成功。随后首次调用 Gmail 时会失败,并显示以 Gmail API has not been used in project 开头的错误,提示您启用该 API。

步骤 3:设置同意页面、品牌信息和受众群体

此页面以前称为 OAuth 同意屏幕。自 2026 年 10 月起,Google 将其拆分为多个部分,品牌信息和受众群体也分别位于不同页面。需要填写以下字段:

  • 应用名称和用户支持电子邮件。只有您能看到这些内容,因此保持简单即可。
  • 受众群体或用户类型:Internal 或 External。只有当项目属于 Google Workspace 组织时,才会显示 Internal;它会将登录范围限制为该组织的成员。个人 @gmail.com 账号必须使用 External。
  • 开发者联系电子邮件。Google 会将项目相关通知发送到此地址。
  • 获授权的域名,位于品牌信息部分。添加运行 n8n 的域名,例如 example.com。
  • 测试用户,位于受众群体部分。添加要连接的 Gmail 地址。处于 Testing 状态的 External 应用会拒绝不在此列表中的所有用户,其登录会以 access_denied 错误结束。

暂时将发布状态保留为 Testing。下面的七天部分会说明何时更改此状态。

第 4 步:创建 Web 应用 OAuth 客户端

在凭据或客户端部分,创建一个 OAuth 客户端 ID,并填写以下字段:

  • 应用类型:Web 应用。桌面客户端没有重定向 URI 字段,因此无法使用 n8n 的回调地址。
  • 名称:任意名称,例如 n8n。
  • 授权的重定向 URI:粘贴 n8n 模态框中的 OAuth Redirect URL,内容必须完全一致。
  • 授权的 JavaScript 来源:留空。这是另一份列表,将回调地址粘贴到这里不会生效。

保存客户端。Google 会显示客户端 ID 和客户端密钥。将两者粘贴到 n8n 凭据中,然后选择 使用 Google 登录。Google 会显示应用的授权页面,确认授予 Gmail 访问权限。此时,n8n 模态框中应显示该账号已连接。保存凭据。

redirect_uri_mismatch 的表现

如果 n8n 模态框中的 URL 与 Google 客户端中的 URL 哪怕只相差一个字符,Google 也会停止登录。页面标题为 Access blocked: This app's request is invalid,并显示以下文本:

Error 400: redirect_uri_mismatch

You can't sign in to this app because it doesn't comply with Google's OAuth 2.0 policy.

If you're the app developer, register the redirect URI in the Google Cloud Console.

打开该页面上的请求详情。其中会显示 n8n 实际发送的 redirect_uri= 值。将其与 OAuth 客户端中的列表进行比较。常见差异包括:注册的是 https,但实际发送的是 http;多了一个 :5678;使用 localhost 代替域名;以及缺少子路径。如果发送的值错误,请修正 n8n 环境。如果注册的值错误,请修正 Google 客户端并等待几分钟。Google 警告称,客户端更改可能需要一段时间才能生效。

Google 可能接受重定向,但浏览器仍会进入 502 或 404 页面。这表示回调请求没有到达 n8n。这是代理配置问题,nginx 反向代理配置如何将请求传递给应用会解释可能导致该问题的每条指令。

第 5 步:构建会触发的 Gmail 触发器

创建一个工作流,并使用新凭据添加 Gmail Trigger 节点。按以下方式配置:

  • Event:Message Received。这是唯一可用的事件。
  • Poll Times:测试期间设置为每分钟一次。
  • Read Status 筛选器:保留为仅处理未读邮件。
  • Search 筛选器:可选。它接受 Gmail 搜索语法,例如 from:billing@example.com。

Gmail Trigger 会轮询。它按照你设置的计划向 Gmail 请求新邮件,因此 Google 无需访问服务器上的 webhook。它只需要有效的令牌。

给自己发送一封测试邮件,然后在节点中获取测试事件。输出应显示邮件 ID 及其标头。启用工作流,使编辑器关闭后仍会执行轮询。根据版本不同,该控件可能标记为 Active 或 Publish。再发送一封邮件,并等待一个轮询周期。执行列表应显示一次成功运行。

如果工作流之后停止工作,请检查两个问题。令牌是否仍然有效?容器是否仍在运行?下一节将介绍令牌。容器停止有其自身的原因,自托管 n8n 持续离线的原因将对此进行说明。

七天期限:Gmail 工作流为何一周后失效

大多数自托管 Gmail 配置都会遇到此问题,而且在问题发生前不会收到任何警告。n8n 的 Google 文档明确说明:对于发布状态为 Testing、用户类型为 External 的 Google Cloud 应用,“授权和令牌会在 7 天后过期”。Google 的受众文档也说明了同样的规则:“测试用户的授权会在同意授权后的 7 天过期。”

问题会这样发生。登录时,Google 会向 n8n 提供一个短期访问令牌和一个刷新令牌。旧访问令牌过期后,n8n 使用刷新令牌获取新的访问令牌。对于处于 Testing 状态的 External 应用,刷新令牌本身会在授权同意 7 天后过期。第 7 天时,刷新请求失败,Google 返回 invalid_grant。此后,每次 Gmail 轮询都会失败。

有两点容易让人意外。计时从选择 Sign in with Google 时开始,而不是从工作流上次运行时开始。再次登录只会重新获得 7 天期限。如果设置完成约一周后,执行失败信息中出现 invalid_grant,原因就是这个 7 天限制。

请根据所拥有的账号选择一种解决方式。

方式 A:将 External 应用发布到生产环境

在受众页面中,将发布状态从 Testing 更改为 In production。更改后签发的刷新令牌不再受 7 天限制。然后在 n8n 中再次选择 Sign in with Google。当前持有的令牌是在 Testing 规则下签发的,因此必须获取新令牌。

发布应用不等于完成验证。n8n 默认请求的作用域包括 https://mail.google.com/ 和 https://www.googleapis.com/auth/gmail.modify。Google 将两者都归类为受限作用域。使用受限作用域的公开应用需要完成验证和安全评估。Google 还列出了例外情况,我们已于 2026 年 10 月 4 日核对。适用于自托管 n8n 的例外是个人使用。如果应用“供个人使用(少于 100 个用户)”,您和用户可以继续使用它,无需完成验证。

您看到的将是未验证应用页面。登录时,Google 会显示 Google hasn't verified this app。打开该页面上的高级选项,然后继续访问应用。对于仅供您自己使用的应用,这是正常现象,并且只会在有人授予授权时显示。Google 将显示此页面的应用限制为总计 100 个新用户,而个人使用的 n8n 通常远达不到这个数量。

生产环境中的令牌仍可能停止工作。如果您在 Google Account 设置中移除该应用的访问权限,Google 会停止接受其刷新令牌。包含 Gmail 作用域的刷新令牌也会在账号密码更改后停止工作。连续 6 个月未使用的令牌会过期。对于同一个客户端,Google 每个账号最多保留 100 个有效刷新令牌,因此如果您多次登录,最早的令牌会被丢弃。每种情况最终都会产生相同的 invalid_grant 错误,解决方法都是重新登录。

方式 B:在 Google Workspace 域中使用 Internal 应用

如果 Gmail 地址属于 Google Workspace 域,请在该组织内创建项目,并将受众设置为 Internal。Google 仅对处于 Testing 状态的 External 应用应用 7 天规则,因此 Internal 应用不受影响。Google 的验证例外也涵盖内部使用。仅供“Google Workspace 或 Cloud Identity 组织中的人员使用”的应用不会显示未验证应用页面,也不受用户数量限制。

只有在项目位于该组织内,且登录人员是该组织成员时,此方式才有效。个人 @gmail.com 地址无法使用 Internal 应用。

方式 C:使用应用专用密码的 IMAP 和 SMTP

您也可以完全跳过 OAuth。Gmail 支持使用 IMAP(Internet Message Access Protocol)读取邮件,使用 SMTP(Simple Mail Transfer Protocol)发送邮件。自 2025 年 1 月起,Gmail 始终启用 IMAP,因此无需更改设置。

使用应用专用密码登录。这是 Google 为单个应用生成的 16 位代码。账号必须启用 2-Step Verification。启用了 Advanced Protection 的账号,以及工作或学校账号,都无法使用应用专用密码。如果 2-Step Verification 仅使用安全密钥,也无法使用应用专用密码。

在 n8n 中,使用 Email Trigger (IMAP) 节点和 IMAP 凭据读取邮件。主机使用 imap.gmail.com,端口使用 993,并启用 SSL/TLS。使用 Send Email 节点和 SMTP 凭据发送邮件。主机使用 smtp.gmail.com,端口使用 465,并启用 SSL/TLS。用户名是完整的 Gmail 地址,密码是去掉空格的应用专用密码。

此方式也有实际代价。应用专用密码可以访问整个邮箱,Google 的帮助文档也说明不建议使用应用专用密码。更改 Google 密码后,Google 会撤销所有应用专用密码,因此必须创建新密码,工作流才能恢复。您还会失去 Gmail Trigger 的专用过滤功能,并且 IMAP 会将 Gmail 标签显示为普通文件夹。

Outlook:Microsoft Entra 应用使用相同的回调

Microsoft 邮件服务使用相同的模式。n8n 根据同一个实例基础 URL 构建所有 OAuth2 回调。Gmail 凭据显示正确的重定向 URL 后,Microsoft 凭据也会显示相同的 URL。

n8n 的 Microsoft 凭据文档介绍了注册流程。打开 应用注册页面。该页面属于 Microsoft Entra。创建一个注册并设置名称。对于支持的帐户类型,n8n 文档选择“Accounts in any organizational directory (Any Azure AD directory - Multi-tenant) and personal Microsoft accounts”。将重定向 URI 平台设置为 Web,然后粘贴 n8n 的 OAuth Redirect URL。将 Application (client) ID 复制到 n8n 的 client ID 字段。进入 certificates and secrets 部分创建 client secret,然后将其值复制到 n8n。如果 Microsoft 帐户由组织管理,管理员可能必须先批准该应用。n8n 文档到此为止,本指南也到此为止。

应选择哪种方式?

对于个人 Gmail 帐户,将 External 应用发布到生产环境,并在首次使用时继续通过“未验证应用”页面。对于 Workspace 邮箱,使用 Internal 应用。无法创建 Google Cloud 项目时,或工作流只需读取和发送邮件时,选择 IMAP 并使用应用专用密码。

以上功能均不需要付费套餐。Gmail 节点、IMAP 节点和 OAuth 凭据都包含在 n8n 免费的自托管 Community Edition 中。如果您仍在评估 n8n 是否适合您的工作,n8n 的用途及其工作流运行方式将介绍基础知识。

FAQ

为什么我的 n8n Gmail 凭据显示 localhost 重定向 URL?

n8n 根据 N8N_EDITOR_BASE_URL 构建 OAuth 重定向 URL。如果未设置该值,n8n 会使用 webhook URL。如果两者都未设置,n8n 会根据 N8N_PROTOCOL、N8N_HOST、N8N_PORT 和 N8N_PATH 构建 URL。如果这些值都未设置,结果就是 http://localhost:5678/rest/oauth2-credential/callback。在容器环境中,将 N8N_EDITOR_BASE_URL 设置为公开的 https:// 地址。然后使用 docker compose up -d 重新创建容器,再次打开该凭据。

为什么我的 n8n Gmail 触发器在 7 天后停止工作?

您的 Google 应用属于 External 类型,且仍处于 Testing 状态。用户同意授权后,Google 会在 7 天后使测试用户的授权过期。此时,n8n 的 refresh token 将停止工作,每次轮询都会失败并显示 invalid_grant。重新登录只能重新获得 7 天的使用期限。对于个人 Gmail 账户,长期解决方案是将应用发布到 production,然后再次登录。在 Google Workspace 域中,使用 Internal 应用可完全避免此限制。

使用自托管 n8n 配置 Gmail 是否需要通过 Google 验证?

个人使用不需要。n8n 请求受限的 Gmail 权限范围,使用受限权限范围的公开应用需要通过验证。对于用户少于 100 人的个人使用应用,Google 提供豁免。登录时,您会看到“Google 尚未验证此应用”页面,但可以跳过该页面,继续使用您自己的应用。

Gmail 触发器是否需要公开的 webhook URL?

不需要。Gmail Trigger 按 Poll Times 中设置的计划轮询 Gmail,因此 Google 不会调用您的服务器。OAuth 回调是浏览器重定向。登录时,您自己的浏览器必须能够访问回调 URL,并且该 URL 必须与 Google 客户端中注册的 URL 一致。

这篇文章对您有帮助吗?

#n8n#gmail#google-oauth#自托管#automation