Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

升級 Spanner Omni 部署作業

本文說明如何將 Spanner Omni 部署項目從舊版升級至新版。

Spanner Omni 使用非同步分階段推出狀態機，確保升級安全無虞，不會造成服務中斷。分階段升級可讓您執行下列操作：

套用資料庫結構定義更新。
在輪流重新啟動期間驗證二進位檔相容性。
如果在完成前發現錯誤，請復原至先前版本。

升級工作流程

Spanner Omni 升級程序包含多個連續階段：

架構階段：使用目標二進位版本執行內部資料庫架構遷移作業，為部署作業做準備。結構定義遷移作業無法復原，但可與舊版二進位檔回溯相容。
二進位檔階段：使用輪流重新啟動的方式，更新部署作業中所有伺服器的伺服器二進位檔或容器映像檔。如果偵測到錯誤，您可以在最終程序開始前，隨時將二進位檔或容器映像檔復原為先前的版本。
啟用功能階段：啟用與版本相容的功能，並在升級所有伺服器上的二進位檔後開始。如果升級不包含版本相容功能，則可能不適用這個階段；如果功能相互依附，則可能需要多輪升級。對於支援回溯的選用階段，您可以使用 Spanner Omni CLI 啟動回溯。
完成階段：完成推出作業，封存目標版本。最終階段開始後，就無法復原。

事前準備

升級 Spanner Omni 部署作業前，請確認符合下列先決條件：

您已部署並執行 Spanner Omni。詳情請參閱「在 Kubernetes 上建立部署作業」或「在 VM 上建立部署作業」。
您已下載並安裝 Spanner Omni CLI。
您可從執行 CLI 指令的機器，透過網路存取所有 Spanner Omni 內部通訊埠 (TCP 15000 至 15027)，或透過網路存取部署端點。
如果部署作業使用傳輸層安全標準 (TLS) 或相互 TLS (mTLS) 加密，請確保基本目錄 BASE_DIR/tls 下有有效憑證，或憑證已掛接至叢集。
您已找出目標版本：
- 如果是 VM 部署作業，請下載目標版本套件 spanner-omni-server-TARGET_VERSION.tar.gz。
- 如果是 Helm 和 Kubernetes 部署作業，請在 Artifact Registry 中找出目標容器映像檔，例如 us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION。

步驟 1：準備升級結構定義

如要啟動升級程序，請準備目標版本的推出作業。在這個階段，Spanner Omni 會執行內部資料庫結構定義遷移作業，現有伺服器則會繼續處理流量。

選取部署環境的分頁標籤：

VM

在 VM 部署作業中，請下載並解壓縮目標版本套件，然後使用解壓縮的 Spanner Omni CLI 啟動推出準備作業。

登入部署中的伺服器，該伺服器必須具有所有 Spanner Omni 內部通訊埠 (TCP 15000 到 15027) 的網路存取權。
下載並解壓縮目標發布套件：
```
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR
```
更改下列內容：
- TARGET_VERSION：要升級的目標版本，例如 2026.r4-lts。
- EXTRACT_DIR：解壓縮發布套件的目錄，例如 /tmp/target_spanner/。
執行從解壓縮的 CLI 擷取的 rollouts prepare 指令，開始準備推出作業：
```
EXTRACT_DIR/bin/spanner deployment rollouts prepare \
  --target-server-binary=EXTRACT_DIR/bin/spanner_server \
  --root-server=ROOT_SERVERS \
  --base-dir=BASE_DIR
```
更改下列內容：
- EXTRACT_DIR：包含目標 bin/spanner CLI 和 bin/spanner_server 二進位檔的解壓縮目錄。
- ROOT_SERVERS：一個根伺服器端點，或以半形逗號分隔的多個根伺服器清單，例如 localhost:15000 或 server1:15000,server2:15000,server3:15000。
- BASE_DIR：Spanner Omni 的基本目錄，例如 /spanner。
- 如果部署作業使用 TLS 或 mTLS 加密，請附加 --ca-certificate-file=CA_CERT_FILE 和 --client-certificate-directory=CERT_DIR，指向有效憑證。

Helm

在 Helm 部署作業中，準備結構定義時，請視您執行的是多伺服器或單一伺服器部署作業而定：

