手動設定指南

透過自動佈建流程，您只要按幾下滑鼠，就能將標記伺服器部署至 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 資料編輯者角色的服務帳戶，或是取得 Firestore 存取權的 Cloud Datastore 使用者角色的服務帳戶，並使用檔案名稱 (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

視標記伺服器部署的目標系統而定，掛接憑證的方式可能會有所不同。例如 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 叢集可做為進入點，Proxy 預覽要求至預覽伺服器，並按照「伺服器端代碼簡介」一文所述的方式處理所有其他要求。請使用以下必要設定與標記伺服器 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 環境變數進行設定。
  • 請務必將 SST 叢集部署作業指向網站上新的子網域，該子網域與提供應用程式的子網域不同。舉例來說，如果您的應用程式透過 example.com 提供網路流量，請使用子網域 (如 analytics.example.com) 做為標記伺服器。
  • 使用 Docker 設定 SST 叢集後，請將 HTTPS 網址設定為指向 SST 叢集。
  • 請務必定期重新啟動伺服器，確保伺服器能取得最新的 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. 在「Summary」(摘要) 中選取「Console」(控制台) 分頁標籤，確認沒有任何訊息要求您更新標記伺服器。

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