percona/percona-xtradb-cluster

Percona XtraDB Cluster Docker 镜像文档

1. 镜像概述与主要用途

Percona XtraDB Cluster Docker 镜像是 Percona XtraDB Cluster 的容器化版本，镜像地址为 percona/percona-xtradb-cluster。该镜像支持在 Docker 网络（包括覆盖网络 overlay network）中运行，允许在不同主机上部署 Percona XtraDB Cluster 节点，从而构建跨主机的高可用 MySQL 集群。

主要用途：简化 Percona XtraDB Cluster 的部署与管理，提供开箱即用的高可用 MySQL 集群解决方案，适用于需要数据同步复制、故障自动转移的场景。

2. 核心功能与特性

• Docker 网络支持：兼容 Docker bridge 网络和 overlay 网络，支持跨主机节点通信。
• 灵活配置：通过环境变量实现集群参数配置，无需手动修改配置文件。
• 服务发现：集成 etcd 发现服务，支持新节点自动发现并加入现有集群。
• XtraBackup 集成：默认创建 xtrabackup@localhost 用户，支持 XtraBackup SST（State Snapshot Transfer）数据同步方式，可通过环境变量设置密码。
• ProxySQL 集成：与 Percona ProxySQL 镜像无缝集成，实现集群负载均衡和高可用管理。

3. 使用场景与适用范围

• 开发/测试环境：快速部署 Percona XtraDB Cluster 集群，验证高可用方案。
• 生产环境：构建跨主机的高可用 MySQL 集群，保障业务连续性。
• 分布式部署：通过 Docker overlay 网络在多主机环境中部署集群节点，提升集群扩展性。

4. 产品文档

• 版本 5.7
• 版本 8.0

5. 使用方法与配置说明

5.1 环境准备

5.1.1 创建 Docker 网络

集群节点需在同一 Docker 网络中通信。默认情况下，镜像会尝试创建名为 ${CLUSTER_NAME}_net 的 overlay 网络。若需自定义网络（如 bridge 网络或指定参数），可提前创建：

bash
# 示例：创建 bridge 网络
export CLUSTER_NAME=cluster1
docker network create -d bridge ${CLUSTER_NAME}_net

5.2 配置参数说明

5.3 启动集群节点

5.3.1 使用发现服务（etcd）启动集群

前提：已部署 etcd 服务（见 6. 发现服务）。

1. 设置环境变量：

   bash
   export CLUSTER_NAME=cluster1
   export ETCD_HOST=10.20.2.4:2379  # etcd 服务地址
   export MYSQL_ROOT_PASSWORD=Theistareyk  # root 密码
   export NETWORK_NAME=${CLUSTER_NAME}_net
   

2. 创建 Docker 网络（若未提前创建）：

   bash
   docker network create -d overlay $NETWORK_NAME  # overlay 网络支持跨主机通信
   

3. 启动第一个集群节点（创建新集群）：

   bash
   docker run -d \
     --name ${CLUSTER_NAME}_node1 \
     --net $NETWORK_NAME \
     -e CLUSTER_NAME=$CLUSTER_NAME \
     -e DISCOVERY_SERVICE=$ETCD_HOST \
     -e MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD \
     -e XTRABACKUP_PASSWORD=xtrabackup_pass  # 可选，xtrabackup 用户密码
     percona/percona-xtradb-cluster
   

4. 启动后续节点（自动加入集群）：

   bash
   docker run -d \
     --name ${CLUSTER_NAME}_node2 \
     --net $NETWORK_NAME \
     -e CLUSTER_NAME=$CLUSTER_NAME \
     -e DISCOVERY_SERVICE=$ETCD_HOST \
     -e MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD \
     -e XTRABACKUP_PASSWORD=xtrabackup_pass \
     percona/percona-xtradb-cluster
   

5.3.2 不使用发现服务启动集群

通过 CLUSTER_JOIN 指定现有集群节点 IP 列表，手动加入集群。

1. 设置环境变量：

   bash
   export CLUSTER_NAME=cluster1
   export MYSQL_ROOT_PASSWORD=Theistareyk
   export NETWORK_NAME=${CLUSTER_NAME}_net
   

2. 创建 Docker 网络：

   bash
   docker network create -d bridge $NETWORK_NAME  # bridge 网络（单主机）或 overlay（跨主机）
   

3. 启动第一个节点（创建新集群，CLUSTER_JOIN 为空）：

   bash
   docker run -d \
     --name ${CLUSTER_NAME}_node1 \
     --net $NETWORK_NAME \
     -e CLUSTER_NAME=$CLUSTER_NAME \
     -e CLUSTER_JOIN="" \  # 空值表示创建新集群
     -e MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD \
     percona/percona-xtradb-cluster
   

