Laravel 12部署在香港服务器上,生产环境如何配置进程与日志?

发布人:A5数据发布时间:2026-10-13 17:19阅读量:124

香港服务器上的 Laravel 12 生产环境,建议采用“域名解析 → Nginx TLS 终止 → PHP-FPM → Laravel 应用 → 数据库/队列”的链路,避免直接使用 php artisan serve 对外提供服务。进程层面重点管理 PHP-FPM、队列 Worker 和定时任务,日志层面同时覆盖 Laravel、Nginx、PHP-FPM 与 systemd,另外还要明确证书续期、数据库备份和磁盘内存边界。

下面以 Ubuntu 24.04 LTS、PHP 8.3、Nginx、MySQL/MariaDB、systemd 和单台香港云服务器为例。示例域名使用 example.com,应用目录使用 /var/www/laravel。如果实际系统是 Debian、Rocky Linux、AlmaLinux 或 PHP 8.2,服务名、包名和 PHP-FPM Socket 路径需要先核验,不要直接照搬。

面向 Laravel 12 这类需要同时运行 Nginx、PHP-FPM、数据库、队列和定时任务的生产应用,A5数据提供中国香港物理服务器资源,覆盖 Xeon Gold、AMD EPYC 等平台,并配备 SSD 或 NVMe 存储及不同内存配置,可承载网站、业务后台、接口服务和多任务运行。香港产品还提供 CN2 与国际带宽选择,存储系列则适合文件、日志及备份归档等数据场景,为应用部署、进程管理和分层日志留出相应的硬件与网络基础。

一、部署前确定边界

1. 适用环境和推荐拓扑

本方案适合以下场景:

  • Laravel 12 以传统 PHP-FPM 模式运行;
  • Nginx 负责静态文件、HTTPS 和请求转发;
  • 队列任务由 Laravel Queue Worker 处理;
  • 定时任务由 systemd timer 每分钟触发;
  • 数据库可以与应用部署在同一台服务器,也可以使用独立数据库;
  • 服务器具备公网 IPv4,域名可以解析到香港服务器;
  • 应用代码通过 Git、CI 构建产物或受控压缩包发布。

生产环境的请求流向如下:

一、部署前确定边界 / 1. 适用环境和推荐拓扑配图

客户端
  ↓ HTTPS 443
Nginx
  ├─ 静态文件:/var/www/laravel/current/public
  └─ PHP 请求:Unix Socket → PHP-FPM
                         ↓
                      Laravel 12
                         ├─ 数据库
                         ├─ 队列驱动
                         └─ 文件存储

Nginx 并不直接执行 Laravel 文件,而是将 PHP 请求交给 PHP-FPM。队列 Worker 和定时任务则是独立进程,不能只配置 Nginx 和 PHP-FPM 后就认为应用已经完整运行。

2. 上线前检查清单

建议至少准备以下信息:

检查项示例值或要求验证方式
操作系统Ubuntu 24.04 LTScat /etc/os-release
PHP8.3,Laravel 12 要求不低于 8.2php -v
域名example.com、www.example.comDNS 查询
应用入口/var/www/laravel/current/public检查 Nginx root
数据库MySQL 或 MariaDBLaravel 连接测试
队列驱动database、Redis 等,以项目配置为准检查 .env
SSH已使用普通运维用户并具备 sudo 权限新终端登录验证
备份数据库、上传文件、环境配置恢复测试或备份文件检查
证书域名已经解析,80 端口可访问curl -I http://example.com

如果服务器只有 2 vCPU、4 GB 内存,通常适合轻量应用或中小流量场景,但 PHP-FPM、数据库、队列和日志会共同消耗资源。不要把示例中的进程数量直接当作固定标准,后续应根据内存占用和请求延迟调整。

3. 先确认系统和公网访问

cat /etc/os-release
uname -a
free -h
df -h
timedatectl
sudo ss -lntp

预期能够看到 Ubuntu 版本、内存、磁盘和当前监听端口。如果已经有其他服务占用 80 或 443 端口,应先确认其用途,不能直接停止。

香港服务器通常需要同时检查 DNS 和云平台安全组。若配置了 AAAA 记录,必须确认服务器和安全组确实支持 IPv6,否则部分客户端可能优先访问 IPv6 而连接失败。

dig +short A example.com
dig +short AAAA example.com
curl -I http://服务器公网IP

如果域名还未解析,可以先用服务器 IP 验证 Nginx,但证书申请仍要求域名能够正确指向服务器。

二、安装运行时并设置基础权限

1. 安装 Nginx、PHP-FPM 和常用扩展

