ARM64 架构下编译支持 ngx_http_lua_module 的 Nginx —— Dockerfile 实践

🧾 ARM64 架构下编译支持 ngx_http_lua_module 的 Nginx —— Dockerfile 实践

一、📘 背景

ngx_http_lua_module 是 OpenResty 的核心模块之一，使 Nginx 可以直接执行 Lua 脚本，实现灵活的动态逻辑处理，例如：

• 动态负载均衡
• 请求内容过滤
• 动态缓存控制
• 自定义鉴权逻辑

官方的 Nginx 镜像默认 不包含 Lua 支持，因此需要通过编译源码的方式添加。

---

二、🧩 编译所需组件

编译时需要以下依赖：

依赖包	说明
build-essential	基础编译工具（gcc、make 等）
libpcre3 / libpcre3-dev	Nginx 正则匹配模块依赖
zlib1g / zlib1g-dev	Nginx 压缩模块依赖
openssl / libssl-dev	HTTPS 支持
wget / git	下载源码
gettext-base	提供 envsubst 命令用于模板变量替换

额外依赖组件：

组件	说明
LuaJIT	高性能 Lua 虚拟机，Nginx 的 Lua 模块依赖它
lua-nginx-module	Nginx 与 LuaJIT 的集成模块
lua-resty-core / lua-resty-lrucache	OpenResty 常用 Lua 库（必须安装，否则报 “resty.core not found”）

---

三、🛠️ Dockerfile 分为两阶段

第一阶段：编译（builder）
第二阶段：运行时（runtime）

✅ 第一阶段：编译阶段（builder）

目标：在 arm64v8/ubuntu:22.04 上编译 Nginx + Lua 模块。

