Docker与Compose生产级部署实战：从安装、编排到踩坑全指南-平芜编程栈

都是在生产环境里跑过、被坑过以后反复验证过的结论。

1. 为什么Docker和Compose几乎总是成对出现

先把这个基础问题说透。很多人第一次接触Docker的时候，容易把Docker和Docker Compose搞混，其实它们解决的是两个不同层面的问题，但配合起来才是一个完整的工作流。

Docker本身是容器运行时，负责拉取镜像、启停容器、管理网络和数据卷。你可以在命令行用docker run启动一个容器，比如跑一个MySQL：

docker run -d \ --name mysql8 \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=yourpassword \ -v mysql_data:/var/lib/mysql \ mysql:8.0

那如果我们的项目需要同时跑MySQL、Redis、后端应用、前端Nginx呢？四个容器，每个都要写一大串参数，每次都要一个个启动、一个个停止，容器之间还要互相通信，手动管理多容器会出现几个很现实的问题：

启动顺序靠记，某个服务起晚了就连不上数据库
端口冲突排查起来很麻烦
容器之间的网络配置要么用默认bridge手动互联，要么用--link这种已经被官方标记为过时的功能
换个环境部署，同样的命令要重新敲一遍，环境差异导致各种莫名奇妙的问题

Docker Compose就是来解决这个问题的。它用一个docker-compose.yml文件把这些容器的配置、依赖关系、网络、数据卷都"声明"出来，然后用一条docker compose up -d把整个服务栈拉起来。

做个简单的类比：Docker是一间独立的集装箱房间，Docker Compose是一整栋楼的设计图加管理员。设计图规定了每个房间的位置、装修标准、水电怎么接，管理员负责按图纸施工和后续维护。没有图纸也能造房子，但一旦房间多了，图纸和管理员是刚需。

这也是为什么"完整的Docker部署教程"几乎必然要同时讲Docker和Compose。只装Docker不装Compose，遇到稍微复杂一点的场景就得靠脚本硬扛；只学Compose不懂Docker的基础命令和原理，出了问题完全不知道怎么排查。两个一起用，才能覆盖从单机单容器到多服务编排的完整链路。

2. Linux服务器上安装Docker引擎：核心步骤与镜像加速

安装Docker之前先想清楚一个问题：你的部署目地是生产环境还是个人测试？这个问题直接决定了你要不要加很多额外的配置。对于生产环境，我通常建议在干净的Linux服务器上安装Docker Engine而不是Docker Desktop，因为桌面版额外的虚拟机层在服务器上没有任何意义，反而增加资源消耗和故障点。

以下以Ubuntu 22.04 LTS为例，这也是目前云服务器最常用的版本之一。先更新系统并安装依赖：

sudo apt update sudo apt install ca-certificates curl gnupg lsb-release

然后添加Docker官方的GPG key和软件源。这一步很多教程简化掉直接跳过，但我建议老老实实加上，因为用官方源装出来的版本和apt自带的老旧版本差别很大，后者经常不带Compose插件，也不满足新特性的要求。

sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

接着安装Docker引擎和Compose插件。这里记住一个重点：新版Docker Engine安装包会同时提供docker-compose-plugin，装完以后系统里同时有docker和docker compose命令，这里的docker compose是插件形式，而不是老的独立二进制docker-compose，两者有区别，后面会专门展开讲。

sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

安装完成后启动服务并设置开机自启：

sudo systemctl enable docker --now sudo systemctl status docker

如果每一步都正常，最后用docker version验证一下。这个命令会同时显示Client和Server版本信息，如果只看到Client没有Server，说明Docker daemon没起来，这时候先看sudo systemctl status docker的日志再排查。

2.1 非root用户执行docker命令的正确姿势

这是几乎所有新手都会遇到的一个门槛：装完Docker以后，普通用户执行docker ps会报permission denied while trying to connect to the Docker daemon socket。原因是Docker的socket文件默认属于root用户和docker组，普通用户没有权限访问。

解决办法是把当前用户加入docker组，然后重新登录或者重启会话：

sudo usermod -aG docker $USER newgrp docker

注意一点：加入docker组相当于把root权限间接交给了这个用户，因为docker组内的用户可以随意操作宿主机文件系统。所以不要随便把业务账号加进docker组，生产环境建议用专门的部署账号，或者坚持用带sudo的方式执行。

2.2 配置国内可用的镜像加速器

这是"亲测有效"的关键前置条件。默认情况下Docker从Docker Hub拉镜像，网络状况不稳定的时候，一个几百MB的镜像能拉到怀疑人生，甚至直接超时。解决办法是配置registry mirror，让Docker从更快的镜像源拉取。

