跳到主要内容

Google Cloud 配置指南

目录​

  1. Google Cloud 概述
  2. 项目创建与配置
  3. Google OAuth 2.0 配置
  4. Cloud Run 配置
  5. Cloud Build 配置
  6. Artifact Registry 配置
  7. 服务账号配置
  8. API 启用

Google Cloud 概述​

什么是 Google Cloud？​

Google Cloud Platform（GCP）是 Google 提供的云计算服务平台，提供计算、存储、网络、大数据、机器学习等各种云服务。在本项目中，我们使用 Google Cloud 的以下服务：

  • Cloud Run：运行容器化的应用（无服务器容器运行环境）
  • Cloud Build：自动构建和部署应用（CI/CD 服务）
  • Artifact Registry：存储 Docker 镜像（容器镜像仓库）
  • IAM（身份和访问管理）：管理用户和服务账号的权限

为什么选择 Google Cloud？​

  1. Google 生态集成：与 Google Workspace（Sheets、Slides）无缝集成
  2. 企业内网支持：支持 Google 内部网络部署（Corp Run）
  3. 成本可控：按使用量计费，适合内部项目
  4. 技术栈统一：与项目使用的其他 Google 服务（Gemini、OAuth）保持一致

项目创建与配置​

创建 Google Cloud 项目​

  1. 访问 Google Cloud Console

  2. 创建新项目

    • 点击项目选择器，选择"新建项目"
    • 输入项目名称（如 insighthub-production）
    • 选择组织（如果适用）
    • 点击"创建"

  3. 记录项目 ID

    • 项目创建后，记录项目 ID（格式：grcn-sca-bigquery）
    • 项目 ID 将用于后续配置

启用计费​

注意：即使使用企业内网，某些服务（如 Cloud Run、Cloud Build）仍可能需要启用计费。

  1. 关联结算账号

    • 在项目设置中，关联组织的结算账号
    • 或创建新的结算账号

  2. 设置预算警报（可选）

    • 在"预算和提醒"中设置预算上限
    • 配置警报，避免意外费用

Google OAuth 2.0 配置​

什么是 OAuth 2.0？​

OAuth 2.0 是一种授权协议，允许用户授权第三方应用访问他们的 Google 账号信息，而无需提供密码。在本项目中，OAuth 2.0 用于：

  1. 用户登录：验证用户身份
  2. 访问 Google Sheets：读取用户有权限访问的 Google Sheet 数据

创建 OAuth 2.0 凭据​

1. 启用 Google+ API​

  1. 打开 API 库
    • 在 Google Cloud Console 中，导航到"API 和服务" > "库"
    • 搜索"Google+ API"（或"Google Identity Services API"）
    • 点击"启用"

注意：Google+ API 已弃用，但某些 OAuth 流程仍需要。如果找不到，可以跳过此步骤。

2. 配置 OAuth 同意屏幕​

  1. 打开 OAuth 同意屏幕

    • 导航到"API 和服务" > "OAuth 同意屏幕"
    • 选择用户类型（内部或外部）
    • 点击"创建"

  2. 填写应用信息

    • 应用名称：CSA 3A (InsightHub)
    • 用户支持电子邮件：您的邮箱
    • 应用徽标：（可选）上传应用图标
    • 应用主页链接：Cloud Run 服务的 URL
    • 应用隐私政策链接：（可选）
    • 应用服务条款链接：（可选）

  3. 配置作用域（Scopes）

    • 点击"添加或移除作用域"
    • 添加以下作用域：
      • https://www.googleapis.com/auth/userinfo.email（用户邮箱）
      • https://www.googleapis.com/auth/userinfo.profile（用户基本信息）
      • https://www.googleapis.com/auth/spreadsheets.readonly（只读访问 Google Sheets）

  4. 添加测试用户（如果选择"外部"用户类型）

    • 在"测试用户"部分，添加允许访问的用户邮箱
    • 生产环境发布后，所有用户都可以访问

  5. 保存并继续

    • 完成所有步骤后，点击"保存并继续"
    • 确认配置信息

