基于Terraform的AI Agent网关在AWS上的生产级部署实践

1. 项目概述与核心价值

如果你正在寻找一个能让你在AWS上快速、安全地部署一个功能完整的AI Agent网关的方案，那么infrahouse/terraform-aws-openclaw这个Terraform模块，很可能就是你一直在找的“瑞士军刀”。这个模块的核心价值，在于它将一个复杂的、生产就绪的AI应用栈，封装成了一个开箱即用的基础设施即代码（IaC）解决方案。你不再需要手动去拼凑ALB、Cognito、EC2、EFS、Secrets Manager这些服务，也不用头疼于安全配置和密钥管理。这个模块帮你把这些都做好了，并且是按照企业级的安全和运维标准来做的。

简单来说，它部署的是 OpenClaw 项目——一个开源的AI Agent网关和编排平台。你可以把它想象成一个AI应用的“中央调度器”或“API网关”，它允许你连接和管理不同的AI模型提供商（如AWS Bedrock、Anthropic Claude、OpenAI GPT、本地Ollama模型），并通过一个统一的界面或API来调用它们。这对于构建需要灵活切换模型、管理API密钥、记录日志和追踪成本的AI应用来说，是一个非常实用的基础组件。

这个模块最吸引我的地方是它的“生产就绪”特性。很多开源项目只告诉你“怎么跑起来”，但这个模块从一开始就考虑了“怎么安全、稳定地跑在生产环境”。它用Cognito替代了简单的共享令牌认证，用Secrets Manager安全地存储API密钥，用EFS保证应用数据在实例替换时不丢失，用CloudWatch Logs提供长达一年的日志留存以满足合规要求。这些设计决策，都是我们在实际运维中踩过坑、交过学费后才总结出来的最佳实践。接下来，我会带你深入拆解这个模块的设计思路、核心配置，并分享我在部署和调优过程中的实操经验与避坑指南。

2. 架构深度解析：为什么这样设计？

在动手部署之前，理解这个模块的架构设计至关重要。这不仅能帮你更好地使用它，也能在你需要自定义扩展时，知道从哪里下手。整个架构可以看作是一个经典的三层Web应用在云上的现代化实现，但每一层都针对AI工作负载做了特别的优化。

2.1 网络与访问层：安全是第一道防线

模块使用了一个面向公网的Application Load Balancer作为流量入口。ALB负责处理TLS终止（通过自动从AWS Certificate Manager申请的证书）、将HTTP流量重定向到HTTPS，以及最重要的——与Amazon Cognito集成进行用户认证。

注意：这里的设计与OpenClaw原生的“网关令牌”认证方式有本质区别。原生方式需要在浏览器或客户端配置一个静态令牌，存在泄露风险且难以管理用户。而Cognito方案提供了基于OAuth 2.0的标准认证流程，支持多因素认证（MFA）、用户生命周期管理，并且认证状态由AWS管理，应用本身不处理密码，安全性大大提升。

ALB背后连接的是一个Auto Scaling Group（ASG）管理的EC2实例集群。这些实例部署在私有子网中，无法直接从互联网访问，只能通过ALB的安全组规则进来。这种网络隔离是纵深防御的关键一步。即使应用层出现漏洞，攻击者也无法直接接触到后端实例。

2.2 计算与数据层：持久化与弹性

计算层由EC2实例承担，运行着OpenClaw应用本身以及可选的Ollama服务（用于本地模型推理）。模块默认使用Ubuntu 24.04 LTS (Noble)的AMI，并进行了系统加固。

数据持久化是通过Amazon EFS实现的。OpenClaw的配置文件、会话数据、以及Ollama拉取的模型文件，都会挂载到EFS文件系统上。这意味着：

1. 实例可替换：当ASG进行伸缩或实例因故障替换时，新实例挂载同一个EFS，所有数据和配置立即可用，实现了无状态计算节点与有状态数据的分离。
2. 多实例共享：未来如果扩展为多实例集群，所有实例可以共享同一份配置和模型数据，避免数据不一致。
3. 备份与恢复：模块默认启用了EFS的备份策略，你可以基于此快照进行数据恢复。

