n8n 中文文档

自定义 AWS 基础设施

terraform-aws-n8n 模块可以置备部署的每一层,也可以指向您已经在运行的基础设施。本页介绍主要的自定义点:让模块指向现有基础设施、拆分 ingress 流量,以及使用自定义 n8n 镜像。

客户管理的基础设施

模块能够置备的每一层,都可以改为指向您已经在运行的基础设施。每一层都遵循同一模式:一个 create_<x> 布尔值(默认为 true)用于停止模块置备该层;当它为 false 时,还需要一个或多个引用输入。

层 开关 引用输入
RDS PostgreSQL create_database db_host、db_password(或 db_password_secret_ref)
EKS 集群和节点组 create_eks existing_eks_cluster_name、existing_eks_cluster_prerequisites_confirmed
ElastiCache Redis create_elasticache redis_host、redis_port、redis_auth_token(或 redis_auth_token_secret_ref)、redis_transit_encryption_enabled
S3 存储桶 create_s3_bucket existing_s3_bucket_name
RDS KMS 密钥 create_db_kms_key db_kms_key_arn
S3 KMS 密钥 create_s3_kms_key s3_kms_key_arn
集群控制器(load balancer controller、Cluster Autoscaler、metrics-server、KEDA) install_lbc / install_cluster_autoscaler / install_metrics_server / install_keda 无;假定现有集群上已经运行等效组件

例如,要让模块指向您已经管理的 Redis 实例:

module "n8n" {
  # ...
  create_elasticache = false
  redis_host         = aws_elasticache_replication_group.shared.primary_endpoint_address
  redis_port         = 6379
  redis_auth_token   = var.shared_redis_auth_token
}

警告

让开关与其引用输入保持一致

只设置 redis_host 这类引用输入,而不同时把对应的 create_<x> 布尔值设为 false,并不会失败:模块仍会置备自己的托管资源,并让 n8n 指向该资源,而您提供的基础设施则闲置不用。请始终同时设置两者。

如果您让两个 n8n 部署指向同一个 Redis 主机,请为每个部署设置唯一的 redis_key_prefix。否则,两个部署会共享同一队列和领导者选举通道,在一个实例上发布工作流可能使另一个实例产生 webhook not registered 错误。

模块的 examples 文件夹中提供了每一层客户管理基础设施的可运行参考配置(customer-managed-redis、customer-managed-s3、customer-managed-cluster 和 customer-managed-everything)。

提示

创建 VPC 始终不在范围内

模块始终需要一个预先存在的 VPC(vpc_id、private_subnets、public_subnets)。它从不创建 VPC。

客户管理的 ingress

默认情况下,模块会创建一个面向互联网的 Application Load Balancer,把 /webhook 路由到 webhook 处理器,把 / 路由到 main Pod。设置 create_ingress = false 即可改为管理您自己的 ingress,例如把公开的 webhook 流量与仅供内部使用的编辑器和 API 分开。

把流量路由到模块作为输出公开的 Service:

输出 提供的内容
n8n_service_name 编辑器 UI、REST API
n8n_webhook_service_name Webhook、表单、等待恢复、MCP
n8n_webhook_path_prefixes 必须到达 webhook 处理器的路径前缀
n8n_service_port 两者都是(5678)

请把 n8n_webhook_path_prefixes 中的每个前缀都路由到 webhook 处理器,而不只是 /webhook:模块会在 main Pod 上禁用生产 webhook 处理,因此 /webhook-waiting(Wait 节点恢复)、/form 和 /form-waiting(Form Trigger 节点)以及 /mcp(MCP server 触发器)如果到达 main Pod,都会返回 404。请在任何兜底的 / 规则之前声明这些前缀。

调用方自行管理的 ingress 还需要:

  • 对 n8n_service_name 启用会话粘性,使每个浏览器都停留在同一个 main Pod 上。否则,来自同一浏览器的编辑器请求和 WebSocket 连接会分散到多个 main Pod,编辑器会失去连接。
  • 设置 n8n_proxy_hops,其值为客户端与 n8n 之间会添加 X-Forwarded-For 标头的代理数量。模块默认将其设为 1。如果只有模块或您自己的负载均衡器这一层代理,该值是正确的。路径中每多一个 HTTP 代理(例如 CloudFront),就再加 1。

拆分 ingress 的完整可运行示例(包括证书和两条 DNS 记录)位于 examples/split-ingress。

自定义 n8n 镜像

设置 n8n_image_repository,即可让 Helm release 指向您构建的镜像,而不是默认的 n8n 镜像。常见原因包括使用内部基础镜像,或把社区节点烘焙进镜像:

module "n8n" {
  # ...其他输入...

  n8n_image_repository = "123456789012.dkr.ecr.eu-west-1.amazonaws.com/n8n"
  n8n_image_tag        = "2.27.4-mypackages"

  # 固定为构建自定义镜像所基于的 n8n 版本。
  n8n_task_runner_image_tag = "2.27.4"

  # 软件包已经在镜像中时不需要。
  n8n_reinstall_missing_packages = false
}

警告

通过 UI 安装的社区软件包不会从自定义镜像中加载

n8n 只从 N8N_CUSTOM_EXTENSIONS 设置的目录加载社区节点,而不会从镜像 node_modules 中一次普通的 npm install 加载。请把 n8n_custom_extensions_path 设为镜像放入这些软件包的目录,并在 Dockerfile 中把软件包安装到该目录。以这种方式加载的节点还会被重命名为 CUSTOM.* 类型,因此基于同一软件包的 UI 安装副本构建的现有工作流,必须更新节点类型后才能解析。

如果每次软件包变更都重新构建镜像不切实际,n8n_extra_volumes 和 n8n_extra_volume_mounts 可以从 ConfigMap、Secret 或 persistent volume claim 挂载同一目录,而不必把它烘焙进镜像。

大规模下的 Pod DNS

n8n_dns_config 设置 n8n Pod 上的 DNS 选项。Pod 数量很大时,Kubernetes 默认的 DNS 搜索路径行为(ndots:5)会让每一次集群内或 AWS 服务的主机名查找(例如访问 S3 或 ElastiCache)先经过最多四次不必要的搜索域查询,然后才按写明的名称尝试。如果部署中的每个依赖都通过完全限定域名寻址(本模块默认就是这样),请把 n8n_dns_config 设为 ndots:1:

n8n_dns_config = {
  options = [{ name = "ndots", value = "1" }]
}

这会在大规模下大幅减少 DNS 查询量,并消除 CoreDNS 饱和导致的失败请求,但不会让单个请求变得更快。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。