Percona Docker镜像文档

注意事项

本镜像为percona官方镜像的amd64架构构建版本。更多信息请参见官方镜像文档中的"非amd64架构说明"和官方镜像FAQ中的"镜像源在Git中变更后如何处理"。

快速参考

• 维护者：
  Percona

• 获取帮助：
  Docker社区Slack、Server Fault、Unix & Linux或Stack Overflow

支持的标签及对应的Dockerfile链接

• 8.0.43-34-centos, 8.0-centos, 8-centos, 8.0.43-34, 8.0, 8, ps-8.0.43-34, ps-8.0, ps-8

• psmdb-8.0.12, psmdb-8.0

• psmdb-7.0.24, psmdb-7.0

• psmdb-6.0.25, psmdb-6.0

快速参考（续）

• 问题反馈：
  Percona Server相关问题请提交至Percona Server JIRA（需创建账号）。

• 支持的架构：(更多信息)
  amd64

• 镜像 artifact 详情：
  repo-info仓库的repos/percona/目录（历史记录）
  （包含镜像元数据、传输大小等）

• 镜像更新：
  official-images仓库的library/percona标签
  official-images仓库的library/percona文件（历史记录）

• 本文档来源：
  docs仓库的percona/目录（历史记录）

Percona Server for MySQL简介

Percona Server for MySQL是由Percona创建的MySQL关系型数据库管理系统分支。它旨在保持与官方MySQL版本的高度兼容性，同时专注于性能优化和增强服务器操作可见性。Percona Server还包含XtraDB存储引擎，这是Percona对InnoDB存储引擎的改进版本。

***.org/wiki/Percona_Server

!logo

如何使用本镜像

启动amd64/percona服务器实例

启动Percona Server for MySQL实例非常简单：

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

其中，some-percona是您为容器分配的名称，my-secret-pw是为MySQL root用户设置的密码，tag是指定MySQL版本的标签。请参见上文的标签列表选择合适的标签。

通过MySQL命令行客户端连接Percona Server

以下命令启动另一个amd64/percona容器实例，并针对原始amd64/percona容器运行mysql命令行客户端，允许您对数据库实例执行SQL语句：

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

其中，some-percona是原始amd64/percona容器的名称（已连接到some-network Docker网络）。

本镜像也可用作非Docker或远程实例的客户端：

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

更多关于MySQL命令行客户端的信息，请参见MySQL文档。

使用docker compose

percona的compose.yaml示例：

# 使用root/example作为用户/密码凭据

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

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

运行docker compose up，等待初始化完成后，访问http://localhost:8080或[***]（根据实际情况）。

容器shell访问和查看MySQL日志

docker exec命令允许在Docker容器内运行命令。以下命令将为您的amd64/percona容器提供bash shell：

$ docker exec -it some-percona bash

日志可通过Docker容器日志查看：

$ docker logs some-percona

使用自定义MySQL配置文件

启动配置在/etc/my.cnf文件中指定，该文件会包含/etc/my.cnf.d目录下所有以.cnf结尾的文件。该目录中的设置会补充或覆盖/etc/my.cnf中的设置。如果需要使用自定义MySQL配置，可在主机上创建配置文件目录，并将该目录挂载为容器内的/etc/my.cnf.d。

若/my/custom/config-file.cnf是自定义配置文件的路径和名称，可按以下方式启动amd64/percona容器（注意命令中仅使用自定义配置文件的目录路径）：

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

这将启动一个新容器some-percona，其中Percona Server实例将使用/etc/my.cnf和/etc/my.cnf.d/config-file.cnf的组合启动设置，后者的设置优先级更高。

不使用cnf文件的配置

许多配置选项可作为mysqld的标志传递。这使您无需cnf文件即可自定义容器。例如，若要将所有表的默认编码和排序规则更改为UTF-8（utf8mb4），只需运行：

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

若要查看所有可用选项，运行：

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

环境变量

启动amd64/percona镜像时，可通过docker run命令行传递一个或多个环境变量调整实例配置。注意：如果容器启动时数据目录已包含数据库，则以下变量均无效——任何预先存在的数据库在容器启动时都不会被修改。

MYSQL_ROOT_PASSWORD（必填）

设置root超级用户的密码。例如上述示例中设为my-secret-pw。

MYSQL_ROOT_HOST（可选）

默认情况下，root用户可从任何主机连接。此选项限制root用户仅能从指定主机连接，也可设为localhost仅允许本地连接。

MYSQL_DATABASE（可选）

指定启动时创建的数据库名称。若同时提供了MYSQL_USER和MYSQL_PASSWORD，则该用户将被授予对该数据库的超级用户权限（对应GRANT ALL）。

MYSQL_USER、MYSQL_PASSWORD（可选）

