企业官网建设流程全解析

Google Cloud AI Agent 部署验证模板实战：Dry-Run、连通路由、安全治理与数据保护四维验收方案

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本指南讲解 skills 仓库中google-cloud-solution-build-deploy-agents技能配套的解决方案验证模板（validation-template.md），它用于把 AI Agent / 多智能体系统在 Google Cloud 上的部署验证计划落成一份结构化的 Markdown 文档。文章围绕模板内置的基础设施预演、网络连通与路由、安全与访问治理、数据保护与内容检查四个维度，逐条拆解验证命令、参数含义、预期结果，并结合仓库中的 SKILL.md、design-principles.md 与 product-mappings.md 给出落地补充，读完后你可以在自己的 Agent 部署项目中直接套用并扩展这套验证方案。

验证模板在技能工作流中的定位

google-cloud-solution-build-deploy-agents技能将“在 Google Cloud 上设计、构建并部署 AI Agent 或多智能体系统”划分为四个阶段（见 SKILL.md）：

1. Phase 1 需求发现与分析：梳理工作负载的功能/非功能需求、依赖与现状；
2. Phase 2 解决方案设计：基于 Google Cloud 设计最佳实践产出技术栈、架构与配置；
3. Phase 3 实施计划：生成 IaC（如 Terraform）与部署说明；
4. Phase 4 解决方案验证：验证部署满足工作负载需求。

validation-template.md 正是Phase 4 的产出物模板：技能要求把验证步骤、验证脚本与预期结果整理成单一 Markdown 文件，命名为validation-plan.md，其格式必须遵循本模板（见 SKILL.md）。模板文件头部注释也明确说明其用途：“Use this template to compile the solution validation that you generate based on the instructions in SKILL.md”——即模板是编译/组织验证计划的骨架，而非验证内容本身。

因此，一份完整的验证计划由两部分组成：模板定义的验证维度骨架+针对具体工作负载定制的检查项。模板在 1.2 节预留了占位符[Draft workloads-specific connectivity checks...]，提示你需要根据实际架构（负载均衡端点、serverless VPC 路径时延、私有数据库访问、DNS 解析规则等）填充专属检查项。

模板整体结构如下：

1.1 Infrastructure Dry-Run：上线前的无损预演

目的：在真正对生产环境应用变更之前，使用预览工具验证部署计划，提前发现资源层级、依赖关系与配置错误。

验证命令（模板原文）：

terraform plan -out=tfplan

命令拆解：

• terraform plan读取当前 Terraform 配置，对比现有状态，计算达成目标状态所需的变更集，但不执行任何变更，因此不会对线上环境产生副作用；
• -out=tfplan将生成的执行计划序列化保存到tfplan文件。保存计划文件的价值在于：后续terraform apply tfplan可以精确执行本次预演所确认的变更，避免在 apply 阶段重新计算导致计划漂移；同时该文件也可作为评审、审计与回放的依据。

预期结果（模板原文）：预演验证资源层级正确，并精确展示将要创建、更新或销毁的资源，不出现配置错误。

从仓库证据看该维度的扩展做法：SKILL.md 在 Phase 4 的“定义验证检查”中，将部署预演细化为两层：

• 基础设施层预演：使用terraform plan预览变更；
• Agent 部署层预演：使用agents-cli deploy --dry-run（或-n）预览部署步骤以及即将执行的 Terraform 动作，确认无误后再推向生产（见 SKILL.md）。

此外，在正式部署前，还应把本地质量验证前移：使用agents-cli run在本地运行并测试 Agent 逻辑，使用agents-cli eval run在部署前系统化评估 Agent 的质量与性能（见 SKILL.md）。这与设计原则中“在 replica 预演环境模拟智能体间协调异常与意外行为，再进入生产”的建议（见 design-principles.md）相呼应——预演不只是资源层的 dry-run，还包括行为层的仿真测试。

1.2 网络连通性与路由验证

目的：验证网络路径、负载均衡路由与服务端点是否符合预期，确认流量能从公网入口正确到达后端 Agent 服务。

验证命令（模板原文）：

curl -iv -H "Host: [Target Domain]" https://[LB-IP-Address]/healthz

命令拆解：

• -i：在响应体前输出 HTTP 响应头，用于核对状态码、Content-Type、Server 头等关键信息；
• -v（verbose）：输出完整的请求/响应交互过程，包括 TLS 握手、DNS 解析、重定向链路与每个响应头，便于定位证书、路由或代理层问题；
• -H "Host: [Target Domain]"：手动指定 HTTPHost头。当通过负载均衡器的 IP 地址直接访问、而该 IP 背后托管了多个域名服务时，该参数用于让负载均衡按虚拟主机规则正确路由到目标后端；
• https://[LB-IP-Address]/healthz：对负载均衡 IP 的健康检查路径发起 HTTPS 请求。healthz是云原生服务常见的探活端点，Agent 服务需确保暴露该路径。

