garfieldwtf/openresty

OpenResty Docker镜像文档

镜像概述和主要用途

docker-openresty是OpenResty的Docker工具集。Docker是容器管理平台，而OpenResty是一个全功能Web应用服务器，它捆绑了标准NGINX核心、众多第三方NGINX模块及其外部依赖。本镜像提供了多架构支持（amd64、aarch64、s390x）和多种操作系统版本，适用于快速部署基于NGINX和LuaJIT的高性能Web应用。

OpenResty镜像标签

建议将镜像固定到明确的标签。以下是常见标签示例及说明：

以下是未指定版本的标签示例（仅作参考）：

支持的标签及对应Dockerfile链接

基于上游OpenResty包构建的"flavors"：

• alpine-apk, (alpine-apk/Dockerfile)
• amzn2, (centos/Dockerfile with amzn2)
• bullseye-fat, (bullseye/Dockerfile.fat)
• bullseye, (bullseye/Dockerfile)
• buster-fat, (buster/Dockerfile.fat)
• buster, (buster/Dockerfile)
• centos, centos-rpm, (centos/Dockerfile with el8)
• centos7, (centos7/Dockerfile with el7)
• fedora, fedora-rpm, (fedora/Dockerfile with fc35)
• rocky, (fedora/Dockerfile with rockylinux)
• windows, (windows/Dockerfile)

基于源码构建的"flavors"（适用于高级自定义场景）：

• alpine-fat, (alpine/Dockerfile.fat)
• alpine, (alpine/Dockerfile)
• bionic, (bionic/Dockerfile)
• focal, (focal/Dockerfile)
• jammy, (jammy/Dockerfile)

openresty/openresty:latest标签指向最新的bullseye镜像。自1.19.3.2-1版本起，所有flavors支持amd64和aarch64多架构构建；自1.21.4.1-1版本起，基于源码构建的Ubuntu flavors（如jammy）支持s390x架构（禁用PCRE JIT）。

使用方法

若接受构建默认值，可直接使用Docker Hub上的openresty镜像：

bash
docker run [options] openresty/openresty:bullseye-fat

[options]包括端口映射（-p）、卷挂载（-v）、后台运行（-d）等参数。

docker-openresty会将/usr/local/openresty/nginx/logs/access.log和error.log符号链接到/dev/stdout和/dev/stderr，以确保Docker日志正常工作。若修改nginx.conf中的日志路径，需对新路径创建符号链接（Windows镜像不支持此功能）。

临时目录（如client_body_temp_path）存储在/var/run/openresty/，建议挂载此目录而非使用容器本地目录（Windows镜像不支持）。

Nginx配置文件

Docker工具会安装默认的nginx.conf。可通过自定义Dockerfile或卷挂载覆盖该文件。

Linux镜像的nginx.conf包含指令include /etc/nginx/conf.d/*.conf;，因此该目录下的所有配置都会被包含。默认虚拟主机配置位于/etc/nginx/conf.d/default.conf。

可直接覆盖default.conf或挂载整个conf.d目录：

bash
docker run -v /my/custom/conf.d:/etc/nginx/conf.d openresty/openresty:alpine

在selinux主机（如CentOS）上，需添加:Z到卷挂载参数：

bash
docker run -v /my/custom/conf.d:/etc/nginx/conf.d:Z openresty/openresty:alpine

Windows镜像需直接修改主配置文件：

bash
docker run -v C:/my/custom/nginx.conf:C:/openresty/conf/nginx.conf openresty/openresty:windows

OPM

从1.11.2.2版本开始，Linux版OpenResty包含包管理器opm，位于/usr/local/openresty/bin/opm。除alpine、buster和bullseye外，所有镜像均内置opm。

在alpine镜像中使用opm需安装curl和perl：

bash
apk add --no-cache curl perl

在bullseye镜像中使用opm，可选择bullseye-fat镜像或在自定义构建中安装openresty-opm包。

LuaRocks

alpine-fat、centos和bionic变体包含LuaRocks，位于/usr/local/openresty/luajit/bin/luarocks。alpine变体因追求精简未包含（需构建系统支持）。

在Dockerfile中安装LuaRocks包：

dockerfile
RUN /usr/local/openresty/luajit/bin/luarocks install <rock>

注意事项

• envsubst工具在除alpine和windows外的所有镜像中可用，用于将环境变量模板化到配置文件。
• 默认情况下，OpenResty会启用SSE4.2优化（若构建机器支持）。在不支持SSE4.2的机器上运行会导致无效操作码问题。可通过以下命令构建禁用SSE4.2的自定义镜像：

  bash
  docker build -f bionic/Dockerfile --build-arg "RESTY_LUAJIT_OPTIONS=--with-luajit-xcflags='-DLUAJIT_NUMMODE=2 -DLUAJIT_ENABLE_LUA52COMPAT -mno-sse4.2'" .
  

• OpenResty的OpenSSL版本需与opm和LuaRocks包版本兼容，至少主版本需一致（如1.1.1）。镜像标签resty_openssl_version指示此值。
• 1.13.6.2-alpine基于OpenSSL 1.0.2r构建，1.15.8.1-alpine及更高版本基于OpenSSL 1.1.1构建。
• Windows镜像需与主机系统版本兼容，当前基于"Windows Server 2016"系列构建。
• 容器停止时会向nginx发送SIGQUIT信号以优雅关闭（完成活跃连接），Docker默认使用SIGTERM会立即终止连接。若配置监听UNIX域套接字，需手动删除套接字文件（因nginx bug #753）。
• Alpine 3.9及以上使用OpenSSL 1.1.1，默认启用TLS 1.3，可能影响ssl_session_(store|fetch)_by_lua*，OpenResty 1.17.x.1及以上已修复此问题。

镜像标签

镜像构建包含多种信息标签，可通过jq查看：

bash
docker inspect openresty/openresty:1.17.8.1-0-bionic | jq '.[].Config.Labels'

主要标签说明：

Docker CMD

Dockerfile的CMD使用-g "daemon off;"指令保持Nginx后台运行。若nginx.conf中已包含此指令，需显式调用openresty（Windows镜像调用nginx）：

bash
docker run [options] openresty/openresty:bionic openresty

调用其他命令（如resty工具）：

bash
docker run [options] openresty/openresty:bionic resty [script.lua]

注意：alpine镜像不包含resty工具所需的perl和ncurses包。

构建（从源码）

克隆仓库并使用指定Dockerfile构建自定义镜像：

bash
git clone https://github.com/openresty/docker-openresty.git
cd docker-openresty
docker build -t myopenresty -f bionic/Dockerfile .
docker run myopenresty

支持的基础系统Dockerfile路径：

• Alpine: alpine/Dockerfile
• Alpine Fat: alpine/Dockerfile.fat
• Ubuntu Bionic: bionic/Dockerfile
• Ubuntu Focal: focal/Dockerfile
• Ubuntu Jammy: jammy/Dockerfile

构建参数

使用--build-arg设置构建参数：

bash
docker build --build-arg RESTY_J=4 -f jammy/Dockerfile .

主要构建参数及默认值：