两者配合使用，用于创建新用户并设置密码。该用户将被授予MYSQL_DATABASE指定数据库的超级用户权限。创建用户需同时提供这两个变量。注意：无需通过此机制创建root超级用户，root用户默认使用MYSQL_ROOT_PASSWORD指定的密码创建。

MYSQL_ALLOW_EMPTY_PASSWORD（可选）

设为yes允许root用户使用空密码启动容器。注意：除非确知风险，否则不建议设置为yes，这会使实例完全无保护，任何人可获取超级用户权限。

MYSQL_RANDOM_ROOT_PASSWORD（可选）

设为yes将为root用户生成随机初始密码（使用pwmake）。生成的root密码将输出到stdout（格式：GENERATED ROOT PASSWORD: .....）。

MYSQL_ONETIME_PASSWORD（可选）

初始化完成后将root用户（非MYSQL_USER指定的用户）设为过期状态，强制首次登录时更改密码。注意：此功能仅支持MySQL 5.6+，在MySQL 5.5上使用会初始化失败并报错。

MYSQL_INITDB_SKIP_TZINFO（可选）

首次运行时，MySQL会自动从本地系统加载CONVERT_TZ()函数所需的时区信息。若不需要此行为，可设置此选项禁用时区加载。

INIT_TOKUDB（可选）

启用TokuDB引擎。仅当禁用透明大页（THP）时可激活。

INIT_ROCKSDB（可选）

启用RocksDB引擎。

Docker Secrets

作为通过环境变量传递敏感信息的替代方案，可在上述环境变量后添加_FILE后缀，使初始化脚本从容器内的文件加载变量值。尤其适用于从Docker Secrets加载存储在/run/secrets/<secret_name>文件中的密码。例如：

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

目前仅支持MYSQL_ROOT_PASSWORD、MYSQL_ROOT_HOST、MYSQL_DATABASE、MYSQL_USER和MYSQL_PASSWORD。

遥测

从Percona Server 8.0.35-27开始，遥测功能默认启用。若不希望向Percona发送使用数据，可设置环境变量PERCONA_TELEMETRY_DISABLE=1：

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

初始化新实例

容器首次启动时，将创建指定名称的新数据库并使用提供的配置变量初始化。此外，会执行/docker-entrypoint-initdb.d目录中所有扩展名为.sh、.sql和.sql.gz的文件，文件按字母顺序执行。通过将SQL转储文件挂载到该目录，或提供包含数据的自定义镜像，可轻松填充amd64/percona服务。SQL文件默认导入到MYSQL_DATABASE指定的数据库。

注意事项

数据存储位置

重要提示：Docker容器中运行的应用有多种数据存储方式。建议amd64/percona镜像用户熟悉以下选项：

• 让Docker通过使用自身内部卷管理将数据库文件写入主机系统磁盘。这是默认方式，简单且对用户透明。缺点是主机系统上的工具和应用可能难以定位文件。
• 在主机系统上创建数据目录（容器外部），并将其挂载到容器内可见的目录。这将数据库文件放在主机系统的已知位置，便于主机上的工具和应用访问。缺点是用户需确保目录存在，并正确设置主机系统上的目录权限和其他安全机制。

以下是后一种方式的基本步骤：

1. 在主机系统的合适卷上创建数据目录，例如/my/own/datadir。

2. 按以下方式启动amd64/percona容器：

   $ docker run --name some-percona -v /my/own/datadir:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d amd64/percona:tag
   

命令中的-v /my/own/datadir:/var/lib/mysql部分将主机系统的/my/own/datadir目录挂载为容器内的/var/lib/mysql，MySQL默认在此写入数据文件。

MySQL初始化完成前无法连接

若容器启动时数据目录未初始化数据库（特别是不存在mysql子目录），将创建默认数据库。这是预期行为，但意味着在初始化完成前，实例不接受传入连接。这可能导致使用Docker Compose等自动化工具同时启动多个容器时出现问题。

如果连接MySQL的应用无法处理MySQL downtime或等待MySQL启动，可能需要在服务启动前添加连接重试循环。官方镜像中的实现示例可参见WordPress或Bonita。

用于现有数据库

若启动amd64/percona容器时数据目录已包含数据库（特别是存在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

从备份文件恢复数据

恢复数据可使用带-i标志的docker exec命令，例如：

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

许可证

查看本镜像包含软件的许可证信息。

与所有Docker镜像一样，本镜像可能包含其他许可软件（如基础发行版中的Bash等，以及主软件的直接或间接依赖）。

自动检测到的其他许可证信息可在repo-info仓库的percona/目录中找到。

对于任何预构建镜像的使用，镜像用户有责任确保其使用符合包含的所有软件的相关许可证。