Después de instalar KingCMS la portada abre, pero las páginas internas devuelven 404; o los enlaces antiguos fallan después de cambiar la dirección de una categoría o un artículo. En ambos casos suele faltar la reescritura de URL o una redirección 301. Esta guía explica por qué ocurre, cómo configurar nginx o Apache, cómo funciona el ajuste del panel y por qué las direcciones antiguas redirigen solas.

Las direcciones no son carpetas reales

Una dirección como /news/hello-world es solo una ruta: en el disco no existe esa carpeta. Salvo los archivos reales (/assets/, imágenes), todas las peticiones pasan a x1/public/index.php y la aplicación resuelve el slug hacia una categoría, página, artículo o producto. Por eso la raíz del sitio debe apuntar a x1/public/, no a la raíz del repositorio ni a x1/.

Configuración de nginx

Añade dos bloques al server del sitio: try_files envía las rutas inexistentes a index.php y el bloque location pasa las peticiones PHP a php-fpm.

server {
    listen 80;
    server_name cms.example.com;
    root /var/www/kingcms/x1/public;
    index index.php;
    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }
}

Ajusta el socket de php-fpm según tu versión de PHP. Ejecuta nginx -t antes de recargar.

Configuración de Apache

Activa mod_rewrite (a2enmod rewrite) y permite .htaccess en el directorio del sitio (AllowOverride All). El directorio public/ ya incluye un .htaccess que envía los archivos y carpetas inexistentes a index.php y conserva la cadena de consulta:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]

El ajuste «formato de URL»

En Panel → Ajustes → Información básica hay un ajuste de formato de URL. Las URL amigables (/categoría/artículo) necesitan la configuración del servidor; el modo compatible (/?categoría/artículo&page=2) funciona sin ella. Al cambiar a URL amigables y guardar, la aplicación solicita /healthz para comprobar que la reescritura funciona; si la comprobación falla, el guardado se rechaza y se mantiene el valor anterior. Configura primero el servidor y luego cambia el ajuste.

Redirecciones 301 de direcciones antiguas

Cuando cambia la dirección de una categoría o un artículo, la aplicación conserva automáticamente una redirección 301 de la dirección antigua a la nueva; no hay que escribir reglas a mano. Si un enlace antiguo sigue devolviendo 404, confirma primero que venga de un cambio de nombre; si no, revisa que la reescritura esté activa en el servidor.

Problemas frecuentes

  • La portada funciona y las páginas internas dan 404: en nginx revisa que try_files apunte a /index.php; en Apache revisa mod_rewrite y AllowOverride.
  • La portada también da 404: comprueba que la raíz del sitio apunte a x1/public/ y que index.php exista.
  • Las imágenes no cargan: las imágenes están en x1/data/uploads/, fuera de la raíz del sitio; configura un alias /media/ en nginx y desactiva la ejecución de PHP en esa carpeta.
  • Enlace antiguo 404 tras cambiar el nombre: confirma que la dirección antigua provenga del cambio de nombre; la aplicación añade la 301 automáticamente.

Para la instalación y la preparación del servidor consulta Instalación y entorno; para actualizar, Actualización en línea.