密钥管理是所有AI应用的核心痛点。模块使用AWS Secrets Manager来存储所有第三方LLM提供商的API密钥（如Anthropic、OpenAI）。这些密钥在Secrets Manager中被KMS加密存储，然后通过实例的IAM角色权限，在启动时以环境变量的方式安全地注入到OpenClaw进程中。你永远不需要在代码、配置文件或用户数据中明文写入API密钥。

2.3 安全与可观测性：贯穿始终的设计

安全不是功能，而是属性。这个模块在多个层面体现了这一点：

• 系统服务加固：OpenClaw和Ollama都以systemd服务运行，并配置了ProtectSystem=strict,NoNewPrivileges=true等限制，即使服务被攻破，攻击者也很难提升权限或破坏宿主系统。
• 供应链安全：Node.js通过官方的GPG签名APT仓库安装，Ollama从GitHub Release下载校验和验证过的tar包，OpenClaw通过npm以非特权用户安装。避免了常见的curl | sudo bash这种高风险安装模式。
• 日志与监控：所有应用日志（包括访问日志、错误日志）都通过CloudWatch Logs Agent发送到CloudWatch Logs组，并配置了365天的保留期，满足ISO 27001或SOC 2等合规审计要求。同时，ALB的访问日志也会记录到S3。模块还内置了CloudWatch警报，针对ALB的5xx错误、高延迟等指标，可以发送通知到指定的邮箱。

3. 核心配置与实操部署详解

理解了架构，我们就可以开始动手了。模块的输入变量设计得比较清晰，但有些选项的配置会直接影响性能、成本和安全性，需要仔细斟酌。

3.1 基础环境与网络准备

在调用模块前，你需要准备好基础的AWS环境。最关键的是VPC网络规划。模块需要两组子网ID：

• alb_subnet_ids: 用于ALB的公有子网。通常你需要至少两个在不同可用区（AZ）的公有子网，以确保ALB的高可用性。这些子网需要具有到互联网的网关（IGW）路由。
• backend_subnet_ids: 用于EC2实例的私有子网。这些子网通常没有互联网网关，但需要通过NAT网关或VPC端点访问外部服务（如下载包、拉取Docker镜像、调用Bedrock API等）。同样建议跨多个AZ部署。

一个典型的main.tf文件开头可能是这样的，它先使用一个社区VPC模块创建网络：

