Terraform 管理云主机实战：从零创建腾讯云 CVM 与状态管理

1. 为什么我最终选择了 Terraform 来管理云主机

第一次接触云主机管理的时候，我和大多数人一样，登录控制台，点几下鼠标，选个镜像、挑个配置、确认订单，一台机器就开出来了。三五台的时候这么干没问题，但当环境一多、项目一杂，问题就来了：测试环境开了一台机器忘了关，月底账单多出几百块；生产环境的配置和测试环境不一致，排查半天发现是安全组规则少了一条；想把整套环境复制一份给新同事用，只能靠截图和文档，对方照着做还是各种踩坑。这些事经历几次之后，我就开始认真考虑用代码来管理基础设施了。

Terraform 就是解决这类问题的工具。它的核心思路叫基础设施即代码（Infrastructure as Code，简称 IaC），说白了就是把"我要几台机器、什么配置、什么网络"这些信息写进文本文件里，然后让工具去执行。这个文本文件可以提交到代码仓库、可以做版本对比、可以复制给任何人，环境的一致性就有了保障。我这次要做的，就是用 Terraform 在腾讯云上创建 CVM（Cloud Virtual Machine，云服务器），把整个流程从零跑通一遍。

这篇文章适合谁看？如果你手上有几台云主机，正在被配置不一致、环境难复制、账单失控这些问题困扰，那这篇内容就是写给你的。如果你完全没接触过 Terraform，也没关系，我会从安装开始一步步讲，把每个参数为什么这么填都说清楚。整个过程我会用腾讯云作为示例平台，因为它的 provider 文档比较完整，国内访问速度也稳定，适合作为入门练手。

需要提前说明的是，Terraform 本身是平台无关的，学会之后换成别的云平台，思路完全一样，只是 provider 和资源名称不同。所以这篇内容的价值不只是"教你开一台腾讯云主机"，而是帮你建立一套用代码管理云资源的思维方式。

2. Terraform 核心概念与工作原理拆解

2.1 Terraform 到底在做什么

要理解 Terraform，先要理解它和普通脚本的区别。很多人第一反应是"我用 shell 脚本调 API 不也能创建机器吗"，确实可以，但脚本有个致命问题：它只管创建，不管状态。你跑一遍脚本创建了一台机器，再跑一遍又创建一台，它不知道哪些资源已经存在、哪些需要更新、哪些需要删除。Terraform 的核心价值就在于它维护了一份状态文件（state file），记录了当前基础设施的真实情况，每次执行时它会对比"你想要的"和"现有的"，然后计算出需要做哪些操作。

这个对比过程叫plan，执行过程叫apply。你可以把 Terraform 想象成一个特别靠谱的装修队长：你给他一张设计图（配置文件），他先去现场看一遍（refresh），然后告诉你"这面墙要拆、那个插座要加"（plan），你确认没问题了他才动手（apply）。这个"先看再报再动手"的流程，是 Terraform 相比裸脚本最大的优势，也是它能在生产环境放心使用的原因。

Terraform 的工作流程可以概括为几个关键命令，我先把它们列出来，后面会逐个展开：

2.2 Provider 机制：Terraform 的"翻译官"

Terraform 本身其实不认识腾讯云、也不认识任何云平台。它之所以能操作各种云资源，靠的是provider（提供者）。Provider 是一个插件，它把 Terraform 的通用指令翻译成具体云平台的 API 调用。比如你写resource "tencentcloud_instance"，腾讯云的 provider 就知道要去调创建 CVM 的接口。

这个设计非常巧妙。Terraform 核心团队只需要维护核心逻辑，各个云厂商自己维护 provider，这样新服务上线时，厂商更新 provider 就行，不用等 Terraform 发版。目前主流的云平台都有自己的官方 provider，腾讯云的是tencentcloudstack/tencentcloud，在 Terraform Registry 上可以查到完整的资源文档。

