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

目录

• PolarDB-X 企业版分布式集群部署文档
• • 快速连接
  • • 快速连接命令
  • 集群信息
  • • 集群状态
    • Pod 列表
    • 服务列表
    • 镜像版本
  • 安装步骤
  • • 1. 安装 Helm
    • 2. 创建命名空间
    • 3. 添加 Helm 仓库并安装 Operator
    • 4. 获取最新镜像版本
    • 5. 创建集群配置文件
    • 6. 部署集群
    • 7. 监控部署进度
    • 8. 获取连接密码
  • 集群架构
  • • 架构图
    • 组件说明
  • 连接方式
  • • 方式1: kubectl port-forward (推荐)
    • 方式2: 集群内连接
    • 方式3: 使用内部 Service
    • 方式4: 直接连接 DN (只读)
  • 快速命令参考
  • • 集群状态查看
    • 日志查看
    • 进入容器
    • Pod 名称速查
  • 分布式特性验证
  • • 分区表创建与测试
    • 广播表测试
    • 单表测试
    • CDC 验证
    • 事务测试
  • 故障排查
  • • Pod 启动失败
    • 镜像拉取慢
    • 连接问题
    • 常见错误
  • 卸载步骤
  • 参考资料
  • • 官方文档
    • 开源资源
    • 社区文章
  • 版本信息

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

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

快速连接

快速连接命令

# SSH 到 148
ssh x.148

# 端口转发（在新终端执行）
kubectl port-forward svc/polardbx-demo 3306

# 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

ssh x.148

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

# 验证
helm version
# 输出: version.BuildInfo{Version:"v3.19.5", …}

2. 创建命名空间

kubectl create namespace polardbx-operator-system

3. 添加 Helm 仓库并安装 Operator

# 添加仓库
helm repo add polardbx https://polardbx-charts.oss-cn-beijing.aliyuncs.com

# 安装 Operator
helm install –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 | grep polardbx-demo

# 查看详细信息
kubectl get polardbxcluster -o wide

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

8. 获取连接密码

eval pxc=polardbx-demo
eval user=$(kubectl get secret $pxc -o jsonpath='{.data}' | grep -o '"[^"]*"' | head -1 | tr -d '"')
echo "User: $user"
kubectl get secret $pxc -o jsonpath="{.data['$user']}" | base64 -d – | xargs echo "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-demo 3306

# 在本地连接
mysql -h127.0.0.1 -P3306 -upolardbx_root -pnf9xwvc2

方式2: 集群内连接

# SSH 到 148
ssh x.148

# 进入 CN Pod
kubectl exec -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

# 查看所有 Pods
kubectl get pods | grep polardbx-demo

# 查看 Pods 分布
kubectl get pods -o wide | grep polardbx-demo

# 查看服务
kubectl get svc | grep polardbx-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 容器
kubectl exec -it polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 -c engine — bash

# GMS 容器
kubectl exec -it polardbx-demo-t8ms-gms-cand-0 -c engine — bash

# DN 容器
kubectl exec -it polardbx-demo-t8ms-dn-0-cand-0 -c engine — bash

Pod 名称速查

分布式特性验证

分区表创建与测试

— 查看版本
SELECT version();
— 输出: 8.0.32-X-Cluster-8.4.19-20250825

— 创建分区库
CREATE DATABASE test_db PARTITION_MODE='partitioning';
USE test_db;

— 创建分区表 (自动分片到2个DN)
CREATE TABLE test_table (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(255),
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) PARTITION BY HASH(id) PARTITIONS 8;

— 插入测试数据
INSERT INTO test_table (name) VALUES ('test1'), ('test2'), ('test3');
INSERT INTO test_table (name) VALUES ('data1'), ('data2'), ('data3');

— 查看数据
SELECT * FROM test_table;

— 查看表拓扑分布 (数据分布在哪些DN)
SHOW TOPOLOGY FROM test_table;

— 查看存储节点信息
SHOW STORAGE;

— 查看CN节点信息
SHOW MPP;

— 查看所有数据库
SHOW DATABASES;

— 查看表信息
SHOW TABLES;
SHOW FULL TABLES;

— 查看建表语句
SHOW CREATE TABLE test_table;

广播表测试

— 广播表会在每个DN都存储全量数据
CREATE TABLE broadcast_table (
id INT PRIMARY KEY,
name VARCHAR(100)
) BROADCAST;

INSERT INTO broadcast_table VALUES (1, 'config1'), (2, 'config2');

— 查看拓扑，可以看到在所有DN上都有数据
SHOW TOPOLOGY FROM broadcast_table;

单表测试

— 单表只存储在单个DN上
CREATE TABLE single_table (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
data VARCHAR(255)
) SINGLE;

INSERT INTO single_table (data) VALUES ('single data');

SHOW TOPOLOGY FROM single_table;

CDC 验证

— 查看 Binlog 状态
SHOW MASTER STATUS;

— 查看 Binlog 事件
SHOW BINLOG EVENTS IN 'binlog.000001' FROM 4;

— 查看 Binlog 文件列表
SHOW BINARY LOGS;

事务测试

— 测试分布式事务
BEGIN;
INSERT INTO test_table (name) VALUES ('trans1');
INSERT INTO test_table (name) VALUES ('trans2');
COMMIT;

— 查询验证
SELECT * FROM test_table WHERE name IN ('trans1', 'trans2');

故障排查

Pod 启动失败

# 查看 Pod 状态
kubectl get pods | grep polardbx-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

镜像拉取慢

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

连接问题

# 检查服务状态
kubectl get svc polardbx-demo

# 检查 endpoints
kubectl get endpoints polardbx-demo

# 测试端口转发
kubectl port-forward svc/polardbx-demo 3306

# 进入 Pod 测试内部连接
kubectl exec -it polardbx-demo-t8ms-cn-default-84c4845fdc-5fgz8 — bash
mysql -hpolardbx-demo -upolardbx_root -pnf9xwvc2

常见错误

卸载步骤

# SSH 到 148
ssh x.148

# 1. 删除集群
kubectl delete polardbxcluster polardbx-demo

# 2. 等待 pods 删除完成
kubectl get pods | grep polardbx-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 开发者大会总结

版本信息