用 Terraform 给 AI Agent 上云（一）：为什么 IaC 是唯一靠谱的部署方式

过去十八个月我在阿里云上交付过四个 Agent 系统。其中三个的初始形态都是某人在控制台点一阵之后留下的一台 ECS 上跑着 tmux 会话。这三个系统都各自经历过一个仓促的周末——第二位工程师入职的时候、生产区域 GPU 缺货的时候、安全团队来问网络拓扑图的时候——把所有东西从头重建一遍。

第四个系统从第一天就是 terraform apply 起家的。也只有这个我没有为它失去过周末。

这个系列就是第四种模式的实战手册：如何用 Terraform 在阿里云上把一个 AI Agent 系统真正需要的云基础设施搭起来。它不是 Terraform 入门教程——网上不缺好的入门，官方 Get Started 文档也覆盖了基础。它是"我跑 Agent"和"我在阿里云上跑"这两件事交集处的资深工程师剧本。

八篇文章。最后会落在一个真正能跑的完整 stack 上。第一篇先讲 why。

一个 Agent 系统到底需要什么

在谈基础设施之前，先把 Agent 系统的组件列清楚——pip install langgraph 那个 README 通常会跳过的部分：

Runtime——承载 Agent 主循环进程，通常是 Python 或 Node，要能熬过重启
向量库——做语义记忆，存文档、历史对话、工具产出的 embedding
关系型存储——存会话状态：每一轮对话、工具调用轨迹、用户身份
对象存储——存产物：生成的图片、PDF、截图、运行快照
LLM 网关——一个统一的地方持有 API key，并按 Agent 维度限流
出网——访问 DashScope、OpenAI、Anthropic、你的爬虫目标
可观测——Agent 运行非确定性极高，日志和 trace 不是可选项
密钥——provider key、OAuth token、OSS 凭证、数据库密码
成本控制——因为 Agent 一旦自循环，token 账单一夜之间能涨十倍

这至少是九个独立的阿里云服务，相互之间还有特定的接线方式。每一个都有自己的控制台页面、自己的 RAM 权限、自己的 region 范围、自己的网络。三个月之后还能让 dev、staging、prod 三个环境对得上的概率，约等于零。

控制台 vs IaC 的那个瞬间

这个痛点足够��用，我已经有一张固定图了：

仔细看左边那一列。每一步都合情合理——没有一个是低级错误。它们就是聪明人在几个月里做出一连串小而合理的决定之后的产物。右边那一列是同一条路径，但每一步都在 git 里留下了一份产物。两列之间的差，就是"我交付了"和"凌晨两点我被叫起来因为没人知道 cn-beijing 上跑的是什么"的差。

阿里云 Terraform 官方文档说得更外交一些。引用《What Is Alibaba Cloud Terraform?》：

控制台操作：在界面上一步步点击和填写参数。重复手工操作——很难保证一致性。依赖文档和口头约定。
Terraform：在配置文件里描述资源的期望状态。配置文件可评审、可共享、可复用。配置文件存在版本控制中，变更可追溯、可回滚。

第二段就是整个推销词。本系列其余内容都是实现细节。

两句话讲清楚 Terraform 是什么

Terraform 是 HashiCorp 的开源声明式工具。你用 HashiCorp Configuration Language (HCL) 写 .tf 文件描述你想要的云资源；Terraform 把这个期望状态和记录在 state file 里的真实状态做 diff，输出一个 plan；你审 plan；你 apply；Terraform 把 plan 翻译成对 provider 的 API 调用。

需要内化的三件事：

声明式，不是命令式。 你不说"创建一个实例"——你说"存在一个这种形态的实例"。同样的配置重复跑一遍，如果什么都没变就是 no-op。这就是为什么 Terraform 可以放心放进 CI、每次提交都跑。
State 是真实存在的。 terraform.tfstate 文件是一份 JSON，把你 HCL 里的 resource 地址映射到云上的真实资源 ID。state 一丢，Terraform 就以为什么都不存在了。第二篇就是把 state 放到一个可靠的地方。
Apply 之前先 plan。 这是杀手锏。每次变更都会在真正动手之前先告诉你字面意义的 diff——会创建什么、修改什么、销毁什么。养成把 plan 输出贴到 PR 描述里的习惯，未来的你会感谢现在的你。

阿里云 provider 覆盖了什么

云平台通过 provider 插件和 Terraform 对话。官方的 alicloud provider 是中国第一个官方 Terraform provider，由阿里维护。截至本文写作时，它发布了 300 多种 resource 类型，分布在大约六个领域：

按照官方《What Is Alibaba Cloud Terraform?》页面的说法，覆盖类别包括：

计算与容器：ECS、ACK（Kubernetes）、Function Compute、Auto Scaling
网络：VPC、SLB、ALB、NLB、NAT 网关、云企业网（CEN）
存储与数据库：OSS、NAS、RDS、PolarDB、Redis、MongoDB
安全与管理：RAM、KMS、WAF
大数据与 AI：MaxCompute、PAI

