--- title: "Subproyectos detrás de OpenResty - API7.ai" description: "This post introduces OpenResty's directory structure and related tools, such as NGINX C Modules, test-nginx, lua-resty projects, and more." url: "https://api7.ai/es/learning-center/openresty/subprojects-behind-openresty" --- # Subproyectos detrás de OpenResty API7.ai September 12, 2022 [OpenResty (NGINX + Lua)](https://api7.ai/learning-center/openresty) ¿Cómo extraer código Lua de `nginx.conf` y mantenerlo legible y mantenible? La solución es bastante simple. Veamos cómo implementarlo con OpenResty. Primero, crea un directorio llamado `lua`. Luego, colocaremos todos los archivos `.lua` en él. ``` $ mkdir lua $ cat lua/hello.lua ngx.say("hello, world") ``` Segundo, usa `content_by_lua_block` para reemplazar `content_by_lua_file` en el archivo `nginx.conf`. ``` pid logs/nginx.pid; events { worker_connections 1024; } http { server { listen 8080; location / { content_by_lua_file lua/hello.lua; } } } ``` Tercero, reinicia los servicios de OpenResty, ¡y listo! ``` $ sudo kill -HUP `cat logs/nginx.pid` ``` Usando `content_by_lua_file`, podríamos actualizar el archivo Lua directamente en lugar de actualizar `nginx.conf`. Pero surgen algunas preguntas: 1. Usamos una ruta relativa en la sección `content_by_lua_file lua/hello.lua`. ¿Cómo encuentra OpenResty el archivo Lua real? 2. Después de modificar el código Lua, necesitamos reiniciar OpenResty para que funcione. ¿Hay alguna manera de depurar de manera eficiente? 3. ¿Cómo agregar el directorio que contiene los archivos Lua a la ruta de búsqueda de OpenResty? Te animo a que pienses en estas preguntas, ya que todas pueden responderse en la documentación oficial. Por eso siempre enfatizo la importancia de la documentación. Para la primera pregunta, si se proporciona una ruta relativa, cuando OpenResty se inicia, prefijará el `-p PATH` en los parámetros de la línea de comandos de inicio de OpenResty y concatenará la ruta relativa en una ruta absoluta. De esta manera, OpenResty puede encontrar el archivo Lua sin problemas. El segundo problema es que el código Lua se carga en la primera solicitud y se almacena en caché por defecto. Por lo tanto, cada vez que cambias el archivo fuente Lua, debes recargar OpenResty para que funcione. Puedes evitar la recarga desactivando `lua_code_cache` en `nginx.conf`. Sin embargo, es esencial tener en cuenta que este método solo debe usarse temporalmente para desarrollo y depuración. Si estás implementando en producción, debes habilitar la caché. De lo contrario, tendrá un impacto significativo en el rendimiento. Para la última pregunta, OpenResty proporciona una directiva `lua_package_path` para establecer la ruta de búsqueda de módulos Lua. Por ejemplo, podemos configurar `lua_package_path` como `$prefix/lua/?.lua;;`: - `$prefix` es el `-p PATH` en el parámetro de inicio. - `/lua/?.lua` indica todos los archivos en el directorio Lua con el sufijo `.lua`. - Los dos últimos puntos y comas representan la ruta de búsqueda de código incorporada. ## Estructura del directorio después de la instalación Después de entender el primer programa "hello world", profundicemos y veamos cómo es la estructura de directorios de OpenResty después de su instalación y qué archivos contiene. Primero, pasamos la opción `-V` para ver dónde está instalado OpenResty. Para el siguiente resultado, omití muchos parámetros de compilación de módulos, que agregaremos más adelante: ``` $ openresty -V nginx version: openresty/1.13.6.2 built by clang 10.0.0 (clang-1000.10.44.4) built with OpenSSL 1.1.0h 27 Mar 2018 TLS SNI support enabled configure arguments: --prefix=/usr/local/Cellar/openresty/1.13.6.2/nginx ... ``` Yo uso brew para instalar OpenResty en mi Mac. La ruta es `/usr/local/Cellar/openresty/1.13.6.2/nginx`, que puede diferir de tu entorno. Esta ruta contiene los directorios `bin`, `luajit`, `lualib`, `nginx`, `pod` y otros. Es esencial entender el significado de estas carpetas para que podamos aprender OpenResty mejor. Así que echemos un vistazo a cada una de ellas. Primero está el importante directorio `bin`. ``` $ ll /usr/local/Cellar/openresty/1.13.6.2/bin total 320 -r-xr-xr-x 1 ming admin 19K 3 27 12:54 md2pod.pl -r-xr-xr-x 1 ming admin 15K 3 27 12:54 nginx-xml2pod lrwxr-xr-x 1 ming admin 19B 3 27 12:54 openresty -> ../nginx/sbin/nginx -r-xr-xr-x 1 ming admin 62K 3 27 12:54 opm -r-xr-xr-x 1 ming admin 29K 3 27 12:54 resty -r-xr-xr-x 1 ming admin 15K 3 27 12:54 restydoc -r-xr-xr-x 1 ming admin 8.3K 3 27 12:54 restydoc-index ``` Aquí se encuentran tanto la CLI de OpenResty, `resty`, que mencionamos en la sección anterior, como el ejecutable principal, `openresty`, que en realidad es un enlace simbólico a `nginx`. En cuanto a las otras herramientas en el directorio, no hay duda de que, como `resty`, son todos scripts en Perl. Entre ellos, `opm` es una herramienta de gestión de paquetes que nos permite gestionar todo tipo de paquetes de terceros, lo cual cubriremos en una sección posterior; y `restydoc`, un viejo amigo de la primera sección, es un visor de documentación proporcionado por OpenResty, que nos permite ver la documentación de OpenResty y NGINX. ``` $ restydoc -s ngx.say $ restydoc -s proxy_pass ``` Los dos ejemplos anteriores consultan la API de OpenResty y los comandos de NGINX, respectivamente. `restydoc` es una herramienta muy útil para que los ingenieros de backend se enfoquen en el desarrollo. Después de explorar el directorio `bin`, pasemos al directorio `pod`. Primero, enfaticemos que `pod` aquí no tiene nada que ver con el concepto de un pod en Kubernetes. En cambio, `pod` es un lenguaje de marcado utilizado en Perl para escribir documentación de módulos Perl. Este directorio contiene la documentación de `OpenResty`, `NGINX`, `lua-resty-*` y `LuaJIT`, que están todos vinculados con `restydoc` mencionado anteriormente. Luego están los familiares directorios `NGINX` y `luajit`. Estos dos son fáciles de entender. Principalmente almacenan los archivos ejecutables y dependencias de NGINX y LuaJIT, y son la base de OpenResty. Mucha gente dice que OpenResty está basado en Lua, pero eso es inexacto. Como vimos anteriormente, OpenResty en realidad está basado en LuaJIT. De hecho, en las primeras etapas, OpenResty venía con Lua y LuaJIT, y podíamos decidir si usar Lua o LuaJIT mediante opciones de compilación. Sin embargo, Lua está siendo descontinuado, y solo se admite el más eficiente LuaJIT. Finalmente, veamos el directorio `lualib`. Contiene las bibliotecas Lua utilizadas en OpenResty, principalmente divididas en dos directorios: `ngx` y `resty`. - El directorio `ngx` contiene los códigos Lua del proyecto oficial [lua-resty-core](https://github.com/openresty/lua-resty-core/tree/master/lib/ngx), que es una reimplementación basada en FFI de la API de OpenResty. Explicaré en un capítulo especial por qué necesitamos reimplementarlo. - El directorio `resty` contiene códigos Lua de varios proyectos `lua-resty-*`, que veremos a continuación. Siguiendo la convención de este curso, en este punto proporcionaré la fuente de estos directorios. Esta es también una de las alegrías de los proyectos de código abierto. Si te gusta profundizar y preguntar hasta el final, siempre encontrarás cosas más interesantes. Aquí está el [script de empaquetado](https://github.com/openresty/openresty-packaging/blob/master/rpm/SPECS/openresty.spec#L218) de OpenResty para CentOS, que contiene todos los directorios mencionados anteriormente. ``` %files %defattr(-,root,root,-) /etc/init.d/%{name} /usr/bin/%{name} %{orprefix}/bin/openresty %{orprefix}/site/lualib/ %{orprefix}/luajit/* %{orprefix}/lualib/* %{orprefix}/nginx/html/* %{orprefix}/nginx/logs/ %{orprefix}/nginx/sbin/* %{orprefix}/nginx/tapset/* %config(noreplace) %{orprefix}/nginx/conf/* %{orprefix}/COPYRIGHT ``` ## Visión general del proyecto OpenResty Cuando hablamos de OpenResty, pensamos en `lua-nginx-module`. Sí, este módulo C de NGINX es realmente el núcleo de OpenResty, pero no es equivalente a OpenResty. Muchos ingenieros llaman a OpenResty como `ngx + lua`, lo cual también se usa en libros compartidos y publicados en muchas conferencias técnicas. Esto no es riguroso y no es apoyado por la comunidad de OpenResty. Permíteme hablar sobre por qué y qué otros proyectos relacionados, además de `lua-nginx-module`, hay en OpenResty. Abre la [página principal](https://github.com/openresty/) del proyecto OpenResty en GitHub, y verás que OpenResty contiene 68 proyectos públicos, que se dividen aproximadamente en las siguientes siete categorías. Permíteme presentarlas brevemente para que tengas una impresión preliminar y puedas aprender rápidamente. ### Módulos C de NGINX La nomenclatura de los proyectos de OpenResty está estandarizada, y aquellos nombrados como `*-nginx-module` son los módulos C de NGINX. Hay más de 20 módulos C en OpenResty, y podemos encontrarlos usando `openresty -V`, que usamos al comienzo de esta sección. ``` $ openresty -V nginx version: openresty/1.13.6.2 built by clang 10.0.0 (clang-1000.10.44.4) built with OpenSSL 1.1.0h 27 Mar 2018 TLS SNI support enabled configure arguments: --prefix=/usr/local/Cellar/openresty/1.13.6.2/nginx --with-cc-opt='-O2 -I/usr/local/include -I/usr/local/opt/pcre/include -I/usr/local/opt/openresty-openssl/include' --add-module=../ngx_devel_kit-0.3.0 --add-module=../echo-nginx-module-0.61 --add-module=../xss-nginx-module-0.06 --add-module=../ngx_coolkit-0.2rc3 --add-module=../set-misc-nginx-module-0.32 --add-module=../form-input-nginx-module-0.12 --add-module=../encrypted-session-nginx-module-0.08 --add-module=../srcache-nginx-module-0.31 --add-module=../ngx_lua-0.10.13 --add-module=../ngx_lua_upstream-0.07 --add-module=../headers-more-nginx-module-0.33 --add-module=../array-var-nginx-module-0.05 --add-module=../memc-nginx-module-0.19 --add-module=../redis2-nginx-module-0.15 --add-module=../redis-nginx-module-0.3.7 --add-module=../ngx_stream_lua-0.0.5 --with-ld-opt='-Wl,-rpath,/usr/local/Cellar/openresty/1.13.6.2/luajit/lib -L/usr/local/lib -L/usr/local/opt/pcre/lib -L/usr/local/opt/openresty-openssl/lib' --pid-path=/usr/local/var/run/openresty.pid --lock-path=/usr/local/var/run/openresty.lock --conf-path=/usr/local/etc/openresty/nginx.conf --http-log-path=/usr/local/var/log/nginx/access.log --error-log-path=/usr/local/var/log/nginx/error.log --with-pcre-jit --with-ipv6 --with-stream --with-stream_ssl_module --with-stream_ssl_preread_module --with-http_v2_module --without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module --with-http_stub_status_module --with-http_realip_module --with-http_addition_module --with-http_auth_request_module --with-http_secure_link_module --with-http_random_index_module --with-http_geoip_module --with-http_gzip_static_module --with-http_sub_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gunzip_module --with-threads --with-dtrace-probes --with-stream --with-stream_ssl_module --with-http_ssl_module ``` Aquí `--add-module=` es seguido por los módulos C de OpenResty. Los principales son `lua-nginx-module` y `stream-lua-nginx-module`, el primero para manejar tráfico de Capa 7 y el segundo para manejar tráfico de Capa 4. Algunos de estos módulos C requieren atención especial y no se recomiendan, aunque están compilados en OpenResty por defecto. Por ejemplo, `redis2-nginx-module`, `redis-nginx-module` y `memc-nginx-module` se usan para interoperar con Redis y Memcached. Estas bibliotecas C fueron recomendadas por OpenResty en las primeras etapas, pero han sido reemplazadas por `lua-resty-redis` y `lua-resty-memcached` después de que se agregó la función `cosocket`, y se mantienen inactivas. OpenResty no desarrollará más bibliotecas C de NGINX en el futuro, sino que se centrará en la biblioteca Lua basada en `cosocket`, que es el futuro. ### Bibliotecas `lua-resty-*` El repositorio oficial de OpenResty contiene 18 bibliotecas `lua-resty-*`, incluyendo Redis, MySQL, Memcached, WebSocket, DNS, control de tráfico, procesamiento de cadenas, caché en proceso y otras bibliotecas estándar. Además de las oficiales que vienen incluidas, hay más bibliotecas de terceros. Son esenciales, y dedicaremos más tiempo a estas bibliotecas en la siguiente sección. ### Rama de LuaJIT mantenida por OpenResty OpenResty mantiene su propia [rama de LuaJIT](https://github.com/openresty/luajit2) además de su parche de OpenSSL. En 2015, el autor de LuaJIT, Mike Pall, anunció su retiro para encontrar un nuevo mantenedor de LuaJIT, pero Mike no encontró un mantenedor adecuado. Ahora se dedica principalmente a la corrección de errores, y el desarrollo de nuevas funciones se ha suspendido, por lo que OpenResty mantiene su propia rama de LuaJIT. En comparación con Lua, LuaJIT agrega muchas funciones esenciales y únicas, pero no muchos ingenieros las conocen, por lo que son habilidades semiocultas que presentaré más adelante. ### Marco de pruebas El marco de pruebas de OpenResty es [test-nginx](https://github.com/openresty/test-nginx), también desarrollado en Perl, y como puedes ver por el nombre, está diseñado específicamente para probar proyectos relacionados con NGINX. Todos los casos de prueba oficiales de OpenResty para módulos C y la biblioteca `lua-resty` son impulsados por `test-nginx`. Este es un sistema mucho más potente e independiente, a diferencia de los marcos comunes basados en aserciones. Algunos contribuyentes de OpenResty tampoco han entendido este marco de pruebas y, a veces, envían PRs que contienen código C y Lua complejo, pero aún así a menudo se sienten intimidados por la idea de escribir casos de prueba correspondientes. Así que si has visto algunos de los casos de prueba en el directorio `/t` del proyecto OpenResty y aún estás confundido, no dudes de ti mismo. La mayoría de las personas están en la misma situación. Además de `test-nginx`, el proyecto [mockeagain](https://github.com/openresty/mockeagain) simula una red lenta, permitiendo que los programas lean y escriban un byte a la vez. Esta es una herramienta muy útil para servidores web. ### Cadena de herramientas de depuración El proyecto OpenResty ha invertido mucho esfuerzo en cómo depurar código de manera científica y dinámica. Los dos proyectos de OpenResty, [openresty-systemtap-toolkit](https://github.com/openresty/openresty-systemtap-toolkit) y [stapxx](https://github.com/openresty/stapxx), están basados en `systemtap`, una herramienta de depuración y seguimiento dinámico. La mayor ventaja de usar `systemtap` es que permite el análisis in vivo mientras es completamente no intrusivo para la aplicación objetivo. Por ejemplo, un `systemtap` es como ir al hospital y hacerse una tomografía computarizada, indolora y no perceptible. Aún mejor, `systemtap` puede generar gráficos de llamadas visuales para el análisis de rendimiento, lo cual describiré más adelante, así que aquí tienes un gráfico de llamadas para que te hagas una idea. ![Gráfico de llamadas relacionado con OpenResty](https://static.api7.ai/uploads/2023/12/25/Ysj9Uqfk_rEx9YfVXSV.jpg?imageMogr2/format/webp) ### Empaquetado Los scripts de empaquetado de OpenResty en diferentes sistemas operativos de distribución (como CentOS, Ubuntu, macOS, etc.) están escritos a mano para una mejor controlabilidad. Cuando presentamos la estructura del directorio después de la instalación, ya cubrimos estos proyectos relacionados con el empaquetado: [openresty-packaging](https://github.com/openresty/openresty-packaging) y [home-brew](https://github.com/openresty/homebrew-brew). Si estás interesado en esto, puedes aprenderlo por tu cuenta, y no lo repetiré aquí. ### Herramientas de ingeniería Además de estos proyectos más grandes, OpenResty tiene varias herramientas de ingeniería que en su mayoría están ocultas. Por ejemplo, [openresty-devel-utils](https://github.com/openresty/openresty-devel-utils) es el conjunto de herramientas para desarrollar OpenResty y NGINX. Por supuesto, también están desarrolladas en Perl, y la mayoría de las herramientas no están documentadas. Pero para los desarrolladores de OpenResty, estas herramientas son muy útiles. Comenzaré seleccionando algunas y presentándolas brevemente. - [lj-releng](https://github.com/openresty/openresty-devel-utils/blob/master/lj-releng) es una herramienta de inspección de código LuaJIT simple y efectiva, similar a `luacheck`, que puede encontrar problemas potenciales con variables globales. - [reindex](https://github.com/openresty/openresty-devel-utils/blob/master/reindex), que significa reconstruir el índice, es una herramienta para formatear casos de prueba de `test-nginx`, reorganizar números de casos de prueba y eliminar espacios en blanco adicionales. `reindex` es una de las herramientas que los desarrolladores de OpenResty usan a diario. - [opsboy](https://github.com/openresty/opsboy) se utiliza para realizar implementaciones automatizadas. Se utiliza para implementar y ejecutar las pruebas de regresión que OpenResty realiza en clústeres de AWS EC2 antes de cada lanzamiento. Para obtener información detallada, puedes consultar la [documentación oficial](https://openresty.org/en/ec2-test-cluster.html). `opsboy` es un DSL implementado en Perl. A los autores de OpenResty les gusta crear diferentes DSLs para resolver problemas. ## Resumen Hoy, principalmente aprendimos la estructura del directorio de OpenResty después de la instalación y algunos subproyectos detrás de él. Después de aprender el contenido de hoy, espero que puedas conocer más sobre los proyectos de OpenResty. OpenResty ha ido mucho más allá del alcance del equilibrio de carga y proxy inverso de NGINX y ha creado su propio ecosistema. La próxima vez hablaremos de esto en detalle. ## Lectura adicional - [¿Cuál es la diferencia entre OpenResty y NGINX?](https://api7.ai/learning-center/openresty/openresty-vs-nginx/) - [Tu primer programa en OpenResty: Hello World](https://api7.ai/learning-center/openresty/hello-world-in-openresty/) Share article link Share Related Posts [![Preguntas frecuentes de OpenResty | Cómo se utiliza OpenResty en la práctica](https://static.api7.ai/uploads/2023/02/12/jbv9M0zi_Hello%20World%20in%20OpenResty%20%283%29.png)](https://api7.ai/learning-center/openresty/faq-5) ## [Preguntas frecuentes de OpenResty | Cómo se utiliza OpenResty en la práctica](https://api7.ai/learning-center/openresty/faq-5) [![Parte 3: Cómo construir una API Gateway para Microservicios usando OpenResty](https://static.api7.ai/uploads/2023/02/07/3XJXY9Jy_45.png)](https://api7.ai/learning-center/openresty/how-to-build-a-microservices-api-gateway-part-3) ## [Parte 3: Cómo construir una API Gateway para Microservicios usando OpenResty](https://api7.ai/learning-center/openresty/how-to-build-a-microservices-api-gateway-part-3) Table of Contents - [Estructura del directorio después de la instalación](#estructura-del-directorio-despu%C3%A9s-de-la-instalaci%C3%B3n) - [Visión general del proyecto OpenResty](#visi%C3%B3n-general-del-proyecto-openresty) - [Módulos C de NGINX](#m%C3%B3dulos-c-de-nginx) - [Bibliotecas `lua-resty-*`](#bibliotecas-lua-resty-) - [Rama de LuaJIT mantenida por OpenResty](#rama-de-luajit-mantenida-por-openresty) - [Marco de pruebas](#marco-de-pruebas) - [Cadena de herramientas de depuración](#cadena-de-herramientas-de-depuraci%C3%B3n) - [Empaquetado](#empaquetado) - [Herramientas de ingeniería](#herramientas-de-ingenier%C3%ADa) - [Resumen](#resumen) - [Lectura adicional](#lectura-adicional)