Percona Server for MySQL Docker 官方镜像实战指南:启动、配置、备份与生产级运维

原创2026-10-14 23:21:191,857 阅读
文章标签:文档

Percona Server for MySQL Docker 官方镜像实战指南:启动、配置、备份与生产级运维

本文以 docker-library 官方文档仓库中 percona/README.md 为蓝本,系统讲解 Percona Server for MySQL 官方 Docker 镜像的完整使用链路:从镜像标签选型、容器启动与客户端连接,到自定义配置、环境变量、Docker Secrets 与遥测开关,再到数据持久化、备份恢复等生产级运维要点。读者读完本文后,能够独立完成 Percona Server for MySQL 容器的搭建、定制与日常维护,并理解该官方镜像文档在 docker-library 仓库中的生成与维护机制。

Percona Server for MySQL 是什么

Percona Server for MySQL 是 Percona 公司在 MySQL 关系型数据库管理系统基础上维护的一个分支(fork)。它致力于在保持与官方 MySQL 发行版高度兼容的同时,重点强化性能表现与服务器运行状态的可观测性。Percona Server 还内置了 XtraDB——Percona 对 InnoDB 存储引擎的分支实现,这是它区别于社区版 MySQL 的核心特性之一。

在 docker-library 文档仓库中,该镜像的使用说明由 percona/content.md 提供主体内容,最终生成的 percona/README.md 面向 Docker Hub 发布;percona/metadata.json 将其归类于 databases-and-storage 分类。镜像本身的 Dockerfile 由 Percona 官方维护,仓库根目录的 README.md 也说明:每个镜像目录下所有 Markdown 文件均需通过 markdownfmt 格式化校验后才会合入。

镜像标签与版本选型

官方镜像的 "Supported tags" 部分由 .template-helpers/generate-dockerfile-links-partial.sh 结合 bashbrew 从官方镜像清单中动态生成,标签大致分为 MySQL 主线与 MongoDB 分支两组:

Percona Server for MySQL(主线)

标签组 对应版本目录
9.7.2-2、9.7、9、ps-9.7.2-2、ps-9.7、ps-9 percona-server-9.x
8.0.46-37-centos、8.0-centos、8-centos、8.0.46-37、8.0、8、ps-8.0.46-37、ps-8.0、ps-8 percona-server-8.0(含 CentOS 基础镜像变体)

Percona Server for MongoDB(psmdb 分支)

标签组 对应版本目录
psmdb-8.0.32、psmdb-8.0 percona-server-mongodb-8.0
psmdb-7.0.43、psmdb-7.0 percona-server-mongodb-7.0
psmdb-6.0.29、psmdb-6.0 percona-server-mongodb-6.0

从标签结构可以推断:ps- 前缀的标签是 Percona Server 的便捷别名,-centos 后缀表示基于 CentOS 构建的变体;psmdb- 前缀则专门对应 MongoDB 分支镜像。选型时建议优先使用大版本标签(如 8.0、9.7)以便获得补丁更新,生产环境则应锁定精确版本标签(如 8.0.46-37)保证可复现性。本文后续命令中的 tag 请按需替换为上述任一标签。

该镜像当前仅提供 amd64 架构构建,架构信息同样由 .template-helpers/arches.sh 从官方清单动态生成。

快速启动:创建第一个 percona 容器

启动一个 Percona Server for MySQL 实例非常简单:

$ docker run --name some-percona -e MYSQL_ROOT_PASSWORD=my-secret-pw -d percona:tag

参数说明:

  • --name some-percona:为容器指定名称;
  • -e MYSQL_ROOT_PASSWORD=my-secret-pw:设置 MySQL root 超级用户密码;
  • -d percona:tag:以后台守护进程模式运行,tag 指定 MySQL 版本。

注意:MYSQL_ROOT_PASSWORD 是必填项,首次初始化时容器会据此创建 root 账号。

从 MySQL 命令行客户端连接数据库

连接同一 Docker 网络内的 percona 容器

启动另一个 percona 容器实例作为客户端,对原容器执行 SQL:

$ docker run -it --network some-network --rm percona mysql -hsome-percona -uexample-user -p