上面九件套清单除了"可观测"（SLS / ARMS / CloudMonitor，其实也覆盖了，只是这张短清单上没列）和"按 LLM provider 存 key"的部分（第六篇用 KMS Secrets Manager 处理）之外，全在覆盖之内。

一段最小 HCL 例子，直接来自官方 ECS 实践文档：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
provider "alicloud" {
  region = "cn-shanghai"
}

resource "alicloud_vpc" "main" {
  vpc_name   = "agents-prod"
  cidr_block = "10.20.0.0/16"
}

resource "alicloud_vswitch" "private_a" {
  vpc_id     = alicloud_vpc.main.id
  cidr_block = "10.20.1.0/24"
  zone_id    = "cn-shanghai-l"
}

resource "alicloud_security_group" "agent_runtime" {
  name   = "agent-runtime-sg"
  vpc_id = alicloud_vpc.main.id
}

三个资源，里面有 vpc_id 引用，Terraform 自动解析出依赖顺序。你不用说"先 VPC、再 vSwitch、再 SG"——你写期望状态，Terraform 帮你建 DAG。

模块：复用的最小单位

最重要的早期习惯是 module。一个 module 就是一个目录的 .tf 文件，接受输入、产出输出。一旦你有一个能跑通的模式——三个 vSwitch + NAT + 安全组基线的 VPC——把它包成 module，就可以在 dev、staging、prod、intl-prod 之间反复用，不用复制 HCL。

最简单的 module 调用：

1
2
3
4
5
6
7
module "vpc" {
  source = "./modules/vpc-baseline"

  vpc_name   = "agents-${var.env}"
  cidr_block = "10.20.0.0/16"
  zones      = ["cn-shanghai-l", "cn-shanghai-m", "cn-shanghai-n"]
}

./modules/vpc-baseline/main.tf 的内部装着真正的 alicloud_vpc、alicloud_vswitch、alicloud_nat_gateway。调用方不用关心——它只想要一个带合理默认值的 VPC。这和 Python 函数是一回事，只不过对象是基础设施。

第三篇我们就把这个 module 写出来，并在后续每一篇都复用它。

Terraform vs Pulumi vs Crossplane vs ROS

下手之前快速看一眼替代品。没有谁是错的，按团队适配度选，不要按宗教选：

我四个都用过之后的诚实评价：

Terraform 是默认。provider、module、会用的人形成的生态最大。HCL 第一天觉得别扭，第二天就习惯了。除非有强烈反对的理由，就用它。
Pulumi 在 Terraform provider 之上包了一层，但允许你用 Python/TypeScript/Go。表达力是真的——你拿到了循环、条件、IDE 真的会查的类型。代价是 debug：出问题的时候你在两层之间跳（你的代码 → Pulumi → TF provider）。如果你团队真的恨 HCL，值得。
Crossplane 活在 Kubernetes 里——每个云资源是一个 CRD，你 kubectl apply 一个 VPC 出来。如果你已经是纯 K8s 商店且做 GitOps，很优雅；如果不是，很折磨。
ROS（资源编排服务）是阿里云原生对应物。和控制台深度集成，模板是 JSON 或 YAML，不用装 provider 插件。只有当你 100% 永远在阿里云上、运维团队也偏好托管服务时才选它。

阿里云官方文档 FAQ 里有一段公允的对比：

Terraform 和 ROS 都是声明式 IaC 工具。Terraform 是开源的第三方工具，支持多云管理。ROS 是阿里云原生服务，与控制台深度集成。如果你需要多云支持或已经在用 Terraform，选 Terraform。

对一个调多个 LLM provider、未来某天可能需要美国区域或新加坡区域的 Agent 系统而言，对多云友好的 Terraform 是合理的默认。

这个系列做什么、不做什么

做的：

八篇之内带你从 terraform init 到一个完整的 research-agent-stack 跑在阿里云上。
给出 VPC、ECS、ACK、OSS、RDS、OpenSearch、KMS、SLS、CloudMonitor 的真实可运行 HCL。
覆盖文档里没有的失败模式——state 漂移、tfstate 锁死、GFW 下载 provider、区域库存。
最后给一个能 fork 的起手仓库。

不做的：

教 HCL 语法本身，超出我们要用的范围。HashiCorp 官方教程做得更好。
教你怎么写 Agent 本身。LangGraph、AutoGen、MetaGPT、Claude Code 都已经各自有系列，挑一个。
阿里云和 AWS / GCP 一项项对比。IaC 的模式跨云通用，资源名字不通用。

第二篇是第一次实操：装 alicloud provider，挑认证方式（静态 AK/SK、AssumeRole、ECS RAM role 三种不等价），用 OSS + Tablestore 配 remote state 加锁，以及 dev/staging/prod 的 workspace 模式。

如果今天只做一件事，把 Terraform 装上（macOS 上 brew install terraform，或者跟官方《Install Terraform》文档），跑 terraform version 确认。本系列后续都假设你已经装好了。

实操提示： 第一天就在 required_providers 里把 alicloud provider 版本钉死。这个 provider 在持续开发，minor 版本之间的 break change 不多但不为零。版本钉死意味着你周五跑出来的 terraform plan 周一还能得到同样的结果。