Alibaba Cloud Terraform 三层架构 模块化设计 for_each 实战

如果你也曾在云控制台里反复点过 VPC、ECS、SLB、RDS、OSS,最后却发现测试环境和生产环境总有一点“不一样”。

实际部署中,重要的不是“三层 Web 服务”怎么落到阿里云,而是:成熟架构一旦进入工程落地阶段,就应该被代码化、模块化、可重复化。

三层架构是企业 Web 服务里最经典、也最经得起时间考验的拓扑形态之一。接入层负责流量分发与反向代理,应用层承载业务逻辑,数据层负责持久化。边界清晰、扩展自然、职责明确,所以它总能出现在各种项目方案里。

但真正让团队头疼的,通常不是“懂不懂三层架构”,而是怎么稳定地、重复地、低风险地把它部署出来。手工在控制台搭一套环境,常见的问题几乎可以写成一张事故清单:

  • 同样一套环境,每次都要重复点十几二十个步骤。
  • 安全组规则写错一条,排查半天才发现是入口网段不对。
  • 测试环境能跑,生产环境不通,最后发现是参数和资源规格悄悄漂移了。
  • 架构图看起来完整,但上线前没人能说清楚“到底有哪些资源、按什么顺序创建、依赖关系是什么”。

Terraform 的 Infrastructure as Code(IaC)范式,正是为这些问题准备的。它把基础设施状态变成了可审查、可版本化、可复现、可回滚思考的工程资产。

这篇文章就以一个完整的阿里云三层 Web 服务 Terraform 项目为例,拆开讲讲它背后的设计:模块怎么分、for_each 怎么在不同层级发挥作用、模块之间如何传数据、安全策略怎么做得既实用又不粗暴,以及为什么“可观测性”应该在部署阶段就被设计进去。

阅读导航

  1. 先看整套阿里云三层拓扑,快速建立全局图景。
  2. 再看模块拆分方式,理解 Terraform 为什么能写得“既稳又能复用”。
  3. 重点拆解 for_each 的三种使用层级,这是整篇最核心的技术部分。
  4. 最后看依赖注入、安全边界、验证 API 和变量校验,理解工程化细节怎么落地。

先看全貌:这套架构到底长什么样?

整套环境部署在阿里云 cn-shanghai 区域,强制跨两个可用区,目标很明确:不是只把服务跑起来,而是从一开始就按高可用拓扑来搭。

流量链路

Internet
  |
  v
公网 SLB (8088, PayByTraffic)
  |
  +-- Web ECS: web-az1  10.0.0.11  (cn-shanghai-l)
  +-- Web ECS: web-az2  10.0.1.11  (cn-shanghai-m)
       |
       | Nginx 反向代理
       v
内网 SLB (80, intranet)
  |
  +-- App ECS: app-az1  10.0.10.21  (cn-shanghai-l)
  +-- App ECS: app-az2  10.0.11.21  (cn-shanghai-m)
       |
       | Nginx 应用服务 (8080) + 验证 API (18080)
       v
RDS MySQL 8.0 (高可用, 3306)
  |
  v
OSS 私有存储桶

网络规划:一个 10.0.0.0/16 的 VPC,拆成三层、共六个 VSwitch,每层各跨两个 AZ。

层级 可用区cn-shanghai-l 可用区cn-shanghai-m
Web 10.0.0.0/24 10.0.1.0/24
App 10.0.10.0/24 10.0.11.0/24
DB 10.0.20.0/24 10.0.21.0/24

RDS 采用高可用实例,显式指定主可用区和备可用区,ha_config = "Auto",一主一备的高可用架构,支持自动故障切换。备节点不可访问。

架构概况:公网入口接住流量,Web 层响应静态资源和做反向代理,App 层执行业务逻辑和依赖验证,RDS 与 OSS 负责状态与存储,所有资源都被 Terraform 串成了一条可重复执行的交付链。