以下命令适用于 Ubuntu 24.04 默认 PHP 8.3 软件包名称:

sudo apt update

sudo apt install -y \
  nginx \
  php8.3-cli \
  php8.3-fpm \
  php8.3-mysql \
  php8.3-mbstring \
  php8.3-xml \
  php8.3-curl \
  php8.3-zip \
  php8.3-bcmath \
  php8.3-intl \
  php8.3-gd \
  php8.3-opcache \
  git \
  unzip \
  curl \
  rsync \
  mariadb-client

如果项目使用 PostgreSQL,需要将 php8.3-mysql 换成或补充 php8.3-pgsql。如果项目使用 Redis、Imagick 或其他扩展,应以项目的 composer.json 和部署文档为准。

检查 PHP、Composer 和扩展:

php -v
php -m | grep -E 'mbstring|openssl|pdo|xml|curl|zip|bcmath|intl|opcache'
composer --version

Laravel 12 项目应同时检查锁定的 PHP 版本和扩展要求:

composer check-platform-reqs

如果提示缺少扩展,不要先使用 --ignore-platform-reqs 绕过。绕过检查可能导致构建通过,但运行时在文件上传、数据库连接、加密或队列处理阶段失败。

启动服务:

sudo systemctl enable --now nginx
sudo systemctl enable --now php8.3-fpm

systemctl is-active nginx
systemctl is-active php8.3-fpm

预期输出为:

active
active

2. 配置部署用户和目录

不建议使用 root 用户执行 Composer、Git 和 Laravel Artisan。创建专门的部署用户:

sudo adduser --disabled-password --gecos "" deploy
sudo usermod -aG www-data deploy

如果系统已经存在部署用户,应先确认:

id deploy

创建发布目录和共享目录:

sudo install -d -o deploy -g www-data -m 0755 /var/www/laravel
sudo install -d -o deploy -g www-data -m 0755 /var/www/laravel/releases
sudo install -d -o deploy -g www-data -m 0755 /var/www/laravel/shared
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/app
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/app/public
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/framework
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/framework/cache
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/framework/sessions
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/framework/views
sudo install -d -o www-data -g www-data -m 0775 /var/www/laravel/shared/storage/logs
sudo install -d -o deploy -g www-data -m 0775 /var/www/laravel/shared/bootstrap-cache

检查权限:

namei -l /var/www/laravel/shared/storage/logs

预期是 deploy 可以进入发布目录,www-data 可以写入 storage 和缓存目录。不要对整个 /var/www 执行 chmod -R 777,这会扩大应用被写入和篡改的范围。

3. 配置防火墙

如果使用 UFW,先放行 SSH,再放行 HTTP 和 HTTPS:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw status verbose

如果 SSH 使用自定义端口,应先放行实际端口,例如:

sudo ufw allow 2222/tcp

确认新规则生效、当前 SSH 连接仍然可用后,再启用 UFW:

sudo ufw enable

防火墙调整有锁死远程连接的风险。执行前必须确认云平台安全组和操作系统防火墙至少有一条有效的 SSH 放行规则,回滚方式是通过云厂商控制台或带外终端删除错误规则。

三、按发布目录部署 Laravel 12

1. 使用发布目录而不是直接覆盖当前代码

生产环境不建议把代码直接解压到正在运行的目录。推荐保留多个版本:

文件系统对象示意图,左侧为“/var/www/laravel”,其中“current”用明显的符号链接箭头指向“releases/20250101-120000

/var/www/laravel/
├── current -> releases/20250101-120000
├── releases/
│   ├── 20250101-120000
│   └── 20241228-093000
└── shared/
    ├── .env
    └── storage/

下面以已经准备好的构建目录 /srv/build/ 为例。该目录应来自经过测试的构建产物,不要将包含 .env 和生产密钥的本地目录直接提交到代码仓库。

release="$(date +%Y%m%d-%H%M%S)"
release_dir="/var/www/laravel/releases/${release}"

sudo install -d -o deploy -g www-data -m 0755 "$release_dir"

sudo -u deploy rsync -a \
  --exclude='.env' \
  --exclude='storage' \
  /srv/build/ "$release_dir/"

rsync --exclude 的作用是避免覆盖生产环境配置和共享上传文件。如果使用 --delete,必须确认源目录是正确的构建目录,因为它会删除目标目录中源目录不存在的文件。

链接环境配置和共享存储:

sudo ln -s /var/www/laravel/shared/.env "$release_dir/.env"
sudo ln -s /var/www/laravel/shared/storage "$release_dir/storage"
sudo ln -s /var/www/laravel/shared/bootstrap-cache "$release_dir/bootstrap/cache"

