简介nginx-1.24.0 的 Docker 镜像构建资料包面向需要定制化部署 Nginx 的 Docker 开发者与运维人员解决从源码或镜像模板快速构建、替换默认配置与维护镜像版本的问题。资源共 48 个文件压缩包仅 64KB主要包含 11 个 Dockerfile 模板、23 个 Shell 配置脚本、5 个 template 模板文件及多份 README 说明Dockerfile 覆盖 alpine、debian、alpine-slim 等多种基础镜像entrypoint 相关脚本则实现环境变量渲染、IPv6 监听开关、worker 进程数自动调优等功能。已有 946 人学习下载。借助这些脚本与模板读者既能直接构建稳定可用的 Nginx 镜像也能深入理解官方镜像的目录组织与启动逻辑按需调整基础镜像、模块或监听参数免去从零编写构建配置的重复工作适合希望掌握镜像定制技巧的中高级 Docker 使用者。 今年年初给生产环境升级网关的时候我把 Nginx 镜像固定到了 nginx-1.24.0 这个版本上。折腾完一轮日志、挂载和反代配置之后最大的感受是Docker 固定版本 Nginx 的组合确实比在宿主机上散装维护要省心太多。这篇博文就围绕 nginx-1.24.0 docker 镜像从选型思路、拉取加速、部署配置到常见坑位完整还原我实际落地时的一套流程。无论你是刚接触 Docker 的新手还是已经用 Nginx 跑业务的运维应该都能从中找到直接能抄的配置。1. 项目概述与镜像选型思路1.1 为什么选择 1.24.0 这个版本Nginx 的版本线一直很清晰主线版本Mainline迭代快、新功能先行稳定版本Stable每隔一段时间从主线中切出来重点做修复和稳定性保障。1.24.0 就是 2023 年发布的一个稳定版本归属于 1.24 系列在 1.25 主线出来之后依然持续获得安全修复适合生产环境长期使用。选择 1.24.0 而不是 latest背后是版本可追溯的考虑。Docker 镜像的latest标签是个移动靶今天拉下来是 1.25.x明天可能是 1.27.x一旦行为有变化排查问题的时候连“我对面的 Nginx 到底是哪个版本”都说不清楚。固定到nginx:1.24.0之后镜像的编译参数、模块集合、默认配置结构都是确定的出问题能复现、能回滚这对线上环境是底线要求。还有一点容易被忽略1.24.0 这个版本对 HTTP/3 的实验支持、Stream 模块的增强、以及一些 SSL 相关的改进都趋于成熟。如果业务暂时不需要最新主线特性稳定版是个更安全的选择。社区里很多基础镜像、一键部署脚本到现在也还是基于 1.24 系列做的适配生态兼容性没问题。1.2 官方镜像与自建镜像的取舍Docker Hub 上的nginx官方镜像维护质量很高默认基于 Debian也提供 Alpine 变体。我在实际项目里两种都用过各自有明确的使用场景。镜像基础系统压缩后大小适用场景nginx:1.24.0Debian bookworm/slim约 40MB 左右生产环境、需要兼容更多系统库、团队熟悉 Debian 系nginx:1.24.0-alpineAlpine Linux (musl)约 20MB 左右追求镜像体积、内网部署、依赖简单自构建镜像自定义基础镜像取决于内容需要集成编译模块、企业安全基线、离线交付选择逻辑其实很简单如果只是为了跑静态站点或做反向代理直接拉官方镜像省时省力如果业务需要编译第三方模块比如nginx-rtmp-module、lua-nginx-module那就要走自构建路线在 Dockerfile 里基于官方镜像源码编译或者用nginx:1.24.0-alpine配合apk add安装扩展包。我个人的建议是优先用官方镜像做基础用 Dockerfile 再包一层自己的配置和二进制工具尽量避免完全从零构建。原因有两个。一是官方镜像的编译参数经过大量生产验证隐藏坑少二是自构建镜像的维护成本很高每次 Nginx 发布安全更新你都得重新走一遍编译流程。除非有硬性需求否则不要重复造轮子。2. 镜像拉取与国内加速配置2.1 快速拉取官方镜像拉取镜像本身没什么技术含量但有一个习惯值得养成先明确你要的完整镜像名和标签再执行命令。docker pull nginx:1.24.0拉取完成后可以用docker images确认镜像已经存在并检查镜像大小和创建时间docker images | grep nginx如果只是临时验证可以直接启动一个最简容器映射端口后访问docker run -d --name nginx-quick -p 8080:80 nginx:1.24.0启动后用浏览器访问http://服务器IP:8080能看到 Nginx 默认欢迎页就说明镜像没问题。注意这里的-d是后台运行--name给容器起个名字方便管理-p 8080:80把宿主机 8080 端口映射到容器内 80 端口。2.2 解决 Docker Hub 拉取慢的问题国内拉 Docker Hub 镜像慢是常态尤其是nginx:1.24.0这种多层镜像几十兆的文件经常卡在某个 layer 上。解决思路不是去绕路而是配置 Docker daemon 的镜像加速器registry mirror把拉取请求分发到国内可访问的镜像仓库。修改 Docker 配置文件/etc/docker/daemon.json加入 registry-mirrors 配置{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] }配置好后重启 Docker 服务sudo systemctl daemon-reload sudo systemctl restart docker重启后重新拉取镜像速度通常会有明显改善。需要说明的是镜像加速器属于公开服务可用性会随时间变化如果某个地址失效换成其他可用的即可。另外如果公司内部有 Harbor 或 Nexus 仓库也可以自己搭一个 mirror稳定性更好。2.3 基于官方镜像构建业务镜像拉取官方镜像只是第一步真正落地还需要把业务配置和静态文件打进去。我一般会在项目里维护一个 Dockerfile内容类似下面这样FROM nginx:1.24.0 LABEL maintaineropsexample.com # 拷贝静态站点资源 COPY html/ /usr/share/nginx/html/ # 拷贝 nginx 配置 COPY conf.d/ /etc/nginx/conf.d/ # 构建阶段做配置校验 RUN nginx -t EXPOSE 80 443 CMD [nginx, -g, daemon off;]构建命令docker build -t my-nginx:1.24.0 .这里有几个细节值得展开说。RUN nginx -t放在构建阶段而不是容器启动阶段是为了把配置错误提前暴露在 CI 环节避免镜像启动后才发现配置语法有问题。CMD [nginx, -g, daemon off;]是官方镜像默认的启动方式daemon off让 Nginx 在前台运行否则容器会因为没有前台进程而立即退出。构建镜像和使用-v挂载配置是两种互补的思路。构建镜像适合交付、发布、版本管理挂载卷适合开发调试、快速改配置。生产环境我倾向于两者结合基础镜像固定版本站点配置通过挂载方式管理这样改配置不用重新构建镜像但镜像本身又保持了可回溯性。3. 部署落地与核心配置实操3.1 docker run 快速部署如果只是单机部署一个 Nginx 网关docker run足够。我的常用命令行如下docker run -d \ --name nginx-prod \ -p 80:80 \ -p 443:443 \ -v /data/nginx/html:/usr/share/nginx/html:ro \ -v /data/nginx/conf.d:/etc/nginx/conf.d:ro \ -v /data/nginx/logs:/var/log/nginx \ --restart always \ nginx:1.24.0逐个解释关键参数。-v /data/nginx/html:/usr/share/nginx/html:ro把宿主机静态目录挂载进容器:ro表示只读挂载防止容器内误写。-v /data/nginx/conf.d:/etc/nginx/conf.d:ro挂载配置目录新增站点只需要在宿主机加一个.conf文件然后 reload。-v /data/nginx/logs:/var/log/nginx把日志挂载出来方便日志采集和排查。--restart always让 Docker 在容器异常退出或宿主机重启后自动拉起这是生产环境必不可少的参数。3.2 docker-compose 编排部署当 Nginx 需要和后端多个服务联动时docker run命令会变得冗长难维护此时用 docker-compose 更清晰。下面是一个实际可用的docker-compose.ymlversion: 3.8 services: nginx: image: nginx:1.24.0 container_name: nginx-gateway ports: - 80:80 - 443:443 volumes: - ./html:/usr/share/nginx/html:ro - ./conf.d:/etc/nginx/conf.d:ro - ./logs:/var/log/nginx - ./ssl:/etc/nginx/ssl:ro networks: - app-net restart: always app-server: image: node:18-alpine container_name: app-backend networks: - app-net restart: always networks: app-net: driver: bridge这里的关键点是让 Nginx 和后端服务加入同一个自定义网络app-net。在自定义网络中容器之间可以通过服务名直接通信所以 Nginx 配置里的proxy_pass http://app-server:3000可以直接把请求转发给 app-server 容器不需要关心对方的 IP 地址变化。这一点比纯docker run方式优雅得多也是 docker-compose 最常见的用法。启动命令docker compose up -d查看状态docker compose ps3.3 Nginx 核心配置反代、URL 限制、基础认证与证书Nginx 的配置虽然灵活但核心套路就那么几种。我整理了几个实战中高频用到的配置片段直接放在/etc/nginx/conf.d/下即可生效。第一个是反向代理配置。假设有一个后端服务运行在app-server:3000我们需要把/api/路径的请求转发过去server { listen 80; server_name example.com; location /api/ { proxy_pass http://app-server:3000; 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; } location / { root /usr/share/nginx/html; index index.html; } }有人问“Nginx 限制只转发带参数的 URL”怎么做。这个需求通常出现在接口签名校验、防爬虫或特定的业务逻辑场景。可以用if配合$request_uri判断location /api/ { # 如果请求 URL 中不包含问号参数直接返回 404 if ($request_uri !~ \?) { return 404; } proxy_pass http://app-server:3000; proxy_set_header Host $host; }注意$request_uri是包含完整原始请求 URI 的变量!~ \?表示匹配不到问号。实际使用时建议先确认业务方对 URL 参数格式的具体约定避免误杀合法请求。第二个是配置 index.php 的 401 验证身份。这个场景主要出现在用 Nginx 代理 PHP 服务或者给内部管理页面加访问控制。最简单的方案是 Basic Authserver { listen 80; server_name admin.example.com; location / { auth_basic Restricted Area; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://php-backend:9000; include /etc/nginx/fastcgi_params; } }.htpasswd文件可以用openssl passwd -apr1生成openssl passwd -apr1 your-password把用户名和生成的密文写入/etc/nginx/.htpasswd一行一个用户。这种方式对内部系统够用注意不要在公网明文传输密码那需要配合 HTTPS。第三个是配置 TLS 证书。ssl证书文件挂载到容器内目录后server 块写成server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com.pem; ssl_certificate_key /etc/nginx/ssl/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; location / { proxy_pass http://app-server:3000; proxy_set_header Host $host; } }修改配置后记得先校验再重载# 校验配置语法 docker exec nginx-gateway nginx -t # 平滑重载配置 docker exec nginx-gateway nginx -s reloadreload不会中断现有连接是生产环境最安全的配置生效方式。4. 常见问题与排查技巧实录4.1 容器启动失败端口被占用Nginx 容器启动失败最常见的原因是端口被宿主机上的进程占用。表现是docker run或者docker compose up -d执行后容器状态一直是Exited查看日志能看到类似docker logs nginx-gateway输出nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)这行日志的意思是容器内的 Nginx 试图绑定 80 端口但宿主机 80 端口已经被占用了。排查思路是先看看宿主机上谁占用了端口sudo ss -lntp | grep :80找到对应的 PID 和进程名后要么停掉冲突进程要么修改端口映射。需要注意的是如果宿主机本身已经装了一个 Nginx或者有 Caddy 之类的 Web 服务器在监听 80冲突几乎是必然的。这种情况我一般建议修改容器的宿主机侧端口映射比如-p 8080:80先保证服务能起来。4.2 修改配置没生效挂载路径和 reload 的坑新手最容易踩的坑是改了宿主机上的配置文件但容器里没生效。原因有两层。第一层是挂载路径不对。用-v /data/nginx/conf.d:/etc/nginx/conf.d:ro挂载后宿主机上改的文件必须是在/data/nginx/conf.d/目录下而不是随便找个地方新建文件。确认挂载是否生效可以进容器看一眼docker exec -it nginx-gateway ls -l /etc/nginx/conf.d/第二层是改完没有 reload。Nginx 不会监听配置文件变化并自动重载必须手动执行nginx -s reload或者重启容器。我自己踩过好几次这个坑改完配置直接docker restart nginx-gateway结果因为重启导致连接闪断被同事吐槽。正确的做法是先docker exec nginx-gateway nginx -t校验语法再docker exec nginx-gateway nginx -s reload平滑重载。4.3 Docker Desktop 虚拟化相关报错Windows 上使用 Docker Desktop 时最典型的问题就是启动失败并提示Docker Desktop failed to start because virtualisation support wasnt detected。这个问题本质是 Docker Desktop 依赖 Windows 的虚拟化功能而该功能没有被正确启用。处理步骤通常如下进入 BIOS/UEFI 设置确认 Intel VT-x 或 AMD-V 已开启。在 Windows 功能中启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”然后重启。确认 Hyper-V 没有被其他软件完全禁用部分安全软件会干扰虚拟化服务。如果你用的是 WSL 2 后端还可以在 PowerShell 里执行wsl --status查看 WSL 内核版本必要时执行wsl --update更新。这几步操作大多能解决。4.4 日志增长与资源限制Nginx 容器跑久了日志文件会越来越大尤其是访问日志被挂载到宿主机后没有人管的话轻易能涨到几个 GB。我常用的方案是把日志挂载目录交给 logrotate 或 filebeat 处理同时给容器设置资源上限services: nginx: image: nginx:1.24.0 deploy: resources: limits: cpus: 1.0 memory: 512M注意deploy.resources在 docker-compose 的version: 3.8下会被 Docker 识别但如果你用的是docker run对应的参数是--cpus1.0 --memory512m。限制资源的目的是防止 Nginx 异常情况下吃光宿主机内存导致整机卡死。5. 与常用组件的联动实践5.1 Nginx 反向代理 MySQL/Redis 等管理界面Docker 部署 MySQL 8.0 或 Redis 后很多人直接用宿主机 IP 加端口访问管理面板这样既暴露了端口又不容易做权限控制。我习惯在前面加一层 Nginx用子路径或子域名做反向代理。举个例子本地跑了一个 MySQL 管理工具监听在mysql-admin:8080Nginx 配置server { listen 80; server_name db-admin.example.com; location / { auth_basic DB Admin; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://mysql-admin:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这样一来外部只能看到 Nginx 的 80 端口MySQL 管理界面的真实端口完全隐藏访问时还需要输入用户名密码。安全性比直接暴露端口高一个量级。5.2 配置模板化与动态变量Nginx 官方镜像里自带envsubst可以用来做配置模板化。比如我们需要根据环境变量动态设置server_name可以写一个模板文件default.conf.templateserver { listen 80; server_name ${SERVER_NAME}; root /usr/share/nginx/html; }容器启动时通过环境变量渲染模板docker run -d \ -e SERVER_NAMEexample.com \ -v /data/nginx/templates:/etc/nginx/templates:ro \ -p 80:80 \ nginx:1.24.0官方镜像的 entrypoint 会自动处理/etc/nginx/templates/目录下的.template文件将其渲染为/etc/nginx/conf.d/下的真实配置。这个技巧在测试环境和生产环境共用一套配置时非常有用只需要调整环境变量即可。5.3 固定版本、健康检查和日常维护最后说几个日常维护习惯。镜像 tag 一定要固定到具体版本比如nginx:1.24.0不要用latest。给容器加上健康检查docker-compose 里可以这样写services: nginx: image: nginx:1.24.0 healthcheck: test: [CMD, curl, -f, http://localhost/healthz] interval: 30s timeout: 5s retries: 3注意官方 Debian 镜像默认没有 curl需要先apt-get install curl所以更轻量的做法是直接检查 Nginx master 进程healthcheck: test: [CMD-SHELL, nginx -t pgrep nginx] interval: 30s timeout: 5s retries: 3Nginx 安全更新方面建议定期关注官方安全公告当 1.24 系列发布补丁版本比如 1.24.1时及时更新镜像 tag 并重新构建业务镜像。升级流程很简单拉新镜像、改 docker-compose 里的 tag、docker compose up -d容器重建后检查一遍日志即可。我在几台生产服务器上用nginx:1.24.0镜像稳定跑了半年多期间经历过配置调整、证书替换、后端扩容整个流程比直接在宿主机上装 Nginx 要清爽很多。最值钱的体会是Docker 化之后Nginx 的配置、日志、依赖全部收敛在一个可控范围内不会因为某台服务器被装了一堆乱七八糟的库而影响网关稳定性。如果你正准备把 Nginx 迁移到容器环境完全可以按这篇文章的路径走一遍遇到问题再回来对照第 4 节的排查清单大部分坑都能绕开。本文还有配套的精品资源点击获取