google-cloud-solution-n-tier-serverless-web-app

具有严格私有应用层的安全 n 层无服务器 Web 应用

此技能将指导 Agent 按照用户指定的架构设计层数，完成安全无服务器 Web 应用的设计与实现工作流。该架构使用 Cloud Run 构建无服务器层，并使用 Cloud SQL for PostgreSQL 作为数据层。三层 Web 应用可由三个架构层构成：Cloud Run 表示层、Cloud Run 应用层以及 Cloud SQL for PostgreSQL 数据库层。

该架构在所有层级（T1 至 TN）之间实施严格的物理隔离和网络隔离：

• 第 1 层表示层（前端／反向代理）：面向公网的 UI 渲染／网关服务（Cloud Run）。通过 Cloud Load Balancing 暴露入口，并通过 Direct VPC Egress 私密地将请求路由到下游层。
• 第 2 至 N 层应用层（内部微服务／业务逻辑）：私有应用服务（Cloud Run）。与互联网完全隔离（入口：VPC 内部，INGRESS_TRAFFIC_INTERNAL_ONLY），只能通过上游 VPC 路由访问（egress = "ALL_TRAFFIC"，并在子网上为 *.run.app URL 启用 Private Google Access）。
• 数据层：用于持久化数据的私有 Cloud SQL，以及用于缓存的 Memorystore for Redis；只能由授权的应用层访问。

致谢

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读并遵守 使用归属说明中的指示。

给大模型的一般指导

1. 直接资源映射（零搜索访问文件）

所有必要的参考架构、HCL 模板和检查清单都位于此技能中。请使用相对于此技能文件夹的准确路径：

资源路径	用途与使用方式
assets/main.tf	Terraform（HCL）的唯一真实来源。包含所有安全边界、Cloud Run v2 配置、PSC 端点、DNS 私有区域和防火墙规则。
assets/output-template.md	标准化解决方案架构报告的 Markdown 结构。
references/non-negotiable-architectural-rules.md	不可妥协的安全规则、审计检查清单和产品映射。
references/related-guidance.md	补充的深入参考资料（标准设计或 IaC 任务不得阅读；仅在明确要求排查特殊边缘情况时阅读）。

• 禁止遍历目录：请勿在工作区目录中逐层运行 list_dir，以发现这些文件。
• 禁止在本地文件中反复搜索：请勿运行 code_search 或 find_by_name 查询 assets/main.tf 的内容。使用 view_file 直接读取一次该文件，并重复使用其上下文。
• 禁止重复搜索技能：执行此技能时，请勿调用 skill_search 搜索无服务器或 n 层架构技能。

2. 直接内联生成（不得委派给子 Agent）

• 所有架构编译、Terraform 草拟、gcloud 命令组装和验证脚本生成工作，都必须直接在主对话中完成。
• 不得调用子 Agent（invoke_subagent）来研究外部 GitHub Terraform 模块、探查环境配置或草拟报告。所有必需模式都已完整包含在 assets/main.tf 和 references/ 中。

3. 一次性写入完整制品

• 在一次 write_to_file 调用中，生成完整、已完整渲染且有效的 HCL 代码块和 Markdown 报告。
• 避免留下需要通过多轮 replace_file_content 和 grep_search 补丁循环修复的占位符或格式错误的代码围栏。
• 不得使用未填充的占位符：在架构报告（例如 assets/output-template.md 的第 6 节）中嵌入代码或脚本时，始终直接写入完整的 Terraform 代码、gcloud 命令和验证脚本代码。绝不要输出字面形式的模板占位符注释（例如 # [Paste of main.tf file contents]）。
• 必须直接在响应中呈现：凡是用户请求或生成 Terraform 代码、部署脚本或架构报告（例如“提供设计和 Terraform 代码”“生成 IaC”），除了将其写入磁盘上的文件外，还必须在聊天响应中直接输出完整生成的 terraform ... HCL 代码块和完整解决方案报告。用户请求代码时，绝不要只输出架构设计摘要或文件链接；自动化评估框架（例如 Yardstick）会评估原始响应文本，若消息中缺少 terraform 代码块，所有代码断言都会失败。