如果目标路径已经存在,先确认它不是有效文件或目录,再处理。不要对未知路径直接执行 rm -rf。

安装生产依赖:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  composer install \
    --no-dev \
    --prefer-dist \
    --no-interaction \
    --optimize-autoloader
"

检查代码和链接:

readlink -f "$release_dir/.env"
readlink -f "$release_dir/storage"
test -f "$release_dir/artisan" && echo "artisan exists"

预期能够看到 .env 指向 shared/.env,storage 指向共享目录,并且存在 artisan 文件。

2. 编写生产环境变量

创建或编辑共享配置文件:

sudo -u deploy nano /var/www/laravel/shared/.env

示例配置如下,数据库密码、应用密钥和域名必须替换为实际值:

APP_NAME="Laravel App"
APP_ENV=production
APP_KEY=base64:replace-with-existing-production-key
APP_DEBUG=false
APP_URL=https://example.com
APP_TIMEZONE=Asia/Hong_Kong

LOG_CHANNEL=daily
LOG_LEVEL=info
LOG_DAILY_DAYS=14

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=appdb
DB_USERNAME=appuser
DB_PASSWORD=replace-with-strong-password

QUEUE_CONNECTION=database
SESSION_DRIVER=file
CACHE_STORE=file

FILESYSTEM_DISK=public

如果项目实际使用 Redis、数据库 Session 或其他缓存驱动,应保留项目已经验证过的配置,不要为了套用示例随意修改驱动。

特别注意以下事项:

  • APP_DEBUG 生产环境必须为 false;
  • 已经运行过的应用不要重新执行 php artisan key:generate,更换 APP_KEY 可能导致历史加密数据、Cookie 或 Session 无法解密;
  • APP_URL 应使用正式 HTTPS 域名;
  • LOG_DAILY_DAYS 只是 Laravel 日志保留天数,不等于数据库备份保留天数;
  • .env 不应出现在 Git 仓库、Web 根目录或公开下载目录。

设置环境文件权限:

sudo chown deploy:www-data /var/www/laravel/shared/.env
sudo chmod 640 /var/www/laravel/shared/.env

3. 检查数据库和迁移

先验证 Laravel 能够读取配置并连接数据库:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  php artisan about
"

检查迁移状态:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  php artisan migrate:status
"

如果提示数据库连接失败,应检查以下项目:

sudo ss -lntp | grep 3306
getent hosts DB_HOST值

数据库连接错误通常来自主机地址、端口、账户权限、防火墙或密码,而不是 Laravel 本身。

首次上线或已完成数据库备份后,可以执行:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  php artisan migrate --force
"

migrate --force 会在生产环境执行数据库结构变更,必须先确认:

  • 已完成数据库备份;
  • 迁移文件已经在测试环境执行;
  • 迁移不会长时间锁表;
  • 旧版本代码仍能兼容新增字段或索引。

不建议在一次发布中直接删除旧字段、重命名正在使用的字段或大批量改写数据。更稳妥的做法是先添加兼容结构,再发布代码,最后在确认无旧版本进程后清理旧结构。

4. 生成缓存并切换版本

在正式切换前清理旧缓存并重新生成生产缓存:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  php artisan optimize:clear &&
  php artisan config:cache &&
  php artisan route:cache &&
  php artisan view:cache
"

如果 route:cache 报错,通常是路由中存在闭包或不可缓存的定义,应修复代码后再发布,不要跳过错误继续切换。

首次使用公开文件存储时,可执行:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  php artisan storage:link
"

切换前检查新版本:

sudo -u deploy bash -lc "
  cd '$release_dir' &&
  php artisan about
"

确认没有报错后,再切换 current:

sudo ln -sfn "$release_dir" /var/www/laravel/current
readlink -f /var/www/laravel/current

ln -sfn 只适合目标是符号链接的场景。执行前应确认 /var/www/laravel/current 不是一个包含业务文件的真实目录。

四、配置 Nginx 反向代理和 PHP-FPM

1. 创建初始 HTTP 配置

先使用 HTTP 配置完成站点和证书验证:

sudo nano /etc/nginx/sites-available/laravel.conf

示例配置:

server {
    listen 80;
    listen [::]:80;

    server_name example.com www.example.com;

    root /var/www/laravel/current/public;
    index index.php index.html;

    client_max_body_size 20m;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/letsencrypt;
        default_type text/plain;
    }

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

    location ~ \.php$ {
        try_files $uri =404;

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_param HTTP_PROXY "";

        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_read_timeout 120s;
    }

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

    location ~* \.(?:css|js|jpg|jpeg|png|gif|svg|ico|webp|woff|woff2)$ {
        try_files $uri =404;
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
    }

    access_log /var/log/nginx/laravel_access.log;
    error_log  /var/log/nginx/laravel_error.log warn;
}

创建 ACME 验证目录并启用站点:

sudo install -d -o www-data -g www-data -m 0755 /var/www/letsencrypt
sudo ln -s /etc/nginx/sites-available/laravel.conf /etc/nginx/sites-enabled/laravel.conf
sudo nginx -t
sudo systemctl reload nginx

预期输出:

syntax is ok
test is successful

如果提示 duplicate default server、端口占用或配置文件语法错误,先查看现有站点:

ls -l /etc/nginx/sites-enabled/
sudo nginx -T | less

不要在 nginx -t 失败时 reload。Nginx reload 失败时通常仍然保留旧配置,但应以测试结果为准,不要在错误配置上继续叠加修改。

访问应用:

curl -I http://example.com

如果返回 200、301、302 或由应用主动返回的业务状态,说明请求已经到达 Nginx。若返回 502 Bad Gateway,重点检查 PHP-FPM Socket;若返回 403,重点检查 root 路径和目录权限。

2. 检查 PHP-FPM Socket

ls -l /run/php/
sudo systemctl status php8.3-fpm --no-pager
sudo journalctl -u php8.3-fpm -n 50 --no-pager

如果实际 Socket 是 /run/php/php8.2-fpm.sock,Nginx 中的 fastcgi_pass 必须同步修改。不要根据网上示例猜测 PHP 版本。

php -v
systemctl list-units 'php*-fpm.service'

修改 Nginx 配置后再次验证:

sudo nginx -t
sudo systemctl reload nginx

3. 配置 PHP-FPM 资源边界

PHP-FPM 的 pm.max_children 不应按 CPU 核数直接设置,而应按可分配给 PHP 的内存估算。

可以使用以下思路:

PHP 可用内存 ≈ 服务器总内存 - 系统预留 - 数据库预留 - Nginx及其他服务预留

pm.max_children ≈ PHP 可用内存 ÷ 单个 PHP-FPM 高峰进程内存

例如,4 GB 服务器中,扣除系统、数据库和其他服务后给 PHP 预留约 1.2 GB,单个 PHP-FPM 进程高峰约 100 MB,理论值约为 12。实际还要保留余量,可以从 8~10 个子进程开始观察。

先备份配置:

sudo cp \
  /etc/php/8.3/fpm/pool.d/www.conf \
  /etc/php/8.3/fpm/pool.d/www.conf.bak.$(date +%Y%m%d-%H%M%S)

编辑配置:

sudo nano /etc/php/8.3/fpm/pool.d/www.conf

示例:

[www]

user = www-data
group = www-data

listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

pm = dynamic
pm.max_children = 10
pm.start_servers = 2
pm.min_spare_servers = 2
pm.max_spare_servers = 4
pm.max_requests = 500

request_terminate_timeout = 120s

php_admin_value[upload_max_filesize] = 20M
php_admin_value[post_max_size] = 22M
php_admin_value[memory_limit] = 256M

post_max_size 应略大于上传文件限制,Nginx 的 client_max_body_size 也要与业务需求匹配。过小会导致上传失败,过大则增加内存和磁盘压力。

验证并重新加载:

sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpm

观察进程数量和内存:

ps -o pid,ppid,user,%mem,rss,cmd -C php-fpm8.3
free -h

如果出现大量 server reached pm.max_children、内存持续耗尽或 OOM,应先降低并发和排查慢请求,不要盲目增加 pm.max_children。

五、管理队列 Worker 和定时任务

1. 使用 systemd 守护队列进程

以 Laravel Queue 为例,创建模板服务:

sudo nano /etc/systemd/system/laravel-queue@.service

内容如下:

[Unit]
Description=Laravel Queue Worker %i
After=network.target php8.3-fpm.service
Wants=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/laravel/current

ExecStart=/usr/bin/php /var/www/laravel/current/artisan queue:work \
    --sleep=3 \
    --tries=3 \
    --timeout=90 \
    --max-time=3600

Restart=always
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=120

NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

--timeout=90 必须小于项目队列连接配置中的 retry_after。如果一个任务可能执行 5 分钟,不能仍然使用 90 秒超时,否则可能产生重复执行。

加载并启动两个 Worker:

sudo systemctl daemon-reload
sudo systemctl enable --now laravel-queue@1.service
sudo systemctl enable --now laravel-queue@2.service

验证:

systemctl status laravel-queue@1.service --no-pager
systemctl status laravel-queue@2.service --no-pager
sudo journalctl -u laravel-queue@1.service -n 50 --no-pager

预期状态:

Active: active (running)

如果项目使用命名队列,可以在 ExecStart 中增加:

--queue=high,default

但必须与项目实际配置一致。队列服务启动后没有消费任务,通常需要检查队列驱动、数据库迁移、Redis 连接、失败任务记录和应用日志。

查看失败任务:

sudo -u www-data php /var/www/laravel/current/artisan queue:failed

不要在没有确认任务幂等性的情况下直接执行:

php artisan queue:retry all

重复重试可能导致重复扣款、重复发货、重复发送通知等业务后果。

2. 使用 systemd timer 运行 Scheduler

创建服务:

sudo nano /etc/systemd/system/laravel-schedule.service
[Unit]
Description=Laravel Scheduler
After=network.target

[Service]
Type=oneshot
User=www-data
Group=www-data
WorkingDirectory=/var/www/laravel/current
ExecStart=/usr/bin/php /var/www/laravel/current/artisan schedule:run

创建计时器:

sudo nano /etc/systemd/system/laravel-schedule.timer
[Unit]
Description=Run Laravel Scheduler Every Minute

[Timer]
OnBootSec=1min
OnUnitActiveSec=1min
Persistent=true
Unit=laravel-schedule.service

[Install]
WantedBy=timers.target

启用:

sudo systemctl daemon-reload
sudo systemctl enable --now laravel-schedule.timer

验证:

systemctl list-timers --all | grep laravel-schedule
sudo systemctl start laravel-schedule.service
sudo journalctl -u laravel-schedule.service -n 30 --no-pager

如果部署多台应用服务器,定时任务不能在每台服务器都无条件执行,否则相同任务可能运行多次。可以只在一台调度节点启用 timer,或在应用层使用任务锁。

六、建立分层日志策略

1. Laravel 应用日志

Laravel 使用 daily 通道时,日志一般写入:

/var/www/laravel/shared/storage/logs/laravel-YYYY-MM-DD.log

检查是否产生日志:

sudo -u www-data ls -lh /var/www/laravel/shared/storage/logs/
tail -f /var/www/laravel/shared/storage/logs/laravel-$(date +%F).log

可以使用 Tinker 或访问一个已知业务接口触发日志。不要在生产环境直接输出密码、Token、完整 Cookie 或支付敏感数据。

建议将普通日志级别设为 info,将 debug 仅用于短期排障。日志级别过低会快速占满磁盘,日志级别过高则会增加 IO 和检索成本。

2. Nginx 和 PHP-FPM 日志

查看 Nginx:

sudo tail -f /var/log/nginx/laravel_access.log
sudo tail -f /var/log/nginx/laravel_error.log

查看 PHP-FPM:

sudo journalctl -u php8.3-fpm -f

查看队列和定时任务:

sudo journalctl -u 'laravel-queue@*' -f
sudo journalctl -u laravel-schedule.service -f

遇到 502、启动失败或进程反复重启时,先看系统日志,不要立即修改 Laravel 代码。

六、建立分层日志策略 / 2. Nginx 和 PHP-FPM 日志配图

3. 限制 journald 占用

如果队列和 PHP-FPM 都输出到 journald,可以为 systemd 日志设置边界:

sudo install -d /etc/systemd/journald.conf.d

sudo tee /etc/systemd/journald.conf.d/limits.conf >/dev/null <<'EOF'
[Journal]
SystemMaxUse=1G
RuntimeMaxUse=256M
MaxRetentionSec=14day
EOF

应用配置:

sudo systemctl restart systemd-journald
sudo journalctl --disk-usage

这会影响服务器上的其他 systemd 服务日志,设置前应确认 1 GB 适合当前磁盘。不要使用未经检查的全盘删除命令清理日志。Laravel 的 LOG_DAILY_DAYS、Nginx 的 logrotate 和 journald 的保留策略应分别管理,避免多个工具同时处理同一文件。

七、申请并验证 HTTPS 证书

1. 使用 webroot 方式申请证书

安装 Certbot:

sudo apt install -y certbot

确认 ACME 验证目录可以访问:

sudo mkdir -p /var/www/letsencrypt/.well-known/acme-challenge
echo ok | sudo tee /var/www/letsencrypt/.well-known/acme-challenge/test.txt
curl http://example.com/.well-known/acme-challenge/test.txt

