--- title: "Nginx, VPS, proxy y CDN: desplegar Éclair" description: "Desplegar Éclair en un VPS: configuración de Nginx comentada, PHP-FPM, HTTPS con Certbot, proxy inverso, IP real, Cloudflare y ejemplo Docker php:8.3-apache." url: "https://eclair.academy/es/rutas/experto/nginx-vps" lang: "es" author: "Thierry Gustin" published: "2026-11-02" updated: "2026-11-02" --- # Nginx, VPS, proxy y CDN: desplegar Éclair > **Lo esencial** — Para desplegar Éclair fuera de un hosting compartido, reproduce en Nginx las reglas del .htaccess, envía lo demás a index.php mediante PHP-FPM con fastcgi_buffering off, activa HTTPS con Certbot e indica en Ajustes › Avanzado si el sitio está detrás de un proxy o una CDN. Un contenedor php:8.3-apache con mod_rewrite y AllowOverride All también funciona. Desplegar Éclair en un VPS, detrás de un proxy o de una CDN consiste en reproducir lo que el `.htaccess` hace en un hosting compartido: proteger las carpetas internas, enviarlo todo a `index.php`, comprimir los archivos estáticos y guardarlos en caché. Esta lección te da una configuración de Nginx comentada, los ajustes de HTTPS, proxy y Cloudflare, un ejemplo de Docker y las comprobaciones finales. > **Antes de empezar** — Duración: 1 hora. Requisitos: un VPS Debian o Ubuntu con acceso root, Nginx y PHP-FPM 8.3 instalados, un dominio que apunte al servidor y la lección [La arquitectura de Éclair](https://eclair.academy/es/rutas/experto/arquitectura). En un hosting compartido no necesitas nada de esto: consulta [Elegir tu alojamiento](https://eclair.academy/es/alojamiento). ## Lo que sabrás hacer ### 🔧 Configurar Nginx Las reglas del .htaccess, PHP-FPM y el flujo del asistente. ### 🔒 Pasar a HTTPS Certbot, Forzar HTTPS, dirección oficial y HSTS. ### 🌍 Poner un proxy o una CDN Dirección IP real, Cloudflare y contenedor Docker. ## Lo que Nginx debe reproducir del .htaccess Nginx ignora los archivos `.htaccess`. Por eso su configuración debe garantizar las mismas protecciones: | Regla del .htaccess | Por qué | | --- | --- | | `app/`, `data/` y `cache/` responden 404 | el código, los datos y las páginas generadas siguen siendo privados | | archivos ocultos en 404, salvo `.well-known` | `.git` o `.env` invisibles, descubrimiento OAuth del MCP accesible | | ningún `.php` ejecutable salvo `index.php` | un script depositado en otro sitio nunca se ejecuta | | `media/` sin scripts ni páginas | una imagen trampa no se convierte en una página | | todo lo demás hacia `index.php` | responde el enrutador de Éclair, direcciones limpias incluidas | | compresión, caché del navegador de un año | páginas ligeras, archivos estáticos reutilizados | La cabecera `Authorization`, que el `.htaccess` tiene que copiar para el conector MCP, Nginx la transmite de serie a PHP-FPM. ## La configuración de Nginx comentada Las reglas retoman la sección Nginx de la guía oficial de Éclair; las líneas marcadas con «añadido» completan el ejemplo para un servidor real. `root` designa la carpeta que recibe el contenido de la carpeta `eclair` del archivo de distribución. ```nginx server { listen 80; listen [::]:80; server_name exemple.fr www.exemple.fr; root /var/www/eclair; index index.php; client_max_body_size 24m; # añadido: imágenes de hasta 20 MB (Nginx: 1 MB por defecto) gzip on; # añadido: compresión, como el .htaccess gzip_types text/plain text/css text/xml text/markdown application/javascript application/json application/xml application/rss+xml image/svg+xml; # Carpetas internas y archivos ocultos, salvo .well-known (descubrimiento OAuth) location ~ ^/(app|data|cache)(/|$) { return 404; } location ~ /\.(?!well-known/) { return 404; } # Medios: solo imágenes y tipografías location ^~ /media/ { location ~* \.(php\d?|phtml|phar|s?html?|svgz?|xml|js)$ { return 404; } add_header X-Content-Type-Options nosniff; add_header Content-Security-Policy "default-src 'none'; img-src 'self'; sandbox"; # añadido, como media/.htaccess expires 1y; } # Archivos estáticos versionados: caché del navegador de un año location ~* \.(webp|avif|jpe?g|png|gif|ico|css|js|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; } # Todo lo demás pasa por el controlador frontal location / { try_files $uri /index.php$is_args$args; } location = /index.php { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root/index.php; fastcgi_pass unix:/run/php/php-fpm.sock; # adáptalo, por ejemplo /run/php/php8.3-fpm.sock fastcgi_buffering off; # lo recomienda la guía: asistente IA en directo fastcgi_read_timeout 300s; # añadido: peticiones largas a la IA (60 s por defecto) } # Ningún otro script PHP location ~ \.php$ { return 404; } } ``` Tres ajustes merecen una explicación: - **`client_max_body_size`**: por defecto, Nginx rechaza las peticiones de más de 1 MB (error 413), mientras que Éclair acepta imágenes de 20 MB. Ajusta también `upload_max_filesize` y `post_max_size` en el `php.ini` de PHP-FPM. - **`fastcgi_buffering off`**: el asistente IA responde en flujo. Éclair ya envía `X-Accel-Buffering: no`, que Nginx respeta por defecto; la directiva cubre las configuraciones que lo ignoran. - **`fastcgi_read_timeout`**: «Crear con IA» responde de una vez al cabo de 20 a 60 segundos, y Éclair se concede hasta 300 segundos, mientras que Nginx corta tras 60 segundos de silencio. ```bash sudo nginx -t && sudo systemctl reload nginx # Éclair solo escribe en data/, cache/ y media/ sudo chown -R www-data:www-data /var/www/eclair/data /var/www/eclair/cache /var/www/eclair/media ``` ## HTTPS con Certbot y después los ajustes de Éclair ```bash sudo certbot --nginx -d exemple.fr -d www.exemple.fr ``` Certbot obtiene un certificado de Let's Encrypt, añade la escucha en el puerto 443 al bloque `server` y puede redirigir el HTTP al HTTPS. Después instala Éclair abriendo `https://exemple.fr`: el asistente guarda la dirección tal como la has abierto y ya marca **Forzar HTTPS**. Luego, en la administración: 1. Abre **Seguridad**: la dirección del sitio debe estar verificada. Si no lo está, haz clic en **Verificar la dirección del sitio**. 2. En **Ajustes › Avanzado**, comprueba que **Forzar HTTPS** está marcado. Éclair se niega a activarlo mientras no hayas iniciado sesión en https. 3. Deja marcado **Redirigir a la dirección oficial**: una sola versión del sitio, con o sin www, en cuanto se verifica la dirección. 4. Cuando todo esté estable, marca **HSTS**. Éclair envía entonces `Strict-Transport-Security: max-age=31536000`, es decir, un año, sin los subdominios. A partir de ahí, los navegadores rechazarán el http:// para tu dominio: por eso no lo actives nunca durante las pruebas. No añadas HSTS también en Nginx: la cabecera saldría dos veces. Si prefieres gestionarlo en Nginx, desmarca la opción de Éclair y recuerda que un `add_header` colocado en un bloque `location` anula los del bloque `server`. ## ¿Cómo desplegar Éclair detrás de un proxy inverso? Cuando otro servidor termina el HTTPS (Nginx delante de un contenedor, Caddy, Traefik…), PHP recibe HTTP. Éclair considera segura la conexión si la variable `HTTPS` está activa, si el puerto es el 443 o si la petición lleva `X-Forwarded-Proto: https` o `X-Forwarded-SSL: on`. Por eso el proxy debe enviar `X-Forwarded-Proto` y conservar la cabecera `Host`, que Éclair compara con su dirección oficial. ```nginx # Nginx como proxy inverso delante de Éclair (contenedor publicado en 127.0.0.1:8080) location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; # host de origen, comparado con la dirección del sitio proxy_set_header X-Forwarded-Proto $scheme; # https, tal como lo ve el visitante proxy_set_header X-Real-IP $remote_addr; # dirección IP real del visitante proxy_buffering off; # flujo del asistente IA proxy_read_timeout 300s; client_max_body_size 24m; } ``` > **No publiques el puerto interno** — Éclair se fía de `X-Forwarded-Proto` venga de donde venga. Publica el puerto de Éclair solo en `127.0.0.1`, para que únicamente tu proxy pueda hablar con él. Detrás de un proxy, PHP ve la dirección IP del proxy: los límites contra la fuerza bruta y los del formulario afectarían a todos los visitantes a la vez. En **Ajustes › Avanzado › Sitio detrás de un proxy / CDN**, elige la cabecera que lleva la dirección real. Éclair solo la lee si la has elegido, y de `X-Forwarded-For` solo conserva la última dirección, la que añade el proxy más cercano. | Situación | Opción en Éclair | | --- | --- | | sin proxy, o con la dirección ya corregida por el módulo realip de Nginx | No (recomendado) | | Nginx como proxy inverso con `proxy_set_header X-Real-IP` | X-Real-IP | | proxy que completa `X-Forwarded-For` | X-Forwarded-For | | Cloudflare delante del sitio, con o sin proxy detrás | Cloudflare | Elige una cabecera solo si el sitio está realmente detrás de ese servicio: si no, un visitante podría escribirla él mismo y saltarse los límites. Detrás de Cloudflare, acepta únicamente las conexiones que vengan de las [direcciones publicadas por Cloudflare](https://www.cloudflare.com/ips/). ## Cloudflare: lo que hay que ajustar - **Cifrado**: modo SSL/TLS «Full (strict)», con un certificado real en tu servidor, por ejemplo el de Certbot. - **Cortafuegos y protección contra bots**: deja pasar `/_eclair/` y `/.well-known/`; si no, Claude y ChatGPT no llegan ni al conector MCP ni a su autorización. - **Caché**: los archivos estáticos ya están marcados para un año. No guardes el HTML en la caché de Cloudflare: Éclair vacía su propia caché en cada publicación, no la de Cloudflare, y ni la administración ni `/_eclair/` deben acabar nunca en ella. - **Opciones que inyectan scripts**: según [la documentación de Cloudflare](https://developers.cloudflare.com/fundamentals/reference/policies-compliances/content-security-policies/), Rocket Loader exige `ajax.cloudflare.com` en `script-src`, y Web Analytics, `static.cloudflareinsights.com`. La CSP de Éclair solo autoriza los scripts del propio dominio: deja esas opciones desactivadas. - **Dirección IP**: elige «Cloudflare» en **Ajustes › Avanzado › Sitio detrás de un proxy / CDN**. ## ¿Cómo desplegar Éclair con Docker? Este es un ejemplo de partida, que tendrás que adaptar, basado en la imagen oficial `php:8.3-apache`. Conserva Apache para que el `.htaccess` de Éclair se aplique tal cual. Coloca este `Dockerfile` junto a la carpeta `eclair` descomprimida. ```dockerfile # Ejemplo de partida, que hay que adaptar: Éclair 1.8 en la imagen oficial PHP 8.3 + Apache FROM php:8.3-apache # Ya incluidas en la imagen: mbstring, json, dom, session, zlib, curl, openssl, sodium, Argon2id. # Por añadir: gd con JPEG y WebP (imágenes), zip (copias de seguridad), exif (fotos de móvil enderezadas). RUN apt-get update \ && apt-get install -y --no-install-recommends libjpeg62-turbo-dev libpng-dev libwebp-dev libzip-dev \ && docker-php-ext-configure gd --with-jpeg --with-webp \ && docker-php-ext-install -j"$(nproc)" gd zip exif \ && rm -rf /var/lib/apt/lists/* # Módulos que usa el .htaccess: reescritura, cabeceras, compresión (sin efecto si ya están activos) RUN a2enmod rewrite headers deflate # .htaccess permitidos: la imagen ya lo hace para /var/www/ (docker-php.conf); aquí se hace explícito RUN printf '%s\n' '' ' AllowOverride All' '' \ > /etc/apache2/conf-available/eclair.conf \ && a2enconf eclair # Ajustes de PHP para producción, subidas de imágenes de hasta 20 MB RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \ && printf '%s\n' 'upload_max_filesize = 20M' 'post_max_size = 24M' > "$PHP_INI_DIR/conf.d/eclair.ini" # El contenido de la carpeta eclair del archivo de distribución, archivos ocultos incluidos COPY --chown=www-data:www-data eclair/ /var/www/html/ ``` ```yaml # compose.yaml: datos y medios persistentes, puerto reservado al proxy HTTPS de la máquina services: eclair: build: . restart: unless-stopped ports: - "127.0.0.1:8080:80" volumes: - eclair-data:/var/www/html/data - eclair-media:/var/www/html/media volumes: eclair-data: eclair-media: ``` `docker compose up -d --build` lanza el sitio en el puerto 8080 de la máquina, detrás del proxy HTTPS de la sección anterior. Los volúmenes con nombre conservan `data/` y `media/` de una versión a otra: para actualizar, sustituye la carpeta `eclair` por la del nuevo archivo de distribución y reconstruye la imagen. La imagen oficial también activa OPcache por defecto (Dockerfile consultado el 1 de noviembre de 2026). ```bash docker compose exec eclair php -r 'var_dump(function_exists("imagewebp"));' # bool(true) docker compose exec eclair apache2ctl -M | grep -E 'rewrite|headers|deflate' ``` ## Comprobaciones después del despliegue ```bash SITE=https://exemple.fr # 1. Archivos internos inaccesibles: se espera un 404 para cada uno for f in /data/site.php /data/users.php /app/bootstrap.php /cache/runtime.php /data/.htaccess; do printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "$SITE$f")" "$f" done # 2. Reescritura de URL: el controlador responde «ok» curl -s "$SITE/__eclair/ping"; echo # 3. Caché estática: X-Cache: HIT en la segunda llamada curl -sI "$SITE/" > /dev/null; curl -sI "$SITE/" | grep -i x-cache # 4. Conector MCP activado: 401 y cabecera WWW-Authenticate curl -si -X POST "$SITE/_eclair/mcp" | grep -i -E '^HTTP|www-authenticate' ``` Termina en la administración: la página **Seguridad** debe mostrar una prueba de protección en verde y una dirección verificada, lo que supone que el servidor puede llamarse a sí mismo por su dirección pública, incluso desde un contenedor. Por último, sube una imagen de más de 1 MB en **Medios** y, si el asistente IA está activado, comprueba que su respuesta aparece poco a poco. ## Para recordar - Nginx ignora el `.htaccess`: copia sus reglas y deja `.well-known` accesible para el conector MCP. - Para desplegar Éclair como es debido, permite subidas de 20 MB y desactiva el búfer de FastCGI para el asistente IA. - Detrás de un proxy, envía `X-Forwarded-Proto` y `Host`, y elige una cabecera de dirección IP solo si existe de verdad. - Con Cloudflare: modo Full (strict), `/_eclair/` y `/.well-known/` abiertos, HTML fuera de la caché, Rocket Loader desactivado. - El ejemplo de Docker conserva Apache y el `.htaccess` original, con `data/` y `media/` en volúmenes. ## Para saber más - [La arquitectura de Éclair](https://eclair.academy/es/rutas/experto/arquitectura): por qué existe cada regla del `.htaccess`. - [Rendimiento: mantener 100 sobre 100](https://eclair.academy/es/rutas/experto/rendimiento): medir el sitio una vez desplegado. - [Seguridad avanzada y mantenimiento](https://eclair.academy/es/rutas/experto/seguridad-avanzada): permisos de los archivos, copias de seguridad y actualizaciones. - [Conectar Claude a tu sitio](https://eclair.academy/es/rutas/ia-mcp/conectar-claude): el conector MCP, que exige HTTPS. - Nginx: [módulo FastCGI](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html), para `fastcgi_buffering` y `fastcgi_read_timeout` (en inglés). - Docker Hub: [imagen oficial de php](https://hub.docker.com/_/php), con sus extensiones y su `php.ini` (en inglés). ## Preguntas frecuentes ### ¿Hay que conservar los archivos .htaccess con Nginx? Con Nginx no sirven de nada, pero no molestan y volverán a ser útiles si regresas a Apache. Es tu configuración de Nginx la que protege el sitio. ### ¿Por qué el asistente IA responde de golpe detrás de Nginx? Un búfer retiene el flujo: comprueba `fastcgi_buffering off;` en el bloque PHP, o `proxy_buffering off;` si Nginx hace de proxy inverso. El resto del sitio no se ve afectado. ### ¿Puede Cloudflare guardar mis páginas HTML en caché? Puede, pero Éclair ya no podrá vaciar esa caché en cada publicación: tus visitantes verían versiones antiguas. La caché estática de Éclair ya sirve las páginas en pocos milisegundos desde tu servidor. ### ¿Hace falta Docker para alojar Éclair? No. Basta con un hosting compartido con Apache o LiteSpeed, y también con un VPS con Nginx. Docker sirve sobre todo para estandarizar despliegues o aislar varios sitios en una misma máquina.