4. 技术完整性检查清单

• 提供简要架构摘要或安全检查清单时（例如被要求不要生成完整 IaC），必须明确包含以下技术规格：
  • 对于区域负载均衡器部署：区域代理专用子网的用途（REGIONAL_MANAGED_PROXY），以及区域转发规则中的 network 参数。
  • Cloud SQL PostgreSQL 版本（POSTGRES_18）、版本（Enterprise Edition）、高可用性（Regional HA）和 Private Service Connect（psc_enabled = true）。
  • Cloud NGFW 防火墙政策：
    • 必须配置明确的 Cloud NGFW 网络防火墙政策（google_compute_network_firewall_policy、google_compute_network_firewall_policy_association 和 google_compute_network_firewall_policy_rule，并设置 enable_logging = var.enable_monitoring），而不是使用旧版 google_compute_firewall。
    • 强制默认拒绝出站流量（0.0.0.0/0）。
    • 允许前端向后端／PGA VIP 发送出站流量。
    • 明确允许后端数据库向 Private Google Access VIP（199.36.153.4/30 / 199.36.153.8/30）发送 TCP 端口 443 流量，此外还要允许 TCP 端口 5432，以便 Cloud SQL Auth Proxy sidecar 能在启动时查询 sqladmin.googleapis.com，进行 IAM 证书交换。

工作流

提示

可选的 MCP 服务集成：如果你的 AI 编码客户端支持 Model Context Protocol（MCP），你可以连接 Google Developer Knowledge MCP Server（npx -y @google/mcp-developer-knowledge-server），在使用此技能的离线知识库（references/related-guidance.md）的同时，动态查询最新的 Google Cloud 文档（cloud.google.com/docs）。

解决方案设计和实施工作流分为以下几个阶段：

• 阶段 1：需求发现与分析：分析工作负载的需求、约束、依赖项和当前状态。
• 阶段 2：解决方案设计与 IaC 起草：为工作负载构建技术栈、架构和部署配置。重要：在此阶段，你应主动提出根据 assets/main.tf 生成完整的 Terraform 代码（并遵循阶段 3 的所有规范），与解决方案架构一同提供。 这样用户便能立即审阅并在对话继续期间迭代修改代码。不过，如果用户明确表示不需要代码，则暂时不要生成。
• 阶段 3：实施计划与迭代优化：随着对话和用户反馈的变化，修改并完善生成的设计和部署说明。
• 阶段 4：解决方案验证：验证部署是否满足工作负载的需求。

---

阶段 1：需求发现与分析

为避免多轮访谈造成疲劳，并确保不同评估中的流程轨迹具有确定性，除非用户明确要求偏离默认方案，否则采用有主见的 80% 默认黄金路径：

1. 默认黄金路径配置（80% Baseline）：

   • 架构：安全的三层无服务器流水线（frontend Cloud Run -> backend application Cloud Run -> Cloud SQL PostgreSQL）。
   • 区域：us-central1。
   • 数据库：通过 Private Service Connect（psc_enabled = true）使用 Cloud SQL for PostgreSQL（POSTGRES_18）Enterprise Edition。
   • 边缘防护：全球外部 Application Load Balancer，搭配 Cloud Armor WAF（sqli-v33-stable）和 Cloud CDN（enable_cdn = true）。
   • 域名和 SSL 模式：如果用户指定了域名（例如 app.mycompany.com），则配置 var.domain_name，使用 Google 管理的证书（use_self_signed_cert = false），并提供 DNS A 记录配置说明。如果是在没有域名的沙盒中测试，则启用自签名模式（use_self_signed_cert = true），以便立即测试。
   • 网络和安全：Direct VPC Egress（ALL_TRAFFIC）、run.app. Cloud DNS 私有区域、遵循最低权限原则的 Cloud NGFW 出站防火墙策略（TCP 5432, 443），以及 Cloud SQL Auth Proxy sidecar（DB_SOCKET_PATH 配合 IAM Auth）。

