Docker Compose部署Nginx实战：从配置挂载到反向代理与负载均衡-代码聚汇网

Docker Compose部署Nginx实战：从配置挂载到反向代理与负载均衡

戈玄白今天要做题·2026-09-13·阅读 21 GEO检测（免费）

Docker ComposeNginx反向代理

|难度：普通|阅读约 42 分钟

“docker compose”这个名词，但凡你接触过Docker，多少都见过几次。它比docker run更好用、更清晰，尤其适合在一台服务器上跑多个容器、或者想把一套服务的启动方式固化下来的场景。这篇文章我会从Compose的核心概念讲起，再手把手带你在Linux服务器上用Docker Compose把Nginx搭起来，覆盖配置挂载、反向代理、负载均衡和生产环境的常见坑，全部是我实际跑过、踩过、验证过的经验。

如果你正准备用Nginx做静态站点、反向代理或者负载均衡入口，又不想每次部署都靠记忆敲一长串docker run，这篇文章就是给你准备的。哪怕你是第一次听说Compose，按下面的步骤走完，也能独立搭出一套像样的Nginx服务。

1. 先搞懂Docker Compose解决的是什么问题

1.1 为什么docker run不够用

先说一个最常见的场景。你有一个Spring Boot后端、一个MySQL、一个Redis，加一个前端Nginx，四个人要服务配合起来才能跑通一套业务。用docker run一个个拉起来不是不行，但问题很现实：

每次启动都要敲一长串参数，映射端口、挂载目录、指定网络，漏掉一个参数服务行为就不一样。
容器之间的通信依赖网络配置，单独跑的时候你得手动docker network create，然后再把每个容器都--network指过去。
配置没法版本化，哪天服务器重装，你只能凭记忆或者翻历史命令把服务一个个恢复起来。
同时操作多个容器时，启停顺序、依赖关系全是靠人肉控制。

Docker Compose就是为解决这些问题出现的。它用一个compose.yaml文件，把你要启动的所有服务、网络、卷、端口映射、依赖关系都声明清楚。之后一条docker compose up -d，整套服务一次性拉起；一条docker compose down，整套服务干干净净停掉。配置进Git，换机器直接拉代码启动，这比任何脚本都靠谱。

有人会说“我写个shell脚本不也一样吗”。脚本的问题是它描述的是“怎么做”，而不是“要什么”。比如脚本里写了先启动MySQL、再启动后端，但换个环境端口冲突了、目录不存在了，你需要在脚本里加各种判断逻辑。Compose的模型是声明式的，你告诉它最终要什么样，它自己处理顺序和依赖，这才是容器编排该有的思路。

1.2 Compose的三板斧：service、network、volume

compose.yaml核心就三类对象：服务（services）、网络（networks）、卷（volumes）。搞清楚这三者的关系，Compose基本就懂了一半。

**服务（services）**是核心，每个服务对应一个镜像和一组运行配置。比如Nginx服务、MySQL服务、后端Java服务，每个服务都类似一次docker run，但写法更结构化。你可以指定镜像、容器名、端口映射、环境变量、挂载卷、健康检查、重启策略等。

**网络（networks）**解决服务间的通信问题。Compose默认会为项目创建一个网络，同一个compose.yaml里的服务天然在同一个网络里，可以直接用服务名互相访问。比如Nginx要代理后端接口，配置里直接写proxy_pass http://backend:8080，这里的backend就是后端服务的服务名，Docker内建的DNS会自动解析成对应的容器IP，而这个IP是动态的，重新启动就可能变，所以必须用服务名而不是IP。

**卷（volumes）**解决数据持久化和配置注入问题。容器是临时的，删掉重建数据就没了，所以需要把宿主机目录挂载进容器，或者用命名卷让Docker帮你管理存储。Nginx这种无状态服务，主要挂载的是配置文件、静态文件和日志目录，后面我会专门讲。

1.3 为什么我用Compose而不用docker-compose

这里必须提一个很多新人困惑的点：docker-compose和docker compose到底什么关系。

早期Docker Compose是独立于Docker Engine的Python工具，用docker-compose命令调用。后来Docker官方把Compose以插件形式集成进了Docker Engine，成为V2版本，命令也变成中间不带横杠的docker compose。现在你安装新版Docker Engine的时候，Compose V2插件是默认自带的一部分，不需要单独安装。

所以下文里我统一使用docker compose（V2）的命令格式。如果你用的还是老版本环境，只有docker-compose，逻辑上完全一样，只是命令里多个横杠的区别。配置文件名方面，V2默认识别compose.yaml，也兼容老的docker-compose.yaml，我推荐统一用compose.yaml，干净而且符合新规范。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备：把Docker和Compose插件装利索

