添加 Terraform 基础设施配置以支持 AWS ECS 部署

[Chen188]

概述

本 PR 为 TEN-Agent 项目添加了完整的 Terraform 基础设施即代码（IaC）配置，支持将应用部署到 AWS ECS（使用 Fargate 启动类型）。配置基于项目根目录中的 docker-compose.yaml 文件，实现了模块化、可维护的云基础设施管理。

已实现的需求

✅ Docker Compose 分析与转换

• 分析了 docker-compose.yaml 文件中定义的所有服务、网络、卷和配置
• 将所有服务（除 graph designer 模块外）转换为 ECS 任务定义
• 保持了服务间的依赖关系和网络配置

✅ 模块化 Terraform 配置文件

在项目根目录下创建了以下 Terraform 配置文件：

1. main.tf - 主配置文件，包含 provider 配置和模块调用
2. variables.tf - 定义所有可配置变量，支持多环境配置
3. outputs.tf - 定义输出值（ALB DNS、服务 URL 等）
4. ecs.tf - ECS 集群和服务配置（Fargate 启动类型）
5. tasks.tf - ECS 任务定义，基于 docker-compose 服务配置
6. networking.tf - VPC、子网、安全组等网络资源
7. alb.tf - 应用负载均衡器配置
8. secrets.tf - AWS Secrets Manager 配置，用于管理敏感信息
9. route53.tf - Route 53 域名配置
10. acm.tf - ACM 证书配置
11. iam.tf - IAM 角色和策略配置

✅ 安全配置

• 敏感信息管理：
  • 在 secrets.tf 中为所有敏感信息（API 密钥、密码等）创建 AWS Secrets Manager secrets
  • ECS 任务定义使用 secrets 字段引用这些 secrets
  • 避免在代码中硬编码敏感信息

✅ 多环境支持

• 实现了完整的环境切换机制：
  • environments/dev.tfvars - 开发环境配置
  • environments/staging.tfvars - 预发布环境配置
  • environments/prod.tfvars - 生产环境配置
• 不同环境可配置不同的：
  • 实例大小（CPU、内存）
  • 副本数量
  • 日志保留期限
  • 域名配置

✅ 域名和 SSL 配置

• Route 53：支持自定义域名配置
• ACM：自动创建和验证 SSL/TLS 证书
• ALB 集成：将负载均衡器与域名和证书关联

✅ 最佳实践

• ✔️ 使用变量而不是硬编码值
• ✔️ 添加了详细的注释说明
• ✔️ 使用 tags 标记所有资源（Project、Environment、ManagedBy）
• ✔️ 输出重要的资源信息
• ✔️ 遵循 Terraform 命名约定
• ✔️ 实现资源依赖管理

新增文件

Terraform 配置文件

• main.tf - 主配置文件
• variables.tf - 变量定义
• outputs.tf - 输出定义
• ecs.tf - ECS 集群和服务
• tasks.tf - ECS 任务定义
• networking.tf - 网络资源
• alb.tf - 负载均衡器
• secrets.tf - 密钥管理
• route53.tf - DNS 配置
• acm.tf - SSL 证书
• iam.tf - IAM 角色和策略

环境配置文件

• environments/dev.tfvars - 开发环境
• environments/staging.tfvars - 预发布环境
• environments/prod.tfvars - 生产环境

辅助文件

• terraform.tfvars.example - 变量配置示例
• .gitignore.terraform - Terraform 文件忽略规则

脚本文件

• deploy.sh - 自动化部署脚本
• validate-deployment.sh - 部署验证脚本

文档文件

• terraform-README.md - 完整的使用文档
• TERRAFORM-QUICKSTART.md - 快速入门指南
• TERRAFORM-FILES-SUMMARY.md - 文件结构说明
• TERRAFORM-DEPLOYMENT-SUMMARY.md - 部署流程说明
• TERRAFORM-INDEX.md - 索引和导航

使用说明

前置条件

