注意:此开发者网站正在向 developers.google.com/tag-platform 迁移,2021 年 9 月 30 日起将会进行重定向

手动设置指南

通过使用自动配置流程,只需点击几下,即可将代码植入服务器部署到 App Engine。如果您希望在其他环境中配置代码植入服务器,可以手动执行此操作。代码植入服务器是 Docker 映像内的一个 Node.js 服务器。

要手动配置代码植入服务器,您需要分别配置服务器端代码植入 (SST) 集群和预览服务器。SST 集群是所有请求去到代码植入服务器的入口点,并将负责处理请求,如服务器端代码植入简介中所述。要预览容器,需要使用预览服务器。

请参见图 1,了解代码植入服务器与预览服务器之间进行的数据互动。

代码植入服务器和预览服务器数据流示意图

图 1:代码植入服务器和预览服务器数据流示意图。

本指南介绍了如何完成以下操作:

  • 查看 Docker 映像的所有可用设置。
  • (可选)添加 BigQuery 凭据
  • 使用 SST Docker 映像手动配置预览服务器。
  • 使用 SST Docker 映像手动配置 SST 集群。
  • 验证预览服务器和 SST 集群的配置是否正确无误。

要运行本指南中的 Docker 命令,您必须首先在计算机上安装 Docker

查看 Docker 映像的所有可用设置

您可以在以下网址中找到代码植入服务器 Docker 映像:gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

代码植入服务器和预览服务器使用同一 Docker 映像,但各自的标记不同。在本部分中,我们将介绍如何查找可用于 Docker 映像的所有可用设置。

要查看所有可用设置,请使用 Docker 命令行工具运行以下命令:

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable /bin/bash -c "node server_bin.js --help"

(可选)添加 BigQuery 凭据

要在 Google Cloud 外部使用 BigQuery API,您必须提供有权写入 BigQuery 表的服务帐号凭据。

  1. 按照本指南创建具有 BigQuery Data Editor 角色的服务帐号,然后导出文件名为 local_service_account_key.json 的 JSON 凭据。
  2. 将此 JSON 凭据装载到可供映像访问的卷中。通过使用 docker run,您可以指定 -v local_service_account_key.json:/app/service_account_key.json,将凭据装载到映像中。
  3. GOOGLE_APPLICATION_CREDENTIALS 环境变量指向此凭据。
  4. (可选)在 GOOGLE_CLOUD_PROJECT 环境变量中指定您的 Google Cloud 项目 ID,以便代码植入服务器隐式选择相应项目。
  5. 运行服务器。以下命令会运行包含凭据的代码植入服务器:

    docker run -v local_service_account_key.json:/app/service_account_key.json \
    -p 8080:8080 \
    -e GOOGLE_APPLICATION_CREDENTIALS='/app/service_account_key.json' \
    -e GOOGLE_CLOUD_PROJECT='<your project id>' \
    -e CONTAINER_CONFIG='<config string>' \
    gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable
    

您可以通过多种不同的方式装载凭据,具体取决于代码植入服务器部署到的系统。例如,KubernetesDocker Swarm 提供了 Secret 管理指南。如需了解详情,请参阅相应系统的指南。

请务必遵循最佳做法来保护您的凭据。

手动配置预览服务器

通过预览服务器,您可以预览服务器容器。要运行预览服务器,请运行 Docker 映像,将以下环境变量传递到 Docker 环境。

必需设置

  • CONTAINER_CONFIG - 服务器容器的配置字符串。在跟踪代码管理器中,转到服务器容器工作区,然后点击页面右上角的容器 ID。点击手动配置代码植入服务器,找到容器配置值。

  • RUN_AS_PREVIEW_SERVER - 将此项设置为 true,以将服务器配置为预览服务器。

使用 Docker 命令行工具的示例

要在本地配置预览服务器,请运行以下命令:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e RUN_AS_PREVIEW_SERVER=true gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

您应该能看到向 http://localhost:8080/healthz 发出的请求返回的 200 响应。(可选)使用 PORT 环境变量更改端口。

最佳做法

  • 您必须正好部署 1 个预览服务器。请勿为 1 个以上的实例配置自动扩缩。
  • 使用 Docker 设置预览服务器后,请将 HTTPS 网址配置为指向预览服务器。这是设置 SST 集群的必要条件。

手动配置服务器端代码植入集群

SST 集群用作入口点,代理去到预览服务器的预览请求,并负责处理所有其他请求,如服务器端代码植入简介中所述。您可以将以下必需设置用于代码植入服务器 Docker 映像,以在支持 Docker 的任何环境中配置 SST 集群。

必需设置

  • CONTAINER_CONFIG - 服务器容器的配置字符串。在跟踪代码管理器中,转到服务器容器工作区,然后点击页面右上角的容器 ID。点击手动配置代码植入服务器,找到容器配置值。

  • PREVIEW_SERVER_URL - 预览服务器的 HTTPS 网址。此设置应仅用于配置代码植入服务器,配置预览服务器时不需要使用此设置。如需了解如何设置预览服务器,请参阅上一部分

使用 Docker 命令行工具的示例

要在本地配置单个代码植入服务器,请运行以下命令:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e PREVIEW_SERVER_URL='<HTTPS preview server url>' gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

您应该会看到向 http://localhost:8080/healthz 发出的请求返回的 200 响应。(可选)使用 PORT 环境变量更改端口。

最佳做法

  • 服务器端代码植入服务器既可以配置为单个服务器,也可以配置为集群。我们建议您将其配置为集群,以便获得更出色的可用性、可扩缩性和性能。请注意,配置为集群时,必须使用相同的 CONTAINER_CONFIGPREVIEW_SERVER_URL 环境变量配置每个服务器实例。
  • 确保将 SST 集群部署指向您网站中的新子网域,该子网域应不同于您的应用处理流量所在的子网域。例如,如果您的应用在 example.com 上处理网站流量,请为您的代码植入服务器使用 analytics.example.com 等子网域。
  • 使用 Docker 设置 SST 集群后,请将 HTTPS 网址配置为指向 SST 集群。
  • 务必定期重启服务器,以确保您的服务器为 SST 安装了最新的代码更新。否则,可能会导致 SST 的新功能不兼容。要确定何时需要重启服务器,一种方法是设置活跃性检查,下文会对此进行说明。另请注意,即使不重启服务器,针对服务器容器的所有已发布更新仍将应用。
  • 利用代码植入服务器上的现有 /healthz 端点(例如,https://analytics.example.com/healthz)设置活跃性检查。如果响应为运行状况不佳,则表示应重启服务器。

验证

配置代码植入服务器网址

依次转到管理 > 容器设置下的服务器端跟踪代码管理器容器。将 SST 集群的网址输入到代码植入服务器网址字段,然后点击保存

通过预览模式进行验证

在跟踪代码管理器工作区中,点击预览预览容器,然后查看预览页面是否成功加载。在另一个浏览器标签页中,转到代码植入服务器网址上的任意路径。如果预览页面显示已发送的请求,则表示所有设置都正确无误。