instantlinux/mariadb-galera

mariadb-galera

镜像概述和主要用途

该镜像提供MariaDB 12.x版本，支持在Kubernetes/Swarm环境下自动生成集群，使用命名卷实现数据持久化。基于MariaDB/Galera文档实现了健壮的引导逻辑，可自动完成集群创建和节点加入操作。集群运行需要etcd实例用于共享节点健康状态数据。

核心功能和特性

• 自动集群管理：基于Galera协议实现集群的自动创建与节点加入
• 数据持久化：使用命名卷存储数据库数据，确保数据不丢失
• 跨平台支持：兼容Kubernetes和Docker Swarm编排环境
• 健壮引导逻辑：遵循MariaDB/Galera官方文档实现的集群引导流程，避免启动故障
• 灵活配置：支持通过配置文件自定义数据库参数
• 日志管理：日志输出到stdout/stderr，慢查询日志可通过卷挂载持久化

使用场景和适用范围

适用于需要高可用MariaDB集群的企业级应用场景，尤其适合：

• 需要数据库服务持续可用的业务系统
• 需实现读写分离以提升性能的应用
• 基于Kubernetes或Docker Swarm的容器化部署环境
• 3节点、5节点或更大规模的集群部署需求

使用方法和配置说明

Kubernetes环境使用

在启动集群前，需定义以下依赖项：root密码、网络负载均衡器和专用etcd键值存储。步骤如下：

创建随机root密码：

bash
SECRET=mysql-root-password
PW=$(uuidgen | base64)
cat >/dev/shm/new.yaml <<EOT
---
apiVersion: v1
data:
  $SECRET: $PW
kind: Secret
metadata:
  name: $SECRET
  namespace: \$K8S_NAMESPACE
type: Opaque
EOT
sekret enc /dev/shm/new.yaml >secrets/$SECRET
rm /dev/shm/new.yaml

可使用https://github.com/mozilla/sops%E6%88%96https://github.com/nownabe/sekret%E7%AD%89%E5%B7%A5%E5%85%B7%E7%94%9F%E6%88%90%E5%AF%86%E9%92%A5%E6%96%87%E4%BB%B6%E3%80%82

配置my.cnf： 通过卷挂载/etc/mysql/my.cnf.d目录（映射为$ADMIN_PATH/mariadb/etc/）添加本地my.cnf配置。在Kubernetes环境中建议使用ConfigMap（示例已包含）。

网络配置

容器在入口网络暴露3306、4444、4567和4568端口。集群同步流量和备份（使用mariabackup或此处提供的mysqldump容器）需要内部网络。若需直接连接各集群节点进行写安全访问或故障排除，在较新版本Docker中可覆盖入口负载均衡器：

yaml
version: "3.2"
services:
  db:
    ...
    ports:
    - target: 3306
      published: <端口>
      protocol: tcp
      mode: host

建议为发布端口使用单独的负载均衡器。此方法在https://github.com/instantlinux/docker-tools/blob/main/images/mariadb-galera/kubernetes.yaml%E4%B8%AD%E6%9C%89%E8%AF%A6%E7%BB%86%E5%AE%9A%E4%B9%89%E5%92%8C%E8%AF%B4%E6%98%8E%E3%80%82

DNS名称与读写分离

使用MariaDB技术时，写入性能受集群中性能最差节点的I/O吞吐量限制，而读取性能可在整个集群扩展，仅受网络容量限制。

若在集群中分散数据库写入流量，性能会比单节点更差，原因如多主冲突所述。日志会出现类似以下消息：

WSREP: MDL conflict db=jira7 table=rundetails ticket=6 solved by abort

且集群性能不稳定。解决步骤：

1. 在局域网分配两个静态IP地址
2. 定义主DNS名称和只读DNS名称（如db.mysite.com和db-ro.mysite.com），并为两个IP添加A记录
3. 为主IP配置haproxy（或其他）负载均衡器，配置一个集群节点作为主服务节点，其他节点作为备份
4. 将内置Docker或Kubernetes服务绑定到所有集群成员

