Docker Compose 部署 MySQL：从原理到实战的容器化数据库解决方案

1. 项目概述：为什么选择 Docker Compose 部署 MySQL？

如果你正在为一个新项目搭建数据库环境，或者需要在本地快速复现一个生产级的 MySQL 服务，手动安装、配置、管理 MySQL 服务绝对不是一个高效的选择。版本冲突、配置文件混乱、依赖库缺失、端口占用……这些琐碎但致命的问题，足以消耗掉你半天甚至更久的时间。而 Docker 的出现，尤其是 Docker Compose 的普及，彻底改变了这种局面。

简单来说，这个项目就是利用 Docker Compose 这个“一键编排”工具，来部署一个完全独立、可移植、版本任选的 MySQL 数据库容器。它的核心价值在于“通用性”和“可复现性”。无论你是想在 Windows、macOS 还是 Linux 上运行，无论你需要 MySQL 5.7、8.0 还是最新的 8.4 版本，这套方法都适用。你只需要一个docker-compose.yml文件，就能在任何安装了 Docker 的环境中，通过一行命令启动一个配置完备的 MySQL 服务。这对于开发、测试、演示环境搭建，甚至是小型生产部署，都提供了极大的便利。

我之所以推崇这种方式，是因为它完美地将环境与应用解耦。你的数据库及其所有配置（密码、字符集、数据存储路径）都被清晰地定义在一个代码化的文件里。团队新成员加入时，无需再经历繁琐的“环境配置地狱”，只需git clone代码库，然后执行docker-compose up -d，一个与大家完全一致的数据库环境就准备就绪了。接下来，我将从设计思路到实操细节，完整拆解这个过程。

2. 核心设计思路与文件结构解析

2.1 为什么是 Docker Compose 而不是纯 Docker Run？

很多初学者会问，直接用docker run命令不也能启动一个 MySQL 容器吗？比如docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag。确实可以，但这种方式有几个明显的短板：

1. 命令冗长且易忘：一旦需要配置数据卷、端口映射、环境变量、自定义配置文件，命令会变得非常长，难以记忆和复用。
2. 缺乏版本控制：这条命令通常存在于你的终端历史或某个笔记里，难以与项目代码一同进行版本管理。
3. 多服务协作困难：现代应用很少只有一个数据库，通常还需要 Redis、Nginx 等其他服务。用纯docker run来管理多个容器及其网络关系，复杂度呈指数级上升。

Docker Compose 正是为了解决这些问题而生。它允许你使用 YAML 文件来定义和运行多容器的 Docker 应用。对于 MySQL 部署来说，这意味着：

• 声明式配置：所有配置（镜像版本、端口、卷、环境变量）都以代码形式写在docker-compose.yml中，一目了然。
• 一键启停：通过docker-compose up和docker-compose down统一管理整个应用栈的生命周期。
• 环境隔离：Compose 会为你的项目栈自动创建一个独立的网络，确保容器间可以安全通信，同时与宿主机或其他项目隔离。
• 轻松扩展：未来如果需要添加一个 phpMyAdmin 管理界面，只需在同一个 YAML 文件中增加几行配置即可。

2.2 项目文件结构规划

一个清晰的文件结构是良好实践的开始。在开始编写docker-compose.yml之前，我建议先建立如下目录结构：

your-project/ ├── docker-compose.yml # Docker Compose 主配置文件 ├── mysql/ │ ├── conf/ # 存放自定义 MySQL 配置文件，如 my.cnf │ │ └── custom.cnf │ └── data/ # 映射 MySQL 数据目录，实现数据持久化（重要！） │ └── init/ # （可选）存放初始化 SQL 脚本 │ └── init.sql └── .env # （可选）环境变量文件，用于敏感信息管理

这个结构的好处在于：

• 配置与数据分离：conf目录放配置，data目录放数据，逻辑清晰，备份和迁移时目标明确。
• 数据持久化：将容器内的/var/lib/mysql目录映射到宿主机的./mysql/data，这样即使容器被删除，你的数据依然安全地保留在宿主机上。
• 初始化自动化：通过init目录，你可以在容器首次启动时自动创建数据库、用户和表结构，这对于自动化部署至关重要。
• 环境变量管理：使用.env文件来管理数据库密码等敏感信息，避免将其硬编码在 YAML 文件中，提升安全性。

3. 编写 Docker Compose 配置文件详解

接下来，我们进入核心环节：编写docker-compose.yml文件。我会逐行解释每个配置项的作用和背后的考量。

3.1 基础服务定义与版本选择

首先，我们需要指定 Compose 文件的版本。虽然最新版是 3.x，但为了更好的兼容性，我们使用广泛支持的3.8。