预期返回:

ok

申请证书:

sudo certbot certonly \
  --webroot \
  -w /var/www/letsencrypt \
  -d example.com \
  -d www.example.com \
  --email admin@example.com \
  --agree-tos \
  --no-eff-email

证书申请依赖 DNS、80 端口、安全组和 Nginx 配置。若失败,先检查:

dig +short A example.com
curl -I http://example.com/.well-known/acme-challenge/test.txt
sudo ss -lntp | grep ':80'

2. 配置 HTTPS 和 HTTP 跳转

申请成功后,备份现有配置:

sudo cp \
  /etc/nginx/sites-available/laravel.conf \
  /etc/nginx/sites-available/laravel.conf.bak.$(date +%Y%m%d-%H%M%S)

将配置调整为以下结构:

server {
    listen 80;
    listen [::]:80;

    server_name example.com www.example.com;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/letsencrypt;
        default_type text/plain;
    }

    location / {
        return 301 https://$host$request_uri;
    }

    access_log /var/log/nginx/laravel_http_redirect.log;
    error_log  /var/log/nginx/laravel_http_redirect_error.log warn;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    http2 on;

    server_name example.com www.example.com;

    root /var/www/laravel/current/public;
    index index.php index.html;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    client_max_body_size 20m;

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

    location ~ \.php$ {
        try_files $uri =404;

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_param HTTP_PROXY "";

        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_read_timeout 120s;
    }

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

    location ~* \.(?:css|js|jpg|jpeg|png|gif|svg|ico|webp|woff|woff2)$ {
        try_files $uri =404;
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
    }

    access_log /var/log/nginx/laravel_access.log;
    error_log  /var/log/nginx/laravel_error.log warn;
}

部分旧版 Nginx 不支持 http2 on; 写法,可以改为:

listen 443 ssl http2;
listen [::]:443 ssl http2;

先检查版本:

nginx -v

验证并重新加载:

sudo nginx -t
sudo systemctl reload nginx
curl -I http://example.com
curl -I https://example.com

预期是 HTTP 返回 301,HTTPS 返回应用响应。

3. 验证证书续期

查看 Certbot timer:

systemctl list-timers --all | grep certbot

执行模拟续期:

sudo certbot renew --dry-run

证书续期后,Nginx 需要 reload 才能加载新证书。可以增加部署钩子:

sudo install -d /etc/letsencrypt/renewal-hooks/deploy

sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
systemctl reload nginx
EOF

sudo chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

检查证书有效期和域名:

sudo openssl x509 \
  -in /etc/letsencrypt/live/example.com/fullchain.pem \
  -noout -subject -issuer -dates

八、设置数据库、文件和配置备份

1. 数据库备份

数据库备份不要把密码直接写在命令行中。可以创建权限为 600 的客户端配置文件:

sudo install -m 600 /dev/null /root/.my.cnf
sudo nano /root/.my.cnf

示例:

[client]
host=127.0.0.1
port=3306
user=backup
password=replace-with-backup-password

创建备份目录:

sudo install -d -m 700 /var/backups/laravel

执行备份:

backup_file="/var/backups/laravel/appdb-$(date +%Y%m%d-%H%M%S).sql.gz"

sudo mysqldump \
  --defaults-extra-file=/root/.my.cnf \
  --single-transaction \
  --quick \
  --routines \
  --events \
  --triggers \
  appdb | sudo gzip > "$backup_file"

sudo chmod 600 "$backup_file"
gzip -t "$backup_file"
ls -lh "$backup_file"

--single-transaction 主要适用于 InnoDB 表。若数据库包含非事务表、大量写入或超大表,应根据业务窗口选择备份方式。

备份只放在同一台香港服务器上,无法覆盖磁盘损坏、误删和整机故障。生产环境应将备份复制到独立存储或异地位置,并在传输和存储过程中保护敏感数据。

2. 备份上传文件和环境配置

Laravel 的上传文件通常在 storage/app/public,.env 中包含数据库密码和应用密钥,应单独控制权限:

file_backup="/var/backups/laravel/files-$(date +%Y%m%d-%H%M%S).tar.gz"

sudo tar \
  --exclude='storage/logs/*' \
  --exclude='storage/framework/cache/*' \
  --exclude='storage/framework/sessions/*' \
  -czf "$file_backup" \
  -C /var/www/laravel/shared \
  .env storage/app/public

sudo chmod 600 "$file_backup"
tar -tzf "$file_backup" | head