2.1 Linux服务器上安装Docker Engine

现在大多数云服务器都是CentOS 7/8、Ubuntu 20.04/22.04这类系统，安装Docker Engine的方式官方文档写得很详细，我只把最核心的步骤和容易出错的地方说一下。

Ubuntu 22.04上用官方仓库安装，按顺序执行：

bash复制sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /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
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

docker-compose-plugin这个包必须带，它对应的就是Compose V2插件。安装完以后验证一下：

bash复制docker --version
docker compose version

CentOS这边稍微提一嘴：sudo yum install -y yum-utils，然后sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo，再sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin，装完sudo systemctl start docker，再sudo systemctl enable docker，让Docker开机自启。服务器重启过以后不用手动去启动Docker服务，这个细节很多人容易漏。

2.2 确认Compose V2插件真的能用

验证Compose能不能用，不是看装了没装，而是直接执行命令看输出：

bash复制docker compose version

正常你会看到类似Docker Compose version v2.24.2这样的输出。如果提示docker: 'compose' is not a docker command，说明Compose插件没装好，要么是装Docker时漏了docker-compose-plugin，要么是插件目录权限不对。排查思路很简单：

bash复制ls -l /usr/libexec/docker/cli-plugins/docker-compose

这个文件存在且可执行，docker compose命令就能识别。如果文件不存在，优先补装插件，不要想着自己去下载二进制扔进去，系统包管理器装的版本更匹配，省事。

2.3 镜像拉取的建议

国内拉Docker Hub的镜像速度经常让人崩溃，特别是nginx、redis这类官方镜像，网络一差就超时。我的建议是，如果你所在网络环境访问Docker Hub不理想，就配置镜像加速源。在/etc/docker/daemon.json里写入：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

改完执行sudo systemctl restart docker。注意，这个文件如果不存在就新建。配置完以后docker pull nginx:1.25，看看速度有没有变化。不同地区的网络环境差异很大，哪个源稳定就填哪个，我这里只是举一个我实际用过、延迟可以接受的地址。拉镜像不是只用一次，后期每次部署都会用到，这里花两分钟配置好，长远看非常值。

3. 用Compose搭建Nginx：从目录结构到编排文件

3.1 目录规划先行

很多初学者图省事，把容器跑起来再说，配置文件、日志乱糟糟塞在服务器各个角落。这种习惯等到要排查问题的时候就痛苦了，日志不知道在哪，配置文件是容器里的还是宿主机的都分不清。我的习惯是，每个项目单独建一个目录，所有和这个项目相关的容器配置、挂载目录全部收拢在一起。

比如我要搭一个Nginx网关，先建一个工作目录：

bash复制mkdir -p ~/nginx-compose/nginx/{conf.d,html,logs}
cd ~/nginx-compose

目录结构如下：

code复制nginx-compose/
└── compose.yaml
    └── nginx/
        ├── conf.d/      # Nginx站点配置文件
        ├── html/        # 静态文件
        └── logs/        # 日志目录

为什么这么分？conf.d目录用来放Nginx的站点配置，Nginx镜像里/etc/nginx/nginx.conf一般会在文件末尾include这个目录下的所有.conf文件，所以业务配置我们放在这里，不需要去改主配置。html目录挂到/usr/share/nginx/html，这是Nginx默认的静态站点根目录。logs挂到/var/log/nginx，容器日志写到宿主机，后面排查看日志直接用tail就行，不需要进容器。

3.2 compose.yaml内容逐行拆解

在~/nginx-compose目录下创建compose.yaml，内容如下：

yaml复制services:
  nginx:
    image: nginx:1.25-alpine
    container_name: nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/html:/usr/share/nginx/html:ro
      - ./nginx/logs:/var/log/nginx
    networks:
      - nginx-net

networks:
  nginx-net:
    driver: bridge

逐项说明：

