Nginx Proxy Manager: tuning más allá de los defaults

Nginx Proxy Manager arranca con defaults pensados para shared hosting: buffers chicos, keepalive corto y una cantidad de workers que no mira tu CPU real. Con tráfico serio, eso se traduce en 502s y timeouts. La Nginx Proxy Manager optimización pasa por editar el nginx.conf generado, algo que la UI no te expone.

Nginx Proxy Manager (NPM) es una interfaz web sobre Nginx que te levanta un reverse proxy con certificados Let’s Encrypt en menos de diez minutos. Corre en Docker, administra proxy hosts, redirecciones y SSL desde el navegador. El problema no es lo que hace, sino los valores por defecto: están calibrados para hosting compartido, no para un home lab donde vos tenés el hardware.

¿Por qué la configuración por defecto de Nginx Proxy Manager falla en tráfico real?

Ponele que montás NPM para exponer un par de servicios internos. Todo anda bárbaro. Después conectás un flujo de n8n que dispara webhooks en ráfaga, y de golpe empiezan a caer 502s sin razón aparente. No es magia negra: el buffer del upstream se llena más rápido de lo que drena, y Nginx corta la conexión.

Según el análisis técnico publicado el 8 de julio de 2026 en dev.to, los defaults reflejan supuestos de shared hosting: tamaños de buffer conservadores, ventanas de keepalive cortas y una cantidad de workers que no considera la topología real de tu CPU. En una máquina que es tuya, esos no son defaults seguros. Son defaults equivocados.

Los síntomas son reconocibles una vez que sabés qué mirar. Timeouts en respuestas largas de API (una llamada a Ollama en local o un streaming de OpenAI que tarda 45 segundos), 502s durante los picos de webhooks, y latencia en el handshake SSL. La Nginx Proxy Manager optimización arranca justo acá: entendiendo que el panel lindo esconde un archivo de configuración que nadie te invitó a tocar. Cubrimos ese tema en detalle en automatizar despliegues con CI/CD moderno.

¿Cómo preparar correctamente Nginx Proxy Manager en Docker?

El objetivo declarado de NPM es que tengas un reverse proxy andando en menos de diez minutos. Cumple. Eso sí: ese deploy express deja toda la performance sin tocar.

• Persistí la configuración en volúmenes: montá ./data y ./letsencrypt como volúmenes Docker para no perder certificados ni ajustes en cada recreación del contenedor.
• Ubicá el nginx.conf generado: NPM lo escribe dentro de /data/nginx. Ahí viven los bloques por host que después vas a extender.
• Verificá permisos: si el contenedor no puede escribir en el volumen, falla la renovación y te vas a enterar tarde.
• Reservá acceso directo al archivo: los ajustes de workers y buffers no salen del panel, así que necesitás editar el nginx.conf a mano y recargar.

Si vas a correr esto sobre un VPS en vez de hardware casero, cualquier servidor con acceso root te sirve. Para infraestructura en Argentina, donweb.com tiene planes de VPS y cloud donde podés desplegar Docker sin pelearte con la latencia internacional.

Tuning de workers y buffers en nginx.conf: valores por CPU

Acá viene lo bueno. Esta es la parte que más impacto tiene y la que menos gente configura.

El worker_processes tiene que coincidir con la cantidad de núcleos físicos de tu CPU. Si tenés un procesador de 4 cores, poné worker_processes 4. Podés dejarlo en auto y Nginx lo detecta, pero en un home lab donde sabés exactamente qué hardware tenés, fijarlo a mano te da control. Cada worker maneja miles de conexiones, y quedarte corto significa que un núcleo se satura mientras los demás miran.

Los buffers son el otro frente. El proxy_buffer_size guarda la primera parte de la respuesta del upstream (headers incluidos), mientras que proxy_buffers define cuántos búferes y de qué tamaño usás para el resto. Los defaults son conservadores; si manejás payloads grandes (respuestas JSON gordas, streaming), agrandá tanto el proxy_buffer_size como el proxy_buffers para que la respuesta del upstream no desborde. El proxy_busy_buffers_size tiene que ser mayor que un buffer individual pero menor al total. Sobre eso hablamos en elegir entre Jenkins y GitHub Actions.

Parámetro	Default (shared)	Optimizado (home lab)
worker_processes	1 o bajo	= núcleos físicos (ej. 4)
proxy_buffer_size	4-8 KB	más grande que el default
proxy_buffers	8x 4 KB	más búferes / más grandes (payloads grandes)
proxy_read_timeout	60s	mayor al default (inferencia larga)
keepalive_timeout	corto	más largo + keepalive upstream
proxy_buffering	on	off (para streaming)

¿Qué configuración de keepalive y timeouts necesita Nginx Proxy Manager?

El proxy_connect_timeout y el proxy_read_timeout por defecto rondan los 60 segundos. Suena razonable hasta que una inferencia local tarda 45 segundos y el streaming se corta a mitad de respuesta. Subí el proxy_read_timeout por encima del default cuando trabajás con modelos que piensan un rato. Ampliá el proxy_send_timeout si tenés uploads grandes que suben lento.

El keepalive del upstream es lo que casi nadie toca. Definí un bloque upstream con keepalive habilitado y ajustá keepalive_requests y keepalive_timeout para reusar conexiones en vez de abrir una nueva por cada request. ¿El resultado? Menos overhead de TCP y menos latencia en cada llamada.

Un caso puntual: para respuestas en streaming (SSE, tokens de un LLM que van llegando de a poco), poné proxy_buffering off. Si dejás el buffering activo, Nginx junta toda la respuesta antes de mandártela, y adiós al efecto “tiempo real”. Con el buffering apagado, cada token viaja apenas llega.

