ZenML Pro 组件升级与更新完全指南：Control Plane 与 Workspace Server 的升级、回滚与验证-迪斯科星球

ZenML Pro 组件升级与更新完全指南：Control Plane 与 Workspace Server 的升级、回滚与验证

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml

本指南以 upgrades-updates.md 及其分册 upgrades-control-plane.md 与 upgrades-workspace-server.md 为核心，系统讲解 ZenML Pro 在 SaaS、Hybrid、Self-hosted 三种部署形态下的组件升级方法。读完本文，你将掌握：升级前如何检查版本与备份、Control Plane 与 Workspace Server 的完整升级命令、失败时的回滚流程、升级后的健康验证清单，以及数据库迁移 Job 在 Helm 层面的底层实现原理。

为什么升级顺序如此重要：先 Control Plane，再 Workspace Server

ZenML Pro 的架构由两个核心服务组成（详见 system-architecture.md）：

Control Plane：组织级管理平面，负责身份认证（SSO、OIDC、社交登录）、RBAC 权限管理、组织与团队管理、Workspace 注册与版本协调。每个组织只有一个 Control Plane。
Workspace Server：工作区服务，负责存储流水线元数据、提供 REST API、管理栈与组件实体、签发短期 Service Connector 令牌，并可借助 Workload Manager 在 Kubernetes 集群中创建临时 Runner Pod 以执行从仪表盘触发的流水线。一个 Control Plane 下可以有一个或多个 Workspace Server。

两者之间存在版本兼容约束：新版 Control Plane 可能要求 Workspace Server 不低于某个最低版本。因此官方在文档开头用醒目的警告框强调：

Always upgrade the Control Plane first, then upgrade Workspace Servers.（务必先升级 Control Plane，再升级 Workspace Server。）

按照先 Control Plane、后 Workspace Server 的顺序执行升级，可以保证组件之间的协议与 API 兼容，避免因版本不匹配导致的身份校验失败、元数据读写异常等问题。

升级前的准备工作

无论升级哪个组件，都应当先完成三件事：确认目标版本、检查发布说明、备份关键资产。

检查版本与发布说明

Control Plane（ZenML Pro）：可在 ZenML Pro 的 Helm 仓库中查看可用版本（helm/Chart.yaml 中 OSS 版本信息可作为对照参考）。
Workspace Server（ZenML OSS）：查看 ZenML 的 Helm 仓库中可用版本，并审阅 GitHub Releases 页面上的发布说明，重点关注breaking changes（破坏性变更）与数据库迁移相关说明。

备份清单

在任何升级操作之前，逐项确认以下备份已经完成：

数据库备份（Database backup）：导出当前数据库。这是升级失败后恢复数据的最后防线。
values.yaml 文件（Helm values）：保存当前生效的 Helm values 副本，用于--reuse-values之外的比对与回滚。
TLS 证书（TLS certificates）：确保证书与私钥已被妥善备份，避免升级过程中 Secret 被重建导致证书丢失。

数据库迁移注意事项

部分版本更新会触发数据库结构迁移（migration）。升级期间与升级后需要注意：

在发布说明中审阅迁移相关的变更，确认是否存在必须手动处理的数据结构变化；
监控日志中的迁移错误，出现 migration 相关报错时应立即介入；
验证数据完整性，确认流水线、步骤、工件等元数据未丢失或损坏；
测试关键功能，例如工作区访问、流水线运行（pipeline runs）等核心链路是否正常。

升级 Control Plane

Control Plane 的升级方式取决于部署形态（详见 scenarios.md 中的三种部署对比）。

SaaS 与 Hybrid 部署：无需任何操作

在 SaaS 与 Hybrid 部署中，Control Plane 托管在 ZenML 基础设施上，由 ZenML 团队定期升级。当有升级计划时，ZenML 会提前向所有受影响用户通告最低兼容的 Workspace Server 版本变化，给组织留出充足时间升级各自的工作区服务器，从而保持整个基础设施的版本兼容。

无需操作：SaaS 与 Hybrid 场景下，ZenML 全权负责 Control Plane 的升级。

自托管部署（Self-hosted）：升级流程

自托管场景中，Control Plane 由你自己管理。升级前应审阅发布说明，遇到问题可联系 ZenML 支持。

离线（Air-gapped）环境：准备软件包

