Перейти к содержанию

stream-lua: Поддержка скриптов Lua для потоков NGINX

Установка

Вы можете установить этот модуль в любом дистрибутиве на базе RHEL, включая, но не ограничиваясь:

  • RedHat Enterprise Linux 7, 8, 9 и 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-stream-lua

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-stream-lua

Включите модуль, добавив следующее в верхнюю часть /etc/nginx/nginx.conf:

load_module modules/ngx_stream_lua_module.so;

Этот документ описывает nginx-module-stream-lua v0.0.17.post4, выпущенный 16 декабря 2025 года.

Синопсис

events {
    worker_connections 1024;
}

stream {
    # определите TCP-сервер, слушающий на порту 1234:
    server {
        listen 1234;

        content_by_lua_block {
            ngx.say("Hello, Lua!")
        }
    }
}

Настройка в качестве SSL TCP-сервера:

stream {
    server {
        listen 4343 ssl;

        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /path/to/cert.pem;
        ssl_certificate_key /path/to/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        content_by_lua_block {
            local sock = assert(ngx.req.socket(true))
            local data = sock:receive()  -- прочитать строку из потока
            if data == "thunder!" then
                ngx.say("flash!")  -- вывод данных
            else
                ngx.say("boom!")
            end
            ngx.say("the end...")
        }
    }
}

Поддерживается также прослушивание на UNIX-доменном сокете:

stream {
    server {
        listen unix:/tmp/nginx.sock;

        content_by_lua_block {
            ngx.say("What's up?")
            ngx.flush(true)  -- сбросить любые ожидающие данные и ждать
            ngx.sleep(3)  -- спать 3 секунды
            ngx.say("Bye bye...")
        }
    }
}

Описание

Это порт модуля ngx_http_lua_module в подсистему "stream" Nginx для поддержки общих клиентов потоков/TCP.

Доступные API Lua и директивы Nginx остаются такими же, как и в модуле ngx_http_lua.

Директивы

Следующие директивы были перенесены напрямую из ngx_http_lua. Пожалуйста, проверьте документацию ngx_http_lua для получения более подробной информации об их использовании и поведении.

Директива send_timeout в подсистеме Nginx "http" отсутствует в подсистеме "stream". Таким образом, ngx_stream_lua_module использует директиву lua_socket_send_timeout для этой цели.

Примечание: директива lingering close, которая существовала в более ранних версиях stream_lua_nginx_module, была удалена и теперь может быть смоделирована с помощью новой добавленной API tcpsock:shutdown, если это необходимо.

preread_by_lua_block

синтаксис: preread_by_lua_block { lua-script }

контекст: stream, server

фаза: preread

Действует как обработчик фазы preread и выполняет строку кода Lua, указанную в lua-script, для каждого соединения (или пакета в режиме дейтаграммы). Код Lua может вызывать API вызовы и выполняется как новая запущенная корутина в независимой глобальной среде (т.е. в песочнице).

Возможно получить необработанный сокет запроса, используя ngx.req.socket и получать данные от клиента или отправлять данные клиенту. Однако имейте в виду, что вызов метода receive() сокета запроса будет потреблять данные из буфера, и такие потребленные данные не будут видны обработчикам дальше по цепочке.

Код preread_by_lua_block всегда будет выполняться в конце фазы обработки preread, если preread_by_lua_no_postpone не включен.

Эта директива была впервые введена в релизе v0.0.3.

Назад к оглавлению

preread_by_lua_file

синтаксис: preread_by_lua_file <path-to-lua-script-file>

контекст: stream, server

фаза: preread

Эквивалентно preread_by_lua_block, за исключением того, что файл, указанный в <path-to-lua-script-file>, содержит код Lua или байт-код LuaJIT для выполнения.

Переменные Nginx могут использоваться в строке <path-to-lua-script-file> для обеспечения гибкости. Однако это несет некоторые риски и обычно не рекомендуется.

Когда указано относительное имя файла, например foo/bar.lua, оно будет преобразовано в абсолютный путь относительно server prefix, определенного с помощью параметра командной строки -p PATH, указанного при запуске сервера Nginx.

Когда кэш кода Lua включен (по умолчанию), пользовательский код загружается один раз при первом соединении и кэшируется. Конфигурация Nginx должна быть перезагружена каждый раз, когда исходный файл Lua изменяется. Кэш кода Lua может быть временно отключен во время разработки, переключив lua_code_cache off в nginx.conf, чтобы избежать необходимости перезагрузки Nginx.

Эта директива была впервые введена в релизе v0.0.3.

Назад к оглавлению

log_by_lua_block

синтаксис: log_by_lua_block { lua-script }

контекст: stream, server

фаза: log

