NGINX JavaScript, também conhecido como NJS, é um módulo dinâmico para NGINX que permite a extensão da funcionalidade integrada usando a sintaxe JavaScript familiar. A linguagem NJS é um subconjunto de JavaScript, compatível com ES5 (ECMAScript 5.1 Strict Variant) com algumas extensões ES6 (ECMAScript 6) e mais recentes. Consulte compatibilidade para obter mais detalhes.
Como funciona
Baixando e instalando
Provisionando o repositório de pacotes NGINX
Instalando os módulos JavaScript NGINX
Arquivos e locais instalados
Introdução ao NGINX JavaScript
Verifique se o NGINX está em execução
Habilitando os módulos JavaScript do NGINX
Noções básicas de gravação de arquivos de script .js
Referência de objetos, métodos e propriedades personalizados
Exemplo: Olá mundo
A interface de linha de comando (CLI) NJS
Construindo a partir da fonte
Instalando dependências
Clonando o repositório NGINX JavaScript GitHub
Construindo utilitário de interface de linha de comando independente (opcional)
Clonando o repositório NGINX GitHub
Construindo NGINX JavaScript como um módulo do NGINX
Especificações técnicas do JavaScript NGINX
Distribuições suportadas
Ambientes de implantação suportados
Versões NGINX suportadas
Recomendações de dimensionamento
Fazendo perguntas, relatando problemas e contribuindo
Registro de alterações
Licença
NGINX JavaScript é fornecido como dois módulos dinâmicos para NGINX (ngx_http_js_module e ngx_stream_js_module) e pode ser adicionado a qualquer instalação NGINX Open Source ou NGINX Plus compatível sem recompilação.
O módulo NJS permite que os administradores NGINX:
Adicione controles de acesso complexos e verificações de segurança antes que as solicitações cheguem aos servidores upstream
Manipular cabeçalhos de resposta
Escreva manipuladores de conteúdo, filtros e muito mais flexíveis e assíncronos!
Veja exemplos e nossos diversos projetos desenvolvidos com a NJS:
Estende a funcionalidade do NGINX Plus para se comunicar diretamente com provedores de identidade compatíveis com OIDC, autenticando usuários e autorizando conteúdo entregue pelo NGINX Plus.
Implementação de referência do NGINX Plus como provedor de serviços para autenticação SAML.
Expõe o endpoint de métricas do Prometheus diretamente do NGINX Plus.
Dica
O NJS também pode ser usado com o servidor de aplicativos NGINX Unit. Saiba mais sobre a API de controle da unidade NGINX e como definir chamadas de função com NJS.
Siga estas etapas para baixar e instalar binários NGINX e NGINX JavaScript Linux pré-compilados. Você também pode optar por construir o módulo localmente a partir do código-fonte.
Siga este guia para adicionar o repositório oficial do pacote NGINX ao seu sistema e instalar o NGINX Open Source. Se você já possui o NGINX Open Source ou o NGINX Plus instalado, pule a parte de instalação do NGINX na última etapa.
Depois que o repositório for provisionado, você poderá instalar o NJS emitindo o seguinte comando:
sudo apt instalar nginx-module-njs
sudo yum instalar nginx-module-njs
sudo apk adicionar nginx-module-njs@nginx
sudo zypper instalar nginx-module-njs
Dica
O repositório de pacotes inclui um módulo alternativo que permite símbolos de depuração. Embora não seja recomendado para ambientes de produção, este módulo pode ser útil no desenvolvimento de configurações baseadas em NJS. Para baixar e instalar a versão de depuração do módulo, substitua o nome do módulo no comando anterior por nginx-module-njs-dbg .
Os scripts de instalação do pacote instalam dois módulos, suportando contextos NGINX http e stream .
ngx_http_js_module
Este módulo NJS permite a manipulação de dados transmitidos por HTTP.
ngx_stream_js_module
Este módulo NJS permite a manipulação de dados transmitidos através de protocolos de fluxo como TCP e UDP.
Por padrão, ambos os módulos são instalados no diretório /etc/nginx/modules .
O uso de NJS envolve habilitar o módulo, adicionar arquivos JavaScript com funções definidas e invocar funções exportadas em arquivos de configuração NGINX.
NGINX JavaScript é um módulo para NGINX Open Source ou NGINX Plus. Caso ainda não tenha feito isso, siga estas etapas para instalar o NGINX Open Source ou o NGINX Plus. Depois de instalado, certifique-se de que a instância NGINX esteja em execução e seja capaz de responder às solicitações HTTP.
Emita o seguinte comando para iniciar o NGINX:
sudo nginx
enrolar -I 127.0.0.1
Você deverá ver a seguinte resposta:
HTTP/1.1 200 OK Servidor: nginx/1.25.5
Depois de instalados, um (ou ambos) módulo(s) NJS devem ser incluídos no arquivo de configuração NGINX. Na maioria dos sistemas, o arquivo de configuração NGINX está localizado em /etc/nginx/nginx.conf por padrão.
sudo vi /etc/nginx/nginx.conf
Use a diretiva load_module no contexto de nível superior (“principal”) para ativar um (ou ambos) módulo(s).
módulos load_module/ngx_http_js_module.so; módulos load_module/ngx_stream_js_module.so;
Os arquivos de script NJS normalmente são nomeados com uma extensão .js e colocados no diretório /etc/nginx/njs/ . Geralmente são compostos por funções que são exportadas, disponibilizando-as nos arquivos de configuração do NGINX.
NJS fornece uma coleção de objetos com métodos e propriedades associados que não fazem parte das definições do ECMAScript. Veja a referência completa a esses objetos e como eles podem ser usados para estender e personalizar ainda mais o NGINX.
Aqui está um exemplo básico de "Hello World".
A função hello neste arquivo retorna um código de resposta de status HTTP 200 OK junto com a string "Hello World!", seguida por um feed de linha. A função é então exportada para uso em um arquivo de configuração NGINX.
Adicione este arquivo ao diretório /etc/nginx/njs :
função olá(r) {
r.return(200, "Olá mundo!n");}exportar padrão {olá} Modificamos nossa configuração NGINX ( /etc/nginx/nginx.conf ) para importar o arquivo JavaScript e executar a função em circunstâncias específicas.
# Carregue o ngx_http_js_module moduleload_module module/ngx_http_js_module.so;events {}http { # Defina o caminho para nossos arquivos JavaScript njs
js_path "/etc/nginx/njs/"; # Importe nosso arquivo JavaScript para a variável "main"
js_import principal de http/hello.js; server {listen 80;location / { # Execute a função "hello" definida em nosso arquivo JavaScript em todas as solicitações HTTP # e responda com o conteúdo de nossa função. js_content main.hello;
}
}
}Para obter uma lista completa das diretivas njs, consulte as páginas de documentação dos módulos ngx_http_js_module e ngx_stream_js_module.
Dica
Uma versão mais detalhada deste e de outros exemplos pode ser encontrada no repositório oficial njs-examples.
O NGINX JavaScript é instalado com um utilitário de interface de linha de comando. A interface pode ser aberta como um shell interativo ou usada para processar sintaxe JavaScript a partir de arquivos predefinidos ou entrada padrão. Como o utilitário é executado de forma independente, objetos específicos do NGINX, como HTTP e Stream, não estão disponíveis em seu tempo de execução.
$ njs>> globalThisglobal {
njs: njs {versão: '0.8.4'
},
global: [Circular],
processo: processo {argv: ['/usr/bin/njs'],env: { PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin: /bin', HOSTNAME: 'f777c149d4f8', TERMO: 'xterm', NGINX_VERSION: '1.25.5', NJS_VERSION: '0.8.4', PKG_RELEASE: '1~buster', HOME: '/root'}
},
console: {log: [Função: nativo],dump: [Função: nativo],tempo: [Função: nativo],timeEnd: [Função: nativo]
},
imprimir: [Função: nativo]}>>$ echo "2**3" | js-q 8
As etapas a seguir podem ser usadas para construir o NGINX JavaScript como um módulo dinâmico a ser integrado ao NGINX ou um binário independente para uso como um utilitário de interface de linha de comando.
Importante
Para construir o módulo para uso com o NGINX, você também precisará clonar, configurar e construir o NGINX seguindo as etapas descritas neste documento.
A maioria das distribuições Linux exigirá a instalação de várias dependências para construir NGINX e NGINX JavaScript. As instruções a seguir são específicas para o gerenciador de pacotes apt , amplamente disponível na maioria das distribuições Ubuntu/Debian e seus derivados.
sudo apt instalar gcc make
sudo apt instalar libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-dev
Para construir com QuickJS, você também precisará construir a biblioteca QuickJS:
clone do git https://github.com/bellard/quickjscd quickjs CFLAGS='-fPIC' make libquickjs.a
Aviso
Este é o conjunto mínimo de bibliotecas de dependência necessárias para construir NGINX e NJS. Outras dependências podem ser necessárias se você optar por construir o NGINX com módulos adicionais. Monitore a saída do comando configure discutido nas seções a seguir para obter informações sobre quais módulos podem estar faltando.
Usando seu método preferido, clone o repositório JavaScript NGINX em seu diretório de desenvolvimento. Consulte Clonando um repositório GitHub para obter ajuda adicional.
https://github.com/nginx/njs.git
As etapas a seguir são opcionais e necessárias apenas se você optar por construir o NJS como um utilitário independente.
Para usar o shell interativo NJS, você precisará instalar a biblioteca libedit-dev
sudo apt instalar libedit-dev
Execute os seguintes comandos no diretório raiz do seu repositório clonado:
./configure
Construa JavaScript NGINX:
fazer
O utilitário agora deve estar disponível em <NJS_SRC_ROOT_DIR>/build/njs . Consulte A interface de linha de comando (CLI) do NJS para obter informações sobre o uso.
Clone o repositório de código-fonte NGINX em um diretório fora do repositório de origem NJS clonado anteriormente.
https://github.com/nginx/nginx.git
Para construir o NGINX JavaScript como um módulo dinâmico, execute os seguintes comandos no diretório raiz do repositório de código-fonte NGINX:
auto/configure --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
Para construir com suporte QuickJS, forneça o caminho de inclusão e da biblioteca usando as opções --with-cc-opt= e --with-ld-opt= :
auto/configure --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
--with-cc-opt="-I<QUICKJS_SRC_ROOT_DIR>" --with-ld-opt="-L<QUICKJS_SRC_ROOT_DIR>"Aviso
Por padrão, este método construirá apenas o módulo ngx_http_js_module . Para usar NJS com o módulo NGINX Stream, você precisará habilitá-lo durante a etapa configure para que ele seja compilado com o binário NGINX. Fazer isso compilará automaticamente o módulo ngx_stream_js_module quando NJS for adicionado à compilação. Uma maneira de fazer isso é alterar a etapa configure para:
auto/configure --with-stream --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
Compilar o módulo
fazer
Dica
Para construir o NGINX com JavaScript NGINX incorporado em um único binário, altere a etapa configure para o seguinte:
auto/configure --add-module=<NJS_SRC_ROOT_DIR>/nginx
Se construído como módulo(s) dinâmico(s), o(s) módulo(s) JavaScript NGINX estarão disponíveis no diretório <NGINX_SRC_ROOT_DIR>/objs/ . Os módulos podem então ser copiados para uma instalação NGINX existente e habilitados. Consulte Ativando os módulos JavaScript do NGINX para obter detalhes.
Como alternativa, você pode optar por instalar os binários NGINX e NGINX JavaScript criados emitindo o seguinte comando:
Importante
Se integrado ao binário NGINX como um módulo padrão (não dinâmico), este será o método mais fácil de instalação
fazer instalar
Por padrão, o binário NGINX será instalado em /usr/local/nginx/sbin/nginx . Os módulos JavaScript NGINX serão copiados para /usr/local/nginx/modules/ .
As especificações técnicas do NJS são idênticas às do NGINX.
Consulte Sistemas operacionais e plataformas testados para obter uma lista completa de distribuições suportadas.
Recipiente
Nuvem pública (AWS, Google Cloud Platform, Microsoft Azure)
Máquina virtual
O NGINX JavaScript é compatível com todas as versões de código aberto do NGINX começando com nginx-1.14 e todas as versões do NGINX Plus começando com NGINX Plus R15.
Nós encorajamos você a se envolver conosco. Consulte o guia de contribuição para obter informações sobre como fazer perguntas, relatar problemas e contribuir com código.
Consulte nossa página de lançamento para acompanhar as atualizações.
Licença tipo BSD de 2 cláusulas
Documentação adicional disponível em: https://nginx.org/en/docs/njs/
©2024 F5, Inc. Todos os direitos reservados. https://www.f5.com/products/nginx