对于与公网隔离的离线环境，标准helm pull无法使用，需要先向 ZenML 支持申请离线软件包（offline bundle），其中应包含：

更新后的容器镜像（container images）
更新后的 Helm charts
发布说明与迁移指南（migration guide）
漏洞评估报告（如适用）

拿到软件包后按以下步骤导入：

若使用私有镜像仓库，将新容器镜像复制到你的私有仓库；
通过受批准的方式将软件包传输到离线环境；
解压并加载新镜像，打标签并推送（push）到内部镜像仓库。

标准升级步骤

第 1 步：更新 Helm Values。修改values.yaml中的镜像标签，指向新版本的 image tag。在 helm/values.yaml 中，镜像配置位于server.image段：

server: image: repository: zenmldocker/zenml-server pullPolicy: Always # 覆盖默认 tag（默认使用 chart 的 appVersion） tag: <new-version-tag>

第 2 步：执行升级。根据是否需要修改配置，选择两种方式：

方案 A——配置无变化时，原地升级并复用现有 values：

helm upgrade zenml-pro ./zenml-pro-<new-version>.tgz \ --namespace <your-control-plane-namespace> \ --reuse-values

方案 B——配置有变化时，先导出再修改后重新应用：

# 导出当前生效的 values helm --namespace <your-control-plane-namespace> get values zenml-pro > current-values.yaml # 按需编辑 current-values.yaml，然后执行升级 helm upgrade zenml-pro ./zenml-pro-<new-version>.tgz \ --namespace <your-control-plane-namespace> \ --values current-values.yaml

第 3 步：监控升级过程。观察日志与 Pod 状态，确认滚动更新健康进行：

kubectl -n <your-control-plane-namespace> get pods kubectl -n <your-control-plane-namespace> logs <control-plane-pod>

第 4 步：验证升级。检查 Pod 状态、审阅日志、测试 SDK 连通性，并确认能够正常访问仪表盘。

Control Plane 回滚流程

如果升级失败或引发问题：

# 回滚到上一个修订版本 helm rollback zenml-pro <previous-revision> --namespace <your-control-plane-namespace> # 验证回滚后的 Pod 状态 kubectl -n <your-control-plane-namespace> get pods

回滚完成后，先审阅日志弄清失败原因，再决定是否重新发起升级，避免在同样的错误上重复踩坑。

升级 Workspace Server

Workspace Server 的升级路径同样因部署形态而异，但核心原则一致：先完成 Control Plane 升级，再进行 Workspace Server 升级。

SaaS 部署：前端自助升级

SaaS 场景下，工作区服务器可直接通过 ZenML Pro 前端以**自助方式（self-service）**升级，流程如下：

在 ZenML Pro UI 中进入工作区设置（workspace settings）；
发起工作区升级（initiate the workspace upgrade）；
系统会自动执行一次数据库备份，确保后续可以回滚；
在 UI 中监控升级进度。

这种方式以最小的运维开销保证工作区持续更新，全程由系统托管备份与安全保证。

Hybrid 与自托管部署：Helm 升级流程

在 Hybrid 或自托管部署中，你需要自行管理 Workspace Server，完整流程如下：

第 1 步：更新 Helm Values。将values.yaml中 Workspace Server 的版本改为目标镜像标签（即你想要升级到的版本）。

第 2 步：应用升级。重新应用 Helm chart：

helm upgrade <your-workspace-release-name> zenml/zenml \ --namespace <your-workspace-namespace> \ --values values.yaml

第 3 步：自动备份。作为升级流程的一部分，系统会在继续之前自动进行数据库备份，确保任何情况下都能安全回滚。

第 4 步：监控升级。观察日志与 Pod 状态：

kubectl -n <your-workspace-namespace> get pods kubectl -n <your-workspace-namespace> logs <workspace-server-pod>

第 5 步：失败自动回滚。若升级因任何原因失败，系统会利用备份自动回滚到之前的 Workspace Server 版本，无需人工干预。

第 6 步：零停机保障。工作区升级经过高可用编排，升级过程中用户不会感知到停机。

Workload Manager 更新注意事项

升级时请留意发布说明中与Workload Manager相关的变更。如果你配置了 Workload Manager（用于在 Kubernetes 中创建临时 Runner Pod 执行仪表盘触发的流水线），升级后可能需要更新 Helm values 中的环境变量。完整的配置参考见 deploy-workspace-snapshots.md。