Запускает исходный код Lua, указанный как <lua-script>, во время фазы обработки запроса log. Это не заменяет текущие журналы доступа, а выполняется перед ними.

API, которые могут вызывать yield, такие как ngx.req.socket, ngx.socket.*, ngx.sleep или ngx.say, недоступны в этой фазе.

Эта директива была впервые введена в релизе v0.0.3.

Назад к оглавлению

log_by_lua_file

синтаксис: log_by_lua_file <path-to-lua-script-file>

контекст: stream, server

фаза: log

Эквивалентно log_by_lua_block, за исключением того, что файл, указанный в <path-to-lua-script-file>, содержит код Lua или байт-код LuaJIT для выполнения.

Переменные Nginx могут использоваться в строке <path-to-lua-script-file> для обеспечения гибкости. Однако это несет некоторые риски и обычно не рекомендуется.

Когда указано относительное имя файла, например foo/bar.lua, оно будет преобразовано в абсолютный путь относительно server prefix, определенного с помощью параметра командной строки -p PATH, указанного при запуске сервера Nginx.

Когда кэш кода Lua включен (по умолчанию), пользовательский код загружается один раз при первом соединении и кэшируется. Конфигурация Nginx должна быть перезагружена каждый раз, когда исходный файл Lua изменяется. Кэш кода Lua может быть временно отключен во время разработки, переключив lua_code_cache off в nginx.conf, чтобы избежать необходимости перезагрузки Nginx.

Эта директива была впервые введена в релизе v0.0.3.

Назад к оглавлению

lua_add_variable

синтаксис: lua_add_variable $var

контекст: stream

Добавляет переменную $var в подсистему "stream" и делает ее изменяемой. Если $var уже существует, эта директива ничего не сделает.

По умолчанию переменные, добавленные с помощью этой директивы, считаются "не найденными", и чтение их с помощью ngx.var вернет nil. Однако их можно переназначить через API ngx.var.VARIABLE в любое время.

Эта директива была впервые введена в релизе v0.0.4.

Назад к оглавлению

preread_by_lua_no_postpone

синтаксис: preread_by_lua_no_postpone on|off

контекст: stream

Управляет тем, следует ли отключить отложенные preread_by_lua* директивы для выполнения в конце фазы обработки preread. По умолчанию эта директива отключена, и код Lua откладывается до выполнения в конце фазы preread.

Эта директива была впервые введена в релизе v0.0.4.

Назад к оглавлению

Nginx API для Lua

Многие функции API Lua были перенесены из ngx_http_lua. Ознакомьтесь с официальным руководством ngx_http_lua для получения более подробной информации об этих функциях API Lua.

Этот модуль полностью поддерживает новую подсистему переменных внутри ядра потока Nginx. Вы можете получить доступ к любым встроенным переменным, предоставленным ядром потока или другими модулями потока. * Константы ядра

`ngx.OK`, `ngx.ERROR` и т.д.

Поддерживаются только необработанные сокеты запросов, по очевидным причинам. Значение аргумента raw игнорируется, и всегда возвращается необработанный сокет запроса. В отличие от ngx_http_lua, вы все равно можете вызывать функции API вывода, такие как ngx.say, ngx.print и ngx.flush после получения необработанного сокета запроса через эту функцию.

Когда сервер потока находится в режиме UDP, чтение из сокета потока, возвращаемого вызовом ngx.req.socket, будет возвращать только содержимое одного пакета. Поэтому вызов чтения никогда не будет блокироваться и вернет nil, "no more data", когда все данные из дейтаграммы будут потреблены. Однако вы можете отправить несколько UDP пакетов обратно клиенту, используя сокет потока.

Необработанные TCP-сокеты, возвращаемые этим модулем, будут содержать следующий дополнительный метод:

Назад к оглавлению

reqsock:receiveany

синтаксис: data, err = reqsock:receiveany(max)

контекст: content_by_lua*, ngx.timer.*, ssl_certificate_by_lua*

Этот метод аналогичен методу tcpsock:receiveany.

Этот метод был введен в stream-lua-nginx-module начиная с v0.0.8.

Назад к оглавлению

tcpsock:shutdown

синтаксис: ok, err = tcpsock:shutdown("send")

контекст: content_by_lua*

Закрывает часть записи сокета запроса, предотвращает дальнейшую запись клиенту и отправляет TCP FIN, при этом оставляя часть чтения открытой.

В настоящее время поддерживается только направление "send". Использование любых параметров, кроме "send", вернет ошибку.

Если вы вызывали какие-либо функции вывода (например, ngx.say) перед вызовом этого метода, рассмотрите возможность использования ngx.flush(true), чтобы убедиться, что все занятые буферы полностью очищены перед закрытием сокета. Если были обнаружены какие-либо занятые буферы, этот метод вернет nil с сообщением об ошибке "socket busy writing".