version: '3.8' services: mysql: image: mysql:8.0

• version: '3.8': 这定义了 Compose 文件格式的版本。它决定了你可以使用哪些特性。3.x 版本提供了丰富的功能并具有良好的兼容性。
• services:: 这是定义所有容器服务的根节点。
• mysql:: 这是我们定义的服务名称，你可以随意命名，比如db、database等。在同一个 Compose 网络内，其他容器可以通过这个服务名（mysql）作为主机名来访问该数据库。
• image: mysql:8.0: 指定使用的 Docker 镜像。这里我们使用官方 MySQL 镜像的 8.0 版本标签。这是实现“所有版本通用”的关键：你只需将8.0替换为5.7、8.4或latest，即可切换版本。我强烈建议使用具体版本号（如8.0.33）而非latest，以确保环境的一致性，避免因镜像更新导致意外行为。

3.2 容器配置核心三要素：环境变量、端口与数据卷

一个可用的 MySQL 容器至少需要配置三样东西：root 密码、端口映射和数据持久化。

services: mysql: image: mysql:8.0 container_name: my-mysql-container restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: your_strong_root_password MYSQL_DATABASE: my_app_db MYSQL_USER: app_user MYSQL_PASSWORD: your_strong_app_password TZ: Asia/Shanghai ports: - "3306:3306" volumes: - ./mysql/data:/var/lib/mysql - ./mysql/conf:/etc/mysql/conf.d - ./mysql/init:/docker-entrypoint-initdb.d

逐项解析：

1. container_name: 为容器指定一个固定的名称，方便在docker ps或docker logs命令中识别。如果不指定，Docker 会生成一个随机名称。
2. restart: unless-stopped: 这是生产环境的最佳实践。它意味着容器总是自动重启，除非你手动停止了它。这可以确保数据库服务在宿主机重启或 Docker 守护进程异常后能自动恢复。
3. environment: 这是配置 MySQL 的核心部分，通过环境变量传递参数给容器。
   • MYSQL_ROOT_PASSWORD:（必填）设置 root 用户的密码。请务必使用强密码。
   • MYSQL_DATABASE: （可选）容器启动时自动创建的数据库名称。
   • MYSQL_USER/MYSQL_PASSWORD: （可选）容器启动时自动创建的非 root 用户及其密码。出于安全考虑，应用程序应使用此用户而非 root 进行连接。
   • TZ: 设置容器内的时区，确保时间相关函数和日志时间戳正确。
4. ports: 端口映射，格式为"宿主机端口:容器端口"。这里将容器内的 MySQL 默认端口 3306 映射到宿主机的 3306 端口。注意：如果宿主机 3306 端口已被占用，你需要修改前面的端口号，例如"3307:3306"。
5. volumes: 数据卷映射，实现数据持久化和配置自定义。
   • ./mysql/data:/var/lib/mysql:这是数据持久化的生命线。它将容器内 MySQL 存储所有数据的目录映射到宿主机的./mysql/data目录。删除容器不会影响这个目录下的数据。
   • ./mysql/conf:/etc/mysql/conf.d: 将宿主机./mysql/conf目录映射到容器内的配置目录。你可以将自定义的.cnf配置文件放在./mysql/conf下（如custom.cnf），MySQL 会自动加载它们来覆盖或补充默认配置。
   • ./mysql/init:/docker-entrypoint-initdb.d: 这是一个非常实用的特性。任何放在./mysql/init目录下的.sh、.sql或.sql.gz文件，都会在容器首次启动时（即数据目录为空时）按字母顺序执行。你可以在这里放置建表脚本或初始数据。

重要提示：永远不要将密码等敏感信息硬编码在docker-compose.yml中，尤其是计划提交到 Git 仓库时。下一节我们会解决这个问题。

3.3 进阶配置：网络、资源限制与配置文件

为了更贴近生产需求，我们还可以添加网络和资源限制配置。

services: mysql: # ... 上述基础配置 ... networks: - app-network deploy: resources: limits: cpus: '1.0' memory: 1G reservations: memory: 512M

1. networks: 定义容器加入的网络。这里我们创建/加入一个名为app-network的自定义网络。在同一网络下的容器，可以通过服务名直接通信（如mysql://mysql:3306），无需通过宿主机 IP，更安全、更便捷。你需要在文件底部定义这个网络：

   networks: app-network: driver: bridge

