KingCMS X1 安装与更新文档

Esta página explica la instalación de KingCMS X1.0.0-alpha, la primera visita, las actualizaciones en línea, las copias de seguridad y las tareas programadas. La raíz del sitio debe apuntar al directorio public/ del paquete. La base de datos se crea automáticamente en la primera visita; no hay un instalador por pasos.

1. Requisitos

PHP 8.2 o superior. Los ejemplos usan PHP 8.4 de Debian 13.
Extensiones PHP: pdo_sqlite, sqlite3, sodium, mbstring, intl, curl, gd, xml, ctype, json, openssl. Las imágenes necesitan gd, las copias en línea sqlite3 y las copias con archivos subidos la extensión zip.
SQLite 3 (la línea de comandos sqlite3 se usa para copias manuales).
nginx (mostrado aquí) o Apache, con PHP a través de PHP-FPM.
Un directorio data/ escribible. Allí viven la base SQLite, app.key, la caché y las subidas.

app/ y data/ deben quedar fuera de la raíz del sitio y no ser accesibles desde el navegador. Solo public/ es la raíz.

2. Descarga y verificación

Página de descarga: https://download.kingcms.com/. Versión actual X1.0.0-alpha (publicada el 2026-10-20), unos 16,4 MB, firmada.

wget https://update.kingcms.com/stable/kingcms-x1-X1.0.0-alpha.zip
sha256sum kingcms-x1-X1.0.0-alpha.zip

La suma debe ser:

278bdb5d4a1cb1ca480b7e0802cc8773d69664f58194eb72ee59546a29490767

Si no coincide, no lo despliegue; descárguelo de nuevo.

3. Instalar paquetes

sudo apt update
sudo apt install -y \
  nginx \
  php8.4-fpm php8.4-cli php8.4-sqlite3 php8.4-mbstring \
  php8.4-intl php8.4-curl php8.4-gd php8.4-xml \
  sqlite3

sodium viene en el paquete common de PHP 8.4.

Comprobar extensiones

for ext in pdo_sqlite sqlite3 sodium mbstring intl curl gd xml ctype json openssl; do
  php -r 'exit(extension_loaded($argv[1]) ? 0 : 1);' "$ext" \
    || echo "falta la extensión: $ext"
done

Sin salida, todas están presentes. Si instaló extensiones después, reinicie PHP-FPM:

sudo systemctl restart php8.4-fpm

4. Subir y descomprimir

sudo mkdir -p /var/www/kingcms
sudo unzip kingcms-x1-X1.0.0-alpha.zip -d /var/www/kingcms

El paquete contiene app/, bin/, modules/, public/, resources/, themes/ y vendor/. Las dependencias están incluidas, no hace falta composer install.

Apunte la raíz del sitio a /var/www/kingcms/public, no a /var/www/kingcms ni a app/.

Se recomienda activar OPcache:

opcache.enable=1
opcache.memory_consumption=128
opcache.validate_timestamps=1

5. Permisos de directorio

cd /var/www/kingcms
sudo mkdir -p data/uploads data/cache
sudo chown -R www-data:www-data data
sudo find data -type d -exec chmod 750 {} \;
sudo find data -type f -exec chmod 640 {} \;

En la primera visita se crea data/app.key con permisos 0600. Confirme:

sudo chmod 600 /var/www/kingcms/data/app.key
sudo ls -l /var/www/kingcms/data/app.key

app.key cifra los ajustes secretos. No lo borre ni lo reemplace; sin él los valores cifrados no se pueden recuperar.

6. nginx

Coloque la zona de límite en /etc/nginx/conf.d/kingcms-limit.conf (limit_req_zone solo es válido en el contexto http):

limit_req_zone $binary_remote_addr zone=kingcms:10m rate=10r/s;

Configuración del sitio /etc/nginx/sites-available/kingcms:

server {
    listen 80;
    server_name cms.example.com;

    root /var/www/kingcms/public;
    index index.php;

    client_max_body_size 20m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location /media/ {
        alias /var/www/kingcms/data/uploads/;
        add_header Cache-Control "public, max-age=2592000";

        location ~ \.php$ {
            return 404;
        }

        location ~ /\. {
            deny all;
        }
    }

    location ~ /\.(?!well-known) {
        deny all;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        limit_req zone=kingcms burst=20 nodelay;
    }
}

sudo ln -s /etc/nginx/sites-available/kingcms /etc/nginx/sites-enabled/kingcms
sudo nginx -t
sudo systemctl reload nginx

