PolarDB-X 企业版分布式集群部署文档

部署日期: 2026-01-22
部署环境: x.148 (K8s v1.24.10)
节点列表: qfusion1, qfusion2, qfusion3, qfusion4

快速连接

快速连接命令

# SSH 到 148sshx.148# 端口转发（在新终端执行）kubectl port-forward svc/polardbx-demo3306# MySQL 连接mysql -h127.0.0.1 -P3306 -upolardbx_root -pnf9xwvc2

集群信息

集群状态

架构

Pod 列表

# GMS (3副本 Paxos) polardbx-demo-t8ms-gms-cand-0 (qfusion3) polardbx-demo-t8ms-gms-cand-1 (qfusion4) polardbx-demo-t8ms-gms-log-0 (qfusion2) # DN-0 (3副本) polardbx-demo-t8ms-dn-0-cand-0 (qfusion4) polardbx-demo-t8ms-dn-0-cand-1 (qfusion2) polardbx-demo-t8ms-dn-0-log-0 (qfusion1) # DN-1 (3副本) polardbx-demo-t8ms-dn-1-cand-0 (qfusion1) polardbx-demo-t8ms-dn-1-cand-1 (qfusion3) polardbx-demo-t8ms-dn-1-log-0 (qfusion4) # CN (2个计算节点) polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 polardbx-demo-t8ms-cn-default-84c4845fdc-qhm9f # CDC polardbx-demo-t8ms-cdc-default-7b8f4bc45-snp74

服务列表

镜像版本

安装步骤

1. 安装 Helm

sshx.148curl-fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3chmod700get_helm.sh ./get_helm.sh# 验证helm version# 输出: version.BuildInfo{Version:"v3.19.5", ...}

2. 创建命名空间

kubectl create namespace polardbx-operator-system

3. 添加 Helm 仓库并安装 Operator

# 添加仓库helm repoaddpolardbx https://polardbx-charts.oss-cn-beijing.aliyuncs.com# 安装 Operatorhelminstall--namespace polardbx-operator-system polardbx-operator polardbx/polardbx-operator# 验证 Operator 状态kubectl get pods -n polardbx-operator-system

Operator 组件:

• polardbx-clinic
• polardbx-controller-manager
• polardbx-hpfs (多个副本)
• polardbx-tools-updater (多个副本)

4. 获取最新镜像版本

curl-s"https://polardbx-opensource.oss-cn-hangzhou.aliyuncs.com/scripts/get-version.sh"|sh

输出:

CN polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-sql:v2.4.2_5.4.19 DN polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-engine:v2.4.2_8.4.19 CDC polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-cdc:v2.4.2_5.4.19

5. 创建集群配置文件

cat>/tmp/polardbx-enterprise.yaml<<'EOF' apiVersion: polardbx.aliyun.com/v1 kind: PolarDBXCluster metadata: name: polardbx-demo namespace: default spec: topology: nodes: gms: template: image: polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-engine:v2.4.2_8.4.19 resources: requests: cpu: 500m memory: 1Gi limits: cpu: 2 memory: 4Gi cn: replicas: 2 template: image: polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-sql:v2.4.2_5.4.19 resources: requests: cpu: 500m memory: 1Gi limits: cpu: 2 memory: 4Gi dn: replicas: 2 template: image: polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-engine:v2.4.2_8.4.19 resources: requests: cpu: 500m memory: 1Gi limits: cpu: 2 memory: 4Gi cdc: replicas: 1 template: image: polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-cdc:v2.4.2_5.4.19 resources: requests: cpu: 500m memory: 1Gi limits: cpu: 2 memory: 4Gi EOF

6. 部署集群

kubectl apply -f /tmp/polardbx-enterprise.yaml

7. 监控部署进度

# 实时监控集群状态kubectl get polardbxcluster -w# 查看 Pods 状态kubectl get pods|greppolardbx-demo# 查看详细信息kubectl get polardbxcluster -o wide