image: nginx:1.25-alpine，我选alpine版本，镜像大概几十MB，比标准版小很多，基础系统是Alpine Linux，性能和兼容性都没问题。如果你想用标准版，改成nginx:stable或者带具体版本号都可以。
container_name给容器起一个固定的名字。这样docker exec -it nginx bash的时候不用查容器ID，方便。
restart: unless-stopped比较关键。服务器重启后，Docker会自动把这个容器拉起来，除非你手动停止过它。生产环境我基本都用这个策略。
ports做端口映射。宿主机80端口映射到容器80端口，443同理。如果宿主机80端口被占用，可以改成"8080:80"，之后访问就用8080端口。
volumes就是前面说的挂载。注意conf.d和html两个目录加了:ro，表示只读挂载。原因是这些目录只需要宿主机往里写，容器内只需要读，只读挂载能防止容器内部误操作改掉配置，也符合最小权限原则。logs目录不加ro，因为Nginx要向里面写日志。
networks里定义了一个nginx-net网络，驱动是bridge（桥接），这是Docker默认的容器间通信方式。目前只有一个Nginx服务，单独定义网络看起来有点多余，但后续如果要在同一个Compose文件里加后端服务、让Nginx反代过去，这个网络就有大用了。

技术细节说一句：在现代Docker Compose中，即使不定义networks，Compose也会自动为你的项目创建一个默认网络，所有服务自动加入。但我还是习惯显式声明网络，第一是语义清晰，第二是后续要调整网络参数时不用大改文件。

3.3 启动、检查和停止

文件写好后，先做一次配置检查：

bash复制docker compose config

这条命令会把compose.yaml里的配置渲染成最终的解析结果打印出来。如果语法有错，这里就会报出来，不会等到启动时才发现在哪个地方少了一个缩进。确认无误后启动：

bash复制docker compose up -d

-d表示后台运行。输出正常的话，检查容器状态：

bash复制docker compose ps

看到STATUS一栏是Up就说明起来了。再用浏览器访问服务器IP，或者curl http://localhost，如果你没改配置，静态目录下也没有文件，就会看到Nginx的默认欢迎页Welcome to nginx!。

停止服务用：

bash复制docker compose down

这个命令会停止并删除容器，但不会删除挂载卷里的数据，所以日志和配置文件都还在。如果连网络一起清理掉，加--volumes参数，但这里我们没用到匿名卷，不需要加。

4. 让Nginx真正干活：配置挂载与常用场景

4.1 Nginx配置文件的组成结构

Nginx的配置核心是nginx.conf，但业务上的server块、upstream块我们一般放在/etc/nginx/conf.d/目录下，通过主配置文件的include指令引入。使用Docker部署时，主配置来自镜像内部，我们不改它，只挂载conf.d目录就行，这个思路和直接编译安装Nginx时组织配置完全一致。

配置一个最简单的静态站点，在宿主机创建nginx/conf.d/default.conf：

nginx复制server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

然后往nginx/html/index.html里写点内容，比如：

html复制<!DOCTYPE html>
<html>
<head><title>Hello Nginx</title></head>
<body>
  <h1>docker compose + nginx 跑通了</h1>
</body>
</html>

改完配置后，需要让Nginx重新加载配置，不用重启容器：

bash复制docker exec nginx nginx -t
docker exec nginx nginx -s reload

nginx -t先测试配置文件语法是否正确，这是必须的一步，语法错了Nginx会拒绝reload，但你不会知道问题出在哪，直接跑服务一切看起来正常结果页面404，这种体验我太熟悉了，都是血泪教训。nginx -s reload会让Nginx平滑加载新配置，连接不中断。

4.2 反向代理配置细节

Nginx最常见的生产用途就是反向代理。前面提到热搜里有个问题“ip头部的五元组信息nginx转发会带吗”，这个值得展开说一下。

五元组一般指源IP、源端口、目的IP、目的端口、协议。Nginx做反向代理之后，后端服务看到的连接来自Nginx容器，而不是真实客户端。如果不做任何处理，后端拿到的源IP就是Nginx的容器IP，这在做用户IP识别、访问控制的时候会带来问题，需要用X-Forwarded-For等头部把客户端信息带过去。

配置示例：

nginx复制server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

这里backend是Compose里另一个服务名。proxy_set_header的作用是把请求头属性改掉或增加。Host保持原始域名，X-Real-IP直接取$remote_addr，也就是Nginx直接连接的客户端地址。X-Forwarded-For是标准做法，会在原值基础上追加一层代理的客户端IP，如果前面还有一层代理，这个头能记录完整链路。

后端服务也要配合。以Spring Boot为例，它默认能够识别X-Forwarded-For，通过request.getHeader("X-Forwarded-For")拿到真实IP。但如果后端是自研服务且通过四层负载均衡接入，可能还需要额外配置，这已经超出Nginx范围，但你至少要明白链路是怎么走的。

如果只想把一组服务放在Compose里，让Nginx反代它们，可以这么组织：

yaml复制services:
  nginx:
    image: nginx:1.25-alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
    networks:
      - nginx-net

  backend:
    image: your-backend-image
    expose:
      - "8080"
    networks:
      - nginx-net

