Nginx, VPS, proxy y CDN: desplegar Éclair

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.

Lo que Nginx debe reproducir del .htaccess

Nginx ignora los archivos .htaccess. Por eso su configuración debe garantizar las mismas protecciones:

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.

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.

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

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 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;
}

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.

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.

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, 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.

# 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' '<Directory /var/www/html>' '    AllowOverride All' '</Directory>' \
      > /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/

# 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).

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

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: por qué existe cada regla del .htaccess.
• Rendimiento: mantener 100 sobre 100: medir el sitio una vez desplegado.
• Seguridad avanzada y mantenimiento: permisos de los archivos, copias de seguridad y actualizaciones.
• Conectar Claude a tu sitio: el conector MCP, que exige HTTPS.
• Nginx: módulo FastCGI, para fastcgi_buffering y fastcgi_read_timeout (en inglés).
• Docker Hub: imagen oficial de php, con sus extensiones y su php.ini (en inglés).

Todas las lecciones de la ruta