发布日期: 2025-10-16
版本号: v23.0.0-rc1

Vitess v23.0.0 发布的主要变化是将默认MySQL版本从8.0.40升级至8.4.6，使用vitess-operator升级时需遵循特定步骤。次要变化包括：废弃VTOrc的DiscoverInstanceTimings指标；删除了VTGate中四个旧指标（QueriesProcessed等）；新增VTGate的TransactionsProcessed和VTOrc的SkippedRecoveries指标。此外，拓扑组件中--consul_auth_static_file现在要求至少一个凭证；VTOrc移除了/api/aggregated-discovery-metrics API，新增了对EmergencyReparentShard恢复的按键空间/分片级动态控制功能；VTTablet添加了RestartReplication API，MySQL默认认证插件改为caching_sha2_password，修复了时区环境变量未传递的错误，且gRPC客户端错误包装方式有变。Docker方面，停止构建基于已终止支持的Debian Bullseye的镜像。本次发布包含225个合并的拉取请求。

更新内容 （中文）

Vitess v23.0.0 发布

摘要

目录

主要变更

新的默认版本

升级至 MySQL 8.4

我们的 vitess/lite:latest 镜像所使用的默认主要 MySQL 版本从 8.0.40 升级至 8.4.6。 此变更在 #18569 中合并。

VTGate 默认公告的 MySQL 版本也从 8.0.40 改为 8.4.6。如果这不是您实际运行的版本，可以设置 mysql_server_version 标志来公告所需的版本。

⚠️ 使用 vitess-operator 升级至此版本时：

如果您使用 vitess-operator，考虑到我们正在将 MySQL 版本从 8.0.40 升级至 8.4.6，您需要手动升级：

  1. 在您的 YAML 文件的 extra cnf 中添加 innodb_fast_shutdown=0。
  2. 应用此文件。
  3. 等待所有 pod 变为健康状态。
  4. 然后更改您的 YAML 文件以使用新的 Docker 镜像 (vitess/lite:v23.0.0)。
  5. 从您 YAML 文件的 extra cnf 中移除 innodb_fast_shutdown=0。
  6. 应用此文件。

这仅在从最新的 8.0.x 升级至 8.4.x 时需要一次。一旦您在 8.4.x 上，就可以在 8.4.x 版本之间升级和降级，而无需运行 innodb_fast_shutdown=0。

次要变更

废弃项

指标

组件 指标名称 备注 废弃 PR
vtorc DiscoverInstanceTimings 已被 DiscoveryInstanceTimings 替换 #18406

删除项

指标

组件 指标名称 废弃于 废弃 PR
vtgate QueriesProcessed v22.0.0 #17727
vtgate QueriesRouted v22.0.0 #17727
vtgate QueriesProcessedByTable v22.0.0 #17727
vtgate QueriesRoutedByTable v22.0.0 #17727

新增指标

VTGate

名称 维度 描述 PR
TransactionsProcessed Shard, Type 按分片分布和事务类型统计在 VTGate 处理的事务数。 #18171

VTOrc

名称 维度 描述 PR
SkippedRecoveries RecoveryName, Keyspace, Shard, Reason 统计已处理的各类跳过的恢复次数。 #17985

拓扑

--consul_auth_static_file 需要 1 个或多个凭证

在多个组件中使用的 --consul_auth_static_file 标志现在要求能够从提供的 json 文件中加载 1 个或多个凭证。

VTOrc

移除了聚合发现指标 HTTP API

VTOrc 的未记录的 /api/aggregated-discovery-metrics HTTP API 端点已被移除。VTOrc 已记录的 API 列表可在此处找到。

我们建议使用标准的 VTOrc 指标来收集相同的指标。如果您在标准指标中发现缺少某个指标，请提交 issue 或 PR 来解决此问题。

对基于 EmergencyReparentShard 的恢复进行动态控制

注意：禁用基于 EmergencyReparentShard 的恢复会引入可用性风险；请极其谨慎使用！如果您经常依赖此功能，例如在自动化中，这可能表明是一种反模式。如果是这样，请提交 issue 以讨论在 VTOrc 中原生支持您的用例。

