Laravel 10应用部署到香港服务器,生产环境需要配置哪些关键项

发布人:A5数据发布时间:2026-10-26 10:41阅读量:81

香港服务器上的 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

相关推荐