1. 简介
此 Codelab 将引导您了解 Cloud Run 的基本使用入门知识。您将了解如何使用其他功能，包括 VPC 访问权限、Secret Manager 和 ADK，以便在 Cloud Run 上托管 AI 代理。
学习内容
- 部署 nginx 映像
- 从源代码进行部署
- 回滚部署
- 预览部署
- 使用开发者知识 MCP 服务器工具
- 将 Secret Manager 与 Cloud Run 搭配使用
- 连接到 VPC 内的内部 Cloud Run 服务
- 将 ADK 智能体部署到 Cloud Run
所需条件
- 网络浏览器，例如 Chrome
- 启用了结算功能的 Google Cloud 项目
创建 Google Cloud 项目
- 在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。
- 确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
启动 Cloud Shell
Cloud Shell 是在 Google Cloud 中运行的命令行环境，预加载了必要的工具。
- 点击 Google Cloud 控制台顶部的激活 Cloud Shell。
- 连接到 Cloud Shell 后，验证您的身份验证：
gcloud auth list - 确认您的项目已配置：
gcloud config get project - 如果项目未按预期设置，请进行设置：
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
设置环境变量
此 Codelab 使用以下环境变量。
首先，设置区域。
export REGION=<YOUR_REGION>
接下来，确认您的 PROJECT_ID 和 REGION
echo "PROJECT_ID: $PROJECT_ID | REGION: $REGION"
2. 从映像部署
在本部分中，您将直接从 Docker Hub 部署标准 nginx 映像。您将配置该容器以使其可公开访问，并将容器端口设置为 80。
- 部署 nginx 服务：
gcloud run deploy nginx-service \
--image=nginx \
--allow-unauthenticated \
--port=80 \
--region=$REGION
- 部署完成后，命令输出将提供服务网址。在浏览器中打开该网址，即可看到“欢迎使用 nginx！”页面。
3. 从源代码进行部署
mkdir color-app && cd $_
创建一个名为 requirements.txt 且包含以下内容的文件：
Flask>=2.0.0
gunicorn>=20.0.0
创建一个名为 main.py 且包含以下内容的文件：
import os
from flask import Flask, render_template_string
app = Flask(__name__)
TEMPLATE = """
<!doctype html>
<html lang="en">
<head>
<title>Cloud Run Traffic Revisions</title>
<style>
body {
display: flex;
justify-content: center;
align-items: center;
min-height: 50vh;
background-color: darkseagreen;
font-family: sans-serif;
}
.content {
background-color: rgba(255, 255, 255, 0.8); /* Semi-transparent white background */
padding: 2em;
border-radius: 8px;
text-align: center;
box-shadow: 0 4px 8px rgba(0,0,0,0.1);
}
</style>
</head>
<body>
<div class="content">
<!-- ROLLBACK DEMO: change this text to "gray" -->
<p>background color: <strong>darkseagreen</strong></p>
</div>
</body>
</html>
"""
@app.route('/')
def main():
return render_template_string(TEMPLATE)
if __name__ == '__main__':
port = int(os.environ.get('PORT', 8080))
app.run(debug=True, host='0.0.0.0', port=port)
现在运行以下命令。
gcloud run deploy \
--allow-unauthenticated
--region $REGION
4. 回滚和预览链接
在本部分中，您将引入一个 bug，并学习如何在调查修复方案的同时回滚到之前的修订版本。
- 首先，您需要记录当前处理流量的修订版本的名称，因为该版本不包含 bug。
GOOD_REVISION=$(gcloud run revisions list --service color-app \
--region $REGION --format 'value(REVISION)')
- 在 color-app
main.py文件中，搜索“ROLLBACK DEMO”，并将该行更新为以下内容：
<p>background color: <strong>gray</strong></p>
- 现在，重新运行
gcloud run deploy。了解之前配置的使用情况。
现在，您已部署了一个 bug，您可以返回到源代码，进行更改或执行 git revert，然后进行构建、触发新的构建等。不过，您可能会在此过程中引入错误。
更安全的方式是回滚。
- 如需回滚到上一个修订版本，请运行以下命令：
gcloud run services update-traffic color-app \
--to-revisions=$GOOD_REVISION=100 \
--region=$REGION
现在，您可以部署不会接收任何流量的新修订版本。
- 现在，通过将文本改回
darkseagreen来修复 bug
<p>background color: <strong>darkseagreen</strong></p>
- 然后部署该版本以验证修复。请注意，该修订版本不会收到任何流量，因为 100% 的流量都固定到 GOOD_REVISION
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
- 验证 Deployment
您会发现网址略有不同。访问该版本时，您会看到此部署中的 bug 修复。
- 将流量发送回最新修订版本。
现在，您将流量重新设置回最新修订版本。
gcloud run services update-traffic color-app \
--to-latest \
--region=$REGION
并删除修订版本标记
gcloud run services update-traffic color-app \
--remove-tags=bugfix \
--region=$REGION
如需详细了解回滚，请参阅相关文档。
5. 开发者知识 MCP 服务器
Developer Knowledge MCP 服务器让 AI 赋能的开发工具能够搜索 Google 的官方开发者文档，并检索 Google 产品（例如 Firebase、Google Cloud、Android、Google 地图等）的相关信息。通过将 AI 应用直接连接到我们的官方文档库，您可以确保收到的代码和指导是最新的，并且基于权威的上下文。
您需要按照安装指南操作，以授予 AI 智能体对 Developer Knowledge MCP 服务器的访问权限。
安装后，您可以向 AI 智能体询问文档中可能在模型训练日期截止后发布的新功能。
例如，如果您查看 Cloud Run 版本说明，就会看到 2026 年 2 月 24 日有一条条目，内容是“使用 Cloud Run 服务健康状况（预览版）部署具有自动故障切换和故障恢复功能的高可用性多区域 Cloud Run 服务，以处理外部流量。”
现在，您可以向 AI 智能体提出以下问题：“详细介绍一下这项新的 Cloud Run 功能，用于实现多区域自动故障切换。”
6. 使用 Secret Manager
您可以通过以下 3 种方式在 Cloud Run 上公开 Secret：
- 作为环境变量（锁定到部署时拉取的版本）。
- 装载为文件卷（持续更新到最新版本）。
- 在代码中使用 Secret Manager 客户端库。
在本部分中，您将使用专用服务账号将 Secret 公开为环境变量。
- 创建名为“my-secret”的新 Secret：
gcloud secrets create my-secret --replication-policy="automatic"
- 将密文值添加为新版本：
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
- 为颜色应用创建专用服务账号：
gcloud iam service-accounts create color-app-sa \
--display-name="Color App Service Account"
- 向专用服务账号授予对 Secret 的访问权限。
gcloud secrets add-iam-policy-binding my-secret \
--member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
- 再次部署。现在，该服务将有权访问 MY_SECRET 环境变量：
gcloud run deploy color-app \
--source . \
--update-secrets=MY_SECRET=my-secret:latest \
--service-account=color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com \
--region=$REGION
7. 连接到 VPC
在本部分中，您将设置以下架构：
- 无法通过公共互联网访问的私有后端
- 通过直接 VPC 出站流量与后端通信的公共前端
此示例将使用默认网络和子网。
前提条件：确保在子网上启用专用 Google 访问通道，以便 VPC 可以将内部请求路由到 Cloud Run 服务。
gcloud compute networks subnets update default \
--region=$REGION \
--enable-private-ip-google-access
- 为此部分创建文件夹
mkdir ../vpc-demo
cd ../vpc-demo
- 创建专用后端服务
mkdir backend
touch backend/app.js
touch backend/package.json
在 backend/app.js 文件中，添加以下内容：
const http = require('http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end('Hello World from the Private Backend!');
});
const port = process.env.PORT || 8080;
server.listen(port, () => {
console.log(`Private backend listening on port ${port}`);
});
在 backend/package.json 文件中，添加以下内容：
{
"name": "backend",
"scripts": {
"start": "node app.js"
}
}
- 部署仅限内部使用的入站流量专用后端：
gcloud run deploy private-backend \
--source ./backend \
--region $REGION \
--ingress internal \
--no-allow-unauthenticated
- 记录后端网址。您稍后会向前端应用提供此网址。
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')
export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
- 创建前端应用
mkdir frontend
touch frontend/app.js
touch frontend/package.json
在 frontend/app.js 文件中，添加以下内容：
const http = require('http');
const server = http.createServer(async (req, res) => {
const backendUrl = process.env.BACKEND_URL;
if (!backendUrl) {
res.writeHead(500, { 'Content-Type': 'text/plain' });
return res.end('Error: BACKEND_URL environment variable is missing.');
}
try {
// Fetch the OIDC token from the Metadata server
const tokenResponse = await fetch(`http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${backendUrl}`, {
headers: { 'Metadata-Flavor': 'Google' }
});
if (!tokenResponse.ok) {
throw new Error(`Failed to fetch identity token: ${tokenResponse.statusText}`);
}
const token = await tokenResponse.text();
// Ping the backend with the token
const response = await fetch(backendUrl, {
headers: { 'Authorization': `Bearer ${token}` }
});
const text = await response.text();
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end(`Frontend successfully routed through VPC. Backend says: "${text}"`);
} catch (error) {
res.writeHead(500, { 'Content-Type': 'text/plain' });
res.end(`Frontend failed to reach the backend. Error: ${error.message}`);
}
});
const port = process.env.PORT || 8080;
server.listen(port, () => {
console.log(`Public frontend listening on port ${port}`);
});
- 在
frontend/package.json文件中，添加以下内容：
{
"name": "backend",
"scripts": {
"start": "node app.js"
}
}
- 为前端服务创建专用服务账号：
gcloud iam service-accounts create frontend-sa \
--display-name="Frontend Service Account"
- 向其授予 Cloud Run Invoker 角色
PROJECT_ID=$(gcloud config get project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/run.invoker"
- 现在，使用直接 VPC 出站流量部署公共前端。我们将“--vpc-egress=all-traffic”设置为强制将出站请求发送到 VPC：
gcloud run deploy public-frontend \
--source ./frontend \
--region $REGION \
--allow-unauthenticated \
--network default \
--subnet default \
--vpc-egress all-traffic \
--service-account=frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com \
--set-env-vars BACKEND_URL=$BACKEND_URL
- 验证服务
- 测试前端：对公共前端网址执行 curl 命令。它应成功与后端通信并返回响应。
FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
curl $FRONTEND_URL
- 测试后端（直接）：尝试直接从本地机器（公共互联网）对后端网址执行 curl 命令。由于入站流量受限为“内部”，并且需要进行身份验证，因此该请求应会失败并返回 404 错误。
curl $BACKEND_URL
8. 部署 ADK 代理
在本部分中，您将了解 Python buildpack 如何支持检测智能体开发套件 (ADK) 的默认入口点。
您将创建以下文件夹结构：
adk-demo - my_agent - __init.py__ - agent.py - requirements.txt
- 创建文件夹结构
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
- 将以下内容添加到
my_agent/__init.py__文件中：
from . import agent
- 将以下内容添加到
my_agent/agent.py文件中：
from google.adk import Agent
root_agent = Agent(
name="demo_agent",
model="gemini-3-flash-preview",
instruction="You are a helpful assistant for a Cloud Run demo."
)
- 将以下内容添加到
requirements.txt文件中：
google-adk
- 为代理创建专用服务账号：
gcloud iam service-accounts create agent-sa \
--display-name="Agent Service Account"
- 向服务账号授予 Vertex AI User 角色：
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:agent-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
- 部署 ADK 代理
您必须在可访问 Gemini API 的区域中进行部署。在本示例中，该地址为 us-west1。
gcloud run deploy my-adk-agent-demo \
--source . \
--region us-west1 \
--allow-unauthenticated \
--service-account=agent-sa@${PROJECT_ID}.iam.gserviceaccount.com \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"
- 通过 Curl 调用端点
您可以看到，该智能体可立即作为可用于生产用途的 API 使用。
将 Cloud Run 服务网址记录到环境变量中。
AGENT_URL=$(gcloud run services describe my-adk-agent-demo \
--region us-west1 \
--format 'value(status.url)')
与代理创建会话
curl -X POST $AGENT_URL/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'
询问“什么是 Cloud Run”，并过滤回答以仅显示代理的回答
curl -X POST $AGENT_URL/run \
-H "Content-Type: application/json" \
-d "{
\"appName\": \"my_agent\",
\"userId\": \"u_123\",
\"sessionId\": \"s_123\",
\"newMessage\": {
\"role\": \"user\",
\"parts\": [{ \"text\": \"What is Cloud Run?\"
}]}
}" | python3 -c "import sys, json; print(json.load(sys.stdin)[-1]['content']['parts'][0]['text'])"
您应该会看到类似以下内容：
Hello! I am **demo_agent**, and I'm here to help you with your Cloud Run demo. **Cloud Run** is a fully managed compute platform by Google Cloud that allows you to run **containerized applications** in a serverless environment...
9. 清理
为避免您的 Google Cloud 账号持续产生费用，您可以删除整个项目（如下所示），也可以删除在此 Codelab 中创建的各个资源。
删除 nginx、color-app、private-backend、public-frontend 服务
gcloud run services delete nginx-service --region $REGION --quiet
gcloud run services delete color-app --region $REGION --quiet
gcloud run services delete private-backend --region $REGION --quiet
gcloud run services delete public-frontend --region $REGION --quiet
删除 ADK 代理（注意：在此示例中，该代理部署在 us-west1 中）
gcloud run services delete my-adk-agent-demo --region us-west1 --quiet
移除存储在 Secret Manager 中的 Secret：
gcloud secrets delete my-secret --quiet
删除“颜色”应用服务账号
gcloud iam service-accounts delete color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet
删除 ADK 代理服务账号
gcloud iam service-accounts delete agent-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet
（可选）删除项目
如果您专门为此 Codelab 创建了一个新项目，则可以删除整个项目，以确保一次性移除所有资源：
# run only if you want to delete the entire project
gcloud projects delete $PROJECT_ID
10. 恭喜！
您已完成此 Codelab。您已了解 Cloud Run 使用入门的基础知识。
要点回顾
- 部署 nginx 映像
- 从源代码进行部署
- 回滚部署
- 预览部署
- 使用开发者知识 MCP 服务器工具
- 将 Secret Manager 与 Cloud Run 搭配使用
- 连接到 VPC 内的内部 Cloud Run 服务
- 将 ADK 智能体部署到 Cloud Run