引入了新的 vtctldclient RPC SetVtorcEmergencyReparent，允许按 keyspace 和/或 shard 禁用涉及 EmergencyReparentShard 操作的 VTOrc 恢复。在此版本之前，仅可以全局/按 VTOrc 实例禁用基于 EmergencyReparentShard 的恢复。VTOrc 现在将在每次恢复时考虑从拓扑刷新的此 keyspace/shard 级别设置。禁用状态通过首先检查 keyspace，然后检查 shard 状态来确定。删除 keyspace 级别的覆盖不会删除每个 shard 的覆盖。

为了提供对禁用了基于 EmergencyReparentShard 的 VTOrc 恢复的 keyspace/shard 的可观测性，添加了 EmergencyReparentShardDisabled 指标。此指标标签可用于创建告警，以确保基于 EmergencyReparentShard 的恢复不会在非预期的时间段内被禁用。

恢复统计信息现在包含 keyspace/shard

以下与恢复相关的统计信息现在包含 keyspace 和 shard 的标签：

  1. FailedRecoveries
  2. PendingRecoveries
  3. RecoveriesCount
  4. SuccessfulRecoveries

在此版本之前，标签中仅包含恢复“类型”。

/api/replication-analysis HTTP API 已废弃

/api/replication-analysis HTTP API 端点现已废弃，并被 /api/detection-analysis 替换，后者目前返回相同的响应格式。

VTTablet

API 变更

  • 在 TabletManagerClient 接口中添加了 RestartReplication 方法。这个新的 RPC 允许在单次调用中停止并重启具有半同步配置的 MySQL 复制，为分别调用 StopReplication 和 StartReplication 提供了一个方便的替代方案。

CLI 标志

  • skip-user-metrics 标志，如果启用，将用 "UserLabelDisabled" 替换用户名标签，以防止在具有大量唯一用户的环境中指标数量激增。

托管的 MySQL 配置默认使用 caching-sha2-password

MySQL 8.0.26 及更高版本的默认身份验证插件现在是 caching_sha2_password，而不是 mysql_native_password。之所以进行此更改，是因为 mysql_native_password 已被弃用，并将在未来的 MySQL 版本中被移除。为了向后兼容，mysql_native_password 仍然可用。

此更改特别影响复制用户。如果您配置了具有显式密码的用户，建议在升级到 v23 后，使用类似以下的语句确保升级该用户：

ALTER USER 'vt_repl'@'%' IDENTIFIED WITH caching_sha2_password BY 'your-existing-password';

在未来的 Vitess 版本中，mysql_native_password 身份验证插件将被禁用于托管的 MySQL 实例。

MySQL 时区环境变量传播

修复了一个错误，即像 TZ 这样的环境变量没有从 mysqlctl 传播到 mysqld 进程。 因此，之前忽略了来自环境的时区设置。现在 mysqld 正确地继承了环境变量。 ⚠️ 依赖旧行为并显式设置非 UTC 时区的部署可能会在 DATETIME 值的解释方式上看到变化。为了保持兼容性，请在 MySQL pod 中显式设置 TZ=UTC。

gRPC tabletmanager 客户端错误变更

vttablet gRPC tabletmanager 客户端现在返回由内部 go/vt/vterrors 包包装的错误。依赖 google-gRPC 错误代码的外部自动化现在应该使用 vterrors.Code(err) 来检查错误的代码，该代码返回在 proto/vtrpc.proto 中定义的 vtrpcpb.Code。

Docker

Debian Bullseye 已于 1 年前结束生命周期，因此从 v23 开始，我们将不再构建或发布基于 debian:bullseye 的镜像。

将继续为 Debian Bookworm 构建，并添加最近发布的 Debian Trixie。v23 明确不将默认 Debian 标签更改为 Trixie。

此版本的完整变更日志可在此处找到。

此版本包含 225 个合并的 Pull Request。

