发布日期: 2025-10-29
版本号: v23.0.0-rc2

Vitess v23.0.0 发布的主要变化包括：默认 MySQL 版本从 8.0.40 升级至 8.4.6，使用 vitess-operator 的用户需按照特定步骤手动升级。次要变更包括废弃和删除了一些监控指标（如 vtgate 的 QueriesProcessed 等），新增了 VTGate 的 TransactionsProcessed 和 VTOrc 的 SkippedRecoveries 等指标；VTOrc 移除了聚合发现指标的 API，新增了基于键空间/分片的动态恢复控制和统计，并弃用了 /api/replication-analysis 接口；VTTablet 新增了 RestartReplication 方法和 skip-user-metrics 标志，MySQL 默认认证插件改为 caching-sha2_password，并修复了时区环境变量传递问题，gRPC 客户端错误处理方式有所调整；此外，Docker 镜像不再基于已停止维护的 Debian Bullseye 构建。

更新内容 （中文）

Vitess v23.0.0 发布

摘要

目录

• 主要变更
  • 新默认版本
    • 升级至 MySQL 8.4
• 次要变更
  • 弃用功能
    • 指标
  • 删除功能
    • 指标
  • 新增指标
    • VTGate
    • VTOrc
  • 拓扑
    • --consul_auth_static_file 需要1个或更多凭据
  • VTOrc
    • 已移除聚合发现指标 HTTP API
    • 动态控制基于 EmergencyReparentShard 的恢复操作
    • 恢复统计信息现在包含键空间/分片
    • /api/replication-analysis HTTP API 弃用
  • VTTablet
    • API 变更
    • CLI 标志
    • 托管 MySQL 配置默认使用 caching-sha2-password
    • MySQL 时区环境变量传播
    • gRPC tabletmanager 客户端错误变更
  • Docker

主要变更

新默认版本

升级至 MySQL 8.4

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

VTGate 默认也通告 MySQL 版本 8.4.6 而非 8.0.40。如果您运行的不是此版本，可以设置 mysql_server_version 标志来通告所需的版本。

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

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

1. 在您的 YAML 文件的额外 cnf 中添加 innodb_fast_shutdown=0。
2. 应用此文件。
3. 等待所有 Pod 健康。
4. 然后更改您的 YAML 文件以使用新的 Docker 镜像（vitess/lite:v23.0.0）。
5. 从您的 YAML 文件的额外 cnf 中移除 innodb_fast_shutdown=0。
6. 应用此文件。

从最新的 8.0.x 升级到 8.4.x 时仅需执行此操作一次。一旦您处于 8.4.x 版本，则可以在 8.4.x 版本之间进行升级和降级，而无需运行 innodb_fast_shutdown=0。

次要变更

弃用功能

指标

删除功能

指标

新增指标

VTGate

VTOrc

拓扑

--consul_auth_static_file 需要1个或更多凭据

几个组件中使用的 --consul_auth_static_file 标志现在要求从提供的 json 文件中可以加载1个或更多凭据。

VTOrc

已移除聚合发现指标 HTTP API

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

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

动态控制基于 EmergencyReparentShard 的恢复操作

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

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

为了提供对已禁用基于 EmergencyReparentShard 的 VTOrc 恢复的键空间/分片的可观测性，新增了 EmergencyReparentShardDisabled 指标。此指标标签可用于创建警报，以确保基于 EmergencyReparentShard 的恢复不会在不需要的时段内被禁用。

恢复统计信息现在包含键空间/分片

以下与恢复相关的统计信息现在包含键空间和分片的标签：

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) 来检查错误的代码，该代码返回在 the proto/vtrpc.proto protobuf 中定义的 vtrpcpb.Codes。

Docker

Bullseye 已于1年前停止支持，因此从 v23 开始，我们将不再基于 debian:bullseye 构建或发布镜像。

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

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

此版本包含 239 个已合并的 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
• Minor Changes
  • Deprecations
    • Metrics
  • Deletions
    • Metrics
  • New Metrics
    • VTGate
    • VTOrc
  • Topology
    • --consul_auth_static_file requires 1 or more credentials
  • VTOrc
    • Aggregated Discovery Metrics HTTP API removed
    • Dynamic control of EmergencyReparentShard-based recoveries
    • Recovery stats to include keyspace/shard
    • /api/replication-analysis HTTP API deprecation
  • VTTablet
    • API Changes
    • CLI Flags
    • Managed MySQL configuration defaults to caching-sha2-password
    • MySQL timezone environment propagation
    • gRPC tabletmanager client error changes
  • Docker

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

Deletions

Metrics

New Metrics

VTGate

VTOrc

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 239 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

下载链接

• vitess-23.0.0-rc2-2c76877.tar.gz
• vitess-23.0.0_rc2-2c76877.x86_64.rpm
• vitess_23.0.0-rc2-2c76877_amd64.deb