Provider 的版本管理是个容易被忽视但很重要的点。我踩过的坑是：本地用了一个版本的 provider 跑通了，同事那边装了另一个版本，结果某些参数行为不一致，plan 出来的结果对不上。所以我的习惯是在配置文件里锁定 provider 版本，用version参数指定一个范围，避免不同人执行结果不一致。

2.3 状态文件：Terraform 的"记忆"

状态文件（默认叫terraform.tfstate）是 Terraform 最核心也最容易被误解的部分。它是一份 JSON 文件，记录了 Terraform 管理的所有资源的 ID、属性、依赖关系。每次 plan 和 apply 时，Terraform 都会读取这份文件，和配置文件对比，和云端真实状态对比，三方比对后才能算出正确的操作。

这里有个新手常犯的错误：把状态文件当成"配置文件"去手动编辑。绝对不要这么做。状态文件是 Terraform 自己维护的，手动改会导致状态和现实不一致，后续操作可能误删资源。如果确实需要调整，应该用terraform state系列命令，比如terraform state mv、terraform state rm，这些命令会安全地修改状态。

另一个关键问题是状态文件的存储位置。默认它存在本地，这在个人练习时没问题，但团队协作时就是灾难：两个人各自持有状态文件，互相覆盖，资源就乱了。生产环境的做法是把状态文件放到远程后端（backend），比如对象存储，所有人共享同一份状态，并且支持状态锁定，防止并发操作冲突。腾讯云的对象存储（COS）就支持作为 Terraform 的 backend，配置方式后面会讲。

2.4 配置文件的基本结构

Terraform 的配置文件用 HCL（HashiCorp Configuration Language）编写，后缀是.tf。它的语法比 JSON 友好，支持注释、变量、表达式。一个典型的配置文件包含几个部分：

• terraform 块：声明需要的 provider 和版本
• provider 块：配置 provider 的参数，比如密钥、地域
• resource 块：定义要创建的资源
• variable 块：定义可变的输入参数
• output 块：定义执行后要输出的信息

这种分块设计让配置很清晰。我个人的习惯是把 provider 配置、变量定义、资源定义分到不同文件里，比如provider.tf、variables.tf、main.tf、outputs.tf。Terraform 会自动加载目录下所有.tf文件，所以文件怎么分不影响执行，只影响可读性。对于稍微复杂一点的项目，分文件是必须的，否则一个几百行的文件找起来很痛苦。

3. 环境准备与腾讯云 Provider 配置实操

3.1 安装 Terraform 与验证

安装 Terraform 最简单的方式是去官网下载对应系统的二进制包，解压后把可执行文件放到 PATH 里。以 Linux 为例，大致流程是下载压缩包、解压、移动到/usr/local/bin，然后执行terraform version验证。macOS 用户可以用 Homebrew，一条brew install terraform就搞定。Windows 用户下载 exe 后加到环境变量即可。

安装完成后，第一件事是确认版本。我建议用 1.0 以上的版本，因为 0.12 之前的语法和现在差异很大，网上很多老教程还在用旧语法，容易混淆。执行terraform version会输出当前版本和最新的 provider 版本提示，这个提示很有用，能帮你判断是否需要升级。

提示：不要用包管理器里那些来路不明的 Terraform 包，版本可能很旧。认准官方发布的二进制文件，或者用官方推荐的包管理方式。

3.2 获取腾讯云访问凭证

Terraform 要操作腾讯云资源，必须有访问凭证。腾讯云用的是 SecretId 和 SecretKey 这一对密钥，在控制台的访问管理里可以创建。创建时要注意几点：一是这对密钥的权限范围，建议遵循最小权限原则，只授予需要的权限，不要图省事用主账号的密钥；二是密钥只会在创建时显示一次 SecretKey，一定要当场保存好，关掉页面就再也看不到了。

拿到密钥后，怎么传给 Terraform 是个安全问题。最不推荐的做法是直接写在配置文件里，因为配置文件通常要提交到代码仓库，密钥就泄露了。我常用的方式有两种：一是用环境变量，执行前export TENCENTCLOUD_SECRET_ID=xxx和export TENCENTCLOUD_SECRET_KEY=xxx，provider 会自动读取；二是用.tfvars文件存变量，然后把这个文件加到.gitignore里，不提交。

环境变量的方式最省事，适合本地开发。但要注意，环境变量在同一个终端会话里才有效，换个终端就没了。如果你经常需要切换不同的账号，可以写个小脚本，切换时 source 一下。团队协作时，更规范的做法是把密钥放到密钥管理服务里，执行时动态获取，不过这就属于进阶话题了。

3.3 编写 provider 配置

Provider 配置块告诉 Terraform 用哪个 provider、什么版本、什么地域。腾讯云 provider 的基本写法是这样：

terraform { required_providers { tencentcloud = { source = "tencentcloudstack/tencentcloud" version = "~> 1.81.0" } } } provider "tencentcloud" { region = "ap-guangzhou" }

这里source指定 provider 的来源地址，version用~>表示允许补丁版本升级但不跨小版本，这样既能拿到 bug 修复，又不会因为大版本变更导致行为不一致。region指定资源创建的地域，广州、上海、北京都是常用选择，选离用户近的延迟低。

地域这个参数有个细节：provider 级别的地域是默认值，单个资源也可以覆盖它。比如你大部分资源在广州，但有一台机器想放上海，可以在那个 resource 里单独指定availability_zone。不过跨地域的资源之间内网不通，除非用对等连接，所以一般一个项目固定一个地域比较省心。

3.4 执行 terraform init 的背后逻辑

配置写好后，第一步是terraform init。这个命令做几件事：扫描配置文件，找出需要的 provider，从 Registry 下载对应的插件到.terraform目录，初始化 backend，下载模块。第一次执行会看到下载进度，之后如果 provider 没变，再执行会很快，因为它会检查本地缓存。

init有个常见报错是网络问题导致下载失败。国内访问 Terraform Registry 有时会慢，可以配置镜像源加速。另一个报错是 provider 版本冲突，比如两个模块依赖了不兼容的版本，这时需要调整版本约束。init 成功后，目录下会多出.terraform文件夹和.terraform.lock.hcl文件，后者记录了实际使用的 provider 版本，建议提交到代码仓库，这样团队所有人用的版本完全一致。

注意：.terraform目录不要提交到仓库，它包含下载的二进制文件，体积大且和平台相关。.terraform.lock.hcl则应该提交，它是版本锁定的关键。

4. 用 Terraform 创建 CVM 的完整实操

4.1 定义变量让配置更灵活

在写资源之前，我习惯先把可变的部分抽成变量。这样同一套配置可以通过不同的变量值创建不同环境，不用改代码。变量定义在variables.tf里：

variable "instance_name" { description = "CVM 实例名称" type = string default = "tf-demo-cvm" } variable "instance_type" { description = "实例规格" type = string default = "S5.MEDIUM4" } variable "image_id" { description = "镜像 ID" type = string default = "img-9qabwvbn" } variable "password" { description = "实例密码" type = string sensitive = true }

这里sensitive = true很重要，它会让 Terraform 在输出时隐藏这个值，避免密码出现在日志里。密码这种敏感信息，我一般通过TF_VAR_password环境变量传入，或者用.tfvars文件配合 gitignore，绝不硬编码。

实例规格的选择有个经验：S5.MEDIUM4表示 S5 系列、2 核 4G。腾讯云的规格命名规则是"系列.规格"，数字部分通常第一位是核数相关，具体要查文档。选规格时不要只看核数和内存，还要看是标准型、计算型还是内存型，不同系列适用的场景不同。跑 Web 服务标准型够用，跑数据库要选内存型，跑计算密集任务选计算型。

4.2 编写 CVM 资源定义

