@umacloud/knowledge 1.0.1

package/devops/01-standards/terraform-complete.md

@@ -0,0 +1,2117 @@
+---
+id: terraform-complete
+title: Terraform 完整指南
+domain: devops
+category: 01-standards
+difficulty: intermediate
+tags: [complete, devops, terraform, 实战配置, 工作流, 核心概念, 概述, 模块设计]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Terraform 完整指南
+
+> 文档版本: v1.0 | 最后更新: 2026-03-28 | 适用范围: Terraform 1.6+ / OpenTofu 1.6+
+
+---
+
+## 目录
+
+1. [概述](#概述)
+2. [核心概念](#核心概念)
+3. [HCL 语法详解](#hcl-语法详解)
+4. [状态管理](#状态管理)
+5. [模块设计](#模块设计)
+6. [工作流](#工作流)
+7. [AWS 实战配置](#aws-实战配置)
+8. [安全](#安全)
+9. [CI/CD 集成](#cicd-集成)
+10. [团队协作](#团队协作)
+11. [性能优化](#性能优化)
+12. [常见陷阱与反模式](#常见陷阱与反模式)
+13. [Agent Checklist](#agent-checklist)
+
+---
+
+## 概述
+
+### IaC 理念
+
+Infrastructure as Code (IaC) 将基础设施的定义、部署和管理全部代码化，像管理应用代码一样管理基础设施。核心原则：
+
+- **声明式定义**：描述期望状态而非操作步骤，Terraform 自动计算差异并执行变更
+- **版本控制**：所有基础设施变更通过 Git 追踪，可审计、可回溯
+- **可重复性**：同一套代码在任意环境产生一致的结果，消除手动配置漂移
+- **自文档化**：代码本身就是基础设施的文档，无需额外维护配置清单
+- **协作友好**：变更通过 PR 审查，团队共享统一的基础设施定义
+
+### Terraform vs 竞品对比
+
+| 维度 | Terraform / OpenTofu | Pulumi | CloudFormation | Ansible |
+|------|---------------------|--------|----------------|---------|
+| 语言 | HCL (声明式 DSL) | Python/TS/Go/C# 等通用语言 | JSON/YAML | YAML (过程式) |
+| 云支持 | 多云 (3000+ Provider) | 多云 | 仅 AWS | 多云 (侧重配置管理) |
+| 状态管理 | 显式 State 文件 | 托管 / 自管 State | AWS 托管 | 无状态 (幂等模块) |
+| 学习曲线 | 中等 (HCL 专用语法) | 低 (复用已有语言) | 中高 (AWS 绑定) | 低 (YAML 编排) |
+| Plan/Preview | `terraform plan` 原生支持 | `pulumi preview` | Change Sets | `--check` 模式 |
+| 模块生态 | Terraform Registry 海量模块 | Pulumi Registry | AWS 嵌套栈 / Modules | Ansible Galaxy |
+| 适合场景 | 基础设施编排 (网络/计算/存储) | 复杂逻辑 + 基础设施 | 纯 AWS 环境 | 配置管理 + 应用部署 |
+| 开源协议 | BSL 1.1 (Terraform) / MPL 2.0 (OpenTofu) | Apache 2.0 | 闭源 | GPL 3.0 |
+
+**选型建议**：
+- 多云 / 混合云基础设施编排 → Terraform / OpenTofu
+- 团队已有强 Python/TS 背景且逻辑复杂 → Pulumi
+- 纯 AWS 且已深度使用 AWS 服务 → CloudFormation
+- 服务器配置管理 + 应用部署 → Ansible
+- Terraform 负责基础设施层，Ansible 负责配置层，二者常配合使用
+
+---
+
+## 核心概念
+
+### Provider
+
+Provider 是 Terraform 与外部 API 交互的插件。每个云平台、SaaS 服务或内部系统都有对应的 Provider。
+
+```hcl
+# 声明 Provider 及版本约束
+terraform {
+  required_version = ">= 1.6.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.40"  # 允许 5.40.x 补丁更新
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.6.0, < 4.0.0"
+    }
+  }
+}
+
+# 配置 Provider
+provider "aws" {
+  region = var.aws_region
+
+  default_tags {
+    tags = {
+      Environment = var.environment
+      ManagedBy   = "terraform"
+      Project     = var.project_name
+    }
+  }
+}
+
+# 多 Provider 实例 (alias)
+provider "aws" {
+  alias  = "us_west"
+  region = "us-west-2"
+}
+```
+
+### Resource
+
+Resource 是 Terraform 管理的核心对象，代表一个基础设施组件。
+
+```hcl
+resource "aws_instance" "web" {
+  ami           = data.aws_ami.ubuntu.id
+  instance_type = var.instance_type
+  subnet_id     = aws_subnet.public[0].id
+
+  vpc_security_group_ids = [aws_security_group.web.id]
+
+  root_block_device {
+    volume_size = 20
+    volume_type = "gp3"
+    encrypted   = true
+  }
+
+  tags = {
+    Name = "${var.project_name}-web"
+  }
+
+  lifecycle {
+    create_before_destroy = true
+    prevent_destroy       = false
+    ignore_changes        = [ami]  # AMI 更新由其他流程管理
+  }
+}
+```
+
+### Data Source
+
+Data Source 用于查询外部信息，不创建资源。
+
+```hcl
+# 查询最新 Ubuntu AMI
+data "aws_ami" "ubuntu" {
+  most_recent = true
+  owners      = ["099720109477"]  # Canonical
+
+  filter {
+    name   = "name"
+    values = ["ubuntu/images/hvm-ssd/ubuntu-*-22.04-amd64-server-*"]
+  }
+
+  filter {
+    name   = "virtualization-type"
+    values = ["hvm"]
+  }
+}
+
+# 查询当前 AWS 账户信息
+data "aws_caller_identity" "current" {}
+
+# 查询可用区
+data "aws_availability_zones" "available" {
+  state = "available"
+}
+```
+
+### Variable
+
+输入变量定义模块的参数化接口。
+
+```hcl
+variable "environment" {
+  description = "Deployment environment (dev/staging/prod)"
+  type        = string
+
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Environment must be one of: dev, staging, prod."
+  }
+}
+
+variable "instance_count" {
+  description = "Number of EC2 instances to create"
+  type        = number
+  default     = 2
+
+  validation {
+    condition     = var.instance_count >= 1 && var.instance_count <= 20
+    error_message = "Instance count must be between 1 and 20."
+  }
+}
+
+variable "allowed_cidrs" {
+  description = "List of CIDR blocks allowed to access the service"
+  type        = list(string)
+  default     = []
+}
+
+variable "tags" {
+  description = "Additional tags to apply to all resources"
+  type        = map(string)
+  default     = {}
+}
+```
+
+### Output
+
+输出值暴露模块的计算结果，供其他模块引用或展示给用户。
+
+```hcl
+output "instance_ids" {
+  description = "IDs of created EC2 instances"
+  value       = aws_instance.web[*].id
+}
+
+output "load_balancer_dns" {
+  description = "DNS name of the load balancer"
+  value       = aws_lb.main.dns_name
+}
+
+output "database_endpoint" {
+  description = "RDS instance endpoint"
+  value       = aws_db_instance.main.endpoint
+  sensitive   = true  # 不在 CLI 输出中显示
+}
+```
+
+### Local
+
+Local 值用于中间计算，简化重复表达式。
+
+```hcl
+locals {
+  # 通用标签合并
+  common_tags = merge(var.tags, {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Project     = var.project_name
+  })
+
+  # 根据环境选择实例规格
+  instance_type = {
+    dev     = "t3.micro"
+    staging = "t3.small"
+    prod    = "t3.medium"
+  }[var.environment]
+
+  # 可用区列表
+  azs = slice(data.aws_availability_zones.available.names, 0, 3)
+
+  # CIDR 计算
+  private_subnets = [for i, az in local.azs : cidrsubnet(var.vpc_cidr, 8, i)]
+  public_subnets  = [for i, az in local.azs : cidrsubnet(var.vpc_cidr, 8, i + 100)]
+}
+```
+
+### Module
+
+模块是可复用的 Terraform 配置包，封装一组相关资源。
+
+```hcl
+# 调用本地模块
+module "vpc" {
+  source = "./modules/vpc"
+
+  vpc_cidr     = "10.0.0.0/16"
+  environment  = var.environment
+  project_name = var.project_name
+}
+
+# 调用 Registry 模块
+module "eks" {
+  source  = "terraform-aws-modules/eks/aws"
+  version = "~> 20.0"
+
+  cluster_name    = "${var.project_name}-${var.environment}"
+  cluster_version = "1.29"
+  vpc_id          = module.vpc.vpc_id
+  subnet_ids      = module.vpc.private_subnet_ids
+}
+```
+
+---
+
+## HCL 语法详解
+
+### 类型系统
+
+HCL 具备完整的类型系统，支持原始类型和复合类型。
+
+```hcl
+# 原始类型
+variable "name"    { type = string }
+variable "count"   { type = number }
+variable "enabled" { type = bool }
+
+# 集合类型
+variable "cidrs"       { type = list(string) }
+variable "ports"       { type = set(number) }
+variable "tags"        { type = map(string) }
+
+# 结构化类型
+variable "database" {
+  type = object({
+    engine         = string
+    engine_version = string
+    instance_class = string
+    storage_gb     = number
+    multi_az       = bool
+    backup_retention = optional(number, 7)  # 可选字段 + 默认值
+  })
+}
+
+# 元组类型 (固定长度、异构)
+variable "rule" {
+  type = tuple([string, number, string])
+  # 例: ["tcp", 443, "0.0.0.0/0"]
+}
+
+# any 类型 (推迟到运行时推断)
+variable "flexible_input" {
+  type    = any
+  default = null
+}
+```
+
+### 表达式
+
+```hcl
+# 字符串插值
+resource "aws_instance" "app" {
+  tags = {
+    Name = "${var.project_name}-${var.environment}-app-${count.index + 1}"
+  }
+}
+
+# 多行字符串 (heredoc)
+resource "aws_iam_policy" "example" {
+  policy = <<-EOT
+    {
+      "Version": "2012-10-17",
+      "Statement": [
+        {
+          "Effect": "Allow",
+          "Action": "s3:GetObject",
+          "Resource": "arn:aws:s3:::${var.bucket_name}/*"
+        }
+      ]
+    }
+  EOT
+}
+
+# 引用其他资源
+resource "aws_security_group_rule" "ingress" {
+  security_group_id = aws_security_group.web.id   # 引用另一个资源的属性
+  source_security_group_id = module.alb.security_group_id  # 引用模块输出
+}
+```
+
+### 内置函数
+
+```hcl
+locals {
+  # 字符串函数
+  upper_env   = upper(var.environment)           # "PROD"
+  name_parts  = split("-", var.resource_name)    # ["my", "app"]
+  joined      = join(", ", var.cidrs)            # "10.0.0.0/8, 172.16.0.0/12"
+  trimmed     = trimspace("  hello  ")           # "hello"
+  replaced    = replace(var.name, "/", "-")      # 替换字符
+
+  # 数值函数
+  max_val     = max(5, 12, 9)                    # 12
+  min_val     = min(var.min_size, 10)            # 取较小值
+  ceiling     = ceil(7.3)                        # 8
+
+  # 集合函数
+  flat_list   = flatten([var.public_subnets, var.private_subnets])
+  unique_list = distinct(var.regions)
+  merged_map  = merge(local.default_tags, var.extra_tags)
+  keys_list   = keys(var.tags)
+  values_list = values(var.tags)
+  sorted      = sort(var.names)
+  lookup_val  = lookup(var.instance_map, "web", "t3.micro")  # 带默认值的 map 查找
+  contains_it = contains(var.allowed_envs, "prod")
+
+  # 编码函数
+  json_policy = jsonencode({
+    Version   = "2012-10-17"
+    Statement = [{ Effect = "Allow", Action = "*", Resource = "*" }]
+  })
+  b64_encoded = base64encode("hello world")
+  yaml_config = yamlencode({ key = "value", list = [1, 2, 3] })
+
+  # 文件函数
+  user_data   = file("${path.module}/scripts/init.sh")
+  template    = templatefile("${path.module}/templates/config.tpl", {
+    db_host = aws_db_instance.main.address
+    db_port = aws_db_instance.main.port
+  })
+
+  # 网络函数
+  subnet_cidr = cidrsubnet("10.0.0.0/16", 8, 1)   # "10.0.1.0/24"
+  host_ip     = cidrhost("10.0.1.0/24", 5)         # "10.0.1.5"
+
+  # 类型转换
+  str_to_num  = tonumber("42")
+  num_to_str  = tostring(42)
+  to_set      = toset(["a", "b", "a"])              # 去重
+}
+```
+
+### 动态块 (Dynamic Block)
+
+```hcl
+# 动态生成安全组规则
+resource "aws_security_group" "web" {
+  name        = "${var.project_name}-web-sg"
+  description = "Security group for web tier"
+  vpc_id      = module.vpc.vpc_id
+
+  dynamic "ingress" {
+    for_each = var.ingress_rules
+    content {
+      description = ingress.value.description
+      from_port   = ingress.value.port
+      to_port     = ingress.value.port
+      protocol    = ingress.value.protocol
+      cidr_blocks = ingress.value.cidr_blocks
+    }
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}
+
+# 对应的变量定义
+variable "ingress_rules" {
+  type = list(object({
+    description = string
+    port        = number
+    protocol    = string
+    cidr_blocks = list(string)
+  }))
+  default = [
+    { description = "HTTPS", port = 443, protocol = "tcp", cidr_blocks = ["0.0.0.0/0"] },
+    { description = "HTTP",  port = 80,  protocol = "tcp", cidr_blocks = ["0.0.0.0/0"] },
+  ]
+}
+```
+
+### for_each vs count
+
+```hcl
+# --- count: 基于数量的简单迭代 ---
+resource "aws_instance" "worker" {
+  count = var.worker_count
+
+  ami           = data.aws_ami.ubuntu.id
+  instance_type = "t3.medium"
+  subnet_id     = element(module.vpc.private_subnet_ids, count.index)
+
+  tags = {
+    Name = "${var.project_name}-worker-${count.index + 1}"
+  }
+}
+
+# --- for_each: 基于集合的迭代 (推荐) ---
+# 使用 map 实现不同配置
+variable "instances" {
+  type = map(object({
+    instance_type = string
+    subnet_tier   = string
+  }))
+  default = {
+    web = { instance_type = "t3.small", subnet_tier = "public" }
+    api = { instance_type = "t3.medium", subnet_tier = "private" }
+    worker = { instance_type = "t3.large", subnet_tier = "private" }
+  }
+}
+
+resource "aws_instance" "app" {
+  for_each = var.instances
+
+  ami           = data.aws_ami.ubuntu.id
+  instance_type = each.value.instance_type
+  subnet_id     = each.value.subnet_tier == "public" ? module.vpc.public_subnet_ids[0] : module.vpc.private_subnet_ids[0]
+
+  tags = {
+    Name = "${var.project_name}-${each.key}"
+    Role = each.key
+  }
+}
+
+# --- for 表达式 ---
+locals {
+  # 列表推导
+  instance_ids = [for inst in aws_instance.app : inst.id]
+
+  # Map 推导
+  instance_ip_map = { for k, inst in aws_instance.app : k => inst.private_ip }
+
+  # 带过滤的推导
+  public_instances = { for k, v in var.instances : k => v if v.subnet_tier == "public" }
+
+  # 嵌套推导
+  sg_rules = flatten([
+    for name, config in var.services : [
+      for port in config.ports : {
+        name = name
+        port = port
+      }
+    ]
+  ])
+}
+```
+
+### 条件表达式
+
+```hcl
+# 三元运算符
+resource "aws_instance" "app" {
+  instance_type = var.environment == "prod" ? "t3.large" : "t3.micro"
+}
+
+# 条件创建资源 (count)
+resource "aws_cloudwatch_metric_alarm" "high_cpu" {
+  count = var.environment == "prod" ? 1 : 0
+
+  alarm_name  = "${var.project_name}-high-cpu"
+  namespace   = "AWS/EC2"
+  metric_name = "CPUUtilization"
+  # ...
+}
+
+# 条件创建资源 (for_each)
+resource "aws_route53_record" "alias" {
+  for_each = var.create_dns ? toset(["main"]) : toset([])
+
+  zone_id = var.zone_id
+  name    = var.domain_name
+  type    = "A"
+  # ...
+}
+
+# 条件输出
+output "bastion_ip" {
+  value = var.enable_bastion ? aws_instance.bastion[0].public_ip : null
+}
+```
+
+---
+
+## 状态管理
+
+### Remote State
+
+**State 文件包含敏感信息，严禁提交到 Git。** 生产环境必须使用 Remote Backend。
+
+```hcl
+# S3 Backend (推荐用于 AWS)
+terraform {
+  backend "s3" {
+    bucket         = "mycompany-terraform-state"
+    key            = "prod/vpc/terraform.tfstate"
+    region         = "ap-northeast-1"
+    encrypt        = true
+    dynamodb_table = "terraform-state-lock"  # State Locking
+    # 启用版本控制以支持状态回滚
+  }
+}
+
+# 创建 Backend 基础设施 (Bootstrap, 单独管理)
+resource "aws_s3_bucket" "terraform_state" {
+  bucket = "mycompany-terraform-state"
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+
+resource "aws_s3_bucket_versioning" "terraform_state" {
+  bucket = aws_s3_bucket.terraform_state.id
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "terraform_state" {
+  bucket = aws_s3_bucket.terraform_state.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "aws:kms"
+    }
+  }
+}
+
+resource "aws_dynamodb_table" "terraform_lock" {
+  name         = "terraform-state-lock"
+  billing_mode = "PAY_PER_REQUEST"
+  hash_key     = "LockID"
+
+  attribute {
+    name = "LockID"
+    type = "S"
+  }
+}
+```
+
+### State Locking
+
+State Locking 防止多人同时操作导致状态损坏。
+
+- **S3 Backend**：DynamoDB 表实现锁
+- **GCS Backend**：原生支持锁
+- **Terraform Cloud / Enterprise**：内置锁管理
+- **强制解锁**（仅在锁残留时使用）：`terraform force-unlock <LOCK_ID>`
+
+### State 迁移
+
+```bash
+# 从 local 迁移到 S3
+# 1. 添加 backend "s3" 配置
+# 2. 执行初始化迁移
+terraform init -migrate-state
+
+# 在 backend 之间迁移
+terraform init -migrate-state -force-copy
+
+# 导出当前状态
+terraform state pull > terraform.tfstate.backup
+
+# 推送状态 (谨慎使用)
+terraform state push terraform.tfstate
+```
+
+### State 操作
+
+```bash
+# 列出所有资源
+terraform state list
+
+# 查看资源详情
+terraform state show aws_instance.web
+
+# 移动资源 (重命名/移入模块)
+terraform state mv aws_instance.web aws_instance.app
+terraform state mv aws_instance.web module.compute.aws_instance.web
+
+# 从状态中移除 (不删除实际资源)
+terraform state rm aws_instance.legacy
+
+# 导入已有资源到 Terraform 管理
+terraform import aws_instance.web i-1234567890abcdef0
+
+# Terraform 1.5+ 声明式 import
+import {
+  to = aws_instance.web
+  id = "i-1234567890abcdef0"
+}
+
+# taint: 标记资源需要重建 (下次 apply 时)
+terraform taint aws_instance.web
+
+# untaint: 取消 taint 标记
+terraform untaint aws_instance.web
+
+# Terraform 1.6+ 推荐使用 -replace 替代 taint
+terraform apply -replace="aws_instance.web"
+```
+
+---
+
+## 模块设计
+
+### 标准模块结构
+
+```
+modules/
+└── vpc/
+    ├── main.tf          # 核心资源定义
+    ├── variables.tf     # 输入变量
+    ├── outputs.tf       # 输出值
+    ├── versions.tf      # Provider 版本约束
+    ├── locals.tf        # 本地变量
+    ├── data.tf          # Data Source
+    ├── README.md        # 模块文档 (terraform-docs 自动生成)
+    └── examples/        # 使用示例
+        └── simple/
+            └── main.tf
+```
+
+### 模块输入输出设计
+
+```hcl
+# modules/vpc/variables.tf
+variable "vpc_cidr" {
+  description = "CIDR block for the VPC"
+  type        = string
+
+  validation {
+    condition     = can(cidrhost(var.vpc_cidr, 0))
+    error_message = "Must be a valid CIDR block."
+  }
+}
+
+variable "enable_nat_gateway" {
+  description = "Whether to create NAT Gateway for private subnets"
+  type        = bool
+  default     = true
+}
+
+variable "single_nat_gateway" {
+  description = "Use a single NAT Gateway instead of one per AZ (cost saving for non-prod)"
+  type        = bool
+  default     = false
+}
+
+# modules/vpc/outputs.tf
+output "vpc_id" {
+  description = "The ID of the VPC"
+  value       = aws_vpc.main.id
+}
+
+output "private_subnet_ids" {
+  description = "List of private subnet IDs"
+  value       = aws_subnet.private[*].id
+}
+
+output "public_subnet_ids" {
+  description = "List of public subnet IDs"
+  value       = aws_subnet.public[*].id
+}
+
+output "nat_gateway_ips" {
+  description = "Elastic IPs of the NAT Gateways"
+  value       = aws_eip.nat[*].public_ip
+}
+```
+
+### 版本约束
+
+```hcl
+# 精确版本
+module "vpc" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "5.5.3"
+}
+
+# 补丁版本范围
+module "eks" {
+  source  = "terraform-aws-modules/eks/aws"
+  version = "~> 20.8"  # >= 20.8.0, < 21.0.0
+}
+
+# 版本范围
+module "rds" {
+  source  = "terraform-aws-modules/rds/aws"
+  version = ">= 6.0.0, < 7.0.0"
+}
+
+# Git 源 (含版本标签)
+module "custom" {
+  source = "git::https://github.com/myorg/terraform-modules.git//modules/custom?ref=v2.1.0"
+}
+```
+
+### 模块组合模式
+
+```hcl
+# 根模块组合多个子模块
+module "networking" {
+  source = "./modules/vpc"
+
+  vpc_cidr           = var.vpc_cidr
+  environment        = var.environment
+  enable_nat_gateway = var.environment == "prod"
+  single_nat_gateway = var.environment != "prod"
+}
+
+module "database" {
+  source = "./modules/rds"
+
+  vpc_id             = module.networking.vpc_id
+  subnet_ids         = module.networking.private_subnet_ids
+  instance_class     = local.instance_type
+  environment        = var.environment
+  multi_az           = var.environment == "prod"
+}
+
+module "compute" {
+  source = "./modules/ecs"
+
+  vpc_id             = module.networking.vpc_id
+  private_subnet_ids = module.networking.private_subnet_ids
+  public_subnet_ids  = module.networking.public_subnet_ids
+  db_endpoint        = module.database.endpoint
+  environment        = var.environment
+}
+```
+
+---
+
+## 工作流
+
+### 核心命令
+
+```bash
+# 初始化: 下载 Provider + 模块 + 初始化 Backend
+terraform init
+terraform init -upgrade          # 升级 Provider 到约束范围内最新版
+terraform init -reconfigure      # 重新配置 Backend (忽略已有配置)
+
+# 格式化
+terraform fmt                    # 格式化当前目录
+terraform fmt -recursive         # 递归格式化所有子目录
+terraform fmt -check             # 仅检查格式 (CI 用)
+
+# 验证
+terraform validate               # 语法 + 类型检查 (不连接远端)
+
+# 计划
+terraform plan                   # 预览变更
+terraform plan -out=tfplan       # 保存计划到文件 (推荐用于 CI/CD)
+terraform plan -target=aws_instance.web  # 仅计划特定资源
+terraform plan -var="environment=prod"   # 传入变量
+
+# 执行
+terraform apply                  # 交互式确认后执行
+terraform apply tfplan           # 执行保存的计划 (无需再次确认)
+terraform apply -auto-approve    # 跳过确认 (仅用于自动化流水线)
+terraform apply -replace="aws_instance.web"  # 强制重建指定资源
+
+# 销毁
+terraform destroy                # 销毁所有资源
+terraform destroy -target=aws_instance.web   # 仅销毁指定资源
+
+# 输出
+terraform output                 # 显示所有输出
+terraform output -json           # JSON 格式输出
+terraform output database_endpoint  # 查看单个输出
+
+# 依赖图
+terraform graph | dot -Tpng > graph.png  # 生成资源依赖图
+```
+
+### Workspace
+
+Workspace 用于在同一配置中管理多个环境的状态（轻量级方案）。
+
+```bash
+# 创建并切换到新 workspace
+terraform workspace new dev
+terraform workspace new staging
+terraform workspace new prod
+
+# 列出所有 workspace
+terraform workspace list
+
+# 切换 workspace
+terraform workspace select prod
+
+# 在配置中使用 workspace
+# main.tf
+locals {
+  env = terraform.workspace
+}
+```
+
+**注意**：对于复杂项目，推荐使用目录分离（`environments/dev/`、`environments/prod/`）而非 workspace，因为不同环境往往有不同的资源组合。
+
+---
+
+## AWS 实战配置
+
+### VPC 完整配置
+
+```hcl
+resource "aws_vpc" "main" {
+  cidr_block           = var.vpc_cidr
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-${var.environment}-vpc"
+  })
+}
+
+# 公有子网 (多 AZ)
+resource "aws_subnet" "public" {
+  count = length(local.azs)
+
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = local.public_subnets[count.index]
+  availability_zone       = local.azs[count.index]
+  map_public_ip_on_launch = true
+
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-public-${local.azs[count.index]}"
+    Tier = "public"
+    "kubernetes.io/role/elb" = "1"  # EKS ALB 发现标签
+  })
+}
+
+# 私有子网 (多 AZ)
+resource "aws_subnet" "private" {
+  count = length(local.azs)
+
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = local.private_subnets[count.index]
+  availability_zone = local.azs[count.index]
+
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-private-${local.azs[count.index]}"
+    Tier = "private"
+    "kubernetes.io/role/internal-elb" = "1"
+  })
+}
+
+# Internet Gateway
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-igw"
+  })
+}
+
+# NAT Gateway (每个 AZ 一个，生产环境高可用)
+resource "aws_eip" "nat" {
+  count  = var.single_nat_gateway ? 1 : length(local.azs)
+  domain = "vpc"
+
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-nat-eip-${count.index + 1}"
+  })
+}
+
+resource "aws_nat_gateway" "main" {
+  count = var.single_nat_gateway ? 1 : length(local.azs)
+
+  allocation_id = aws_eip.nat[count.index].id
+  subnet_id     = aws_subnet.public[count.index].id
+
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-nat-${count.index + 1}"
+  })
+
+  depends_on = [aws_internet_gateway.main]
+}
+
+# 路由表
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block = "0.0.0.0/0"
+    gateway_id = aws_internet_gateway.main.id
+  }
+
+  tags = merge(local.common_tags, { Name = "${var.project_name}-public-rt" })
+}
+
+resource "aws_route_table" "private" {
+  count  = var.single_nat_gateway ? 1 : length(local.azs)
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block     = "0.0.0.0/0"
+    nat_gateway_id = aws_nat_gateway.main[var.single_nat_gateway ? 0 : count.index].id
+  }
+
+  tags = merge(local.common_tags, { Name = "${var.project_name}-private-rt-${count.index + 1}" })
+}
+
+resource "aws_route_table_association" "public" {
+  count          = length(local.azs)
+  subnet_id      = aws_subnet.public[count.index].id
+  route_table_id = aws_route_table.public.id
+}
+
+resource "aws_route_table_association" "private" {
+  count          = length(local.azs)
+  subnet_id      = aws_subnet.private[count.index].id
+  route_table_id = aws_route_table.private[var.single_nat_gateway ? 0 : count.index].id
+}
+```
+
+### RDS 配置
+
+```hcl
+resource "aws_db_subnet_group" "main" {
+  name       = "${var.project_name}-db-subnet"
+  subnet_ids = aws_subnet.private[*].id
+
+  tags = local.common_tags
+}
+
+resource "aws_db_instance" "main" {
+  identifier = "${var.project_name}-${var.environment}"
+
+  engine               = "postgres"
+  engine_version       = "16.2"
+  instance_class       = var.environment == "prod" ? "db.r6g.large" : "db.t3.micro"
+  allocated_storage    = 20
+  max_allocated_storage = var.environment == "prod" ? 200 : 50  # Auto-scaling 上限
+
+  db_name  = var.db_name
+  username = var.db_username
+  password = var.db_password  # 建议通过 Secrets Manager 管理
+
+  db_subnet_group_name   = aws_db_subnet_group.main.name
+  vpc_security_group_ids = [aws_security_group.db.id]
+
+  multi_az               = var.environment == "prod"
+  storage_encrypted      = true
+  deletion_protection    = var.environment == "prod"
+  skip_final_snapshot    = var.environment != "prod"
+  final_snapshot_identifier = var.environment == "prod" ? "${var.project_name}-final-snapshot" : null
+
+  backup_retention_period = var.environment == "prod" ? 35 : 7
+  backup_window           = "03:00-04:00"
+  maintenance_window      = "Mon:04:00-Mon:05:00"
+
+  performance_insights_enabled = var.environment == "prod"
+
+  tags = local.common_tags
+
+  lifecycle {
+    ignore_changes = [password]  # 密码由外部管理
+  }
+}
+```
+
+### S3 配置
+
+```hcl
+resource "aws_s3_bucket" "assets" {
+  bucket = "${var.project_name}-${var.environment}-assets"
+
+  tags = local.common_tags
+}
+
+resource "aws_s3_bucket_versioning" "assets" {
+  bucket = aws_s3_bucket.assets.id
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "assets" {
+  bucket = aws_s3_bucket.assets.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+    bucket_key_enabled = true
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "assets" {
+  bucket = aws_s3_bucket.assets.id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_lifecycle_configuration" "assets" {
+  bucket = aws_s3_bucket.assets.id
+
+  rule {
+    id     = "transition-to-ia"
+    status = "Enabled"
+
+    transition {
+      days          = 90
+      storage_class = "STANDARD_IA"
+    }
+
+    transition {
+      days          = 180
+      storage_class = "GLACIER"
+    }
+
+    noncurrent_version_expiration {
+      noncurrent_days = 90
+    }
+  }
+}
+```
+
+### IAM 配置
+
+```hcl
+# ECS Task Role
+resource "aws_iam_role" "ecs_task" {
+  name = "${var.project_name}-${var.environment}-ecs-task"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "sts:AssumeRole"
+        Effect = "Allow"
+        Principal = {
+          Service = "ecs-tasks.amazonaws.com"
+        }
+      }
+    ]
+  })
+
+  tags = local.common_tags
+}
+
+# 最小权限策略
+resource "aws_iam_role_policy" "ecs_task" {
+  name = "${var.project_name}-ecs-task-policy"
+  role = aws_iam_role.ecs_task.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "s3:GetObject",
+          "s3:PutObject",
+          "s3:ListBucket"
+        ]
+        Resource = [
+          aws_s3_bucket.assets.arn,
+          "${aws_s3_bucket.assets.arn}/*"
+        ]
+      },
+      {
+        Effect = "Allow"
+        Action = [
+          "secretsmanager:GetSecretValue"
+        ]
+        Resource = [
+          "arn:aws:secretsmanager:${var.aws_region}:${data.aws_caller_identity.current.account_id}:secret:${var.project_name}/*"
+        ]
+      }
+    ]
+  })
+}
+```
+
+### ALB 配置
+
+```hcl
+resource "aws_lb" "main" {
+  name               = "${var.project_name}-${var.environment}-alb"
+  internal           = false
+  load_balancer_type = "application"
+  security_groups    = [aws_security_group.alb.id]
+  subnets            = aws_subnet.public[*].id
+
+  enable_deletion_protection = var.environment == "prod"
+
+  access_logs {
+    bucket  = aws_s3_bucket.alb_logs.id
+    prefix  = "alb"
+    enabled = true
+  }
+
+  tags = local.common_tags
+}
+
+resource "aws_lb_listener" "https" {
+  load_balancer_arn = aws_lb.main.arn
+  port              = 443
+  protocol          = "HTTPS"
+  ssl_policy        = "ELBSecurityPolicy-TLS13-1-2-2021-06"
+  certificate_arn   = var.acm_certificate_arn
+
+  default_action {
+    type             = "forward"
+    target_group_arn = aws_lb_target_group.app.arn
+  }
+}
+
+resource "aws_lb_listener" "http_redirect" {
+  load_balancer_arn = aws_lb.main.arn
+  port              = 80
+  protocol          = "HTTP"
+
+  default_action {
+    type = "redirect"
+    redirect {
+      port        = "443"
+      protocol    = "HTTPS"
+      status_code = "HTTP_301"
+    }
+  }
+}
+
+resource "aws_lb_target_group" "app" {
+  name        = "${var.project_name}-${var.environment}-tg"
+  port        = 8080
+  protocol    = "HTTP"
+  vpc_id      = aws_vpc.main.id
+  target_type = "ip"
+
+  health_check {
+    enabled             = true
+    healthy_threshold   = 3
+    unhealthy_threshold = 3
+    timeout             = 5
+    interval            = 30
+    path                = "/health"
+    matcher             = "200"
+  }
+
+  deregistration_delay = 60
+
+  tags = local.common_tags
+}
+```
+
+### EKS 配置
+
+```hcl
+module "eks" {
+  source  = "terraform-aws-modules/eks/aws"
+  version = "~> 20.8"
+
+  cluster_name    = "${var.project_name}-${var.environment}"
+  cluster_version = "1.29"
+
+  vpc_id     = module.networking.vpc_id
+  subnet_ids = module.networking.private_subnet_ids
+
+  # 集群访问控制
+  cluster_endpoint_public_access  = true
+  cluster_endpoint_private_access = true
+  cluster_endpoint_public_access_cidrs = var.environment == "prod" ? var.allowed_cidrs : ["0.0.0.0/0"]
+
+  # 集群插件
+  cluster_addons = {
+    coredns = {
+      most_recent = true
+    }
+    kube-proxy = {
+      most_recent = true
+    }
+    vpc-cni = {
+      most_recent              = true
+      service_account_role_arn = module.vpc_cni_irsa.iam_role_arn
+    }
+  }
+
+  # 托管节点组
+  eks_managed_node_groups = {
+    general = {
+      instance_types = ["t3.large"]
+      capacity_type  = var.environment == "prod" ? "ON_DEMAND" : "SPOT"
+      min_size       = var.environment == "prod" ? 3 : 1
+      max_size       = var.environment == "prod" ? 10 : 3
+      desired_size   = var.environment == "prod" ? 3 : 1
+
+      labels = {
+        Environment = var.environment
+        NodeGroup   = "general"
+      }
+
+      tags = local.common_tags
+    }
+  }
+
+  tags = local.common_tags
+}
+```
+
+---
+
+## 安全
+
+### Secrets 管理
+
+```hcl
+# 严禁在代码中硬编码密码 -- 使用 AWS Secrets Manager
+resource "aws_secretsmanager_secret" "db_password" {
+  name                    = "${var.project_name}/${var.environment}/db-password"
+  recovery_window_in_days = var.environment == "prod" ? 30 : 0
+  tags                    = local.common_tags
+}
+
+resource "aws_secretsmanager_secret_version" "db_password" {
+  secret_id     = aws_secretsmanager_secret.db_password.id
+  secret_string = random_password.db.result
+}
+
+resource "random_password" "db" {
+  length  = 32
+  special = true
+  override_special = "!#$%^&*()-_=+"
+}
+
+# 在 RDS 中引用
+resource "aws_db_instance" "main" {
+  # ...
+  password = random_password.db.result
+  # ...
+}
+```
+
+### Sensitive 变量
+
+```hcl
+variable "db_password" {
+  description = "Database master password"
+  type        = string
+  sensitive   = true  # 不会出现在 plan / apply 输出中
+}
+
+output "db_connection_string" {
+  value     = "postgresql://${var.db_username}:${var.db_password}@${aws_db_instance.main.endpoint}/${var.db_name}"
+  sensitive = true
+}
+```
+
+### Vault 集成
+
+```hcl
+provider "vault" {
+  address = var.vault_address
+  # 认证通过环境变量 VAULT_TOKEN 或 AppRole
+}
+
+data "vault_generic_secret" "db" {
+  path = "secret/data/${var.environment}/database"
+}
+
+resource "aws_db_instance" "main" {
+  # ...
+  username = data.vault_generic_secret.db.data["username"]
+  password = data.vault_generic_secret.db.data["password"]
+}
+```
+
+### Policy as Code
+
+#### Sentinel (Terraform Cloud / Enterprise)
+
+```python
+# sentinel/enforce-encryption.sentinel
+import "tfplan/v2" as tfplan
+
+# 强制 S3 Bucket 开启加密
+s3_buckets = filter tfplan.resource_changes as _, rc {
+    rc.type is "aws_s3_bucket" and
+    rc.mode is "managed" and
+    (rc.change.actions contains "create" or rc.change.actions contains "update")
+}
+
+encryption_enforced = rule {
+    all s3_buckets as _, bucket {
+        bucket.change.after.server_side_encryption_configuration is not null
+    }
+}
+
+main = rule {
+    encryption_enforced
+}
+```
+
+#### OPA (Open Policy Agent)
+
+```rego
+# policy/enforce_tags.rego
+package terraform.analysis
+
+import input as tfplan
+
+# 要求所有资源必须有 Environment 和 ManagedBy 标签
+required_tags := ["Environment", "ManagedBy"]
+
+deny[msg] {
+    resource := tfplan.resource_changes[_]
+    resource.change.actions[_] == "create"
+    tags := resource.change.after.tags
+    required_tag := required_tags[_]
+    not tags[required_tag]
+    msg := sprintf("Resource '%s' is missing required tag '%s'", [resource.address, required_tag])
+}
+
+# 禁止使用过大的实例类型
+deny[msg] {
+    resource := tfplan.resource_changes[_]
+    resource.type == "aws_instance"
+    resource.change.actions[_] == "create"
+    instance_type := resource.change.after.instance_type
+    startswith(instance_type, "x1")
+    msg := sprintf("Instance type '%s' is not allowed (too expensive). Use t3/m6i family.", [instance_type])
+}
+```
+
+### RBAC (Terraform Cloud)
+
+```hcl
+# 团队权限配置
+resource "tfe_team" "developers" {
+  name         = "developers"
+  organization = var.tfc_organization
+}
+
+resource "tfe_team_access" "developers_dev" {
+  access       = "write"       # plan + apply
+  team_id      = tfe_team.developers.id
+  workspace_id = tfe_workspace.dev.id
+}
+
+resource "tfe_team_access" "developers_prod" {
+  access       = "plan"        # 仅 plan，不能 apply
+  team_id      = tfe_team.developers.id
+  workspace_id = tfe_workspace.prod.id
+}
+```
+
+---
+
+## CI/CD 集成
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/terraform.yml
+name: Terraform
+
+on:
+  pull_request:
+    paths:
+      - 'infrastructure/**'
+  push:
+    branches: [main]
+    paths:
+      - 'infrastructure/**'
+
+permissions:
+  id-token: write   # OIDC
+  contents: read
+  pull-requests: write
+
+jobs:
+  plan:
+    name: Terraform Plan
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    defaults:
+      run:
+        working-directory: infrastructure/
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ap-northeast-1
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: 1.7.4
+
+      - name: Terraform Init
+        run: terraform init -no-color
+
+      - name: Terraform Format Check
+        run: terraform fmt -check -recursive
+
+      - name: Terraform Validate
+        run: terraform validate -no-color
+
+      - name: Terraform Plan
+        id: plan
+        run: terraform plan -no-color -out=tfplan
+        continue-on-error: true
+
+      - name: Comment PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const output = `#### Terraform Plan 📋
+            \`\`\`
+            ${{ steps.plan.outputs.stdout }}
+            \`\`\`
+            *Pushed by: @${{ github.actor }}*`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: output
+            });
+
+      - name: Plan Status
+        if: steps.plan.outcome == 'failure'
+        run: exit 1
+
+  apply:
+    name: Terraform Apply
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment: production
+    defaults:
+      run:
+        working-directory: infrastructure/
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ap-northeast-1
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: 1.7.4
+
+      - name: Terraform Init
+        run: terraform init -no-color
+
+      - name: Terraform Apply
+        run: terraform apply -auto-approve -no-color
+```
+
+### GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - validate
+  - plan
+  - apply
+
+variables:
+  TF_ROOT: infrastructure/
+  TF_STATE_NAME: default
+
+.terraform_base:
+  image: hashicorp/terraform:1.7.4
+  before_script:
+    - cd ${TF_ROOT}
+    - terraform init -no-color
+
+validate:
+  extends: .terraform_base
+  stage: validate
+  script:
+    - terraform fmt -check -recursive
+    - terraform validate -no-color
+  rules:
+    - changes:
+        - infrastructure/**
+
+plan:
+  extends: .terraform_base
+  stage: plan
+  script:
+    - terraform plan -no-color -out=tfplan
+  artifacts:
+    paths:
+      - ${TF_ROOT}/tfplan
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      changes:
+        - infrastructure/**
+
+apply:
+  extends: .terraform_base
+  stage: apply
+  script:
+    - terraform apply -auto-approve -no-color tfplan
+  dependencies:
+    - plan
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      changes:
+        - infrastructure/**
+  when: manual
+  environment:
+    name: production
+```
+
+### Atlantis
+
+```yaml
+# atlantis.yaml
+version: 3
+projects:
+  - name: vpc
+    dir: infrastructure/vpc
+    workspace: default
+    terraform_version: v1.7.4
+    autoplan:
+      when_modified:
+        - "*.tf"
+        - "../modules/vpc/**"
+      enabled: true
+    apply_requirements:
+      - approved    # PR 需要审批
+      - mergeable   # PR 可合并
+
+  - name: app
+    dir: infrastructure/app
+    workspace: default
+    terraform_version: v1.7.4
+    autoplan:
+      when_modified:
+        - "*.tf"
+        - "../modules/ecs/**"
+      enabled: true
+    apply_requirements:
+      - approved
+      - mergeable
+```
+
+### Terraform Cloud
+
+```hcl
+# 配置 Terraform Cloud 作为 Backend
+terraform {
+  cloud {
+    organization = "mycompany"
+
+    workspaces {
+      tags = ["app:myproject", "env:prod"]
+    }
+  }
+}
+```
+
+---
+
+## 团队协作
+
+### 推荐目录结构
+
+```
+infrastructure/
+├── environments/
+│   ├── dev/
+│   │   ├── main.tf           # 调用模块，dev 环境参数
+│   │   ├── variables.tf
+│   │   ├── outputs.tf
+│   │   ├── terraform.tfvars  # dev 环境变量值
+│   │   └── backend.tf        # dev 环境 state 配置
+│   ├── staging/
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── outputs.tf
+│   │   ├── terraform.tfvars
+│   │   └── backend.tf
+│   └── prod/
+│       ├── main.tf
+│       ├── variables.tf
+│       ├── outputs.tf
+│       ├── terraform.tfvars
+│       └── backend.tf
+├── modules/                   # 可复用模块
+│   ├── vpc/
+│   ├── ecs/
+│   ├── rds/
+│   ├── s3/
+│   └── iam/
+├── policies/                  # OPA / Sentinel 策略
+│   ├── enforce_tags.rego
+│   └── enforce_encryption.rego
+└── scripts/
+    ├── bootstrap.sh           # 初始化 S3 Backend + DynamoDB Lock
+    └── import.sh              # 批量导入已有资源
+```
+
+### 命名规范
+
+```hcl
+# 资源命名: <project>-<environment>-<component>-<qualifier>
+# 例: myapp-prod-web-sg, myapp-dev-db-primary
+
+# Terraform 资源名 (代码内标识符): 使用下划线，语义清晰
+resource "aws_security_group" "web_ingress" { }       # 好
+resource "aws_security_group" "sg1" { }                # 差：无语义
+resource "aws_security_group" "web-ingress-sg" { }     # 差：HCL 用下划线
+
+# 变量名: 使用下划线，名词短语
+variable "vpc_cidr" { }
+variable "enable_nat_gateway" { }     # bool 用 enable_ 前缀
+variable "instance_count" { }         # 数量用 _count 后缀
+
+# 输出名: 使用下划线，描述所输出的值
+output "vpc_id" { }
+output "private_subnet_ids" { }
+output "database_endpoint" { }
+
+# 模块名: 使用下划线
+module "networking" { }
+module "application_cluster" { }
+```
+
+### 代码审查要点
+
+1. **Plan 输出审查**：每个 PR 必须附带 `terraform plan` 输出
+2. **破坏性变更识别**：关注 `destroy` 和 `replace` 操作，尤其是数据库和持久化存储
+3. **安全审查**：检查安全组规则、IAM 策略是否遵循最小权限
+4. **标签完整性**：所有资源必须包含 Environment、ManagedBy、Project 标签
+5. **硬编码检查**：不应出现 IP 地址、密码、Account ID 等硬编码值
+6. **State 影响**：注意资源地址变更（重命名/移入模块）是否会导致重建
+7. **Provider 版本**：版本约束是否合理，是否会引入破坏性更新
+
+### 变更管理
+
+```bash
+# 安全的变更流程
+# 1. 创建特性分支
+git checkout -b feat/add-redis-cluster
+
+# 2. 修改配置
+# 3. 本地验证
+terraform fmt -check -recursive
+terraform validate
+terraform plan -out=tfplan
+
+# 4. 审查 plan 输出
+# 5. 提交 PR，附带 plan 输出
+# 6. 代码审查 + plan 审查
+# 7. 合并到 main，自动触发 apply (或手动 approve)
+
+# 紧急变更回滚
+# 方式 1: git revert + apply
+git revert HEAD
+terraform apply
+
+# 方式 2: 恢复 State 到之前版本 (S3 版本控制)
+aws s3api list-object-versions --bucket mycompany-terraform-state --prefix prod/app/terraform.tfstate
+aws s3api get-object --bucket mycompany-terraform-state --key prod/app/terraform.tfstate --version-id <version-id> terraform.tfstate.restore
+terraform state push terraform.tfstate.restore
+```
+
+---
+
+## 性能优化
+
+### 并行度控制
+
+```bash
+# 默认并行度为 10，可根据 API 限制调整
+terraform apply -parallelism=20     # 提高并行度 (资源量大时)
+terraform apply -parallelism=3      # 降低并行度 (API 限流时)
+```
+
+### Targeted Apply
+
+```bash
+# 仅操作特定资源 (调试/紧急修复时使用)
+terraform plan -target=module.networking
+terraform apply -target=aws_instance.web
+
+# 注意: targeted apply 会跳过依赖检查，仅用于临时操作
+# 完成后应执行完整的 terraform plan 确认状态一致
+```
+
+### 模块拆分策略
+
+```
+# 按生命周期拆分 State，减少 plan/apply 范围
+
+infrastructure/
+├── networking/          # 变更频率低 - VPC/Subnet/NAT
+│   └── terraform.tfstate
+├── data-stores/         # 变更频率低 - RDS/ElastiCache/S3
+│   └── terraform.tfstate
+├── compute/             # 变更频率高 - ECS/EC2/ASG
+│   └── terraform.tfstate
+├── monitoring/          # 变更频率中 - CloudWatch/Alarms
+│   └── terraform.tfstate
+└── dns/                 # 变更频率低 - Route53/ACM
+    └── terraform.tfstate
+```
+
+跨 State 引用使用 `terraform_remote_state` Data Source：
+
+```hcl
+# compute/main.tf - 引用 networking 的输出
+data "terraform_remote_state" "networking" {
+  backend = "s3"
+  config = {
+    bucket = "mycompany-terraform-state"
+    key    = "prod/networking/terraform.tfstate"
+    region = "ap-northeast-1"
+  }
+}
+
+resource "aws_instance" "web" {
+  subnet_id = data.terraform_remote_state.networking.outputs.private_subnet_ids[0]
+}
+```
+
+### 大规模部署优化
+
+```bash
+# 使用 -refresh=false 跳过 refresh (状态与实际一致时)
+terraform plan -refresh=false
+
+# 生成 plan 文件后使用 terraform show 审查
+terraform plan -out=tfplan
+terraform show -json tfplan | jq '.resource_changes | length'
+
+# Provider 镜像 (加速 init)
+# ~/.terraformrc
+provider_installation {
+  filesystem_mirror {
+    path    = "/usr/share/terraform/providers"
+    include = ["registry.terraform.io/hashicorp/*"]
+  }
+  direct {
+    exclude = ["registry.terraform.io/hashicorp/*"]
+  }
+}
+```
+
+---
+
+## 常见陷阱与反模式
+
+### 1. State 漂移
+
+**问题**：手动在控制台修改了资源，Terraform State 与实际状态不一致。
+
+```bash
+# 检测漂移
+terraform plan -refresh-only
+
+# 同步 State 到实际状态 (不修改资源)
+terraform apply -refresh-only
+
+# 预防: 禁止手动操作，所有变更通过 Terraform
+# 预防: 定期运行 drift detection (Terraform Cloud 内置支持)
+```
+
+### 2. 循环依赖
+
+**问题**：资源 A 依赖 B 的属性，B 又依赖 A 的属性。
+
+```hcl
+# 错误: 安全组循环引用
+resource "aws_security_group" "a" {
+  ingress {
+    security_groups = [aws_security_group.b.id]  # A 依赖 B
+  }
+}
+
+resource "aws_security_group" "b" {
+  ingress {
+    security_groups = [aws_security_group.a.id]  # B 依赖 A → 循环!
+  }
+}
+
+# 正确: 使用独立的 rule 资源打破循环
+resource "aws_security_group" "a" {
+  name   = "sg-a"
+  vpc_id = aws_vpc.main.id
+}
+
+resource "aws_security_group" "b" {
+  name   = "sg-b"
+  vpc_id = aws_vpc.main.id
+}
+
+resource "aws_security_group_rule" "a_from_b" {
+  type                     = "ingress"
+  security_group_id        = aws_security_group.a.id
+  source_security_group_id = aws_security_group.b.id
+  from_port                = 443
+  to_port                  = 443
+  protocol                 = "tcp"
+}
+
+resource "aws_security_group_rule" "b_from_a" {
+  type                     = "ingress"
+  security_group_id        = aws_security_group.b.id
+  source_security_group_id = aws_security_group.a.id
+  from_port                = 8080
+  to_port                  = 8080
+  protocol                 = "tcp"
+}
+```
+
+### 3. Provider 版本锁定
+
+**问题**：未锁定版本导致团队成员使用不同版本，产生不一致的 plan。
+
+```hcl
+# 错误: 无版本约束
+terraform {
+  required_providers {
+    aws = {
+      source = "hashicorp/aws"
+    }
+  }
+}
+
+# 正确: 明确版本约束 + 提交 .terraform.lock.hcl
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.40"
+    }
+  }
+}
+
+# .terraform.lock.hcl 必须提交到 Git
+# 更新锁文件: terraform init -upgrade
+```
+
+### 4. count vs for_each 陷阱
+
+```hcl
+# 错误: 使用 count + 列表，删除中间元素导致后续资源全部重建
+variable "subnets" {
+  default = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
+}
+
+resource "aws_subnet" "bad" {
+  count      = length(var.subnets)
+  cidr_block = var.subnets[count.index]  # 删除第 2 个 → 第 3 个变为 index 1 → 重建!
+}
+
+# 正确: 使用 for_each + map/set，键稳定不受顺序影响
+variable "subnets" {
+  default = {
+    az-a = "10.0.1.0/24"
+    az-b = "10.0.2.0/24"
+    az-c = "10.0.3.0/24"
+  }
+}
+
+resource "aws_subnet" "good" {
+  for_each   = var.subnets
+  cidr_block = each.value  # 删除 az-b → 仅影响 az-b，az-a 和 az-c 不变
+}
+```
+
+### 5. 过大的 State 文件
+
+**问题**：所有资源放在一个 State 中，plan/apply 极慢，爆炸半径大。
+
+**解法**：按生命周期和变更频率拆分模块（见性能优化章节）。每个 State 管理 50-200 个资源为宜。
+
+### 6. 硬编码 Provider 配置
+
+```hcl
+# 错误: 硬编码 Region 和 Account ID
+provider "aws" {
+  region = "ap-northeast-1"
+}
+
+resource "aws_iam_role" "bad" {
+  assume_role_policy = jsonencode({
+    Statement = [{
+      Principal = { AWS = "arn:aws:iam::123456789012:root" }  # 硬编码
+    }]
+  })
+}
+
+# 正确: 参数化
+provider "aws" {
+  region = var.aws_region
+}
+
+data "aws_caller_identity" "current" {}
+
+resource "aws_iam_role" "good" {
+  assume_role_policy = jsonencode({
+    Statement = [{
+      Principal = { AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root" }
+    }]
+  })
+}
+```
+
+### 7. 忽略 lifecycle 规则
+
+```hcl
+# 数据库等有状态资源必须设置 prevent_destroy
+resource "aws_db_instance" "main" {
+  # ...
+  lifecycle {
+    prevent_destroy = true  # 防止意外 destroy
+  }
+}
+
+# 蓝绿部署场景使用 create_before_destroy
+resource "aws_instance" "web" {
+  # ...
+  lifecycle {
+    create_before_destroy = true  # 先建新实例再删旧实例
+  }
+}
+```
+
+### 8. 敏感数据泄漏
+
+```hcl
+# 错误: 在 terraform.tfvars 中存储密码并提交到 Git
+# terraform.tfvars
+db_password = "my-secret-password"  # 绝不要这样做
+
+# 正确: 使用环境变量
+# export TF_VAR_db_password="my-secret-password"
+
+# 正确: 使用 Secrets Manager / Vault
+data "aws_secretsmanager_secret_version" "db" {
+  secret_id = aws_secretsmanager_secret.db.id
+}
+
+# .gitignore 必须包含:
+# *.tfstate
+# *.tfstate.*
+# *.tfvars      (如果包含敏感值)
+# .terraform/
+```
+
+### 9. 未使用 moved 块处理重构
+
+```hcl
+# Terraform 1.1+ 使用 moved 块安全重命名资源
+# 避免 destroy + create，保留已有资源
+moved {
+  from = aws_instance.web
+  to   = aws_instance.application
+}
+
+moved {
+  from = aws_instance.app
+  to   = module.compute.aws_instance.app
+}
+```
+
+### 10. 忽视 Plan 输出
+
+**反模式**：直接 `terraform apply -auto-approve` 而不审查 plan。
+
+**规范**：
+- 开发环境：本地 `terraform plan` 审查后再 apply
+- 生产环境：CI 生成 plan → PR 审查 plan 输出 → 人工批准后 apply saved plan
+- 永远使用 `terraform plan -out=tfplan` + `terraform apply tfplan`，确保执行的是审查过的计划
+
+---
+
+## Agent Checklist
+
+以下检查清单供 AI Agent 在生成或审查 Terraform 代码时使用：
+
+### 基础规范
+- [ ] `terraform fmt` 格式化通过
+- [ ] `terraform validate` 验证通过
+- [ ] 所有 Provider 声明了版本约束
+- [ ] `.terraform.lock.hcl` 提交到 Git
+- [ ] `.gitignore` 包含 `*.tfstate`、`.terraform/`、敏感 `.tfvars`
+
+### 安全
+- [ ] 无硬编码密码、密钥、Account ID
+- [ ] 敏感变量标记 `sensitive = true`
+- [ ] 密码通过 Secrets Manager / Vault 管理
+- [ ] S3 Bucket 开启加密 + 阻止公开访问
+- [ ] IAM 策略遵循最小权限原则
+- [ ] 安全组规则无不必要的 `0.0.0.0/0` 入站
+- [ ] RDS 开启 `storage_encrypted = true`
+
+### 状态管理
+- [ ] 使用 Remote Backend (S3/GCS/Terraform Cloud)
+- [ ] 启用 State Locking (DynamoDB/原生)
+- [ ] State Bucket 开启版本控制
+- [ ] State 按生命周期合理拆分
+
+### 模块设计
+- [ ] 模块有完整的 `variables.tf` + `outputs.tf`
+- [ ] 变量有 `description` 和 `type`
+- [ ] 关键变量有 `validation` 块
+- [ ] 使用 `for_each` 而非 `count`（除非纯数量迭代）
+- [ ] 模块版本使用 `~>` 约束
+
+### 生产就绪
+- [ ] 数据库等有状态资源设置 `prevent_destroy`
+- [ ] 所有资源有 Environment / ManagedBy / Project 标签
+- [ ] 生产环境 RDS 开启 `multi_az` 和足够的 `backup_retention_period`
+- [ ] ALB 使用 TLS 1.3 策略
+- [ ] HTTP 自动重定向到 HTTPS
+- [ ] EKS 节点组设置合理的 `min_size` / `max_size`
+- [ ] NAT Gateway 生产环境每 AZ 一个
+
+### CI/CD
+- [ ] PR 自动运行 `terraform plan`
+- [ ] Plan 输出作为 PR 评论
+- [ ] 生产 Apply 需要人工批准
+- [ ] 使用 OIDC 而非长期 Access Key 进行认证
+- [ ] Plan 文件保存为 CI Artifact
+
+### 变更安全
+- [ ] 审查 plan 中的 `destroy` / `replace` 操作
+- [ ] 资源重命名使用 `moved` 块
+- [ ] 未使用 `-auto-approve`（除自动化流水线外）
+- [ ] 大规模变更分批执行