---
url: /docs/adr/003-hcp-terraform-state.md
---
# 决策 003：远程基础设施状态

**状态：** 已采纳。**日期：** 2026-08-09。

## 问题

Hyperdrive 保存源数据库凭据，因此 Terraform 状态含敏感信息，需要受控访问、锁定和可恢复历史。把状态直接存本地或放没有恢复方案的对象桶，会增加丢失和泄露风险。

## 决策

每个环境根目录使用 HCP Terraform，固定 `cloud` 的主机、组织及工作区名称。复制模板后显式替换占位配置；预发布与生产各有独立状态，不能靠临时环境变量任意改指向。

默认远程执行，Cloudflare 凭据和数据库输入留在对应工作区。GitHub 基础设施任务使用专用 `TF_API_TOKEN`，应用发布秘密与此分开。

## 需要手动核对的工作区设置

* 使用命令行驱动工作流。
* 使用远程执行模式。
* 工作目录设为 `envs/staging` 或 `envs/production`，确保上传包含共享模块。
* Terraform 版本符合根目录约束。
* 工作区环境变量与敏感输入完整且对应正确环境。

这些设置不全由源码声明，不能只复制文件就认定远程配置完成。

## 风险与替代方案

`sensitive` 只隐藏输出，不使状态文件不含凭据。远程状态访问者仍需要最小权限。调用者的 `TF_VAR_*` 可覆盖部分输入，所以规划前检查临时环境值，并审阅真实计划。

本地执行、远程保存状态可以使用，但凭据回到执行机器且工作区变量不按远程模式供应。对象存储后端需要额外解决初始化、锁定、版本和恢复；模板不同时维护多种后端。

参见 [基础设施规格](../specs/infra-terraform.md) 和 [自动检查与发布](../deployment/ci-cd.md)。