1. 概览
Cloud Run 是一个全代管式平台，可让您直接在 Google 可伸缩的基础架构之上运行代码。本 Codelab 将演示如何将 Cloud Run 上的 Next.js 应用连接到 Cloud SQL for PostgreSQL 数据库。
在本实验中，您将学习如何完成以下操作：
- 创建 Cloud SQL for PostgreSQL 实例（配置为使用 Private Service Connect）
- 将应用部署到 Cloud Run，以连接到 Cloud SQL 数据库
- 使用 Gemini Code Assist 为应用添加功能
2. 前提条件
- 如果您还没有 Google 账号，则必须先创建一个 Google 账号。
- 请使用个人账号，而不是工作账号或学校账号。工作账号和学校账号可能会受到限制，导致您无法启用本实验所需的 API。
3. 项目设置
- 登录 Google Cloud 控制台。
- 在 Cloud 控制台中启用结算功能。
- 完成本实验所需的 Cloud 资源费用应低于 1 美元。
- 您可以按照本实验最后的步骤删除资源，以免产生更多费用。
- 新用户符合参与 300 美元免费试用的条件。
- 创建新项目或选择重复使用现有项目。
4. 打开 Cloud Shell Editor
- 前往 Cloud Shell Editor
- 如果终端未显示在屏幕底部，请打开它：
- 点击汉堡式菜单
- 点击终端
- 点击 New Terminal
- 点击汉堡式菜单
- 在终端中，使用以下命令设置项目：
- 格式：
gcloud config set project [PROJECT_ID] - 示例：
gcloud config set project lab-project-id-example - 如果您不记得项目 ID，请执行以下操作：
- 您可以使用以下命令列出所有项目 ID：
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- 您可以使用以下命令列出所有项目 ID：
- 格式：
- 如果系统提示您进行授权，请点击授权继续。
- 您应会看到以下消息：
Updated property [core/project].
WARNING并收到Do you want to continue (Y/N)?问题，则可能输入的项目 ID 有误。按N，按Enter，然后尝试再次运行gcloud config set project命令。
5. 启用 API
在终端中，启用以下 API：
gcloud services enable \
compute.googleapis.com \
sqladmin.googleapis.com \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
networkconnectivity.googleapis.com \
servicenetworking.googleapis.com \
cloudaicompanion.googleapis.com
如果系统提示您进行授权，请点击授权继续。
此命令可能需要几分钟才能完成，但最终应该会显示类似以下内容的成功消息：
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
6. 设置服务账号
创建并配置供 Cloud Run 使用的 Google Cloud 服务账号，使其具有正确的权限来连接到 Cloud SQL。
- 按照以下方式运行
gcloud iam service-accounts create命令来创建新的服务账号：gcloud iam service-accounts create quickstart-service-account \ --display-name="Quickstart Service Account" - 按如下所示运行 gcloud projects add-iam-policy-binding 命令，将 Log Writer 角色添加到您刚刚创建的 Google Cloud 服务账号。
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \ --member="serviceAccount:quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \ --role="roles/logging.logWriter"
7. 创建 Cloud SQL 实例
- 创建服务连接政策，以允许通过 Private Service Connect 从 Cloud Run 建立到 Cloud SQL 的网络连接
gcloud network-connectivity service-connection-policies create quickstart-policy \ --network=default \ --project=${GOOGLE_CLOUD_PROJECT} \ --region=us-central1 \ --service-class=google-cloud-sql \ --subnets=https://www.googleapis.com/compute/v1/projects/${GOOGLE_CLOUD_PROJECT}/regions/us-central1/subnetworks/default - 为数据库生成唯一的密码
export DB_PASSWORD=$(openssl rand -base64 20) - 运行
gcloud sql instances create命令以创建 Cloud SQL 实例gcloud sql instances create quickstart-instance \ --project=${GOOGLE_CLOUD_PROJECT} \ --root-password=${DB_PASSWORD} \ --database-version=POSTGRES_17 \ --tier=db-perf-optimized-N-2 \ --region=us-central1 \ --ssl-mode=ENCRYPTED_ONLY \ --no-assign-ip \ --enable-private-service-connect \ --psc-auto-connections=network=projects/${GOOGLE_CLOUD_PROJECT}/global/networks/default
此命令可能需要几分钟才能完成。
- 运行
gcloud sql databases create命令以在quickstart-instance中创建 Cloud SQL 数据库。gcloud sql databases create quickstart_db \ --instance=quickstart-instance
8. 准备申请材料
准备一个响应 HTTP 请求的 Next.js 应用。
- 要创建名为
task-app的新 Next.js 项目，请使用以下命令：npx create-next-app@15.0.3 task-app \ --ts \ --eslint \ --tailwind \ --no-src-dir \ --turbopack \ --app \ --no-import-alias - 如果系统要求您安装
create-next-app，请按Enter继续：Need to install the following packages: create-next-app@15.0.3 Ok to proceed? (y) - 转到
task-app目录：cd task-app - 安装
pg以与 PostgreSQL 数据库交互。npm install pg - 将
@types/pg安装为开发依赖项，以使用 TypeScript Next.js 应用。npm install --save-dev @types/pg - 创建
actions.ts文件。touch app/actions.ts - 在 Cloud Shell Editor 中打开
actions.ts文件：cloudshell edit app/actions.tsactions.ts文件。
- 复制以下代码并将其粘贴到打开的
actions.ts文件中：'use server' import pg from 'pg'; type Task = { id: string; title: string; status: 'IN_PROGRESS' | 'COMPLETE'; }; const { Pool } = pg; const pool = new Pool({ host: process.env.DB_HOST, user: process.env.DB_USER, password: process.env.DB_PASSWORD, database: process.env.DB_NAME, ssl: { // @ts-expect-error require true is not recognized by @types/pg, but does exist on pg require: true, rejectUnauthorized: false, // required for self-signed certs // https://node-postgres.com/features/ssl#self-signed-cert } }); const tableCreationIfDoesNotExist = async () => { await pool.query(`CREATE TABLE IF NOT EXISTS visits ( id SERIAL NOT NULL, created_at timestamp NOT NULL, PRIMARY KEY (id) );`); await pool.query(`CREATE TABLE IF NOT EXISTS tasks ( id SERIAL NOT NULL, created_at timestamp NOT NULL, status VARCHAR(255) NOT NULL default 'IN_PROGRESS', title VARCHAR(1024) NOT NULL, PRIMARY KEY (id) );`); } // CREATE export async function addNewTaskToDatabase(newTask: string) { await tableCreationIfDoesNotExist(); await pool.query(`INSERT INTO tasks(created_at, status, title) VALUES(NOW(), 'IN_PROGRESS', $1)`, [newTask]); return; } // READ export async function getTasksFromDatabase() { await tableCreationIfDoesNotExist(); const { rows } = await pool.query(`SELECT id, created_at, status, title FROM tasks ORDER BY created_at DESC LIMIT 100`); console.table(rows); // logs the last 5 visits on the server return rows; // sends the last 5 visits to the client } // UPDATE export async function updateTaskInDatabase(task: Task) { await tableCreationIfDoesNotExist(); await pool.query( `UPDATE tasks SET status = $1, title = $2 WHERE id = $3`, [task.status, task.title, task.id] ); return; } // DELETE export async function deleteTaskFromDatabase(taskId: string) { await tableCreationIfDoesNotExist(); await pool.query(`DELETE FROM tasks WHERE id = $1`, [taskId]); return; } - 在 Cloud Shell Editor 中打开
page.tsx文件：cloudshell edit app/page.tsxpage.tsx文件。 - 删除
page.tsx文件的现有内容。 - 复制以下代码并将其粘贴到打开的
page.tsx文件中：'use client' import React, { useEffect, useState } from "react"; import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions"; type Task = { id: string; title: string; status: 'IN_PROGRESS' | 'COMPLETE'; }; export default function Home() { const [newTaskTitle, setNewTaskTitle] = useState(''); const [tasks, setTasks] = useState<Task[]>([]); async function getTasks() { const updatedListOfTasks = await getTasksFromDatabase(); setTasks(updatedListOfTasks); } useEffect(() => { getTasks(); }, []); async function addTask() { await addNewTaskToDatabase(newTaskTitle); await getTasks(); setNewTaskTitle(''); } async function updateTask(task: Task, newTaskValues: Partial<Task>) { await updateTaskInDatabase({ ...task, ...newTaskValues }); await getTasks(); } async function deleteTask(taskId: string) { await deleteTaskFromDatabase(taskId); await getTasks(); } return ( <main className="p-4"> <h2 className="text-2xl font-bold mb-4">To Do List</h2> <div className="flex mb-4"> <form onSubmit={handleSubmit} className="flex mb-8"> <input type="text" placeholder="New Task Title" value={newTaskTitle} onChange={(e) => setNewTaskTitle(e.target.value)} className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit" /> <button type="submit" className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap" > Add New Task </button> </form> </div> <table className="w-full"> <tbody> {tasks.map(function (task) { const isComplete = task.status === 'COMPLETE'; return ( <tr key={task.id} className="border-b border-gray-200"> <td className="py-2 px-4"> <input type="checkbox" checked={isComplete} onClick={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })} className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500" /> </td> <td className="py-2 px-4"> <span className={`transition-all duration-300 ease-in-out ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`}> {task.title} </span> </td> <td className="py-2 px-4"> <button onClick={() => deleteTask(task.id)} className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded" > Delete </button> </td> </tr> ); })} </tbody> </table> </main> ); }
应用现已准备好部署。
9. 将应用部署到 Cloud Run
- 按照以下方式运行 gcloud projects add-iam-policy-binding 命令，将 Network User 角色添加到您即将创建的 Cloud Run 服务的 Cloud Run 服务账号。
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \ --member "serviceAccount:service-$(gcloud projects describe ${GOOGLE_CLOUD_PROJECT} --format="value(projectNumber)")@serverless-robot-prod.iam.gserviceaccount.com" \ --role "roles/compute.networkUser"
- 运行以下命令将应用部署到 Cloud Run：
gcloud run deploy helloworld \ --region=us-central1 \ --source=. \ --set-env-vars DB_NAME="quickstart_db" \ --set-env-vars DB_USER="postgres" \ --set-env-vars DB_PASSWORD=${DB_PASSWORD} \ --set-env-vars DB_HOST="$(gcloud sql instances describe quickstart-instance --project=${GOOGLE_CLOUD_PROJECT} --format='value(settings.ipConfiguration.pscConfig.pscAutoConnections.ipAddress)')" \ --service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \ --network=default \ --subnet=default \ --allow-unauthenticated - 如果系统提示，请按
Y和Enter确认您要继续：Do you want to continue (Y/n)? Y
几分钟后，应用应会提供一个网址供您访问。
前往该网址，查看应用的实际运行情况。每次访问该网址或刷新页面时，您都会看到 Tasks 应用。
10. 使用 Gemini Code Assist 添加功能
现在，您已部署了一个包含数据库的 Web 应用。接下来，我们将利用 AI 辅助功能为 Next.js 应用添加一项新功能。
- 返回 Cloud Shell Editor
- 重新打开
page.tsxcd ~/task-app cloudshell edit app/page.tsx - 在 Cloud Shell 编辑器中前往 Gemini Code Assist：
- 点击屏幕左侧工具栏中的 Gemini 图标
- 如果系统提示，请使用您的 Google 账号凭据登录
- 如果系统提示您选择项目，请选择您为本 Codelab 创建的项目
- 点击屏幕左侧工具栏中的 Gemini 图标
- 输入提示：
Add the ability to update the title of the task. The code in your output should be complete and working code.。响应应包含类似于以下代码段的内容，用于添加handleEditStart和handleEditCancel函数：const [editingTaskId, setEditingTaskId] = useState<string>(''); const [editedTaskTitle, setEditedTaskTitle] = useState(''); const handleEditStart = (task: Task) => { setEditingTaskId(task.id); setEditedTaskTitle(task.title); }; const handleEditCancel = () => { setEditingTaskId(''); setEditedTaskTitle(''); };<td className="py-2 px-4"> {editingTaskId === task.id ? ( <form onSubmit={(e) => { e.preventDefault(); updateTask(task, { title: editedTaskTitle }); }}> <input type="text" value={editedTaskTitle} onChange={(e) => setEditedTaskTitle(e.target.value)} onBlur={() => handleEditCancel} // Handle clicking outside input className="border border-gray-400 rounded px-3 py-1 mr-2" /> <button type="submit" className="text-green-600 hover:text-green-900 mr-1">Save</button> </form> ) : ( <span onClick={() => handleEditStart(task)} className="cursor-pointer"> {task.title} </span> )} </td> - 将
page.tsx替换为 Gemini Code Assist 的输出。以下是一个有效示例：'use client' import React, { useEffect, useState } from "react"; import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions"; type Task = { id: string; title: string; status: 'IN_PROGRESS' | 'COMPLETE'; }; export default function Home() { const [newTaskTitle, setNewTaskTitle] = useState(''); const [tasks, setTasks] = useState<Task[]>([]); const [editingTaskId, setEditingTaskId] = useState<string>(''); const [editedTaskTitle, setEditedTaskTitle] = useState(''); async function getTasks() { const updatedListOfTasks = await getTasksFromDatabase(); setTasks(updatedListOfTasks); } useEffect(() => { getTasks(); }, []); async function addTask() { await addNewTaskToDatabase(newTaskTitle); await getTasks(); setNewTaskTitle(''); } async function updateTask(task: Task, newTaskValues: Partial<Task>) { await updateTaskInDatabase({ ...task, ...newTaskValues }); await getTasks(); setEditingTaskId(''); // Clear editing state after update setEditedTaskTitle(''); } async function deleteTask(taskId: string) { await deleteTaskFromDatabase(taskId); await getTasks(); } const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); addTask(); }; const handleEditStart = (task: Task) => { setEditingTaskId(task.id); setEditedTaskTitle(task.title); }; const handleEditCancel = () => { setEditingTaskId(''); setEditedTaskTitle(''); }; return ( <main className="p-4"> <h2 className="text-2xl font-bold mb-4">To Do List</h2> <form onSubmit={handleSubmit} className="flex mb-8"> <input type="text" placeholder="New Task Title" value={newTaskTitle} onChange={(e) => setNewTaskTitle(e.target.value)} className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit" /> <button type="submit" className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap" > Add New Task </button> </form> <table className="w-full"> <tbody> {tasks.map(task => { const isComplete = task.status === 'COMPLETE'; return ( <tr key={task.id} className="border-b border-gray-200"> <td className="py-2 px-4"> <input type="checkbox" checked={isComplete} onClick={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })} className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500" /> </td> <td className="py-2 px-4"> {editingTaskId === task.id ? ( <form onSubmit={(e) => { e.preventDefault(); updateTask(task, { title: editedTaskTitle }); }} className="flex" > <input type="text" value={editedTaskTitle} onChange={(e) => setEditedTaskTitle(e.target.value)} onBlur={() => handleEditCancel()} // Handle clicking outside input className="flex-grow border border-gray-400 rounded px-3 py-1 mr-2 bg-inherit" /> <button type="submit" className="bg-green-600 hover:bg-green-900 m-1 text-white font-bold py-2 px-4 rounded" > Save </button> </form> ) : ( <span onClick={() => handleEditStart(task)} className={`transition-all duration-300 ease-in-out cursor-pointer ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`} > {task.title} </span> )} </td> <td className="py-2 px-4"> <button onClick={() => deleteTask(task.id)} className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded float-right" > Delete </button> </td> </tr> ); })} </tbody> </table> </main> ); }
11. 将应用重新部署到 Cloud Run
- 运行以下命令将应用部署到 Cloud Run：
gcloud run deploy helloworld \ --region=us-central1 \ --source=. \ --set-env-vars DB_NAME="quickstart_db" \ --set-env-vars DB_USER="postgres" \ --set-env-vars DB_PASSWORD=${DB_PASSWORD} \ --set-env-vars DB_HOST="$(gcloud sql instances describe quickstart-instance --project=${GOOGLE_CLOUD_PROJECT} --format='value(settings.ipConfiguration.pscConfig.pscAutoConnections.ipAddress)')" \ --service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \ --network=default \ --subnet=default \ --allow-unauthenticated - 如果系统提示，请按
Y和Enter确认您要继续：Do you want to continue (Y/n)? Y
12. 恭喜
在本实验中，您学习了如何执行以下操作：
- 创建 Cloud SQL for PostgreSQL 实例（配置为使用 Private Service Connect）
- 将应用部署到 Cloud Run，以连接到 Cloud SQL 数据库
- 使用 Gemini Code Assist 为应用添加功能
清理
Cloud SQL 不提供免费层级，如果您继续使用，我们会向您收费。您可以删除 Cloud 项目，以免产生额外费用。
虽然 Cloud Run 不会对未在使用中的服务计费，但您可能仍然需要为将容器映像存储在 Artifact Registry 中而产生的相关费用付费。删除 Cloud 项目后，系统即会停止对该项目中使用的所有资源计费。
如有需要，请删除项目：
gcloud projects delete $GOOGLE_CLOUD_PROJECT
您可能还希望从 CloudShell 磁盘中删除不必要的资源。您可以：
- 删除 Codelab 项目目录：
rm -rf ~/task-app - 警告！下一步操作无法撤消！如果您想删除 Cloud Shell 中的所有内容以释放空间，可以删除整个主目录。请务必将您要保留的所有内容保存到其他位置。
sudo rm -rf $HOME