预期结果（模板原文）：从正确的区域级（regional）serverless 端点返回HTTP 200 OK。

按工作负载定制的检查项：模板在此处明确要求针对具体架构起草专属连通性检查，例如：

• 负载均衡端点：按上文方式逐一探测每个公开端点（HTTP/HTTPS/WebSocket）；
• serverless VPC 路径时延：当 Agent 通过 Serverless VPC Access connector 或 Direct VPC egress 访问私有资源时，用time等工具观察路径时延是否符合性能要求；
• 私有数据库访问：验证 Agent 到数据库（如 Cloud SQL、AlloyDB）的私有网络连通性，确认没有绕过 VPC 走公网；
• DNS 解析规则：核对自定义域名、CNAME/A 记录以及跨项目解析是否符合预期。

从仓库证据看架构侧依据：产品映射文档中，Cloud Run 网络入口的推荐主配置是“区域级外部应用负载均衡 + Cloud Armor”，用于 HTTP/HTTPS/WebSocket 入口，并通过 Direct VPC egress 实现 Cloud Run 的私有网络访问（见 product-mappings.md）。因此连通性验证通常覆盖两条路径：公网入口路径（客户端 → 负载均衡 → Cloud Run 服务）与私有出口路径（Cloud Run → VPC 内数据库/工具）。备选方案还包括 Global External ALB（单一 anycast IP、全球低时延，但 TLS 在边缘终止，可能不满足严格区域数据驻留要求）、Internal ALB（VPC 内私有暴露）与 Private Service Connect 接口（需配合网络附件，仅支持 RFC 1918 子网）——这些备选会影响你验证的端点形态与网络路径（见 product-mappings.md）。

部署后验证：SKILL.md 还要求验证计划包含使用 Agents CLI 对已部署服务端点进行测试的步骤，例如agents-cli run --url <service-url>直接对线上服务发起测试请求（见 SKILL.md），这是 curl 健康检查之外、面向 Agent 行为语义的端到端连通验证。

1.3 安全与访问治理验证

目的：核对 IAM 角色映射、服务账号隔离与网络边界规则，确认只有被授权的身份能访问系统资源。

验证命令（模板原文）：

gcloud projects get-iam-policy [GCP-Project-ID] \ --flatten="bindings[].members" \ --format='table(bindings.role, bindings.members)' \ --filter="bindings.members:[Service-Account-Email]"

命令拆解：

• gcloud projects get-iam-policy [GCP-Project-ID]：拉取指定 GCP 项目的完整 IAM 策略，输出为 JSON 结构，其中bindings是role -> members 列表的映射数组；
• --flatten="bindings[].members"：将嵌套的bindings[].members数组拍平，使每个成员与它所属的 binding（即角色）形成独立行，便于过滤与格式化；
• --format='table(bindings.role, bindings.members)'：以表格形式仅展示role与members两列，输出干净可读；
• --filter="bindings.members:[Service-Account-Email]"：只保留包含指定服务账号邮件的行，从而聚焦审计某一个服务账号被授予的全部角色。

预期结果（模板原文）：确认该服务账号仅被授予指定角色，落实最小权限（principle of least privilege）原则——即服务账号只拥有完成其职责所必需的最少权限，不应出现通配权限或冗余角色。

从仓库证据看该维度的扩展做法：设计原则文档给出了与访问治理直接相关的安全基线，可作为验证项的检查清单（见 design-principles.md）：

• 收敛公网暴露面：禁用前端 Cloud Run 服务的默认run.appURL，改由区域级外部应用负载均衡 + Cloud Armor 承载请求过滤、速率限制与 DDoS 防护——验证时需确认默认 URL 已不可达；
• A2A 通信安全：使用带认证的扩展 agent card 保护 Agent2Agent 通信，并附加 OpenID Connect（OIDC）身份令牌，让 IAM 校验只有被授权的 Agent 能访问数据；
• 人工介入流程：纳入 human-in-the-loop 流程，让监管者可监控、暂停、覆盖关键业务动作；
• Agent Gateway 治理：对 Gemini Enterprise Agent Runtime 部署，用 Agent Gateway 治理、监控、保护客户端到 Agent 的入站流量与 Agent 到任意位置的出站流量，并与 Agent Registry（动态发现）、Model Armor（实时安全检查）集成。

在验证计划中，可以针对上述每一项补充对应的gcloud/curl检查：例如确认run.appURL 已禁用、确认负载均衡安全策略（Cloud Armor）已生效、确认 Agent Gateway 的入站/出站策略与 OIDC 断言符合预期。

