教程：为 Cloud Run 构建 WebSocket 聊天服务

本教程介绍如何使用 WebSocket 创建具有多个聊天室的实时聊天服务，并通过持久性连接进行双向通信。通过 WebSocket，客户端和服务器可以互相推送消息，而无需轮询服务器获取更新。

虽然您可以将 Cloud Run 配置为使用会话亲和性，但这会提供尽力而为亲和性，这意味着任何新请求仍然可能会路由到其他实例。因此，聊天服务中的用户消息需要在所有实例之间同步，而不仅仅是在连接到一个实例的客户端之间同步。

设计概览

此示例聊天服务使用 Memorystore for Redis 实例在所有实例中存储和同步用户消息。Redis 使用发布/订阅机制（不要与产品 Cloud Pub/Sub 混淆）将数据推送到连接到任何实例的订阅客户端，从而无需进行 HTTP 轮询来获取更新。

但是，即使有推送更新，任何启动的实例也只会收到推送到容器的新消息。如需加载之前的消息，需要通过永久性存储解决方案存储和检索消息历史记录。此示例使用 Redis 的对象存储区传统功能来缓存和检索消息历史记录。

Redis 实例受具有访问权限控制的专用 IP 保护以免受互联网攻击，并且限制为 Redis 实例所在虚拟专用网中运行的服务。我们建议您使用直接 VPC 出站流量。

限制

• 本教程未介绍最终用户身份验证或会话缓存。如需详细了解最终用户身份验证，请参阅有关最终用户身份验证的 Cloud Run 教程。

• 本教程未实现数据库（例如 Firestore）以无限期地存储和检索聊天记录。

• 此示例服务还需要其他元素才能用于生产环境。 建议使用标准层级 Redis 实例，通过复制和自动故障切换提供高可用性。

目标

• 编写、构建和部署使用 WebSocket 的 Cloud Run 服务。

• 连接到 Memorystore for Redis 实例，以跨实例发布和订阅新消息。

• 使用直接 VPC 出站流量连接 Cloud Run 服务和 Memorystore。

费用

在本文档中，您将使用 Google Cloud的以下收费组件：

• Cloud Build
• Artifact Registry
• Memorystore
• Cloud Run

如需根据您的预计使用量来估算费用，请使用价格计算器。

新 Google Cloud 用户可能有资格申请免费试用。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Enable the Cloud Run, Memorystore for Redis, Artifact Registry, and Cloud Build APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

2. 安装并初始化 gcloud CLI。

所需的角色

如需获得完成本教程所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• Artifact Registry Reader (roles/artifactregistry.reader)
• Cloud Build Editor (roles/cloudbuild.builds.editor)
• Cloud Memorystore Redis Admin (roles/redis.admin)
• Cloud Run Admin (roles/run.admin)
• Create Service Accounts (roles/iam.serviceAccountCreator)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)
• Service Account Admin (roles/iam.serviceAccountAdmin)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

注意：IAM 基本角色也可以提供完成本教程所需的权限。您不应在生产环境中授予基本角色，但可以在开发或测试环境中授予这些角色。

设置 gcloud 默认值

如需为您的 Cloud Run 服务配置 gcloud 默认值，请执行以下操作：

1. 设置默认项目：

   gcloud config set project PROJECT_ID

   将 PROJECT_ID 替换为您在本教程中创建的项目的名称。

2. 为您选择的区域配置 gcloud：

   gcloud config set run/region REGION

   将 REGION 替换为您选择的受支持的 Cloud Run 区域。

Cloud Run 位置

Cloud Run 是区域级的，这意味着运行 Cloud Run 服务的基础架构位于特定区域，并且由 Google 代管，以便在该区域内的所有可用区以冗余方式提供。

选择用于运行 Cloud Run 服务的区域时，主要考虑该区域能否满足您的延迟时间、可用性或耐用性要求。通常，您可以选择距离用户最近的区域，但除此之外，您还应该考虑 Cloud Run 服务使用的其他 Google Cloud产品的位置。跨多个位置使用 Google Cloud 产品可能会影响服务的延迟时间和费用。

Cloud Run 可在以下区域使用：

基于层级 1 价格

