Laravel 10应用部署到香港服务器,生产环境需要配置哪些关键项
香港服务器上的 Laravel 10 生产部署,重点不是让首页“能打开”,而是让 Web 入口、PHP-FPM、数据库、静态资源、HTTPS 和后台任务按生产方式运行。下面以 Ubuntu 22.04/24.04、Nginx、PHP 8.2、MySQL、域名已解析到服务器为例,演示首次部署流程;具体 PHP-FPM socket、软件包名称和服务名应以服务器实际安装结果为准。

一、准备条件
开始前确认以下条件:
- 服务器已安装 Nginx、PHP 8.2 及 Laravel 所需扩展,包括
mbstring、xml、curl、zip、bcmath、mysql、fileinfo、openssl和tokenizer。 - Composer 2 可用;如果需要在服务器编译前端资源,还要安装与项目锁定版本匹配的 Node.js 和 npm。
- 数据库已创建,应用账号仅拥有该应用所需的数据库权限。数据库若在另一台机器上,先确认香港服务器到数据库的网络路径、端口和访问规则。
- 域名的 DNS A 记录已指向服务器公网 IP。申请证书前,80 端口需能从公网访问;启用 HTTPS 后还需开放 443 端口。
- 部署账号可读取代码、执行部署命令,但不应将 Nginx 配置成以 root 运行应用。示例中应用目录为
/var/www/myapp,Web 进程用户为www-data,域名为example.com。
先核对系统与运行时,避免照搬不匹配的服务名:
lsb_release -a
php -v
php -m
composer --version
nginx -v
systemctl list-units --type=service | grep -E 'php.*fpm|nginx'
如果 PHP 扩展缺失,或项目依赖不支持当前 PHP 版本,应先处理依赖兼容性,再进行上线。香港机房位置本身不会改变 Laravel 的部署步骤;但若数据库或第三方服务位于其他地区,网络延迟和访问策略应单独验证。
面向 Laravel 10 应用在香港的生产部署,A5数据提供从入门建站到 Xeon Gold、AMD EPYC 平台的香港物理服务器。不同系列涵盖 SSD 或 NVMe 存储及多种内存配置,可为 Web 服务、数据库和队列任务提供运行资源;部分套餐提供 CN2 或国际带宽线路,适用于网站、业务后台和接口服务等场景。
二、准备发布目录与应用配置
生产环境建议按“发布目录 + current 软链接”组织代码。这样可以保留旧版本,切换代码时不必覆盖正在运行的目录。
sudo mkdir -p /var/www/myapp/releases
sudo chown -R "$USER":www-data /var/www/myapp
进入项目的 Git 仓库后,将代码拉取到新的发布目录。下面用时间戳作示例,执行时应替换成实际发布标识:
cd /var/www/myapp
RELEASE="$(date +%Y%m%d%H%M%S)"
mkdir -p "releases/$RELEASE"
git clone --depth 1 <项目仓库地址> "releases/$RELEASE"
cd "releases/$RELEASE"
若仓库需要认证,不要把访问令牌写进公开脚本或命令历史。也可以在受控的构建环境完成拉取与打包,再将发布包传到服务器。
为应用准备生产环境变量。可复制项目中的模板后编辑,但不要把 .env 提交到代码仓库:
cp .env.example .env
nano .env
至少核对这些配置,数据库密码和邮件凭据应使用实际值:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com
LOG_CHANNEL=stack
LOG_LEVEL=warning
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=myapp_user
DB_PASSWORD=替换为实际密码
SESSION_DRIVER=file
CACHE_STORE=file
Laravel 10 项目若仍使用 CACHE_DRIVER 配置项,应按项目现有配置文件调整,不要只因示例不同而盲目新增变量。香港服务器需要固定应用时区时,可在 .env 设置 APP_TIMEZONE=Asia/Hong_Kong,并确认 config/app.php 使用该变量;若业务统一以 UTC 存储时间,则应在应用层明确转换规则,而不是只调整操作系统时区。
首次创建应用密钥:
php artisan key:generate
已有线上数据的应用不要重新生成 APP_KEY:加密数据、Cookie 等可能因此无法读取。首次部署时生成的密钥应安全备份,并限制 .env 访问权限:
chmod 640 .env
检查结果:
grep -E '^(APP_ENV|APP_DEBUG|APP_URL|DB_HOST|DB_DATABASE)=' .env
确认输出中 APP_ENV=production、APP_DEBUG=false,并确认没有将密码输出到终端记录或工单中。
三、安装依赖并准备发布版本
在发布目录中安装 PHP 依赖。--no-dev 排除开发依赖,--optimize-autoloader 优化类加载:
composer install --no-dev --prefer-dist --optimize-autoloader
如果项目含有前端构建流程,应按仓库中的锁定文件安装依赖并生成生产资源,例如:
npm ci
npm run build
若服务器不承担前端构建,可在受控构建环境生成资源后随发布包上传。确认构建输出路径与项目 Vite、Mix 或其他资源配置一致,不能把“命令执行成功”当作静态资源已被 Nginx 正确访问。
Laravel 运行时需要写入 storage 和 bootstrap/cache,其他代码文件通常只需读取权限。先设置目录属主和权限,不使用 chmod -R 777:
sudo chown -R "$USER":www-data /var/www/myapp/releases/"$RELEASE"
sudo chgrp -R www-data storage bootstrap/cache
chmod -R ug+rwX storage bootstrap/cache
若 Web 进程无法写日志、缓存或上传文件,优先检查目录属主、ACL 和部署账号组关系,而不是放开所有用户写权限。
生成生产配置缓存:
php artisan config:cache
php artisan route:cache
php artisan view:cache
如果项目使用不兼容闭包路由,route:cache 会报错;应检查对应路由定义并按项目情况处理,不要因此省略错误信息。此时可不启用路由缓存,其余缓存仍可单独生成。
四、数据库迁移与版本切换
数据库迁移会改变数据结构,执行前应确认目标数据库、备份和迁移内容。首次上线也建议先做可恢复备份;对已有业务库,先在测试环境验证迁移脚本。确认后再执行:
php artisan migrate --force
--force 用于生产环境确认迁移意图,不会替代备份。若迁移会删除字段或改写数据,优先采用分阶段兼容方案;不要在不清楚影响时直接运行回滚或删除数据库。
检查迁移状态:
php artisan migrate:status
确认成功后,将当前版本切换到新发布目录:

cd /var/www/myapp
ln -sfn "releases/$RELEASE" current.new
mv -Tf current.new current
这里的 current 是 Web 根目录使用的软链接。切换前应确认 current 指向旧发布版本,避免误覆盖其他路径。若系统的 mv 不支持 -T,先核对命令帮助,再使用适合该系统的原子替换方式。
五、配置 Nginx、PHP-FPM 与 HTTPS
先确认 PHP-FPM socket 实际路径:
ls -l /run/php/
以下配置假设 socket 为 /run/php/php8.2-fpm.sock,如果实际名称不同,应同步替换。新建 Nginx 站点配置,例如 /etc/nginx/sites-available/myapp:
server {
listen 80;
server_name example.com www.example.com;
root /var/www/myapp/current/public;
index index.php;
access_log /var/log/nginx/myapp_access.log;
error_log /var/log/nginx/myapp_error.log;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Laravel 的 Web 根目录必须是 public,不能指向项目根目录,否则 .env、源码或其他非公开文件可能暴露。启用配置并先测试语法:
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
sudo nginx -t
sudo systemctl reload nginx
预期结果是 nginx -t 显示配置测试成功。若失败,不要重载;根据错误提示检查拼写、重复站点配置和 socket 路径。
公网 DNS 已解析且 80 端口可访问后,再通过已安装的证书工具申请证书。以 Certbot 的 Nginx 插件为例:
sudo certbot --nginx -d example.com -d www.example.com
按提示选择 HTTP 到 HTTPS 跳转后,检查:
sudo nginx -t
curl -I https://example.com
预期能通过 HTTPS 建立连接并收到 HTTP 响应。若证书申请失败,先核对域名解析、公网 80 端口和防火墙规则;不要通过关闭防火墙来绕过问题。证书续期应使用证书工具提供的定时任务,并检查续期模拟结果:
sudo certbot renew --dry-run
六、启动服务与后台任务
确认 Nginx 和 PHP-FPM 已启用并运行:
sudo systemctl enable --now nginx
sudo systemctl enable --now php8.2-fpm
systemctl status nginx php8.2-fpm --no-pager
若服务名称与示例不同,以 systemctl list-units 的结果为准。Laravel 使用队列时,不能只依赖前台命令或 SSH 会话。应配置 Supervisor 或 systemd 等进程管理器,让队列进程异常退出后可被重新拉起,并按项目的队列连接配置启动 php artisan queue:work。发布后可执行:

php artisan queue:restart
该命令通知队列工作进程在处理完当前任务后退出;必须有进程管理器负责重新启动。若应用没有使用队列,可不配置这一项。
使用 Laravel 定时任务时,配置系统 cron 每分钟调用调度器。以 www-data 用户执行为例:
sudo crontab -u www-data -e
加入一行,路径按实际安装调整:
* * * * * cd /var/www/myapp/current && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
确认 PHP 命令路径:
command -v php
如输出不是 /usr/bin/php,将 cron 中的路径替换为实际结果。未使用 Laravel Scheduler 的项目不需要添加该任务。
七、验证、异常处理与回滚
上线后从入口到应用逐层验证:
curl -I http://example.com
curl -I https://example.com
sudo tail -n 50 /var/log/nginx/myapp_error.log
tail -n 50 /var/www/myapp/current/storage/logs/laravel.log
还应实际打开登录、核心业务页面和静态资源,必要时提交一条可撤销的测试操作。首页返回 200 不代表数据库写入、邮件、队列或上传流程正常;这些功能应按应用实际使用范围分别验证。
常见问题可从低风险检查开始:

- 502 Bad Gateway:检查 PHP-FPM 是否运行,以及 Nginx 配置中的 socket 是否存在、权限是否允许访问。分别查看
systemctl status php8.2-fpm和 Nginx 错误日志。 - 403 或 404:确认
root指向current/public、站点域名匹配,并检查目录的遍历权限。不要把 Nginx 根目录改到 Laravel 项目根目录。 - 页面报 500:先看 Laravel 日志和 PHP-FPM 日志,再确认
.env、数据库连接及storage、bootstrap/cache写权限。排查时不要把APP_DEBUG留在true。 - 数据库连接失败:核对主机、端口、数据库名、账号权限和网络访问规则。远程数据库还需确认数据库侧允许该服务器连接。
- 资源 404 或样式缺失:检查前端构建是否成功、资源文件是否位于发布目录,以及应用生成的资源 URL 是否与 HTTPS 域名一致。
如果新版本启动异常且数据库结构与旧版本兼容,可先把 current 切回旧发布目录,再重载相关服务:
cd /var/www/myapp
ln -sfn releases/旧版本发布标识 current.new
mv -Tf current.new current
sudo systemctl reload nginx
sudo systemctl reload php8.2-fpm
队列进程若仍运行旧代码,应按进程管理器配置重启;Scheduler 则会在下一次执行时读取当前路径。回滚代码不等于回滚数据库:若新版本已执行不兼容迁移,应先依据备份和迁移方案评估数据恢复,不能直接运行 migrate:rollback 作为通用撤销操作。确认旧版本已恢复后,再保留新版本及日志用于分析,不要立即删除发布目录或备份。
验收与回滚检查项
首次上线完成前,逐项确认:
APP_ENV=production、APP_DEBUG=false,应用密钥已生成且妥善保存。- Nginx 根目录指向
current/public,Nginx 配置测试通过,PHP-FPM 服务运行正常。 - HTTP/HTTPS 请求符合预期,证书有效,自动续期模拟通过。
- Laravel 日志、Nginx 日志可读取;核心页面、数据库读写及实际使用的队列、定时任务和上传功能均已验证。
- 新发布目录与旧版本目录都保留,当前软链接目标明确;数据库备份可用,迁移风险和恢复步骤已确认。
- 回滚时先切回兼容的旧代码,再检查队列、服务状态和业务数据;涉及不可逆迁移时,不执行未经验证的数据库回退。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5781.html