SSL, Let’s Encrypt y HSTS: lo que NPM no expone en la UI

NPM genera certificados Let’s Encrypt sin drama y los renueva solo. La parte que queda coja es la configuración SSL avanzada, que otra vez vive en el nginx.conf. Complementá con servir contenido en múltiples idiomas.

• Wildcard certs para subdominios múltiples: si exponés app.tudominio.com, api.tudominio.com y varios más, un certificado wildcard (*.tudominio.com) vía DNS challenge te ahorra emitir uno por cada host.
• HSTS bien puesto: el header Strict-Transport-Security tiene que incluir includeSubDomains. Sin eso, un subdominio queda expuesto a downgrade a HTTP.
• Cuidado con el preload: mandar HSTS con preload sin estar seguro te puede dejar afuera si algo falla. Es difícil de revertir.
• Redirección HTTP a HTTPS completa: revisá que ningún host quede sirviendo por el puerto 80 sin redirigir.

Cómo monitorear Nginx Proxy Manager antes de que los usuarios se quejen

Los logs te cuentan lo que ya pasó. Sirven para el post-mortem, no para prevenir. Lo que querés es visibilidad en tiempo real.

Mirá los procesos worker activos, las conexiones abiertas y la profundidad de la cola. Un netstat rápido te muestra si hay connection refuses acumulándose, que es la señal temprana de que el pool de conexiones se está agotando. Para algo más serio, Prometheus con el exporter de Nginx te deja armar alertas por tasa de 502, tiempo de respuesta P95 y saturación del pool. Herramientas como monit cubren el caso simple de “reiniciá el contenedor si se cae”.

¿Cuándo Nginx Proxy Manager NO es la herramienta correcta?

NPM es una máquina, no un cluster. Ese es el límite. Si necesitás balanceo horizontal real, escalado automático o carga masiva de certificados, se te queda corto.

• Websockets pesados: los maneja, pero requiere tuning extra que la UI no facilita.
• Certificados en masa: emitir cientos de certs de una es lento comparado con automatizaciones dedicadas.
• Nginx puro: más control fino, sin la capa de abstracción, ideal cuando ya sabés lo que hacés.
• Traefik: orquestación dinámica, descubre servicios de Docker solo, mejor para entornos que cambian seguido.
• Load balancers cloud: un balanceador gestionado (tipo un ALB) tiene sentido cuando pasás de un home lab a producción distribuida.

Errores comunes al optimizar Nginx Proxy Manager

• Poner worker_processes al voleo: setear 16 workers en una CPU de 4 cores no acelera nada, solo agrega overhead de contexto. Igualá los núcleos físicos.
• Dejar el timeout en 60s con LLMs: si tus upstreams tardan más de un minuto, el default corta la respuesta. Subí proxy_read_timeout según tu peor caso.
• Editar la UI esperando que persista: los cambios manuales en el nginx.conf pueden pisarse cuando NPM regenera la config del host. Usá los bloques de “Custom Nginx Configuration” del panel para que sobrevivan.
• Olvidar recargar: tocaste el archivo y no pasa nada. Faltó el nginx -s reload dentro del contenedor.

Preguntas Frecuentes

¿Por qué Nginx Proxy Manager tira 502 bajo carga?

El 502 aparece cuando el buffer del upstream se llena más rápido de lo que drena, típico en ráfagas de webhooks. Los buffers por defecto son chicos para tráfico de home lab. Subí proxy_buffers y proxy_buffer_size en el nginx.conf y el problema baja de forma notoria. Más contexto en integrar diferentes proveedores de IA.

¿Qué valor de worker_processes conviene en un home lab?

El valor tiene que coincidir con la cantidad de núcleos físicos de tu CPU. Una CPU de 4 cores usa worker_processes 4. Poner más no mejora el rendimiento y agrega cambios de contexto innecesarios. El valor auto también funciona porque detecta los cores disponibles.

¿Cómo evito timeouts en respuestas largas de API?

Subí proxy_read_timeout por encima del default cuando trabajás con inferencia de modelos que tarda 45 segundos o más. Para streaming, agregá proxy_buffering off así cada fragmento llega apenas se genera en vez de esperar la respuesta completa.

¿Se pueden editar los buffers desde la interfaz de NPM?

No de forma directa. El panel no expone workers ni buffers. Tenés que usar el bloque “Custom Nginx Configuration” en la config avanzada del proxy host, o editar el nginx.conf generado en /data/nginx y recargar Nginx dentro del contenedor.

¿NPM sirve para producción a gran escala?

Para un home lab o un proyecto chico, sí. Para escala grande con balanceo horizontal, alta disponibilidad o miles de certificados, conviene Nginx puro, Traefik o un load balancer gestionado. NPM es una sola máquina y no escala a cluster por diseño.

Conclusión

Nginx Proxy Manager resuelve el 90% del laburo en diez minutos, pero el 10% restante (el que hace la diferencia entre “anda” y “aguanta”) vive en el nginx.conf que la UI no te muestra. Igualá los workers a tus núcleos, agrandá los buffers, estirá los timeouts para inferencia larga y apagá el buffering en streaming. Si tu home lab empieza a pedir cluster o balanceo real, es la señal para mirar Nginx puro o Traefik. Empezá midiendo: sin monitoreo en tiempo real, cualquier tuning es a ciegas.

Fuentes

• Nginx Proxy Manager on Your Home Lab: Performance Tuning Beyond the Defaults – análisis técnico original (dev.to, 8 de julio de 2026)
• Documentación oficial del módulo ngx_http_proxy de Nginx – referencia de buffers y timeouts
• Sitio oficial de Nginx Proxy Manager – guía de instalación y setup en Docker