Skip to content

快速参考

  • 由……维护
    NGINX Docker 维护者

  • 何处获取帮助：
    Docker 社区 Slack、服务器故障、Unix & Linux 或 Stack Overflow

支持的标签及相应的 Dockerfile 链接

快速参考（续）

什么是 nginx？

Nginx（发音为“engine-x”）是一个针对 HTTP、HTTPS、SMTP、POP3 和 IMAP 协议的开源反向代理服务器，也是一个负载均衡器、HTTP 缓存和 Web 服务器（源服务器）。nginx 项目一开始就非常注重高并发、高性能和低内存使用。它在类 BSD 的 2 条款许可证下授权，并且可以在 Linux、BSD 变体、Mac OS X、Solaris、AIX、HP-UX 以及其他类 Unix 系统上运行。它也有一个针对 Microsoft Windows 的概念验证端口。

wikipedia.org/wiki/Nginx

logo

如何使用此图像

托管一些简单的静态内容

$ docker run --name some-nginx -v /some/content:/usr/share/nginx/html:ro -d nginx

或者，一个简单的 Dockerfile 可用于生成包含必要内容的新图像（这是比上述绑定挂载更简洁的解决方案）：

FROM nginx
COPY static-html-directory /usr/share/nginx/html

将此文件放置在与你的内容目录（“静态 HTML 目录”）相同的目录中，运行 docker build -t some-content-nginx . ，然后启动你的容器：

$ docker run --name some-nginx -d some-content-nginx

暴露外部端口

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

然后你可以在你的浏览器中点击 http://localhost:8080 或 http://host-ip:8080 。

自定义配置

你可以挂载你的配置文件，或者使用它构建一个新镜像。

如果您希望调整默认配置，可以使用类似以下的方法从正在运行的 nginx 容器中获取它：

$ docker run --rm --entrypoint=cat nginx /etc/nginx/nginx.conf > /host/path/nginx.conf

然后在你的主机文件系统中编辑 /host/path/nginx.conf 。

有关 nginx 配置文件语法的信息，请参阅官方文档（特别是初学者指南）。

挂载你的配置文件

$ docker run --name my-custom-nginx-container -v /host/path/nginx.conf:/etc/nginx/nginx.conf:ro -d nginx

使用您的配置文件构建一个新图像

FROM nginx
COPY nginx.conf /etc/nginx/nginx.conf

如果在 Dockerfile 中添加自定义的 CMD ，请务必在 CMD 中包含 -g daemon off; ，以便 nginx 保持在前台，这样 Docker 才能正确跟踪进程（否则你的容器在启动后会立即停止）！

然后使用 docker build -t custom-nginx . 构建镜像并如下运行它：

$ docker run --name my-custom-nginx-container -d custom-nginx

在 nginx 配置中使用环境变量（1.19 版新增）

默认情况下，nginx 在大多数配置块中不支持环境变量。但此镜像有一个功能，它将在 nginx 启动前提取环境变量。

以下是使用 docker-compose.yml 的一个示例：

web:
  image: nginx
  volumes:
   - ./templates:/etc/nginx/templates
  ports:
   - "8080:80"
  environment:
   - NGINX_HOST=foobar.com
   - NGINX_PORT=80

