terraform init时，律速往往落在三件事：跨境访问 registry.terraform.io 的延迟与 429、多作业并发写入同一插件缓存目录、以及镜像端与锁文件校验不一致。本文给出可复制的provider_installation与环境变量、失败重试阶梯与磁盘水位门禁，并附对照矩阵与 FAQ。内链：日文站首页、技术博客列表、容器 Registry 越境决策表（免登录阅读）。
痛点拆解（先对齐再调参）
1. 直连公网 registry 时，跨境 RTT 与中间代理的 idle 超时叠加，表现为 handshake 慢或间歇 429，需要镜像近源或拉长 TF_REGISTRY_CLIENT_TIMEOUT并降低并发。
2. 多个 Runner 进程共享同一TF_PLUGIN_CACHE_DIR且无文件锁策略时，可能出现缓存半成品或校验抖动，应每作业子目录或串行化 init。
3. 仅改模块版本而未重新执行terraform providers lock，或镜像返回的 zip 与锁内 digest 不一致，会在 CI 上形成不可复现；须把锁文件提交与lock -check-only门禁写进流水线。
评测维度与阈值
下列阈值为远程 Mac上 Apple Silicon + NVMe 场景的起步建议，可按 P95 与 429 频率上下调整一档。
| 维度 | 观察指标 | 建议阈值 | 动作 |
|---|---|---|---|
| 网络 | registry 请求 P95 | > 3 s 连续 5 次 | 启用 mirror 或上调超时并减半并发 worker |
| 并发 | 同时 terraform 进程数 | 每机 1～2（越境） | 队列化；与组织内其他 docker/npm 拉取错峰 |
| 退避 | 429 / 5xx 重试 | 4 → 12 → 30 → 90 s（上限 120 s） | 每失败一档并发再减一 |
| 磁盘 | 插件缓存卷使用率 | 告警 80% / 限流 85% / 停拉 90% | 清理历史 workspace 或扩容；与 Docker 层缓存分卷 |
- 可引用：
TF_REGISTRY_CLIENT_TIMEOUT起步建议 120～300 s（跨境）；直连稳定后可降到 60 s。 - 可引用：插件缓存目录与 workspace 分离，例如
TF_PLUGIN_CACHE_DIR=$RUNNER_TEMP/terraform-plugin-cache/$CI_JOB_ID。 - 可引用：排障时短期
TF_LOG=INFO或TF_LOG=DEBUG，落盘TF_LOG_PATH避免 stdout 被 CI 截断。
可执行命令/环境变量清单
将TF_CLI_CONFIG_FILE指向受版本管理审查的副本，避免本地默认路径被开发者机器污染。
provider_installation {
network_mirror {
url = "https://YOUR_MIRROR_HOST/terraform/providers/"
include = ["registry.terraform.io/*/*"]
}
direct {
exclude = ["registry.terraform.io/*/*"]
}
}
| 变量/开关 | 作用 | 示例值 |
|---|---|---|
TF_CLI_CONFIG_FILE | 指定 terraform.rc | $PWD/.terraformrc.ci |
TF_PLUGIN_CACHE_DIR | 插件 zip 缓存 | 每作业唯一子目录 |
TF_REGISTRY_CLIENT_TIMEOUT | HTTP 客户端超时 | 300s（跨境） |
TF_LOG / TF_LOG_PATH | 诊断日志 | INFO + 文件路径 |
terraform init | 非交互 | terraform init -input=false -no-color |
terraform providers lock | 生成/刷新锁 | -platform=darwin_arm64 等目标三元组 |
含 mirror 与 direct.exclude，URL 用内网可达主机名。
在 init 之前设置超时、缓存目录与可选日志路径。
terraform providers lock -platform=darwin_arm64 并提交 .terraform.lock.hcl。
shell 外层 for 循环 + sleep 阶梯；失败两次后降低其他并行 stage。
terraform fmt -check、terraform validate、terraform providers lock -check-only。
terraform fmt -check -recursive terraform init -backend=false -input=false -no-color terraform validate -no-color terraform providers lock -check-only -platform=darwin_arm64
对比表或决策矩阵
| 路线 | 适用 | 优点 | 风险/成本 |
|---|---|---|---|
| 直连 registry.terraform.io | 低并发、网络稳定 | 配置最少 | 跨境 429、TLS 与审计不可控 |
| network_mirror + direct.exclude | 企业内网、需固定出口 | 带宽与失败面可控 | 镜像同步与版本索引运维 |
| airgap bundle（预置插件 zip） | 强隔离 | 无外联 | 发布链路长、锁文件必须与 bundle 对齐 |
决策提示：若每周出现两次以上 429，优先落 mirror 或拆分 registry 读路径；若仅偶发超时，先调TF_REGISTRY_CLIENT_TIMEOUT与并发再评估镜像。
FAQ
检查TF_CLI_CONFIG_FILE是否在 CI 被覆盖；direct未正确 exclude 或 mirror 不可达时会回退。用 TF_LOG=DEBUG 看实际下载主机名。
为每个 job 使用独立子目录或加文件锁；同一磁盘上过高并发会放大元数据延迟。
在可访问官方源的环境重跑 terraform providers lock，提交更新后的 .terraform.lock.hcl；镜像侧确认与官方校验和一致。
总结
把超时、并发、缓存目录隔离、锁文件校验写进同一套流水线后，远程 Mac 上的 terraform init 才能与团队内其它越境拉取（容器、Helm 等）错峰共存。需要固定 Apple Silicon 与 NVMe 验证环境时，可在免登录页面完成选型。