本文档介绍了如何将 Spanner Omni 部署从较低版本升级到较高版本。
Spanner Omni 使用异步、分阶段发布状态机,有助于确保安全升级,而不会中断服务。分阶段升级可让您执行以下操作:
- 应用数据库架构更新。
- 在滚动重启期间验证二进制文件兼容性。
- 如果您在最终确定之前检测到错误,请回滚到旧版本。
支持的升级路径
您只能将 LTS 版本更新到下一个 LTS 版本。更新到较新的 LTS 版本时,您无法跳过版本。
如果您从一个短期支持 (STS) 版本升级到另一个 STS 版本,并且两个版本的发布日期之间没有 LTS 版本,则可以跳过一个版本。
如需了解详情,请参阅版本支持政策。
升级工作流
Spanner Omni 升级过程包含多个连续阶段:
- 架构阶段:通过使用目标二进制文件版本运行内部数据库架构迁移来准备部署。架构迁移无法回滚,但它们向后兼容早期的二进制文件版本。
- 二进制文件阶段:使用滚动重启更新部署中所有服务器上的服务器二进制文件或容器映像。如果您检测到错误,可以在最终确定开始之前的任何时间点将二进制文件或容器映像回滚到早期版本。
- 启用功能阶段:启用版本兼容的功能,并在您升级所有服务器上的二进制文件后启动。如果升级不包含版本兼容的功能,则此阶段可能不适用;如果功能相互依赖,则可能需要多轮升级。对于支持回滚的可选阶段,您可以使用 Spanner Omni CLI 发起回滚。
- 完成阶段:完成发布,锁定目标版本。最终确定阶段开始后,将无法回滚。
准备工作
在升级 Spanner Omni 部署之前,请确保您满足以下前提条件:
- 您有一个正在运行的 Spanner Omni 部署。如需了解详情,请参阅在 Kubernetes 上创建部署或在虚拟机上创建部署。
- 您已下载并安装 Spanner Omni CLI。
- 您可以通过运行 CLI 命令的机器对所有 Spanner Omni 内部端口(TCP 15000 到 15027)进行网络访问,也可以对部署端点进行网络访问。
- 如果您的部署使用传输层安全协议 (TLS) 或双向 TLS (mTLS) 加密,请确保您的基本目录中的
BASE_DIR/tls下或集群中装载了有效证书。 - 您已确定目标版本:
- 对于虚拟机部署:下载目标版本软件包
spanner-omni-server-TARGET_VERSION.tar.gz。 - 对于 Helm 和 Kubernetes 部署:在 Artifact Registry 中标识目标容器映像,例如
us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION。
- 对于虚拟机部署:下载目标版本软件包
- Spanner Omni 部署的管理员应安排维护窗口进行升级。您的组织应避免在升级维护窗口期间进行部署。
第 1 步:准备架构升级
如需启动升级,请准备目标版本的发布。在此阶段,Spanner Omni 会运行内部数据库架构迁移,而现有服务器会继续处理流量。
选择您的部署环境对应的标签页:
虚拟机
在虚拟机部署中,下载并解压缩目标版本软件包,然后使用解压缩的 Spanner Omni CLI 启动发布准备工作。
登录到部署中具有对所有 Spanner Omni 内部端口(TCP 15000 到 15027)的网络访问权限的服务器。
下载并解压缩目标版本软件包:
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR替换以下内容:
TARGET_VERSION:要升级到的目标版本,例如2026.r5。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/spannerCLI 和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.r5。
独立 Kubernetes
如果您在不使用 Helm 的情况下在 Kubernetes 上部署 Spanner Omni,请运行独立的 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.r5。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 步:更新二进制文件或容器映像
架构阶段成功完成后,将部署中所有节点上运行的服务器二进制文件或容器映像更新为目标版本。
选择您的部署环境对应的标签页:
虚拟机
在虚拟机部署中,使用滚动重启在所有虚拟机上更新 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 30mHelm 会使用升级前钩子自动执行第 1 阶段,然后启动 StatefulSet (
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 chart 版本,例如1.1.0。NAMESPACE:部署的 Kubernetes 命名空间,例如spanner-ns。TARGET_VERSION:目标容器映像标记,例如2026.r5。
独立 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 中执行滚动重启,以恢复到较早(来源)版本。
虚拟机
在虚拟机部署中,在所有虚拟机上回滚 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 chart 版本,例如1.1.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 部署或扩缩虚拟机部署。
- 了解 Monitoring 概览。