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 智能体对开发者知识 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(projectNumber)')
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": "frontend",
"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" \
--labels dev-tutorial=codelab-ultimate-cr26
- 通过 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