感谢所有贡献者：@Arshdeep54, @BenjaminLockhart, @GrahamCampbell, @GuptaManan100, @HenryCaiHaiying, @app/dependabot, @app/vitess-bot, @arthurschreiber, @bantyK, @beingnoble03, @canoriz, @chapsuk, @chrisplim, @corbantek, @davidpiegza, @dbussink, @deepthi, @demmer, @derekperkins, @frouioui, @harshit-gangal, @jdoupe, @jeefy, @leejones, @mattlord, @maxenglander, @mdlayher, @mhamza15, @morgo, @mounicasruthi, @nickvanw, @notfelineit, @rohit-nayak-ps, @rvrangel, @shlomi-noach, @siddharth16396, @stankevich, @stutibiyani, @systay, @timvaillancourt, @twthorn, @vitess-bot, @wukuai, @yoheimuta

更新内容 （原始）

Release of Vitess v23.0.0

Summary

Table of Contents

Major Changes

New default versions

Upgrade to MySQL 8.4

The default major MySQL version used by our vitess/lite:latest image is going from 8.0.40 to 8.4.6. This change was merged in #18569.

VTGate also advertises MySQL version 8.4.6 by default instead of 8.0.40. If that is not what you are running, you can set the mysql_server_version flag to advertise the desired version.

⚠️ Upgrading to this release with vitess-operator:

If you are using the vitess-operator, considering that we are bumping the MySQL version from 8.0.40 to 8.4.6, you will have to manually upgrade:

  1. Add innodb_fast_shutdown=0 to your extra cnf in your YAML file.
  2. Apply this file.
  3. Wait for all the pods to be healthy.
  4. Then change your YAML file to use the new Docker Images (vitess/lite:v23.0.0).
  5. Remove innodb_fast_shutdown=0 from your extra cnf in your YAML file.
  6. Apply this file.

This is only needed once when going from the latest 8.0.x to 8.4.x. Once you’re on 8.4.x, it is possible to upgrade and downgrade between 8.4.x versions without needing to run innodb_fast_shutdown=0.

Minor Changes

Deprecations

Metrics

Component Metric Name Notes Deprecation PR
vtorc DiscoverInstanceTimings Replaced by DiscoveryInstanceTimings #18406

Deletions

Metrics

Component Metric Name Was Deprecated In Deprecation PR
vtgate QueriesProcessed v22.0.0 #17727
vtgate QueriesRouted v22.0.0 #17727
vtgate QueriesProcessedByTable v22.0.0 #17727
vtgate QueriesRoutedByTable v22.0.0 #17727

New Metrics

VTGate

Name Dimensions Description PR
TransactionsProcessed Shard, Type Counts transactions processed at VTGate by shard distribution and transaction type. #18171

VTOrc

Name Dimensions Description PR
SkippedRecoveries RecoveryName, Keyspace, Shard, Reason Count of the different skipped recoveries processed. #17985

Topology

--consul_auth_static_file requires 1 or more credentials

The --consul_auth_static_file flag used in several components now requires that 1 or more credentials can be loaded from the provided json file.

VTOrc

Aggregated Discovery Metrics HTTP API removed

VTOrc’s undocumented /api/aggregated-discovery-metrics HTTP API endpoint was removed. The list of documented VTOrc APIs can be found here.

We recommend using the standard VTOrc metrics to gather the same metrics. If you find that a metric is missing in standard metrics, please open an issue or PR to address this.

Dynamic control of EmergencyReparentShard-based recoveries

Note: disabling EmergencyReparentShard-based recoveries introduces availability risks; please use with extreme caution! If you rely on this functionality often, for example in automation, this may be signs of an anti-pattern. If so, please open an issue to discuss supporting your use case natively in VTOrc.

The new vtctldclient RPC SetVtorcEmergencyReparent was introduced to allow VTOrc recoveries involving EmergencyReparentShard actions to be disabled on a per-keyspace and/or per-shard basis. Previous to this version, disabling EmergencyReparentShard-based recoveries was only possible globally/per-VTOrc-instance. VTOrc will now consider this keyspace/shard-level setting that is refreshed from the topo on each recovery. The disabled state is determined by first checking if the keyspace, and then the shard state. Removing a keyspace-level override does not remove per-shard overrides.