# =========================
# Builder
# =========================
FROM arm64v8/ubuntu:22.04 AS builderRUN apt-get update && apt-get install -y \build-essential \libpcre3 libpcre3-dev \zlib1g zlib1g-dev \openssl libssl-dev \wget git ca-certificates \&& rm -rf /var/lib/apt/lists/*WORKDIR /optENV NGINX_VERSION=1.24.0
ENV LUAJIT_VERSION=2.1-20230410
ENV LUA_MODULE_VERSION=0.10.29# 下载 Nginx
RUN wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz && \tar -zxvf nginx-${NGINX_VERSION}.tar.gz# 编译 LuaJIT
RUN git clone https://github.com/openresty/luajit2.git -b v${LUAJIT_VERSION} && \cd luajit2 && make && make install# 下载 lua-nginx-module
RUN git clone https://github.com/openresty/lua-nginx-module.git -b v${LUA_MODULE_VERSION}# 下载并安装 lua-resty-core 和 lua-resty-lrucache
RUN git clone https://github.com/openresty/lua-resty-core.git /opt/lua-resty-core && \git clone https://github.com/openresty/lua-resty-lrucache.git /opt/lua-resty-lrucache && \mkdir -p /usr/local/share/lua/5.1/resty && \cp -r /opt/lua-resty-core/lib/resty/* /usr/local/share/lua/5.1/resty/ && \cp -r /opt/lua-resty-lrucache/lib/resty/* /usr/local/share/lua/5.1/resty/# 环境变量
ENV LUAJIT_LIB=/usr/local/lib
ENV LUAJIT_INC=/usr/local/include/luajit-2.1WORKDIR /opt/nginx-${NGINX_VERSION}# 编译 Nginx + Lua 模块，路径改为 /etc/nginx
RUN ./configure \--prefix=/etc/nginx \--sbin-path=/etc/nginx/sbin/nginx \--conf-path=/etc/nginx/nginx.conf \--error-log-path=/etc/nginx/logs/error.log \--http-log-path=/etc/nginx/logs/access.log \--pid-path=/var/run/nginx.pid \--lock-path=/var/run/nginx.lock \--with-cc-opt="-O2 -I${LUAJIT_INC}" \--with-ld-opt="-L${LUAJIT_LIB} -Wl,-rpath,${LUAJIT_LIB}" \--with-http_ssl_module \--with-http_v2_module \--with-http_realip_module \--with-threads \--with-http_stub_status_module \--add-module=/opt/lua-nginx-module \&& make -j$(nproc) \&& make install

---

✅ 第二阶段：运行时阶段（runtime）

目标：生成体积更小、运行时可直接使用的镜像。

# =========================
# Runtime image
# =========================
FROM arm64v8/ubuntu:22.04RUN apt-get update && apt-get install -y \libpcre3 zlib1g openssl gettext-base \&& rm -rf /var/lib/apt/lists/*# 创建 nginx 用户和组
RUN groupadd -r nginx && useradd -r -g nginx nginx \&& mkdir -p /var/log/nginx \&& chown -R nginx:nginx /var/log/nginx# 拷贝 Nginx 安装目录和 Lua 库
COPY --from=builder /etc/nginx /etc/nginx
COPY --from=builder /usr/local/lib/libluajit-5.1.so* /usr/local/lib/
COPY --from=builder /usr/local/share/lua/5.1 /usr/local/share/lua/5.1ENV PATH=/etc/nginx/sbin:$PATH
ENV LD_LIBRARY_PATH=/usr/local/lib# 暴露端口
EXPOSE 80 443# 默认命令
CMD ["nginx", "-g", "daemon off;"]

---

四、📂 目录结构说明

编译完成后 /etc/nginx 目录结构：

/etc/nginx/
├── sbin/nginx                # Nginx 可执行文件
├── conf/nginx.conf           # 主配置文件
├── logs/                     # 日志目录
└── modules/                  # 可选的动态模块目录

Lua 相关模块位置：

/usr/local/share/lua/5.1/resty/├── core/├── lrucache/└── ...

---

五、⚙️ 验证 Lua 模块是否生效

进入容器后执行：

nginx -V 2>&1 | grep lua

输出应包含：

--add-module=/opt/lua-nginx-module

再创建测试配置 /etc/nginx/conf.d/lua_test.conf：

server {listen 80;location /lua {default_type text/plain;content_by_lua_block {ngx.say("Hello from Lua in ARM64 Nginx!")}}
}

启动 nginx 后访问 /lua，应输出：

Hello from Lua in ARM64 Nginx!

---

六、🧰 常见问题与解决方案

错误信息	原因	解决方案
ngx_http_lua_module requires LuaJIT 2.x	LuaJIT 未安装或版本错误	确认 LUAJIT_INC 与 LUAJIT_LIB 环境变量设置正确
resty.core not found	没有安装 lua-resty-core	手动拷贝 core 与 lrucache 到 /usr/local/share/lua/5.1/resty
nginx: [emerg] getpwnam("nginx") failed	配置中使用 user nginx; 但用户不存在	Dockerfile 中添加 useradd -r nginx
could not open error log file	/var/log/nginx 目录不存在或无权限	创建目录并设置权限
/usr/sbin/nginx: not found	PATH 或编译路径不一致	使用 --sbin-path=/etc/nginx/sbin/nginx 并更新 PATH

---

七、🚀 构建与运行

# 构建镜像
docker build -t nginx-lua:arm64 .# 启动容器
docker run -d -p 8080:80 nginx-lua:arm64# 测试访问
curl http://localhost:8080/lua

输出：

Hello from Lua in ARM64 Nginx!

---

八、🌟 进阶优化建议

1. 可选优化：多阶段裁剪镜像

   • 使用 FROM arm64v8/alpine 作为 runtime 基础镜像，体积更小；
   • 但需要手动安装 musl 编译 LuaJIT，过程略复杂。

2. 可选优化：OpenResty 替代方案

   • 如果目标仅是使用 Lua，可以直接用 openresty/openresty:arm64 镜像；
   • 该镜像内置所有 Lua 模块，无需自己编译。

3. 环境变量模板渲染

   • 可使用 envsubst 在容器启动时自动替换 Nginx 配置中的变量。

---

✅ 总结

模块	路径	说明
Nginx 主目录	/etc/nginx	标准安装目录
Nginx 二进制	/etc/nginx/sbin/nginx	执行文件路径
LuaJIT 库	/usr/local/lib/libluajit-5.1.so	动态链接库
Lua 脚本库	/usr/local/share/lua/5.1/resty/	Lua 模块代码
日志路径	/var/log/nginx/	需确保 nginx 用户可写