Percona Docker镜像文档

1. 镜像概述和主要用途

Percona Server for MySQL是由Percona创建的MySQL关系型数据库管理系统的分支。该镜像旨在保持与官方MySQL版本的高度兼容性，同时专注于性能优化和增强服务器操作的可见性。其核心包含Percona的XtraDB存储引擎（InnoDB的增强版），适用于需要高性能、高可靠性MySQL兼容数据库的Docker化部署场景。

2. 核心功能和特性

• 高性能优化：基于MySQL源码优化，提供更好的查询性能和并发处理能力。
• XtraDB存储引擎：InnoDB的增强版本，提供更快的崩溃恢复、更好的I/O性能和更多监控指标。
• 多存储引擎支持：可启用TokuDB、RocksDB等第三方存储引擎（需通过环境变量配置）。
• 灵活配置：支持通过环境变量、自定义配置文件或命令行参数调整数据库参数。
• 安全特性：支持Docker Secrets管理敏感信息（如密码），避免明文环境变量泄露。
• 初始化自动化：首次启动时自动创建数据库，并执行/docker-entrypoint-initdb.d目录下的.sh、.sql、.sql.gz文件。
• 遥测控制：8.0.35-27及以上版本默认启用遥测，可通过环境变量禁用。

3. 使用场景和适用范围

• 生产环境部署：需高性能、MySQL兼容数据库的企业应用。
• 开发/测试环境：快速搭建隔离的数据库实例，支持配置复用。
• Docker化架构：与其他容器化服务（如Web应用、缓存）协同部署。
• 数据密集型应用：依赖数据库性能优化的分析型或事务型系统。

4. 支持的标签

5. 使用方法

5.1 启动Percona Server实例

通过以下命令启动一个基础Percona Server容器：

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

• some-percona：容器名称（自定义）。
• my-secret-pw：root用户密码（必选）。
• tag：指定镜像标签（如8.0，见“支持的标签”列表）。

5.2 通过MySQL命令行客户端连接

容器内连接

在同一Docker网络中启动客户端容器，连接到目标数据库：

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

• some-network：目标数据库容器所在的Docker网络。
• some-percona：目标数据库容器名称。
• example-user：数据库用户名（需提前创建）。

远程连接

作为客户端连接非Docker或远程数据库：

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

5.3 使用docker compose部署

创建compose.yaml文件，定义数据库和管理工具（如Adminer）：

# 使用 root/example 作为用户名/密码凭据
services:
  db:
    image: percona:8.0  # 指定标签
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: example  # root密码
    volumes:
      - percona-data:/var/lib/mysql  # 数据持久化卷

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080  # 暴露Adminer端口

volumes:
  percona-data:  # 声明命名卷

启动服务：

docker compose up -d

访问http://localhost:8080通过Adminer管理数据库。

5.4 容器Shell访问和日志查看

进入容器Shell

docker exec -it some-percona bash

查看日志

docker logs some-percona

5.5 使用自定义配置文件

Percona默认加载/etc/my.cnf及/etc/my.cnf.d/*.cnf配置。通过挂载主机目录覆盖配置：

docker run --name some-percona \
  -v /my/custom:/etc/my.cnf.d \  # 主机配置目录挂载到容器
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -d percona:tag

• 主机目录/my/custom下的.cnf文件会覆盖默认配置。

5.6 无配置文件的配置方式

通过命令行参数直接传递mysqld选项，无需配置文件：

docker run --name some-percona \
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -d percona:tag \
  --character-set-server=utf8mb4 \  # 设置默认字符集
  --collation-server=utf8mb4_unicode_ci  # 设置默认排序规则

查看所有可用参数：

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

6. 配置参数和环境变量

6.1 环境变量说明

6.2 Docker Secrets支持

通过_FILE后缀从文件加载敏感变量（如密码），避免明文暴露。例如：

docker run --name some-percona \
  -e MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mysql-root \  # 从文件加载root密码
  -d percona:tag

支持的变量：MYSQL_ROOT_PASSWORD_FILE、MYSQL_ROOT_HOST_FILE、MYSQL_DATABASE_FILE、MYSQL_USER_FILE、MYSQL_PASSWORD_FILE。

6.3 遥测配置

8.0.35-27及以上版本默认启用遥测（发送使用数据到Percona），可通过以下环境变量禁用：

docker run --name some-percona \
  -e PERCONA_TELEMETRY_DISABLE=1 \  # 禁用遥测
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -d percona:tag

7. 初始化新实例

首次启动容器时，若数据目录为空，将自动执行以下操作：

1. 创建MYSQL_DATABASE指定的数据库（若设置）。
2. 创建MYSQL_USER指定的用户，并授予其MYSQL_DATABASE的所有权限（若设置）。
3. 执行/docker-entrypoint-initdb.d目录下的初始化文件，按字母顺序执行：
   • .sh：Bash脚本（需可执行权限）。
   • .sql：SQL脚本。
   • .sql.gz：压缩SQL脚本（自动解压执行）。

示例：挂载本地SQL文件到初始化目录：

docker run --name some-percona \
  -v /local/init-scripts:/docker-entrypoint-initdb.d \  # 挂载初始化脚本目录
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -d percona:tag

8. 注意事项

8.1 数据存储位置

推荐使用Docker卷或绑定挂载持久化数据，避免容器删除导致数据丢失：

绑定挂载（主机目录）

docker run --name some-percona \
  -v /my/own/datadir:/var/lib/mysql \  # 主机目录挂载到数据目录
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -d percona:tag

Docker卷（推荐）

docker volume create percona-data  # 创建命名卷
docker run --name some-percona \
  -v percona-data:/var/lib/mysql \  # 使用命名卷
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -d percona:tag

8.2 初始化完成前无法连接

首次启动时，数据库初始化期间无法接受连接。自动化部署（如docker compose）需注意：

• 应用需实现连接重试逻辑（如WordPress的重试机制）。
• 使用depends_on仅保证启动顺序，不保证初始化完成，需额外处理。

8.3 现有数据库的使用

若数据目录已存在数据库（如/var/lib/mysql/mysql子目录），启动时必须省略MYSQL_ROOT_PASSWORD，否则会被忽略，且数据库不会被修改。

8.4 数据库备份与恢复

备份数据库

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

恢复数据库

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

9. 许可证信息

• 镜像包含软件的许可证信息：Percona Server 版权说明。
• 基础镜像及依赖软件的许可证信息：repo-info仓库percona目录。

使用前请确保符合所有包含软件的许可证要求。