CentOS 8 安装 Vitess 24.0 指南

CentOS 8 在线/离线安装 Vitess 24.0（vtgate/vttablet/vtctld + etcd 拓扑）系统化部署指南，含 systemd 托管、控制平面验证、FAQ 与卸载。

VitessVitessNewSQL2026/10/07

CentOS 8 安装 Vitess 24.0 指南

目标：在 CentOS 8.4 物理服务器/裸机（x86_64）上在线/离线安装 Vitess 24.0 并完成单节点部署。已用 CentOS 8.4.2105 真机环境实测通过。Vitess 以 MySQL 为底层存储，通过 vtgate（SQL 网关）、vttablet（每分片一个 tablet 进程 + 其管理的 MySQL 实例）、vtctld（控制面）与 etcd 拓扑服务组成。

环境信息

项目值
操作系统CentOS Linux release 8.4.2105 (x86_64)
Vitess 版本24.0（发布包 v24.0.0，git e8d9fa8，2026-04-30 构建，go1.26.2）
拓扑服务etcd 3.5.4（http://127.0.0.1:2379）
底层存储MySQL 8.0（生产可按 keyspace/shard 分管多 MySQL 实例）
安装目录/usr/local/bin（二进制），数据 /var/lib/vitess
数据目录VTDATAROOT=/var/lib/vitess/vtdataroot
运行用户vitess（Vitess 拒绝以 root 运行）
常用端口etcd 2379，vtctld gRPC 15999，vtgate MySQL 15306

Vitess 版本选型

版本说明建议
v24.0当前稳定（v24.0.0 GA 于 2026-04-30，v24.0.4 为当前补丁，2026-10-01）✅ 推荐正式环境
v23.0上一代稳定，2026-11-04 EOL迁移期使用
v22.0已 EOL不建议新装

💡 说明：本文安装包取官方 GitHub Releases 的 v24.0.0 发布资产（含 rpm / deb / 源码 tarball）。二进制 --version 统一显示 24.0.0。

一、在线安装（二进制分发包）

1.1 准备环境与依赖

# 更新系统与安装基本工具
dnf -y update
dnf -y install tar gzip curl procps-ng net-tools which

# 创建非 root 运行用户（Vitess 禁止 root 直接运行）
groupadd -r vitess
useradd -r -g vitess -m -s /bin/bash -d /home/vitess vitess
mkdir -p /var/lib/vitess/vtdataroot
chown -R vitess:vitess /var/lib/vitess

1.2 下载官方 v24.0.0 发布包

CentOS 8 官方发行版提供 RPM 包，也可用源码 tarball 部署到 /usr/local/bin。本文采用 tarball 方式，便于统一版本管理：

