提供基于官方 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 会进入 shelldocker run ... luarocks list 会执行 luarocks 命令启动前,entrypoint 会自动扫描依赖文件并安装缺失的 LuaRocks 包(仅标准版和完整版)。
精简版沿用官方 NGINX 入口,默认前台启动。
类似 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 标准格式)mirror.luarocks.org,官方静态镜像)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
每个示例在独立目录中运行。按各节给出的文件名保存配置,先用 mkdir -p conf.d 创建站点配置目录。
保存为 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。
当 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 同时加入这些网络。
使用 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/
使用 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
完整版预装了以下常用库,无需额外安装即可直接使用:
| 库 | 用途 |
|---|---|
| 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 — HTTP443 — HTTPSgcc、make 等编译工具,以支持 LuaRocks 在运行时安装含 C 扩展的包。mirror.luarocks.org(官方静态镜像),比动态的 luarocks.org 稳定,在国内访问也较为顺畅。如需覆盖,启动时传 -e LUAROCKS_SERVER=https://your-mirror/。Content type
Image
Digest
sha256:823975baa…
Size
102.7 MB
Last updated
24 days ago
docker pull xtulnx/nginx