MySQL Docker 镜像使用指南

快速参考

维护方

由 Docker 社区及 MySQL 团队 维护。

帮助渠道

可通过 Docker 社区 Slack、Server Fault、Unix & Linux 或 Stack Overflow 获取帮助。

支持的标签及对应 Dockerfile 链接

9.4.x 版本（innovation 分支）

• 9.4.0, 9.4, 9, innovation, latest, 9.4.0-oraclelinux9, 9.4-oraclelinux9, 9-oraclelinux9, innovation-oraclelinux9, oraclelinux9, 9.4.0-oracle, 9.4-oracle, 9-oracle, innovation-oracle, oracle
  对应 Dockerfile

8.4.x 版本（lts 分支）

• 8.4.6, 8.4, 8, lts, 8.4.6-oraclelinux9, 8.4-oraclelinux9, 8-oraclelinux9, lts-oraclelinux9, 8.4.6-oracle, 8.4-oracle, 8-oracle, lts-oracle
  对应 Dockerfile

8.0.x 版本（Oracle Linux 基础）

• 8.0.43, 8.0, 8.0.43-oraclelinux9, 8.0-oraclelinux9, 8.0.43-oracle, 8.0-oracle
  对应 Dockerfile

8.0.x 版本（Debian 基础）

• 8.0.43-bookworm, 8.0-bookworm, 8.0.43-debian, 8.0-debian
  对应 Dockerfile

快速参考（续）

问题反馈地址

[***]

支持的架构

• amd64（详情）
• arm64v8（详情）
  （更多架构信息见 官方说明）

镜像详情

• 包含元数据、传输大小等信息：repo-info 仓库的 repos/mysql/ 目录（历史记录）

镜像更新

• 跟踪更新：official-images 仓库的 library/mysql 标签
• 更新记录：official-images 仓库的 library/mysql 文件（历史记录）

本文档来源

docs 仓库的 mysql/ 目录（历史记录）

什么是 MySQL？

MySQL 是全球最流行的开源数据库，以其可靠的性能和易用性成为 Web 应用的首选数据库，覆盖从个人项目、网站到电商平台、信息服务，乃至 、、、! 等大型网站。

更多信息及 MySQL 服务器和其他产品的下载，见 [***]

!MySQL logo

如何使用本镜像

启动 mysql 服务器实例

启动 MySQL 实例的基本命令：

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

• some-mysql：容器名称（可自定义）
• -e MYSQL_ROOT_PASSWORD=my-secret-pw：设置 root 用户密码（必填）
• -d：后台运行容器
• mysql:tag：指定镜像标签（如 mysql:8.4，标签列表见上文）

连接 MySQL 命令行客户端

连接容器内的 MySQL 实例

通过另一个容器连接到已启动的 some-mysql 实例：

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

• --network some-network：确保两个容器在同一网络（若未指定网络，需先创建并连接容器）
• --rm：退出后自动删除临时容器
• -hsome-mysql：目标 MySQL 容器的名称（或 IP）

连接远程 MySQL 实例

也可直接连接非 Docker 环境的远程 MySQL：

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

更多 MySQL 命令行客户端用法见 官方文档。

使用 docker compose

以下是 compose.yaml 示例（以 root/example 为默认账号密码）：

services:
  db:
    image: mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: example
    # 注意：此配置仅为示例，不建议用于生产环境

启动命令：docker compose up，等待初始化完成后即可使用。

容器 shell 访问与日志查看

进入容器 shell

通过 docker exec 进入运行中的容器：

$ docker exec -it some-mysql bash

查看日志

通过 Docker 容器日志查看 MySQL 运行日志：

$ docker logs some-mysql

使用自定义 MySQL 配置文件

默认配置路径

• Oracle 基础镜像（默认）：主配置文件 /etc/my.cnf，可能包含 /etc/mysql/conf.d 目录的扩展配置
• Debian 基础镜像（MySQL 8+）：主配置文件 /etc/mysql/my.cnf，可能包含 /etc/mysql/conf.d 目录的扩展配置

建议先进入容器查看具体配置结构。

挂载自定义配置

若自定义配置文件路径为 /my/custom/config-file.cnf，通过以下命令挂载配置目录：

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