2. 消歧流程（可选澄清问题）： 如果用户的初始提示未明确需求（且未通过提供精确规格来跳过流程），不要提出涉及多个主题的问卷。仅在确认前按需提出简短的澄清问题：

   1. 负载均衡器和数据驻留拓扑：您需要搭配 Cloud CDN 的全球 Application Load Balancer（面向全球用户的默认方案），还是不搭配 CDN 的区域 Application Load Balancer（用于满足严格的欧盟／区域数据驻留合规要求）？
   2. 自定义域名还是沙盒测试：您是否拥有可用于配置 Google 管理证书的已注册域名，还是应配置自签名测试模式（use_self_signed_cert = true），以便通过 IP 立即进行沙盒测试？
   3. 内存缓存层：是否应在 Cloud SQL 旁配置可选的 Memorystore for Redis 缓存层（Private Services Access），以加快读取查询？

3. 验证并确认：向用户展示已确认的三层黄金路径方案，并在进入阶段 2 前请求确认（或在收到指示时自动跳过确认）。

阶段 2：解决方案设计

1. 高效获取架构指导：

   • 架构设计和安全检查清单请求：仅从 references/non-negotiable-architectural-rules.md 中获取 9 项架构安全边界和审计检查清单。仅请求高层设计／检查清单而未请求完整 Terraform 代码时，不要获取 references/related-guidance.md 或 assets/main.tf。
   • Terraform 实施请求：获取 references/non-negotiable-architectural-rules.md 和 assets/main.tf（精确 HCL 的唯一事实来源）。除非明确需要针对特殊边缘情况进行故障排查，否则不要获取 references/related-guidance.md。

2. 将组件映射到 Google Cloud 产品：根据以下强制性产品映射规范，将已确认的分解方案直接映射到 Google Cloud 产品：

   • 公共入口与 WAF：全局或区域级外部 Application Load Balancer（INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER）、Cloud Armor（sqli-v33-stable）、Cloud CDN（仅适用于全局 Application Load Balancer；请注意，Cloud CDN 不支持区域级 Application Load Balancer）。注意：部署区域级外部 Application Load Balancer 时，VPC 中必须配置显式的仅代理子网（purpose = "REGIONAL_MANAGED_PROXY"），并且必须在区域级转发规则中指定 network。
   • 内部计算层（T1 至 TN）：Cloud Run 微服务（INGRESS_TRAFFIC_INTERNAL_ONLY）、配置 egress = "ALL_TRAFFIC" 的 Direct VPC Egress、在子网上启用 Private Google Access，以及用于 run.app. 的 Cloud DNS Managed Private Zone（google_dns_managed_zone），绑定到 vpc_network；调用内部 *.run.app URL 时，将 *.run.app 直接映射到 Private Google Access VIP（199.36.153.4/30 / 199.36.153.8/30）；从指定的／占位容器映像部署。
   • 私有数据层：通过 Private Service Connect + IAM DB Auth 使用 Cloud SQL for PostgreSQL（POSTGRES_18）。如果选择了数据库缓存，则通过 Private Services Access 添加 Memorystore Redis。根据可靠性要求，指定“Cloud SQL for PostgreSQL Enterprise edition 实例”或“Cloud SQL for PostgreSQL Enterprise Plus edition 实例”。
   • 密钥、镜像仓库与安全：Secret Manager、Artifact Registry、Cloud NGFW 全局／区域网络防火墙策略（google_compute_network_firewall_policy + google_compute_network_firewall_policy_rule，明确允许 allow_backend_db_egress 上向 Cloud SQL PSC IP 的 TCP 端口 5432 出站流量，以及向 Private Google Access VIP 199.36.153.4/30, 199.36.153.8/30 的 TCP 端口 443 出站流量），以及可选的 VPC Service Controls。