编辑/etc/docker/daemon.json（没有就新建）：

{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://dockerproxy.com", "https://docker.nju.edu.cn" ] }

然后重启Docker：

sudo systemctl daemon-reload sudo systemctl restart docker

配置好以后用docker info查看Registry Mirrors那一段是否生效。如果拉取还慢，可以试试其他镜像站，但我不建议把太多镜像源一股脑都填进去，两三个够用的就行。填多了反而可能出现源切换的额外耗时。另外注意，镜像加速器只影响从Docker Hub拉取的镜像，从其他私有仓库或者第三方平台拉镜像不走这个配置。

CentOS、Debian等其他发行版的安装步骤基本类似，套路就是：装依赖、加源、装docker-ce、启动服务。区别主要在包管理器命令和软件源路径，核心配置daemon.json和用户组设置是通用的。

3. Windows和macOS的场景：Docker Desktop还是纯命令行

本地开发和测试环境用Windows或者macOS，跟服务器上的安装方式则完全不同。很多人下载Docker Desktop以后被各种报错劝退，其实不是软件不行，而是没搞清楚它的运行机制。

Docker Desktop的底层是自己管理的一个轻量级虚拟机，在Windows上是基于WSL 2或者Hyper-V，在macOS上是基于Apple Virtualization框架或者老一点的HyperKit。所有容器实际都跑在这个Linux虚拟机里，Docker Desktop只是它的图形化管理壳。明白了这个基本原理，很多问题就有了排查方向。

3.1 安装Docker Desktop之前先检查虚拟化

最常见的问题之一就是启动时报错Virtualization support not detected。原因很直接：BIOS里的虚拟化功能没开启。

进BIOS查一下CPU虚拟化设置，Intel平台叫VT-x或者Intel Virtualization Technology，AMD平台叫SVM Mode，把它改成Enabled保存重启，大部分问题就解决了。

Windows上还有第二道开关：控制面板—程序—启用或关闭Windows功能，确认以下两项至少有一项是开的：

Hyper-V
适用于Linux的Windows子系统（WSL）
虚拟机平台

推荐最新的Windows 11直接开WSL 2，然后安装Docker Desktop时选择使用WSL 2 backend。这样比Hyper-V更轻量，集成的Linux内核由wsl命令统一管理，日常使用也更顺滑。

装完Docker Desktop以后，它在系统托盘常驻，所有Docker相关命令在PowerShell、CMD或者Windows Terminal里都能直接用。Docker Desktop内置了docker compose插件，所以compose相关的命令在本地一句额外的东西都不用装。

3.2 Docker Desktop的镜像源配置

本地开发同样要配置镜像加速，不然一样会被拉镜像卡住。打开Docker Desktop的Settings，切到Docker Engine这个Tab，能看到一段JSON配置，在registry-mirrors字段里填入跟服务器版一样的镜像源即可：

{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://docker.nju.edu.cn" ] }

改完点Apply & Restart，Docker Desktop会自动重启并生效。

3.3 挂载本地文件目录做数据卷时踩的坑

在Windows上用Docker Desktop挂载本地目录做数据卷，比如把MySQL的数据文件挂载到D:\mysql-data，看起来配置没问题，但容器跑起来以后写文件失败，日志报Permission denied或者Can't create/write to file。

根因在于：Windows文件系统映射到Linux虚拟机里的权限模型不一致，Docker Desktop会弹窗让你授权共享驱动器。在Settings -> Resources -> File Sharing里把D盘加进去，或者直接把所有盘符授权，这问题就没了。另外，数据卷目录尽量不用中文路径和带空格路径，Windows路径的兼容性本来就敏感，别给自己找额外的麻烦。

4. Compose的安装方式与版本差异

如果用的是Docker Desktop，或者新版Docker Engine加docker-compose-plugin，docker compose子命令直接可用。但如果是历史遗留环境、离线安装、或者某台服务器上的Docker版本比较老，就得单独处理Compose。

先说清楚两个容易混淆的东西：

docker-compose：独立的Python二进制文件，老式写法，通常安装到/usr/local/bin/docker-compose
docker compose：Docker官方插件，集成在CLI插件目录里，新式写法

功能上两者差别不大，但新项目我强烈建议用后者，因为它是官方持续维护的，也更符合Docker命令行生态的演进方向。Compose文件格式现在已经演进到v2/v3，新版docker compose对现代语法的支持也更好。

4.1 独立二进制安装方式

确实需要单独安装docker-compose二进制时，官方推荐的方式是去GitHub Releases页面下载对应的二进制文件：

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose

验证一下版本：

docker-compose version

如果网络环境访问不了GitHub，可以从镜像站下载，或者找一台已经装好Compose的机器把二进制拷贝过去。独立二进制安装完成以后要确认/usr/local/bin在PATH里，不然执行命令会提示找不到。

4.2 Compose文件格式的版本匹配问题

Compose文件开头的version字段（例如version: "3.8"）在旧版必须写，新版官方已经不推荐写了。我实测下来这个字段不写也不影响运行，新版Compose会直接按最新格式解析。

但有一个场景要注意：假设你的生产服务器上Docker Compose还是老版本（比如1.25那种），而你的docker-compose.yml里用了depends_on的condition新语法、healthcheck、init这些新特性，老版本根本解析不了，直接报错。所以拿到别人的Compose文件先看本地的Compose版本，再决定要不要调整语法。这里给一个参考：Compose v1.27以上才支持完整的depends_on.condition，v2.0以上才比较完整地支持healthcheck链式依赖。

5. 第一个生产级编排实践：MySQL 8.0 + Redis主从

纸上谈兵说多了没用，下面用一个比较典型的场景把整个Compose编排流程串起来：部署一套MySQL 8.0（带数据持久化），加一个Redis主从架构（主库写、从库读，支持故障手动切换的那种基础形态），最后再挂一个最简单的应用容器来验证服务间网络互通。这个组合基本覆盖了日常项目90%的编排需求。

先看目录结构：

deploy/ ├── docker-compose.yml ├── .env └── mysql/ └── conf/ └── my.cnf

.env文件存放环境变量，目的是把密码这类敏感信息跟Compose文件分离，也方便不同环境用不同配置：

MYSQL_ROOT_PASSWORD=strong_root_password MYSQL_DATABASE=app_db MYSQL_USER=app_user MYSQL_PASSWORD=app_password REDIS_REQUIREPASS=redis_pass_123

然后是docker-compose.yml：

services: mysql: image: mysql:8.0 container_name: mysql8 restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} TZ: Asia/Shanghai command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci - --default-time-zone=+8:00 ports: - "3306:3306" volumes: - mysql_data:/var/lib/mysql - ./mysql/conf/my.cnf:/etc/mysql/conf.d/my.cnf:ro healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-p${MYSQL_ROOT_PASSWORD}"] interval: 10s timeout: 5s retries: 5 start_period: 30s redis-master: image: redis:7.2 container_name: redis-master restart: unless-stopped command: ["redis-server", "--appendonly", "yes", "--requirepass", "${REDIS_REQUIREPASS}"] ports: - "6379:6379" volumes: - redis_master_data:/data redis-replica: image: redis:7.2 container_name: redis-replica restart: unless-stopped depends_on: - redis-master command: ["redis-server", "--appendonly", "yes", "--replicaof", "redis-master", "6379", "--masterauth", "${REDIS_REQUIREPASS}", "--requirepass", "${REDIS_REQUIREPASS}"] ports: - "6380:6379" volumes: - redis_replica_data:/data app: image: nginx:alpine container_name: demo-app restart: unless-stopped depends_on: mysql: condition: service_healthy redis-master: condition: service_started ports: - "8080:80" volumes: mysql_data: redis_master_data: redis_replica_data:

运行：

cd deploy docker compose up -d

查看运行状态：

docker compose ps

看到healthy状态以后，进数据库验证一下：

docker exec -it mysql8 mysql -uapp_user -papp_password app_db

进MySQL以后执行SELECT 1;能正常返回就说明数据库通了。

5.1 为什么每个关键配置都要这样写

数据卷挂载是唯一能保证容器重建后数据还在的方式。很多人图省事直接把数据库目录挂到宿主机的普通文件夹，但那样权限问题、IO性能问题接踵而来。用命名卷（named volume）让Docker自己管理存储位置，既能保持数据持久化，又规避了跨平台权限问题，我强烈建议数据库这类有持久化需求的服务都用命名卷。

restart: unless-stopped是企业部署的默认选择。它跟always的区别在于：当容器被用户手动docker compose stop停掉以后，unless-stopped不会在Docker重启时把它拉起来，适合明确要停的服务；而always会在Docker daemon启动时不管之前是什么状态都拉起。生产环境我用unless-stopped多一点，因为运维有手工维护的余地。

depends_on配合healthcheck才能实现真正的按序启动。早期的Compose只保证服务启动顺序，但不保证服务内部真正就绪。MySQL可能容器起来了但还在初始化目录，这时候应用去连接它必然失败。加了healthcheck以后，depends_on的condition: service_healthy会让Compose一直等MySQL通过健康检查才启动下一个服务。这是生产级编排和玩具级编排的分水岭。

Redis主从的replicaof参数里，主机名直接写Compose服务名redis-master。这是Compose内部网络DNS带来的便利，服务之间不用记IP，用服务名就能互相解析。同样的道理，应用容器里连MySQL就直接用mysql:3306，连Redis从库就用redis-replica:6379。

关于账号密码，Compose会自动读取同目录的.env文件，把变量插进docker-compose.yml。这样docker-compose.yml本身可以提交到Git仓库，而.env留在服务器本地或者用密钥管理工具单独分发，避免了密码被提交进仓库的风险。

5.2 生产环境还可以补几刀

上面这个配置跑起来已经能应付大多数演示环境了，但要上生产，我一般还会加这么几件事：

在MySQL的my.cnf里显式限定bind-address = 0.0.0.0，否则容器内MySQL默认只监听localhost，外部工具连不上
Redis如果只需要内网访问，从库端口可以不映射到宿主机，让它在Compose网络内部通信就好
给Compose项目设置独立的网络别名，避免多个项目之间的容器因为服务名冲突而串网
加一层oom_score_adj或者deploy.resources.limits限制资源使用，防止某个容器异常吃满内存拖垮宿主机

比如docker compose.yml里可以加资源限制：

deploy: resources: limits: cpus: '0.50' memory: 512M

注意deploy.resources在非Swarm模式下新版本Compose直接支持，但老版本可能提示忽略，这个语法要跟Compose版本匹配，别在旧版本上白费力气。

6. 日常运维中真正用得上的命令清单

装好、部署好只是开始，日常维护才是大头。下面这份清单是我在各种项目里反复用到的命令，每条都标了使用场景和注意事项。

命令	使用场景	注意事项和坑
`docker compose ps`	查看服务栈内所有容器状态	加`-a`可以看到已停止的容器
`docker compose logs -f <service>`	跟踪某个服务的实时日志	不指定服务名会输出所有容器日志，噪音大
`docker compose exec <service> <cmd>`	进入正在运行的容器执行命令	加`-u root`可切换用户；不要用`docker exec`替代，前者会更准确定位服务
`docker compose config`	校验Compose文件并展开变量	改动.yml以后先跑一遍，能发现大部分语法错误
`docker compose down`	停止服务并移除网络	加`-v`时连数据卷一起删，不可恢复，执行前想清楚
`docker compose restart <service>`	单独重启某个服务	不改代码不重建，适合配置了环境变量的服务
`docker compose build --no-cache`	重新构建镜像，不用缓存层	构建Dockerfile改过基础依赖时用
`docker system df`	查看镜像、容器、数据卷占用空间	定期看一下，避免磁盘被撑爆
`docker system prune -af`	清理所有停止容器和无用镜像	高危操作，生产环境先确认没有需要保留的离线镜像
`docker stats`	实时查看所有容器CPU/内存占用	排查性能问题或者内存泄漏特别好用

其中docker compose config被很多人忽略，它其实是最早能暴露问题的一步。写错一个缩进、变量没定义，直接运行up会浪费时间，先用config展开检查最划算。

还要提一个习惯：不要在生产环境用latest标签，锁定镜像的具体版本号或者用commit SHA。latest标签随上游更新而漂移，哪天你执行了docker compose pull，容器悄悄跑上新版本，行为变化可能毫无预兆。锁版本配合docker compose的声明式配置，才能做到"这个部署是可复现的"。

7. 亲测踩过的坑和对应解法

这部分才是标题里"亲测有效"四个字的分量所在。下面这些坑，我每一个都在真实环境里遇到过，先说现象和排查链路，再给最终解法，你可以按同样的思路去排查自己的问题。

7.1 Permission denied while trying to connect to the Docker daemon socket

现象：普通用户执行docker ps报错，sudo docker ps正常。

排查链路：第一反应看docker version是否正常，确认Client和Server都在；接着看/var/run/docker.sock的文件权限；然后看当前用户是否属于docker组。

解法：sudo usermod -aG docker $USER，重新登录。忘了重新登录是这个坑的另一个常见原因，newgrp docker可以临时刷新当前会话而不需要注销。

7.2 Windows上Docker Desktop持续报Virtualization support not detected

现象：Docker Desktop启动几秒后报错，日志显示虚拟化检测失败。

排查链路：先任务管理器确认虚拟化是否已启用；若显示"已启用"，去控制面板检查Hyper-V和虚拟机平台是否打开；如果这两项都正常，问题出在BIOS里的VT-x被关闭了。

解法：重启机器进BIOS，把Virtualization Technology改为Enabled，开机再验证。笔记本用户特别注意：有些电脑在电池模式下默认关闭虚拟机开关，插上电源重启一次可能就好了，这个情况比较隐蔽，遇到就多试一次。

7.3 拉取镜像超时或者速度极慢

现象：docker pull跑很久，最后提示net/http: request canceled。

排查链路：先确认是不是首次拉取大镜像（比如MySQL这种体积的），网络慢会导致一个几百MB的镜像拉十几分钟；然后检查daemon.json里registry-mirrors是否生效；如果配置了多个镜像源，逐一套出来测试哪个真正可达。

解法：配置镜像加速器（见2.2节），或者临时从国内云厂商的镜像仓库拉取，改tag以后再用。另外拉镜像的时候不要开太多并行任务，带宽有限的情况下并行拉取反而会更慢。

7.4 容器起来了，但应用连不上MySQL

现象：docker compose up -d全部显示Up，应用日志报Access denied for user，或者Can't connect to MySQL server on 'mysql'。

排查链路：先在宿主机上验证MySQL端口通不通，telnet 127.0.0.1 3306（注意Windows下要先开telnet服务）；再进MySQL容器看进程状态，docker exec -it mysql8 mysql -uroot -p；如果是连接被拒，重点看MySQL的bind配置和用户授权；如果是密码错误，确认一下.env里的变量是否被正确读取，docker compose config看展开后的实际值。

解法：MySQL容器里的授权规则要照顾到连接来源，Compose网络里连接MySQL的主机名是服务名，要给对应的用户授权mysql -h localhost和mysql -h mysql都能通过。配置示例：

CREATE USER 'app_user'@'%' IDENTIFIED BY 'app_password'; GRANT ALL PRIVILEGES ON app_db.* TO 'app_user'@'%'; FLUSH PRIVILEGES;

7.5 容器启动后时区不对，日志时间差8小时

现象：容器日志时间跟北京时间差8小时，MySQL里存储的时间字段也是错的。

排查链路：容器默认使用UTC时区，宿主机和容器各走各的时钟。看docker exec <container> date的输出即可验证。

解法：Compose配置里给每个服务加TZ: Asia/Shanghai环境变量，MySQL这类应用还需要在command或者配置文件里设置--default-time-zone=+8:00。如果是Debian系的基础镜像，有些还要装tzdata包，否则TZ环境变量不生效。Java应用的话除了容器时区，JVM默认时区也要一并处理。

7.6 Redis主从配置好了但从库连不上主库

现象：redis-replica日志一直报MASTER <-> REPLICA sync started，但是没有MASTER <-> REPLICA sync finished，或者直接报NOAUTH Authentication required。

排查链路：先确认主库是否设置了密码；再看从库的--masterauth有没有配上；如果主库配置了bind 127.0.0.1，从库在别的容器里根本连不上主库的地址；最后看Compose网络里能否用服务名解析到主库。

解法：主库的redis-server命令不要加--bind 127.0.0.1，如果担心安全，用Compose的expose而不是ports对外只暴露给同网络内的服务；从库的--masterauth必须和主库的--requirepass一致。日志里看到Full resync就说明从库已经开始正常同步了。

8. 一套部署配置拷到另一台机器就能跑，才叫真有效

写到这我停一下，想聊点个人体会。标题里"亲测有效"四个字，看上去是"我这套配置跑通了"的意思，但我的理解更深一层：有效的标准是，任何一个人拿到你的Compose文件，在一台干净的机器上能复现出同样的结果。

我最开始接触Docker的时候，也是照着网上的教程一步步装，装完发现各种细节对不上，比如系统版本不同、镜像源失效、新旧工具混用。后来整理出自己的部署模板，固定流程：装引擎、配置加速器、套Compose模板、验证健康检查、跑日志、锁版本号、记录变更。这套流程完整走一遍以后，部署的时间成本直线下降。

日常工作中我还在用这么一个小技巧：把一套完整的生产Compose项目（docker-compose.yml加.env.example加README）放进Git仓库管理。.env这类含敏感信息的文件用.gitignore排除掉，只提交.env.example作为模板。换服务器的时候，git clone下来，把.env.example复制一份为.env填好密码，docker compose up -d，整个服务栈就起来了，整个迁移过程半小时内绝对能搞定。我在实际使用中发现，这套"从零搭建到一键复现"的工作流，比记住任何一条具体命令都更有价值，也是我坚持推荐Compose的根本原因。