• -v /my/custom:/etc/mysql/conf.d：将主机目录 /my/custom 挂载到容器的配置扩展目录
• 自定义配置会覆盖默认配置中相同的项

无需配置文件的参数调整

可直接通过 mysqld 命令行参数自定义配置（无需配置文件）。例如，设置默认字符集为 utf8mb4：

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

查看所有可用参数：

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

环境变量

启动容器时可通过 -e 设置以下环境变量（首次初始化数据库时生效，已有数据库时忽略）：

必选变量

• MYSQL_ROOT_PASSWORD：设置 root 用户密码（必填，除非使用 MYSQL_ALLOW_EMPTY_PASSWORD 或 MYSQL_RANDOM_ROOT_PASSWORD）

可选变量

• MYSQL_DATABASE：初始化时创建指定名称的数据库
• MYSQL_USER & MYSQL_PASSWORD：创建新用户并授予 MYSQL_DATABASE 的所有权限（需同时设置）
• MYSQL_ALLOW_EMPTY_PASSWORD：允许 root 密码为空（设为 yes，不推荐生产环境）
• MYSQL_RANDOM_ROOT_PASSWORD：生成随机 root 密码（设为 yes，密码会打印到日志）
• MYSQL_ONETIME_PASSWORD：强制 root 用户首次登录需修改密码（MySQL 5.6+ 支持，设为非空值）
• MYSQL_INITDB_SKIP_TZINFO：跳过时区数据加载（设为非空值，不影响 CONVERT_TZ() 函数时可用）

从文件加载敏感信息（Docker Secrets）

通过环境变量后缀 _FILE 从文件加载值（适用于 Docker Secrets）。例如，从 /run/secrets/mysql-root 文件读取 root 密码：

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

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

初始化新数据库

容器首次启动时，若数据库目录为空，会自动初始化数据库，并执行 /docker-entrypoint-initdb.d 目录下的 .sh、.sql、.sql.gz、.sql.bz2、.sql.xz、.sql.zst 文件（按字母顺序执行）。

示例：挂载 SQL 文件初始化数据

将 SQL 脚本挂载到 /docker-entrypoint-initdb.d：

$ docker run --name some-mysql -v /path/to/init.sql:/docker-entrypoint-initdb.d/init.sql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag

SQL 文件会自动导入到 MYSQL_DATABASE 指定的数据库（未指定则导入到默认数据库）。

注意事项

数据存储位置

MySQL 数据默认存储在容器内的 /var/lib/mysql，建议通过以下方式持久化数据：

方式 1：使用 Docker 卷（推荐）

让 Docker 管理存储，数据保存在主机的 Docker 卷中（路径由 Docker 控制）：

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

• mysql-data：卷名称（首次使用会自动创建）

方式 2：挂载主机目录

将主机目录挂载到容器内的 /var/lib/mysql（需确保目录权限正确）：

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

初始化完成前无法连接

容器启动时若需初始化数据库（首次启动且数据目录为空），初始化期间无法接受连接。自动化工具（如 Docker Compose）同时启动多个容器时可能遇到此问题，建议在应用中添加连接重试逻辑（参考 WordPress 的实现）。

使用现有数据库

若挂载的 /var/lib/mysql 目录已包含数据库（如 /var/lib/mysql/mysql 子目录），无需设置 MYSQL_ROOT_PASSWORD，容器会直接使用现有数据库，忽略所有初始化环境变量。

以非 root 用户运行

若需指定 UID/GID 运行 mysqld（如适配主机目录权限），可通过 --user 参数设置（非 root 用户）：

$ mkdir data && chown 1000:1000 data  # 主机目录权限设为 1000:1000
$ docker run -v "$PWD/data":/var/lib/mysql --user 1000:1000 --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag

数据库备份与恢复

备份数据库

通过 docker exec 在容器内执行 mysqldump：

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

恢复数据库

通过 docker exec -i 导入 SQL 文件：

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

许可信息

• 镜像中软件的许可信息：MySQL 官方许可页面
• 额外许可信息（如基础镜像中的 Bash 等）：repo-info 仓库的 mysql/ 目录

使用前请确保遵守所有包含软件的许可条款。