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

njs: Динамические модули NGINX njs

Установка на Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-njs, предоставленному репозиторием GetPageSpeed Extras.

  1. Настройте репозиторий APT, как описано в настройке репозитория APT.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-njs
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия             | Компонент   | Архитектуры   |
|-------------|--------------------|-------------|---------------|
| debian      | bookworm           | main        | amd64, arm64  |
| debian      | bookworm-mainline  | main        | amd64, arm64  |
| debian      | trixie             | main        | amd64, arm64  |
| debian      | trixie-mainline    | main        | amd64, arm64  |
| ubuntu      | focal              | main        | amd64, arm64  |
| ubuntu      | focal-mainline     | main        | amd64, arm64  |
| ubuntu      | jammy              | main        | amd64, arm64  |
| ubuntu      | jammy-mainline     | main        | amd64, arm64  |
| ubuntu      | noble              | main        | amd64, arm64  |
| ubuntu      | noble-mainline     | main        | amd64, arm64  |

Статус проекта: Активен – Проект достиг стабильного, используемого состояния и активно разрабатывается. Поддержка сообщества

Баннер NGINX JavaScript

NGINX JavaScript

NGINX JavaScript, также известный как NJS, является динамическим модулем для NGINX, который позволяет расширять встроенный функционал с использованием знакомого синтаксиса JavaScript. Язык NJS является подсетом JavaScript, совместимым с ES5 (ECMAScript 5.1 Строгий вариант) с некоторыми расширениями ES6 (ECMAScript 6) и новее. См. совместимость для получения дополнительных сведений.

Как это работает

NGINX JavaScript предоставляется как два динамических модуля для NGINX (ngx_http_js_module и ngx_stream_js_module) и может быть добавлен в любую поддерживаемую установку NGINX Open Source или NGINX Plus без перекомпиляции.

Модуль NJS позволяет администраторам NGINX: - Добавлять сложные проверки контроля доступа и безопасности перед тем, как запросы достигнут серверов верхнего уровня - Управлять заголовками ответа - Писать гибкие, асинхронные обработчики контента, фильтры и многое другое!

Смотрите примеры и наши различные проекты, разработанные с помощью NJS:

https://github.com/nginxinc/nginx-openid-connect

Расширяет функциональность NGINX Plus для прямого взаимодействия с совместимыми поставщиками идентификации OIDC, осуществляя аутентификацию пользователей и авторизацию контента, предоставляемого NGINX Plus.

https://github.com/nginxinc/nginx-saml

Справочная реализация NGINX Plus как поставщика услуг для SAML аутентификации.

https://github.com/nginxinc/njs-prometheus-module

Экспонирует конечную точку метрик Prometheus непосредственно из NGINX Plus.

[!TIP] NJS также может использоваться с приложенческим сервером NGINX Unit. Узнайте больше о API управления NGINX Unit и о том, как определять вызовы функций с помощью NJS.

Загрузка и установка

Следуйте этим шагам, чтобы загрузить и установить предварительно скомпилированные бинарные файлы NGINX и NGINX JavaScript для Linux. Вы также можете выбрать сборку модуля локально из исходного кода.

Подготовка репозитория пакетов NGINX

Следуйте этому руководству, чтобы добавить официальный репозиторий пакетов NGINX в вашу систему и установить NGINX Open Source. Если у вас уже установлен NGINX Open Source или NGINX Plus, пропустите раздел установки NGINX в последнем шаге.

Начало работы с NGINX JavaScript

Использование NJS включает в себя включение модуля, добавление файлов JavaScript с определенными функциями и вызов экспортированных функций в конфигурационных файлах NGINX.

Проверьте, что NGINX работает

NGINX JavaScript является модулем для NGINX Open Source или NGINX Plus. Если вы еще этого не сделали, выполните следующие шаги, чтобы установить NGINX Open Source или NGINX Plus. После установки убедитесь, что экземпляр NGINX запущен и может отвечать на HTTP-запросы.

Запуск NGINX

Введите следующую команду, чтобы запустить NGINX:

sudo nginx

Проверьте, что NGINX отвечает на HTTP-запросы

curl -I 127.0.0.1

Вы должны увидеть следующий ответ: 

HTTP/1.1 200 OK
Server: nginx/1.25.5

Включение модулей NGINX JavaScript

После установки один (или оба) модуля NJS должны быть включены в конфигурационный файл NGINX. В большинстве систем конфигурационный файл NGINX по умолчанию расположен по адресу /etc/nginx/nginx.conf.

Редактирование конфигурационного файла NGINX

sudo vi /etc/nginx/nginx.conf

Включите динамическую загрузку модулей NJS