Эта функция особенно полезна для протоколов, которые генерируют ответ перед фактическим завершением потребления всех входящих данных. Обычно ядро отправляет RST клиенту, когда tcpsock:close вызывается без очистки принимающего буфера сначала. Вызов этого метода позволит вам продолжать чтение из принимающего буфера и предотвратит отправку RST.

Вы также можете использовать этот метод для моделирования lingering close, аналогично тому, что предоставляется модулем ngx_http_core_module для протоколов, которым необходимо такое поведение. Вот пример:

local LINGERING_TIME = 30 -- 30 секунд
local LINGERING_TIMEOUT = 5000 -- 5 секунд

local ok, err = sock:shutdown("send")
if not ok then
    ngx.log(ngx.ERR, "не удалось закрыть: ", err)
    return
end

local deadline = ngx.time() + LINGERING_TIME

sock:settimeouts(nil, nil, LINGERING_TIMEOUT)

repeat
    local data, _, partial = sock:receive(1024)
until (not data and not partial) or ngx.time() >= deadline

Назад к оглавлению

reqsock:peek

синтаксис: ok, err = reqsock:peek(size)

контекст: preread_by_lua*

Заглядывает в буфер preread, который содержит данные потока, отправленные клиентом, не потребляя их. То есть данные, возвращаемые этим API, все еще будут переданы вверх по потоку на следующих фазах.

Эта функция принимает один обязательный аргумент size, который представляет собой количество байт, которые нужно заглянуть. Повторные вызовы этой функции всегда возвращают данные с начала буфера preread.

Обратите внимание, что фаза preread происходит после TLS-рукопожатия. Если сервер потока был настроен с включенным TLS, возвращаемые данные будут в открытом виде.

Если буфер preread не содержит запрашиваемого количества данных, текущая Lua-нить будет приостановлена до тех пор, пока не появятся новые данные, не будет превышен preread_buffer_size или не истечет preread_timeout. Успешные вызовы всегда возвращают запрашиваемые объемы данных, то есть не будет возвращено частичных данных.

Когда preread_buffer_size будет превышен, текущее сеанс потока будет немедленно завершен с кодом состояния сеанса 400 ядром потока, с сообщением об ошибке "preread buffer full", которое будет выведено в журнал ошибок.

Когда preread_timeout будет превышен, текущий сеанс потока будет немедленно завершен с кодом состояния сеанса 200 ядром потока.

В обоих случаях дальнейшая обработка сеанса невозможна (за исключением log_by_lua*). Соединение будет автоматически закрыто ядром потока.

Обратите внимание, что этот API не может быть использован, если произошло потребление данных клиента. Например, после вызова reqsock:receive. Если такая попытка была сделана, будет выброшена ошибка Lua "attempt to peek on a consumed socket". Потребление данных клиента после вызова этого API разрешено и безопасно.

Вот пример использования этого API:

local sock = assert(ngx.req.socket())

local data = assert(sock:peek(1)) -- заглянуть в первые 1 байт, содержащие длину
data = string.byte(data)

data = assert(sock:peek(data + 1)) -- заглянуть в длину + байт размера

local payload = data:sub(2) -- обрезать байт длины, чтобы получить фактический полезный груз

ngx.log(ngx.INFO, "полезный груз: ", payload)

Этот API был впервые введен в релизе v0.0.6.

Назад к оглавлению

Совместимость с Nginx

Последняя версия этого модуля совместима со следующими версиями Nginx:

  • 1.29.x (последнее тестирование: 1.29.2)
  • 1.27.x (последнее тестирование: 1.27.1)
  • 1.25.x (последнее тестирование: 1.25.1)
  • 1.21.x (последнее тестирование: 1.21.4)
  • 1.19.x (последнее тестирование: 1.19.3)
  • 1.17.x (последнее тестирование: 1.17.8)
  • 1.15.x (последнее тестирование: 1.15.8)
  • 1.13.x (последнее тестирование: 1.13.6)

Ядра Nginx старше 1.13.6 (исключительно) не тестировались и могут работать или не работать. Используйте на свой страх и риск!

Укажите системе сборки nginx, где найти LuaJIT 2.1:

export LUAJIT_LIB=/path/to/luajit/lib export LUAJIT_INC=/path/to/luajit/include/luajit-2.1

Здесь мы предполагаем, что Nginx будет установлен в /opt/nginx/.

./configure --prefix=/opt/nginx \ --with-ld-opt="-Wl,-rpath,/path/to/luajit-or-lua/lib" \ --with-stream \ --with-stream_ssl_module \ --add-module=/path/to/stream-lua-nginx-module

Код репозитория

Код репозитория этого проекта размещен на GitHub по адресу openresty/stream-lua-nginx-module.

См. также

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-stream-lua.