手動設定指南

自動佈建流程可用於只需點選幾下，即可將標記伺服器部署至 Cloud Run。如要在其他環境中佈建標記伺服器，您可以手動進行。標記伺服器是 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 server_bin.js --help

(選用) 加入 Google Cloud 憑證

如要在 Google Cloud 以外使用 BigQuery 或 Firestore API，您必須提供已獲授權存取這些資源的服務帳戶憑證。

  1. 請按照這份指南建立服務帳戶，並授予該帳戶 BigQuery 資料編輯者角色 (BigQuery 存取權) 或 Cloud Datastore 使用者角色 (Firestore 存取權)，然後匯出 JSON 憑證，檔案名稱為 local_service_account_key.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

視代碼標記伺服器部署至哪個系統而定，掛載憑證的方式可能有所不同。舉例來說，Kubernetes 和 Docker Swarm 都提供密鑰管理指南。詳情請參閱個別系統的指南。

請務必遵循最佳做法保護您的憑證。

手動佈建預覽伺服器

預覽伺服器可讓您預覽伺服器容器。如要執行預覽伺服器，請將下列環境變數傳遞至 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 叢集的必要條件。
  • 負載平衡器或 CDN 的逾時時間必須超過 20 秒，否則預覽模式將無法正常運作。

手動佈建伺服器端標記叢集

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_CONFIG 和 PREVIEW_SERVER_URL 環境變數進行設定。
  • 請務必在相同來源中代管標記伺服器 (最佳做法)，或將其設為目前網站的子網域。舉例來說，如果您的應用程式在 example.com 提供網路流量，請為標記伺服器使用 example.com/analytics 這類路徑。進一步瞭解自訂網域設定。
  • 使用 Docker 設定 SST 叢集後，請設定指向 SST 叢集的 HTTPS 網址。
  • 請務必定期重新啟動伺服器，確保您的伺服器能收到最新的 SST 程式碼更新。否則可能會導致新的 SST 功能不相容。如要瞭解何時需要重新啟動伺服器，可以設定有效性檢查，詳情請參閱下文。另外請注意，即使未重新啟動，伺服器容器的任何已發布更新仍會套用。
  • 請在標記伺服器上使用現有的 /healthz 端點 (例如 https://analytics.example.com/healthz) 設定活動檢查。非正常回應表示應重新啟動伺服器。
  • Docker 容器包含預設的健康狀態檢查指令 HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]，可定期查詢 /healthz 端點。如果您依賴 Docker 健康檢查，可以按照 Docker 操作說明變更設定。
  • 如果預覽伺服器和標記伺服器位於相同來源，請將預覽伺服器放在與標記伺服器不同的路徑上。指定包含路徑的 PREVIEW_SERVER_URL。
  • 已佈建的伺服器最多應有 1 個 vCPU。額外的 vCPU 不會被使用，並會對自動調度資源功能造成負面影響。

驗證

設定伺服器容器網址

在代碼管理工具中，前往伺服器容器。在「管理」下方，依序點選「容器設定」 >「容器設定」，將代碼伺服器的網址貼到「伺服器容器網址」欄位，然後按一下「儲存」。

透過預覽模式驗證

在代碼管理工具工作區中，按一下「預覽」即可預覽容器，並查看預覽頁面是否載入。在另一個瀏覽器分頁中，前往伺服器容器網址的任何路徑。如果預覽頁面顯示已傳送的要求，表示一切設定都正確無誤。

如果您將多個子網域對應至單一標記伺服器，且想要在各個子網域上預覽，請在「Admin」(管理員) >「Container Settings」(容器設定) 下方新增其他「伺服器容器網址」。如果提供多個網址，所有網址路徑都必須相符 (網域名稱後方的資訊字串)。舉例來說，您可以預覽 example.com/abc 和 example2.com/abc，但無法預覽 example.com/abc 和 example2.com/def。如果新增多個網址，「Preview」按鈕旁邊會顯示圖示，讓您選取要預覽的網址。

更新標記伺服器版本

gtm-cloud-image 映像檔包含 Node.js 和標記伺服器運作所需的程式庫。Docker 映像檔會定期更新，以修正安全性問題並加入新功能。建議您至少在每個主要版本發布時更新標記伺服器 (例如從 1.x.x 升級至 2.x.x)。

如要更新 Docker 映像檔，請按照下列步驟操作：

  1. 擷取 gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable 的目前圖片版本。
  2. 使用與先前部署相同的設定部署伺服器。
  3. 更新單一預覽伺服器和叢集中的所有代碼伺服器。
  4. 關閉所有舊的伺服器。

如要確認更新是否成功，請按照下列步驟操作：

  1. 在伺服器容器中，按一下「Preview」按鈕，即可啟動新的偵錯工作階段，並在另一個分頁中傳送要求。
  2. 在「摘要」中，選取「控制台」分頁標籤，確認沒有要求您更新標記伺服器的訊息。

在成功更新伺服器後，代碼管理工具最多可能會在一天內顯示訊息，要求您更新標記伺服器。不過，預覽頁面會顯示最新的代碼標記伺服器版本訊息。