2. deploy.resources: （在docker-compose up时生效，需 Docker Swarm 模式？实际上，对于docker-compose up，应使用resources顶级字段，但旧版语法可能不同。更通用的单机资源限制方法是使用mem_limit和cpus，但在 Compose v3 中，推荐如下写法，但注意docker-compose可能不完全支持deploy，单机环境建议用resources顶级字段）更正：对于docker-compose（非 Swarm 模式），应使用以下语法：

   services: mysql: # ... mem_limit: 1g cpus: '1.0'

   这限制了容器最多使用 1GB 内存和 1 个 CPU 核心，防止单个容器耗尽宿主机资源。

3. 自定义配置文件示例：假设我们需要调整 MySQL 的默认字符集和最大连接数。在./mysql/conf目录下创建custom.cnf文件：

   [mysqld] character-set-server=utf8mb4 collation-server=utf8mb4_unicode_ci max_connections=200 default-time-zone='+08:00' [client] default-character-set=utf8mb4

   这个配置将服务器和客户端的默认字符集设置为utf8mb4（支持完整的 Unicode，包括表情符号），最大连接数设为 200，并设置时区。

4. 安全与最佳实践：管理敏感信息

将数据库密码明文写在 YAML 文件中是极不安全的。正确的做法是使用环境变量文件.env。

步骤：

1. 在docker-compose.yml同级目录创建.env文件：

   MYSQL_ROOT_PASSWORD=YourSuperSecretRootPass123! MYSQL_USER_PASSWORD=YourStrongAppUserPass456! TZ=Asia/Shanghai

2. 修改docker-compose.yml，引用这些环境变量：

   environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_PASSWORD: ${MYSQL_USER_PASSWORD} TZ: ${TZ} MYSQL_DATABASE: my_app_db MYSQL_USER: app_user

3. 至关重要：将.env文件添加到.gitignore中，确保它不会被提交到版本控制系统。

现在，你的密码等敏感信息只存在于本地的.env文件中，docker-compose.yml文件可以安全地分享和版本控制。

5. 完整操作流程与命令实录

假设你的项目目录已经准备好了docker-compose.yml、.env以及相关的mysql/conf、mysql/data、mysql/init目录。

5.1 启动 MySQL 服务

打开终端，进入项目目录，执行以下命令：

# 在后台启动所有服务（-d 代表 detached 模式） docker-compose up -d

执行后你会看到类似输出：

Creating network "your-project_app-network" with driver "bridge" Creating volume "your-project_mysql-data" with local driver Creating my-mysql-container ... done

这个命令会：

1. 检查并拉取所需的 MySQL 镜像（如果本地没有）。
2. 根据docker-compose.yml创建定义的网络和卷。
3. 创建并启动名为my-mysql-container的容器。

5.2 检查服务状态与日志

启动后，如何确认 MySQL 正在健康运行？

# 查看容器状态 docker-compose ps # 或 docker ps | grep mysql # 查看 MySQL 容器的实时日志（非常有用，尤其是启动失败时） docker-compose logs -f mysql # 查看特定时间段的日志 docker-compose logs --tail=50 mysql

在日志中，你应该看到类似mysqld: ready for connections的关键信息，这表明 MySQL 已成功启动并开始监听连接。

5.3 连接到 MySQL 数据库

现在，你可以从宿主机或同一网络下的其他容器连接数据库。

从宿主机连接（使用 MySQL 客户端）：

# 假设你本地安装了 mysql-client mysql -h 127.0.0.1 -P 3306 -u root -p # 然后输入 .env 文件中设置的 MYSQL_ROOT_PASSWORD

从同一 Docker Compose 项目中的另一个容器连接：在其他服务的配置中，数据库连接字符串的主机名直接使用服务名mysql。 例如，一个 Python 应用的连接字符串可能是：mysql://app_user:password@mysql:3306/my_app_db。

5.4 管理服务生命周期

# 停止服务，但保留容器和数据 docker-compose stop # 停止并移除容器、网络（但不会删除数据卷） docker-compose down # 停止并移除容器、网络、以及所有在 docker-compose.yml 中定义的匿名卷（谨慎使用！） # 这不会删除我们通过 `- ./mysql/data:...` 映射的命名卷（即 ./mysql/data 目录） docker-compose down -v # 重启服务 docker-compose restart mysql # 在启动服务前，重新构建镜像（如果你修改了 Dockerfile，本例中没有） docker-compose up -d --build

6. 常见问题排查与实战技巧

即使按照步骤操作，你也可能会遇到一些问题。这里记录了我踩过的一些坑和解决方案。

6.1 容器启动失败：端口已被占用

问题现象：执行docker-compose up -d后，容器状态为Exited (1)，查看日志docker-compose logs mysql显示Bind for 0.0.0.0:3306 failed: port is already allocated。

原因与解决：宿主机 3306 端口已被其他 MySQL 实例占用。