Configure HTTPS antes de publicar. Las devoluciones de WeChat/Alipay y las cookies Secure lo requieren.

Límites de subida de PHP

upload_max_filesize = 20M
post_max_size = 20M

Deben ser iguales o mayores que client_max_body_size de nginx; luego reinicie PHP-FPM.

7. Reescritura en Apache

Active mod_rewrite (a2enmod rewrite y reinicie Apache) y permita .htaccess (AllowOverride All).

<VirtualHost *:80>
    ServerName cms.example.com
    DocumentRoot /var/www/kingcms/public

    <Directory /var/www/kingcms/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

El .htaccess incluido en public/ envía archivos y directorios inexistentes a index.php, conservando la cadena de consulta:

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

8. Base de datos en la primera visita

Abra el sitio en el navegador. Si data/kingcms.sqlite no existe, el programa crea la base SQLite, ejecuta las migraciones del núcleo y de los módulos, escribe los ajustes por defecto y genera data/app.key. No hay que importar SQL.

9. Crear el administrador

Mientras no exista un administrador, todas las páginas redirigen a /admin/setup (excepto /assets/ y /healthz). El formulario único pide:

nombre de usuario (obligatorio, hasta 64 caracteres);
contraseña (mínimo 8 caracteres);
confirmación de contraseña;
opcionalmente, crear contenido de ejemplo;
aceptación del acuerdo de licencia.

Tras crearlo, inicia sesión y redirige a /admin; /admin/setup devuelve 404 de forma permanente. El acceso es /admin/login. Para restablecer la contraseña:

cd /var/www/kingcms
sudo -u www-data php bin/kingcms admin:reset-password

10. Actualizaciones en línea

Las actualizaciones en línea están disponibles. La página de actualización del panel lee https://update.kingcms.com/stable/latest.json, la compara con la versión instalada y muestra notas y sumas de verificación.

Haga copia de la base de datos y de app.key primero.
La actualización reemplaza los archivos del programa y conserva data/.
Con OPcache y validate_timestamps=0, recargue PHP-FPM después.
También puede descargar el paquete nuevo, verificarlo como en la sección 2 y sobrescribir los archivos, conservando data/.

11. Copias de seguridad

Copie juntos la base SQLite y app.key.

sudo install -d -m 700 /var/backups/kingcms
sudo sqlite3 /var/www/kingcms/data/kingcms.sqlite \
  ".backup '/var/backups/kingcms/kingcms-$(date +%F).sqlite'"
sudo install -m 600 /var/www/kingcms/data/app.key \
  /var/backups/kingcms/app.key

Use sqlite3 .backup en lugar de copiar un .sqlite en uso. La página de copias del panel también permite copiar, descargar, borrar y restaurar, y programar copias diarias o semanales.

Nota: para respaldar un sitio en funcionamiento, use la función de copias del panel o sqlite3 .backup en lugar de copiar el archivo de base de datos en uso; respalde la base de datos junto con app.key.

12. cron

php bin/kingcms cron:run ejecuta los ganchos por minuto de los módulos activos y las tareas pendientes (liberar reservas de stock, avisos ntfy, resúmenes de estadísticas). Añada a /etc/cron.d/kingcms:

SHELL=/bin/sh
PATH=/usr/local/bin:/usr/bin:/bin
* * * * * www-data /usr/bin/php /var/www/kingcms/bin/kingcms cron:run >/dev/null 2>&1

13. Prueba local rápida

php -S 127.0.0.1:8080 -t public public/index.php

Abra http://127.0.0.1:8080. La primera visita crea data/, data/kingcms.sqlite y data/app.key, y redirige a /admin/setup. El servidor integrado es solo para pruebas locales, no para producción.

14. Preguntas frecuentes

La portada funciona, las páginas internas dan 404. La reescritura no está activa. En nginx revise try_files ... /index.php?$query_string; en Apache, mod_rewrite y AllowOverride All.

La portada también da 404. Compruebe que la raíz apunta a public/ y que existe public/index.php.

Las imágenes subidas no cargan. Están en data/uploads/, fuera de la raíz; configure el alias /media/ y desactive PHP allí.

Las URL antiguas fallan tras renombrar. El programa guarda redirecciones 301 automáticamente.

15. Licencia

Eliminar el enlace Powered by KingCMS del front-end requiere una licencia; consulte Precios y licencias.