• asia-east1（台湾）
• asia-northeast1（东京）
• asia-northeast2（大阪）
• asia-south1（印度孟买）
• europe-north1（芬兰） 二氧化碳排放量低
• europe-north2（斯德哥尔摩） 二氧化碳排放量低
• europe-southwest1（马德里） 二氧化碳排放量低
• europe-west1（比利时） 二氧化碳排放量低
• europe-west4（荷兰） 二氧化碳排放量低
• europe-west8（米兰）
• europe-west9（巴黎） 二氧化碳排放量低
• me-west1（特拉维夫）
• northamerica-south1（墨西哥）
• us-central1（爱荷华） 二氧化碳排放量低
• us-east1（南卡罗来纳）
• us-east4（北弗吉尼亚）
• us-east5（哥伦布）
• us-south1（达拉斯） 二氧化碳排放量低
• us-west1（俄勒冈） 二氧化碳排放量低

基于层级 2 价格

• africa-south1（约翰内斯堡）
• asia-east2（香港）
• asia-northeast3（韩国首尔）
• asia-southeast1（新加坡）
• asia-southeast2 （雅加达）
• asia-south2（印度德里）
• australia-southeast1（悉尼）
• australia-southeast2（墨尔本）
• europe-central2（波兰，华沙）
• europe-west10（柏林）
• europe-west12（都灵）
• europe-west2（英国伦敦） 二氧化碳排放量低
• europe-west3（德国法兰克福）
• europe-west6（瑞士苏黎世） 二氧化碳排放量低
• me-central1（多哈）
• me-central2（达曼）
• northamerica-northeast1（蒙特利尔） 二氧化碳排放量低
• northamerica-northeast2（多伦多） 二氧化碳排放量低
• southamerica-east1（巴西圣保罗） 二氧化碳排放量低
• southamerica-west1（智利圣地亚哥） 二氧化碳排放量低
• us-west2（洛杉矶）
• us-west3（盐湖城）
• us-west4（拉斯维加斯）

如果您已创建 Cloud Run 服务，可在Google Cloud 控制台的 Cloud Run 信息中心内查看区域。

确定

检索代码示例

要检索可用的代码示例，请执行以下操作：

1. 将示例代码库克隆到本地计算机：

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

2. 切换到包含 Cloud Run 示例代码的目录：

   Node.js

   cd nodejs-docs-samples/run/websockets/

了解代码

Socket.io 是一个可实现浏览器与服务器间实时双向通信的库。虽然 Socket.io 不是 WebSocket 实现，但它封装了功能以提供一个较简单的 API，为多个通信协议提供额外功能，例如更高的可靠性、自动重新连接以及广播到所有或部分客户端。

客户端集成

<script src="/socket.io/socket.io.js"></script>

客户端为每个连接实例化一个新的套接字实例。由于此示例是服务器端呈现的，因此无需定义服务器网址。套接字实例可以发出和监听事件。

// Initialize Socket.io
const socket = io('', {
  transports: ['websocket'],
});

// Emit "sendMessage" event with message
socket.emit('sendMessage', msg, error => {
  if (error) {
    console.error(error);
  } else {
    // Clear message
    $('#msg').val('');
  }
});

// Listen for new messages
socket.on('message', msg => {
  log(msg.user, msg.text);
});

// Listen for notifications
socket.on('notification', msg => {
  log(msg.title, msg.description);
});

// Listen connect event
socket.on('connect', () => {
  console.log('connected');
});

注意：对于不支持会话亲和性的多实例架构，Socket.io 必须仅使用 Websocket 传输。如果 Socket.io 回退到长轮询，它将在会话生命周期内发送多个 HTTP 请求。第一个请求建立“握手”，其中包含会话 ID 等重要信息。在第一个请求之后，请求可能会被路由到另一个实例，由于服务器不知道会话 ID，该实例将生成错误。

服务器端集成

在服务器端，Socket.io 服务器完成初始化，并连接到 HTTP 服务器。与客户端类似，Socket.io 服务器与客户端建立连接后，会为每个连接创建一个套接字实例，用于发出和监听消息。Socket.io 还提供了一个简单的界面，用于创建“聊天室”，即套接字可以加入和退出的任意通道。

// Initialize Socket.io
const server = require('http').Server(app);
const io = require('socket.io')(server);

