xtulnx/nginx

By xtulnx

•Updated 18 days ago

高性能网关，带插件

Image

2.6K

Overview Tags

xtulnx/nginx repository overview

⁠Tengine (Nginx)

基于 Tengine⁠（阿里巴巴 nginx 分支）的 Docker 镜像，内置 LuaJIT 和 LuaRocks 支持，容器启动时自动安装 Lua 依赖。

⁠镜像变体

这个仓库发布同一仓库下的多个变体：

xtulnx/nginx:latest、xtulnx/nginx:3.1、xtulnx/nginx:3.1.2 说明：标准版，包含 Tengine + LuaJIT + LuaRocks，支持启动时自动安装 Lua 依赖。
xtulnx/nginx:slim、xtulnx/nginx:3.1-slim、xtulnx/nginx:3.1.2-slim 说明：精简版，纯 Tengine，不含 Lua/LuaJIT/LuaRocks。适合纯反向代理和静态文件服务。
xtulnx/nginx:full、xtulnx/nginx:3.1-full、xtulnx/nginx:3.1.2-full 说明：完整版，在标准版基础上预装常用 lua-resty 库（jwt, http, redis, mysql, limit-traffic 等）。

这些 tag 会一起发布 linux/amd64 和 linux/arm64 多架构镜像。

⁠默认行为

镜像的入口规则：

docker run ...（无参数）会启动 nginx -g "daemon off;"
docker run ... nginx -t 会执行 nginx 配置测试
docker run ... sh 会进入 shell
docker run ... luarocks list 会执行 luarocks 命令

启动前，entrypoint 会自动扫描依赖文件并安装缺失的 LuaRocks 包（仅标准版和完整版）。

⁠自动安装 Lua 依赖

类似 uv 自动安装 Python 依赖，这个镜像在启动时会自动安装 Lua 依赖。

创建 luarocks-deps.txt 文件，每行一个包名：

lua-cjson
lua-resty-http
lua-resty-jwt
# 注释行会被忽略
# lua-resty-redis

挂载到容器中：

docker run --rm -d \
  -v ./luarocks-deps.txt:/etc/nginx/luarocks-deps.txt:ro \
  -v ./conf.d:/etc/nginx/conf.d:ro \
  -p 80:80 \
  xtulnx/nginx:latest

支持的依赖文件路径：

