NGINX Docker 镜像使用指南

快速参考

维护者

NGINX Docker 维护团队

帮助资源

如需帮助，可访问：

• Docker 社区 Slack
• Server Fault
• Unix & Linux 论坛
• Stack Overflow

支持的标签及对应 Dockerfile 链接

Mainline 版本（主线版）

基于 Debian 系统：

• 1.29.2, mainline, 1, 1.29, latest 等（含 trixie 系统标签）
  Dockerfile 链接

扩展版本：

• Perl 模块：1.29.2-perl, mainline-perl 等
  Dockerfile 链接
• OpenTelemetry 支持：1.29.2-otel, mainline-otel 等
  Dockerfile 链接

基于 Alpine 系统（轻量版）：

• 1.29.2-alpine, mainline-alpine 等（含 alpine3.22 系统标签）
  Dockerfile 链接
• 扩展版本：alpine-perl, alpine-slim, alpine-otel（对应 Perl 模块、精简版、OpenTelemetry 支持）

Stable 版本（稳定版）

基于 Debian 系统：

• 1.28.0, stable, 1.28 等（含 bookworm 系统标签）
  Dockerfile 链接

扩展版本：stable-perl, stable-otel 等（Perl 模块、OpenTelemetry 支持）

基于 Alpine 系统：

• 1.28.0-alpine, stable-alpine 等（含 alpine3.21 系统标签）
  Dockerfile 链接
• 扩展版本：alpine-perl, alpine-slim, alpine-otel

快速参考（补充）

• 问题反馈地址：NGINX Docker 仓库 Issues
• 支持的架构：amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, mips64le, ppc64le, riscv64, s390x（详见说明）
• 镜像详情：repo-info 仓库的 nginx 目录（含元数据、传输大小等）
• 镜像更新：通过 official-images 仓库的 nginx 标签 或 配置文件 追踪
• 本文档来源：docs 仓库的 nginx 目录

什么是 NGINX？

NGINX（发音 "engine-x"）是一款开源的反向代理服务器，支持 HTTP、HTTPS、SMTP、POP3、IMAP 等协议，同时具备负载均衡、HTTP 缓存和 Web 服务器（源服务器）功能。其设计初衷是高并发、高性能和低内存占用，采用 2 条款 BSD 类许可证授权，可运行于 Linux、BSD 变体、macOS、Solaris、AIX、HP-UX 等类 Unix 系统，也提供 Windows 实验性端口。

更多信息：*** - NGINX

如何使用本镜像

托管静态内容

方法 1：直接挂载本地目录

bash
$ docker run --name some-nginx -v /本地内容目录:/usr/share/nginx/html:ro -d nginx

（ro 表示只读挂载，防止容器修改本地文件）

方法 2：通过 Dockerfile 构建自定义镜像

创建 Dockerfile：

dockerfile
FROM nginx
COPY 本地静态目录 /usr/share/nginx/html

将 Dockerfile 与静态目录放在同一文件夹，执行：

bash
$ docker build -t some-content-nginx .  # 构建镜像
$ docker run --name some-nginx -d some-content-nginx  # 启动容器

暴露外部端口

如需通过宿主机端口访问 NGINX，可映射端口（例如将容器 80 端口映射到宿主机 8080 端口）：

bash
$ docker run --name some-nginx -d -p 8080:80 some-content-nginx

访问 [***] 或 [***] 即可查看内容。

自定义配置

方式 1：挂载配置文件

1. 先从容器中获取默认配置：

   bash
   $ docker run --rm --entrypoint=cat nginx /etc/nginx/nginx.conf > /本地路径/nginx.conf
   

2. 修改本地 nginx.conf 后，挂载启动：

   bash
   $ docker run --name my-custom-nginx -v /本地路径/nginx.conf:/etc/nginx/nginx.conf:ro -d nginx
   

方式 2：构建包含自定义配置的镜像

创建 Dockerfile：

dockerfile
FROM nginx
COPY nginx.conf /etc/nginx/nginx.conf  # 替换默认配置

构建并启动：

bash
$ docker build -t custom-nginx .
$ docker run --name my-custom-nginx -d custom-nginx

使用环境变量动态配置（1.19+ 支持）

NGINX 配置文件默认不支持环境变量，但本镜像提供 envsubst 工具处理模板文件：

1. 创建模板目录 templates，添加配置模板（如 templates/default.conf.template）：

   nginx
   server {
       listen ${NGINX_PORT};  # 引用环境变量
       server_name ${NGINX_HOST};
   }
   

2. 通过 docker-compose.yml 传入环境变量：

   yaml
   web:
     image: nginx
     volumes:
       - ./templates:/etc/nginx/templates  # 挂载模板目录
     ports:
       - "8080:80"
     environment:
       - NGINX_HOST=foobar.com
       - NGINX_PORT=80
   

   启动后，模板会自动渲染为 /etc/nginx/conf.d/default.conf，变量被替换为实际值。

自定义模板路径/后缀：可通过环境变量调整（如 NGINX_ENVSUBST_TEMPLATE_DIR 指定模板目录，NGINX_ENVSUBST_SUFFIX 指定模板后缀）。

其他实用配置

只读模式运行

需挂载可写目录（NGINX 默认需写入 /var/cache/nginx 和 /var/run）：

bash
$ docker run -d -p 80:80 --read-only \
  -v $(pwd)/nginx-cache:/var/cache/nginx \
  -v $(pwd)/nginx-pid:/var/run \
  nginx

调试模式

使用 nginx-debug 二进制输出详细日志：

bash
$ docker run --name my-nginx -v /本地路径/nginx.conf:/etc/nginx/nginx.conf:ro -d \
  nginx nginx-debug -g 'daemon off;'

静默启动日志

设置环境变量 NGINX_ENTRYPOINT_QUIET_LOGS=1 可关闭启动时的详细日志：

bash
$ docker run -d -e NGINX_ENTRYPOINT_QUIET_LOGS=1 nginx

非 root 用户运行

需修改配置文件指定可写路径（如 /tmp），或使用官方 nginx-unprivileged 镜像。

镜像变体说明

nginx:<version>（默认版）

基于 Debian 系统，包含常用依赖，适合大多数场景。标签中含 trixie/bookworm 等为 Debian 发行版代号，建议显式指定以避免基础系统更新导致问题。

nginx:<version>-perl

包含 Perl 模块（默认版已移除），适用于需 Perl 扩展的场景。

nginx:<version>-alpine

基于 Alpine Linux，镜像体积极小（约 5MB 基础镜像），适合对大小敏感的环境。注意：Alpine 使用 musl libc，部分依赖 glibc 的软件可能不兼容。

nginx:<version>-slim

精简版，仅含运行 NGINX 所需的最小依赖，适合资源受限环境（非特殊需求建议优先使用默认版）。

许可证

本镜像包含的 NGINX 软件遵循 NGINX 许可证。
镜像可能包含其他软件（如基础系统工具），其许可证信息可参考 repo-info 仓库的 nginx 目录。
使用前请确保遵守所有包含软件的许可证要求。