• 方案A（推荐）：修改docker-compose.yml中的端口映射，例如改为"3307:3306"，然后使用新端口3307连接。
• 方案B：找出并停止占用 3306 端口的进程。
  • Linux/macOS:sudo lsof -i :3306或sudo netstat -tulpn | grep :3306
  • Windows:netstat -ano | findstr :3306

6.2 数据权限错误

问题现象：容器反复重启，日志中出现mysqld: Can't create/write to file '/var/lib/mysql/is_writable' (Errcode: 13 - Permission denied)。

原因：宿主机上的./mysql/data目录权限与容器内 MySQL 进程（通常以mysql用户运行，UID 通常是 999）不匹配。这在 Linux 宿主机上很常见。

解决：

1. 确保./mysql/data目录存在。
2. 在宿主机上，更改该目录的所有权。你需要知道容器内mysql用户的 UID/GID（通常是 999），或者使用一个更通用的方法：

   # 进入项目目录 sudo chown -R 999:999 ./mysql/data

   如果不知道 UID，可以先启动一个临时容器查看，或者使用以下命令递归修改目录权限为对所有人可读写（安全性较低，仅用于开发）：

   sudo chmod -R 777 ./mysql/data # 不推荐用于生产

   最佳实践：在docker-compose.yml中，可以为 MySQL 服务指定用户，使其与宿主机某个现有用户匹配，但这涉及更复杂的配置。对于开发环境，chown 999:999是最直接的。

6.3 初始化脚本未执行

问题现象：放在./mysql/init/下的.sql文件在容器首次启动时没有执行。

排查步骤：

1. 确认是“首次启动”：初始化脚本只在数据目录（/var/lib/mysql）为空时执行。如果你之前启动过并有了数据，脚本不会再次运行。你可以先执行docker-compose down -v（注意这会删除匿名卷，但我们的命名卷./mysql/data是安全的？不，-v会删除所有在 compose 文件中定义的卷，包括命名卷。危险！）实际上，对于映射到本地目录的卷（./mysql/data），docker-compose down -v不会删除宿主机上的目录内容，但会删除 Docker 管理的卷元数据。最安全的方法是停止容器后，手动清空./mysql/data目录的内容（rm -rf ./mysql/data/*），然后再启动。
2. 检查脚本权限和格式：确保.sql文件是 UTF-8 无 BOM 编码，并且具有可读权限。脚本中避免包含USE database;语句，因为MYSQL_DATABASE环境变量指定的数据库会在脚本执行前自动创建并被选中。
3. 查看 Docker 日志：docker-compose logs mysql会详细显示初始化过程的输出，包括脚本执行的任何错误信息。

6.4 性能调优与配置持久化

问题：默认配置可能不适合你的负载。

解决：通过自定义配置文件./mysql/conf/custom.cnf进行调整。以下是一些常见调优参数：

[mysqld] # 缓冲池大小，通常是系统内存的 50%-70%，但容器内需考虑 mem_limit innodb_buffer_pool_size = 512M # 连接数相关 max_connections = 200 thread_cache_size = 10 # 日志 slow_query_log = 1 slow_query_log_file = /var/log/mysql/slow.log long_query_time = 2 # 其他 transaction_isolation = READ-COMMITTED

修改配置后，需要重启 MySQL 容器生效：docker-compose restart mysql。

6.5 备份与恢复数据

由于数据持久化在./mysql/data，备份就是备份这个目录。但更优雅的方式是使用mysqldump命令在容器内执行。

备份：

# 将数据库导出到宿主机当前目录 docker exec my-mysql-container sh -c 'exec mysqldump --all-databases -uroot -p"$MYSQL_ROOT_PASSWORD"' > ./backup/all-databases-$(date +%Y%m%d).sql

恢复：

# 将备份文件复制到容器内，然后导入 docker cp ./backup/all-databases-20231027.sql my-mysql-container:/tmp/backup.sql docker exec -i my-mysql-container sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < ./backup/all-databases-20231027.sql # 或者直接通过管道 cat ./backup/backup.sql | docker exec -i my-mysql-container mysql -uroot -p"$MYSQL_ROOT_PASSWORD"

这套基于 Docker Compose 的 MySQL 部署方案，从简单的单行命令到可管理、可配置、可复现的声明式部署，覆盖了从开发到生产准备的绝大多数场景。它的魅力在于，你只需维护一个docker-compose.yml和一个.env文件，就能在任何地方瞬间重建一个完全一致的数据库环境。对于团队协作和持续集成/持续部署（CI/CD）流水线来说，这种“基础设施即代码”的方式，无疑是提升效率和可靠性的利器。