其中 some-percona 是原数据库容器的名字(需与客户端容器处于同一个 some-network Docker 网络中),-h 指定主机、-u 指定用户,-p 提示输入密码后进入交互式 SQL 会话。

连接非 Docker 或远程实例

该镜像也可直接充当 MySQL 客户端,用于连接宿主机上或远程的 MySQL 服务:

$ docker run -it --rm percona mysql -hsome.mysql.host -usome-mysql-user -p

--rm 保证客户端容器退出后自动清理,适合临时执行 SQL 的场景。

通过 Docker Compose 编排

仓库提供了可直接运行的 percona/compose.yaml,内容如下(默认凭据为 root/example):

# Use root/example as user/password credentials

services:

  db:
    image: percona
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: example

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080

使用步骤:

  1. 将上述内容保存为 compose.yaml;
  2. 运行 docker compose up;
  3. 等待初始化完全完成后,访问 http://localhost:8080(或 http://host-ip:8080)通过 Adminer 图形界面管理数据库。

该编排将数据库容器与 adminer 管理界面容器串联,restart: always 保证服务异常退出后自动拉起。需要说明的是,compose 编排时多个服务会同时启动,若应用容器在数据库初始化完成前就尝试连接,可能因连接被拒绝而失败,具体应对见下文"初始化期间无法连接"一节。

容器 Shell 访问与日志查看

进入容器内部的 bash shell:

$ docker exec -it some-percona bash

查看 MySQL 服务日志(初始化过程、启动报错、慢查询等信息均输出到 Docker 容器日志):

$ docker logs some-percona

这两个命令是排查容器内数据库问题的基础手段:前者用于在容器内直接执行 mysql、mysqld 等工具,后者用于观察启动与运行日志。

自定义 MySQL 配置

使用 /etc/my.cnf.d 目录挂载配置

容器启动配置由 /etc/my.cnf 指定,该文件会包含 /etc/my.cnf.d 目录下所有以 .cnf 结尾的文件,后者的设置会补充或覆盖前者的同名配置项。挂载自定义配置的方法:在宿主机目录中创建配置文件,再将该目录以只读方式挂载到容器的 /etc/my.cnf.d:

$ docker run --name some-percona -v /my/custom:/etc/my.cnf.d -e MYSQL_ROOT_PASSWORD=my-secret-pw -d percona:tag

若宿主机上 /my/custom/config-file.cnf 是自定义配置文件,则上述命令启动的 some-percona 容器会合并 /etc/my.cnf 与 /etc/my.cnf.d/config-file.cnf 的启动设置,且后者优先级更高。注意挂载时只需指定目录路径 /my/custom,容器会自动读取其中全部 .cnf 文件。

不使用 cnf 文件的配置方式

mysqld 支持大量命令行参数,可直接通过 docker run 追加在镜像名之后传入,免去维护 cnf 文件。例如将默认字符集与排序规则改为 UTF-8(utf8mb4):

$ docker run --name some-percona -e MYSQL_ROOT_PASSWORD=my-secret-pw -d percona:tag --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

查看 mysqld 全部可用选项:

$ docker run -it --rm percona:tag --verbose --help

该命令会输出完整的服务器选项清单,可作为参数化配置的权威参考。这种方式适合参数较少、需要临时调整的场景;参数较多时仍建议采用 cnf 文件挂载,便于版本化管理。

环境变量详解

通过 docker run 传入环境变量即可调整实例配置。重要前提:如果数据目录中已存在数据库,下列所有变量将不生效——启动时已有的数据库永远不会被改动。