const {createAdapter} = require('@socket.io/redis-adapter');
// Replace in-memory adapter with Redis
const subClient = redisClient.duplicate();
io.adapter(createAdapter(redisClient, subClient));
// Add error handlers
redisClient.on('error', err => {
  console.error(err.message);
});

subClient.on('error', err => {
  console.error(err.message);
});

// Listen for new connection
io.on('connection', socket => {
  // Add listener for "signin" event
  socket.on('signin', async ({user, room}, callback) => {
    try {
      // Record socket ID to user's name and chat room
      addUser(socket.id, user, room);
      // Call join to subscribe the socket to a given channel
      socket.join(room);
      // Emit notification event
      socket.in(room).emit('notification', {
        title: "Someone's here",
        description: `${user} just entered the room`,
      });
      // Retrieve room's message history or return null
      const messages = await getRoomFromCache(room);
      // Use the callback to respond with the room's message history
      // Callbacks are more commonly used for event listeners than promises
      callback(null, messages);
    } catch (err) {
      callback(err, null);
    }
  });

  // Add listener for "updateSocketId" event
  socket.on('updateSocketId', async ({user, room}) => {
    try {
      addUser(socket.id, user, room);
      socket.join(room);
    } catch (err) {
      console.error(err);
    }
  });

  // Add listener for "sendMessage" event
  socket.on('sendMessage', (message, callback) => {
    // Retrieve user's name and chat room  from socket ID
    const {user, room} = getUser(socket.id);
    if (room) {
      const msg = {user, text: message};
      // Push message to clients in chat room
      io.in(room).emit('message', msg);
      addMessageToCache(room, msg);
      callback();
    } else {
      callback('User session not found.');
    }
  });

  // Add listener for disconnection
  socket.on('disconnect', () => {
    // Remove socket ID from list
    const {user, room} = deleteUser(socket.id);
    if (user) {
      io.in(room).emit('notification', {
        title: 'Someone just left',
        description: `${user} just left the room`,
      });
    }
  });
});

Socket.io 还提供了一个 Redis 适配器，可以向所有客户端广播事件，无论是哪个服务器服务套接字。Socket.io 仅使用 Redis 的发布/订阅机制，不存储任何数据。

const {createAdapter} = require('@socket.io/redis-adapter');
// Replace in-memory adapter with Redis
const subClient = redisClient.duplicate();
io.adapter(createAdapter(redisClient, subClient));

Socket.io 的 Redis 适配器可以重复使用用于存储聊天室的消息记录的 Redis 客户端。每个容器都会创建一个与 Redis 实例的连接，而 Cloud Run 可以创建大量实例。这远低于 Redis 可以支持的 65,000 个连接。

注意：Cloud Run 容器生命周期不考虑出站请求，例如 Redis 连接；因此，与 Redis 的活跃连接不会阻止容器缩容。

重新连接

Cloud Run 的最长超时时间为 60 分钟。因此，您需要添加重新连接逻辑，以应对可能的超时情况。在某些情况下，Socket.io 会在断开连接或连接错误事件后自动尝试重新连接。无法保证客户端将重新连接到同一个实例。

// Listen for reconnect event
socket.io.on('reconnect', () => {
  console.log('reconnected');
  // Emit "updateSocketId" event to update the recorded socket ID with user and room
  socket.emit('updateSocketId', {user, room}, error => {
    if (error) {
      console.error(error);
    }
  });
});

// Add listener for "updateSocketId" event
socket.on('updateSocketId', async ({user, room}) => {
  try {
    addUser(socket.id, user, room);
    socket.join(room);
  } catch (err) {
    console.error(err);
  }
});

如果存在活动连接，实例将一直存在，直到所有请求关闭或超时为止。即使您使用 Cloud Run 会话亲和性，也可以将新请求负载均衡到活跃容器，从而允许容器缩容。如果您担心大量容器在流量高峰后继续存在，可以降低超时值上限，从而更频繁地清理未使用的套接字。

发布服务

