自定义 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 饱和导致的失败请求,但不会让单个请求变得更快。