Relay Starter Kit 项目云基础设施部署指南

项目概述

Relay Starter Kit 是一个基于 GraphQL 和 React 的现代化 Web 应用开发框架。本文将详细介绍如何为其配置和部署 Google Cloud Platform (GCP) 和 CDN 服务的基础设施资源，使用 Terraform 实现基础设施即代码(IaC)的管理方式。

环境准备

基础工具安装

在开始部署前，需要确保本地开发环境已安装以下工具：

1. Node.js 环境：建议使用 v18 或更高版本，并配合 Yarn 包管理器
2. Google Cloud SDK：用于与 GCP 服务交互
3. Terraform CLI：基础设施编排工具

macOS 下安装 Terraform

对于 macOS 用户，推荐使用 Homebrew 安装 Terraform：

brew tap hashicorp/tap
brew install hashicorp/tap/terraform
brew update
brew upgrade hashicorp/tap/terraform
terraform -version

GCP 项目配置

需要为测试和生产环境分别创建 GCP 项目：

1. 登录 GCP 控制台
2. 创建两个项目，例如：
   • 生产环境：example-prod
   • 测试环境：example-test

Terraform Cloud 工作区配置

1. 创建两个工作区：
   • app-test：测试环境
   • app-prod：生产环境
2. 在每个工作区中设置 GOOGLE_CREDENTIALS 环境变量，值为具有足够权限的 GCP 服务账户 JSON 密钥

Terraform CLI 认证

1. 在 Terraform Cloud 中创建 API Token
2. 在项目根目录创建 .terraformrc 文件：

credentials "app.terraform.io" {
  token = "你的API令牌"
}

部署流程

初始化工作区

yarn tf init -upgrade

此命令会初始化 Terraform 工作区并下载必要的 provider 插件。

规划变更

yarn tf plan

执行此命令会生成执行计划，显示将要创建、修改或删除的资源，但不会实际执行变更。

应用变更

yarn tf apply

此命令会实际执行 plan 阶段提出的变更，部署基础设施资源。

环境切换

默认使用测试环境工作区，要切换到生产环境：

TF_WORKSPACE=prod yarn tf plan
TF_WORKSPACE=prod yarn tf apply

最佳实践建议

1. 权限管理：为 Terraform 使用的服务账户遵循最小权限原则
2. 状态文件：建议使用远程后端存储 Terraform 状态
3. 变更审查：在生产环境应用变更前，务必仔细审查 plan 输出
4. 版本控制：将 Terraform 配置文件和模块纳入版本控制系统
5. 模块化设计：将基础设施分解为可重用的模块

常见问题排查

1. 认证失败：检查 GOOGLE_CREDENTIALS 环境变量是否正确设置
2. 权限不足：确保服务账户具有足够权限
3. 资源冲突：某些 GCP 资源名称需要全局唯一
4. API 未启用：确保所需 GCP API 已在项目中启用

通过本文介绍的流程，开发者可以快速为 Relay Starter Kit 项目搭建完整的云基础设施环境，实现开发、测试和生产环境的隔离部署。