核心的资源定义在main.tf里。创建一台 CVM 需要指定几个关键参数：可用区、实例规格、镜像、系统盘、网络、安全组、登录方式。下面是一个完整的例子：

resource "tencentcloud_instance" "demo" { instance_name = var.instance_name availability_zone = "ap-guangzhou-6" instance_type = var.instance_type image_id = var.image_id system_disk_type = "CLOUD_PREMIUM" system_disk_size = 50 allocate_public_ip = true internet_max_bandwidth_out = 5 security_groups = [tencentcloud_security_group.demo.id] password = var.password tags = { Environment = "demo" ManagedBy = "terraform" } }

逐个参数说下我的理解。availability_zone是可用区，同一个地域下有多个可用区，选哪个影响不大，但要注意某些规格不是所有可用区都有。system_disk_type里CLOUD_PREMIUM是高性能云硬盘，还有CLOUD_SSD和CLOUD_BASIC，性能依次递减，价格也递减。系统盘 50G 是起步，跑 Docker 或者装的东西多的话建议 100G 起。

allocate_public_ip = true表示分配公网 IP，这个参数很关键。如果不分配，机器只有内网 IP，外网访问不了。internet_max_bandwidth_out是公网出带宽，单位 Mbps，5 是最低档，按流量计费的话这个值影响不大，但按带宽计费时就是实际带宽上限。带宽计费方式在创建时如果不指定，默认是按流量，适合流量小的场景。

security_groups引用了一个安全组资源，这个安全组也要在同一个配置里定义。安全组是云主机的防火墙，不配置的话默认拒绝所有入站，机器创建出来也连不上。安全组的定义后面单独讲。

tags是标签，强烈建议加上。标签能帮你按项目、环境、负责人分类资源，账单分析、批量操作时特别有用。我见过太多人资源开了一堆，最后分不清哪台是干嘛的，只能靠 IP 猜。加上ManagedBy = "terraform"这个标签，还能一眼看出哪些资源是 Terraform 管的，避免手动误删。

4.3 安全组配置：别让机器裸奔

安全组是云主机的第一道防线。默认安全组通常只开了 22 端口（Linux SSH），其他都关着。如果你要跑 Web 服务，得手动放行 80、443。安全组的配置逻辑是：先定义安全组，再定义规则，规则里指定方向、协议、端口、来源。

resource "tencentcloud_security_group" "demo" { name = "tf-demo-sg" description = "Terraform 示例安全组" } resource "tencentcloud_security_group_rule" "ssh" { security_group_id = tencentcloud_security_group.demo.id type = "ingress" protocol = "tcp" port_range = "22" cidr_ip = "0.0.0.0/0" description = "SSH 访问" }

这里cidr_ip = "0.0.0.0/0"表示允许所有 IP 访问 22 端口。这在生产环境是极其危险的，等于把 SSH 端口暴露给全世界，会被暴力破解。正确做法是限制成你自己的办公网 IP 段，比如1.2.3.0/24。如果 IP 不固定，可以用跳板机或者密钥登录加端口改非标准值来降低风险。

提示：安全组规则的方向ingress是入站，egress是出站。默认出站全放行，一般不用改。入站规则要按需最小化开放，能不开的端口坚决不开。

4.4 执行 plan 与 apply 的完整过程

配置写好后，执行顺序是terraform init→terraform plan→terraform apply。init 前面讲过，重点说 plan 和 apply。

terraform plan会输出一个执行计划，用+表示新增、-表示删除、~表示修改。第一次执行时，你会看到所有资源都是+，因为都是新建。仔细看这个计划，确认要创建的资源数量、规格、配置都对。plan 的输出最后会有一行汇总，比如 "Plan: 3 to add, 0 to change, 0 to destroy."，这个数字要和你预期一致。

确认无误后执行terraform apply，它会再次显示计划并让你输入yes确认。这个二次确认是防止误操作的重要机制，不要用-auto-approve跳过，除非是在自动化流水线里。apply 过程中会实时输出每个资源的创建进度，创建 CVM 通常需要一两分钟，因为要分配资源、初始化系统。

apply 完成后，Terraform 会把新创建的资源信息写入状态文件。这时候你可以用terraform output查看定义的输出，或者直接去控制台确认机器是否创建成功。我习惯在outputs.tf里输出公网 IP，方便后续连接：

output "public_ip" { description = "CVM 公网 IP" value = tencentcloud_instance.demo.public_ip }

4.5 验证与连接测试

机器创建出来后，第一件事是验证能不能连上。用ssh root@<公网IP>，密码就是变量里传的那个。如果连不上，按这个顺序排查：安全组有没有放行 22 端口、公网 IP 是否分配、机器是否还在初始化中（刚创建的前几十秒可能 SSH 服务还没起来）。

连上之后，可以跑几个命令确认机器状态：uname -a看系统版本、df -h看磁盘、free -h看内存。这些信息和你配置里指定的规格对比一下，确认没有偏差。如果发现规格不对，可能是镜像和规格不兼容，Terraform 会自动选一个可用的，这种情况 plan 阶段会有提示。

5. 状态管理与团队协作的进阶实践

5.1 远程后端配置

本地状态文件在个人练习时够用，但一旦涉及团队协作或者多台机器操作，就必须换成远程后端。腾讯云的对象存储（COS）可以作为 Terraform 的 backend，配置方式是在terraform块里加 backend 配置：

terraform { backend "cos" { bucket = "my-terraform-state-1250000000" region = "ap-guangzhou" prefix = "cvm-demo/terraform.tfstate" } }

配置好后执行terraform init，Terraform 会提示是否迁移本地状态到远程，选 yes 即可。之后所有状态操作都走远程，多人协作时状态是共享的，还支持锁定，防止两个人同时 apply 导致冲突。

这里有个坑：backend 配置里不能使用变量，必须是硬编码的值。这意味着不同环境要用不同的 backend 配置，通常的做法是用-backend-config参数在执行时传入，或者用不同的目录隔离。我一般按环境分目录，每个目录一套配置，简单直接。

5.2 状态文件的日常维护

状态文件虽然不用手动编辑，但有些维护操作是必须会的。比如某个资源是手动在控制台创建的，现在想纳入 Terraform 管理，可以用terraform import命令把它的 ID 导入状态。导入后还要在配置文件里补上对应的 resource 定义，否则下次 plan 会认为要删除它。

另一个常见操作是terraform state list查看当前管理的所有资源，terraform state show <资源地址>查看某个资源的详细属性。当 plan 结果和预期不符时，这两个命令能帮你快速定位问题。比如你明明改了配置但 plan 显示没变化，可能是资源地址写错了，state list 一看就知道。

注意：状态文件包含敏感信息，比如密码、密钥，所以远程后端的存储桶权限要严格控制，只给需要的人访问。本地状态文件也不要随便发给别人。

5.3 用模块组织复杂配置

当资源多起来之后，把所有东西写在一个目录里会变得难以维护。Terraform 的模块（module）机制可以把一组相关资源打包，通过输入输出参数复用。比如你可以写一个"标准 Web 服务器"模块，输入是规格和数量，输出是 IP 列表，然后在不同项目里调用。

模块的调用方式是在配置里写module块，指定模块来源（本地路径或 Registry）和输入变量。模块化之后，创建一套完整环境可能只需要十几行配置，大大提升了复用性。不过模块也不是越多越好，过度抽象会让配置变得难懂，我的经验是：重复三次以上的配置才值得抽成模块，否则直接写更直观。

6. 常见问题排查与避坑经验

6.1 创建失败的典型原因

CVM 创建失败的原因五花八门，我整理了几个高频的：

密码这个坑我踩过。腾讯云对密码有复杂度要求，太简单的会被拒。而且密码里如果有特殊字符，在 shell 里传环境变量时可能被转义，导致实际传进去的和预期的不一样。我的做法是生成一个符合要求的随机密码，避免手动设置。