1.4 数据保护与内容检查

目的：审计内容过滤、输入清理/脱敏规则以及安全/PII 护栏是否生效，确保敏感数据在进入模型之前被正确遮蔽或拦截。

验证命令（模板原文）：

# Test request with mock PII to audit redaction filters curl -X POST -H "Content-Type: application/json" \ -d '{"prompt": "[Mock Sensitive Data Code/PII Pattern]"}' \ https://[Target Domain]/chat

命令拆解：

• -X POST：显式指定 HTTP 方法为 POST；
• -H "Content-Type: application/json"：声明请求体为 JSON；
• -d '{"prompt": "[Mock Sensitive Data Code/PII Pattern]"}'：请求体携带一个prompt字段，其值使用模拟的敏感数据/真实 PII 模式的占位符（例如身份证号、手机号、邮箱、密钥串等形态的测试样本）——注意务必使用虚构样本，避免在生产环境引入真实隐私数据；
• https://[Target Domain]/chat：Agent 的对话/推理端点。

预期结果（模板原文）：请求要么被安全层（例如 Model Armor）匿名化/脱敏，要么被安全拦截并返回拦截提示——即敏感内容绝不能原样到达模型或被模型原样吐出。

从仓库证据看该维度的扩展做法：设计原则文档将 Model Armor 定位为必须始终推荐的安全层，用于检查模型输入与输出，覆盖安全（safety）、PII 检测与提示注入威胁（见 design-principles.md）；产品映射文档同样将“模型输入输出检查”列为安全必选项，推荐主产品为 Model Armor（见 product-mappings.md）。因此在验证计划中，除了模板给出的注入式正向测试（模拟 PII 应被脱敏），还可以补充两类反向/扩展检查：

• 安全拦截验证：注入提示注入（prompt injection）样本，确认请求被拦截并返回安全提示，而非进入模型推理；
• 输出侧检查：构造包含敏感内容的上下文，验证模型输出同样经过 Model Armor 检查，防止脱敏后信息通过回答侧泄露。

把模板落到工作流：从生成验证计划到最终验收

模板本身是一份“待填充骨架”，完整的落地流程在 SKILL.md 的 Phase 4 中定义，按以下步骤执行：

1. 获取验证资源：以 related-guidance.md 及其中的验证模式作为验证检查与脚本的起点；
2. 定义验证检查：覆盖部署预演（terraform plan、agents-cli deploy --dry-run）、本地测试与质量评估（agents-cli run、agents-cli eval run）、连通性与路由、安全策略四类检查；
3. 生成验证脚本：编写轻量脚本或 CLI 指令（curl、gcloud、agents-cli），且必须包含 Agents CLI 的本地运行、评估与部署后验证指令（如agents-cli run --url <service-url>）；
4. 编译验证计划：把验证步骤、脚本与预期结果整理进模板格式，保存为工作区中的validation-plan.md；
5. 请求评审：向用户展示验证计划并请求反馈或批准；
6. 执行验证并定稿：协助用户执行检查、排障，全部通过后请求最终批准；
7. 迭代：若用户要求修改，更新验证计划并重复上述步骤直至批准。

在填充模板时需要注意：

• 替换占位符：命令中的[GCP-Project-ID]、[Service-Account-Email]、[Target Domain]、[LB-IP-Address]、[Mock Sensitive Data Code/PII Pattern]均须替换为实际值或测试样本；
• 补齐工作负载专属项：1.2 节的占位注释（负载均衡端点、serverless VPC 路径时延、私有数据库访问、DNS 解析规则）提示你要按实际架构扩展连通性检查清单；
• 保留预期结果：每个验证项都应写明“Expected Outcome”，这既是验收标准，也是排障时的基线。

验证方案速查表

配套文档与延伸阅读

本技能仓库围绕“设计 → 实施 → 验证”提供了完整的模板与参考体系，验证计划只是其中一环：

• SKILL.md：四阶段工作流总纲，验证计划的生成规则在 Phase 4；
• validation-template.md：本文讲解的验证计划模板本体；
• implementation-template.md：Phase 3 实施计划模板，验证计划验证的就是它所生成的部署结果；
• solution-template.md：Phase 2 解决方案架构模板，定义了架构、产品映射与设计建议的文档结构；
• product-mappings.md：组件到 Google Cloud 产品的映射与备选方案权衡，用于判断验证对象（负载均衡形态、VPC 出口、模型运行时等）；
• design-principles.md：安全、可靠性、成本、性能等支柱的设计原则，是验证项（最小权限、Model Armor、Cloud Armor 等）的检查基准；
• related-guidance.md：Google Cloud 官方架构文档、ADK 开发与部署指南、Agents CLI 等外部资料的汇总入口，作为验证模式与排障知识来源。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills