手動設定指南

只要按幾下滑鼠，即可透過自動佈建流程，將代碼伺服器部署至 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/healthy 的要求傳回 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/healthy 的要求傳回 200 回應。 您也可以使用 PORT 環境變數變更連接埠。

最佳做法

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

驗證

設定伺服器容器網址

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

透過預覽模式驗證

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

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

更新標記伺服器版本

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. 在伺服器容器中，按一下「預覽」按鈕，啟動新的偵錯工作階段，並在另一個分頁中傳送要求。
  2. 在「摘要」中，選取「控制台」分頁標籤，確認沒有要求更新代碼伺服器的訊息。

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