networks:
  nginx-net:
    driver: bridge

注意backend服务我没有写ports，而是用了expose。ports会映射到宿主机，expose只在Compose内部网络暴露端口，外部访问不到。这样做的好处是后端服务不直接暴露给外部，只有Nginx能通过内部网络访问它，安全上多了一层。这是生产部署里非常推荐的做法。

4.3 负载均衡配置示例

Nginx另一个高频用法是负载均衡。假设你有两个后端实例，Nginx把请求分发到这两个实例上，配置如下：

nginx复制upstream backend_servers {
    server backend1:8080 weight=3;
    server backend2:8080 weight=1;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

upstream块定义后端服务器组，server指令列出成员和权重。weight=3表示backend1分配权重是backend2的3倍，默认轮询策略如果不加权重，就是每个请求轮流分发。后端服务异常时，Nginx会自动把请求发给健康的节点，这是Nginx负载均衡最基本的行为，不做复杂度解释，能跑通就行。

对应的Compose服务配置：

yaml复制services:
  nginx:
    # 和上面一样
    networks:
      - nginx-net

  backend1:
    image: your-backend-image
    expose:
      - "8080"
    networks:
      - nginx-net

  backend2:
    image: your-backend-image
    expose:
      - "8080"
    networks:
      - nginx-net

Nginx容器通过服务名backend1和backend2解析到对应容器的IP。这里注意，如果服务名带下划线或特殊字符，Nginx的upstream server名称要确保能被DNS解析。绝大多数情况服务名都能解析，但如果你在配置里遇见奇怪的解析问题，先检查服务名是否合法，再检查两个容器是否在同一个网络。

5. 生产环境必须注意的那几件事

5.1 日志别丢，别乱

Nginx访问日志默认输出到容器内的/var/log/nginx/access.log，错误日志是error.log。前面我在compose里把宿主机./nginx/logs挂载到了这个目录，所以日志会持久化到宿主机。有一类常见问题就是容器时间不对，Nginx日志时间戳和宿主机时间差8小时，这是镜像时区导致的。要解决，可以在compse环境变量里设置TZ: Asia/Shanghai：

yaml复制    environment:
      - TZ=Asia/Shanghai

日志的切割也值得留意。长时间运行的Nginx，access.log会越来越大，不加处理能到好几个G。思路是让Nginx定期重新打开日志文件，配合logrotate或者写一个定时任务来切割。这里不展开，但提一个关键点：不要直接用mv移动日志文件而不通知Nginx，移动后Nginx还是会往旧inode写日志，空间不会被释放。正确姿势是移动后执行docker exec nginx nginx -s reopen，让Nginx重新打开新的日志文件。

5.2 端口冲突和防火墙

端口映射时最常见的报错是这样的：

code复制Error response from daemon: driver failed programming external connectivity on endpoint nginx: Bind for 0.0.0.0:80 failed: port is already allocated

意思是宿主机80端口已经被占用了。排查方式先看端口被谁占了：

bash复制ss -tlnp | grep :80

如果是别的服务占用了，要么停掉那个服务，要么把Nginx映射到其他端口，比如宿主机8080映射容器80。注意，很多云服务器厂商的安全组规则默认不放开80端口，你本地curl通、外网访问不通的时候，先检查云控制台安全组有没有放行80和443端口，这是新手最容易忽略的一环。

5.3 健康检查与自动重启

Compose里可以为服务定义健康检查，让Docker确认服务是否真正可用，而不只是进程还活着。对于Nginx，健康检查可以这样做：

yaml复制    healthcheck:
      test: ["CMD", "nginx", "-t"]
      interval: 30s
      timeout: 5s
      retries: 3

但注意nginx -t检查的是配置语法，不能完全代表服务能正常响应请求。更接近真实情况的是用wget或curl请求一个健康检查路径：

yaml复制    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost/health >/dev/null 2>&1"]
      interval: 30s
      timeout: 5s
      retries: 3

不过nginx:alpine镜像里不一定带wget，可能要用wget相关命令或者用curl，需要确认镜像里装的工具。如果镜像里没有这些工具，也可以直接依赖restart: unless-stopped配合Docker自身检查机制，实际上Nginx进程退出时，容器会退出，unless-stopped策略会把容器重新拉起。

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

6.1 修改配置后不生效

很多人改了宿主机挂载的配置文件，然后发现Nginx还是旧行为，排查方向是：

有没有真正reload。改配置后必须docker exec nginx nginx -s reload，让Nginx重新加载。
挂载的配置路径对不对。有些镜像主配置文件include的是/etc/nginx/conf.d/*.conf，但如果你把配置挂到了别的目录，Nginx根本不会加载。
端口映射有没有挂对。映射关系是宿主机端口:容器端口，不要反过来理解。宿主机8080映射容器80，访问的是8080。

有个常见的误操作是改了容器内部的文件而不是宿主机挂载的源文件。因为挂载生效后，两个位置是同一份文件，但如果你手动进容器改了文件，容器删除重建后配置就会回到镜像内的原始状态。所以配置文件一定要以宿主机为准，容器里的改法只适合临时调试。

6.2 权限导致403或404

挂载了html目录后，浏览器访问经常遇到403 Forbidden。大部分原因是挂载目录的属主和权限不对。Nginx的worker进程在容器内以nginx用户运行，如果你宿主机的挂载目录权限是700，且属主是root，容器内的nignx用户读不到文件。

解决办法，要么把目录权限改成755，要么在Compose里通过用户映射解决，不过最简单粗暴也最有效的是保证目录对所有人可读：

bash复制chmod -R a+rX ~/nginx-compose/nginx/html

404也有可能是try_files $uri $uri/ =404;配置导致的。因为你没有对应的静态文件，自然返回404。调试时先缩小范围，直接访问IP看默认页是否正常，再叠加业务配置。

6.3 nginx: 未找到命令的几种情形

热搜词里有个“nginx: 未找到命令”，我见过几种情况：

在宿主机直接敲了nginx命令，但你的Nginx是在容器里跑的，宿主机并没有安装Nginx二进制。解决办法是docker exec nginx nginx -t，所有Nginx命令都应该通过容器执行。
容器内的shell环境变量PATH没包含Nginx安装目录。alpine镜像里Nginx一般在/usr/sbin/nginx，正常情况下是能直接执行的。如果提示找不到，显式写全路径执行即可。
你想用docker compose exec进容器，但容器已经停了，exec进不去。先docker compose start启动容器再执行。

理解一句话：用Docker部署的服务，操作入口是容器，不是宿主机。所有和Nginx相关的命令都通过docker exec进入容器环境执行，这个习惯建立起来，很多困惑会自然消失。

6.4 容器一直在重启（Restarting）

docker compose ps看到STATUS是Restarting，说明容器启动后立刻崩溃，被重启策略不断拉起。查看日志：

bash复制docker compose logs nginx

常见原因：

nginx: [emerg] bind() to 0.0.0.0:80 failed，端口被宿主机的进程或者其他容器占用。
配置语法错误，nginx -t过不了，主进程退出。这种情况启动前先手动docker compose config检查，能拦下大部分低级错误。
挂载目录不存在。Compose在挂载时会自动创建宿主机目录，但如果某个子目录权限不对，Nginx读取不到配置，也会启动失败。

6.5 端口映射时忘绑定IP

如果ports写成：

yaml复制    ports:
      - "8080:80"

等价于0.0.0.0:8080->80/tcp，意味着所有网卡上的8080端口都能访问到Nginx。生产环境如果想限制只允许内网访问，就需要绑定网卡IP：

yaml复制    ports:
      - "127.0.0.1:8080:80"

这样只有本机能通过8080访问，外网访问不到。如果前面还有一层Caddy、Nginx或者其他网关做统一入口，这种写法很实用，避免服务暴露在不该暴露的地方。

写在最后的经验

我在实际项目里用这套方式部署过很多次Nginx，最深的体会是：Compose本身不难，难的是理解“宿主机与容器的边界”。哪些目录要挂载、哪些命令要在容器里执行、哪些网络是内部可见的，搞懂这几个问题，后面所有配置都是在同一个思路下展开的。

如果你刚开始接触，我建议先不要追求一步到位。先把Nginx容器跑起来，改一个静态页面，再手动写一个反向代理配置，折腾一遍以后，再回头看Compose文档里的各类参数，会发现之前看不懂的内容突然都很顺眼。配置文件写错了不可怕，docker compose down && docker compose up -d也没有负担，真正重要的是一步步搞清楚为什么这样写。

另外，如果你打算把Nginx用于真实业务，慎用latest标签，固定一个具体版本号，比如nginx:1.25-alpine，这样部署到其他环境时镜像版本完全一致，避免因版本差异导致配置不兼容的坑。Compose文件本身建议用Git管理，每一次改动都有记录，回滚也方便。服务器不是一锤子买卖，良好的文件组织习惯是比任何技巧都值钱的东西。