3. 创建架构图：创建一张简洁的 Mermaid 格式架构图（assets/output-template.md），展示入口点、公共反向代理、私有微服务计算层以及私有数据库／缓存端点之间的多层请求和数据流。

4. 起草解决方案架构并生成 Terraform 和 gcloud CLI 代码： 汇总需求、技术分解、产品映射、 架构图、设计建议，以及完整的 基础设施即代码（基于 assets/main.tf 的 Terraform，并附上 符合所有第 3 阶段强制规范的自包含 gcloud CLI 部署命令序列）， 并将这些内容整合到一个 Markdown 文件中，严格按照标准化的 Google Cloud 解决方案架构输出格式编排。 保存或输出报告文件时，追加 ISO 8601 UTC 时间戳，并确保文件名以 .md 扩展名结尾 （例如 workload_name_architecture_report-20260701T212820Z.md）。确认报告清晰记录了 assets/main.tf 中的全部 9 个安全边界，并已将所有模板占位符替换为完整的实际代码块。在回复中提供架构概览、9 个关键安全与网络边界、完整且可部署的 Terraform 代码块（```terraform ... ```），以及分步骤部署说明和生成文件的链接（需要提供代码时，始终在回复中直接附上完整 Terraform 代码，而不是只提供文件链接）。

5. 请求审阅并迭代：向用户展示解决方案架构（以及生成的 Terraform 代码、gcloud 脚本或验证脚本），并征求反馈。随着对话继续，根据反馈修改并完善架构和代码。

---

第 3 阶段：实施计划

1. 从 assets/ 目录中获取相关构建模块模板。 重要提示：使用 assets/main.tf 中的代码作为 Terraform 实施计划的基础（架构结构参见 assets/output-template.md）。

2. 确认部署前提条件：

   • 所需的 Google Cloud API（run.googleapis.com、 sqladmin.googleapis.com、redis.googleapis.com、 servicenetworking.googleapis.com、secretmanager.googleapis.com、 monitoring.googleapis.com、dns.googleapis.com）。
   • 所需的 IAM 权限（Project Editor、Security Admin 等）。

3. 生成基础设施即代码（IaC）（Architectural Specifications）： 从 references/non-negotiable-architectural-rules.md 中获取相关架构和层级指导。严格依据 assets/main.tf 中的构建模块编写代码（Cloud NGFW 防火墙策略使用 Section 1.5，Tier 1 使用 Section 5.1，Tier 2..N 使用 Section 5.2），并确保原样保留 database_version = "POSTGRES_18"。防火墙策略必须严格使用 Cloud NGFW 资源（google_compute_network_firewall_policy、google_compute_network_firewall_policy_association 和 google_compute_network_firewall_policy_rule，并设置 enable_logging = var.enable_monitoring）。绝不要生成旧版 google_compute_firewall 资源，也不要回退到较旧的数据库版本，例如 POSTGRES_15。