环境变量 必填 作用与说明
MYSQL_ROOT_PASSWORD 必填 设置 root 超级用户账号的密码
MYSQL_ROOT_HOST 可选 默认 root 可从任意主机连接;设置后仅允许指定主机连接,可用 localhost 实现仅本机访问
MYSQL_DATABASE 可选 启动时自动创建指定名称的数据库;若同时提供了用户/密码,该用户将获得此库的超级权限(相当于 GRANT ALL)
MYSQL_USER / MYSQL_PASSWORD 可选 配合使用以创建新用户并设置密码,该用户对 MYSQL_DATABASE 指定的库拥有超级权限;两个变量必须同时提供才会创建用户
MYSQL_ALLOW_EMPTY_PASSWORD 可选 设为 yes 允许 root 空密码启动。强烈不建议:会使实例完全无保护,任何人可获得完整超级用户权限
MYSQL_RANDOM_ROOT_PASSWORD 可选 设为 yes 时用 pwmake 生成随机初始 root 密码,密码会打印到 stdout(GENERATED ROOT PASSWORD: .....)
MYSQL_ONETIME_PASSWORD 可选 初始化完成后将 root(注意不是 MYSQL_USER 指定的用户)密码标记为已过期,强制首次登录时修改密码。仅 MySQL 5.6+ 支持,5.5 上使用会在初始化时报错
MYSQL_INITDB_SKIP_TZINFO 可选 首次运行时 MySQL 会自动加载本机时区信息以供 CONVERT_TZ() 函数使用;设置此变量可跳过时区加载
INIT_TOKUDB 可选 开启 TokuDB 存储引擎,前提是系统已禁用透明大页(THP)
INIT_ROCKSDB 可选 开启 RocksDB 存储引擎

补充说明:

  • MYSQL_USER / MYSQL_PASSWORD 机制仅用于创建普通业务用户,root 超级用户始终由 MYSQL_ROOT_PASSWORD 创建,无需也不应通过该机制重复创建;
  • MYSQL_ONETIME_PASSWORD 强制改密机制在合规审计场景下很有价值,可避免初始化密码长期留在默认状态;
  • INIT_TOKUDB 依赖 THP 禁用,部署前需确认宿主内核参数,否则引擎无法激活。

Docker Secrets:免明文密码传递

作为环境变量传参的替代方案,可在上述环境变量名后追加 _FILE 后缀,初始化脚本会从容器内文件中读取对应值,特别适用于从 Docker secrets(存放于 /run/secrets/<secret_name>)加载密码:

$ docker run --name some-mysql -e MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mysql-root -d percona:tag

当前仅支持以下变量的 _FILE 形式:MYSQL_ROOT_PASSWORD、MYSQL_ROOT_HOST、MYSQL_DATABASE、MYSQL_USER、MYSQL_PASSWORD。这一机制让敏感信息与命令历史、compose 文件解耦,是容器化部署中规避密码泄露的最佳实践之一。

Telemetry 遥测控制

自 Percona Server 8.0.35-27 起,遥测功能默认开启,会向 Percona 发送使用数据。如不希望上报,可设置环境变量 PERCONA_TELEMETRY_DISABLE=1:

$ docker run --name some-mysql -e PERCONA_TELEMETRY_DISABLE=1 -d percona:tag

对数据出境合规敏感的生产环境,建议在初始化参数中显式加入该开关。

初始化全新实例

容器首次启动时,会创建指定名称的新数据库,并依据提供的配置变量完成初始化。此外,容器会按字母顺序执行 /docker-entrypoint-initdb.d 目录下所有 .sh、.sql 和 .sql.gz 文件:

  • 通过绑定挂载将 SQL 转储文件放入该目录,即可在首次启动时自动导入数据;
  • 也可以基于镜像构建自定义镜像,把初始化脚本打进 /docker-entrypoint-initdb.d;
  • .sql 文件默认导入到 MYSQL_DATABASE 指定的数据库中。

这是"开箱即用"初始化测试数据、预置表结构、导入历史转储的标准入口,执行顺序由文件名决定,命名时可用 01_xxx.sql、02_xxx.sql 控制先后依赖。

Caveats:生产运维注意事项

数据存放位置(数据持久化)

Docker 容器中的数据默认不持久,重启/删除容器会导致数据丢失。官方镜像提供两种数据存储方式:

方式一:Docker 卷(默认)

由 Docker 内部卷管理将数据库文件写入宿主机磁盘,透明易用,缺点是宿主机上的工具与程序难以直接定位和访问这些文件。

方式二:宿主目录绑定挂载(推荐生产使用)

将宿主机上的数据目录挂载为容器内 MySQL 默认的数据目录 /var/lib/mysql:

  1. 在宿主机合适位置创建数据目录,例如 /my/own/datadir;
  2. 启动容器时挂载:
$ docker run --name some-percona -v /my/own/datadir:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d percona:tag

-v /my/own/datadir:/var/lib/mysql 将宿主机目录映射为容器内 /var/lib/mysql(MySQL 默认写数据文件的位置),数据从此位于宿主机已知路径,方便直接备份与迁移。缺点是需要自行保证目录存在,并正确配置目录权限与宿主安全机制。

初始化完成前无法连接

容器启动时若尚无已初始化的数据库,会先创建默认数据库,在初始化完成之前不接受任何外部连接。这在 Docker Compose 等多容器同时启动的自动化场景中容易引发问题:应用容器可能先于数据库就绪而连接失败。

若应用无法优雅处理数据库未就绪的情况,应在服务启动前加入连接重试循环。docker-library 官方镜像中已有此类实现范例(如 WordPress、Bonita 的 entrypoint 脚本),可参考其思路:轮询 mysqladmin ping 或尝试建连直到成功后再启动业务进程。

对接已有数据库

如果启动容器时数据目录中已包含数据库(具体表现为存在 mysql 子目录),则应省略 MYSQL_ROOT_PASSWORD 变量——即便传入也会被忽略,且已有数据库不会被以任何方式改动。这一行为保证了挂载旧数据目录时不会误重置密码或破坏既有数据。

创建数据库转储(备份)

大多数常规工具均可使用,但为确保能访问到 mysqld 服务,最稳妥的方式是借助 docker exec 在同一容器内执行备份工具:

$ docker exec some-percona sh -c 'exec mysqldump --all-databases -uroot -p"$MYSQL_ROOT_PASSWORD"' > /some/path/on/your/host/all-databases.sql

该命令将容器内 mysqldump 的全库导出重定向到宿主机文件;sh -c 'exec ...' 包裹可确保直接以 shell 替换方式运行,密码通过容器内已注入的环境变量 $MYSQL_ROOT_PASSWORD 引用,避免明文出现在命令中。

从转储文件恢复数据

恢复使用 docker exec 的 -i(交互)标志,将宿主机转储文件反向喂入容器内的 mysql 客户端:

$ docker exec -i some-percona sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < /some/path/on/your/host/all-databases.sql

备份与恢复命令互为逆操作,二者组合即可形成完整的容器化数据保全流程。

附:镜像文档的生成与维护机制

本文依据的 percona/README.md 并非手工维护,而是自动生成产物:其文件头部的 WARNING 注释明确声明"由 percona/ 目录下其他文件结合模板生成"。具体生成链路如下:

  1. 内容源文件:percona/content.md 保存了"如何使用本镜像"的正文(启动、连接、配置、环境变量、初始化、注意事项等);
  2. 模板骨架:.template-helpers/template.md 定义了 README 的整体版式,通过 %%MAINTAINER%%、%%TAGS%%、%%ARCHES%%、%%CONTENT%%、%%LOGO%%、%%COMPOSE%%、%%LICENSE%% 等占位符拼装各组成部分;
  3. 生成脚本:update.sh 读取 content.md、compose.yaml、license.md、metadata.json 等文件,调用 .template-helpers/generate-dockerfile-links-partial.sh 与 .template-helpers/arches.sh(均依赖 bashbrew 解析官方镜像清单)动态生成标签列表与架构列表,最终产出 README;
  4. 元数据校验:metadata.sh 负责校验各镜像 metadata.json 的 JSON 格式、分类合法性(分类需取自根目录 metadata.json 定义的枚举,且不超过 3 个),percona 的分类为 databases-and-storage。

理解这套机制有助于在查阅其他官方镜像文档时快速定位"正文源头"(content.md)与"配套资源"(compose.yaml、license.md 等),也解释了为何 Docker Hub 上的镜像描述与仓库 README 始终保持同步。

License 说明

镜像内软件(Percona Server for MySQL)的许可信息见 percona/license.md。与所有 Docker 镜像一样,镜像内还可能包含基于其他许可证分发的软件(如基础发行版自带的 Bash 等),以及主软件的直接或间接依赖。镜像的最终使用者有责任确认对镜像内所有软件的使用均符合相应许可证要求。

登录后查看全文
docs