Workspace Server 回滚流程

如果升级失败或引发问题：

Helm 回滚：

helm rollback zenml <previous-revision> --namespace zenml-workspace

恢复数据库：如有必要，使用升级前自动备份的数据进行恢复。
验证回滚：

kubectl -n zenml-workspace get pods

升级后的通用验证清单

无论升级了哪个组件，官方建议在升级完成后执行以下四项验证（详见 upgrades-updates.md 的 Post-Upgrade Verification 一节）：

健康检查（Health Checks）：确认所有 Pod 均处于 Running 状态。
连通性测试（Test Connectivity）：确认 ZenML SDK 能够成功连接服务器（例如zenml connect后执行zenml stack list）。
功能验证（Validate Functionality）：实际执行一次流水线运行，验证端到端链路。
日志审阅（Review Logs）：检查日志中是否存在错误或警告，尤其是数据库迁移与 Workload Manager 相关条目。

底层原理：数据库迁移 Job 是如何在升级中执行的

了解 Helm 模板与源码实现，可以更清楚地理解升级过程中的"自动备份"与"自动迁移"是如何落地的。

pre-upgrade Hook：迁移 Job

在 helm/templates/server-db-job.yaml 中，当配置了database.url（即使用外部 MySQL 等数据库）时，chart 会渲染一个名为<release>-db-migration的 Kubernetes Job，其关键特征：

通过helm.sh/hook: pre-install,pre-upgrade声明为pre-upgrade hook，即在每次helm upgrade真正滚动新 Pod 之前执行；
backoffLimit: 0：迁移失败不重试，直接让升级流程失败并暴露问题；
容器启动命令为zenml migrate-database，即调用 ZenML CLI 完成数据库迁移。

对应的 CLI 实现在 src/zenml/cli/base.py 中：migrate-database是一个隐藏命令（hidden=True），读取全局配置中的 store 配置，若为 SQL 类型则调用BaseZenStore.create_store()执行迁移并输出 "Database migration finished."；若非 SQL 存储（例如直连远程 ZenML server），则会输出警告"Unable to migrate database while connected to a ZenML server."。

主服务禁止自迁移

与此同时，helm/templates/server-deployment.yaml 中，当设置了database.url时，主 Deployment 会注入环境变量DISABLE_DATABASE_MIGRATION: "True"，确保迁移只由 pre-upgrade 的 Job 完成一次，主服务启动时不再自行迁移，从而避免并发迁移导致的竞态问题。

升级期间的备份策略

helm/values.yaml 的server.database段提供了升级前自动备份的多种策略（backupStrategy）：

策略	说明	适用场景
`disabled`	不执行备份	数据库极小的测试环境（不推荐用于生产）
`in-memory`	架构与数据暂存于内存，最快但不持久化，迁移失败后无法人工介入恢复	默认策略，适用于中小型数据库
`dump-file`	将架构与数据 dump 到本地文件，可配置 PV 持久化（`backupPVStorageSize`/`backupPVStorageClass`）	需要持久化备份文件的场景
`database`	在同一个数据库服务器上复制出备份库（需设置`backupDatabase`），仅支持 MySQL 兼容数据库	使用外部 MySQL 且账号具备管理备份库权限时
`mydumper`	使用 mydumper/myloader 工具备份，可配置线程与压缩参数	大型数据库的高性能备份
`custom`	自定义备份引擎，需指定继承`BaseBackupEngine`的类路径	有定制备份需求的场景

这一机制正是"升级自动备份、失败可回滚"的实现基础：无论是 SaaS 前端的自助升级，还是 Hybrid 下helm upgrade触发的升级，迁移前都会按该策略先做数据库备份。

滚动更新与优雅停机

helm/templates/server-deployment.yaml 中还体现了"零停机"设计的工程细节：

存活探针：GET /health（initialDelay 15s、period 15s、failureThreshold 5）；
就绪探针：GET /ready（initialDelay 8s、period 15s、failureThreshold 5）；
优雅停机：preStophook 执行sleep 15，在 SIGTERM 前多留 15 秒，让端点从 ingress 摘除、流量切走，从而将滚动升级期间的 502 错误降到最低。

结合这些探针与优雅停机配置，升级时新 Pod 就绪后流量才切换，旧 Pod 被优雅回收，用户侧的流水线交互不会中断。

企业官网建设流程全解析