模块怎么切,决定了这个 Terraform 项目能走多远

这个项目没有把所有资源堆在一个 main.tf 里,而是拆成了 7 个职责明确的模块:

modules/
├── network/        # VPC + 6 个跨 AZ VSwitch
├── security/       # 三个安全组及其规则
├── compute-tier/   # Web/App 层 ECS 编排器(调用 ecs-instance)
├── ecs-instance/   # 单个 ECS 实例(系统盘 + 2 块数据盘)
├── load-balancer/  # SLB(公网/内网通用)
├── database/       # RDS 实例、数据库、账户、备份策略
└── storage/        # OSS 私有存储桶(随机后缀保证全局唯一)

它的依赖关系:

network
  ├── security
  ├── database
  ├── app_tier (compute-tier) → internal_load_balancer
  └── web_tier (compute-tier) → public_load_balancer
storage(独立)

其中 load-balancer 模块被复用了两次:一次做公网 SLB,一次做内网 SLB。模块本身不关心自己是“入口层”还是“层间转发层”,它只接受 address_type、端口、后端实例等参数。这种设计的好处:

  • 复用是通过接口抽象实现的,而不是复制一份代码再改名字。
  • 后续如果要调整健康检查、监听参数或标签策略,只改一处即可。
  • 模块边界清晰后,主配置文件更像一份“架构编排文件”,可读性会直线上升。

也就是说,模块化不只是为了“代码优雅”,而是为了让基础设施具备长期演进能力。

可以把主配置文件理解成“总导演”,把模块理解成“专业工种”。 网络、计算、负载均衡、数据库、存储各司其职,最终由 main.tf 负责把它们按依赖关系排成一套完整演出。


for_each 在这个项目里的作用

很多人第一次接触 Terraform 的 for_each,只把它当作“创建多个资源”的语法糖。但在这个项目里,它实际上出现了三个层次,而且每个层次解决的问题都不一样。

for_each 不只是“循环”,更像 Terraform 里的“结构放大器”。放在模块层,它复制的是编排模式;放在资源层,它复制的是规则关系;放在动态块层,它复制的是嵌套配置。

1. 模块级 for_each:把 ECS 变成一个“实例工厂”

compute-tier 模块是这个项目里最像“编排器”的地方。它接收一个描述所有实例的 map,然后对 map 中的每个 entry 调用一次 ecs-instance 子模块。

module "instances" {
  for_each = var.instances
  source   = "../ecs-instance"

  number_of_instances = 1
  name                = each.key
  vswitch_id          = each.value.vswitch_id
  private_ip          = each.value.private_ip
  user_data           = lookup(var.user_data_by_instance, each.key, "")

  data_disks = [
    {
      name     = "${each.key}-data-b"
      size     = tostring(var.data_disk_size)
      category = var.data_disk_category
      device   = "/dev/xvdb"
    },
    {
      name     = "${each.key}-data-c"
      size     = tostring(var.data_disk_size)
      category = var.data_disk_category
      device   = "/dev/xvdc"
    }
  ]
}

调用方传进来的并不是一串索引,而是一张“节点清单”:

locals {
  app_nodes = {
    app-az1 = {
      vswitch_id = module.network.app_vswitch_ids[0]
      private_ip = var.app_private_ips[0]
      zone       = var.availability_zones[0]
    }
    app-az2 = {
      vswitch_id = module.network.app_vswitch_ids[1]
      private_ip = var.app_private_ips[1]
      zone       = var.availability_zones[1]
    }
  }
}

这种 map 驱动的方式,比 count 更适合中大型基础设施项目,原因非常现实:

  • 资源地址稳定。 用 key 定址,module.instances["app-az1"] 不会因为中间插入或删除一项而整体漂移。
  • 状态语义清晰。 状态文件和 plan 输出里看到的是 app-az1、web-az2 这类有业务语义的名字,而不是冰冷的下标。
  • 天然支持差异化。 每个实例都可以有不同的 VSwitch、固定 IP、可用区、初始化脚本,配置入口依然保持统一。

