在腾讯云上维护 CDN 加速域名时，如果团队还停留在控制台手工修改源站、缓存规则和证书，很容易出现配置漂移、操作无记录、回滚困难等问题。Terraform 的声明式模型可以把这些配置统一写成 HCL 文件，用版本控制系统管理变更历史，用 plan 预览差异，用 apply 收敛状态。这种思路和基础设施即代码完全一致，CDN 不再是一个黑盒，而是可以审计、可以复现的资源集合。
用 Terraform 管理 CDN 的收益与前提
传统的 CDN 配置依赖控制台操作，一个域名上线后，后续的源站切换、缓存过期时间调整、回源协议修改都靠手工完成。一旦多人协作，就面临三个问题：变更过程没有记录，无法追溯是谁在什么时候改了什么；不同环境之间配置不一致，测试环境和生产环境逐渐漂移；出现问题时难以快速回滚，只能凭记忆恢复。Terraform 通过代码描述目标状态，任何一次修改都会先在代码评审中被讨论，再通过 CI 流程执行，状态文件记录了资源的实际信息，可以随时对比差异。
要在腾讯云上使用 Terraform，首先需要安装 Terraform CLI，并在代码目录中声明腾讯云 Provider。Provider 负责处理 API 认证和资源生命周期管理，认证信息通常通过环境变量或变量文件注入，不要写死在代码里。腾讯云的 API 密钥需要配置 SecretId 和 SecretKey，并为子账号赋予 CDN 管理与 COS 权限。下面是一个基础的 Provider 初始化配置。
terraform {
required_providers {
tencentcloud = {
source = "tencentcloudstack/tencentcloud"
version = "~> 1.81"
}
}
}
provider "tencentcloud" {
region = "ap-guangzhou"
secret_id = var.secret_id
secret_key = var.secret_key
}
variable "secret_id" {
type = string
sensitive = true
}
variable "secret_key" {
type = string
sensitive = true
}
这里使用 required_providers 指定腾讯云 Provider 来源和版本，版本约束可以避免由 Provider 升级引入的破坏性变更。认证参数使用 sensitive = true 的变量，这样在执行 terraform plan 或 terraform apply 时不会在输出中明文显示密钥内容。如果团队使用多个地域，可以将 region 改为变量，由环境决定。
核心资源 tencentcloud_cdn_domain 的配置拆解
腾讯云 CDN 域名在 Terraform 中对应 tencentcloud_cdn_domain 资源。一个完整的 CDN 加速配置通常包含加速域名、服务类型、加速区域、源站列表、回源协议、缓存规则以及 HTTPS 配置等。下面的示例创建了一个面向中国大陆的 Web 加速域名，源站使用自有域名并跟随回源协议。
resource "tencentcloud_cdn_domain" "example" {
domain = "cdn.ipipp.com"
service_type = "web"
area = "mainland"
origin {
origin_list = ["origin.ipipp.com"]
origin_type = "domain"
origin_pull_protocol = "follow"
}
tags = {
env = "production"
}
}
domain 字段必须是已完成备案的域名，否则 API 会返回错误。 service_type 支持 web、download、media 等类型，分别对应网页小文件、大文件下载和音视频点播场景。 area 控制加速范围，可选 mainland、overseas 或 global。源站配置中的 origin_list 可以填写多个源站地址，当第一个源站不可用时 CDN 会自动切换到后续源站，实现简单的源站容灾。
除了基础字段，这个资源还支持很多高级参数。例如 origin_pull_protocol 的取值可以是 http、https 或 follow，分别表示强制 HTTP 回源、强制 HTTPS 回源以及跟随客户端协议回源。生产环境一般建议选 follow，这样既能保持灵活的访问方式，又不会因为协议转换导致源站内容不一致。另外，通过 tags 参数可以为资源打上标签，方便后续按环境或业务维度统计成本、过滤资源。
缓存规则、HTTPS 证书与回源高级配置
缓存规则决定了哪些内容由 CDN 边缘节点缓存、缓存多久、是否忽略查询字符串等问题。在 Terraform 中，可以通过 cache_key 和 cache 两个嵌套块来控制。 cache_key 定义缓存键的生成方式，例如是否完整保留 URL、是否对查询字符串排序或忽略特定参数。 cache 则设置具体的缓存过期时间，可以按文件类型、目录或全部请求配置不同规则。
resource "tencentcloud_cdn_domain" "example" {
domain = "cdn.ipipp.com"
service_type = "web"
area = "mainland"
origin {
origin_list = ["origin.ipipp.com"]
origin_type = "domain"
origin_pull_protocol = "follow"
}
cache_key {
full_url_cache = "off"
query_string {
switch = "on"
reorder = "off"
}
}
cache {
rule_type = "all"
cache_time = 3600
}
}
上面示例中， cache_key 的 full_url_cache 设为 off，表示不缓存完整 URL，而是基于规范化后的路径和部分查询字符串生成缓存键。 query_string 开启后，CDN 会将查询字符串纳入缓存键计算，但 reorder 为 off 时不会对参数顺序进行重新排序，这意味着 a=1&b=2 和 b=2&a=1 会被当作两个不同的缓存对象。如果业务允许参数顺序变化，可以将 reorder 打开，提升缓存命中率。
HTTPS 配置是 CDN 域名上线前的关键一步。腾讯云 CDN 支持证书托管在 SSL 证书服务中，也可以在 Terraform 中直接传入证书内容。对于自动化运维而言，推荐将证书 ID 存放到变量中，由 Terraform 引用，证书的实际值通过 CI 环境变量注入。下面是一个启用 HTTPS、HTTP/2 和强制跳转的示例。
resource "tencentcloud_cdn_domain" "example" {
domain = "cdn.ipipp.com"
service_type = "web"
area = "mainland"
origin {
origin_list = ["origin.ipipp.com"]
origin_type = "domain"
origin_pull_protocol = "follow"
}
https_config {
https_switch = "on"
http2_switch = "on"
cert_type = "sni"
cert = var.cert_id
private_key = var.cert_key
force_redirect {
switch = "on"
redirect_type = "https"
}
hsts {
switch = "on"
max_age = 31536000
include_sub_domains = "on"
}
}
}
cert_type 为 sni 时使用 SNI 证书，适合多域名共享同一 IP 的场景。 cert 和 private_key 分别对应证书公钥和私钥，若证书已经上传到腾讯云 SSL 证书服务，则只需要填写证书 ID，无需在 Terraform 中暴露私钥内容。 hsts 块开启后，浏览器会强制使用 HTTPS 访问该域名， max_age 单位是秒，表示 HSTS 策略的生效时长。生产环境建议开启 HSTS，有效降低中间人攻击风险。
状态管理、模块化与自动化流水线
Terraform 的状态文件记录了资源与真实云资源之间的映射关系。多人协作时必须使用远程状态存储，否则本地的 terraform.tfstate 文件会导致状态冲突和误删风险。腾讯云对象存储 COS 可以作为 Terraform 的远程后端，通过 backend "cos" 配置将状态文件保存在 COS 桶中，同时利用 COS 的版本控制保留历史状态。使用远程后端后，团队所有成员共享同一份状态，执行 plan 或 apply 时 Terraform 会自动从 COS 拉取最新状态。
terraform {
backend "cos" {
bucket = "terraform-state-1234567890"
prefix = "cdn"
region = "ap-guangzhou"
}
}
状态文件中可能包含敏感信息，例如证书私钥、API 密钥等，因此 COS 桶应设置严格的访问控制，仅允许运维人员的子账号读写。同时，建议为 COS 桶开启版本控制，这样如果某次 apply 导致状态异常，可以快速从历史版本恢复。对于生产环境，还可以引入状态锁机制，防止两个人同时执行 apply 产生冲突。
当 CDN 域名资源增多后，重复写相同的 origin、 cache_key 配置会变得难以维护。Terraform 的模块化能力可以将这些通用配置封装成可复用模块，调用方只需传入业务相关的少量参数。比如把所有加速域名的缓存策略统一封装，不同项目只传入域名和源站信息即可。
module "cdn_domain" {
source = "./modules/cdn_domain"
domain = "static.ipipp.com"
origin_list = ["origin.ipipp.com"]
cache_time = 3600
https_switch = "on"
cert_id = var.cert_id
}
在 CI/CD 流水线中集成 Terraform 是自动化运维的最后一环。代码推送到 Git 仓库后，CI 系统按照三个步骤执行：先运行 terraform fmt -check 验证格式，再运行 terraform plan 生成变更计划并输出给代码评审人查看，最后在合并到主分支后执行 terraform apply 自动应用变更。这样每一次 CDN 配置调整都有完整的代码评审记录，任何变更都可以被审计和回滚。
常见问题与避坑指南
使用 Terraform 管理腾讯云 CDN 时，有几个容易踩坑的地方需要特别注意。首先是已有资源的导入问题，如果 CDN 域名已经在控制台创建，直接执行 apply 会尝试新建资源并报错。此时需要使用 terraform import 命令把现有资源导入到状态文件中，命令格式为 terraform import tencentcloud_cdn_domain.example cdn.ipipp.com。导入后还需要仔细核对代码中的参数是否与控制台配置一致，否则下一次 plan 可能会显示大量差异。
其次是缓存键配置与业务缓存命中率的关系。很多团队默认关闭查询字符串缓存，但实际上某些动态参数需要影响缓存结果，例如带有用户身份标识的参数就不应该被完全忽略。如果配置不当，可能导致不同用户看到相同缓存内容，或者缓存命中率过低。建议在接入 CDN 前梳理 URL 参数对内容的影响，再决定 cache_key 的具体策略。
最后是敏感信息的管理。虽然 Terraform 支持 sensitive = true，但状态文件中仍会明文存储证书私钥或 API 密钥。对于生产环境，建议使用密钥管理服务存储敏感值，Terraform 通过数据源动态获取，或者将证书托管到腾讯云 SSL 证书服务，只把证书 ID 写入代码。另外，远程状态存储的 COS 桶必须开启访问控制，不要使用公共读权限。