ZenML Pro 组件升级与更新完全指南:Control Plane 与 Workspace Server 的升级、回滚与验证 📅 发布时间:2026/9/18 3:36:09 👁 浏览次数: 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 ServerZenML Pro 的架构由两个核心服务组成详见 system-architecture.mdControl 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 PlaneZenML Pro可在 ZenML Pro 的 Helm 仓库中查看可用版本helm/Chart.yaml 中 OSS 版本信息可作为对照参考。Workspace ServerZenML 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 PlaneControl 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——配置无变化时原地升级并复用现有 valueshelm 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 ServerWorkspace 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 charthelm 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是一个隐藏命令hiddenTrue读取全局配置中的 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 /healthinitialDelay 15s、period 15s、failureThreshold 5就绪探针GET /readyinitialDelay 8s、period 15s、failureThreshold 5优雅停机preStophook 执行sleep 15在 SIGTERM 前多留 15 秒让端点从 ingress 摘除、流量切走从而将滚动升级期间的 502 错误降到最低。结合这些探针与优雅停机配置升级时新 Pod 就绪后流量才切换旧 Pod 被优雅回收用户侧的流水线交互不会中断。相关文档导航Deployment Details部署细节——组件配置参考适用于初始部署与部署后调优System Architecture系统架构——理解 Control Plane 与 Workspace Server 如何交互Scenarios部署场景——SaaS / Hybrid / Self-hosted 的选型对比与部署入口Control Plane 部署——Control Plane 的配置参考Workspace Server 部署——Workspace Server 的配置参考Workspace Server 配置快照——Workload Manager 等完整配置参考。最后再次强调升级铁律先 Control Plane后 Workspace Server升级前备份数据库、values 与证书升级后按健康检查、连通性、功能、日志四项清单逐一验证。遵循这一流程无论是云端托管还是完全离线的自托管环境都能安全、平稳地完成 ZenML Pro 各组件的版本演进。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考