module "network" { source = "terraform-aws-modules/vpc/aws" version = "~> 5.0" name = "my-openclaw-vpc" cidr = "10.0.0.0/16" azs = ["us-east-1a", "us-east-1b"] public_subnets = ["10.0.1.0/24", "10.0.2.0/24"] private_subnets = ["10.0.101.0/24", "10.0.102.0/24"] enable_nat_gateway = true single_nat_gateway = true # 为节省成本，单AZ部署NAT网关 enable_vpn_gateway = false tags = { Terraform = "true" Environment = "dev" } }

3.2 模块调用与关键参数解析

准备好网络后，就可以调用OpenClaw模块了。下面是一个包含详细注释的配置示例，我逐一解释关键参数：

module "openclaw" { source = "registry.infrahouse.com/infrahouse/openclaw/aws" version = "0.4.0" # 务必检查并使用最新版本 # 必须提供两个不同的aws provider，一个用于主资源，一个专用于DNS操作（Route53） providers = { aws = aws aws.dns = aws } # 环境标识，用于资源命名和标签 environment = "production" # 你的Route53托管区域ID，用于创建DNS记录和ACM证书验证 zone_id = aws_route53_zone.my_domain.zone_id # 使用前面VPC模块输出的子网ID alb_subnet_ids = module.network.public_subnets backend_subnet_ids = module.network.private_subnets # 告警邮件列表，当ALB出现5xx错误或高延迟时会收到通知 alarm_emails = ["devops-team@mycompany.com"] # 初始Cognito用户列表。部署后，这些用户会收到临时密码邮件（如果Cognito配置了邮件） cognito_users = [ { email = "alice@mycompany.com" full_name = "Alice Developer" }, { email = "bob@mycompany.com" full_name = "Bob Analyst" }, ] # --- 以下为可选但重要的配置 --- # 1. 实例类型选择：这是成本与性能的核心权衡点 # 如果只用云端LLM（Bedrock/OpenAI），t3.medium(4GB)足够。 # 如果要运行本地Ollama模型，参考文档中的模型内存表。 # 例如，运行7B模型建议t3.xlarge(16GB)。 instance_type = "t3.xlarge" # 2. Ollama配置：如果不需要本地模型，设为null可节省启动时间和磁盘空间 ollama_default_model = "llama3.1:8b" # 实例启动时会自动拉取此模型 # ollama_default_model = null # 完全禁用Ollama # 3. 根卷大小：Ollama模型会下载到根卷。30GB是起步，大模型需要更多。 root_volume_size = 50 # GB # 4. DNS记录：默认创建 `openclaw.yourdomain.com`。可以自定义。 # 设置 `dns_a_records = [""]` 将为根域名（apex zone）创建记录，如 `yourdomain.com` dns_a_records = ["ai-gateway", "claw"] # 将创建 ai-gateway.yourdomain.com 和 claw.yourdomain.com # 5. 允许访问的IP范围：默认是["0.0.0.0/0"]，即公网可访问。 # 如果你只想在公司网络访问，可以设置为办公室IP段。 # allowed_cidrs = ["203.0.113.0/24", "198.51.100.0/24"] # 6. 额外Bedrock模型：模块默认注册了Claude和Nova系列。 # 如果你想添加其他Bedrock模型，如Llama 3.1 70B： extra_bedrock_models = [ { id = "us.meta.llama3-1-70b-instruct-v1:0" name = "Llama 3.1 70B Instruct" # 以下参数会传递给OpenClaw的模型配置，可选 # contextWindow = 128000 # maxTokens = 8192 }, ] # 7. 额外系统包：如果你想在实例上安装其他工具，例如GitHub CLI供OpenClaw技能使用 extra_packages = ["gh"] }

执行terraform init和terraform apply后，大约需要10-15分钟完成所有资源创建。最关键的输出是module.openclaw.url，这就是你的OpenClaw网关访问地址。

3.3 初始登录与用户管理

应用部署完成后，首次访问输出的URL，你将被重定向到Cognito托管登录页面。这里有一个非常重要的实操细节：

模块通过cognito_users变量创建的用户，在首次创建时处于FORCE_CHANGE_PASSWORD状态。Cognito不会自动发送包含密码的邮件，除非你配置了Cognito的自定义邮件发送功能（使用SES或Lambda）。

因此，更常见的初始用户设置流程是：

1. 让模块先创建用户池和用户（状态为UNCONFIRMED或FORCE_CHANGE_PASSWORD）。
2. 使用AWS CLI或控制台，以管理员身份为用户设置一个临时密码，并手动将用户状态改为CONFIRMED。
3. 将临时密码通过安全渠道（如1Password、Bitwarden共享）发送给用户，用户首次登录时会被要求更改密码。

# 使用AWS CLI设置用户密码并确认用户 aws cognito-idp admin-set-user-password \ --user-pool-id <你的UserPoolId> \ --username alice@mycompany.com \ --password "TempPass123!" \ --permanent aws cognito-idp admin-confirm-sign-up \ --user-pool-id <你的UserPoolId> \ --username alice@mycompany.com

提示：你可以从模块的输出cognito_user_pool_id获取User Pool ID。对于生产环境，建议集成企业身份提供商（如Azure AD、Okta）作为Cognito的身份源，实现单点登录（SSO），这样用户管理会更方便。

4. 多模型提供商配置实战

OpenClaw的核心魅力在于其多模型支持。模块为每种提供商提供了不同的集成方式。

4.1 AWS Bedrock：零配置默认选项

这是最省心的方式。模块默认已配置好Bedrock支持，使用的模型是Amazon Nova 2 Lite。为什么能零配置？因为EC2实例通过IAM角色获得了调用Bedrock API的权限。你不需要提供任何API密钥，只需确保部署所在的AWS区域（如us-east-1）已经启用了你想要的Bedrock模型。

你可以在OpenClaw的Web界面的“模型”页面，看到所有已注册的Bedrock模型。模块的extra_bedrock_models变量允许你添加更多模型。你需要知道模型的“推理配置标识符”（Inference Profile ID），格式如us.anthropic.claude-3-5-sonnet-20241022-v2:0。你可以在AWS控制台的Bedrock页面的“ playground”或“模型访问”部分找到这些ID。

4.2 Anthropic / OpenAI API：密钥配置

如果你想使用Claude API或OpenAI GPT API，就需要提供相应的API密钥。模块已经创建好了一个Secrets Manager密钥，你只需要将密钥值放进去。

步骤一：找到密钥ARN应用部署后，记下输出变量secret_arn的值，或者去AWS控制台的Secrets Manager服务里，查找名称包含openclaw-api-keys的密钥。

步骤二：写入密钥你不能通过Terraform直接写入密钥值，因为Terraform状态文件会明文记录这些值，极不安全。正确的方式是通过AWS控制台、CLI或你公司的密钥管理流程来设置。

# 使用AWS CLI更新密钥（假设密钥已存在） aws secretsmanager put-secret-value \ --secret-id <你的Secret ARN> \ --secret-string '{ "ANTHROPIC_API_KEY": "sk-ant-your-claude-key", "OPENAI_API_KEY": "sk-your-openai-key" }'

步骤三：重启OpenClaw服务更新密钥后，需要重启EC2实例上的OpenClaw服务，以便其重新读取Secrets Manager中的值。最快的方式是在AWS控制台重启EC2实例，或者通过SSH连接到实例执行：

sudo systemctl restart openclaw

重启后，在OpenClaw的“模型”页面，你应该能看到新出现的“Claude (API)”和“OpenAI”提供商选项。

4.3 Ollama本地模型：性能与成本权衡

Ollama支持让你可以在自己的EC2实例上运行开源模型，这对于数据隐私、网络隔离或降低API调用成本非常有用。但你需要仔细规划实例规格。

模块的文档提供了一个非常实用的实例选型参考表，其核心逻辑是：Ollama模型需要完全加载到内存中。一个7B参数的模型，在量化后可能需要5-8GB内存。这还不包括操作系统、OpenClaw应用和其他进程的开销。

我的经验法则是：为模型预留的内存 = 模型文件大小 * 1.2 + 2GB（系统缓冲）。例如，一个7B的Q4量化模型文件约4GB，那么你需要至少4*1.2+2 ≈ 7GB的可用内存。因此，选择t3.xlarge（16GB内存）是稳妥的。

另一个关键参数是ollama_default_model。如果你设置了一个模型（如llama3.1:8b），实例在启动时会自动执行ollama pull来下载它。这可能会显著增加实例启动时间（从几分钟到半小时，取决于模型大小和网络）。对于生产环境，我建议：

1. 首次部署时，先将ollama_default_model设为null，让实例快速启动。
2. 通过SSH连接到实例，手动拉取模型，测试性能。
3. 确认模型和实例规格匹配后，再更新Terraform配置，设置ollama_default_model并terraform apply。后续替换的实例就会自动拉取模型了。

5. 运维、监控与故障排查

部署只是第一步，让系统稳定运行才是关键。模块内置了一些监控和运维支撑功能，你需要知道如何使用它们。

5.1 日志查看与问题诊断

所有日志都集中在CloudWatch Logs中。你需要关注两个主要的日志组：

1. /aws/ec2/openclaw-<environment>: 这是EC2实例的系统日志和应用日志（包括OpenClaw和Ollama的stdout/stderr）。当应用启动失败或运行时出错时，首先来这里查看。
2. /aws/application-load-balancer/openclaw-<environment>: 这是ALB的访问日志。可以查看所有HTTP请求的详细信息，用于分析流量模式、诊断4xx/5xx错误。

一个常见的启动问题是OpenClaw服务启动失败。你可以在CloudWatch中过滤/aws/ec2/openclaw-<environment>日志流，搜索关键词ERROR或Failed to start。常见原因包括：

• Secrets Manager权限不足：检查实例的IAM角色是否附加了正确的策略，能否读取指定的密钥。
• EFS挂载失败：检查实例所在子网的安全组是否允许2049端口（NFS）访问EFS挂载点。
• 端口冲突：确保OpenClaw默认的3000端口没有被其他进程占用（模块配置应该已处理）。

5.2 监控告警与性能指标

模块默认创建了几个CloudWatch警报：

• ALB 5xx错误率：当5xx状态码比例超过阈值（默认5%）时告警。这通常意味着后端实例健康检查失败或应用崩溃。
• ALB目标响应时间：当平均响应时间超过阈值（默认5秒）时告警。这可能表明实例负载过高或模型推理速度慢。
• 实例健康检查：如果ALB目标组的健康检查连续失败，实例会被标记为不健康并从负载均衡器中移除。

这些警报会发送到alarm_emails变量指定的邮箱。对于生产环境，我强烈建议你将警报集成到更专业的监控系统，如PagerDuty、Slack或Opsgenie。你可以通过Terraform的aws_cloudwatch_metric_alarm资源，基于模块输出的ALB ARN、目标组ARN等，创建更细粒度的告警。

5.3 备份、恢复与伸缩

数据备份：EFS文件系统默认启用了AWS Backup每日自动备份，保留期为35天。你可以在AWS Backup控制台查看和管理这些备份。如果需要恢复，可以创建一个新的EFS卷从备份恢复，然后更新模块的efs_file_system_id变量指向新卷（注意：这需要停机操作）。

水平伸缩：模块使用Auto Scaling Group管理实例，但目前默认的desired_capacity、min_size、max_size可能被固定在1（具体需查看模块源码）。如果你需要高可用或多实例负载均衡，需要修改模块内部关于aws_autoscaling_group的配置，或者向模块维护者提需求。需要注意的是，OpenClaw本身可能不是完全无状态的，多实例时需要确保会话等状态信息被妥善处理（例如存储在外部Redis中），这超出了当前模块的范围。

垂直伸缩（实例规格）：如果你想升级或降级实例类型（例如从t3.large升级到t3.xlarge），直接修改instance_type变量并执行terraform apply即可。ASG会启动一个新实例，等待它通过健康检查后，终止旧实例，实现滚动更新。由于EFS的存在，数据不会丢失。

6. 安全加固与高级配置建议

模块已经做了很多安全加固，但在企业级部署中，你可能还需要考虑以下几点：

6.1 网络访问控制精细化

模块的allowed_cidrs变量默认是["0.0.0.0/0"]，即允许任何IP访问ALB。在生产环境，你应该将其限制为公司的办公网络IP段或VPN IP段。

allowed_cidrs = ["203.0.113.0/24", "198.51.100.0/24"] # 替换为你的实际IP段

更进一步，你可以结合AWS WAF，在ALB前部署Web应用防火墙，防御常见的SQL注入、XSS等攻击，并设置基于地理位置的访问限制。

6.2 Cognito高级安全功能

模块创建的Cognito用户池已经配置了密码策略等基础安全设置。你可以在AWS控制台进一步启用：

• 多因素认证：要求用户使用TOTP认证器（如Google Authenticator）或SMS进行二次验证。
• 高级安全功能：启用自适应认证、威胁检测，可以识别异常登录行为（如从不常见地点登录）。
• 自定义域名：使用你自己的域名作为Cognito登录页面，提升用户体验和品牌一致性。

6.3 密钥轮换与权限最小化

对于Anthropic/OpenAI的API密钥，应建立定期轮换机制。你可以在Secrets Manager中配置密钥的自动轮换，通过一个Lambda函数来更新密钥。确保该Lambda函数的执行角色有写入密钥的权限（模块的api_keys_writers变量可以用于此目的）。

遵循权限最小化原则，定期审查EC2实例IAM角色的权限。模块已经授予了必要的权限（读取Secrets Manager、写入CloudWatch Logs、调用Bedrock等）。通过extra_instance_permissions变量添加额外权限时，务必精确到具体的API和资源。

6.4 实例连接与调试

模块如果未提供key_name，则会自动生成一个SSH密钥对，私钥会以Terraform输出的形式显示（ssh_private_key）。请务必妥善保存此输出，因为Terraform状态文件刷新后可能不再显示。有了私钥，你可以通过Session Manager或Bastion Host连接到处于私有子网的EC2实例进行调试。

一个实用的调试命令是检查OpenClaw服务的状态和日志：

sudo systemctl status openclaw sudo journalctl -u openclaw -f --lines=50

以及检查Ollama服务：

sudo systemctl status ollama ollama list # 查看已拉取的模型 curl http://localhost:11434/api/tags # 通过API检查模型

7. 成本估算与优化策略

运行这个架构会产生多项AWS费用，主要构成如下：

1. EC2实例：最大的可变成本。根据选择的实例类型和运行时长计费。t3.large按需实例在美国东部区域约$0.0832/小时，每月约$60。如果使用r6i系列内存优化型实例运行大模型，成本会显著上升。
2. EFS存储：按使用的存储量（GB-月）和吞吐量模式计费。默认的“弹性”模式适合可变工作负载。如果数据量不大（<10GB），每月成本可能在$3-$10。
3. ALB：按使用时长（小时）和处理的LCU（负载均衡器容量单位）数量计费。轻度使用下每月约$20-$30。
4. Secrets Manager：每个密钥每月$0.40。模块创建了一个密钥。
5. CloudWatch Logs：按摄入的数据量和存储时长计费。365天留存会产生持续的存储成本，但有助于合规。
6. Cognito：每月活跃用户（MAU）前5万免费，超出后按阶梯收费。对于内部工具，用户数通常很少，成本可忽略。
7. Bedrock：按实际调用的Tokens数量计费，模型不同单价不同。这是使用AI模型的主要成本，与你的使用量直接相关。

优化建议：

• 开发/测试环境：使用t3.medium或t3.small实例，并设置ollama_default_model = null。可以使用Auto Scaling策略，在非工作时间将desired_capacity设置为0以停止实例，大幅节省成本。
• 利用预留实例：对于生产环境，如果实例需要7x24运行，购买EC2预留实例（RI）或Savings Plans可以节省最高70%的成本。
• 监控Bedrock成本：在OpenClaw界面或通过CloudWatch指标，密切关注Bedrock的调用量和成本。对于非关键任务，可以考虑使用成本更低的模型（如Nova Lite）或切换到本地Ollama模型。
• 清理EFS旧数据：定期检查EFS中是否有不再需要的旧模型文件或日志数据，避免存储成本膨胀。

部署完成后，你可以在AWS Cost Explorer中，通过资源标签（模块会为所有资源打上Environment和Service标签）来精确追踪这个OpenClaw栈的成本。

这个terraform-aws-openclaw模块将一个复杂的生产级AI网关部署，简化成了几行Terraform配置。它背后的设计理念——安全、可维护、成本透明——正是我们在云上构建关键应用时所追求的。在实际使用中，我最看重的是它“开箱即用”的安全基线和对多模型提供商的无缝集成，这为团队快速实验和迭代AI功能提供了坚实可靠的基础设施层。