HUB
Sign inSign up

xtulnx/nginx

By xtulnx

•Updated 15 minutes ago

高性能网关,带插件

Image
0

4.0K

xtulnx/nginx repository overview

⁠NGINX 和 Tengine 镜像

提供基于官方 NGINX 的精简版,以及基于 Tengine⁠ 的标准版和完整版。Tengine 变体内置 LuaJIT 和 LuaRocks,支持启动时安装 Lua 依赖。

⁠镜像变体

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

  • xtulnx/nginx:latest、xtulnx/nginx:3.1、xtulnx/nginx:3.1.3 说明:标准版,包含 Tengine + LuaJIT + LuaRocks,支持启动时自动安装 Lua 依赖。
  • xtulnx/nginx:slim、xtulnx/nginx:3.1-slim、xtulnx/nginx:3.1.4-slim 说明:精简版,基于官方 NGINX 1.30.7,内置反向代理、TLS、HTTP/2、Stream、Real IP、auth_request、GeoIP 和图片处理等模块。
  • xtulnx/nginx:full、xtulnx/nginx:3.1-full、xtulnx/nginx:3.1.3-full 说明:完整版,在标准版基础上预装常用 lua-resty 库(jwt, http, redis, mysql, limit-traffic 等)。

各变体提供 linux/amd64 和 linux/arm64 镜像。3.1.4 更新精简版。

⁠默认行为

标准版和完整版的入口规则:

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

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

精简版沿用官方 NGINX 入口,默认前台启动。

⁠自动安装 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 \
  -p 80:80 \
  xtulnx/nginx:latest