To provide observability of keyspace/shards with EmergencyReparentShard-based VTOrc recoveries disabled, the EmergencyReparentShardDisabled metric was added. This metric label can be used to create alerting to ensure EmergencyReparentShard-based recoveries are not disabled for an undesired period of time.

Recovery stats to include keyspace/shard

The following recovery-related stats now include labels for keyspaces and shards:

  1. FailedRecoveries
  2. PendingRecoveries
  3. RecoveriesCount
  4. SuccessfulRecoveries

Previous to this release, only the recovery “type” was included in labels.

/api/replication-analysis HTTP API deprecation

The /api/replication-analysis HTTP API endpoint is now deprecated and is replaced with /api/detection-analysis, which currently returns the same response format.

VTTablet

API Changes

  • Added RestartReplication method to TabletManagerClient interface. This new RPC allows stopping and restarting MySQL replication with semi-sync configuration in a single call, providing a convenient alternative to separate StopReplication and StartReplication calls.

CLI Flags

  • skip-user-metrics flag if enabled, replaces the username label with “UserLabelDisabled” to prevent metric explosion in environments with many unique users.

Managed MySQL configuration defaults to caching-sha2-password

The default authentication plugin for MySQL 8.0.26 and later is now caching_sha2_password instead of mysql_native_password. This change is made because mysql_native_password is deprecated and removed in future MySQL versions. mysql_native_password is still enabled for backwards compatibility.

This change specifically affects the replication user. If you have a user configured with an explicit password, it is recommended to make sure to upgrade this user after upgrading to v23 with a statement like the following:

ALTER USER 'vt_repl'@'%' IDENTIFIED WITH caching_sha2_password BY 'your-existing-password';

In future Vitess versions, the mysql_native_password authentication plugin will be disabled for managed MySQL instances.

MySQL timezone environment propagation

Fixed a bug where environment variables like TZ were not propagated from mysqlctl to the mysqld process. As a result, timezone settings from the environment were previously ignored. Now mysqld correctly inherits environment variables. ⚠️ Deployments that relied on the old behavior and explicitly set a non-UTC timezone may see changes in how DATETIME values are interpreted. To preserve compatibility, set TZ=UTC explicitly in MySQL pods.

gRPC tabletmanager client error changes

The vttablet gRPC tabletmanager client now returns errors wrapped by the internal go/vt/vterrors package. External automation relying on google-gRPC error codes should now use vterrors.Code(err) to inspect the code of an error, which returns vtrpcpb.Codes defined in the proto/vtrpc.proto protobuf.

Docker

Bullseye went EOL 1 year ago, so starting from v23, we will no longer build or publish images based on debian:bullseye.

Builds will continue for Debian Bookworm, and add the recently released Debian Trixie. v23 explicitly does not change the default Debian tag to Trixie.

The entire changelog for this release can be found here.

The release includes 225 merged Pull Requests.

Thanks to all our contributors: @Arshdeep54, @BenjaminLockhart, @GrahamCampbell, @GuptaManan100, @HenryCaiHaiying, @app/dependabot, @app/vitess-bot, @arthurschreiber, @bantyK, @beingnoble03, @canoriz, @chapsuk, @chrisplim, @corbantek, @davidpiegza, @dbussink, @deepthi, @demmer, @derekperkins, @frouioui, @harshit-gangal, @jdoupe, @jeefy, @leejones, @mattlord, @maxenglander, @mdlayher, @mhamza15, @morgo, @mounicasruthi, @nickvanw, @notfelineit, @rohit-nayak-ps, @rvrangel, @shlomi-noach, @siddharth16396, @stankevich, @stutibiyani, @systay, @timvaillancourt, @twthorn, @vitess-bot, @wukuai, @yoheimuta

下载链接