多伺服器部署 (高可用性 / 正式環境)： Helm 會自動處理結構定義準備作業。在「步驟 3：更新二進位檔或容器映像檔」中執行 helm upgrade 時，Helm 資訊套件會觸發 spanner-prepare-for-upgrade 前升級掛鉤工作，在更新任何 StatefulSet 之前執行結構定義遷移作業。直接前往「步驟 2：確認推出更新的目前狀態」。
單一伺服器部署 (deployment.singleServer=true)：由於單一伺服器模式會將內部服務嚴格繫結至迴路介面 (127.0.0.1)，因此網路作業無法連上這些服務。使用暫時性偵錯容器和目標容器映像檔，在執行中的 Pod 內在本機執行結構定義遷移作業：
```
kubectl debug pod/POD_NAME -n NAMESPACE \
  --image=us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION \
  --container=upgrade-prepare -i \
  -- /google/spanner/bin/spanner_server prepare_for_upgrade --root_server=127.0.0.1
```
更改下列內容：
- POD_NAME：伺服器 Pod 的名稱，例如 spanner-a-0。
- NAMESPACE：部署作業的 Kubernetes 命名空間，例如 spanner-ns。
- TARGET_VERSION：要升級的目標版本，例如 2026.r4-lts。

獨立 Kubernetes

如果是在 Kubernetes 上部署 Spanner Omni，但未使用 Helm，請執行獨立的 Kubernetes 批次工作，針對使用目標映像檔的現用根伺服器執行結構定義遷移作業。

建立名為 spanner-prepare-upgrade.yaml 的檔案，並加入下列工作資訊清單：

apiVersion: batch/v1
kind: Job
metadata:
  namespace: NAMESPACE
  name: spanner-prepare-for-upgrade
spec:
  # Fail fast on the first error to stop the rollout immediately.
  backoffLimit: 0
  template:
    metadata:
      namespace: NAMESPACE
    spec:
      restartPolicy: Never
      containers:
        - name: spanner-upgrade
          image: us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION
          command: ["/google/spanner/bin/spanner_server"]
          args:
            - "prepare_for_upgrade"
            - "--root_server=ROOT_SERVER_ENDPOINT"
          volumeMounts:
            - name: tls-certs
              mountPath: "/spanner/tls"
              readOnly: true
            - name: spanner-data
              mountPath: /spanner
      volumes:
        - name: tls-certs
          secret:
            secretName: tls-certs
            optional: true
            defaultMode: 256
        - name: spanner-data
          emptyDir: {}

更改下列內容：

NAMESPACE：部署作業的 Kubernetes 命名空間，例如 spanner-ns。
TARGET_VERSION：要升級的目標版本，例如 2026.r4-lts。
ROOT_SERVER_ENDPOINT：有效根伺服器 Pod 的端點，例如 spanner-a-0.pod.spanner-ns。

套用資訊清單，執行準備作業：

kubectl apply -f spanner-prepare-upgrade.yaml

步驟 2：確認推出作業的有效狀態

準備步驟完成後，請確認已建立發布作業，並檢查其階段狀態。

列出有效的推出作業，以擷取推出作業 ID：

spanner deployment rollouts list \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

將 DEPLOYMENT_ENDPOINT 替換為部署作業中伺服器的端點，例如 localhost:15000 或 spanner-a-0.pod.spanner-ns:15000。

輸出結果會與下列內容相似：

NAME                         STATE          TARGET_VERSION    START_TIME                     END_TIME
rollouts/1788942172101727    IN_PROGRESS    2026.r3-beta      2026-09-09T08:22:52.101727Z    -

檢查詳細的推出階段狀態：

spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

更改下列內容：

ROLLOUT_ID：推出作業的數字 ID，例如 1788942172101727。
DEPLOYMENT_ENDPOINT：部署作業中伺服器的端點。

輸出結果會與下列內容相似：

name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: IN_PROGRESS
    - name: rollouts/1788942172101727/phases/finalize
      state: PENDING
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta

請先確認下列階段狀態，再繼續操作：

