Laravel 12部署在香港服务器上,生产环境如何配置进程与日志?
香港服务器上的 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 构建产物或受控压缩包发布。
生产环境的请求流向如下:

客户端
↓ 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 LTS | cat /etc/os-release |
| PHP | 8.3,Laravel 12 要求不低于 8.2 | php -v |
| 域名 | example.com、www.example.com | DNS 查询 |
| 应用入口 | /var/www/laravel/current/public | 检查 Nginx root |
| 数据库 | MySQL 或 MariaDB | Laravel 连接测试 |
| 队列驱动 | 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
├── 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 代码。

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 Gateway | systemctl status php8.3-fpm、Socket | PHP-FPM 未启动、Socket 路径错误、权限错误 | 修正 Socket 或恢复 PHP-FPM |
| 504 Gateway Timeout | Nginx error log、PHP-FPM 慢请求 | 查询慢、外部接口超时、fastcgi_read_timeout 不匹配 | 优化任务和查询,不要只提高超时 |
| 403 Forbidden | root、目录权限、Nginx error log | root 未指向 public、目录不可进入 | 修正路径和最小权限 |
| 500 Internal Server Error | Laravel 日志、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. 推荐发布顺序
每次发布可以按以下顺序执行:

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