3. 创建 OAuth 2.0 客户端 ID​

  1. 打开凭据页面

    • 导航到"API 和服务" > "凭据"
    • 点击"创建凭据" > "OAuth 客户端 ID"

  2. 选择应用类型

    • 选择"Web 应用"

  3. 配置客户端

    • 名称：InsightHub Web Client
    • 已授权的 JavaScript 来源：
      • 开发环境：http://localhost:5173（Vite 默认端口）
      • 生产环境：https://your-cloud-run-url.run.app
    • 已授权的重定向 URI：
      • 开发环境：http://localhost:5173/auth/callback
      • 生产环境：https://your-cloud-run-url.run.app/auth/callback

  4. 创建并记录凭据

    • 点击"创建"
    • 重要：记录以下信息：
      • 客户端 ID：格式如 123456789-abcdefghijklmnop.apps.googleusercontent.com
      • 客户端密钥：格式如 GOCSPX-abcdefghijklmnopqrstuvwxyz
    • 客户端密钥只显示一次，请妥善保存

配置环境变量​

将 OAuth 凭据配置到环境变量中：

开发环境（.env 文件）：

VITE_GOOGLE_OAUTH_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz

生产环境（Cloud Build 触发器）：

  • 添加替换变量 _VITE_GOOGLE_OAUTH_CLIENT_ID
  • 添加替换变量 _GOOGLE_CLIENT_SECRET

Cloud Run 配置​

创建 Cloud Run 服务​

1. 首次部署​

Cloud Run 服务会在首次部署时自动创建，无需手动创建。

2. 服务配置​

在 cloudbuild.yaml 中配置服务参数：

- '--region'
- '${_DEPLOY_REGION}'  # 如 asia-northeast1
- '--platform'
- 'managed'
- '--allow-unauthenticated'  # 允许未认证访问

配置说明：

  • region：选择离用户最近的区域（如 asia-northeast1 用于亚太地区）
  • platform：managed 表示完全托管，无需管理基础设施
  • allow-unauthenticated：允许公开访问（如果需要内部访问，可以移除此选项）

3. 资源配置（可选）​

可以在 Cloud Build 中添加资源配置：

- '--memory'
- '512Mi'
- '--cpu'
- '1'
- '--timeout'
- '300'
- '--max-instances'
- '10'
- '--min-instances'
- '0'

配置说明：

  • memory：每个容器实例的内存（默认 512 MiB）
  • cpu：每个容器实例的 CPU 数量（默认 1）
  • timeout：请求超时时间（秒，默认 300）
  • max-instances：最大实例数（默认 100）
  • min-instances：最小实例数（默认 0，空闲时无实例运行）

Cloud Build 配置​

创建 Cloud Build 触发器​

1. 连接到源代码仓库​

  1. 打开 Cloud Build 触发器

    • 在 Google Cloud Console 中，导航到"Cloud Build" > "触发器"
    • 点击"创建触发器"

  2. 选择源代码

    • 选择源代码仓库（GitHub、GitLab 或 Cloud Source Repositories）
    • 授权 Cloud Build 访问仓库
    • 选择仓库和分支

2. 配置触发器​

  1. 触发器设置

    • 名称：insighthub-deploy
    • 事件：推送到分支时（Push to a branch）
    • 分支：^main$（或您的主分支名称）
    • 配置类型：Cloud Build 配置文件（yaml 或 json）
    • 位置：cloudbuild.yaml

  2. 替换变量（Substitutions）

    • 添加以下替换变量：
变量名说明示例值
_AR_HOSTNAMEArtifact Registry 主机名asia-northeast1-docker.pkg.dev
_AR_PROJECT_IDGoogle Cloud 项目 IDgrcn-sca-bigquery
_AR_REPOSITORYArtifact Registry 仓库名cloudrun-source-deploy
_SERVICE_NAMECloud Run 服务名helen-new-insighthub
_DEPLOY_REGION部署区域asia-northeast1
_VITE_GEMINI_API_KEYGemini API KeyAIzaSy...
_VITE_GOOGLE_OAUTH_CLIENT_IDOAuth Client ID123456789-...
_VITE_GOOGLE_SLIDES_TEMPLATE_IDGoogle Slides 模板 ID1a2b3c4d...
_VITE_HELP_DOCUMENT_URL帮助文档 URLhttps://...
_AUDIT_LOG_SPREADSHEET_ID审计日志 Google Sheet ID1a2b3c4d...
_APPS_SCRIPT_SLIDES_ID图片插入 Apps Script ID5e6f7g8h...
_GOOGLE_CLIENT_SECRETOAuth Client SecretGOCSPX-...