schema：顯示 SUCCEEDED，表示內部資料庫結構定義遷移作業已完成。
binary：顯示 IN_PROGRESS，表示推出引擎已準備好進行二進位更新。
finalize：顯示 PENDING，等待二進位階段完成。

步驟 3：更新二進位檔或容器映像檔

架構階段成功後，請在部署作業的所有節點中，將執行中的伺服器二進位檔或容器映像檔更新為目標版本。

選取部署環境的分頁標籤：

VM

在 VM 部署作業中，使用輪流重新啟動的方式，更新所有 VM 中的 spanner_server 二進位檔：

一次更新一個故障域或可用區：在多可用區部署中，更新一個可用區的伺服器，並確認穩定性，再更新下一個可用區。確保 Paxos 共識群組維持法定人數。
逐步重新啟動：同時重新啟動的伺服器不得超過 5%，以維持持續查詢的可用性。
確認伺服器健康狀態：請確保所有重新啟動的伺服器都正常運作，並已重新加入叢集，再更新下一個故障域。

Helm

在 Helm 部署作業中，請執行 helm upgrade，同時傳遞 --reuse-values 或提供值檔案，保留現有的設定值：

多伺服器部署 (正式環境 / 高可用性)：

helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version CHART_VERSION \
  -n NAMESPACE \
  --reuse-values \
  --set image.tag=TARGET_VERSION \
  --timeout 30m

Helm 會使用升級前掛鉤自動執行第 1 階段，然後依序啟動 StatefulSets 的區域滾動式更新 (rollout.staggered: true)。

單一伺服器部署 (deployment.singleServer=true)：

明確傳遞 --set skipPrepareUpgrade=true，讓 Helm 略過升級前勾點工作，因為您已在本機完成第 1 階段：

helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version CHART_VERSION \
  -n NAMESPACE \
  --reuse-values \
  --set skipPrepareUpgrade=true \
  --set image.tag=TARGET_VERSION \
  --timeout 30m

更改下列內容：

CHART_VERSION：目標 Helm 資訊套件版本，例如 1.0.0。
NAMESPACE：部署作業的 Kubernetes 命名空間，例如 spanner-ns。
TARGET_VERSION：目標容器映像檔標記，例如 2026.r4-lts。

獨立 Kubernetes

在沒有 Helm 的自訂 Kubernetes 部署作業中，請在 StatefulSet 或 Deployment 規格中，將容器映像檔更新為 TARGET_VERSION。

在故障域中執行滾動式更新，一次更新一個可用區，並同時重新啟動不超過 5% 的 Pod，以保留仲裁。

步驟 4：驗證二進位階段進度

將所有伺服器或 Pod 更新至目標版本後，請確認二進位階段已順利完成。

查看推出階段狀態：

spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

更改下列內容：

ROLLOUT_ID：推出作業的數字 ID，例如 1788942172101727。
DEPLOYMENT_ENDPOINT：部署作業中伺服器的端點。

輸出結果會與下列內容相似：

name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/finalize
      state: PENDING
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta

確認 binary 階段狀態變更為 SUCCEEDED。在所有剩餘階段完成前，整體推出狀態仍為 IN_PROGRESS。phases/binary轉換為 SUCCEEDED 後，部署作業即可繼續進行其餘階段。

步驟 5：排定並執行其餘階段

二進位檔階段成功後，請確認部署作業穩定無虞，然後排定其餘階段的推出時間，直到 finalize 階段為止。finalize 階段 (推出作業的最後一個階段) 會在整個部署作業中封存新版本。只要指定 --deployment-endpoint，即可從任何可存取 Spanner Omni 服務的機器執行這項指令。

針對 PENDING 狀態中的每個剩餘階段 (例如 enable_features (如有)，然後是 finalize)，請完成下列步驟：

排定階段：

spanner deployment rollouts phases schedule PHASE_NAME \
  --rollout=ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

更改下列內容：

PHASE_NAME：要排程的階段名稱，例如 finalize 或 enable_features。
ROLLOUT_ID：推出作業的數字 ID，例如 1788942172101727。
DEPLOYMENT_ENDPOINT：部署作業中伺服器的端點。

輸出內容會指出排定的階段為 IN_PROGRESS：

name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/finalize
      state: IN_PROGRESS
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta

等待階段成功，並驗證其狀態：

spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

針對每個剩餘階段重複執行這些步驟，直到完成所有階段 (包括 finalize)。

最後一個階段 (finalize) 完成後，所有階段和整體推出狀態都會轉換為 SUCCEEDED：

endTime: "2026-09-09T08:45:43.949702Z"
name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/finalize
      startTime: "2026-09-09T08:45:43.898111Z"
      state: SUCCEEDED
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: SUCCEEDED
targetVersion: 2026.r3-beta

在推出作業清單中確認「已完成」狀態：

spanner deployment rollouts list \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

輸出內容會確認推出作業已完成：

NAME                         STATE        TARGET_VERSION    START_TIME                     END_TIME
rollouts/1788942172101727    SUCCEEDED    2026.r3-beta      2026-09-09T08:22:52.101727Z    2026-09-09T08:45:43.949702Z

復原升級

如果在升級期間遇到問題，是否可以復原升級作業取決於目前的推出階段：

結構定義階段：無法復原。準備期間套用的內部資料庫結構定義遷移作業只能向前遷移，無法還原。不過，結構定義遷移作業可與來源版本回溯相容，因此舊版伺服器二進位檔仍可正常運作。
二進位階段：在開始最終程序前，隨時可以復原為舊版。詳情請參閱「復原二進位檔或容器映像檔」。
選用推出階段：對於支援自動復原的選用階段 (例如啟用功能)，請使用 Spanner Omni CLI 啟動復原程序。
最終階段：無法回溯。最終化程序開始後，目標版本就會在部署作業中永久封存，無法再進行回溯。

復原二進位檔或容器映像檔

如要在最終階段開始前復原二進位檔階段，請在所有伺服器或 Pod 中執行滾動式重新啟動，以還原先前的 (來源) 版本。

VM

在 VM 部署作業中，將所有 VM 的 spanner_server 二進位檔復原：

將較早的 spanner_server 二進位版本部署至主機。
在故障網域中逐步重新啟動伺服器，一次更新一個區域，且同時重新啟動的伺服器不得超過 5%，以保留 Paxos 仲裁。
確認所有重新啟動的伺服器都正常運作，且已重新加入叢集，再前往下一個故障域。

Helm

在 Helm 部署作業中，將容器映像檔標記更新回先前的版本：

helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version CHART_VERSION \
  -n NAMESPACE \
  --reuse-values \
  --set image.tag=SOURCE_VERSION \
  --timeout 30m

更改下列內容：

CHART_VERSION：Helm 範本版本，例如 1.0.0。
NAMESPACE：部署作業的 Kubernetes 命名空間，例如 spanner-ns。
SOURCE_VERSION：要還原的舊版容器映像檔標記，例如 2026.r2-beta.3。

獨立 Kubernetes

在沒有 Helm 的自訂 Kubernetes 部署作業中，請將 StatefulSet 或 Deployment 規格中的容器映像檔更新回 SOURCE_VERSION。

在故障域中執行滾動式更新，一次更新一個可用區，並同時重新啟動不超過 5% 的 Pod，以保留仲裁。

復原選用的推出階段

對於支援復原的選用推出階段 (例如啟用功能階段)，請執行 rollouts rollback 指令來啟動復原程序：

spanner deployment rollouts rollback ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

更改下列內容：

ROLLOUT_ID：推出作業的數值 ID。
DEPLOYMENT_ENDPOINT：部署作業中伺服器的端點。

後續步驟

瞭解如何維護部署作業。
瞭解如何調度 Kubernetes Deployment 的資源或調度 VM Deployment 的資源。
瞭解 Monitoring 總覽。

升級 Spanner Omni 部署作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

升級工作流程

事前準備

步驟 1：準備升級結構定義

VM

Helm

獨立 Kubernetes

步驟 2：確認推出作業的有效狀態

步驟 3：更新二進位檔或容器映像檔

VM

Helm

獨立 Kubernetes

步驟 4：驗證二進位階段進度

步驟 5：排定並執行其餘階段

復原升級

復原二進位檔或容器映像檔

VM

Helm

獨立 Kubernetes

復原選用的推出階段

後續步驟

升級 Spanner Omni 部署作業