Vitess 24.0 配置参数详解

Vitess 24.0 配置参数详解，按 etcd 拓扑、vtctld、vtgate、vttablet、备份与运行时分类说明关键参数，附生产环境模板与 FAQ。

VitessVitessNewSQL2026/10/07

Vitess 24.0 配置参数详解

目标：详解 Vitess 24.0 四大组件（etcd 拓扑、vtctld、vtgate、vttablet）的核心配置参数，给出真实起服命令对应参数，并提供生产环境模板与 FAQ。参数以 v24 推荐的横线风格（--xxx-yyy）为主，同时标注 v24 仍兼容的下划线风格（--xxx_yyy，已标记 deprecated）。

参数风格说明

v24 起多数长参数统一改为横线风格（kebab-case），下划线风格仍可用但会打印弃用告警（实测样例）：

Flag --backup_storage_implementation has been deprecated, use --backup-storage-implementation instead
Flag --file_backup_storage_root has been deprecated, use --file-backup-storage-root instead
Flag --grpc_port has been deprecated, use --grpc-port instead
WARNING: --logtostderr has no effect when structured logging is enabled ...

💡 建议：新配置统一使用横线风格；--logtostderr 在新版为结构化日志，如需 glog 需加 --log-structured=false。

一、etcd 拓扑（topology store）

Vitess 用 etcd 保存「全局拓扑 + 单元(cell)拓扑」，根路径为 vitess/global。

参数类型说明实测值
--namestring节点名vitess-etcd
--data-dirstring数据目录/var/lib/vitess/etcd
--listen-client-urlsurl客户端监听http://127.0.0.1:2379
--advertise-client-urlsurl对外广播地址http://127.0.0.1:2379
--listen-peer-urlsurl集群节点间http://0.0.0.0:2380
--initial-cluster列表初始成员vitess-etcd=http://127.0.0.1:2380
--initial-cluster-statenew/existing新建或加入new

⚠️ 注意：listen-client-urls 不要同时写 127.0.0.1:2379 与 0.0.0.0:2379，二者冲突报 bind: address already in use（实测踩坑）。

二、vtctld（控制面）

三个 Vitess 组件都通过 --topo_* 三件套连接 etcd：

--topo_implementation etcd2 \
--topo_global_server_address etcd1:2379 \
--topo_global_root vitess/global \
参数类型默认说明
--topo_implementationstringzk2拓扑实现：etcd2/consul/zk2
--topo_global_server_addressstring-全局拓扑地址（etcd http://host:2379）
--topo_global_rootstringvitess/global全局拓扑根路径
--cellstring-vtctld 所在单元
--service_mapstring-gRPC 服务开关：grpc-vtctl,grpc-vtctld
--backup-storage-implementationstring-备份后端：file（本地）等
--file-backup-storage-rootstring-本地备份根目录
--portint0HTTP 调试端口
--grpc-portint0gRPC 端口（服务端监听，默认 15999）
--grpc-vtctldbool-是否注册 vtctld gRPC

实测 vtctld 启动（节选）：

vtctld --topo_implementation etcd2 --topo_global_server_address etcd1:2379 \
  --topo_global_root vitess/global --cell test --service_map grpc-vtctl,grpc-vtctld \
  --backup_storage_implementation file --file_backup_storage_root /vt/vtdataroot/backups \
  --port 8080 --grpc_port 15999
msg "Version: 24.0.0 (...)" 
msg "Listening for gRPC calls on port 15999"

三、vtgate（SQL 网关）

参数类型默认说明
--topo_implementationstringzk2与全局一致用 etcd2
--port / --grpc-portint0本机 HTTP/gRPC
--mysql-server-portint0对外 MySQL 协议端口（本例 15306）
--mysql-server-bind-addressstring""绑定地址
--mysql-auth-server-implstringstatic认证：none/static/ldap
--mysql-auth-server-static-stringstring-静态用户表 JSON
--cellstring-本节点单元
--cells-to-watchstring-vtgate 覆盖的单元（逗号分隔）
--tablet-types-to-waitstring-等待的 tablet 类型，如 PRIMARY,REPLICA,RDONLY
--service_mapstring-grpc-vtgateservice 等
--normalize-queriesbooltrue查询规范化
--max-connectionsint0每后端最大连接数

实测 vtgate 启动（节选）：

