OpenTofu：从独立 CLI、Provider 信任到 State 加密
OpenTofu 与 Terraform 共享大量 HCL 语法和操作习惯，但它拥有独立的 tofu 可执行文件、发行节奏、Registry、Provider 分发信任和扩展能力。把 tofu 隐藏在 terraform 别名后，日志就无法证明谁生成过计划、谁最后写入 State；把两套 CLI 轮流指向同一个 Backend，更会让兼容假设直接进入资源身份账本。
OpenTofu 的工程价值不在于“换一个命令名”。团队选择它之后，要能固定 CLI 与 Provider 来源，重放计划，保护 State，验证加密元数据，处理版本迁移，并在执行失败后恢复到可解释状态。Terraform 的完整入口见 Terraform；共同的漂移分类、地址迁移和销毁防护见 State、漂移与销毁防护。
安装后先证明实际执行的是 tofu
安装入口以 OpenTofu 官方安装说明 为准。开发机可以使用系统包管理器，CI 更适合使用固定版本、带摘要的工具镜像或组织内部制品缓存。安装完成后同时记录路径和版本，避免 PATH 前部残留旧二进制。
winget install --exact --id OpenTofu.Tofu
Get-Command tofu | Format-List Source,Version
tofu version
tofu -help升级前先在隔离目录对真实模块执行 init -backend=false、validate 和只读计划。CLI 升级、Provider 升级与模块升级是三条不同变更线，不要放进同一个无法归因的 Pull Request。卸载也不能只删二进制：用户级 tofu.rc 或 .tofurc、TF_CLI_CONFIG_FILE 指向的镜像配置、插件缓存、登录凭据和本地 State 都要逐项确认归属。
OpenTofu 采用 MPL 2.0，项目治理和发行由 Linux Foundation 体系承载。许可证不等于所有模块、Provider 和远端服务都使用相同许可；将 OpenTofu 嵌入托管产品或内部发行镜像时，仍要分别盘点 CLI、Provider、模块和附带工具的来源与义务。
配置、资源图、Provider 与 State 各自承担什么
HCL 配置表达期望对象和引用关系，资源图决定创建、读取、更新与删除的先后约束，Provider 把抽象资源转换为目标 API 调用，State 保存配置地址与远端对象身份的映射。Backend 只规定 State 存取与锁的位置，不能替代目标平台的权限、备份与审计。
terraform {
required_providers {
local = {
source = "hashicorp/local"
version = "2.5.3"
}
}
}
variable "content" {
type = string
sensitive = true
}
resource "local_sensitive_file" "demo" {
filename = "${path.module}/out/demo.txt"
content = var.content
file_permission = "0600"
}sensitive = true 主要控制终端和计划 UI 的展示，并不保证值不会进入 State。Provider 若需要该值完成刷新或后续更新，它仍可能被持久化。State 加密解决的是持久数据的机密性，不会自动消除计划文件、调试日志、目标 API、生成文件和进程环境中的副本。
用无云实验看清 plan 与 apply 的绑定
先在临时目录使用合成值运行，不要拿真实云账号验证基本语义。初始化后保存计划，再将同一份计划交给执行步骤；审批对象应是计划摘要和制品哈希，而不是随后重新计算的一份计划。
$env:TF_VAR_content = 'synthetic-not-a-secret'
tofu init
tofu fmt -check
tofu validate
tofu plan -out .tofuplan
Get-FileHash .tofuplan -Algorithm SHA256
tofu show .tofuplan
tofu apply .tofuplan
Get-Content out/demo.txt
tofu state list计划文件可能包含敏感值和完整资源变化，应进入短保留、受权限控制的制品存储，不能作为普通 CI artifact 长期公开。执行完成后用 tofu show、目标对象回读和 State 列表三方核对；只看退出码无法发现 Provider 已返回成功但目标端随后被策略回滚的情况。
反向实验可以在保存计划后修改配置，再尝试执行旧计划。OpenTofu 会执行被保存的动作，而不是自动吸收新配置；这正说明提交、计划与审批必须绑定。若流水线在审批后重新 plan，评审过的对象已经被悄悄替换。
Provider 来源与签名进入供应链门禁
tofu init 会解析 Provider 版本并写入 .terraform.lock.hcl。锁文件保存选择结果和校验信息，应随代码评审；它不锁 CLI，也不保证模块来源不可移动。Registry 主机、namespace、类型和版本共同构成 Provider 身份，内部镜像不能只复制 zip 而丢失验证元数据。
OpenTofu Registry 对 Provider 签名有自己的信任模型。官方或社区签名状态、密钥来源与下载主机都应出现在初始化日志中；企业镜像需要保存原始包、摘要、签名材料和同步记录。首次生成锁文件时应在受信网络和已知平台上完成，多平台 CI 则显式补齐目标平台哈希。
tofu providers
tofu providers lock -platform=windows_amd64 -platform=linux_amd64
git diff -- .terraform.lock.hcl
tofu init -lockfile=readonly反向验证是在隔离镜像中删掉所需版本或替换摘要，init -lockfile=readonly 必须失败。若流水线自动重写锁文件并继续，供应链门禁实际上允许下载内容自行改变批准身份。Provider 升级要单独生成计划，关注 schema 迁移、默认值变化、ForceNew 属性和读取行为，而不是只看版本号跨度。
State 加密要同时设计方法、密钥和回退
OpenTofu 提供原生 State 与 Plan 加密能力。加密配置描述密钥提供者、加密方法和应用目标；密文中仍需保存必要元数据，读取方必须拥有对应配置和解密材料。启用前先盘点所有 State 读写者：开发机、CI、自动化 API、漂移扫描器、灾备脚本和历史版本 CLI。漏掉任何一个都会在切换后形成无法读取的暗节点。
下面只展示结构，密钥不得硬编码进仓库：
terraform {
encryption {
key_provider "pbkdf2" "demo" {
passphrase = var.state_passphrase
}
method "aes_gcm" "demo" {
keys = key_provider.pbkdf2.demo
}
state {
method = method.aes_gcm.demo
}
plan {
method = method.aes_gcm.demo
}
}
}本地 PBKDF2 适合理解结构，不是共享生产环境的密钥托管方案。生产应使用能审计、轮换和恢复的密钥提供者，并把密钥读取身份与基础设施执行身份分开评估。启用过程先在 State 副本和隔离 Backend 演练，保存明文版本的受控备份及恢复期限，再让一个 canary 写入者升级；确认其他读者能读取后才扩大。
加密失败要区分配置解析、密钥访问、元数据不兼容、密文损坏和 Backend 读取五层。看到“无法解密”时不要立刻改加密块或覆盖 State，先复制原始对象及版本号，记录 CLI 版本和密钥标识，再在隔离目录只读恢复。
Backend、锁和版本控制仍是独立责任
State 加密不解决并发写入。共享环境需要支持锁或原子条件写的 Backend，并启用对象版本、最小权限、审计和恢复演练。锁超时后不能凭“流水线已经红了”直接强制解锁；远端 Provider 操作可能仍在继续，原运行也可能只是丢失了日志连接。
force-unlock 前的证据
run_id = <执行编号>
lock_id = <锁身份>
backend_version = <对象版本或 generation>
process_status = <原执行器状态>
remote_operations = <目标 API 中仍在运行的变更>
recovery_owner = <批准解锁并负责对账的人>先停止新的执行入口，确认原进程和远端操作状态，备份当前 State 与 Backend 元数据，再决定等待、解锁、恢复旧版本或接管。解锁只移除互斥条件，不会撤销已经发送到云 API 的创建、修改和删除请求。
从 Terraform 迁移要把兼容假设变成实验
迁移不是把流水线中的 terraform 替换成 tofu。先冻结 Terraform 写入，只复制配置、锁文件和 State 到隔离环境；记录 Terraform CLI、Provider、Backend、模块来源和 State serial/lineage。随后用目标 OpenTofu 版本初始化并生成只读计划，预期无变化。出现差异时按配置解析、Provider 选择、刷新结果、默认值和 State schema 分类处理。
terraform version
terraform providers
terraform state pull > terraform-state-backup.json
tofu version
tofu init -reconfigure
tofu providers
tofu plan -detailed-exitcode
$LASTEXITCODE # 0 无差异；2 有差异；1 错误不要让两套引擎在迁移窗口轮流写同一个 State。验证通过后切换唯一写入者，保留 Terraform 回退期限，但回退前必须证明新 State 仍可被旧工具安全读取；一旦启用 OpenTofu 专有语言块或 State 加密，回退条件会改变。此时正确恢复可能是还原切换前 State 与配置，而不是让旧 CLI 强行读取新格式。
.tofu 文件和 terraform.language 等扩展可用于明确 OpenTofu 配置，但会改变跨引擎兼容面。需要双引擎消费的模块应分别保存受支持的版本约束文件，并在 CI 对两套解析器、Provider 计划和无变化结果做矩阵验证。兼容目标若没有自动测试，就不应承诺。
CI 只允许一条受控写入链
验证阶段可以并行，写入阶段必须按环境串行，并把代码提交、CLI、Provider 锁、变量集合、Backend、计划摘要、审批和执行结果关联到同一个运行记录。开发者本机默认只做 fmt、validate 和沙箱计划，共享环境的 apply 由短期工作负载身份完成。
change:
commit: <git-sha>
engine: opentofu
cli_version: <exact-version>
lockfile_sha256: <sha256>
backend: <environment-state-id>
plan_sha256: <sha256>
approval: <approval-id>
runner_identity: <oidc-subject>
state_version_after: <object-version>变量来源必须可解释。非敏感变量可由版本化文件提供，敏感值从受控 Secret 系统在运行时注入；保存计划前就要接受它可能包含秘密。目标云身份只给当前环境和必要资源动作，Backend 身份只给对应 State 前缀。把管理员云凭据和 State 管理凭据放在同一个长期 Token 中，会让任一泄漏同时获得资源与历史状态。
变量合并要能指出最后一个写入来源
OpenTofu 可以从变量默认值、自动变量文件、显式 -var-file、环境变量和命令行参数取得输入。便利的来源越多，越容易出现“计划和执行拿到不同值”。共享流水线应明确只允许哪些层，保存变量文件摘要，并在执行保存计划时复用同一输入；不要在审批后重新读取可能已经变化的 Secret 或远端配置。
允许的共享环境变量来源
1. 模块默认值：只放非敏感、跨环境稳定的默认
2. 环境变量文件：版本化非敏感值，记录文件摘要
3. Secret 注入：运行时短期读取，不写入命令行与日志
4. break-glass 覆盖：双人批准、显式到期、运行后对账TF_VAR_* 会被子进程继承，也可能进入诊断输出和崩溃采集；-var secret=value 还会进入 Shell 历史和进程参数。CI 使用受保护的标准输入、临时权限文件或凭据 helper 注入，作业结束后验证临时目录和日志没有残留。变量声明的 sensitive 只影响展示传播，不能替代运行环境的秘密治理。
反向实验是在 Plan 阶段和 Apply 阶段分别注入不同的合成值。若流水线执行保存计划，结果应保持 Plan 阶段值；若它重新计划，则必须被制品摘要或审批绑定门禁拒绝。这样才能证明输入冻结不是一份流程文档，而是执行路径本身的约束。
Module 来源和版本约束决定配置供应链
Module 会在初始化阶段进入工作目录，其代码可以改变资源数量、Provider 要求、数据源读取和销毁行为。Registry 版本、Git commit、制品摘要和本地相对路径的稳定性不同。共享模块应使用不可变版本或完整 commit SHA，避免分支、可移动 tag 和未经审查的网络归档直接进入生产计划。
module "network" {
source = "app.terraform.io/example/network/cloud"
version = "4.2.1"
environment = var.environment
}版本约束限定候选集合，锁文件并不会像 Provider 那样固定远端 Module。升级 Module 时先读取变更说明和迁移指引，在隔离 Backend 比较资源地址、Provider 约束与计划；看到资源替换时，先判断是合理架构变化、地址重构遗漏还是 Provider schema 差异。不要为了获得空计划而直接批量 state mv，地址迁移必须能对应公开的重构关系。
内部 Module Registry 要保存发布主体、源提交、构建摘要、依赖 Provider 和撤销状态。发现错误版本后，仅删除 Registry 条目不足以回收已经下载到 runner 缓存的副本；还要阻断版本、清理缓存、定位消费仓库并重新生成计划。
Import、moved 与忘记对象处理不同的身份变化
远端对象已经存在但 State 不认识时使用 Import；配置地址重命名但物理对象不变时使用 moved；团队决定保留对象却停止由当前 State 管理时，才使用移除映射的能力。这三者都修改管理关系，但不会自动证明目标对象配置正确。
moved {
from = module.legacy.local_file.demo
to = module.runtime.local_file.demo
}Import 后立即生成计划，任何意外修改或删除都说明配置尚未完整描述现状。moved 应与代码重构同一提交进入评审，并在所有仍可能消费旧地址的分支退出后再清理。忘记对象前记录远端 ID、新 Owner 和后续治理入口；否则资源会继续计费和暴露权限，却从漂移扫描中消失。
批量导入或地址迁移要先导出 State、启用 Backend 版本并串行执行。操作完成后比较资源地址集合、远端 ID 集合和下一次计划。只有三者收敛，才算完成身份接管；CLI 返回成功只说明 State 命令写入了某个版本。
销毁是资源生命周期的正常出口
临时环境若不能安全销毁，会积累成本、网络入口和长期凭据；生产环境若能被一次普通计划销毁，又缺少足够保护。OpenTofu 的生命周期约束、策略门禁、云平台删除保护、备份和 IAM 拒绝属于不同层，必须组合使用。
销毁计划先按资源地址、类型、环境和数据等级分类。数据库、对象存储、密钥、域名、固定 IP 等资源需要独立恢复或转交决定；依赖图中的“最后删除”不等于业务上可以删除。计划审批显示删除数量，还要显示受保护对象、快照状态、保留对象和目标账号。
tofu plan -destroy -out .destroy-plan
tofu show -json .destroy-plan > .destroy-plan.json
# 策略与人工审查通过后才允许：
tofu apply .destroy-plan退出后查询目标平台，确认资源、子对象、快照、DNS、身份、日志出口和计费项都按决定处理；再撤销 Backend、Registry 与执行凭据。销毁失败时不要直接删 State 让流水线变绿。先保留映射，修复拒绝条件或把明确保留的对象移交给新控制面。
故障先定位在初始化、刷新、计划、执行还是写回
初始化失败通常落在 Registry、模块、Provider 下载、代理、CA 或锁文件；刷新失败落在目标 API、身份、区域和 Provider schema；计划异常落在配置、State 映射和读取结果；执行失败可能已经产生部分远端对象；写回失败则会出现远端变化成功但 State 未记录的危险分叉。
最坏的动作是在写回失败后直接重跑。先保存日志、计划、State 版本和远端对象 ID，运行只读刷新或针对性查询判断哪些动作已经发生。需要接管的对象使用 import 或配置地址迁移，不能通过手工编辑 State 猜测修复。涉及删除时，先用目标平台保护锁、备份和恢复演练建立外层防线。
故障恢复完成后要有反证：旧写入身份已拒绝、旧 State 版本只读保留、临时镜像和计划制品已按期限删除、目标资源与 State 列表一致、下一次计划不包含未解释变化。没有这些证据，绿色计划可能只是把遗漏对象排除在管理范围之外。
升级和退出都要保留资源身份
CLI、Provider、模块和 Backend 分开升级。每次只改变一个主要变量，先在无云夹具和非关键 Stack 上比较计划；Provider schema 变化需要特别观察替换动作和 State 迁移。State 加密密钥轮换要验证新旧读者、备份和回退，不与 CLI 大版本、Backend 迁移同窗进行。
退出 OpenTofu 有三种结果：迁移到另一 IaC 引擎、把对象交给别的控制面、保留远端对象但停止管理。无论哪一种，都要导出最终配置、锁文件、State、Provider 清单、Backend 版本和资源 ID；撤销 CI 身份、Registry 凭据和密钥访问；对目标平台执行独立清单核对。删除本地 .terraform 目录不等于退出，tofu state rm 也只会忘记映射，不会删除远端对象。
团队只有在唯一写入者明确、加密材料可恢复、迁移路径经过无变化计划验证、旧身份被拒绝、资源与 State 能双向对账时，才真正拥有 OpenTofu，而不是暂时能够运行 tofu apply。
日常维护还要观察初始化失败率、计划等待时间、锁冲突、State 对象大小、Provider 下载命中率、漂移数量和销毁拒绝次数。指标必须关联环境、模块和运行身份，但不能把变量值、计划正文或 State 内容送入普通日志。升级或 Backend 迁移后，用同一组指标比较错误分布，能更早发现某个 runner、镜像区域或只读消费者仍停在旧链路。OpenTofu 的停止条件很明确：剩余差异都能解释，执行入口只有一个，State 可恢复，旧身份已撤销，下一位维护者无需借助个人电脑即可重放计划和完成退出。