Archivos, carpetas y direcciones

En Éclair, todo lo que forma tu sitio vive en archivos y carpetas que puedes ver por FTP: no hay base de datos. Esta referencia describe la estructura de carpetas, la función de cada archivo de data/, los ajustes de eclair-config.php, las reglas del .htaccess y de Nginx, los permisos necesarios, qué incluir en las copias de seguridad y todas las direcciones que el sitio genera solo.

La estructura de la carpeta eclair

Es el contenido de esta carpeta lo que subes a la carpeta pública de tu hosting (public_html, www…).

eclair/
├── index.php                  controlador frontal: sirve la caché sin cargar la aplicación
├── .htaccess                  reescritura, protecciones, compresión, caché del navegador
├── eclair-config.exemple.php  plantilla de los ajustes avanzados opcionales
├── app/                       el código de Éclair (nunca accesible desde la web)
│   ├── bootstrap.php          arranque: versión de PHP, eclair-config.php, carga
│   ├── manifest.php           huellas originales para el control de integridad
│   ├── lib/                   clases: Content, Blocks, Seo, Analyzer, Media, Auth, Mcp…
│   ├── admin/views/           pantallas de la administración (.php.gz en el archivo ZIP)
│   ├── install/               asistente de instalación y pantalla «Instalación bloqueada»
│   ├── lang/                  traducciones de la administración (6 idiomas, JSON comprimido)
│   └── theme/                 plantillas del sitio público, theme.css, themes/, directions.css
├── assets/
│   ├── admin/                 CSS y JavaScript de la administración
│   └── site/site.js           el único script del sitio público (1,2 KB comprimido)
├── data/                      contenidos, ajustes, cuentas: nunca público
├── cache/                     páginas generadas: nunca público
└── media/                     imágenes subidas, iconos del sitio, fuente de los títulos

app/ y assets/ contienen el código: una actualización los sustituye. Tus datos están en data/ y media/, que las actualizaciones no tocan nunca. El archivo ZIP oficial contiene también, junto a la carpeta eclair, los archivos LISEZ-MOI.txt, LICENSE.txt y THIRD-PARTY-NOTICES.txt: no hace falta subirlos a tu hosting.

¿Cómo se sirve una página?

1. Toda petición de página llega a index.php; las imágenes, los CSS y los scripts los sirve directamente el servidor. Para una lectura (GET o HEAD), index.php lee cache/runtime.php: caché activa, fecha de caducidad, dominio y HTTPS exigidos.
2. Si la página existe en cache/pages/, se envía tal cual, con su ETag; un navegador que ya la tiene recibe una respuesta 304 Not Modified.
3. Si no, app/bootstrap.php arranca la aplicación: comprueba la versión de PHP, lee eclair-config.php si existe y después dirige la petición a la instalación, la administración, el formulario, el conector MCP o el sitio. La página generada se guarda en caché para las visitas siguientes.

El detalle del código está en La arquitectura de Éclair.

¿Qué contiene la carpeta data?

Cada archivo de data/ es un archivo .php que empieza por la línea <?php exit; ?>, seguida de datos JSON. Aunque un servidor ignorara los .htaccess, abrirlo en un navegador no mostraría nada. Las escrituras son atómicas (archivo temporal y luego cambio de nombre) y los archivos son privados.

Las carpetas cache y media

cache/

La caché se vacía sola con cada cambio, y a la hora prevista para un artículo programado. Para vaciarla a mano: Ajustes › Avanzado › Vaciar la caché.

media/

El archivo media/.htaccess solo autoriza imágenes: ni scripts, ni páginas HTML, ni SVG, ni listados de archivos, con una política de seguridad que prohíbe cualquier contenido activo. Las subidas se explican en Imágenes y biblioteca de medios de Éclair.

¿Qué poner en eclair-config.php?

Este archivo opcional se coloca junto a index.php. Copia eclair-config.exemple.php con el nombre eclair-config.php y quita el comentario de lo que necesites. Se lee al arrancar la aplicación, antes que todo lo demás, y el control de integridad no lo señala como archivo desconocido.

<?php
defined('ECLAIR') || exit;

// Detalle de los errores, mientras resuelves un problema:
// define('ECLAIR_DEBUG', true);

// Datos fuera de la carpeta pública (mueve antes la carpeta data):
// define('ECLAIR_DATA', '/home/micuenta/eclair-data');

// Protección reforzada de las claves de API, que se define antes de guardarlas:
// define('ECLAIR_SECRET', 'una-frase-secreta-larga');

El código reconoce también dos constantes técnicas que no aparecen en la guía oficial: ECLAIR_AI_ENDPOINTS (dirección alternativa de un servicio de IA, para una pasarela o para pruebas) y ECLAIR_FONTS_URL (origen de las fuentes, por defecto Fontsource a través de cdn.jsdelivr.net). Úsalas solo si sabes por qué. ECLAIR_VERSION y ECLAIR_ROOT las fija index.php.

Las reglas del .htaccess explicadas

