Tutoriais de VPS
Laravel 13 no VPS: Nginx, PHP-FPM, MySQL, filas e backup (2026)
Publique Laravel 13 no Ubuntu 24.04 com PHP 8.3-FPM, Nginx, MySQL e HTTPS; configure permissões, migrações, filas, scheduler, backup externo e rollback.

Ao levar Laravel do ambiente local para um VPS, quatro problemas são comuns: Nginx aponta para a raiz do projeto, .env conecta ao banco errado, storage não permite escrita ou falta um processo permanente para a fila. Reinstalar PHP repetidamente raramente resolve essas causas de erro 500. O roteiro usa Ubuntu 24.04, Laravel 13, PHP 8.3-FPM, Nginx e MySQL em um servidor, com HTTPS, migrações, filas, agendamentos, backup e rollback. O original consultou a documentação em 3 de outubro de 2026; a página oficial também confirma PHP 8.3 ou superior. Confira sempre composer.lock e as extensões exigidas pelo seu projeto.
| Uso | Ponto inicial | Acompanhe |
|---|---|---|
| Site de baixo tráfego com banco no mesmo VPS | 2 vCPU / 4 GB RAM / 40 GB SSD | Workers PHP-FPM, buffer MySQL, logs e backups |
| Importação, processamento de imagens ou várias filas | 4 vCPU / 8 GB RAM / 80 GB SSD | Pico de memória e duração de jobs simultâneos |
São estimativas, não garantias. Teste com requisições reais, tamanho do banco e picos de jobs. Publique apenas SSH de administração e 80/443; MySQL 3306 fica local. Se falta o banco, siga primeiro MySQL 8.4: instalação e backup. Não é necessário expor sua porta à internet.
Os comandos pressupõem Ubuntu 24.04 sem outro serviço web nessas portas. Se existe painel de hospedagem ou configuração Nginx, confira 80/443 e os sites antes de substituir a 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 pelo menos PHP 8.3. Acrescente módulos de imagem, PDF, Redis e outros conforme composer.json. Não esconda dependências ausentes com composer install --ignore-platform-reqs.
Crie um usuário de deploy e mantenha o código em /srv/laravel-app. Substitua YOUR_REPO_URL pelo seu repositório Git. Em repositório privado, prefira chave de deploy somente leitura; evite token pessoal no histórico do shell.
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
Instale composer install com o composer.lock versionado. Se usa Vite, escolha Node.js compatível com package.json, execute npm ci && npm run build e confira public/build nessa versão. Você também pode compilar no CI e publicar os artefatos junto do código. Não improvise npm install no servidor e gere versões de dependência diferentes.
No host do banco, crie banco e conta próprios com senha longa aleatória. O exemplo concede acesso apenas a laravel_app; ambientes mais maduros podem separar conta de execução e conta de migração.
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';
Copie .env.example e edite /srv/laravel-app/.env. São campos essenciais; complete e-mail, armazenamento de objetos e APIs conforme o projeto:
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
Gere APP_KEY apenas na primeira publicação. Gerar outra chave pode impedir descriptografar cookies, sessões e dados. Guarde .env com segurança fora do VPS e do Git. Laravel precisa escrever em storage e bootstrap/cache; não aplique chmod -R 777 ao projeto inteiro. Para uploads locais, execute sudo -u deploy php artisan storage:link e inclua storage/app/public nos backups.
Confira migrações para fila, cache e sessão antes de migrar o banco. Projetos novos normalmente incluem essas tabelas; antigos podem precisar gerar migrações conforme a versão. Revise os arquivos:
cd /srv/laravel-app
ls database/migrations
sudo -u deploy php artisan migrate --force
sudo -u deploy php artisan optimize
optimize armazena configuração, rotas e views em cache. Execute novamente ao mudar .env. Use env() apenas em arquivos de configuração: fora deles, o cache pode fazer valores desaparecerem. Faça backup antes de migrações produtivas; nem todas permitem reversão simples.
Aponte o registro A de app.example.com ao VPS e grave o site em /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 deve apontar para public, nunca /srv/laravel-app. Caso contrário, .env, código e dependências podem ficar públicos. Antes do certificado, confira DNS e firewalls da nuvem/host para 80/443. A rota /up confirma inicialização do Laravel; crie verificações específicas de MySQL/cache. Um 200 em /up não valida toda a aplicação.
Definir QUEUE_CONNECTION=database não inicia consumo de jobs. Para e-mails, uploads ou tarefas assíncronas, configure worker permanente em /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 deve ser menor que retry_after para reduzir execução duplicada. Jobs longos exigem ajustar ambos e stopwaitsecs no Supervisor. Workers mantêm código em memória: em cada deploy use php artisan reload ou queue:restart, deixando o Supervisor reiniciá-los.
O scheduler precisa de uma chamada por minuto. Como usuário de deploy, abra crontab -e e adicione:
* * * * * cd /srv/laravel-app && /usr/bin/php artisan schedule:run >> /srv/laravel-app/storage/logs/scheduler.log 2>&1
Confira sudo -u deploy crontab -l e sudo -u deploy php artisan schedule:list. Sem tarefas agendadas, você pode pular isso. Configure rotação de logs; veja logrotate no VPS.
Anote o commit anterior e o backup do banco antes de publicar. Esta sequência de servidor único exige janela de manutenção; não repita key:generate numa atualização:
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
Faça backup de pelo menos três componentes: banco consistente, .env/APP_KEY criptografados e uploads. Confira o cliente com mysqldump --version; para MySQL 8.4 em contêiner separado, prefira cliente compatível nesse contêiner. Guarde os parâmetros MySQL [client] de uma conta de backup em /home/deploy/.my.cnf, com modo chmod 600. Não passe senha como argumento. O arquivo deve conectar 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
Sem uploads locais, omita o último comando. Copie arquivos e .env criptografado para outra máquina ou armazenamento de objetos: o mesmo disco não é backup externo. Periodicamente restaure com gunzip -c 数据库备份.sql.gz | mysql --defaults-extra-file=测试库凭据.cnf 测试库名 num banco de teste isolado, recupere uploads e valide páginas importantes. Nunca ensaie no banco de produção. Veja backup automático para retenção.
Para rollback, volte ao commit testado, instale dependências travadas e recursos, otimize configuração e recarregue workers. Rollback de código não reverte banco. Migrações destrutivas exigem compatibilidade planejada ou restauração consistente de dados e arquivos. Não execute migrate:rollback por impulso: isso pode reverter outras migrações ou perder dados.
| Sintoma | Confira primeiro | Causas comuns |
|---|---|---|
| 500 | storage/logs/laravel.log, journalctl -u php8.3-fpm | .env, APP_KEY, conexão, permissões ou extensões |
| 502 Bad Gateway | nginx -t, status FPM e error log Nginx | FPM parado, socket errado ou workers esgotados |
| Página sem estilo | public/build e requisições do navegador | Artefatos Vite ausentes |
| E-mails/jobs parados | supervisorctl status, queue:failed | Worker ausente, conexão diferente ou jobs falhos |
| Agendamentos não executam | Crontab, schedule:list, scheduler.log | Usuário/fuso errado ou falha da tarefa |
.env não muda nada | php artisan about e cache | Falta repetir optimize ou env() está fora da configuração |
Referências: deploy Laravel 13, filas e Supervisor e scheduler. Antes de trocar DNS, teste num domínio de ensaio migrações, HTTPS, consumo de fila, restauração e rollback de código.