🚫 Terraform 在 Docker 中 .terraformrc 不生效？彻底搞懂 TF_CLI_CONFIG_FILE 与 Provider 镜像配置

关键词：Terraform、阿里云、Provider 镜像、filesystem_mirror、network_mirror、TF_CLI_CONFIG_FILE、Docker、RAM 权限、Forbidden.RAM

💥 起因：一个看似简单的 init 卡住

在使用 Terraform 部署阿里云资源时，你可能会遇到：

• 初始化卡在 Finding aliyun/alicloud versions...
• 报错 context deadline exceeded（GitHub 超时）
• 即使配置了 .terraformrc，Terraform 依然走官方 registry

更诡异的是：

把 .terraformrc 放在 /root/.terraformrc 没用，但通过 TF_CLI_CONFIG_FILE=/xxx/.terraformrc 就能生效！

这在 Docker 容器中尤为常见。

🔍 根本原因：Docker 中“家目录”不是你以为的家目录

Terraform 默认从 当前用户的家目录（$HOME）加载配置文件：

• Linux: $HOME/.terraformrc
• Windows: %APPDATA%\terraform.rc

但在 Docker 容器中：

• 如果你以 root 启动，$HOME 是 /root
• 但如果你通过 docker exec -u www-data 或 PHP-FPM 进程运行 Terraform，$HOME 可能是 /var/www 或 /nonexistent
• 此时 Terraform 根本不会去读 /root/.terraformrc！

✅ 结论：
在容器化、脚本化、多用户环境下，依赖 $HOME/.terraformrc 是不可靠的。

✅ 正确姿势：强制指定配置文件路径

使用 环境变量 TF_CLI_CONFIG_FILE 显式指定配置文件路径：

export TF_CLI_CONFIG_FILE=/etc/terraform/.terraformrc
terraform init

或在 PHP 中：

putenv('TF_CLI_CONFIG_FILE=/var/www/.terraformrc');
shell_exec('terraform init');

✅ 这是 100% 可靠 的方式，不受用户、Shell、Docker 镜像影响。

🌐 镜像源怎么选？两种方案对比

方案一：使用阿里云官方 Network Mirror（推荐）

# /var/www/.terraformrc
provider_installation {
  network_mirror {
    url = "https://mirrors.aliyun.com/terraform/"
    include = ["registry.terraform.io/aliyun/alicloud"]
  }
  direct {
    exclude = ["registry.terraform.io/aliyun/alicloud"]
  }
}

✅ 优点：

• 无需手动下载 provider
• 自动支持新版本
• 国内访问快
• 支持签名验证（无需 TF_SKIP_PROVIDER_VERIFY_SIGNATURES）

方案二：本地 Filesystem Mirror（离线场景）

provider_installation {
  filesystem_mirror {
    path    = "/terraform-mirror"
    include = ["registry.terraform.io/aliyun/alicloud"]
  }
  direct {
    exclude = ["registry.terraform.io/aliyun/alicloud"]
  }
}

⚠️ 要求：

• 目录结构必须为：/terraform-mirror/registry.terraform.io/aliyun/alicloud/1.262.1/...
• 需手动准备二进制、SHA256SUMS、.sig 文件
• 通常需配合 TF_SKIP_PROVIDER_VERIFY_SIGNATURES=true

📌 除非完全离线，否则优先选阿里云 network mirror！

🔒 权限别忘：RAM 用户必须授权

即使 Terraform 能下载 provider，部署时仍可能报错：

Forbidden.RAM: User not authorized to operate on the specified resource
AuthAction: vpc:CreateVpc

✅ 解决方案：

1. 登录阿里云主账号
2. 进入 RAM 控制台
3. 为子用户授权：
   • 系统策略：AliyunVPCFullAccess + AliyunECSFullAccess + AliyunSLBFullAccess（按需）
   • 或自定义最小权限策略

🛡️ 安全建议：永远不要在生产环境使用主账号 AK，坚持“子用户 + 最小权限”。

📦 Docker 部署最佳实践

在 Dockerfile 中：

COPY .terraformrc /etc/terraform/.terraformrc
ENV TF_CLI_CONFIG_FILE=/etc/terraform/.terraformrc
# 不要依赖 HOME

在 docker-compose.yml 或 Kubernetes 中：

environment:
  - TF_CLI_CONFIG_FILE=/etc/terraform/.terraformrc

PHP 调用时也显式设置：

putenv('TF_CLI_CONFIG_FILE=/etc/terraform/.terraformrc');

✅ 总结：记住这三点，再也不踩坑

🙌 结语

Terraform 的配置看似简单，但在容器化、自动化、多云环境下，细节决定成败。
不要假设“家目录存在”、“网络畅通”、“权限足够” —— 显式配置、最小权限、国内镜像，才是稳定交付的基石。

本文已验证于 Terraform v1.5+、阿里云 Provider v1.262+、Docker + PHP 自动化部署场景。

如果你觉得这篇总结有帮助，欢迎点赞、收藏或转发给同样在“terraform init 卡一天”的同事 😄