安全建议：

  • 敏感信息（如 API Key、Client Secret）建议使用 Google Secret Manager 存储
  • 在触发器中从 Secret Manager 读取，而不是直接配置
  1. 服务账号
    • 选择 Cloud Build 使用的服务账号
    • 确保服务账号具有以下权限：
      • Cloud Build Service Account
      • Artifact Registry Writer
      • Cloud Run Admin

3. 保存触发器​

  • 点击"创建"保存触发器
  • 触发器会在代码推送到指定分支时自动执行

Artifact Registry 配置​

什么是 Artifact Registry？​

Artifact Registry 是 Google Cloud 的容器镜像仓库服务，用于存储和管理 Docker 镜像。Cloud Build 构建的镜像会推送到 Artifact Registry，然后 Cloud Run 从 Artifact Registry 拉取镜像运行。

创建 Artifact Registry 仓库​

1. 打开 Artifact Registry​

  • 在 Google Cloud Console 中，导航到"Artifact Registry"
  • 点击"创建仓库"

2. 配置仓库​

  • 名称：cloudrun-source-deploy（或您选择的名称）
  • 格式：Docker
  • 模式：标准（Standard）
  • 位置：选择与 Cloud Run 相同的区域（如 asia-northeast1）

3. 权限配置​

  • 访问控制：使用 IAM 权限控制访问
  • 确保 Cloud Build 服务账号具有"Artifact Registry Writer"角色
  • 确保 Cloud Run 服务账号具有"Artifact Registry Reader"角色

服务账号配置​

什么是服务账号？​

服务账号是 Google Cloud 中的一种特殊账号，用于代表应用程序访问 Google Cloud 服务，而不是代表用户。在本项目中，服务账号用于：

  1. Cloud Build：执行构建和部署操作
  2. Apps Script 调用：通过 Execution API 调用 Apps Script
  3. Google Workspace 访问：访问 Google Sheets 和 Google Slides

创建服务账号​

1. 打开 IAM 和管理​

  • 在 Google Cloud Console 中，导航到"IAM 和管理" > "服务账号"
  • 点击"创建服务账号"

2. 配置服务账号​

  • 服务账号名称：insighthub-service-account
  • 服务账号 ID：自动生成（可以修改）
  • 说明：InsightHub 应用服务账号

3. 授予角色​

添加以下角色：

角色说明
Cloud Run Invoker允许调用 Cloud Run 服务
Artifact Registry Reader允许读取 Artifact Registry 中的镜像
Service Account User允许使用服务账号

4. 创建密钥​

  1. 打开服务账号详情

    • 点击创建的服务账号
    • 切换到"密钥"标签页

  2. 添加密钥

    • 点击"添加密钥" > "创建新密钥"
    • 选择"JSON"格式
    • 点击"创建"
    • 重要：JSON 密钥文件会下载到本地，请妥善保存

  3. 配置环境变量

    • 开发环境：将 JSON 文件保存到项目目录，配置 GOOGLE_SERVICE_ACCOUNT_KEY_PATH
    • 生产环境：将 JSON 内容配置到 GOOGLE_SERVICE_ACCOUNT_JSON 环境变量

服务账号权限配置​

Apps Script 调用权限​

服务账号需要能够调用 Apps Script Execution API：

  1. 启用 Apps Script API

    • 在 Google Cloud Console 中，导航到"API 和服务" > "库"
    • 搜索"Apps Script API"
    • 点击"启用"

  2. 授予执行权限

    • 在 Apps Script 项目中，将服务账号邮箱添加为"查看者"或"编辑者"
    • 服务账号邮箱格式：service-account-name@project-id.iam.gserviceaccount.com

Google Workspace 访问权限​

如果服务账号需要访问 Google Sheets 或 Google Slides：

  1. 共享资源

    • 在 Google Sheets/Slides 中，将服务账号邮箱添加为"编辑者"
    • 服务账号邮箱格式：service-account-name@project-id.iam.gserviceaccount.com

  2. 域范围授权（可选）

    • 如果需要访问组织内的所有资源，可以配置域范围授权（Domain-wide Delegation）
    • 这需要 Google Workspace 管理员权限

API 启用​

需要启用的 API​

以下 API 需要在 Google Cloud 项目中启用：