支持的依赖文件路径:

  • /etc/nginx/luarocks-deps.txt
  • /app/luarocks-deps.txt
  • /app/rockspecs/*.rockspec(LuaRocks 标准格式)

⁠Tengine 变体内置配置

  • Tengine 3.1.0(兼容 nginx 指令)
  • LuaJIT 2.1(OpenResty fork)
  • LuaRocks 3.13.0(默认镜像源:mirror.luarocks.org,官方静态镜像)
  • 错误日志输出到 stderr;默认关闭访问日志,可在 server/location 中按需开启(适合 Docker 日志收集)
  • 预定义共享内存区域:shared_cache 32m、rate_limit_store 16m、locks 1m

⁠目录约定

以下布局适用于 3.1.4-slim 及之后的精简版,以及从当前源码构建的 Tengine 变体。已发布的 Tengine 3.1.3 系列仍可挂载 /etc/nginx/conf.d/ 和 /etc/nginx/lua/,主配置、日志和静态文件沿用该版本的布局。

  • /etc/nginx — 默认工作目录和配置根目录。主配置为 /etc/nginx/nginx.conf,可按需挂载替换。
  • /etc/nginx/conf.d/ — 站点配置目录,主配置在 http 块中加载 *.conf。
  • /etc/nginx/conf.d/default.conf — 镜像自带的默认站点配置,可通过同路径挂载文件替换;挂载整个 conf.d 目录时不会加载镜像内置配置
  • 相对 include 路径以主配置文件所在目录为基准。例如默认布局下,include conf.d/vhosts/a.conf; 会加载 /etc/nginx/conf.d/vhosts/a.conf。
  • /etc/nginx/lua/ — 标准版和完整版的 Lua 脚本目录,已加入 lua_package_path。
  • /var/log/nginx/ — 日志目录,默认日志文件链接到 stdout 和 stderr,可用 docker logs 查看。
  • /usr/share/nginx/html/ — 默认静态文件目录。
  • /var/cache/nginx/ — 缓存目录

从旧版迁移时,将主配置、公共站点配置和静态文件迁到上述路径,并同步更新配置中的 include、root、alias 和日志路径。切换镜像前用新镜像执行 nginx -t。

精简版的默认主配置会加载 HTTP GeoIP 和图片处理模块。挂载自定义主配置时,如需继续使用这两个模块,请在 http 块之前加载:

load_module /usr/lib/nginx/modules/ngx_http_geoip_module.so;
load_module /usr/lib/nginx/modules/ngx_http_image_filter_module.so;

GeoIP 使用时需自行挂载数据库,并通过 geoip_country、geoip_city 等指令指定路径。

⁠快速开始

最简单的启动方式:

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

仅替换默认站点时,在当前目录创建 default.conf:

server {
    listen 80;

    location / {
        default_type text/plain;
        return 200 "nginx is ready\n";
    }
}

挂载到容器中:

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 ./default.conf:/etc/nginx/conf.d/default.conf:ro \
  xtulnx/nginx:latest \
  nginx -t

⁠Docker Compose 示例

每个示例在独立目录中运行。按各节给出的文件名保存配置,先用 mkdir -p conf.d 创建站点配置目录。

⁠转发到同一 Compose 项目的后端

保存为 compose.yml:

services:
  nginx:
    image: xtulnx/nginx:slim
    depends_on:
      - backend
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro

  backend:
    image: hashicorp/http-echo:1.0.0
    command: ["-text=backend ok"]

保存为 conf.d/default.conf:

server {
    listen 80;

    location / {
        proxy_pass http://backend:5678;
    }
}
docker compose up -d
curl -fsS http://127.0.0.1:8080/
docker compose down
⁠转发到宿主机端口

假设宿主机上的 HTTP 服务监听 8081。在 Linux Docker Engine 上,用 extra_hosts 将容器内的 host.docker.internal 映射到宿主机网关。宿主服务应监听容器可访问的地址,例如 Docker 网桥地址。在 Linux 的桥接网络中,宿主机的 127.0.0.1 无法通过网关访问。Docker Desktop 自带此域名,可删除示例中的 extra_hosts。 Docker Compose 网络⁠ · Docker Desktop 宿主机访问⁠

保存为 compose.yml:

services:
  nginx:
    image: xtulnx/nginx:slim
    ports:
      - "127.0.0.1:8080:80"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro

保存为 conf.d/default.conf:

server {
    listen 80;

    location / {
        proxy_pass http://host.docker.internal:8081;
    }
}

在保存这两个文件的目录启动并验证:

docker compose up -d
curl -fsS http://127.0.0.1:8080/
docker compose down

使用 docker run 时,对应参数是 --add-host=host.docker.internal:host-gateway。

⁠跨 Compose 项目反向代理

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

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

docker network create nginx-proxy

保存为 compose.proxy.yml:

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

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

业务项目保存为 compose.app.yml。Web 服务同时加入项目默认网络和共享网络,Redis 只加入项目默认网络:

services:
  web:
    image: hashicorp/http-echo:1.0.0
    command: ["-listen=:8080", "-text=shared network ok"]
    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。

保存为 conf.d/default.conf。NGINX 使用共享网络别名和容器内部端口访问服务:

server {
    listen 80;

    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;
    }
}

先启动业务项目,再启动 NGINX:

docker compose -p demo-app -f compose.app.yml up -d
docker compose -p demo-proxy -f compose.proxy.yml up -d
curl -fsS http://127.0.0.1:8080/

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

docker compose -p demo-proxy -f compose.proxy.yml exec nginx nginx -t
docker compose -p demo-proxy -f compose.proxy.yml exec nginx nginx -s reload

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

docker network inspect nginx-proxy

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

⁠为自定义域名申请 HTTPS 证书

使用 Certbot 的 Webroot 模式为自己的域名申请 Let's Encrypt 证书。把域名的 A 记录指向部署宿主机,有 AAAA 记录时也要确保对应的 IPv6 地址可达。公网须能访问 TCP 80 端口以完成验证,HTTPS 服务使用 TCP 443。通配符证书需要 DNS-01 验证。 Let's Encrypt 验证方式⁠

在独立目录中执行 mkdir -p conf.d。将以下 NGINX 配置里的 app.example.com 全部替换为实际域名,并准备接收证书通知的邮箱。

保存为 compose.yml:

services:
  nginx:
    image: xtulnx/nginx:slim
    restart: unless-stopped
    depends_on:
      - backend
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - acme-webroot:/var/www/certbot:ro
      - letsencrypt:/etc/letsencrypt:ro

  backend:
    image: hashicorp/http-echo:1.0.0
    command: ["-text=https backend ok"]

  certbot:
    image: certbot/certbot:v5.10.0
    profiles: ["certbot"]
    volumes:
      - acme-webroot:/var/www/certbot
      - letsencrypt:/etc/letsencrypt

volumes:
  acme-webroot:
  letsencrypt:

保存为 conf.d/http.conf。挑战请求由 HTTP 直接响应,其他请求转向 HTTPS:

server {
    listen 80;
    server_name app.example.com;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/certbot;
        default_type text/plain;
        try_files $uri =404;
    }

    location / {
        return 308 https://app.example.com$request_uri;
    }
}

保存为 https.conf.example,先放在 conf.d/ 目录之外,等证书签发后再启用:

server {
    listen 443 ssl;
    server_name app.example.com;

    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://backend:5678;
        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;
    }
}

先启动 NGINX 和示例后端,再申请证书。将下面的域名和邮箱替换为实际值,DOMAIN 应与两个配置文件中的域名一致:

DOMAIN=app.example.com
[email protected]

docker compose up -d nginx
docker compose run --rm -T certbot certonly --webroot -w /var/www/certbot \
  --non-interactive --agree-tos --email "$EMAIL" --cert-name "$DOMAIN" -d "$DOMAIN"

签发成功后启用 HTTPS,检查配置并重载:

cp https.conf.example conf.d/https.conf
docker compose exec -T nginx nginx -t &&
  docker compose exec -T nginx nginx -s reload
curl -fsS "https://$DOMAIN/"

Certbot 和 NGINX 使用同一份挑战文件和证书。保留 letsencrypt 数据卷以复用证书和续期配置。可在宿主机定时任务中进入该 Compose 目录并运行下面的命令:

docker compose run --rm -T certbot renew --quiet &&
  docker compose exec -T nginx nginx -s reload

续期仍通过 HTTP 端口验证,保留挑战路径配置。可先运行 docker compose run --rm -T certbot renew --dry-run 检查续期流程。 Certbot 使用文档⁠

⁠作为基础镜像使用

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

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/ /usr/share/nginx/html/

⁠Lua 网关示例

使用 full 镜像演示限流、JWT 认证、A/B 路由、响应缓存和 JSON 日志。Lua 代码直接写在站点配置中。创建一个独立目录,在其中执行 mkdir -p conf.d。

保存为 compose.yml:

services:
  nginx:
    image: xtulnx/nginx:full
    command: ["nginx", "-g", "env JWT_SECRET; daemon off;"]
    depends_on:
      - backend
      - backend-v2
    environment:
      JWT_SECRET: ${JWT_SECRET:?请先设置 JWT_SECRET}
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro

  backend:
    image: hashicorp/http-echo:1.0.0
    command: ["-text=control backend"]

  backend-v2:
    image: hashicorp/http-echo:1.0.0
    command: ["-text=experiment backend"]

保存为 conf.d/default.conf:

log_format demo_json escape=json '{"uri":"$uri","status":$status,"request_time":$request_time}';

upstream demo_control {
    server backend:5678;
}

upstream demo_experiment {
    server backend-v2:5678;
}

server {
    listen 80;
    access_log /dev/stdout demo_json;

    # 按客户端 IP 限流。共享内存由 full 镜像的主配置定义。
    location /api/ {
        access_by_lua_block {
            local limit_req = require "resty.limit.req"
            local limiter = limit_req.new("rate_limit_store", 10, 5)
            if not limiter then
                return ngx.exit(500)
            end
            local delay, err = limiter:incoming(ngx.var.binary_remote_addr, true)
            if not delay then
                if err == "rejected" then
                    ngx.header["Retry-After"] = "1"
                    return ngx.exit(429)
                end
                return ngx.exit(500)
            end
            if delay > 0 then
                ngx.sleep(delay)
            end
        }
        proxy_pass http://demo_control;
    }

    # 校验 HS256 签名和过期时间后,将 subject 交给后端。
    location /protected/ {
        access_by_lua_block {
            local jwt = require "resty.jwt"
            local token = (ngx.var.http_authorization or ""):match("^Bearer%s+([^%s]+)$")
            local secret = os.getenv("JWT_SECRET")
            if not token or not secret or secret == "" then
                ngx.header["WWW-Authenticate"] = "Bearer"
                return ngx.exit(401)
            end

            local decoded = jwt:load_jwt(token)
            if not decoded.valid or type(decoded.header) ~= "table" or decoded.header.alg ~= "HS256" then
                return ngx.exit(401)
            end

            local result = jwt:verify_jwt_obj(secret, decoded)
            local claims = result.payload
            if not result.verified or type(claims) ~= "table"
               or type(claims.exp) ~= "number" or claims.exp <= ngx.time()
               or type(claims.sub) ~= "string" or not claims.sub:match("^[%w_.@%-]+$") then
                return ngx.exit(401)
            end
            ngx.req.set_header("X-User-Id", claims.sub)
        }
        proxy_pass http://demo_control;
    }

    # 同一个分桶键始终进入同一组,约 10% 的分桶进入实验组。
    location /experiment/ {
        set $demo_group demo_control;
        rewrite_by_lua_block {
            local key = ngx.var.cookie_demo_id or ngx.var.remote_addr
            if ngx.crc32_long(key) % 100 < 10 then
                ngx.var.demo_group = "demo_experiment"
            end
        }
        add_header X-AB-Group $demo_group;
        proxy_pass http://$demo_group;
    }

    # 缓存固定的公开 GET 响应,60 秒后重新访问后端。
    location = /cached/ {
        resolver 127.0.0.11 ipv6=off;
        content_by_lua_block {
            if ngx.req.get_method() ~= "GET" then
                ngx.header["Allow"] = "GET"
                return ngx.exit(405)
            end
            local cache = ngx.shared.shared_cache
            local body = cache:get("demo:public-echo")
            local hit = body ~= nil
            if not hit then
                local http = require "resty.http"
                local client = http.new()
                client:set_timeout(2000)
                local response = client:request_uri("http://backend:5678/")
                if not response or response.status ~= 200 then
                    return ngx.exit(502)
                end
                body = response.body
                cache:set("demo:public-echo", body, 60)
            end
            ngx.header["X-Cache"] = hit and "HIT" or "MISS"
            ngx.header.content_type = "text/plain"
            ngx.print(body)
        }
    }

}

生成示例密钥、启动并检查各路由:

export JWT_SECRET="$(openssl rand -hex 32)"
docker compose up -d
curl -fsS http://127.0.0.1:8080/api/
curl -fsSi http://127.0.0.1:8080/experiment/
curl -fsSi http://127.0.0.1:8080/cached/
curl -fsSi http://127.0.0.1:8080/cached/
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/protected/
docker compose logs nginx

缓存首次请求返回 X-Cache: MISS,随后返回 HIT。未带 token 的认证请求返回 401。如需验证认证成功,可在同一终端使用 Python 3 生成一个 5 分钟有效的测试 token:

TOKEN=$(python3 - <<'EOF'
import base64
import hashlib
import hmac
import json
import os
import time

def encode(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=")

header = encode(b'{"alg":"HS256","typ":"JWT"}')
claims = encode(json.dumps({"sub": "demo-user", "exp": int(time.time()) + 300}).encode())
message = header + b"." + claims
signature = hmac.new(os.environ["JWT_SECRET"].encode(), message, hashlib.sha256).digest()
print((message + b"." + encode(signature)).decode())
EOF
)
curl -fsS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/protected/
docker compose down

⁠full 变体预装库

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

库用途
lua-cjsonJSON 编解码
lua-resty-httpHTTP 客户端
lua-resty-jwtJWT 签发和验证
lua-resty-redisRedis 客户端
lua-resty-mysqlMySQL 客户端
lua-resty-limit-traffic限流(漏桶、令牌桶、计数器)
lua-resty-template模板引擎
lua-resty-string字符串工具(MD5、SHA、AES)
lua-resty-lock分布式锁
lua-resty-upload文件上传处理
lua-resty-websocketWebSocket 支持

⁠端口

  • 80 — HTTP
  • 443 — HTTPS

⁠说明

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

Tag summary

Content type

Image

Digest

sha256:823975baa…

Size

102.7 MB

Last updated

24 days ago

docker pull xtulnx/nginx