Используйте директиву load_module в верхнем уровне (“основном”) контексте, чтобы включить один (или оба) модуля.

load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so;

Основы написания .js скриптов

Файлы сценариев NJS обычно называются с расширением .js и помещаются в директорию /etc/nginx/njs/. Они обычно состоят из функций, которые затем экспортируются, делая их доступными в конфигурационных файлах NGINX.

Справочник по пользовательским объектам, методам и свойствам

NJS предоставляет коллекцию объектов с ассоциированными методами и свойствами, которые не являются частью определений ECMAScript. См. полный справочник для этих объектов и как они могут быть использованы для дальнейшего расширения и настройки NGINX.

Пример: Привет, мир

Вот базовый пример "Привет, мир".

example.js

Функция hello в этом файле возвращает код состояния HTTP 200 OK вместе со строкой "Hello World!", за которой следует перевод строки. Функция затем экспортируется для использования в конфигурационном файле NGINX.

Добавьте этот файл в директорию /etc/nginx/njs:

function hello(r) {
  r.return(200, "Hello world!\n");
}

export default {hello}

nginx.conf

Мы изменяем нашу конфигурацию NGINX (/etc/nginx/nginx.conf), чтобы импортировать файл JavaScript и выполнять функцию при определенных обстоятельствах.

## Загружаем модуль ngx_http_js_module
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Установите путь к нашим JavaScript файлам njs
  js_path "/etc/nginx/njs/";

  # Импортируйте наш JavaScript файл в переменную "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Выполните функцию "hello", определенную в нашем JavaScript файле, для всех HTTP запросов
      # и ответьте содержимым нашей функции.
      js_content main.hello;
    }
  }
}

Для полного списка директив njs смотрите документацию по страницам ngx_http_js_module и ngx_stream_js_module.

[!TIP] Более подробная версия этого и других примеров можно найти в официальном репозитории njs-examples.

Интерфейс командной строки NJS (CLI)

NGINX JavaScript устанавливает утилиту интерфейса командной строки. Интерфейс можно открыть как интерактивную оболочку или использовать для обработки синтаксиса JavaScript из предопределенных файлов или стандартного ввода. Поскольку утилита работает независимо, специфические для NGINX объекты, такие как HTTP и Stream недоступны в ее среде выполнения.

Пример использования интерактивного CLI

$ njs
>> globalThis
global {
  njs: njs {
    version: '0.8.4'
  },
  global: [Circular],
  process: process {
    argv: ['/usr/bin/njs'],
    env: {
      PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
      HOSTNAME: 'f777c149d4f8',
      TERM: 'xterm',
      NGINX_VERSION: '1.25.5',
      NJS_VERSION: '0.8.4',
      PKG_RELEASE: '1~buster',
      HOME: '/root'
    }
  },
  console: {
    log: [Function: native],
    dump: [Function: native],
    time: [Function: native],
    timeEnd: [Function: native]
  },
  print: [Function: native]
}
>>

Пример использования неинтерактивного CLI

$ echo "2**3" | njs -q
8

Клонирование репозитория NGINX JavaScript на GitHub

Используя предпочитаемый вами метод, клонируйте репозиторий NGINX JavaScript в вашу директорию разработки. См. Клонирование репозитория GitHub для дополнительной помощи.

https://github.com/nginx/njs.git

Настроить и собрать

Выполните следующие команды из корневой директории вашего клонированного репозитория:

./configure

Соберите NGINX JavaScript: 

make

Утилита теперь должна быть доступна по адресу <NJS_SRC_ROOT_DIR>/build/njs. См. Интерфейс командной строки NJS (CLI) для получения информации о использовании.

Клонирование репозитория NGINX на GitHub

Клонируйте репозиторий исходного кода NGINX в директорию за пределами ранее клонированного репозитория исходного кода NJS.

https://github.com/nginx/nginx.git

Технические характеристики NGINX JavaScript

Технические характеристики для NJS идентичны таковым у NGINX.

Поддерживаемые дистрибутивы

См. Проверенные операционные системы и платформы для полного списка поддерживаемых дистрибутивов.

Поддерживаемые окружения развертывания

  • Контейнер
  • Облачные сервисы (AWS, Google Cloud Platform, Microsoft Azure)
  • Виртуальная машина

Поддерживаемые версии NGINX

NGINX JavaScript поддерживается всеми версиями NGINX Open Source, начиная с nginx-1.14, и всеми версиями NGINX Plus, начиная с NGINX Plus R15.

Задавать вопросы, сообщать о проблемах и вносить вклад

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

Журнал изменений

Смотрите нашу страницу релизов для отслеживания обновлений.