/etc/nginx/luarocks-deps.txt
/app/luarocks-deps.txt
/app/rockspecs/*.rockspec（LuaRocks 标准格式）

⁠内置配置

Tengine 3.1.0（兼容 nginx 指令）
LuaJIT 2.1（OpenResty fork）
LuaRocks 3.11.1（默认镜像源：mirror.luarocks.org，官方静态镜像）
工作目录：/etc/nginx
错误日志输出到 stderr；默认关闭访问日志，可在 server/location 中按需开启（适合 Docker 日志收集）
预定义共享内存区域：shared_cache 32m、rate_limit_store 16m、locks 1m

⁠目录约定

/etc/nginx/conf.d/ — 站点配置目录（*.conf 自动加载）
/etc/nginx/conf.d/default.conf — 镜像自带的默认站点配置，可通过同路径挂载文件替换；挂载整个 conf.d 目录时不会加载镜像内置配置
/opt/tengine/conf/conf.d/ — prefix 下的公共配置目录（*.conf 自动加载，先于 /etc/nginx/conf.d/）
相对 include 路径相对于 /opt/tengine/conf/ 解析，例如 include conf.d/vhosts/a.conf;
/etc/nginx/lua/ — Lua 脚本目录（已加入 lua_package_path）
/opt/tengine/ — Tengine 安装目录
/opt/tengine/conf/nginx.conf — 主配置文件
/opt/tengine/logs/ — 日志目录（已链接到 stdout/stderr）
/opt/tengine/html/ — 默认静态文件目录
/var/cache/nginx/ — 缓存目录

⁠快速开始

最简单的启动方式：

docker run --rm -d -p 80:80 xtulnx/nginx:latest

仅替换默认站点时，default.conf 只需要包含 server 配置块：

docker run --rm -d \
  -p 80:80 \
  -v ./default.conf:/etc/nginx/conf.d/default.conf:ro \
  xtulnx/nginx:latest

挂载自定义配置和 Lua 脚本：

docker run --rm -d \
  -p 80:80 \
  -v ./conf.d:/etc/nginx/conf.d:ro \
  -v ./lua:/etc/nginx/lua:ro \
  -v ./luarocks-deps.txt:/etc/nginx/luarocks-deps.txt:ro \
  xtulnx/nginx:latest

测试配置是否正确：

docker run --rm \
  -v ./conf.d:/etc/nginx/conf.d:ro \
  xtulnx/nginx:latest \
  nginx -t

⁠docker compose 示例

基础反向代理：

services:
  nginx:
    image: xtulnx/nginx:latest
    container_name: tengine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./lua:/etc/nginx/lua:ro
      - ./luarocks-deps.txt:/etc/nginx/luarocks-deps.txt:ro
      - nginx-logs:/opt/tengine/logs

volumes:
  nginx-logs:

带后端服务的完整示例：

services:
  nginx:
    image: xtulnx/nginx:full
    container_name: tengine
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      TZ: Asia/Shanghai
      JWT_SECRET: your-secret-key
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./lua:/etc/nginx/lua:ro

  api:
    image: your-api-image:latest
    expose:
      - "8080"

volumes:
  nginx-logs:

⁠跨 Compose 项目反向代理

当 Nginx 和业务服务由不同的 Compose 项目管理时，推荐创建一个外部共享网络。Nginx 和各项目中需要被代理的 Web 服务加入该网络；Redis、数据库等内部服务仍只加入各自项目的默认网络。Web 服务不发布宿主机端口，外部流量只能通过 Nginx 进入。

共享网络只需在宿主机创建一次：

docker network create nginx-proxy

Nginx 项目的 compose.yml：

services:
  nginx:
    image: xtulnx/nginx:slim
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
    networks:
      - nginx-proxy

networks:
  nginx-proxy:
    external: true
    name: nginx-proxy

业务项目的 compose.yml。只有 Web 服务同时加入项目默认网络和共享网络，Redis 不会进入共享网络：

services:
  web:
    image: your-turl-image:latest
    expose:
      - "8080"
    networks:
      default:
      nginx-proxy:
        aliases:
          - turl-web

  redis:
    image: redis:8-alpine
    networks:
      - default

networks:
  nginx-proxy:
    external: true
    name: nginx-proxy

expose 只用于声明容器端口；真正避免宿主机和公网直接访问的是不配置 ports。不同项目可以各自拥有名为 redis 的服务，因为它们位于不同的默认网络。共享网络上的别名应包含项目名并保持唯一，例如 turl-web、docs-api、admin-web。

Nginx 使用共享网络别名和容器内部端口访问服务：

location / {
    proxy_pass http://turl-web:8080;
    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;
}

业务容器被重新创建后，如果其网络地址发生变化，应 reload Nginx 使上游域名重新解析：

docker compose exec nginx nginx -t
docker compose exec nginx nginx -s reload

可以通过以下命令确认共享网络中只包含 Nginx 和允许被代理的服务：

docker network inspect nginx-proxy

如果还需要阻止不同业务项目的 Web 服务互相访问，可为每个项目创建独立的外部网络，例如 nginx-turl、nginx-docs，并让 Nginx 同时加入这些网络。

⁠作为基础镜像使用

可以基于此镜像构建项目专用镜像：

FROM xtulnx/nginx:latest

# 安装项目需要的 Lua 依赖（构建时安装，启动更快）
RUN luarocks install lua-resty-jwt \
    && luarocks install lua-resty-http

# 复制项目配置和脚本
COPY conf.d/ /etc/nginx/conf.d/
COPY lua/ /etc/nginx/lua/

或者使用精简版作为纯代理：

FROM xtulnx/nginx:slim

COPY conf.d/ /etc/nginx/conf.d/
COPY html/ /opt/tengine/html/

⁠Lua 使用场景示例

镜像的 examples/ 目录包含以下典型场景的完整示例：

⁠限流

基于漏桶算法，使用 lua_shared_dict 实现高性能本地限流：

location /api/ {
    access_by_lua_file /etc/nginx/lua/rate_limit.lua;
    proxy_pass http://backend;
}

⁠JWT 认证

在网关层验证 JWT token，将用户信息注入上游请求头：

location /protected/ {
    access_by_lua_file /etc/nginx/lua/jwt_auth.lua;
    proxy_pass http://backend;
}

⁠A/B 测试路由

按比例将流量分配到不同版本的后端，基于 IP 哈希保持一致性：

location /experiment/ {
    set $upstream "";
    rewrite_by_lua_file /etc/nginx/lua/dynamic_routing.lua;
    proxy_pass $upstream;
}

⁠响应缓存

基于 lua_shared_dict 缓存后端响应，减少上游压力：

location /cached/ {
    content_by_lua_file /etc/nginx/lua/response_cache.lua;
}

⁠结构化日志

输出 JSON 格式的访问日志，方便日志收集和分析：

location / {
    log_by_lua_file /etc/nginx/lua/json_log.lua;
    proxy_pass http://backend;
}

⁠full 变体预装库

完整版预装了以下常用库，无需额外安装即可直接使用：

库	用途
lua-cjson	JSON 编解码
lua-resty-http	HTTP 客户端
lua-resty-jwt	JWT 签发和验证
lua-resty-redis	Redis 客户端
lua-resty-mysql	MySQL 客户端
lua-resty-limit-traffic	限流（漏桶、令牌桶、计数器）
lua-resty-template	模板引擎
lua-resty-string	字符串工具（MD5、SHA、AES）
lua-resty-lock	分布式锁
lua-resty-upload	文件上传处理
lua-resty-websocket	WebSocket 支持

⁠端口

80 — HTTP
443 — HTTPS

⁠说明

镜像默认以 root 身份运行。
标准版和完整版保留了 gcc、make 等编译工具，以支持 LuaRocks 在运行时安装含 C 扩展的包。
精简版不含编译工具，体积更小。
LuaRocks 默认使用 mirror.luarocks.org（官方静态镜像），比动态的 luarocks.org 稳定，在国内访问也较为顺畅。如需覆盖，启动时传 -e LUAROCKS_SERVER=https://your-mirror/。

Tag summary

Recent tags

Content type

Image

Digest

sha256:b6485ba05…

Size

85.8 MB

Last updated

18 days ago

docker pull xtulnx/nginx