1. AWS 凭证配置：

   export AWS_ACCESS_KEY_ID="your-access-key"
   export AWS_SECRET_ACCESS_KEY="your-secret-key"
   export AWS_DEFAULT_REGION="us-east-1"

2. Terraform 安装：

   • 需要 Terraform >= 1.0
   • AWS Provider >= 5.0

3. 域名准备（可选）：

   • 如需使用自定义域名，需要在 Route 53 中有托管区域

快速开始

1. 初始化 Terraform：

   terraform init

2. 配置变量：

   cp terraform.tfvars.example terraform.tfvars
   # 编辑 terraform.tfvars，填入必要的配置

3. 部署到开发环境：

   terraform plan -var-file="environments/dev.tfvars"
   terraform apply -var-file="environments/dev.tfvars"

4. 部署到生产环境：

   terraform plan -var-file="environments/prod.tfvars"
   terraform apply -var-file="environments/prod.tfvars"

自动化部署

使用提供的部署脚本：

./deploy.sh dev   # 部署到开发环境
./deploy.sh prod  # 部署到生产环境

主要配置变量

变量名	描述	默认值
project_name	项目名称	ten-agent
environment	环境名称	dev
aws_region	AWS 区域	us-east-1
domain_name	自定义域名	"" (可选)
enable_route53	启用 Route 53	false
app_server_cpu	应用服务器 CPU	512
app_server_memory	应用服务器内存	1024
app_server_count	应用服务器数量	2

详细配置请参阅 terraform-README.md 文件。

输出信息

部署完成后，Terraform 将输出：

• ALB DNS 名称
• 应用访问 URL
• ECS 集群名称
• VPC ID
• 子网 ID 列表
• 安全组 ID

架构说明

                                    Internet
                                        |
                                   [Route 53]
                                        |
                                    [ACM Cert]
                                        |
                            [Application Load Balancer]
                                   /    |    \
                                  /     |     \
                       [Target Group] [TG] [TG]
                              |         |     |
                        [ECS Service] [Service] [Service]
                              |         |     |
                        [Fargate Task] [Task] [Task]
                              |         |     |
                        [Container] [Container] [Container]
                              |         |     |
                    [Secrets Manager] [SM] [SM]

资源清单

• 网络资源：VPC、公有/私有子网、Internet 网关、NAT 网关
• 计算资源：ECS 集群、ECS 服务、Fargate 任务
• 负载均衡：Application Load Balancer、目标组、监听器
• 安全：安全组、IAM 角色、AWS Secrets Manager
• DNS：Route 53 托管区域和记录（可选）
• 证书：ACM SSL/TLS 证书（可选）

成本估算

开发环境（最小配置）：

• ECS Fargate：~$30-50/月
• NAT 网关：~$32/月
• ALB：~$16/月
• 其他服务：~$10/月
• 总计：~$88-108/月

生产环境会根据实例数量和规格增加。

测试建议

1. 先在开发环境测试部署
2. 验证所有服务正常运行
3. 检查日志输出
4. 测试负载均衡和健康检查
5. 验证域名和 SSL 证书（如配置）
6. 确认后再部署到生产环境

注意事项

⚠️ 重要提醒：

1. 首次部署前务必检查 terraform.tfvars 配置
2. 生产环境部署前务必备份现有数据
3. AWS Secrets Manager 中需要手动设置 secret 的实际值
4. 删除资源前注意数据备份
5. 注意 AWS 资源产生的费用

相关文档

• 📘 完整使用文档
• 🚀 快速入门指南
• 📁 文件结构说明
• 🔧 部署流程说明
• 📑 索引导航

后续计划

• 添加 CloudWatch 监控和告警配置
• 添加自动扩缩容策略
• 集成 CI/CD 管道
• 添加备份和恢复策略
• 优化成本和性能

---

测试状态：⚠️ 需要在 AWS 环境中进行验证

影响范围：新增功能，不影响现有代码

部署风险：低（新增配置文件，需要手动执行 Terraform 命令）