自托管 n8n 连接 Gmail 与 OAuth 回调配置
了解如何在反向代理后的自托管 n8n 中连接 Gmail,修正 OAuth 回调 URL,并避免 Google External 应用处于 Testing 状态时的七天令牌过期限制。
如何将 Gmail 连接到自托管 n8n
要将 Gmail 连接到自托管 n8n,请创建一个类型为 Web application 的 Google OAuth(开放授权)客户端,然后将 n8n 的回调 URL 粘贴到其中。如果服务器位于反向代理后面,请将 N8N_EDITOR_BASE_URL 设置为公开的 https:// 地址,或正确配置 webhook 基础 URL,以便 n8n 将其用于回调。七天限制取决于应用的受众群体和发布状态。处于 Testing 状态的 External Google 应用会在您登录一周后失去 Gmail 访问权限。
本指南接续使用 Docker 和 HTTPS 在 VPS 上自托管 n8n。您的编辑器通过 https:// 地址打开,容器前面运行着反向代理。本指南中的内容已根据 2026 年 10 月 2 日发布的稳定版本 n8n 2.41.6 进行验证。Google 相关信息已根据 Google 于 2026 年 11 月 19 日的文档进行验证。
为什么回调 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 按以下顺序选择:
- 如果已设置,则使用
N8N_EDITOR_BASE_URL。 - 否则使用 webhook 基础 URL:先使用
N8N_WEBHOOK_URL,再使用旧变量WEBHOOK_URL。 - 否则根据
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 年 11 月起,Google 将其拆分为多个部分,品牌信息和受众分别位于独立页面。需要填写以下字段:
- 应用名称和用户支持电子邮件地址。这些信息会显示在 Google 的同意页面中,用于标识应用及其支持联系人。
- 受众或用户类型:Internal、External 或 Personal。只有当项目属于 Google Cloud 组织时,才会显示 Internal;它会将登录限制为该组织的成员。个人
@gmail.com账号可以选择 Personal,仅供创建者使用;也可以选择 External,用于多用户应用。 - 开发者联系电子邮件地址。Google 会将项目相关通知发送到此地址。
- 授权域名,位于品牌信息部分。添加运行 n8n 的域名,例如
example.com。 - 测试用户,位于处于 Testing 状态的 External 应用的受众部分。添加要连接的 Gmail 地址。处于 Testing 状态的 External 应用会拒绝不在此列表中的所有用户,其登录流程会以
access_denied错误结束。
如果新应用只供您自己使用,Google 的 Personal 模式引导流程会一步完成项目配置并创建 OAuth 客户端。Personal 模式仅限创建者的 Google Account 使用,不受七天测试令牌过期时间或 OAuth 用户数量上限的限制,也不会显示未验证应用页面。这是一次性选择:现有的 External 或 Internal 应用无法切换为 Personal,Personal 应用也无法切换为 External 或 Internal。
对于 External 应用,暂时将发布状态保留为 Testing。下面关于七天限制的部分会说明何时更改该状态。Personal 和 Internal 应用没有发布状态。
第 4 步:创建 Web 应用 OAuth 客户端
在凭据或客户端部分,使用以下字段创建 OAuth 客户端 ID。如果 Personal 模式引导流程已经创建了 Web 应用客户端,请改为编辑该客户端。
- 应用类型:Web 应用。桌面客户端没有重定向 URI 字段,因此无法使用 n8n 的回调。
- 名称:任意名称,例如
n8n。 - 授权的重定向 URI:粘贴 n8n 模态窗口中的 OAuth Redirect URL,保持原样。
- 授权的 JavaScript 来源:留空。这是另一份列表,将回调粘贴到这里不会生效。
保存客户端。Google 会显示客户端 ID 和客户端密钥。Google 第一次显示密钥时,请立即复制;之后将无法再次查看。将两者粘贴到 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 工作流为何一周后停止运行
n8n 的 Google 文档对此有明确说明:对于发布状态为 Testing、用户类型为 External 的 Google Cloud 应用,“consent and tokens expire after seven days”。Google 的受众文档也说明了相同规则:“Authorizations by a test user will expire seven days from the time of consent.”
具体过程如下。您登录时,Google 会向 n8n 提供一个短期 access token 和一个 refresh token。旧 access token 过期后,n8n 使用 refresh token 获取新的 access token。对于处于 Testing 状态的 External 应用,refresh token 本身会在用户同意授权后 7 天过期。第 7 天之后,刷新请求会失败,Google 返回 invalid_grant。此后的每次 Gmail 轮询也都会失败。
有两个细节容易令人误解。计时从您选择 Sign in with Google 时开始,而不是从工作流上次运行时开始。再次登录只会重新获得 7 天期限。如果工作流设置约一周后执行失败,并显示 invalid_grant,请先检查应用的受众和发布状态,不要直接归因于七天限制。撤销访问权限、达到令牌数量限制,以及启用了 Gmail scopes 的账户修改密码,也会导致 refresh token 无法使用。
Personal mode 应用不受此七天限制。对于现有的 External 应用,请根据您使用的账户选择以下一种方式。
退出方式 A:将 External 应用发布到生产环境
在受众页面中,将发布状态从 Testing 改为 In production。此后签发的 refresh token 不受七天限制。然后在 n8n 中再次选择 Sign in with Google。您当前持有的令牌是在 Testing 规则下签发的,因此需要获取新令牌。
发布应用不等于完成验证。n8n 默认请求的 scopes 包括 https://mail.google.com/ 和 https://www.googleapis.com/auth/gmail.modify。Google 将这两个 scopes 都归类为 restricted。使用 restricted scopes 的公开应用需要完成验证;如果应用通过服务器存储或传输受限数据,还需要进行安全评估。Google 还列出了例外情况,我们已于 19 November 2026 核对过相关内容。适用于 External 自托管 n8n 应用的例外是 Limited Audience。如果应用面向少于 100 个用户,您和这些用户可以在无需验证的情况下继续使用。Personal mode 是另一项独立例外,仅限创建者的 Google Account 使用。
未验证的 External 应用会显示未验证应用页面。登录时,Google 会显示 Google hasn't verified this app。在该页面打开高级选项,然后继续访问您的应用。对于仅供您自己使用的 External 应用,这是正常行为,并且只会在有人授予授权时显示。Google 将显示此页面的应用限制为总计 100 个新用户,而个人使用的 n8n 几乎不可能达到这一数量。
生产环境中的令牌仍可能停止工作。当您在 Google Account 设置中移除应用的访问权限时,Google 会停止接受对应的 refresh token。启用了 Gmail scopes 的账户修改密码后,对应的 refresh token 也会失效。连续 6 个月未使用的令牌会过期。对于同一客户端,Google 每个账户最多保留 100 个有效 refresh token;如果您多次登录,最早的令牌会被删除。每种情况最终都会产生相同的 invalid_grant 错误,解决方法是重新登录。
退出方式 B:在 Google Workspace 域中使用 Internal 应用
如果 Gmail 地址属于 Google Workspace 域,请在该组织内创建项目,并将受众设置为 Internal。Google 只对处于 Testing 状态的 External 应用实施七天规则,因此 Internal 应用不受影响。Google 的验证例外也涵盖内部使用。仅供“Google Workspace 或 Cloud Identity 组织中的人员”使用的应用不会显示未验证应用页面,也不受用户数量限制。
这只在项目属于该组织且登录人员是该组织成员时有效。个人 @gmail.com 地址无法使用 Internal 应用。您的 Workspace 管理员仍可能需要允许所请求的 Gmail scopes。
退出方式 C:使用 IMAP 和 SMTP 以及应用专用密码
您可以完全跳过 OAuth。Gmail 支持使用 IMAP(Internet Message Access Protocol)读取邮件,并使用 SMTP(Simple Mail Transfer Protocol)发送邮件。自 January 2025 起,个人 Gmail 账户始终启用 IMAP,因此无需修改设置。Google Workspace 管理员可以为用户启用或禁用 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 标签显示为普通文件夹。
Microsoft Entra 应用中的相同回调
Microsoft 邮件服务使用相同的模式。n8n 根据同一个实例基础 URL 生成所有 OAuth2 回调。Gmail 凭据显示正确的重定向 URL 后,Microsoft 凭据也会显示相同的 URL。
n8n 的 Microsoft 凭据文档介绍了注册流程。打开属于 Microsoft Entra 的应用注册页面,然后创建一个注册并为其命名。对于支持的帐户类型,n8n 文档选择“任何组织目录中的帐户(任何 Azure AD 目录 - 多租户)以及个人 Microsoft 帐户”。将重定向 URI 平台设置为 Web,然后粘贴 n8n 的 OAuth 重定向 URL。将 Application (client) ID 复制到 n8n 的客户端 ID 字段中。在证书和密码部分创建客户端密钥,然后将其值复制到 n8n。如果 Microsoft 帐户由组织管理,管理员可能需要先批准该应用。在 n8n 中选择 Connect my account,登录 Microsoft 并批准访问权限,以完成连接。n8n 文档还介绍了证书身份验证、云环境和服务专用设置。
选择哪种方式?
对于仅供创建者本人使用的新应用,请选择 Personal 模式。对于现有的 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 天使其 Gmail 授权失效。此时,n8n 的 refresh token 也会停止工作,每次轮询都会因 invalid_grant 失败。重新登录只能再获得 7 天的有效期。将 External 应用发布到生产环境,然后再次登录,即可避免此限制。Personal 模式和 Internal 应用不受 7 天测试令牌限制的影响。仅凭时间和 invalid_grant 不能确定原因:访问权限被撤销、令牌限制,以及更改密码(涉及 Gmail 作用域)也会使 refresh token 失效。
在自托管 n8n 中使用 Gmail 是否需要 Google 验证?
Personal 模式或 Limited Audience 应用不需要。n8n 请求受限的 Gmail 作用域,而具有受限作用域的公开应用需要通过验证。Personal 模式仅限创建者的 Google Account 使用,并且不会显示未验证应用警告。另一个单独的 Limited Audience 例外适用于预期用户少于 100 人的应用。对于未验证的 External 应用,您会看到“Google 尚未验证此应用”页面,但可以继续使用您自己的应用。
Gmail 触发器是否需要公开的 webhook URL?
不需要。Gmail Trigger 按 Poll Times 中设定的计划轮询 Gmail,因此 Google 不会调用您的服务器。OAuth 回调是浏览器重定向。登录时,您自己的浏览器必须能够访问回调 URL,并且该 URL 必须与 Google 客户端上注册的 URL 匹配。