Docker Swarm用户需自行配置，Kubernetes用户可通过https://github.com/instantlinux/docker-tools/blob/main/images/mariadb-galera/kubernetes.yaml%E5%92%8Chttps://github.com/instantlinux/docker-tools/blob/main/k8s/Makefile%E8%87%AA%E5%8A%A8%E5%8C%96%E8%BF%99%E4%BA%9B%E6%AD%A5%E9%AA%A4%EF%BC%88%E9%9C%80%E5%85%88%E8%AE%BE%E7%BD%AE%E4%B8%A4%E4%B8%AADNS%E6%9D%A1%E7%9B%AE%EF%BC%89%E3%80%82

日志管理

日志默认输出到stdout/stderr，慢查询日志除外。如需保留慢查询日志，需挂载/var/log/mysql卷。

etcd设置

在Kubernetes下启动etcd可参考https://github.com/instantlinux/docker-tools/blob/main/k8s/Makefile%E4%B8%AD%E7%9A%84%60make etcd`命令。Docker Compose服务定义见https://github.com/instantlinux/docker-tools/tree/main/services/etcd%EF%BC%8C%E5%85%B6%E4%B8%AD%E5%8C%85%E5%90%AB%E4%BD%BF%E7%94%A8%E5%85%8D%E8%B4%B9discovery.etc.io%E5%BC%95%E5%AF%BC%E6%9C%8D%E5%8A%A1%E7%9A%84%E8%AF%B4%E6%98%8E%E3%80%82

该仓库提供完整的https://github.com/instantlinux/docker-tools/blob/main/k8s/README.md%EF%BC%8C%E5%85%8B%E9%9A%86%E4%BB%93%E5%BA%93%E5%90%8E%E5%8F%AF%E9%80%9A%E8%BF%87https://github.com/instantlinux/docker-tools/tree/main/images/mariadb-galera/helm%E6%88%96https://github.com/instantlinux/docker-tools/blob/main/images/mariadb-galera/kubernetes.yaml%E4%BD%BF%E7%94%A8%60make%60%E5%91%BD%E4%BB%A4%E5%90%AF%E5%8A%A8%EF%BC%8C%E5%B9%B6%E8%87%AA%E5%AE%9A%E4%B9%89https://github.com/instantlinux/docker-tools/blob/main/k8s/Makefile.vars%EF%BC%9A

bash
git clone https://github.com/instantlinux/docker-tools.git
cd docker-tools/k8s
# 此make目标在Makefile.instances中定义
make db00

重启集群

停止数据库时，需等待所有pod停止，然后清除etcd中集群条目：

bash
CLUSTER=db00
ETCD_HOST=10.101.1.19
etcdctl --endpoints=$ETCD_HOST:2379 del --prefix /galera/$CLUSTER

然后通过helm chart或docker-compose启动。

Swarm环境使用

该镜像最初基于Docker Swarm开发，https://github.com/instantlinux/docker-tools/blob/main/images/mariadb-galera/docker.compose%E6%96%87%E4%BB%B6%E4%B8%BA%E9%81%97%E7%95%99%E5%AE%9E%E7%8E%B0%E3%80%82%E5%9C%A8stack%E9%83%A8%E7%BD%B2%E5%89%8D%EF%BC%8C%E9%9C%80%E4%BD%BF%E7%94%A8%60docker secret create生成mysql-root-password密钥，并定义指向my.cnf位置的ADMIN_PATH`环境变量（需在每个docker节点相同位置）。

环境变量

注意事项

• 该镜像创建于2017年初，当时Docker Swarm下的数据库集群技术尚不成熟，作者未能找到可在简单"docker stack deploy; docker stack rm; docker stack deploy"循环测试中自动重启且无问题（如脑裂或无法启动）的集群解决方案。本镜像解决了此问题，使用最小化发行版（尝试过Alpine Linux，最终使用debian）。
• Galera在重启时较为敏感，需要大量逻辑处理边缘情况。
• 容器镜像适用于3节点、5节点或更大规模配置，需要稳定的etcd配置用于节点发现和重启时的主节点选举。单实例可使用kubernetes-single.yaml部署，无需高可用资源。
• 截至2025年10月，尚无支持Python3的etcd3库。目前使用2020年最后更新的python-etcd3 0.12.0，通过设置PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION确保兼容性。

致谢

感谢severalnines的ashraf-s9s提供健康检查脚本。

贡献

如需改进此镜像，请参阅https://github.com/instantlinux/docker-tools/blob/main/CONTRIBUTING.md%E3%80%82