4. 获取第一个节点的 IP（用于后续节点加入）：

   bash
   NODE1_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ${CLUSTER_NAME}_node1)
   

5. 启动第二个节点（加入现有集群）：

   bash
   docker run -d \
     --name ${CLUSTER_NAME}_node2 \
     --net $NETWORK_NAME \
     -e CLUSTER_NAME=$CLUSTER_NAME \
     -e CLUSTER_JOIN=$NODE1_IP \  # 指定第一个节点 IP
     -e MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD \
     percona/percona-xtradb-cluster
   

6. 发现服务

6.1 概述

发现服务（当前仅支持 etcd）用于集群节点注册，新节点或 ProxySQL 可通过发现服务自动发现集群中的运行节点，简化集群扩展和管理。

6.2 使用方法

6.2.1 查看集群注册信息

通过 etcd API 查看集群节点注册状态：

bash
curl http://$ETCD_HOST/v2/keys/pxc-cluster/$CLUSTER_NAME/?recursive=true | jq

示例输出：

json
{
  "action": "get",
  "node": {
    "key": "/pxc-cluster/cluster4",
    "dir": true,
    "nodes": [
      {
        "key": "/pxc-cluster/cluster4/10.0.5.2",
        "dir": true,
        "nodes": [
          {
            "key": "/pxc-cluster/cluster4/10.0.5.2/ipaddr",
            "value": "10.0.5.2",
            "modifiedIndex": 19600,
            "createdIndex": 19600
          },
          {
            "key": "/pxc-cluster/cluster4/10.0.5.2/hostname",
            "value": "2af0a75ce0cb",
            "modifiedIndex": 19601,
            "createdIndex": 19601
          }
        ]
      }
    ]
  }
}

6.2.2 清理注册信息

etcd 注册信息不会自动清理，可手动删除集群所有注册记录：

bash
curl http://$ETCD_HOST/v2/keys/pxc-cluster/$CLUSTER_NAME?recursive=true -XDELETE

6.3 启动 etcd 服务

etcd 是分布式键值存储，用于集群发现。以下是单节点 etcd 的启动脚本：

bash
ETCD_HOST=${ETCD_HOST:-10.20.2.4:2379}  # 默认 etcd 地址
docker run -d \
  -v /usr/share/ca-certificates/:/etc/ssl/certs \
  -p 4001:4001 -p 2380:2380 -p 2379:2379 \
  --name etcd \
  quay.io/coreos/etcd \
  -name etcd0 \
  -advertise-client-urls http://${ETCD_HOST}:2379,http://${ETCD_HOST}:4001 \
  -listen-client-urls http://0.0.0.0:2379,http://0.0.0.0:4001 \
  -initial-advertise-peer-urls http://${ETCD_HOST}:2380 \
  -listen-peer-urls http://0.0.0.0:2380 \
  -initial-cluster-token etcd-cluster-1 \
  -initial-cluster etcd0=http://${ETCD_HOST}:2380 \
  -initial-cluster-state new

完整 etcd 文档：[***]

7. 与 ProxySQL 集成

ProxySQL 是 MySQL 负载均衡代理，可与 Percona XtraDB Cluster 及 etcd 发现服务集成，实现读写分离和节点故障自动转移。

7.1 启动 ProxySQL 容器

使用 perconalab/proxysql 镜像启动 ProxySQL，需指定集群名称、etcd 地址及数据库凭证：

bash
docker run -d \
  -p 3306:3306 -p 6032:6032 \  # 3306: 客户端端口；6032: 管理端口
  --net $NETWORK_NAME \
  --name ${CLUSTER_NAME}_proxysql \
  -e CLUSTER_NAME=$CLUSTER_NAME \
  -e ETCD_HOST=$ETCD_HOST \
  -e MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD \  # 集群节点 root 密码（用于注册代理用户）
  -e MYSQL_PROXY_USER=proxyuser \  # 代理用户名称
  -e MYSQL_PROXY_PASSWORD=s3cret \  # 代理用户密码
  perconalab/proxysql

环境变量说明：

• MYSQL_PROXY_USER/MYSQL_PROXY_PASSWORD：ProxySQL 用于连接集群节点的用户，会自动在所有集群节点注册。

7.2 注册集群节点到 ProxySQL

启动后，执行以下命令将集群节点注册到 ProxySQL：

bash
docker exec -it ${CLUSTER_NAME}_proxysql add_cluster_nodes.sh

附录：Docker 覆盖网络参考

Docker overlay 网络支持跨主机容器通信，详细配置步骤可参考：[***]