Docker 部署 Nginx 1.24 实操指南：从镜像选型到生产配置

这问题我太熟了。上周帮一个朋友把跑了三年的老站从裸机 Nginx 迁到容器里他盯着终端问我的第一句话就是docker 部署 nginx 1.24到底稳不稳这个疑问太典型。很多人一听到“容器”就觉得性能要打折、配置要成大麻烦但实际跑下来Nginx 这种为高并发而生的服务放进容器里几乎没有任何额外负担反而让版本切换、多环境复制、回滚都变成一条命令的事。这篇就把我这次迁移的完整过程写出来从版本选型、镜像选择、挂载配置、反向代理、负载均衡到最常见的网络故障排查一次聊透。不管你是第一次接触 Docker还是已经跑过几个容器但从没认真搞过 Nginx这篇文章应该都能用得上。1. 为什么我盯上 Nginx 1.24稳定版本和镜像的选型逻辑1.1 主线版和稳定版生产环境该选谁Nginx 的版本线分 Mainline主线和 Stable稳定两条。主线版功能更新快像 HTTP/3 的 QUIC 支持、新的指令和实验性功能都是先在主线里推稳定版则是从主线的某个时间点切出来做维护的分支只修 bug不再做大的功能变更。1.24 就是这样一个稳定分支大概在 2023 年 4 月发行之后一直以补丁形式维护。对生产环境来说稳定版的价值在于行为可预期。你写下nginx:1.24三年后再看这份配置依然能准确知道它支持哪些指令、TLS 默认行为是什么样的。反过来如果一味追新某天从 1.24 升到 1.27某个默认值一变线上策略可能就要从头调一遍。我一直觉得Nginx 这类基础设施求稳永远是第一原则。1.24 虽然不带主线里的 QUIC 等实验功能但 HTTP/2、SSL、Stream 模块这些主力能力都保留得很完整做反向代理和静态服务器绰绰有余。实用建议新项目直接用当前稳定版1.24 这条线就是很好的选择。已有老配置要迁到容器1.24 对旧配置的兼容性极好基本不用改语法。除非确实需要 HTTP/3否则不要为了一两个新功能牺牲整套生产环境的稳定性。1.2 官方镜像和第三方镜像差别不只在体积Docker Hub 上 nginx 官方镜像的 tag 非常多nginx:1.24、nginx:1.24-alpine、nginx:1.24-perl、nginx:1.24-otel还有各种带后缀的变体。我自己平时只用两个nginx:1.24和nginx:1.24-alpine。前者基于 Debian库最全缺什么工具用 apt 就能装后者基于 Alpine Linux用 apk 管理镜像体积小一大截启动也快适合内存紧张的机器。镜像基础系统压缩后体积约包管理器适用场景nginx:1.24Debian bookworm-slim50MBapt有额外模块或调试工具需求nginx:1.24-alpineAlpine Linux25MBapk追求小体积、常规部署bitnami/nginxDebian100MB以上apt需要非 root 运行、定制镜像复杂场景有人用 distroless有人自己写多阶段构建但对于“docker 部署 nginx 1.24”这个目标官方镜像足够靠谱。还有一个容易被忽略的点官方镜像默认时区是 UTC日志时间和北京时间差 8 小时这个坑我放到第 4 节专门展开。1.3 为什么不建议直接拉 latest这是我写这篇时最想强调的一件事。docker pull nginx拉到的 latest 指向当前主线版本可能是 1.25 甚至更高行为与 1.24 不完全一致。网上很多配置文档是为 1.24 写的如果你跑在 latest 上某些指令可能已经标记为废弃甚至直接不生效。所以写镜像 tag 务必明确到版本nginx:1.24、nginx:1.24.0别偷懒。这也是标题要把版本写死的原因——部署不是“装一个 nginx”而是“装一个我测试过的、行为确定的 nginx”。2. 环境准备这件事占了整个部署过程的一半时间2.1 装 Docker 那点事不同系统差别很大Linux 下我习惯用官方源安装。Ubuntu/Debian 用apt install docker.io虽然快但版本往往偏旧。更稳的做法是安装 docker-ce然后启动服务sudo systemctl enable --now docker sudo systemctl status dockerCentOS 7 用户要特别注意系统自带的 docker 版本很低想跑nginx:1.24这类较新的镜像建议先把 docker 升级到 docker-ce。升级完一定要重启服务否则会出现镜像层兼容、overlay2 驱动不支持等问题。Windows 和 macOS 都是装 Docker Desktop。Windows 这边核心前提是 WSL2 要就绪。大多数人第一次卡住就是 “Docker Desktop failed to start because virtualisation support was disabled”这时候去控制面板开启“虚拟机平台”和“适用于 Linux 的 Windows 子系统”再到 BIOS 里确认 VT-x/AMD-V 是开启的。等 Docker Desktop 的状态恢复正常再打开终端执行docker version看到 client 和 server 都是正常版本才算完成。顺带一提用 Windows Docker Desktop 时终端里报failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen十有八九是 Docker Desktop 没真正启动或者 WSL2 后端没就绪而不是网络问题。2.2 镜像拉取慢配置镜像加速才是正解国内服务器拉 Docker Hub 镜像慢到怀疑人生尤其 nginx 这种几十 MB 的基础镜像断断续续拉几十分钟都正常。解决思路是给 dockerd 配置 registry mirror也就是镜像加速器。修改/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io, https://docker.1panel.live, https://hub.rat.dev ] }改完重启sudo systemctl daemon-reload sudo systemctl restart docker注意这些公共加速地址时效性很强如果某天发现又慢了换一个当前可用的即可。我没有遇到过某个加速源能永久稳定所以“拉不下来”不要硬等及时换源才是正事。2.3 服务起不来先看日志再瞎折腾Docker 服务启动失败最常见的三个原因daemon.json 写坏了、磁盘满了、/var/lib/docker权限或文件系统异常。排查路径固定sudo systemctl status docker sudo journalctl -u docker -n 50journalctl 的输出会直接告诉你错误原因。比如 daemon.json 里多个逗号这种低级语法错误服务就直接拒绝启动磁盘满的时候报错往往和 “no space left on device” 相关。记住一条原则服务起不来先看日志不要反复重启碰运气。3. 第一个容器跑起来从 docker run 到验证一条条拆给你看3.1 最小命令和它的每一步部署 nginx:1.24 最朴素的一条命令长这样docker run -d --name nginx -p 80:80 nginx:1.24逐个参数说-d后台运行终端退出容器也不会停。--name nginx给容器起名后面docker exec、docker logs、docker stop都用这个名字。-p 80:80把宿主机的 80 端口映射到容器里的 80 端口冒号左边是宿主机右边是容器。nginx:1.24指定镜像和 tag。跑完命令后执行docker ps看到 nginx 容器的 STATUS 是 Up基本就成了。再curl http://localhost试试能返回 nginx 欢迎页说明容器里的 nginx 已经正常监听 80 端口。如果你在云服务器上记得安全组也要放行 80 端口不然宿主机通、外网不通。3.2 端口映射背后的小知识为什么外部访问宿主机 80 就能到容器里因为 docker 创建容器时会自动往宿主机 iptables 的 NAT 表里加一条 DNAT 规则把发到宿主机 80 端口的流量转发给容器 IP 的 80 端口。这个机制让多容器部署很方便但也带来一个坑在启用防火墙的环境里docker 自己加的 iptables 规则优先级往往很高你配了防火墙放行规则但端口依然通这时候不要觉得奇怪排查时要知道 docker 的转发是走 NAT 链的。3.3 验证方式不止 curl 一种容器里没有 curl 是常态官方 Debian 版 nginx 镜像默认连 curl 都没有。我有几个固定套路# 宿主上直接测 curl -I http://localhost # 日志看请求 docker logs nginx # 进容器里看版本和配置 docker exec nginx nginx -v docker exec nginx nginx -t # 查看监听端口 docker exec nginx sh -c netstat -tlnp | grep 80Debian 镜像里如果没有 netstat可以用cat /proc/net/tcp不过一般不需要查这么深。记住顺序先看日志再看进程最后测网络。3.4 默认文件布局先摸清楚进入容器后nginx 镜像有几个关键路径必须知道/etc/nginx/nginx.conf主配置文件负责全局设置、加载 conf.d 和 sites-enabled。/etc/nginx/conf.d/default.conf默认站点配置监听 80 端口、指向 html 目录。/usr/share/nginx/html默认静态文件目录欢迎页就在这。/var/log/nginx容器内日志目录docker logs其实是通过引擎把 stdout 接出来的。理解了这几个目录后面做配置挂载就顺了。4. 配置文件挂载的三种坑权限、目录遮蔽与时区4.1 推荐的结构宿主机目录挂载进容器生产部署我不建议进容器改配置而是把配置放在宿主机目录再通过-v挂载进去。我习惯的目录结构/data/nginx/ ├── conf.d/ │ └── site1.conf ├── html/ ├── certs/ └── logs/启动命令带挂载docker run -d --name nginx \ -p 80:80 -p 443:443 \ -v /data/nginx/conf.d:/etc/nginx/conf.d:ro \ -v /data/nginx/html:/usr/share/nginx/html \ -v /data/nginx/logs:/var/log/nginx \ -v /data/nginx/certs:/etc/nginx/certs:ro \ --restartunless-stopped \ nginx:1.24:ro表示只读挂载防止容器内被误改配置。这样做的最大好处是配置在宿主机可以直接用 git 管理要改配置时在宿主机编辑然后执行nginx -s reload全程不进容器。4.2 坑一挂载目录把默认配置遮蔽了这是新手最容易迷糊的地方。假设你执行了上面这条挂载 conf.d 的命令那么容器内原来的/etc/nginx/conf.d/default.conf是看不见的因为宿主机目录把整个 conf.d 目录覆盖了。你的 nginx 启动后如果宿主机 conf.d 里没有任何配置文件访问 80 端口直接 404 或者连接拒绝因为默认站点已经没了。解决方式要么把 default.conf 复制到宿主机 conf.d 再改要么干脆自己写一份 site.conf。千万不要想着“我挂载一个文件进去其他默认配置还在”——bind mount 是按目录整体覆盖不是合并。4.3 坑二日志、缓存目录的权限问题nginx 的 worker 进程在容器内是以 nginx 用户跑的uid 通常是 101。如果你把宿主机某目录挂载成 nginx 需要写入的路径比如/var/log/nginx但宿主机目录属主是 root容器内 nginx 用户写不进去就会出现日志不生成、或者启动时报 permission denied。排查技巧在容器内执行ls -l /var/log/nginx看属主和权限如果不对在宿主机执行chown -R 101:101 /data/nginx/logs。这个问题靠猜不行直接看属主最靠谱。4.4 坑三时区差 8 小时官方镜像默认 UTCnginx access log 里的时间比北京时间少 8 小时。有两个解决思路启动时挂载时区文件-v /etc/timezone:/etc/timezone:ro \ -v /etc/localtime:/etc/localtime:ro在容器内做符号链接但要配合自定义 entrypoint 脚本比较麻烦。我推荐第一种但注意宿主机本身最好不是 UTC 时区否则挂载了也没意义。4.5 改配置后让它生效reload 不是 restartNginx 最大的优点是支持平滑 reload。改了配置文件后先检查语法再 reloaddocker exec nginx nginx -t docker exec nginx nginx -s reloadreload 会启动新的 worker 进程加载新配置再优雅退出旧 worker全程不停服。不要动不动就docker restart nginxrestart 会断开所有活跃连接nginx 的平滑能力就白搭了。5. 静态站、反向代理、负载均衡三份可以抄作业的配置5.1 静态网站挂载目录加基本 server 块一份最简静态站配置/data/nginx/conf.d/static.confserver { listen 80; server_name example.com; root /usr/share/nginx/html/static; index index.html; location / { try_files $uri $uri/ 404; } }宿主机建目录/data/nginx/html/static丢一个 index.html 进去。启动时挂载了 html 目录容器内正好对应/usr/share/nginx/html/static访问 example.com 就能看到静态站。try_files的作用是优先找实际文件找不到再试目录下 index都没有就返回 404这是静态站最常用的安全性写法。5.2 反向代理proxy_pass 是核心把 nginx 当作前置网关转发给后端服务是生产里最普遍的需求。假设后端是一个容器服务名叫 backend监听 8080server { 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; } }这里最关键的是proxy_pass后面的地址。如果填http://backend:8080不带路径nginx 会把原始 URI 原样转发如果写成http://backend:8080/带斜杠会把 location 匹配部分的路径处理掉。这两者混用是配置里出现 404 的经典原因务必做个实验感受一下差异。为了让 nginx 能识别 backend 这个名字后端容器和 nginx 必须在同一个自定义网络里。这个放到下面专门说。5.3 负载均衡upstream 和被动健康检查nginx 开源版的负载均衡配置很简单upstream backend_servers { server backend1:8080 weight2; server backend2:8080 weight1; server backend3:8080 backup; } server { listen 80; location / { proxy_pass http://backend_servers; proxy_next_upstream error timeout http_502; } }weight控制权重backup表示只有前面两个都不可用时才启用。开源版没有主动健康检查只能靠max_fails和fail_timeout做被动检查upstream backend_servers { server backend1:8080 max_fails2 fail_timeout30s; server backend2:8080 max_fails2 fail_timeout30s; }当某个后端连续失败 2 次nginx 会在 30 秒内把它标记为不可用流量只打给其他后端。如果要主动探活就得加第三方模块或者直接用 nginx plus开源版别硬凹。5.4 容器互访自定义网络是标配很多人在两个容器之间通信时还想着用--link或者直接写容器 IP这两个我都不推荐。--link是历史遗留有依赖顺序问题容器 IP 在每次重建后会变化写死在配置里等于埋雷。正确做法是创建自定义 bridge 网络让容器通过服务名互相解析docker network create app-net docker run -d --name backend --network app-net your-backend-image docker run -d --name nginx --network app-net -p 80:80 nginx:1.24在同一网络里nginx 配置里直接写http://backend:8080docker 内嵌 DNS 会自动解析成后端容器的 IP。这就是上面反代配置里 backend 名字能用的前提。6. 网络不通、服务起不来、权限报错常见故障完整排查链路6.1 docker 网络不通三类问题分开查“docker 网络不通”这个说法太宽泛排查第一步是分清到底是哪一种容器访问外网不通先检查宿主机内核转发。sysctl net.ipv4.ip_forward必须是 1然后检查是否配置了防火墙 MASQUERADE 规则。常见场景是用 docker 装了 nginx但容器里 curl 外网一直超时。容器互访不通确认两个容器是否在同一个自定义网络。可以docker inspect nginx --format {{.NetworkSettings.Networks}}查看网络信息。不同网络的容器默认不通想互通必须加入同一网络。外部访问容器不通先确认宿主机端口是否正常监听ss -tlnp | grep 80再检查安全组和防火墙。docker 做了 DNAT防火墙要放行对应端口不是只放行 docker 网段就行。排查顺序我固定为docker ps 看状态 - docker logs 看日志 - 容器内自测 - 宿主机链路 - 防火墙/安全组。每一步都能定位到问题区间。6.2 nginx 容器启动失败或 404启动后docker ps显示容器退出最常见是配置文件语法错误。把配置挂载进去后nginx 启动时会执行nginx -t如果配置写错容器直接起不来。这时docker logs nginx给出的报错信息里会明确指向哪个文件哪一行。如果容器已经挂了用临时容器挂载配置来测试docker run --rm -v /data/nginx/conf.d:/etc/nginx/conf.d:ro nginx:1.24 nginx -t这个方式特别适合“配置要调又怕搞坏现有环境”的时候。如果 404另一个高概率原因是挂载目录遮蔽了默认站点或者 root 写错位置按第 4 节说的排查。6.3 权限报错docker 组和 SELinuxLinux 下最常见的权限报错是Got permission denied while trying to connect to the Docker daemon socket这是因为 docker 默认需要 root 权限而当前用户不在 docker 组。解决办法sudo usermod -aG docker $USER然后重新登录或执行newgrp docker。有一点必须提醒加入 docker 组等于把 root 权限交给该用户因为 docker socket 可以挂载宿主机目录生产环境里要慎重。另外在 RHEL/CentOS/Fedora 系上SELinux 会拦截挂载目录报错可能是 “Permission denied” 或者容器起不来。可以直接对目录打标签chcon -Rt container_file_t /data/nginx或者启动时在挂载参数上加:Z后缀让 docker 自动调整 SELinux 标签。注意 SELinux 不是每个发行版都启用先通过getenforce看看状态再决定。6.4 Windows Docker Desktop 的经典报错最近在 Win11 上被问得最多的是两个。第一个Docker Desktop failed to start because virtualisation support is disabled。在 BIOS 确认开启 VT-x/AMD-V在 Windows 功能里开启“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后在管理员 PowerShell 里执行wsl --update重启电脑。这个报错本质上是 WSL2 没有可用的虚拟化层。第二个failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。先看 Docker Desktop 是否启动看右下角托盘图标是否正常然后在命令行执行docker context list确认当前 context 是 desktop-linux最后如果还不行重启 Docker Desktop 而不是继续敲命令。想验证 Docker 服务是否就绪直接执行docker version看 Server 段有没有信息只看 Client 段容易产生“已经装好”的假象。6.5 日志太大撑爆磁盘Nginx 访问日志默认打到容器 stdoutdocker 引擎把它存在/var/lib/docker/containers/容器ID/下的 json 文件里。时间一长这个文件可以不设上限地长。启动 nginx 时务必加日志上限参数docker run -d --name nginx \ --log-opt max-size10m --log-opt max-file3 \ nginx:1.24这样单个日志文件 10MB最多保留 3 个。如果你已经把日志挂载到宿主机也可以不管 json 文件而是给 nginx 配置access_log /var/log/nginx/access.log再在宿主机上用 logrotate 轮转。二选一别重复计算。我见过一个生产事故就是没设置日志上限容器跑了半年宿主机磁盘被一个 30GB 的 json 日志文件占满Docker 服务完全卡死。7. HTTPS 证书挂载与自动续期以及几个值得加上的运行参数7.1 监听 443 和证书挂载证书文件放在宿主机/data/nginx/certs下启动命令里加了-v /data/nginx/certs:/etc/nginx/certs:ro。配置文件这样写server { listen 443 ssl http2; server_name example.com; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { proxy_pass http://backend:8080; } } server { listen 80; server_name example.com; return 301 https://$host$request_uri; }注意这里 nginx 版本是 1.24listen 443 ssl http2;这种写法是支持的。如果你看到网上教程写http2 on;那是 nginx 1.25.1 之后的新写法在 1.24 里不生效别混用。把 80 端口整段return 301是生产环境里最干净的 HTTP 到 HTTPS 强制跳转方式。证书路径要在容器内可见所以挂载很重要。7.2 用 certbot 容器做自动续期容器里装 certbot 很闹心因为容器一重建证书就没了。推荐的方式是证书放在宿主机用 certbot 容器来完成签发和续期。首次签发假设 webroot 已经把静态文件暴露在/data/nginx/htmldocker run --rm \ -v /data/nginx/html:/var/www/html \ -v /data/nginx/certs:/etc/letsencrypt \ -p 80:80 \ certbot/certbot certonly --webroot \ -w /var/www/html -d example.com \ --email youexample.com --agree-tos --no-eff-email证书会写到/data/nginx/certs/live/example.com/。然后 nginx 配置里把证书路径指向挂载点里的 live 目录比如/etc/nginx/certs/live/example.com/fullchain.pem。续期用宿主 crontab0 3 * * * docker run --rm -v /data/nginx/html:/var/www/html -v /data/nginx/certs:/etc/letsencrypt certbot/certbot renew --webroot -w /var/www/html --quiet docker exec nginx nginx -s reload每天凌晨 3 点尝试续期证书到期前 30 天内才会真正 renewreload 让 nginx 读新证书。这个方案不用在容器里装任何额外工具是目前容器化 nginx 最省心的证书路线。7.3 资源限制和健康检查生产环境加分项给 nginx 容器加上资源上限docker run -d --name nginx \ --restartunless-stopped \ --memory512m --cpus1 \ --log-opt max-size10m --log-opt max-file3 \ -v /data/nginx/conf.d:/etc/nginx/conf.d:ro \ -v /data/nginx/html:/usr/share/nginx/html \ -p 80:80 -p 443:443 \ nginx:1.24--memory512m限制内存--cpus1限制 CPU防止某个异常流量峰值把宿主机拖死。Nginx 本身很省资源512m 对绝大多数场景足够。7.4 docker-compose 收尾整套部署一次成型如果容器数量超过一个建议直接用 docker-compose 管理。下面是这次 nginx 1.24 部署的完整 compose 文件services: nginx: image: nginx:1.24 container_name: nginx restart: unless-stopped ports: - 80:80 - 443:443 volumes: - /data/nginx/conf.d:/etc/nginx/conf.d:ro - /data/nginx/html:/usr/share/nginx/html - /data/nginx/certs:/etc/nginx/certs:ro - /data/nginx/logs:/var/log/nginx networks: - app-net extra_hosts: - host.docker.internal:host-gateway healthcheck: test: [CMD, wget, -q, -O, -, http://localhost/] interval: 10s timeout: 3s retries: 3 networks: app-net: driver: bridge执行docker compose up -d docker compose pshealthcheck 里用的 wget 是 Alpine 镜像自带的如果你用的是 Debian 版 nginx 镜像镜像里没有 wget 也没有 curl健康检查会一直失败。这时要么在镜像里补装 wget要么把 test 改成用 bash 的 /dev/tcp但 Debian 镜像用的是 sh没有内建 /dev/tcp所以最省事的做法还是直接选 alpine 镜像。我自己的习惯是静态资源配置用nginx:1.24-alpine反代场景用nginx:1.24健康检查按镜像实际情况来。最后多提一句我在实际迁移里的体会容器里的 nginx 不要当黑盒用配置文件、日志、证书这三样必须全部放宿主机形成一个“宿主机管文件、容器跑进程”的清晰边界。这样无论容器怎么重建配置和证书都不会丢出了问题也能直接在宿主机上用 vim 查看不用折腾 docker exec。如果你刚上手 docker 部署 nginx 1.24照着第 3 节到第 5 节的顺序先把一个静态站跑通再试着反代一个后端服务最后把 HTTPS 和 compose 加进去。这套路径我验证过很多次坑基本都替你踩完了。等跑顺了你大概率会感叹容器化的 nginx真的比裸机 nginx 好管理太多。