compute-tier 模块没有把子模块的输出散落在外部,而是主动聚合成 map 输出:

output "instance_ids" {
  value = {
    for key, instance in module.instances : key => instance.this_instance_id[0]
  }
}

于是调用方可以直接把这份结果喂给负载均衡模块,无需再做任何中间转换。这就是“模块接口设计”的价值:好的模块,不只是能创建资源,还能把结果整理成下一跳最想要的形状。

2. 资源级 for_each:批量创建安全组规则和 SLB 后端注册

第二种用法出现在资源层。这里的 for_each 不是为了“批量造机器”,而是为了把一组规则、附件或映射关系表达得更精确。

比如安全组模块里,Web 层允许来自两个 Web 子网的 HTTP 流量:

resource "alicloud_security_group_rule" "web_http_from_vswitches" {
  for_each = toset(var.web_vswitch_cidrs)

  type              = "ingress"
  ip_protocol       = "tcp"
  port_range        = "${var.web_backend_port}/${var.web_backend_port}"
  security_group_id = alicloud_security_group.web.id
  cidr_ip           = each.value
}

toset() 在这里非常关键。它把 list 转成 set,既能表达“这是一组离散规则”,又能天然去重。以后如果你只是在变量里多加一个管理出口 IP,Terraform 的 plan 会非常老实地告诉你:新增一条规则,仅此而已。

同样的思路也出现在 SLB 后端实例注册上:

resource "alicloud_slb_server_group_server_attachment" "this" {
  for_each = var.backend_instance_ids

  server_group_id = alicloud_slb_server_group.this.id
  server_id       = each.value
  port            = var.backend_port
  weight          = 100
  type            = "ecs"
}

backend_instance_ids 本身就是上一层模块整理好的 map,到了这里无需再洗数据,直接迭代即可。好的 Terraform 配置不是“每层都很聪明”,而是“每一层都少做一遍重复劳动”。

3. 块级 for_each:用 dynamic 处理可变数量的数据盘

第三种用法更像“模板生成器”。ecs-instance 模块并不知道最终会挂几块数据盘,这件事由上层决定,所以它使用 dynamic 块按输入数据生成嵌套配置:

resource "alicloud_instance" "this" {
  count = var.number_of_instances

  dynamic "data_disks" {
    for_each = var.data_disks

    content {
      name                 = lookup(data_disks.value, "name", null)
      size                 = lookup(data_disks.value, "size", null)
      category             = lookup(data_disks.value, "category", null)
      description          = lookup(data_disks.value, "description", null)
      delete_with_instance = lookup(data_disks.value, "delete_with_instance", null)
      device               = lookup(data_disks.value, "device", null)
    }
  }
}

上层目前传了两块盘,对应 /dev/vdb 和 /dev/vdc,分别挂载到 /dataB、/dataC。如果以后业务需要第三块盘,完全不必回头改模块实现,只要在输入 list 里追加一项就行。

这就是 Terraform 里非常值得借鉴的一种思路:把变化交给数据,把稳定留给模块。


跨模块数据注入:templatefile()

如果说 for_each 解决的是“批量”和“结构化”,那么 templatefile() 解决的,就是 Terraform 项目里另一个经常被低估的问题:模块创建出来的值,怎么优雅地传进 ECS 启动脚本?

在这个项目里:

  • App 层 ECS 启动时,需要知道 RDS 的连接地址、数据库名、账户密码,以及 OSS Bucket 名。
  • Web 层 ECS 启动时,需要知道内网 SLB 的地址,才能把请求反代到应用层。

这些值都不是预先写死的,它们要等别的模块创建完之后才会出现。所以主配置通过 locals + templatefile() 在 apply 阶段生成启动脚本:

locals {
  app_user_data_by_instance = {
    for key in keys(local.app_nodes) : key => templatefile(
      "${path.module}/templates/app_user_data.sh.tftpl",
      {
        app_port            = var.app_service_port
        db_endpoint         = module.database.connection_string
        db_port             = 3306
        db_name             = var.database_names[0]
        db_account_name     = var.db_account_name
        db_account_password = var.db_account_password
        bucket_name         = module.storage.bucket_name
        oss_url             = "https://${module.storage.bucket_name}.oss-${var.region}-internal.aliyuncs.com"
        tier_name           = key
        tier_role           = "application"
      }
    )
  }
}

这段设计有两个层面的价值。

第一,它让 ECS 初始化脚本从“死模板”变成“带上下文的数据模板”。脚本不需要猜基础设施地址,也不需要手工二次配置,实例第一次启动时就已经拿到了完整依赖信息。

第二,它天然形成了一条隐式依赖链。举个最典型的例子:Web 层脚本里用到了 module.internal_load_balancer.address,而内网 SLB 又依赖 App 层实例存在。Terraform 会沿着引用关系自动推导出创建顺序,不需要你再额外写一堆 depends_on 去“人工指挥交通”。

最终效果非常顺滑。Web 层实例起来后,Nginx 直接把请求转发给内网 SLB:

location / {
  proxy_pass http://${upstream_host}:${upstream_port};
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

location = /healthz {
  access_log off;
  return 200 "ok\n";
}

而 App 层启动脚本则顺手装好了 Nginx、MySQL Client、验证 API 以及系统服务,让“基础设施部署”与“服务就绪”之间没有断层。


安全设计:不是“把端口打开”,而是把边界说清楚

这个项目的安全组设计遵循的不是“先通了再说”,而是典型的纵深防御思路:每一层只暴露给真正需要访问它的那一层。

安全组 入站规则 来源
web-sg TCP 80 Web VSwitch CIDR
web-sg TCP 22 Admin CIDR
app-sg TCP 8080 App VSwitch CIDR
app-sg TCP 22 Admin CIDR
rds-sg TCP 3306 source_security_group_id = app-sg + RDS 白名单仅放行 App 固定私网 IP

RDS 这层访问控制,不能只配安全组,还要同时把 App 层固定私网 IP 写进 RDS 白名单。

resource "alicloud_security_group_rule" "rds_mysql_from_app" {
  type                     = "ingress"
  ip_protocol              = "tcp"
  port_range               = "3306/3306"
  security_group_id        = alicloud_security_group.rds.id
  source_security_group_id = alicloud_security_group.app.id
}

resource "alicloud_db_instance" "this" {
  # ... 其他 RDS 参数省略
  security_group_ids = [var.rds_security_group_id]
  security_ips       = toset(var.app_private_ips)
}

我这里把两层控制同时打开:网络侧用安全组表达“只有 App ECS 这一层能来”,RDS 实例侧再用白名单把来源进一步收敛到两台 App ECS 的固定私网 IP。这样做的好处,比一句“更安全”具体得多:

  • 控制面更完整。 安全组解决 VPC 内的网络准入,RDS 白名单补上数据库实例自身的访问控制,两层缺一不可。
  • 范围更收敛。 即使有人误把别的 ECS 加进 app-sg,只要它的 IP 不在 RDS 白名单里,也连不上数据库。
  • 表达更贴近真实拓扑。 这个项目里 App ECS 本来就使用固定私网 IP,所以白名单可以精确落到实例级,而不是放宽到整个子网。

这才是“最小权限”在云资源里的完整落地方式。不是抽象原则,而是安全组和白名单一起组成的一组克制规则。


可观测性不是附属品:App 层内嵌验证 API

App 层启动脚本里内嵌了一个 Python 验证 API,监听在 127.0.0.1:18080,再由 Nginx 通过 /validation.json 对外暴露。这样一来,部署完成后你不必 SSH 上去东敲西敲,而是可以直接发一个请求,检查整个依赖链是否正常:

curl http://10.0.10.21:8080/validation.json | jq

返回结构大致如下:

{
  "tier_name": "app-az1",
  "private_ip": "10.0.10.21",
  "rds": {
    "status": "ok",
    "detail": "authenticated query succeeded",
    "endpoint": "xxx.rds.cn-shanghai.aliyuncs.com:3306",
    "database": "portaldb"
  },
  "oss": {
    "status": "ok",
    "detail": "endpoint reachable with HTTP 403",
    "url": "https://three-layer-webservice-abc123.oss-cn-shanghai-internal.aliyuncs.com"
  },
  "timestamp": "2025-03-15T08:00:00+00:00"
}

服务验证设计要点:

  • RDS 检查不是简单探端口,而是用真实账号执行一次 SELECT 1;,连认证失败、网络不通、超时都能区分出来。
  • OSS 检查也不是“必须 200”,而是把 200 和 403 都视为可达,因为私有 Bucket 返回 403 恰恰说明 endpoint 可访问、权限控制在生效。
  • 两个检查通过 ThreadPoolExecutor 并发执行,所以整体响应延迟基本由最慢那一项决定,不会串行拖长排查时间。

这背后体现的是一个运维认知:

/healthz 和 /validation.json,解决的是两类完全不同的问题。

/healthz 回答的是:“我活着吗?” 这是给负载均衡器看的,越轻越好。

/validation.json 回答的是:“我依赖的东西都正常吗?” 这是给人排障用的,信息越准越有价值。

很多项目把可观测性放在最后补,这个项目则是在部署阶段就把它设计进去了。这会显著降低联调和上线当天的焦虑感。

这类验证接口特别适合团队协作场景。 当测试、运维、开发都需要确认“问题到底出在应用本身,还是出在数据库、对象存储、网络链路”时,一个结构化的诊断端点,往往比口头描述高效得多。


输入变量的防护性设计:把错误挡在 plan 之前

Terraform 的另一个价值,不只是“能创建资源”,而是“能在资源创建前就发现错误”。这个项目在 variables.tf 里用 validation 对关键输入做了前置约束:

variable "availability_zones" {
  type = list(string)
  validation {
    condition     = length(var.availability_zones) == 2
    error_message = "Provide exactly two availability zones for the dual-AZ topology."
  }
}

variable "db_account_password" {
  type      = string
  sensitive = true
  validation {
    condition     = trimspace(var.db_account_password) != ""
    error_message = "Set db_account_password to a non-empty value before apply."
  }
}

这类校验看上去不起眼,但在团队协作里非常值钱。它能把“配置有问题”从 apply 到一半才失败,提前到 terraform validate 或 terraform plan 阶段就直接拦住。

sensitive = true 也同样重要。密码、凭证这类变量在 plan 和 output 里会被自动打码,虽然不等于彻底安全,但至少能把“误曝光”这种低级事故概率压下去。

Terraform 鼓励“尽早失败”。 比起资源创建到一半才发现配置错了,能在 validate 或 plan 阶段被拦下来的错误,处理成本要低得多。


要把这套项目往“生产级”推进,接下来很自然的演进方向包括:

  • 给公网 SLB 挂载 HTTPS 证书,并结合 WAF 做更完整的入口保护。
  • 给 App 层接入 Auto Scaling,让扩缩容从“手工加机器”变成按指标触发。
  • 把 Terraform State 迁移到阿里云 OSS 远端后端,提升团队协作能力。
  • 引入 Workspace 或目录分层,系统化地区分 dev、staging、prod 环境。

结语

三层架构本身并不新鲜,真正拉开差距的,是你用什么方式去交付它。

如果它只存在于一张架构图里,那它只是“设计”。如果它只能靠某个熟练工程师在控制台手动点出来,那它只是“经验”。但如果它被写成 Terraform,拆成模块,带着约束、依赖、验证和可观测性一起交付,那它才真正变成了工程能力。