部署时间约 25-30 分钟（镜像拉取需要时间）

8. 获取连接密码

evalpxc=polardbx-demoevaluser=$(kubectl get secret $pxc -ojsonpath='{.data}'|grep-o'"[^"]*"'|head-1|tr-d'"')echo"User:$user"kubectl get secret$pxc-ojsonpath="{.data['$user']}"|base64 -d -|xargsecho"Password:"

输出:

User: polardbx_root Password: nf9xwvc2

集群架构

PolarDB-X 企业版采用分布式架构，主要组件包括：

架构图

┌─────────────────────────────────────────────────────────────┐ │ PolarDB-X 集群 │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ CN Node 1 │ │ CN Node 2 │ ← 计算节点 (无状态) │ │ │ (SQL解析) │ │ (SQL执行) │ │ │ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ └────────┬─────────┘ │ │ ▼ │ │ ┌──────────────────────────────────┐ │ │ │ GMS Cluster │ ← 全局元服务 │ │ │ (cand-0, cand-1, log-0) │ (3副本 Paxos) │ │ └──────────────────────────────────┘ │ │ │ │ │ ┌────────┴────────┐ │ │ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ DN Group 0 │ │ DN Group 1 │ ← 数据节点 │ │ │ (cand-0/1) │ │ (cand-0/1) │ (各3副本) │ │ │ (log-0) │ │ (log-0) │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ │ │ │ CDC │ ← 变更数据捕获 │ │ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘

组件说明

连接方式

方式1: kubectl port-forward (推荐)

# 在 x.148 上执行端口转发kubectl port-forward svc/polardbx-demo3306# 在本地连接mysql -h127.0.0.1 -P3306 -upolardbx_root -pnf9xwvc2

方式2: 集群内连接

# SSH 到 148sshx.148# 进入 CN Podkubectlexec-it polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 --bash# 连接数据库mysql -hpolardbx-demo -upolardbx_root -pnf9xwvc2

方式3: 使用内部 Service

# 在集群内的任意 Pod 中连接mysql -hpolardbx-demo.default.svc.cluster.local -P3306 -upolardbx_root -pnf9xwvc2

方式4: 直接连接 DN (只读)

# 连接 DN-0 只读副本mysql -hpolardbx-demo-t8ms-dn-0-ro -upolardbx_root -pnf9xwvc2

快速命令参考

集群状态查看

# 查看集群状态kubectl get polardbxcluster# 查看所有 Podskubectl get pods|greppolardbx-demo# 查看 Pods 分布kubectl get pods -o wide|greppolardbx-demo# 查看服务kubectl get svc|greppolardbx-demo# 实时监控kubectl get polardbxcluster -w

日志查看

# CN 日志kubectl logs -f polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 -c engine# GMS 日志kubectl logs -f polardbx-demo-t8ms-gms-cand-0 -c engine# DN 日志kubectl logs -f polardbx-demo-t8ms-dn-0-cand-0 -c engine# CDC 日志kubectl logs -f polardbx-demo-t8ms-cdc-default-7b8f4bc45-snp74 -c engine

进入容器

# CN 容器kubectlexec-it polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 -c engine --bash# GMS 容器kubectlexec-it polardbx-demo-t8ms-gms-cand-0 -c engine --bash# DN 容器kubectlexec-it polardbx-demo-t8ms-dn-0-cand-0 -c engine --bash

Pod 名称速查

分布式特性验证

分区表创建与测试

