oorabona/openresty

OpenResty

结合Nginx与LuaJIT的高性能Web平台，用于动态、可编程的请求处理。


快速开始

bash
# 从GitHub Container Registry拉取
docker pull ghcr.io/oorabona/openresty:latest

# 从Docker Hub拉取
docker pull oorabona/openresty:latest

# 使用自定义配置运行
docker run -d \
  --name openresty \
  -p 80:80 \
  -p 443:443 \
  -v ./conf.d:/usr/local/openresty/nginx/conf/conf.d:ro \
  -v ./lua:/usr/local/openresty/lualib/app:ro \
  ghcr.io/oorabona/openresty:latest

核心功能

• Nginx + LuaJIT：完整的Nginx功能，嵌入LuaJIT实现动态脚本编程
• 源码构建：通过优化配置编译构建，非基于官方镜像
• 可选代理连接：包含ngx_http_proxy_connect_module以支持正向代理
• LuaRocks：内置Lua包管理器，便于模块安装
• 丰富模块：预编译支持HTTP/2、SSL、流媒体及动态模块
• 生产就绪：包含健康检查、非root工作进程及安全强化

使用方法

Docker Compose配置

yaml
services:
  openresty:
    image: ghcr.io/oorabona/openresty:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf.d:/usr/local/openresty/nginx/conf/conf.d:ro
      - ./lua:/usr/local/openresty/lualib/app:ro
    read_only: true
    tmpfs:
      - /var/run/openresty
      - /var/cache/nginx
      - /tmp
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    security_opt:
      - no-new-privileges:true

基础Lua示例

在conf.d/目录中放置Nginx配置：

nginx
# conf.d/default.conf
server {
    listen 80;
    server_name localhost;

    location / {
        content_by_lua_block {
            ngx.say("Hello from OpenResty + Lua!")
        }
    }

    location /api {
        access_by_lua_file /usr/local/openresty/lualib/app/auth.lua;
        proxy_pass http://backend;
    }
}

自定义Lua模块

在lua/目录中创建Lua模块：

lua
-- lua/auth.lua
local jwt = require "resty.jwt"

local token = ngx.var.http_authorization
if not token then
    ngx.status = 401
    ngx.say("缺少Authorization头")
    return ngx.exit(401)
end

-- 验证JWT令牌
local jwt_obj = jwt:verify("secret-key", token)
if not jwt_obj.verified then
    ngx.status = 403
    ngx.say("无效的令牌")
    return ngx.exit(403)
end

安装Lua包

bash
# 使用LuaRocks安装包
docker exec openresty luarocks install lua-resty-jwt

# 列出已安装包
docker exec openresty luarocks list

构建参数

环境变量

OpenResty使用标准Nginx环境变量：

• 通过nginx.conf或环境特定配置文件进行配置
• 在配置文件中使用envsubst处理动态变量
• 配置选项详见Nginx文档

卷挂载

端口

可在Nginx配置中自定义端口。如需非特权运行，使用>1024的端口。

安全配置

进程安全

• 主进程：以root身份运行（需绑定80/443端口）
• 工作进程：以非root用户nginx运行（uid 101，gid 101）
• 无shell访问：nginx用户使用/sbin/nologin shell
• 信号处理：使用SIGQUIT进行优雅关闭

运行时强化

以下docker-compose.yml示例展示安全最佳实践：

yaml
services:
  openresty:
    image: ghcr.io/oorabona/openresty:latest
    read_only: true              # 只读文件系统
    tmpfs:
      - /var/run/openresty       # 可写运行时目录
      - /var/cache/nginx         # 可写缓存目录
      - /tmp                     # 可写临时目录
    cap_drop:
      - ALL                      # 移除所有能力
    cap_add:
      - NET_BIND_SERVICE         # 仅允许绑定特权端口
    security_opt:
      - no-new-privileges:true   # 防止权限提升

非特权端口方案

如需完全无root运行：

yaml
services:
  openresty:
    image: ghcr.io/oorabona/openresty:latest
    user: "101:101"              # 以nginx:nginx用户运行
    read_only: true
    tmpfs:
      - /var/run/openresty
      - /var/cache/nginx
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    ports:
      - "8080:8080"
      - "8443:8443"

注意：需将Nginx配置修改为监听8080/8443而非80/443。

健康检查

内置健康检查验证OpenResty响应状态：

dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD curl -f http://localhost/nginx_status || exit 1

确保Nginx配置包含状态端点：

nginx
location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

依赖项

容器包含以下固定依赖：

关于冻结依赖的说明：

• OpenSSL 1.1.1w：有意冻结在1.1.1系列最终版本。OpenResty需要此版本的特定补丁。迁移至OpenSSL 3.x需上游OpenResty支持。
• PCRE 8.45：传统PCRE库（非PCRE2）。OpenResty为兼容性构建于PCRE 8.x。

这些冻结版本通过OpenResty的补丁机制接收安全更新。

架构

构建流程