默认情况下，此函数读取 /etc/nginx/templates/*.template 中的模板文件，并将执行 envsubst 的结果输出到 /etc/nginx/conf.d 。

所以如果你放置 templates/default.conf.template 文件，它包含像这样的变量引用：

listen       ${NGINX_PORT};

输出到 /etc/nginx/conf.d/default.conf 像这样：

listen       80;

此行为可通过以下环境变量进行更改：

  • NGINX_ENVSUBST_TEMPLATE_DIR
    • 一个包含模板文件的目录（默认： /etc/nginx/templates ）
    • 当此目录不存在时，此函数将不会对模板处理做任何事情。
  • NGINX_ENVSUBST_TEMPLATE_SUFFIX
    • 模板文件的后缀（默认： .template ）
    • 此功能仅处理名称以该后缀结尾的文件。
  • NGINX_ENVSUBST_OUTPUT_DIR
    • 执行 envsubst 的结果输出的目录（默认： /etc/nginx/conf.d ）
    • 输出文件名是去除后缀的模板文件名。
      • 例如： /etc/nginx/templates/default.conf.template 将与文件名 /etc/nginx/conf.d/default.conf 一起输出。
    • 此目录必须可由运行容器的用户写入。

以只读模式运行 nginx

要以只读模式运行 nginx，您需要将 Docker 卷挂载到 nginx 写入信息的每个位置。默认的 nginx 配置需要对 /var/cache/nginx 和 /var/run 具有写访问权限。这可以通过如下方式运行 nginx 轻松实现：

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

如果您有更高级的配置，需要 nginx 写入其他位置，只需向这些位置添加更多的卷挂载。

以调试模式运行 nginx

自 1.9.8 版本以来的图像带有 nginx-debug 二进制文件，在使用更高的日志级别时会产生详细输出。它可以通过简单的 CMD 替换来使用：

$ docker run --name my-nginx -v /host/path/nginx.conf:/etc/nginx/nginx.conf:ro -d nginx nginx-debug -g 'daemon off;'

在 docker-compose.yml 中的类似配置可能看起来像这样：

web:
  image: nginx
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro
  command: [nginx-debug, '-g', 'daemon off;']

入口点安静日志

自 1.19.0 版本起，添加了一个详细的入口点。它提供了容器启动期间发生的事情的信息。你可以通过设置环境变量 NGINX_ENTRYPOINT_QUIET_LOGS 来使此输出静音：

$ docker run -d -e NGINX_ENTRYPOINT_QUIET_LOGS=1 nginx

用户和组 ID

自 1.17.0 起，基于 alpine 和 debian 的镜像变体都使用相同的用户和组 ID 来降低工作进程的权限：

$ id
uid=101(nginx) gid=101(nginx) groups=101(nginx)

以非 root 用户运行 nginx

可以以较低权限的任意 UID/GID 运行该镜像。然而，这需要修改 nginx 配置以使用该特定 UID/GID 对可写的目录：

$ docker run -d -v $PWD/nginx.conf:/etc/nginx/nginx.conf nginx

在当前目录中的 nginx.conf 应该重新定义以下指令：

pid        /tmp/nginx.pid;

并且在 http 语境中：

http {
    client_body_temp_path /tmp/client_temp;
    proxy_temp_path       /tmp/proxy_temp_path;
    fastcgi_temp_path     /tmp/fastcgi_temp;
    uwsgi_temp_path       /tmp/uwsgi_temp;
    scgi_temp_path        /tmp/scgi_temp;
...
}

或者，查看官方的 Docker NGINX 非特权镜像。

图像变体

nginx 图像有多种类型，每种都针对特定的用例而设计。

nginx:<version>

这是事实上的镜像。如果你不确定自己的需求是什么，你可能想要使用这个。它被设计既可用作一次性容器（挂载你的源代码并启动容器以启动你的应用程序），也可用作构建其他镜像的基础。

其中一些标签可能包含像“书虫”这样的名称。这些是 Debian 发行版的套件代号，表明该镜像基于哪个发行版。如果你的镜像需要安装除镜像自带之外的任何其他软件包，你可能希望明确指定其中之一，以便在 Debian 有新版本发布时最大程度地减少损坏。

nginx:<version>-perl / nginx:<version>-alpine-perl

从 nginx:1.13.0 / mainline 和 nginx:1.12.0 / stable 开始，perl 模块已从默认镜像中移除。如果你希望使用 perl 模块，有一个单独的 -perl 标签变体可用。

nginx:<version>-alpine

此镜像基于流行的 Alpine Linux 项目，在 alpine 官方镜像中可用。Alpine Linux 比大多数发行版基础镜像小得多（约 5MB），因此通常会生成更精简的镜像。

当尽可能小的最终镜像大小是你主要关心的问题时，这个变体很有用。需要注意的主要警告是，它确实使用 musl libc 而不是 glibc 及其同类，所以软件通常会根据其对 libc 要求/假设的深度而遇到问题。有关可能出现的问题以及使用基于 Alpine 的镜像的一些优缺点比较的更多讨论，请参阅此 Hacker News 评论线程。

为了最小化镜像大小，在基于 Alpine 的镜像中包含额外的相关工具（例如 git 或 bash ）是不常见的。使用此镜像作为基础，在你自己的 Dockerfile 中添加你需要的东西（如果你不熟悉，可查看 alpine 镜像描述以获取如何安装软件包的示例）。

nginx:<version>-slim

此镜像不包含默认标签中包含的常见软件包，仅包含运行 nginx 所需的最小软件包。除非你在仅部署 nginx 镜像且有空间限制的环境中工作，否则我们强烈建议使用此存储库的默认镜像。

许可证

查看此映像中包含的软件的许可证信息。

与所有 Docker 镜像一样，这些镜像可能还包含其他可能受其他许可证约束的软件（例如来自基础发行版的 Bash 等，以及所包含的主要软件的任何直接或间接依赖项）。

一些能够自动检测到的额外许可证信息可能会在 repo-info 存储库的 nginx/ 目录中找到。

对于任何预构建镜像的使用，镜像用户有责任确保对此镜像的任何使用都符合其中包含的所有软件的任何相关许可证。