1. 创建一个 Memorystore for Redis 实例：

   gcloud redis instances create INSTANCE_ID --size=1 --region=REGION

   替换以下内容：

   • INSTANCE_ID：实例的名称，例如 my-redis-instance。
   • REGION_ID：所有资源和服务的区域，例如 europe-west1。

   系统会自动为实例分配一个在默认服务网络范围内的 IP 地址范围。本教程使用 1GB 的内存用于本地缓存 Redis 实例中的消息。详细了解如何针对您的应用场景确定 Memorystore 实例的初始大小。

2. 使用 Redis 实例的授权网络的 IP 地址定义环境变量：

    export REDISHOST=$(gcloud redis instances describe INSTANCE_ID --region REGION --format "value(host)")

   注意：本教程使用 Redis 端口的默认值 6379。

3. 创建一个服务账号作为服务身份。默认情况下，该账号不具备除项目成员资格之外的任何特权。

   gcloud iam service-accounts create chat-identity
   gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:chat-identity@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/serviceusage.serviceUsageConsumer

4. 运行以下命令，查找 Redis 实例已获授权的 VPC 网络的名称：

     gcloud redis instances describe INSTANCE_ID --region REGION --format "value(authorizedNetwork)"
   

   替换以下内容：

   • INSTANCE_ID：实例的名称，例如 my-redis-instance。
   • REGION_ID：所有资源和服务的区域，例如 europe-west1。

   记下 VPC 网络名称。

5. 构建容器映像并部署到 Cloud Run：

   gcloud run deploy chat-app --source . \
       --allow-unauthenticated \
       --timeout 3600 \
       --service-account chat-identity \
       --network NETWORK \
       --subnet SUBNET \
       --update-env-vars REDISHOST=$REDISHOST

   替换以下内容：

   • NETWORK 是 Redis 实例所连接的已获授权的 VPC 网络的名称。
   • SUBNET 是您的子网的名称。 子网必须至少为 /26。直接 VPC 出站流量支持 IPv4 范围 RFC 1918、RFC 6598 和 E 类。

   在系统提示时通过响应 y 来响应任何提示，以安装所需 API。您只需为项目执行一次此操作。如果您尚未按照设置页面中的说明为其他提示设置默认值，请通过提供平台和区域来响应这些提示。 详细了解如何从源代码部署。

测试

如需试用完整服务，请执行以下操作：

1. 在浏览器中导航至上述部署步骤提供的网址。

2. 添加你的姓名和聊天室以登录。

3. 向聊天室发送消息！

成功：您构建了一个具有多个聊天室的实时聊天服务，该服务使用 WebSocket 维护持久性连接来进行双向通信。

如果您选择继续开发这些服务，请注意，它们已限制了 Identity and Access Management (IAM) 对 Google Cloud 其余服务的访问权限，并需要额外的 IAM 角色才能访问众多其他服务。

清理

为避免您的 Google Cloud 账号产生额外费用，请删除您在本教程中部署的所有资源。

删除项目

如果您为本教程创建了一个新项目，请删除项目。 如果您使用的是某个现有项目，并且需要保留此项目但不保留在本教程中所做的更改，请删除为本教程创建的资源。

为了避免产生费用，最简单的方法是删除您为本教程创建的项目。

要删除项目，请执行以下操作：

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

删除教程资源

1. 删除您在本教程中部署的 Cloud Run 服务。Cloud Run 服务在收到请求之前不会产生费用。

   如需删除 Cloud Run 服务，请运行以下命令：

   gcloud run services delete SERVICE-NAME

   将 SERVICE-NAME 替换为服务的名称。

   您还可以通过Google Cloud 控制台删除 Cloud Run 服务。

2. 移除您在教程设置过程中添加的 gcloud 默认区域配置：

    gcloud config unset run/region
   

3. 移除项目配置：

    gcloud config unset project
   

4. 删除在本教程中创建的其他 Google Cloud 资源：

   • 从 Artifact Registry 中删除服务容器映像（名称为 gcr.io/PROJECT_ID/chat-app）
   • 删除服务账号 chat-identity@PROJECT_ID.iam.gserviceaccount.com
   • 删除 Memorystore for Redis 实例

后续步骤

• 详细了解 Socket.io 的工作原理和更高级的用法。

• 深入了解使用 VPC 网络的直接 VPC 出站流量。

• 查看 Memorystore和在 Cloud Run 上使用 WebSocket 的最佳做法。