6.2 plan 结果异常的排查思路

plan 结果和预期不符，通常有几个原因。一是状态漂移，就是有人在控制台手动改了资源，导致状态文件和现实不一致。这时 plan 会显示要把资源改回去。解决方法是先terraform refresh同步状态，再决定是接受手动改动还是让 Terraform 覆盖。

二是依赖关系问题。Terraform 会自动分析资源依赖，但有时候隐式依赖识别不出来，导致创建顺序错误。比如安全组规则依赖安全组，如果没写对引用，可能规则先创建然后失败。解决方法是显式用depends_on声明依赖。

三是provider 版本差异。前面提过，不同版本的 provider 对同一参数的处理可能不同。团队协作时锁定版本能避免这个问题。

6.3 销毁资源的正确姿势

terraform destroy会删除配置里定义的所有资源，这个操作不可逆，执行前一定要确认。我见过有人想销毁测试环境，结果在错误的目录执行，把生产环境删了。避免这种事故的方法：一是执行前先terraform plan -destroy看看要删什么，二是给生产环境的状态文件加保护，比如用不同的 backend 和严格的权限控制。

销毁时还有个细节：有些资源有删除保护，比如开启了删除保护的数据库，直接 destroy 会失败。需要先在配置里关掉保护，apply 一次，再 destroy。CVM 一般没有这个限制，但如果有挂载的云硬盘，要注意数据备份。

6.4 成本控制的实用技巧

用 Terraform 管理资源后，成本控制变得更容易，因为所有资源都在代码里，一目了然。我的几个习惯：一是给所有资源打上Environment标签，月底按标签分析账单，能清楚看到每个环境花了多少；二是测试环境用按量计费，不用了就 destroy，避免闲置浪费；三是定期跑terraform plan，如果显示有资源要创建但你不知道，说明有人手动改了东西，及时处理。

还有个技巧是用terraform state把不再管理的资源移出状态，但不删除。比如某台机器要转交给别人管理，用terraform state rm把它从状态里移除，Terraform 就不再管它了，机器本身还在运行。这个操作要小心，移除后 Terraform 就"忘记"它了，后续不会再对它做任何操作。

7. 我在这套流程里踩过的坑和总结的经验

回过头看，从第一次用 Terraform 到现在，踩的坑主要集中在几个方面。最开始是密钥管理，图省事把 SecretKey 写在了配置文件里，后来意识到要提交代码，赶紧改成环境变量，还好没造成损失。这件事让我养成了习惯：任何配置在写之前先想清楚它会不会进仓库，会进仓库的绝不写敏感信息。

然后是状态文件。早期不懂远程后端，和同事各自维护状态，结果两边都 apply 了一次，创建出两套资源，账单翻倍。后来统一用 COS 做后端，问题才解决。这个教训是：团队协作的基础设施代码，状态管理必须一开始就规划好，事后迁移很麻烦。

再就是安全组。刚开始为了图方便，入站规则直接开0.0.0.0/0全端口，结果机器被扫，日志里全是暴力破解记录。后来改成只开必要端口，SSH 限制来源 IP，世界清净了。安全这件事，省事的做法往往是最危险的。

最后说个正向的经验：把 Terraform 配置纳入代码审查。每次修改配置都走 PR 流程，让同事看一眼 plan 结果，能发现很多自己忽略的问题。比如有人不小心把实例规格改大了，plan 里会显示要重建机器，审查时就能拦下来。这套流程跑顺之后，基础设施的变更变得可控多了，再也不会出现"谁把生产环境改了"这种扯皮的事。

如果你刚开始用 Terraform，我的建议是先用它管理一两个非关键资源，把 init、plan、apply、destroy 这套流程跑熟，理解状态文件的作用，再逐步扩大范围。别一上来就把生产环境全托管，那样出问题的代价太大。等这套工具用顺手了，你会发现它带来的确定性和可复现性，是手动操作永远给不了的。