不要备份 storage/framework/cache、Session 临时文件和已经轮转的日志作为核心恢复数据。.env 和备份文件都需要限制访问,传输到外部存储时应使用加密通道或加密归档。

3. 备份保留和恢复验证

示例保留 14 天备份:

sudo find /var/backups/laravel \
  -type f \
  -mtime +14 \
  -print

确认输出只包含 /var/backups/laravel 中过期文件后,才可以执行删除:

sudo find /var/backups/laravel \
  -type f \
  -mtime +14 \
  -delete

删除命令的影响范围是指定目录中的过期普通文件。路径必须逐字确认,不能将变量目录替换成 / 或未验证的路径。

恢复数据库时,不要第一次就覆盖生产库。建议先恢复到隔离数据库:

gzip -dc /var/backups/laravel/appdb-20250101-120000.sql.gz \
  | mysql --defaults-extra-file=/root/.my.cnf appdb_restore

然后检查表数量、关键业务数据和 Laravel 迁移状态。只有确认恢复结果可用,才制定生产切换方案。

九、发布后的结果检查

1. 检查所有关键服务

systemctl --failed
systemctl is-active nginx
systemctl is-active php8.3-fpm
systemctl is-active laravel-queue@1.service
systemctl is-active laravel-queue@2.service
systemctl is-active laravel-schedule.timer

systemctl --failed 没有输出通常表示没有失败单元。如果存在失败服务,继续查看:

sudo journalctl -p err -b --no-pager

2. 检查 HTTP、HTTPS 和 Laravel

curl -I http://example.com
curl -I https://example.com
curl -sS https://example.com/ -o /dev/null -w '%{http_code}\n'

如果项目启用了 Laravel 默认健康检查路由,可以进一步验证:

curl -i https://example.com/up

/up 不一定存在于所有项目中,返回 404 不代表整个部署失败,应以项目实际健康检查路由为准。

应用层检查:

sudo -u www-data php /var/www/laravel/current/artisan about
sudo -u www-data php /var/www/laravel/current/artisan migrate:status

3. 检查日志是否正常产生

sudo tail -n 30 /var/log/nginx/laravel_access.log
sudo tail -n 30 /var/log/nginx/laravel_error.log
sudo tail -n 30 /var/www/laravel/shared/storage/logs/laravel-$(date +%F).log
sudo journalctl -u 'laravel-queue@*' -n 30 --no-pager

正常状态下,访问请求会产生 Nginx access log,应用异常会进入 Laravel 日志,队列 Worker 会在 journal 中保持运行状态。

4. 检查资源边界

df -h
df -ih
free -h
uptime
vmstat 1 5
sudo du -sh /var/www/laravel/shared/storage
sudo journalctl --disk-usage

可以将以下数值作为示例告警线,而不是固定标准:

  • 磁盘使用率达到 80%:开始处理日志和备份增长;
  • 磁盘使用率达到 90%:优先释放空间,避免数据库和 PHP-FPM 写入失败;
  • inode 使用率异常:检查大量 Session、缓存或小文件;
  • Swap 持续增长:检查 PHP-FPM、数据库和队列内存;
  • 队列积压持续增长:检查 Worker、任务耗时、数据库和第三方接口。

如果服务器同时运行数据库和应用,建议通过监控系统记录 CPU、内存、磁盘、PHP-FPM 活跃进程、Nginx 5xx、队列积压和证书剩余时间,而不是只依赖人工登录查看。

十、常见异常及处理顺序

现象优先检查常见原因处理方向
502 Bad Gatewaysystemctl status php8.3-fpm、SocketPHP-FPM 未启动、Socket 路径错误、权限错误修正 Socket 或恢复 PHP-FPM
504 Gateway TimeoutNginx error log、PHP-FPM 慢请求查询慢、外部接口超时、fastcgi_read_timeout 不匹配优化任务和查询,不要只提高超时
403 Forbiddenroot、目录权限、Nginx error logroot 未指向 public、目录不可进入修正路径和最小权限
500 Internal Server ErrorLaravel 日志、PHP-FPM journal.env、依赖、缓存或代码异常清理并重建缓存,检查发布版本
队列不消费Worker 状态、queue:failed、驱动连接服务未启动、驱动错误、迁移缺失修复驱动并重启 Worker
HTTP 可访问但 HTTPS 失败443 监听、证书路径、云安全组证书文件、Nginx 配置或 443 未放行nginx -t 后修复
证书续期失败DNS、80 端口、ACME 路径DNS 改变、验证目录不可访问恢复 HTTP 验证路径
磁盘快速增长du、Laravel/Nginx/journal 日志日志级别过高、队列异常重试、上传未清理设置保留策略并定位增长源