1. 引导：下载并编译带OpenResty补丁的OpenSSL 1.1.1
2. PCRE编译：构建带JIT支持的PCRE
3. 可选模块：如启用则下载ngx_http_proxy_connect_module
4. OpenResty构建：配置并编译带所有模块的OpenResty
5. LuaRocks安装：安装Lua包管理器
6. 清理：移除构建依赖以减小镜像体积

包含的Nginx模块

核心HTTP模块：

• http_ssl_module - HTTPS支持
• http_v2_module - HTTP/2协议
• http_realip_module - 从代理头获取客户端IP
• http_addition_module - 在响应前后添加文本
• http_sub_module - 响应内容替换
• http_dav_module - WebDAV方法支持
• http_flv_module - FLV流媒体
• http_mp4_module - MP4流媒体
• http_gunzip_module - 响应解压缩
• http_gzip_static_module - 提供预压缩文件
• http_auth_request_module - 外部认证
• http_random_index_module - 随机目录索引
• http_secure_link_module - 签名URL验证
• http_slice_module - 范围请求分片
• http_stub_status_module - 基础状态页

动态模块：

• http_geoip_module - 基于IP的地理位置
• http_image_filter_module - 图像转换
• http_xslt_module - XSLT转换

流模块：

• stream_core_module - TCP/UDP负载均衡
• stream_ssl_module - 流的TLS支持

邮件模块：

• mail_core_module - 邮件代理
• mail_ssl_module - SMTP/IMAP/POP3 SSL

目录结构

/usr/local/openresty/
├── bin/
│   ├── openresty           # OpenResty二进制文件
│   ├── resty               # Resty命令行工具
│   └── restydoc            # 文档查看器
├── luajit/
│   └── bin/
│       ├── luajit          # LuaJIT解释器
│       └── luarocks        # Lua包管理器
├── lualib/                 # Lua库
│   ├── resty/              # OpenResty Lua模块
│   └── app/                # 自定义模块（挂载点）
├── nginx/
│   ├── conf/
│   │   ├── nginx.conf      # 主配置文件
│   │   └── conf.d/         # 额外配置（挂载点）
│   ├── html/               # 默认网站根目录
│   └── logs/               # 日志（符号链接到stdout/stderr）
├── openssl/                # OpenSSL库
└── pcre/                   # PCRE库

常见使用场景

API网关

nginx
upstream backend {
    server api1:3000;
    server api2:3000;
    keepalive 32;
}

server {
    listen 80;

    location /api/v1 {
        access_by_lua_block {
            -- 限流
            local limit = require "resty.limit.req"
            local lim = limit.new("limit_store", 100, 50)
            local key = ngx.var.remote_addr
            local delay, err = lim:incoming(key, true)
            if not delay then
                if err == "rejected" then
                    return ngx.exit(429)
                end
            end
        }

        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Web应用防火墙

lua
-- lua/waf.lua
local rules = {
    sql_injection = [[(\%27)|(\')|(\-\-)|(\%23)|(#)]],
    xss = [[(\%3C)|(<)|(\%3E)|(>)|(\%3c)|(\%3e)]],
}

local uri = ngx.var.uri
local args = ngx.var.args or ""

for rule_name, pattern in pairs(rules) do
    if string.match(uri, pattern) or string.match(args, pattern) then
        ngx.log(ngx.ERR, "WAF: 阻止", rule_name, "攻击尝试")
        return ngx.exit(403)
    end
end

缓存代理

nginx
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=cache:10m max_size=1g inactive=60m;

server {
    listen 80;

    location / {
        proxy_cache cache;
        proxy_cache_valid 200 60m;
        proxy_cache_valid 404 1m;
        proxy_cache_key "$scheme$request_method$host$request_uri";
        proxy_cache_bypass $http_cache_control;
        add_header X-Cache-Status $upstream_cache_status;

        proxy_pass http://origin;
    }
}

动态负载均衡

lua
-- lua/balancer.lua
local balancer = require "ngx.balancer"
local redis = require "resty.redis"

-- 从Redis获取健康后端
local red = redis:new()
red:connect("redis", 6379)
local backends = red:smembers("healthy_backends")

-- 轮询选择
local current = ngx.shared.balance:incr("counter", 1, 0)
local index = (current % #backends) + 1
local backend = backends[index]

-- 设置上游服务器
local ok, err = balancer.set_current_peer(backend)
if not ok then
    ngx.log(ngx.ERR, "设置后端失败: ", err)
    return ngx.exit(500)
end

性能优化建议

• 连接池：使用上游连接的keepalive
• Lua共享字典：通过lua_shared_dict在工作进程间缓存数据
• LuaJIT优化：使用-jdump分析热点代码
• 工作进程数：设置为CPU核心数
• Sendfile：启用静态文件发送
• TCP Nopush：减少网络开销
• Gzip：压缩响应（或使用gzip_static）

版本管理

bash
# 检查当前版本
./version.sh

#