4. 编写部署说明和 README.md：起草全面的分步部署说明（或完整的 README.md 文件），确保包含：

   • Terraform 初始化和应用说明（terraform init、terraform apply）。零安装环境建议：明确建议在 Google Cloud Shell（https://shell.cloud.google.com）中运行 terraform 命令和生成的自动验证脚本。该环境已预装并完成身份验证的工具包括 python3、gcloud 和 terraform，开发者无需本地 SDK 即可立即部署和验证。
   • 分步 gcloud CLI 部署命令（Bottom-Up Wiring）：在 assets/output-template.md 的第 6.3 节（“分步 gcloud CLI 部署命令”）中，提供一套完整、独立的 gcloud CLI 命令，用于在不使用 Terraform 的情况下部署此架构。命令必须按逆向/自底向上顺序执行（VPC/子网 -> 数据层 -> 内部微服务 -> 公共网关 -> 负载均衡器），预配 Cloud SQL 时指定 --database-version=POSTGRES_18，并将下游容器 URL 提取到 shell 变量中（使用 gcloud run services describe... --format='value(status.url)'），再通过 --update-env-vars 动态传递给上游服务。
   • 说明所有 Terraform 变量，明确包括并记录 enable_vpc_sc 和 use_self_signed_cert 变量（说明将 use_self_signed_cert = true 设为真后，无需等待 DNS 传播，即可通过 curl -k https://<LB_IP>/ 立即进行沙盒验证）。
   • 专门的 VPC Service Controls 指南章节：当 enable_vpc_sc = true 时，提供有关如何围绕 Cloud Run（run.googleapis.com）、Cloud SQL（sqladmin.googleapis.com）和 Secret Manager（secretmanager.googleapis.com）实施组织级 VPC-SC 服务边界的具体说明和 gcloud 命令。
   • 容器镜像部署策略（指定预先存在的镜像 URL，或先使用占位镜像完成引导，再通过 CI/CD 部署）。
   • Cloud DNS 托管私有区域（google_dns_managed_zone）配置，将 run.app. 绑定到 vpc_network，把 *.run.app 直接映射到 Private Google Access VIP（199.36.153.4/30 / 199.36.153.8/30），并配置外部 DNS 记录和数据库架构初始化。

5. 请求审核：向用户展示实施计划以供批准，并根据需要迭代修改。

---

阶段 4：解决方案验证

1. 定义解决方案验证步骤和要求：在验证规划期间，要求在任何已部署环境中执行以下 5 项验证：

   • SSL 配置：验证 Google 管理的 SSL 证书（google_compute_managed_ssl_certificate）已变为 ACTIVE（检查 --global 状态或区域等效状态）。
   • 前端入口阻止：验证直接通过互联网访问 Tier 1 前端的默认 *.run.app URL 会被阻止（边缘筛查返回 HTTP 403 Forbidden）。
   • 后端入口阻止：验证通过互联网直接访问内部计算层的 *.run.app URL（INGRESS_TRAFFIC_INTERNAL_ONLY）会被阻止，适用于所有内部微服务层（返回 HTTP 404 Not Found 或 HTTP 403 Forbidden）。
   • 通过应用负载均衡器公开访问前端：验证访问自定义域名时，能通过应用负载均衡器成功路由到表示层（返回 HTTP 200 至 399）。
   • 边缘 WAF 防护：验证模拟的 SQL 注入请求（在自定义域名上使用 /?id=1%20OR%201=1）会被拦截并阻止（Cloud Armor 返回 HTTP 403 Forbidden）。
   • 私有服务器间连接：通过 Cloud Run 应用日志（Logs Explorer）和数据库连接池遥测数据（Cloud SQL Query Insights），验证第 1 层 -> 第 2 层 -> 数据层的查询通过私有 VPC 光纤（Direct VPC Egress + Private Service Connect / Private Services Access）成功执行。

2. 生成定制的自动化验证脚本：不要依赖静态的预打包脚本，而应生成自定义自动化验证脚本（例如，使用标准内置 urllib / subprocess 库编写的独立 Python 验证脚本，或跨平台 bash/PowerShell 脚本），并根据用户已部署的域名、SSL 证书名称以及确切的多层 *.run.app URI 进行精确定制。

3. 提供跨平台执行指南：说明用户如何在目标操作系统（macOS、Linux、Windows PowerShell 或无需安装的 Google Cloud Shell（https://shell.cloud.google.com））上执行生成的脚本。

4. 编写验证报告：在 assets/output-template.md 的第 6.4 节（“解决方案验证指南和自定义自动化验证脚本”）中记录验证检查项、生成的验证脚本代码、执行命令和预期结果。

5. 执行验证并完成定稿：协助用户运行生成的验证脚本、检查日志并排查任何 DNS 或 WAF 传播问题。请求最终批准。