El .htaccess de Éclair funciona tanto en la raíz de un dominio como en una subcarpeta. Solo usa directivas permitidas en los hostings compartidos: nada de Options ni de php_flag. Esta es su parte de reescritura:

RewriteEngine On
# RewriteBase /
RewriteCond %{HTTP:Authorization} .
RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteRule ^(app|data|cache)(/|$) - [R=404,L]
RewriteRule (^|/)\.(?!well-known/) - [R=404,L]
RewriteRule ^(?!index\.php$).*\.(php\d?|phtml|phar|inc)$ - [R=404,NC,L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L,QSA]

1. RewriteBase / sigue comentada: quítale el comentario solo si tu proveedor lo exige, algo poco habitual.
2. Las dos líneas Authorization transmiten a PHP la cabecera de autorización que algunos hostings eliminan. El conector MCP la necesita.
3. app/, data/ y cache/ responden 404 desde la web.
4. Los archivos ocultos (.git, .env…) responden 404, salvo la carpeta .well-known.
5. Ningún script PHP se ejecuta fuera de index.php.
6. Todo lo que no sea un archivo existente pasa por index.php, incluso una carpeta: nunca se muestra un listado de archivos.

El resto del archivo activa la compresión Brotli o Gzip de las páginas HTML, las hojas CSS, el JavaScript, los datos JSON y XML, los feeds RSS, las imágenes SVG y el Markdown, una caché del navegador de un año para las imágenes, los CSS, los scripts y las fuentes (Cache-Control: public, max-age=31536000, immutable), y declara los tipos WebP, AVIF y WOFF2. Las carpetas app/, data/ y cache/ tienen además su propio .htaccess, que deniega cualquier acceso: la protección es doble.

La configuración de Nginx

Nginx ignora los .htaccess: reproduce estas reglas en el bloque server de tu sitio. Es la configuración que da la guía oficial.

location ~ ^/(app|data|cache)(/|$) { return 404; }
location ~ /\.(?!well-known/) { return 404; }
location ^~ /media/ {
    location ~* \.(php\d?|phtml|phar|s?html?|svgz?|xml|js)$ { return 404; }
    add_header X-Content-Type-Options nosniff;
    expires 1y;
}
location ~* \.(webp|avif|jpe?g|png|gif|ico|css|js|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; }
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;
}
location ~ \.php$ { return 404; }

• Las dos primeras reglas cierran las carpetas internas y los archivos ocultos, salvo .well-known.
• El bloque /media/ rechaza scripts, páginas HTML, SVG y XML, y guarda los archivos en caché durante un año.
• try_files envía a index.php todo lo que no sea un archivo existente.
• Solo index.php pasa a PHP-FPM: adapta fastcgi_pass al socket de tu servidor.
• Para que el asistente IA muestre sus respuestas a medida que se generan, añade fastcgi_buffering off; en el bloque PHP.

HTTPS, proxy y CDN se tratan en Nginx, VPS, proxy y CDN.

¿Qué permisos dar a los archivos y carpetas?

• PHP debe poder escribir en data/, cache/ y media/. El asistente de instalación comprueba cada una («Carpeta “data” con permisos de escritura») y, si falla, aconseja dar permisos de escritura (755) por FTP.
• Después, Éclair crea sus archivos de datos con permisos 0600 (solo puede leerlos la cuenta que ejecuta PHP), sus subcarpetas de data/ y de cache/ con 0700, y las de media/ con 0755.
• Evita los permisos 777, que dejan escribir a cualquier cuenta del servidor. Si 755 no basta, pregunta a tu proveedor con qué cuenta se ejecuta PHP.

¿Qué archivos y carpetas incluir en la copia de seguridad?

La copia de seguridad ZIP no contiene ni las claves de API, ni las conversaciones y conexiones MCP, ni las sesiones. Después de restaurarla en otro servidor, vuelve a pegar tus claves de API y conecta de nuevo Claude o ChatGPT. Para restaurar, sustituye data/ y media/ por los de la copia (por FTP) y vacía la caché desde la administración.

El procedimiento de actualización completo está en Seguridad avanzada y mantenimiento.

Las direcciones que genera Éclair

Las direcciones de los contenidos

Las palabras de las direcciones siguen el idioma del sitio: page en francés y en inglés, pagina en español, italiano y portugués, seite en alemán; auteur, autor, author o autore; recherche, buscar, search, suche, cerca o pesquisa; boutique, tienda, shop, negozio o loja.

Una sola dirección por contenido: Éclair redirige con una 301 las variantes en mayúsculas, con barra final, con barras dobles o con index.php, así como http a https cuando HTTPS está forzado, y www o sin www una vez verificada la dirección oficial.

Algunas palabras están reservadas y no pueden usarse como dirección de página: app, data, cache, assets, media, index, admin, _eclair, __eclair, sitemap, robots, feed, llms, llms-full, favicon, wp-admin, wp-login, además de la dirección de tu administración, la del blog, la palabra de la búsqueda y la dirección de la tienda una vez configurada. El SEO de estas direcciones se explica en El SEO con Éclair.