---
url: /docs/specs/infra-terraform.md
---
# 基础设施规格

## 责任边界

Terraform 管理两个 Hyperdrive 及可选上传存储桶，Wrangler 管理应用代码、域名、路由、绑定、变量和秘密。两者不同时管理同一字段，交接值仅为非秘密资源标识。

结构为 `infra/modules/cloudflare/` 和 `infra/envs/staging/`、`infra/envs/production/`。每个根对应独立状态和固定环境；开发不创建远程资源，也没有共享的逐请求预览环境。

## 版本与命名

根配置约束 Terraform `>= 1.12, < 2.0`、Cloudflare 提供者 `~> 5.0`，锁文件随代码提交。资源名称使用项目标识和环境，项目标识与 Worker 前缀相符。

升级版本同时检查根目录、CI 和远程工作区设置，不仅修改单个工具安装命令。

## 数据库与缓存

每个环境创建有缓存和无缓存两条 Hyperdrive。缓存最大时间和重新验证窗口由模块明确配置；连接软上限默认每条 20，源数据库要预算两条连接之和及余量。

连接串解析拒绝不支持的格式、百分号编码凭据及 `-pooler` 主机。密钥包含特殊字符时先按当前解析限制准备连接方式，不能让未解码文本成为真实密码。

权限、认证、账单和积分使用无查询缓存的连接。上传存储桶的可选配置不代表主站已经有上传接口或清理流程。

## 状态与远程设置

HCP Terraform 保存状态、锁及历史，状态含源数据库凭据。根固定主机、组织和工作区；复制新站时替换占位名称。

工作区选择命令行驱动、远程执行、对应 `envs/<环境>` 工作目录、符合约束的版本和完整变量。Cloudflare 令牌作为工作区环境变量，数据库地址作为敏感输入。调用者 `TF_VAR_*` 可能覆盖输入，运行前检查并审阅计划。

## CI 与权限

普通 CI 仅无后端验证，使用只读锁文件，不持有远程资源凭据。手动基础设施工作流先保存计划，后应用同一计划；规划与应用环境分开，应用令牌按工作区隔离。

规划执行远程配置，不是针对不可信分支的安全沙箱。主分支规则与实际环境审批需要维护者配置。具体操作见 [自动检查与发布](../deployment/ci-cd.md) 与 `infra/README.md`。