使用反向代理 配置 n8n webhooks
n8n 通过组合 N8N_PROTOCOL、N8N_HOST 和 N8N_PORT 来创建 webhook URL。如果 n8n 在反向代理后面运行,这将不起作用。这是因为 n8n 在内部运行在端口 5678 上,但反向代理将其暴露到 Web 的端口 443 上。
在反向代理后面运行 n8n 时,重要的是要执行以下操作:
- 使用
N8N_WEBHOOK_URL环境变量手动设置 webhook URL,以便 n8n 可以在编辑器 UI 中显示它并向外部服务注册正确的 webhook URL。(N8N_WEBHOOK_URL替代自 n8n 2.35.0 起弃用的WEBHOOK_URL;如果仍使用WEBHOOK_URL,n8n 会记录弃用警告。) - 将
N8N_PROXY_HOPS环境变量设置为1。 - 在请求路径上的最后一个代理上,设置以下标头以传递有关初始请求的信息:
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
有关该变量的更多信息,请参阅环境变量参考。
如果还在同一反向代理后运行 n8n 的实例级 MCP 服务器,请确保代理也转发 MCP 请求标头。
在身份验证代理后通过单独的主机名提供表单
提示
Feature availability 功能可用性
N8N_INSECURE_DISABLE_FORM_HTML_SANDBOX 从 n8n 2.15.0 起可用。
某些身份验证代理(例如 Google Identity-Aware Proxy)会使用会话 cookie。要将 n8n 表单放在这类代理之后,请通过单独的主机名提供 webhook 和表单,然后将 N8N_INSECURE_DISABLE_FORM_HTML_SANDBOX 设置为 true。请确保满足何时可以安全地禁用表单沙箱中的条件。
该设置适用于 n8n 作为表单提供的每个页面:
- 来自 n8n Form Trigger 和 n8n Form 节点的页面,包括表单完成页面
- Wait 节点以 On Form Submitted 方式恢复时使用的表单
- Slack、Microsoft Teams 等应用节点中 Send and Wait for Response 操作的审批表单
为什么在身份验证代理后提交表单会失败
n8n 提供表单页面时,会在内容安全策略(CSP)标头中带上 sandbox 指令。该沙箱会为页面分配一个不透明的 origin。因此,浏览器在提交表单时会发送 Origin: null,并且不带 cookie。代理拿不到它的会话 cookie,就会拒绝请求。表单可以加载,但提交时会显示 Problem submitting response,并且不会启动任何执行。
将 N8N_INSECURE_DISABLE_FORM_HTML_SANDBOX 设置为 true 会从表单页面中移除 sandbox 指令。表单页面保留其真实 origin,浏览器会在提交时一并发送代理的会话 cookie。
何时可以安全地禁用表单沙箱
危险
表单沙箱保护打开你表单的用户
表单页面可以显示来自工作流的 HTML,例如来自 Custom HTML 表单元素和完成页面的内容。沙箱会阻止这些 HTML 使用打开表单的人的 n8n 会话。如果没有沙箱,并且表单与编辑器共用同一个主机名,页面上的脚本就能以该用户的身份向 n8n 发送请求。
只有在以下三个条件全部满足时,才将 N8N_INSECURE_DISABLE_FORM_HTML_SANDBOX 设置为 true:
N8N_WEBHOOK_URL和N8N_EDITOR_BASE_URL使用不同的主机名,例如hooks.example.com和n8n.example.com。同一主机名的不同端口是不够的,因为浏览器会在端口之间共享 cookie。- webhook 主机名只提供 webhook 和表单路径。请配置代理,使编辑器和 n8n 的内部 REST API(
/rest)无法通过该主机名访问。用户不会通过 webhook 主机名登录 n8n。 - n8n 以
NODE_ENV=production运行。官方 n8n Docker 镜像会为你设置此项;如果你使用 npm 安装 n8n,请自行设置。否则 n8n 会以开发模式运行,并接受来自任何网站的跨源请求。
默认情况下,n8n 在以下路径上提供 webhook 和表单。如果你使用端点环境变量修改过这些路径,请改用你的值:
- 表单:
/form/、/form-test/和/form-waiting/,分别由N8N_ENDPOINT_FORM、N8N_ENDPOINT_FORM_TEST和N8N_ENDPOINT_FORM_WAIT设置 - Webhook:
/webhook/、/webhook-test/和/webhook-waiting/,分别由N8N_ENDPOINT_WEBHOOK、N8N_ENDPOINT_WEBHOOK_TEST和N8N_ENDPOINT_WEBHOOK_WAIT设置
采用此设置后,浏览器不会将 n8n 会话 cookie 发送到 webhook 主机名,表单页面上的脚本也无法向编辑器主机名上的 n8n 发送经过身份验证的请求。
在单独主机名上提供表单的配置示例
此示例在 n8n.example.com 上提供编辑器,在 hooks.example.com 上提供 webhook 和表单:
# The editor stays on the main hostname
export N8N_EDITOR_BASE_URL=https://n8n.example.com/
# Webhooks and forms use their own hostname, behind the authentication proxy
export N8N_WEBHOOK_URL=https://hooks.example.com/
export N8N_PROXY_HOPS=1
# Required: without it, n8n runs in development mode
export NODE_ENV=production
export N8N_INSECURE_DISABLE_FORM_HTML_SANDBOX=true
N8N_WEBHOOK_URL 从 n8n 2.30.0 起可用。在更早的版本上,请改用 WEBHOOK_URL。
在身份验证代理后从编辑器测试表单
从 n8n 2.47.0 开始,编辑器会在位于身份验证代理之后的 webhook 主机名上打开测试表单。当你在包含 n8n Form Trigger 节点的工作流上选择 Execute workflow 或 Execute step 时,编辑器会在新窗口中打开测试表单。如果你尚未登录代理,会先显示代理的登录页面;登录后,表单即可加载。
在更早的版本上,编辑器不会在此设置下打开测试表单。要测试表单,请打开 n8n Form Trigger 节点,复制其 Test URL,然后在新的浏览器标签页中打开。