API 名称用途是否必需
Cloud Run API运行容器化应用✅ 必需
Cloud Build API构建和部署应用✅ 必需
Artifact Registry API存储 Docker 镜像✅ 必需
Apps Script API调用 Apps Script⚠️ 可选
Google Sheets API访问 Google Sheets⚠️ 可选（如果使用 Google Sheet 功能）
Google Slides API访问 Google Slides⚠️ 可选（如果使用 Google Slides 功能）
Google Identity Services APIOAuth 2.0 认证✅ 必需

启用 API​

  1. 打开 API 库

    • 在 Google Cloud Console 中，导航到"API 和服务" > "库"

  2. 搜索并启用

    • 搜索 API 名称
    • 点击 API 卡片
    • 点击"启用"按钮

  3. 验证启用状态

    • 在"API 和服务" > "已启用的 API"中查看
    • 确保所有必需的 API 都已启用

配置检查清单​

项目配置​

  • Google Cloud 项目已创建
  • 项目 ID 已记录
  • 计费已启用（如需要）

OAuth 2.0 配置​

  • OAuth 同意屏幕已配置
  • OAuth 客户端 ID 已创建
  • 客户端 ID 和密钥已记录
  • 重定向 URI 已配置（开发和生产环境）
  • 环境变量已配置

Cloud Run 配置​

  • 服务区域已选择
  • 资源配置已设置（如需要）
  • 环境变量已配置

Cloud Build 配置​

  • 触发器已创建
  • 源代码仓库已连接
  • 替换变量已配置
  • 服务账号权限已授予

Artifact Registry 配置​

  • 仓库已创建
  • 仓库区域已选择
  • 权限已配置

服务账号配置​

  • 服务账号已创建
  • 密钥已下载
  • 角色已授予
  • Apps Script 权限已配置
  • Google Workspace 资源已共享

API 启用​

  • Cloud Run API 已启用
  • Cloud Build API 已启用
  • Artifact Registry API 已启用
  • Apps Script API 已启用（如需要）
  • Google Identity Services API 已启用

常见问题​

Q1：OAuth 重定向 URI 不匹配错误？​

错误信息：redirect_uri_mismatch

原因：重定向 URI 与 OAuth 客户端配置不匹配

解决方案：

  1. 检查 OAuth 客户端配置中的"已授权的重定向 URI"
  2. 确保包含实际使用的重定向 URI（包括协议、域名、路径）
  3. 开发环境和生产环境需要分别配置

Q2：服务账号无法调用 Apps Script？​

错误信息：PERMISSION_DENIED 或 Script function not found

原因：

  1. Apps Script API 未启用
  2. 服务账号没有 Apps Script 项目的访问权限
  3. Script ID 配置错误

解决方案：

  1. 启用 Apps Script API
  2. 在 Apps Script 项目中，将服务账号邮箱添加为"查看者"
  3. 验证 Script ID 是否正确（从 Apps Script 编辑器 URL 获取）

Q3：Cloud Build 构建失败，提示权限不足？​

错误信息：PERMISSION_DENIED

原因：Cloud Build 服务账号缺少必要的权限

解决方案：

  1. 检查 Cloud Build 使用的服务账号
  2. 确保服务账号具有以下角色：
    • Cloud Build Service Account
    • Artifact Registry Writer
    • Cloud Run Admin
    • Service Account User

Q4：如何查看服务账号的邮箱地址？​

方式 1：通过 Cloud Console

  1. 打开"IAM 和管理" > "服务账号"
  2. 点击服务账号名称
  3. 在详情页面查看"电子邮件"字段

方式 2：通过格式推断 服务账号邮箱格式：service-account-name@project-id.iam.gserviceaccount.com

总结​

本章节详细介绍了 Google Cloud 的配置步骤，包括：

  1. 项目创建：如何创建和配置 Google Cloud 项目
  2. OAuth 2.0 配置：如何配置用户登录和 Google Workspace 访问
  3. Cloud Run 配置：如何配置无服务器容器运行环境
  4. Cloud Build 配置：如何配置自动化构建和部署
  5. Artifact Registry 配置：如何配置容器镜像仓库
  6. 服务账号配置：如何创建和配置服务账号
  7. API 启用：需要启用的 Google Cloud API

正确配置 Google Cloud 是系统部署和运行的基础，请按照检查清单逐一完成配置。

相关文档：