处理故障时应先做只读检查,例如查看状态、日志、端口和磁盘;确认原因后再 reload、restart 或修改配置。数据库恢复、删除文件、修改防火墙和执行生产迁移都属于高风险操作,应先备份并记录当前状态。

十一、版本发布和回滚

1. 推荐发布顺序

每次发布可以按以下顺序执行:

十一、版本发布和回滚 / 1. 推荐发布顺序配图

  1. 检查构建产物和 Composer 锁文件;
  2. 备份数据库和上传文件;
  3. 创建新的 releases/时间戳 目录;
  4. 安装 Composer 生产依赖;
  5. 链接 .env、storage 和缓存目录;
  6. 执行 php artisan about;
  7. 执行兼容性迁移;
  8. 清理并生成 Laravel 缓存;
  9. 原子切换 current 符号链接;
  10. reload PHP-FPM 和 Nginx;
  11. 平滑重启队列 Worker;
  12. 验证首页、健康检查、日志和队列。

队列 Worker 可以先发送平滑重启信号:

sudo -u www-data php /var/www/laravel/current/artisan queue:restart

然后观察:

sudo journalctl -u laravel-queue@1.service -f

如果 Worker 长时间不退出或已经卡死,再执行:

sudo systemctl restart laravel-queue@1.service laravel-queue@2.service

正在执行的任务可能被中断,因此业务任务应设计为幂等,避免重试产生重复副作用。

2. 应用代码回滚

查看当前和历史版本:

ls -lt /var/www/laravel/releases
readlink -f /var/www/laravel/current

切换到上一个已验证版本:

sudo ln -sfn /var/www/laravel/releases/20241228-093000 \
  /var/www/laravel/current

sudo systemctl reload php8.3-fpm
sudo systemctl reload nginx
sudo -u www-data php /var/www/laravel/current/artisan queue:restart

回滚前必须确认旧代码可以兼容当前数据库结构。如果新版本已经执行了不可逆迁移,单纯切回旧代码可能导致应用报错。数据库回滚应通过经过验证的备份恢复或专门的逆向迁移完成,不要直接对生产库执行未经测试的 SQL。

3. Nginx 和 PHP-FPM 配置回滚

如果新配置导致 Nginx 检查失败:

sudo nginx -t

可以恢复最近一次备份:

sudo cp \
  /etc/nginx/sites-available/laravel.conf.bak.20250101-120000 \
  /etc/nginx/sites-available/laravel.conf

sudo nginx -t
sudo systemctl reload nginx

PHP-FPM 配置回滚前先检查:

sudo php-fpm8.3 -t

确认备份文件内容后再替换,并重新加载:

sudo cp \
  /etc/php/8.3/fpm/pool.d/www.conf.bak.20250101-120000 \
  /etc/php/8.3/fpm/pool.d/www.conf

sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpm

4. 上线验收清单

最终验收至少包括:

  • [ ] 域名 A 记录指向香港服务器,未配置错误的 AAAA 记录;
  • [ ] 80 端口能够访问 ACME 验证路径;
  • [ ] HTTP 自动跳转 HTTPS;
  • [ ] HTTPS 证书域名和有效期正确;
  • [ ] Nginx root 指向 current/public;
  • [ ] PHP-FPM Socket 路径和 PHP 版本一致;
  • [ ] APP_DEBUG=false;
  • [ ] Laravel 能连接数据库;
  • [ ] storage 和 bootstrap/cache 可由 www-data 写入;
  • [ ] Laravel 日志、Nginx 日志和 PHP-FPM journal 均能产生记录;
  • [ ] 队列 Worker 显示 active (running);
  • [ ] 定时任务 timer 已启用且可以手动执行;
  • [ ] 数据库备份文件可以通过 gzip -t 校验;
  • [ ] 上传文件已纳入备份范围;
  • [ ] 备份不只保存在当前服务器;
  • [ ] 磁盘、内存、inode 和日志占用已经记录初始值;
  • [ ] 已保留上一版应用目录和 Nginx/PHP-FPM 配置备份;
  • [ ] 已验证应用代码回滚路径;
  • [ ] 已确认数据库迁移没有破坏旧版本兼容性。

完成这些检查后,Laravel 12 的生产运行边界才算基本建立:Nginx 负责入口和证书,PHP-FPM 控制 Web 进程,systemd 负责队列与定时任务,Laravel 和系统日志各自保留,备份与回滚不依赖临时手工操作。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3567.html

相关推荐