vtgate --topo_implementation etcd2 --topo_global_server_address etcd1:2379 \
  --topo_global_root vitess/global --port 8080 --grpc_port 15999 \
  --mysql_server_port 15306 --mysql_auth_server_impl none \
  --cell test --cells_to_watch test --tablet_types_to_wait PRIMARY,REPLICA,RDONLY \
  --service_map grpc-vtgateservice --normalize_queries=true

通过 vtgate 的 MySQL 协议连接后 @@version 返回 8.4.6-Vitess（实测），确认网关层接管 SQL。

四、vttablet（分片 tablet）

参数类型默认说明
--tablet-pathstring-别名 <cell>-<uid>，如 test-0000000101
--tablet-hostnamestring自动tablet 对外地址
--init-keyspace / --init-shardstring-初始化时归属 keyspace/shard
--init-tablet-typestring-初始化类型 replica/rdonly/primary
--init-db-name-overridestring-底层库名（默认 vt_<keyspace>）
--port / --grpc-portint-本机 HTTP/gRPC
--service-mapstring-grpc-queryservice,grpc-tabletmanager,grpc-updatestream
--backup-storage-implementationstringfile备份后端
--file-backup-storage-rootstring-备份目录
--restore-from-backupbool-空库时是否恢复备份
--enable-replication-reporterbool-上报复制延迟
--health-check-intervalduration20s健康检查周期
--queryserver-config-schema-reload-timeduration-schema 刷新周期
--mysqlctl-portint-本 tablet 的 mysqlctl 端口
--mysqlctl-mycnf-templatestring-mysqld 初始化 my.cnf 模板

实测 vttablet 启动（节选）：

vttablet --topo_implementation etcd2 --topo_global_server_address etcd1:2379 \
  --topo_global_root vitess/global --tablet-path test-0000000101 \
  --tablet_hostname vttablet101 --health_check_interval 5s --port 8080 --grpc_port 15999 \
  --service_map grpc-queryservice,grpc-tabletmanager,grpc-updatestream \
  --init_keyspace test_keyspace --init_shard -80 \
  --backup_storage_implementation file --file_backup_storage_root /vt/vtdataroot/backups \
  --init_db_name_override vt_test_keyspace

⚠️ 注意：v24 的 mysqlctl 初始化 MySQL 时必须提供 --mysqlctl-mycnf-template（BYOI），否则报 Failed to open required defaults file: my.cnf（实测）。

五、备份相关（vtctld/vttablet 共用）

参数说明
--backup-storage-implementationfile 本地目录 / gcs/s3/ceph 等
--file-backup-storage-root本地备份根
--backup-count保留备份份数
--backup-compress是否压缩
--restore-from-backuptablet 空数据时从最近备份恢复

六、生产环境模板（三台服务器）

主机服务
topo-node1/2/3etcd 3 节点（集群）
vt-ctrl1/2vtctld（HA），连接 etcd
vt-gate1..nvtgate（面向应用，MySQL 协议 15306）
vt-<shard>每 shard 一个 vttablet + 其 MySQL 8.0

vtgttablet 生产参数示例：

ExecStart=/usr/local/bin/vttablet \
  --topo_implementation etcd2 \
  --topo_global_server_address topo-node1:2379,topo-node2:2379,topo-node3:2379 \
  --topo_global_root vitess/global \
  --tablet_path zone1-0000000101 \
  --init_keyspace commerce --init_shard -80 --init_tablet_type replica \
  --backup_storage_implementation gcs --backup-storage-gcs-bucket my-bucket \
  --port 15100 --grpc_port 16100 --enable_replication_reporter=true \
  --queryserver-config-schema-reload-time 60s

七、参数查看

vttablet --help | less
vtgate  --help | less
vtctld  --help | less

FAQ

问题解决
下划线参数还能用吗可用但 deprecated；新配推荐横线风格。
vtgate 认证怎么开--mysql-auth-server-impl static --mysql-auth-server-static-string 提供用户表。
多 etcd 怎么接入--topo_global_server_address 逗号分隔三个节点的 client-urls。
备份目录不存在需先 mkdir -p 并授权给运行用户。
logtostderr 无效v24 默认结构化日志；--log-structured=false 可回到 glog。

参考链接

Vitess 24.0 配置参数详解 - Quzuo