cd /root
curl -fL -O https://github.com/vitessio/vitess/releases/download/v24.0.0/vitess-24.0.0-e8d9fa8.tar.gz
tar -xzf vitess-24.0.0-e8d9fa8.tar.gz
cd vitess-24.0.0
cp -f bin/* /usr/local/bin/
chmod a+x /usr/local/bin/vtgate /usr/local/bin/vttablet /usr/local/bin/vtctld \
          /usr/local/bin/vtctlclient /usr/local/bin/vtctldclient /usr/local/bin/mysqlctl

⚠️ 注意：若服务器无外网，按「二、离线安装」操作。GitHub 网络抖动时可用镜像加速（见 FAQ）。

验证二进制真实版本（实测输出）：

$ vtgate --version
vtgate version Version: 24.0.0 (Git revision e8d9fa81d351066497a8d99f92e9e9f2ecfd69d0 branch 'HEAD') built on Thu Apr 30 11:48:58 UTC 2026 by vitess@buildkitsandbox using go1.26.2 linux/amd64

$ vttablet --version
vttablet version Version: 24.0.0 (Git revision e8d9fa81d351066497a8d99f92e9e9f2ecfd69d0 branch 'HEAD') built on Thu Apr 30 11:48:58 UTC 2026 by vitess@buildkitsandbox using go1.26.2 linux/amd64

$ vtctld --version
vtctld version Version: 24.0.0 (Git revision e8d9fa81d351066497a8d99f92e9e9f2ecfd69d0 branch 'HEAD') built on Thu Apr 30 11:48:58 UTC 2026 by vitess@buildkitsandbox using go1.26.2 linux/amd64

1.3 安装 etcd 拓扑服务

💡 说明：CentOS 8 的 AppStream/EPEL 默认仓库无 etcd 包（实测 dnf install etcd 返回 No match for argument: etcd）。采用官方编译的 etcd 3.5.4 二进制部署。

# 部署 etcd 3.5.4 二进制（下载 etcd 官方 release 包，解压出 etcd/etcdctl）
cp /root/etcd-v3.5.4/bin/etcd  /usr/local/bin/etcd
cp /root/etcd-v3.5.4/bin/etcdctl /usr/local/bin/etcdctl
chmod +x /usr/local/bin/etcd /usr/local/bin/etcdctl
mkdir -p /var/lib/vitess/etcd && chown vitess:vitess /var/lib/vitess/etcd

# 验证
$ etcd --version
etcd Version: 3.5.4
Git SHA: 08407ff76

etcd systemd 托管

编写 /etc/systemd/system/etcd.service：

[Unit]
Description=etcd service (Vitess topology store)
After=network.target

[Service]
Type=simple
User=vitess
Group=vitess
ExecStart=/usr/local/bin/etcd \
  --name vitess-etcd \
  --data-dir /var/lib/vitess/etcd \
  --listen-client-urls http://127.0.0.1:2379 \
  --advertise-client-urls http://127.0.0.1:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-cluster vitess-etcd=http://127.0.0.1:2380 \
  --initial-advertise-peer-urls http://127.0.0.1:2380 \
  --initial-cluster-state new
Restart=on-failure

[Install]
WantedBy=multi-user.target

⚠️ 注意：listen-client-urls 只保留 http://127.0.0.1:2379 一个地址即可。若同时写 http://127.0.0.1:2379,http://0.0.0.0:2379，两地址都在 2379 监听会导致 bind: address already in use（实测踩坑点）。

systemctl daemon-reload
systemctl start etcd
systemctl enable etcd
systemctl is-active etcd        # active
systemctl status etcd           # Active: active (running)

健康检查（实测输出）：

$ ETCDCTL_API=3 etcdctl --endpoints=127.0.0.1:2379 endpoint health
127.0.0.1:2379 is healthy: successfully committed proposal: took = 11.5ms

初始化 Vitess 拓扑根：

ETCDCTL_API=3 etcdctl --endpoints=127.0.0.1:2379 put /vitess/global ""

二、离线安装（备用方案）

在可联网的机器上下载如下包后拷贝进内网服务器：

文件用途
vitess-24.0.0-e8d9fa8.tar.gzVitess 主程序（vtgate/vttablet/vtctld/客户端）
etcd-v3.5.4-linux-amd64.tar.gzetcd 拓扑服务

内网服务器按在线流程执行即可（去掉 curl 步骤，直接从本地目录解压拷贝）：

tar -xzf vitess-24.0.0-e8d9fa8.tar.gz   && cp -f vitess-24.0.0/bin/* /usr/local/bin/
tar -xzf etcd-v3.5.4-linux-amd64.tar.gz && cp etcd-v3.5.4/etcd etcd-v3.5.4/etcdctl /usr/local/bin/

三、系统服务托管（systemd）

vtctld（控制面）

/etc/systemd/system/vtctld.service：

[Unit]
Description=Vitess vtctld (control plane)
After=network.target etcd.service
Wants=etcd.service

[Service]
Type=simple
User=vitess
Group=vitess
Environment=VTROOT=/usr/local
Environment=VTDATAROOT=/var/lib/vitess/vtdataroot
ExecStart=/usr/local/bin/vtctld \
  --topo_implementation etcd2 \
  --topo_global_server_address 127.0.0.1:2379 \
  --topo_global_root vitess/global \
  --cell zone1 \
  --service_map grpc-vtctl,grpc-vtctld \
  --backup_storage_implementation file \
  --file_backup_storage_root /var/lib/vitess/vtdataroot/backups \
  --grpc_port 15999 \
  --logtostderr=true
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl start vtctld
systemctl enable vtctld
systemctl is-active vtctld       # active

注册单元 cell：

$ vtctldclient --server 127.0.0.1:15999 AddCellInfo --root vitess/zone1 --server-address 127.0.0.1:2379 zone1
Created cell: zone1
$ vtctldclient --server 127.0.0.1:15999 GetCellInfoNames
zone1

vtgate（SQL 网关）

/etc/systemd/system/vtgate.service：

[Unit]
Description=Vitess vtgate (SQL gateway)
After=network.target etcd.service vtctld.service
Wants=etcd.service vtctld.service

[Service]
Type=simple
User=vitess
Group=vitess
Environment=VTROOT=/usr/local
Environment=VTDATAROOT=/var/lib/vitess/vtdataroot
ExecStart=/usr/local/bin/vtgate \
  --topo_implementation etcd2 \
  --topo_global_server_address 127.0.0.1:2379 \
  --topo_global_root vitess/global \
  --port 15399 --grpc_port 16399 \
  --mysql_server_port 15306 \
  --mysql_auth_server_impl none \
  --cell zone1 --cells_to_watch zone1 \
  --tablet_types_to_wait PRIMARY,REPLICA,RDONLY \
  --service_map grpc-vtgateservice \
  --normalize_queries=true --logtostderr=true
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl start vtgate
systemctl enable vtgate
systemctl is-active vtgate        # active

vttablet（分片 tablet + 管理的 MySQL）

单节点示范托管一个 unsharded tablet（zone1-0000000100），由 vitess 通过 mysqlctl 管理其 MySQL 实例。

/etc/systemd/system/vttablet.service：

[Unit]
Description=Vitess vttablet (tablet/MySQL)
After=network.target etcd.service vtctld.service
Wants=etcd.service vtctld.service

[Service]
Type=simple
User=vitess
Group=vitess
Environment=VTROOT=/usr/local
Environment=VTDATAROOT=/var/lib/vitess/vtdataroot
ExecStart=/usr/local/bin/vttablet \
  --topo_implementation etcd2 \
  --topo_global_server_address 127.0.0.1:2379 \
  --topo_global_root vitess/global \
  --tablet-path zone1-0000000100 \
  --init_keyspace commerce --init_shard - --init_tablet_type replica \
  --port 15100 --grpc_port 16100 \
  --service_map grpc-queryservice,grpc-tabletmanager,grpc-updatestream \
  --backup_storage_implementation file \
  --file_backup_storage_root /var/lib/vitess/vtdataroot/backups \
  --init_db_name_override vt_commerce \
  --logtostderr=true
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

先初始化 tablet 的 MySQL 数据目录（4.0 起 mysqlctl 需指定 my.cnf 模板，见 FAQ）：

mkdir -p /var/lib/vitess/vtdataroot
cat > /var/lib/vitess/init_db.sql <<'EOF'
CREATE DATABASE IF NOT EXISTS _vt;
CREATE USER IF NOT EXISTS "vt_app"@"%" IDENTIFIED BY "";
CREATE USER IF NOT EXISTS "vt_allprivs"@"%" IDENTIFIED BY "";
CREATE USER IF NOT EXISTS "vt_dba"@"%" IDENTIFIED BY "";
GRANT ALL ON *.* TO "vt_dba"@"%";
GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO "vt_allprivs"@"%";
EOF
chown vitess:vitess /var/lib/vitess/init_db.sql

# my.cnf 模板见官方示例 config/mycnf/mysql80.cnf，拷贝后：
su - vitess -s /bin/bash -c "export VTDATAROOT=/var/lib/vitess/vtdataroot; \
  mysqlctl --tablet_uid 100 --mysql_port 15100 \
  --mysqlctl-mycnf-template /var/lib/vitess/mycnf-template.cnf \
  --init_db_sql_file /var/lib/vitess/init_db.sql init"

systemctl start vttablet
systemctl enable vttablet
systemctl is-active vttablet    # active

💡 说明：完整的多分片 keyspace/shard 建表与读写验证请见《Vitess 24.0 分布式集群部署指南》与《Vitess 24.0 常用 CLI 命令与工具详解》。

四、验证

systemctl is-active etcd      # active
systemctl is-active vtctld     # active
systemctl is-active vtgate     # active
systemctl is-active vttablet   # active

端口监听（实测输出）：

port 2379  : LISTEN    ← etcd
port 15999 : LISTEN    ← vtctld gRPC
port 15306 : LISTEN    ← vtgate MySQL 协议

客户端连通：

$ vtctldclient --server 127.0.0.1:15999 GetCellInfoNames
zone1
$ vtctlclient --server 127.0.0.1:15999 ListAllTablets
zone1-0000000100 commerce - replica 127.0.0.1:15100 127.0.0.1:3306 [] <null>

五、FAQ

问题原因与解决
vttablet: running this as root makes no senseVitess 禁止 root。为各服务 Unit 加 User=vitess。
dnf install etcd 报 No matchCentOS 8 仓库无 etcd 包，改用官方二进制。（本文方法）
etcd 启动报 bind: address already in uselisten-client-urls 同时写了 127.0.0.1:2379 与 0.0.0.0:2379，删去其中一个即可。
mysqld: Failed to open required defaults file: .../my.cnfv24 的 mysqlctl init 需通过 --mysqlctl-mycnf-template 指定 my.cnf 模板（BYOI），并提供 config/mycnf/mysql80.cnf 模板。
vtgate 启动报 cells_to_watch validation failed: node doesn't existcell 未注册。先 AddCellInfo 创建 cell 再启 vtgate。
想用 RPM 一键安装dnf install ./vitess-24.0.0-e8d9fa8.x86_64.rpm（官方同时提供 rpm/deb）。

六、卸载

# 停服（每行一个单元）
systemctl stop vttablet
systemctl stop vtgate
systemctl stop vtctld
systemctl stop etcd
systemctl disable vttablet
systemctl disable vtgate
systemctl disable vtctld
systemctl disable etcd
rm -f /etc/systemd/system/vtctld.service \
      /etc/systemd/system/vtgate.service \
      /etc/systemd/system/vttablet.service \
      /etc/systemd/system/etcd.service

# 删除二进制与数据
rm -f /usr/local/bin/vtgate /usr/local/bin/vttablet /usr/local/bin/vtctld \
      /usr/local/bin/vtctlclient /usr/local/bin/vtctldclient \
      /usr/local/bin/mysqlctl /usr/local/bin/vtexplain /usr/local/bin/etcd
rm -rf /var/lib/vitess

# 删除用户
userdel vitess

systemctl daemon-reload

参考链接

CentOS 8 安装 Vitess 24.0 指南 - Quzuo