“用docker启动mysql”这个需求，我几乎每周都会碰到一次。不管是给新项目搭一个测试库，还是帮同事在本地还原生产环境，最顺手的方案就是Docker跑MySQL。为什么？因为MySQL能力很强，但传统方式安装起来真的折磨人，版本升级、依赖冲突、卸载残留，每一步都埋着坑。换成Docker之后，MySQL变成了一个可以随时创建、随时删除、随时重建的“临时数据库”，几分钟内就能得到一个干净、可用、配置受控的实例。这篇我打算把整个流程从零到尾捋一遍，从检查环境、安装Docker、拉镜像、启动实例，到数据持久化、参数配置、Compose编排，再聊几个我实际踩过的典型坑。不管你是刚接触Docker的新手，还是已经会用docker run但没深究过数据管理的老手，应该都能从中找到有用的东西。
1. 为什么要用Docker跑MySQL，先想清楚再动手
我见过不少新手上来就复制docker run命令，跑起来就以为完事了，结果后面数据丢了、配置没生效、容器起不来，各种莫名其妙。所以我想先花点篇幅说清楚，用Docker跑MySQL到底是在做什么，它和传统安装方式本质上的区别在哪里。
1.1 传统安装MySQL的几个烦心事
传统方式装MySQL（尤其是Windows）的痛点，我几乎全踩过。首先是安装过程本身，官网提供的msi和zip两种包，安装方式完全不一样，光跟着向导点下一步就能点出一堆问题：没装VC++运行库导致服务起不来，没配好my.ini导致中文乱码，权限不对导致data目录初始化失败。其次是版本升级，从5.7升到8.0并不是换个安装包那么简单，数据字典结构变了，直接把老数据目录拿过去可能打不开，需要先跑升级检查工具。第三是卸载，Windows卸载MySQL经常残留服务、残留注册表项，重新安装时端口被占，服务起不来，只能手动去注册表里翻。这些问题叠加在一起，会让人对“装数据库”这件事产生阴影。
1.2 Docker容器化带来的本质变化
Docker把“安装MySQL”变成了“拉取镜像然后运行”。MySQL官方维护的镜像已经把数据库服务本身的环境打包好了，你不需要关心系统缺哪个依赖库、数据目录权限对不对、服务怎么注册成开机启动。你要做的只是告诉Docker：我要哪个版本的MySQL、映射哪个端口、给root设置什么密码。这是一种“声明式”的用法，你描述目标状态，而不是一步步执行安装流程。容器本质上是进程隔离，MySQL的所有文件都写在容器内部的一个目录里。这带来一个非常关键的特性：容器本身是廉价的、可丢弃的，删掉一个容器再新建一个，只花几秒钟。但代价就是，如果不把数据目录挂载出来，容器删除的时候数据就一起没了。这个理念是整个Docker跑MySQL的核心，后面所有操作基本都是围绕它展开的。
2. 环境准备：Docker没跑起来，后面全是白费
很多人卡在“用Docker启动MySQL”之前，其实是Docker本身没跑起来。尤其是Windows用户，Docker Desktop装完双击没反应，或者启动时报虚拟化相关错误，这一步没解决，后面全是白搭。
2.1 装之前先确认三件事
第一，操作系统版本。Windows 10 64位以上或Windows 11都可以，但家庭版需要提前准备好WSL2，因为Docker Desktop默认依赖WSL2或Hyper-V。第二，虚拟化支持。打开任务管理器，切到“性能”选项卡，看CPU那一栏里的“虚拟化”是不是“已启用”。如果显示“已禁用”，就得进BIOS/UEFI把Intel VT-x或AMD-V打开。第三，确认机器上没有装过旧版Docker Toolbox或者残留的Docker老版本，这些会和Docker Desktop冲突。macOS这边简单很多，只要系统版本不是太老，直接装就行。Linux则不需要Docker Desktop，直接用Docker Engine。
2.2 不同平台的安装操作
Windows推荐以WSL2方式安装。先用管理员身份打开PowerShell，执行wsl --install，装完重启系统。重启后从官网下载Docker Desktop Installer，安装时勾选“Use WSL 2 instead of Hyper-V”。装完打开Docker Desktop，等右下角鲸鱼图标变绿，这一步很多人会卡住，原因基本都在WSL2没启用或者虚拟化没开。macOS直接下载Docker.dmg拖进Applications就能用。Linux（以Ubuntu为例）用apt装更省事：
sudo apt update sudo apt install -y docker.io sudo systemctl enable --now docker sudo usermod -aG docker $USER最后一步是把当前用户加进docker组，否则每次执行docker命令都要加sudo。改完用户组后重新登录一次就能生效。
2.3 验证安装并顺手加速镜像拉取
安装完先验证Docker核心是否正常：
docker version能同时显示客户端和服务端版本信息，就说明Docker引擎已经跑起来了。再执行docker info，能看到Docker的服务端状态、存储驱动、镜像数量这些信息。如果是在Linux服务器上，docker info还能看到是不是rootless模式。
这里还有一个重要建议：国内网络环境下拉取镜像经常超时。即便不是内网环境，直接连Docker官方仓库也时快时慢。建议在Docker配置里加上registry mirror。Docker Desktop用户打开Settings里的Docker Engine，直接在daemon.json里加：
{ "registry-mirrors": ["https://你的镜像源地址"] }Linux用户则改/etc/docker/daemon.json，然后sudo systemctl restart docker。配完之后再拉mysql镜像，速度会有非常明显的提升。
3. 一条docker run命令启动MySQL实例
环境准备好之后，核心操作就来了。docker run这条命令看着就是一行，但里面每个参数背后都有讲究，拆开讲清楚后，你以后用Docker跑Redis、跑PostgreSQL都是同样的套路。
3.1 选对镜像版本：8.0还是5.7
官方镜像名是mysql，标签就是版本号，最常见的是mysql:8.0和mysql:5.7。选哪个？如果是新项目，建议直接上8.0。MySQL 8.0是当前主流的长期支持版本，窗口函数、CTE、JSON能力都更完善，性能也比5.7强不少。但要注意，MySQL 8.0默认的认证插件是caching_sha2_password，如果你本地的老版本数据库客户端不支持这个插件，连接时会报认证失败。如果你是在给老项目复现环境，或者依赖一些旧版驱动，那就老老实实选5.7。另外MySQL官方还在推8.4这个新的LTS版本，可以理解成8.0系列的延续。建议是：没有特殊原因不要直接使用latest标签，latest通常指向当前最新稳定版，但半年后再看，镜像行为可能已经变了，到时候排查问题会很头大。
3.2 第一次启动：逐项拆解docker run命令
最基本的启动命令长这样：
docker run -d \ --name mysql8 \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=123456 \ mysql:8.0逐项解释一下。-d表示以守护模式在后台上运行，终端不会一直卡住，关掉终端也不影响容器继续跑。--name mysql8是给容器起名字，后面docker exec、docker logs、docker stop都要靠这个名字找到它。如果不指定，Docker会随机生成一个很怪的名字，维护起来难受。 -p 3306:3306是端口映射，左边是宿主机端口，右边是容器内端口，含义是把容器里的3306端口映射到宿主机的3306端口上。这样宿主机或者其他机器上的客户端才能通过127.0.0.1:3306访问到容器里的MySQL。比如映射写成-p 3307:3306，那客户端就要连127.0.0.1:3307。 -e MYSQL_ROOT_PASSWORD=123456是环境变量，MySQL官方镜像在首次初始化时会读它，把root用户的密码设成指定值。
这里有两个细节容易被忽略。第一，这个命令只能用于临时体验，真实使用必须加数据卷挂载，这点下一节细说。第二，如果宿主机3306端口已经被占用了，比如本机原来装过MySQL，那容器启动会失败，报端口占用，这也是后面要讲的排错场景之一。
3.3 验证MySQL真的跑起来了
启动之后怎么确认它真的在正常工作？先看容器状态：
docker ps -a看到mysql8的STATUS是Up，说明容器活着。但这里有个常见的误区：Up不代表MySQL服务已经就绪。MySQL容器首次启动要做初始化，包括建立data目录、执行初始化脚本、创建系统表，这个过程可能要几十秒。此时进去执行mysql命令，大概率会报连接失败。正确的验证方式是看日志：
docker logs mysql8日志最后出现“ready for connections”就表示服务已经就绪。然后可以进入容器内部验证：
docker exec -it mysql8 mysql -uroot -p输入密码后看到mysql>提示符就说明完全正常。这一步是容器内通过socket连接MySQL，不经过端口转发。再从宿主机角度验证TCP连接：
mysql -h127.0.0.1 -P3306 -uroot -p能够连上就说明端口映射、网络转发都没问题。socket连接和TCP连接是两个不同的概念，后面排错时经常会用到，提前理解会省事很多。
4. 数据持久化和参数配置，避免删容器丢数据
基础启动跑通之后，立刻要面对两个问题：数据安全和配置可控。这两件事是区分“能用”和“好用”的分水岭。
4.1 为什么必须挂载数据卷
直接docker run启动的MySQL，数据写在容器的可写层。容器的可写层和容器生命周期绑定，一旦docker rm mysql8，数据就全没了。有人觉得自己不会删容器就没关系，但容器崩溃、Docker Desktop重装、系统迁移，都可能导致容器消失。正确的做法是把数据目录挂载出来，用Docker卷或者宿主机目录都行。推荐用命名卷：
docker run -d \ --name mysql8 \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=123456 \ -v mysql-data:/var/lib/mysql \ mysql:8.0-v mysql-data:/var/lib/mysql的含义是创建一个名为mysql-data的卷，映射到容器内的MySQL数据目录。/var/lib/mysql是官方镜像里datadir的位置。数据写到卷里之后，容器删了、重建、升级镜像版本，只要卷还在，数据就还在。验证方法很简单：删掉容器，用同样的卷再启动一个新容器，所有数据库、表都原样存在。这可以说是我个人认为Docker跑MySQL最重要的一个习惯，没有之一。
4.2 配置文件挂载与字符集、表名大小写
MySQL服务端的行为由配置文件控制。官方镜像默认读取/etc/mysql/目录下的配置，并且支持/etc/mysql/conf.d和/etc/mysql/mysql.conf.d这两个目录里放附加配置。最直接的做法是准备一个宿主机目录，例如~/docker/mysql/conf，在里面放一个my.cnf，挂载到/etc/mysql/conf.d/my.cnf：
[mysqld] character-set-server=utf8mb4 collation-server=utf8mb4_unicode_ci max_connections=200容器启动时会读取这个文件，默字符集变成utf8mb4，排序规则也固定下来。如果有业务连接池设置，服务端max_connections也最好一起调大，否则连接池把连接数占满，服务端就拒绝新连接了。动手前务必注意：配置文件必须在容器首次初始化数据目录之前就挂载好。数据目录一旦生成，再改字符集类参数不会对已有表生效，顶多影响新建的表。还有个参数是lower_case_table_names，在Linux容器中默认值是0，也就是表名区分大小写；Windows上默认是1，不区分大小写。如果你想在容器里保持Linux的默认行为，什么都不用配。但如果在数据卷已经初始化之后再去改这个参数，MySQL 8.0会直接拒绝启动，因为该参数不允许在初始化后修改。官方建议：单独建一个空的测试卷，把所有想固化下来的配置都写好，再跑初始化。
4.3 环境变量背后的初始化逻辑
MySQL官方镜像在第一次初始化时会读取一系列环境变量，它们的用途值得逐一弄清楚。
| 环境变量 | 作用 |
|---|---|
| MYSQL_ROOT_PASSWORD | root超级用户密码，必填 |
| MYSQL_DATABASE | 初始化时自动创建的数据库名 |
| MYSQL_USER | 同时创建的普通用户名 |
| MYSQL_PASSWORD | 普通用户密码 |
| MYSQL_ALLOW_EMPTY_PASSWORD | 允许root空密码，仅开发环境偶尔用 |
| TZ | 时区，推荐写Asia/Shanghai |
如果在环境变量里同时给了MYSQL_USER和MYSQL_PASSWORD，镜像还会为这个用户授权MYSQL_DATABASE对应库的全部权限。这个设计非常适合一条命令起一个带库带账号的开发库，省去手动建库建用户。但要注意一个非常关键的点：初始化脚本只在数据目录为空时执行一次。数据卷里已经有数据之后，哪怕你再改MYSQL_ROOT_PASSWORD去重启容器，密码也不会变。这是“我改了密码为什么没用”最常见的来源。
5. 用Docker Compose把MySQL启动方式固化下来
如果只是临时起一个MySQL玩玩，docker run完全够用。但一旦MySQL要作为项目的固定组件长期维护，我强烈建议用Docker Compose把所有启动参数固化成一个文件。
5.1 项目化编排的必要性
docker run的命令一旦拉长，维护成本就开始上升。端口、数据卷、配置目录、时区、字符集、容器名这些参数混在一起，每次重新部署都要凭记忆敲，稍微少写一个-v或者写错端口，排查半天。Docker Compose允许把容器配置写进一个yaml文件，放进项目仓库里。之后无论是换电脑、拉同事一起开发、还是在测试服务器上部署，执行docker compose up -d就能得到一套完全一致的MySQL环境。这个价值在团队协作中尤其突出。不只是MySQL，一个JavaWeb项目往往还包含Redis、应用服务，都可以写在同一个compose文件里，统一生命周期管理，启动一键完成。
5.2 一个可以直接用的compose文件
在项目目录里新建docker-compose.yml：
version: '3.8' services: mysql: image: mysql:8.0 container_name: project_mysql restart: always environment: MYSQL_ROOT_PASSWORD: root123 MYSQL_DATABASE: app_db MYSQL_USER: app MYSQL_PASSWORD: app123 TZ: Asia/Shanghai ports: - "3306:3306" volumes: - mysql-data:/var/lib/mysql - ./mysql/conf:/etc/mysql/conf.d command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci volumes: mysql-data:这里有几个点值得说明。command下面写的参数等同于在启动命令后追加mysqld参数，优先级比配置文件高，用它来固化字符集非常直观。restart: always让容器在Docker守护进程重启后自动恢复，适合长期跑服务的场景。./mysql/conf是宿主机相对路径，把自己的自定义配置放这个目录就行；mysql-data是命名卷，把数据和配置分开管理。这种约定让整个项目的数据边界非常清晰。
5.3 compose的实际操作
启动：
docker compose up -d查看状态：
docker compose ps看日志：
docker compose logs -f mysql停止服务但保留数据：
docker compose stop彻底移除容器但不删卷：
docker compose down这里要特别小心一个操作：docker compose down -v。加-v会把卷一并删除，数据直接没了。我在实际环境里见过有人把服务器的数据卷带走了，那真是灾难性的。建议把down -v当成高危操作，平时一律用down或者stop就行。
6. 高频故障排查：Docker启动MySQL常见报错实录
把前面几个关键点做对之后，正常启动MySQL基本不会再出大问题。但还是把一些我遇到过的高频故障整理出来，方便你对照排查。
6.1 Docker Desktop启动失败：虚拟化相关
Windows上Docker Desktop启动后一直转圈，最后提示“Docker Desktop failed to start because virtualization support is not detected”。这个问题的根源基本是BIOS里的虚拟化没开，或者Windows功能里Hyper-V/WSL2没启用。排查顺序是这样的：先看任务管理器-性能-CPU里“虚拟化”是否已启用，如果显示禁用，进BIOS开启Intel VT-x或AMD-V；然后在PowerShell里执wsl --status，确认WSL状态，如果没安装发行版，执行wsl --install再重装；最后确认Docker Desktop设置里勾选了基于WSL2而非Hyper-V。绝大多数情况下，虚拟化开了、WSL2装好，问题就解决了。
6.2 ERROR 2002 (HY000)：socket连接误区
有个非常典型的报错：“ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock'”。这个报错基本都发生在宿主机上直接执行mysql -uroot -p，或者脚本里没指定host时。原因在于：MySQL客户端默认走socket文件连接本机服务，但宿主机上不存在/tmp/mysql.sock。你连的是Docker容器里的MySQL，就必须走TCP，在连接时明确加上-h127.0.0.1和-P3306。容器内部则相反，docker exec进入容器后，默认socket路径是/var/run/mysqld/mysqld.sock，直接mysql -uroot -p就能连。理解这个差异之后，“宿主机连不上MySQL”的排查思路就能清晰一大半。
6.3 端口占用导致容器反复退出
执行docker run之后docker ps发现容器Up，但几秒后又变成EXITED。查看docker logs mysql8，很常见的是Address already in use。这通常是宿主机3306端口被占用了，可能本机原来装过MySQL服务，或者另一个容器占用了端口。处理方式有两个：停掉占用端口的进程，或者换映射端口，比如把宿主机端口改成3307。Windows上查看端口占用：netstat -ano | findstr 3306，再用taskkill /PID 进程号 /F结束进程。Linux上执行ss -lntp | grep 3306。如果确认宿主机没被占用，还有一种可能是容器内的MySQL进程和自定义配置冲突，比如lower_case_table_names改了导致初始化数据不匹配，日志里会有明确提示，根据日志修正配置再重启。
6.4 老客户端连不上MySQL 8.0
MySQL 8.0用户认证插件默认是caching_sha2_password。如果客户端版本很老，尤其是很旧版本的Navicat或者旧版JDBC驱动，不认这个插件，连接时会报“Authentication plugin 'caching_sha2_password' cannot be loaded”。两个思路：升级客户端至支持MySQL 8.0的版本，或者把用户的认证方式改成mysql_native_password：
ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY '你的密码'; FLUSH PRIVILEGES;如果root没有允许远程登录，可能提示的是root@localhost，这时需要先确认user表里是否存在root@'%'账号。官方镜像在设置MYSQL_ROOT_PASSWORD时会创建一个root@'%'，但最好还是不要为了兼容把root改成native，而是建一个专用账号给外部客户端用，root保持默认认证插件，权限风险更小。
6.5 密码改了不生效
启动命令里写了MYSQL_ROOT_PASSWORD=新密码，容器重启之后连不上，密码还是旧的。原因就是前面讲过的：环境变量只在数据目录为空时的第一次初始化才生效。数据卷里已经有初始化数据后，改环境变量是无效的。如果确实忘记密码要重置，有两个正规做法。一是删除数据卷重新初始化，适合开发环境，docker compose down -v，注意这是危险操作。二是临时用skip-grant-tables模式启动容器，进入容器手工改密码。实际做法是在compose文件的command里加上--skip-grant-tables，进入容器执行ALTER USER语句改密码，改完必须去掉这个参数再重启。这个操作可以写进应急预案，但生产环境操作前一定要先备份数据。
6.6 镜像拉取慢或超时
docker pull mysql:8.0直接卡住或超时，多半是默认镜像源访问不畅。解决办法就是前面提到的配置registry mirror。Docker Desktop在Settings里的Docker Engine中改daemon.json，Linux则改/etc/docker/daemon.json后重启Docker服务。比如阿里云容器镜像服务里可以申请到个人加速地址，填进"registry-mirrors"数组就能明显提速。配置完成后再docker pull mysql:8.0，基本秒下。镜像拉下来之后，后续启动容器都不再依赖外网，这一点在离线环境部署时尤其实用。
容器跑起来只是第一步，真正让我觉得省心的是把数据卷、配置文件、Compose这老三样管好之后，后面几乎不用再碰它。我个人在实际操作中的体会是，用Docker启动MySQL这件事，核心不在于死记那条docker run命令，而在于理解“容器是可随时删除的，但数据和配置必须留在容器外面”。想通这一点，后面你无论是给项目加Redis、搭主从复制，还是把一个JavaWeb项目整体用Compose编排起来，用的都是同一套逻辑。哪怕是遇到把远程库的表同步到本地这种需求，本质上也就是mysqldump导出再导入容器，数据卷机制会让这个过程非常干净。希望这篇能把你的MySQL容器稳稳当当地跑起来，少踩几个我当年踩过的坑。
