Tutoriales de VPS
Laravel 13 en VPS: Nginx, PHP-FPM, MySQL, colas y copias (2026)
Despliega Laravel 13 en Ubuntu 24.04 con PHP 8.3-FPM, Nginx, MySQL y HTTPS; configura permisos, migraciones, colas, scheduler, copias externas y reversión.

Al llevar Laravel de tu ordenador a un VPS, los fallos suelen concentrarse en cuatro puntos: Nginx sirve la raíz del proyecto, .env apunta a otra base, storage no admite escritura o nadie consume la cola. Reinstalar PHP repetidamente rara vez resuelve esas causas de un error 500. Esta guía usa Ubuntu 24.04, Laravel 13, PHP 8.3-FPM, Nginx y MySQL en un servidor, con HTTPS, migraciones, colas, tareas programadas, copias y reversión. El original contrastó la documentación el 3 de octubre de 2026; la guía oficial también confirma PHP 8.3 o superior. Las dependencias de composer.lock y las extensiones de tu proyecto siguen siendo la referencia.
| Uso | Punto de partida | Vigila |
|---|---|---|
| Web con poco tráfico y base en el mismo VPS | 2 vCPU / 4 GB RAM / 40 GB SSD | Workers PHP-FPM, búfer MySQL, registros y copias |
| Importaciones, imágenes o varias colas | 4 vCPU / 8 GB RAM / 80 GB SSD | Memoria máxima y duración de trabajos concurrentes |
Son estimaciones, no garantías. Prueba capacidad con peticiones reales, tamaño de base y picos de trabajos. Abre únicamente SSH de administración y 80/443; MySQL 3306 debe escuchar localmente. Si falta la base, prepara primero MySQL 8.4 y sus copias. No necesitas publicar su puerto.
Los comandos suponen un Ubuntu 24.04 sin otro servicio web ocupando esos puertos. Con un panel de alojamiento o sitios Nginx existentes, revisa 80/443 y la configuración antes de sustituir su entrada.
sudo apt update
sudo apt install -y nginx git unzip composer supervisor certbot python3-certbot-nginx mysql-client \
php8.3-fpm php8.3-cli php8.3-mysql php8.3-mbstring php8.3-xml \
php8.3-curl php8.3-zip php8.3-bcmath php8.3-intl php8.3-gd
php -v
composer --version
php -m | grep -E 'mbstring|pdo_mysql|xml|curl'
systemctl status php8.3-fpm --no-pager
Laravel 13 exige PHP 8.3 como mínimo. Añade módulos para imágenes, PDF, Redis u otras funciones según composer.json. No ocultes extensiones ausentes con composer install --ignore-platform-reqs.
Crea un usuario de despliegue y guarda el código en /srv/laravel-app. Sustituye YOUR_REPO_URL por tu repositorio Git existente. En repositorios privados, usa preferiblemente una clave de despliegue de solo lectura; evita tokens personales en el historial.
sudo adduser --disabled-password --gecos '' deploy
sudo install -d -o deploy -g www-data -m 2750 /srv/laravel-app
sudo -u deploy git clone YOUR_REPO_URL /srv/laravel-app
cd /srv/laravel-app
sudo -u deploy composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
Instala composer install según el composer.lock versionado. Si usas Vite, el Node.js debe satisfacer package.json: ejecuta npm ci && npm run build y comprueba public/build en esta versión. También puedes compilar en CI y desplegar los recursos junto al código. Ejecutar npm install improvisadamente puede producir dependencias irreproducibles.
En el servidor de base de datos, crea una base y una cuenta propias con contraseña larga aleatoria. El ejemplo limita acceso a laravel_app; puedes separar después la cuenta de ejecución de la de migraciones.
CREATE DATABASE laravel_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'laravel_app'@'127.0.0.1' IDENTIFIED BY 'REPLACE_WITH_LONG_RANDOM_PASSWORD';
GRANT ALL PRIVILEGES ON laravel_app.* TO 'laravel_app'@'127.0.0.1';
Copia .env.example y edita /srv/laravel-app/.env. Estos campos son básicos; completa correo, almacenamiento de objetos y APIs según el proyecto:
APP_NAME=MyLaravelApp
APP_ENV=production
APP_DEBUG=false
APP_URL=https://app.example.com
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_app
DB_PASSWORD=REPLACE_WITH_LONG_RANDOM_PASSWORD
QUEUE_CONNECTION=database
CACHE_STORE=database
SESSION_DRIVER=database
cd /srv/laravel-app
sudo -u deploy cp .env.example .env
# 用编辑器填入上面的生产配置后,再执行以下命令
sudo chown -R deploy:www-data /srv/laravel-app
sudo find storage bootstrap/cache -type d -exec chmod 2775 {} \;
sudo find storage bootstrap/cache -type f -exec chmod 664 {} \;
sudo chmod 640 .env
sudo -u deploy php artisan key:generate
Genera APP_KEY solo en el primer despliegue. Regenerarla puede impedir descifrar cookies, sesiones y datos. Conserva .env de forma segura fuera del VPS y de Git. Laravel necesita escribir en storage y bootstrap/cache; evita chmod -R 777 para todo el proyecto. Para archivos subidos locales, ejecuta sudo -u deploy php artisan storage:link e incluye storage/app/public en las copias.
Revisa las migraciones de cola, caché y sesiones antes de migrar. Los proyectos nuevos suelen incluir esas tablas; los antiguos pueden necesitar generar migraciones según su versión. Comprueba los archivos:
cd /srv/laravel-app
ls database/migrations
sudo -u deploy php artisan migrate --force
sudo -u deploy php artisan optimize
optimize almacena configuración, rutas y vistas en caché. Repítelo al cambiar .env. Usa env() únicamente en archivos de configuración: con caché, el código externo puede recibir valores vacíos. Haz copia de la base antes de migrar producción; algunas migraciones no se deshacen fácilmente.
Dirige el registro A de app.example.com al VPS y escribe el sitio en /etc/nginx/sites-available/laravel-app:
server {
listen 80;
server_name app.example.com;
root /srv/laravel-app/public;
index index.php;
charset utf-8;
add_header X-Content-Type-Options nosniff;
add_header X-Frame-Options SAMEORIGIN;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ ^/index\.php(/|$) {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ \.php$ { return 404; }
location ~ /\.(?!well-known).* { deny all; }
}
sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/laravel-app
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d app.example.com
curl -I https://app.example.com/up
sudo certbot renew --dry-run
root debe ser public, nunca /srv/laravel-app. De lo contrario expones .env, código y dependencias. Antes del certificado, comprueba DNS y firewalls de nube/host para 80/443. La ruta de salud /up indica que arrancó Laravel; añade verificaciones específicas de MySQL/caché. Un 200 en /up no acredita todo el negocio.
Configurar QUEUE_CONNECTION=database no consume trabajos. Para correo, cargas o tareas asíncronas, crea un worker persistente en /etc/supervisor/conf.d/laravel-worker.conf:
[program:laravel-worker]
command=/usr/bin/php /srv/laravel-app/artisan queue:work database --sleep=3 --tries=3 --timeout=60 --max-time=3600
directory=/srv/laravel-app
user=deploy
numprocs=1
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stopwaitsecs=120
redirect_stderr=true
stdout_logfile=/srv/laravel-app/storage/logs/worker.log
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status laravel-worker
cd /srv/laravel-app
sudo -u deploy php artisan queue:failed
--timeout=60 debe ser menor que retry_after para reducir ejecuciones duplicadas. En trabajos largos, ajusta ambos valores y stopwaitsecs de Supervisor. Los workers conservan código en memoria: tras cada publicación usa php artisan reload o queue:restart y deja que Supervisor los reinicie.
El scheduler necesita un disparo cada minuto. Como usuario de despliegue, abre crontab -e y añade:
* * * * * cd /srv/laravel-app && /usr/bin/php artisan schedule:run >> /srv/laravel-app/storage/logs/scheduler.log 2>&1
Comprueba sudo -u deploy crontab -l y sudo -u deploy php artisan schedule:list. Si no hay tareas programadas puedes omitirlo. Rota los registros que crecen; consulta logrotate en VPS.
Anota el commit anterior y la copia de base antes de publicar. Esta secuencia de servidor único requiere ventana de mantenimiento; no vuelvas a ejecutar key:generate en una actualización:
cd /srv/laravel-app
git rev-parse HEAD # 记下旧版本
sudo -u deploy php artisan down
sudo -u deploy git fetch --tags
sudo -u deploy git switch --detach YOUR_TESTED_COMMIT_SHA
sudo -u deploy composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
# 若前端资源在服务器构建:以项目要求的 Node.js 版本执行 npm ci && npm run build
sudo -u deploy php artisan migrate --force
sudo -u deploy php artisan optimize
sudo -u deploy php artisan reload
sudo systemctl reload php8.3-fpm
sudo -u deploy php artisan up
curl -fsS https://app.example.com/up
Copia al menos la base consistente, .env/APP_KEY cifrados y los archivos subidos. Comprueba cliente con mysqldump --version; si MySQL 8.4 está en otro contenedor, prefiere su cliente compatible. Guarda en /home/deploy/.my.cnf parámetros MySQL [client] de una cuenta de copia, con permisos chmod 600. No pongas contraseñas en argumentos. Se supone que ese archivo conecta a laravel_app:
sudo install -d -o deploy -g deploy -m 700 /var/backups/laravel
sudo -u deploy bash -c 'set -o pipefail; mysqldump --defaults-extra-file=/home/deploy/.my.cnf --single-transaction --routines --triggers --events laravel_app | gzip > /var/backups/laravel/db-$(date +%F-%H%M).sql.gz'
sudo -u deploy tar -C /srv/laravel-app -czf /var/backups/laravel/uploads-$(date +%F-%H%M).tgz storage/app/public
Omite el último comando si no hay cargas locales. Lleva los archivos y .env cifrado a otra máquina o almacenamiento de objetos: el mismo disco no es una copia externa. Restaura periódicamente con gunzip -c 数据库备份.sql.gz | mysql --defaults-extra-file=测试库凭据.cnf 测试库名 en una base de pruebas aislada, recupera cargas y valida páginas clave. Nunca practiques sobre la base productiva. Consulta copias automáticas para retención.
Para revertir, vuelve al commit probado, instala sus dependencias bloqueadas y recursos, optimiza configuración y recarga workers. Revertir código no revierte la base. Las migraciones destructivas necesitan compatibilidad previa o restaurar datos y archivos consistentes. No ejecutes migrate:rollback sin analizarlo: puede revertir otras migraciones o perder datos.
| Síntoma | Mira primero | Causas frecuentes |
|---|---|---|
| 500 | storage/logs/laravel.log, journalctl -u php8.3-fpm | .env, APP_KEY, conexión, permisos o extensiones |
| 502 Bad Gateway | nginx -t, estado FPM y error log Nginx | FPM parado, socket incorrecto o workers agotados |
| Sin estilos | public/build y red del navegador | Recursos Vite ausentes |
| Correo/trabajos pendientes | supervisorctl status, queue:failed | Worker ausente, conexión distinta o trabajos fallidos |
| Tareas no ejecutadas | Crontab, schedule:list, scheduler.log | Usuario/zona horaria incorrectos o fallo propio |
.env no cambia nada | php artisan about y caché | Falta repetir optimize o se llama env() fuera de configuración |
Referencias: despliegue Laravel 13, colas y Supervisor y scheduler. Antes de cambiar DNS, prueba en un dominio de ensayo migraciones, HTTPS, consumo de cola, restauración y reversión de código.