-- 查看版本SELECTversion();-- 输出: 8.0.32-X-Cluster-8.4.19-20250825-- 创建分区库CREATEDATABASEtest_db PARTITION_MODE='partitioning';USEtest_db;-- 创建分区表 (自动分片到2个DN)CREATETABLEtest_table(idBIGINTAUTO_INCREMENTPRIMARYKEY,nameVARCHAR(255),create_timeTIMESTAMPDEFAULTCURRENT_TIMESTAMP)PARTITIONBYHASH(id)PARTITIONS8;-- 插入测试数据INSERTINTOtest_table(name)VALUES('test1'),('test2'),('test3');INSERTINTOtest_table(name)VALUES('data1'),('data2'),('data3');-- 查看数据SELECT*FROMtest_table;-- 查看表拓扑分布 (数据分布在哪些DN)SHOWTOPOLOGYFROMtest_table;-- 查看存储节点信息SHOWSTORAGE;-- 查看CN节点信息SHOWMPP;-- 查看所有数据库SHOWDATABASES;-- 查看表信息SHOWTABLES;SHOWFULLTABLES;-- 查看建表语句SHOWCREATETABLEtest_table;

广播表测试

-- 广播表会在每个DN都存储全量数据CREATETABLEbroadcast_table(idINTPRIMARYKEY,nameVARCHAR(100))BROADCAST;INSERTINTObroadcast_tableVALUES(1,'config1'),(2,'config2');-- 查看拓扑，可以看到在所有DN上都有数据SHOWTOPOLOGYFROMbroadcast_table;

单表测试

-- 单表只存储在单个DN上CREATETABLEsingle_table(idBIGINTAUTO_INCREMENTPRIMARYKEY,dataVARCHAR(255))SINGLE;INSERTINTOsingle_table(data)VALUES('single data');SHOWTOPOLOGYFROMsingle_table;

CDC 验证

-- 查看 Binlog 状态SHOWMASTERSTATUS;-- 查看 Binlog 事件SHOWBINLOG EVENTSIN'binlog.000001'FROM4;-- 查看 Binlog 文件列表SHOWBINARYLOGS;

事务测试

-- 测试分布式事务BEGIN;INSERTINTOtest_table(name)VALUES('trans1');INSERTINTOtest_table(name)VALUES('trans2');COMMIT;-- 查询验证SELECT*FROMtest_tableWHEREnameIN('trans1','trans2');

故障排查

Pod 启动失败

# 查看 Pod 状态kubectl get pods|greppolardbx-demo# 查看 Pod 详情kubectl describe pod<pod-name># 查看容器日志kubectl logs<pod-name>-c engine kubectl logs<pod-name>-c exporter kubectl logs<pod-name>-c prober

镜像拉取慢

# 在各个节点上预拉取镜像dockerpull polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-engine:v2.4.2_8.4.19dockerpull polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-sql:v2.4.2_5.4.19dockerpull polardbx-opensource-registry.cn-beijing.cr.aliyuncs.com/polardbx/polardbx-cdc:v2.4.2_5.4.19

连接问题

# 检查服务状态kubectl get svc polardbx-demo# 检查 endpointskubectl get endpoints polardbx-demo# 测试端口转发kubectl port-forward svc/polardbx-demo3306# 进入 Pod 测试内部连接kubectlexec-it polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 --bashmysql -hpolardbx-demo -upolardbx_root -pnf9xwvc2

常见错误

卸载步骤

# SSH 到 148sshx.148# 1. 删除集群kubectl delete polardbxcluster polardbx-demo# 2. 等待 pods 删除完成kubectl get pods|greppolardbx-demo# 3. 删除 Operator (可选)helm uninstall --namespace polardbx-operator-system polardbx-operator# 4. 删除 CRD (可选，谨慎操作)kubectl delete crds polardbxclusters.polardbx.aliyun.com xstores.polardbx.aliyun.com# 5. 删除命名空间 (可选)kubectl delete namespace polardbx-operator-system

参考资料

官方文档

• PolarDB-X 官方网站
• PolarDB-X 产品文档
• K8S 快速开始
• PXD 部署文档

开源资源

• PolarDB-X GitHub
• PolarDB-X Operator GitHub
• PolarDB-X Charts

社区文章

• K8S 部署阿里云PolarDB-X 集群教程
• PolarDB 2026 开发者大会总结

版本信息