Laravel 8应用部署到美国服务器,生产环境要配置哪些关键项?
把 Laravel 8 应用部署到美国服务器后,生产环境至少要确认应用入口、PHP-FPM、数据库连接、环境变量、日志、HTTPS、文件权限、定时任务和队列服务能够协同工作。美国服务器的地理位置不会改变 Laravel 的部署方式,但会影响 DNS 解析、访问延迟、服务器时区和防火墙策略,因此这些项目需要在上线前一并核对。
下面以 Ubuntu 22.04、PHP 8.1、Nginx、MySQL 8、域名 app.example.com 和部署目录 /var/www/example.com 为例,说明已有 Laravel 8 项目首次上线时的实施顺序。命令中的域名、数据库名、用户名、仓库地址和密码均为示例,不能直接照搬到生产环境。
A5idc数据提供美国物理服务器租用,覆盖常规 Xeon、AMD EPYC 及多种内存、NVMe 存储配置,可为 Laravel 8 生产环境中的 Web 服务、MySQL 数据库、队列任务和多进程应用提供独立硬件资源。美国常规系列支持 CN2 GIA 等线路方案,适合面向美国用户及跨境业务部署网站、后台与接口服务,并可结合业务规模扩展计算、存储和网络资源。
一、上线前准备与环境确认
1. 确认服务器和应用条件
建议准备一个具备 sudo 权限的部署账号,例如 deploy,不要长期使用 root 直接运行 Composer、Node.js 和 Laravel 命令。
本示例假设:
- 操作系统为 Ubuntu 22.04;
- PHP 使用 8.1,且项目的
composer.lock已在该版本上验证; - Web 服务使用 Nginx;
- 数据库与 Laravel 应用部署在同一台美国服务器上;
- 域名为
app.example.com; - 应用代码已经提交到 Git 仓库;
- DNS 的 A 记录指向服务器公网 IPv4 地址;
- 如果配置了 AAAA 记录,其 IPv6 地址也必须确实指向这台服务器。
先检查服务器版本、PHP 和系统时间:
cat /etc/os-release
php -v
timedatectl status
预期能够看到 Ubuntu 22.04、PHP 8.1,以及正常同步的系统时间。生产环境通常使用 UTC,便于统一记录日志和处理跨时区任务。如果业务明确要求使用美国某个时区,应在 Laravel 的 config/app.php 中单独设置,而不是只修改服务器时间。
DNS 生效后,可以从服务器或外部终端检查:
dig +short app.example.com
返回的地址应与服务器公网地址一致。DNS 尚未生效时,不要急着申请证书或进行最终 HTTPS 验证。
2. 备份应用和数据库
首次部署空数据库时,重点是保留代码包和环境配置。若服务器上已经存在旧版本应用或旧数据库,必须先备份,再执行迁移和切换。
数据库备份示例:
mkdir -p ~/backup
mysqldump --single-transaction --routines --triggers \
-u app_user -p app_prod > ~/backup/app_prod_$(date +%Y%m%d_%H%M%S).sql
执行后按提示输入密码,不要把数据库密码直接写在命令行中。该备份用于数据库回滚或恢复,不能替代代码版本管理。
二、安装运行环境并验证服务
1. 安装 Nginx、PHP、MySQL 和部署工具
以下命令适用于本示例的 Ubuntu 22.04 和 PHP 8.1:
sudo apt update
sudo apt install -y \
nginx mysql-server git unzip curl ca-certificates composer \
php8.1-cli php8.1-fpm php8.1-mysql php8.1-mbstring \
php8.1-xml php8.1-curl php8.1-zip php8.1-bcmath \
php8.1-intl php8.1-opcache
启动并设置服务开机自启:
sudo systemctl enable --now nginx
sudo systemctl enable --now php8.1-fpm
sudo systemctl enable --now mysql
检查运行状态:
systemctl is-active nginx
systemctl is-active php8.1-fpm
systemctl is-active mysql
php -v
composer --version
三个 systemctl is-active 命令都应返回 active。如果 PHP 不是 8.1,不能继续直接使用 /run/php/php8.1-fpm.sock,应先确认实际版本和 FPM Socket:
ls -l /run/php/
后续 Nginx 的 fastcgi_pass 路径必须与实际 Socket 一致。
2. 调整 PHP-FPM 的生产参数
Laravel 8 的具体内存和上传需求取决于业务。下面是一组适合中小型应用的参考配置,上传文件较大或有报表导出任务时需要按实际情况调整。
sudo tee /etc/php/8.1/fpm/conf.d/99-laravel.ini > /dev/null <<'EOF'
memory_limit=256M
upload_max_filesize=20M
post_max_size=25M
max_execution_time=60
realpath_cache_size=4096K
realpath_cache_ttl=600
opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
opcache.revalidate_freq=0
EOF
opcache.validate_timestamps=0 可以减少生产环境频繁检查文件变更带来的开销,但每次代码发布后都必须重启 PHP-FPM,否则旧代码可能继续保留在 Opcache 中。
先检查 PHP-FPM 配置,再重启:
sudo php-fpm8.1 -t
sudo systemctl restart php8.1-fpm
预期结果应包含 configuration file ... test is successful。如果检查失败,应先修正配置,不要继续切换 Nginx 入口。
三、准备 Laravel 发布目录和应用依赖
1. 使用发布目录,避免直接覆盖当前版本
使用 current 软链接指向当前版本,后续可以快速切换回旧版本。先创建目录并设置基础权限:
sudo mkdir -p /var/www/example.com/releases
sudo mkdir -p /var/www/example.com/shared/storage
sudo chown -R deploy:www-data /var/www/example.com
sudo chmod 755 /var/www/example.com
sudo chmod 755 /var/www/example.com/releases
sudo chmod 755 /var/www/example.com/shared
下面的应用构建命令建议以 deploy 用户执行:
sudo -iu deploy
定义发布目录变量并拉取代码:
BASE=/var/www/example.com
RELEASE="$BASE/releases/$(date +%Y%m%d%H%M%S)"
mkdir -p "$RELEASE"
git clone --depth 1 git@example.com:team/example.git "$RELEASE"
cd "$RELEASE"
私有仓库应使用部署密钥或受控的 CI/CD 凭据,不要把访问令牌写入 Git URL、脚本或 .env 并提交到仓库。
将共享环境文件和存储目录连接到当前发布版本:
mkdir -p "$BASE/shared/storage"/app
mkdir -p "$BASE/shared/storage"/framework/cache
mkdir -p "$BASE/shared/storage"/framework/sessions
mkdir -p "$BASE/shared/storage"/framework/views
mkdir -p "$BASE/shared/storage"/logs
if [ ! -f "$BASE/shared/.env" ]; then
cp "$RELEASE/.env.example" "$BASE/shared/.env"
fi
ln -sfn "$BASE/shared/.env" "$RELEASE/.env"
ln -sfn "$BASE/shared/storage" "$RELEASE/storage"
这样做的好处是发布新代码时不会覆盖生产环境配置和用户上传文件。
2. 安装 Composer 和前端依赖
在发布目录中执行:
cd "$RELEASE"
composer install \
--no-dev \
--prefer-dist \
--optimize-autoloader \
--no-interaction
安装完成后检查平台依赖:
composer check-platform-reqs
预期结果应显示 PHP 和已安装扩展满足项目要求。如果出现 PHP 版本或扩展缺失错误,应先处理依赖,不要使用 --ignore-platform-reqs 强行上线。
如果项目包含 Laravel Mix 前端资源,并且仓库中已有 package-lock.json,执行:
npm ci
npm run production
如果没有锁定文件,npm ci 会失败。生产环境不建议临时使用不受控的依赖版本,应先在开发或构建环境生成并提交 package-lock.json,再重新发布。
执行后检查典型构建文件:
ls -l public
test -f public/mix-manifest.json && echo "Mix manifest exists"
如果项目使用其他前端构建工具,应以项目自身的构建脚本为准。
四、配置生产环境变量和数据库
1. 设置 .env 中的关键项
编辑共享环境文件:
nano /var/www/example.com/shared/.env
Laravel 8 的基础生产配置可以参考以下内容:
APP_NAME="Example App"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://app.example.com
LOG_CHANNEL=stack
LOG_LEVEL=warning
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app_prod
DB_USERNAME=app_user
DB_PASSWORD=请替换为强密码
BROADCAST_DRIVER=log
CACHE_DRIVER=file
FILESYSTEM_DRIVER=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=请填写SMTP账号
MAIL_PASSWORD=请填写SMTP密码
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="${APP_NAME}"
需要重点确认以下项目:
APP_ENV必须为production;APP_DEBUG必须为false,避免向访客暴露堆栈、路径和环境变量;APP_URL使用最终 HTTPS 地址;DB_HOST、数据库名、用户名和密码与实际数据库一致;- 单机部署可以暂时使用
file缓存和文件会话; - 使用异步队列时,不能继续使用
QUEUE_CONNECTION=sync; - 邮件密码、支付密钥和第三方 API 密钥不能提交到代码仓库。
首次部署空应用时生成 APP_KEY:
cd /var/www/example.com/releases/当前发布目录
php artisan key:generate --force
APP_KEY 会影响加密 Cookie、密码重置令牌等数据。对已经运行的生产应用重新执行 key:generate,可能导致已有用户会话失效或加密数据无法解密,因此更新版本时不要重复生成。
设置环境文件权限:
chmod 640 /var/www/example.com/shared/.env
chown deploy:www-data /var/www/example.com/shared/.env
2. 创建本地 MySQL 数据库
以下 SQL 只适用于新建数据库和新建用户。对已有生产数据库,不要重复执行或随意覆盖账户权限;执行前应完成备份,并确认影响范围。
sudo mysql
在 MySQL 控制台中执行:
CREATE DATABASE app_prod
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
CREATE USER 'app_user'@'127.0.0.1'
IDENTIFIED BY '请替换为长度足够的强密码';
GRANT ALL PRIVILEGES ON app_prod.* TO 'app_user'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;
应用使用 DB_HOST=127.0.0.1 时,数据库账户的主机部分也按 127.0.0.1 创建。不要为了方便将 MySQL 的 3306 端口暴露到公网,除非确有远程管理需求并且已经配置了来源地址限制。
3. 设置 Laravel 密钥、权限和迁移
回到部署用户和发布目录:
cd /var/www/example.com/releases/当前发布目录
php artisan key:generate --force
php artisan storage:link
Laravel 只需要让 PHP-FPM 对 storage 和 bootstrap/cache 具有写权限,应用代码本身不应对 Web 进程开放全目录写权限:
find storage bootstrap/cache -type d -exec chmod 775 {} \;
find storage bootstrap/cache -type f -exec chmod 664 {} \;
chown -R deploy:www-data storage bootstrap/cache
首次使用空数据库时执行迁移:
php artisan migrate --force
如果是已有数据库,先检查迁移状态:
php artisan migrate:status
数据库迁移可能新增字段、修改索引或改变数据结构。不能把 php artisan migrate:rollback 当作通用回滚手段,因为并非所有迁移都能安全逆向,且回滚可能造成数据丢失。已有数据库应先使用 mysqldump 备份,并在迁移前确认对应迁移文件的影响范围。
4. 缓存配置、路由和视图
确认 .env 内容无误后,在发布目录执行:
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
预期结果是各命令正常结束,没有异常堆栈。
如果 route:cache 报错,通常是路由文件中存在闭包路由。应将闭包改为控制器方法,或者暂时不执行 route:cache,不要忽略错误继续发布。配置缓存启用后,应用代码中不应直接在业务逻辑里调用 env(),环境变量应先写入配置文件,再通过 config() 获取。
五、配置 Nginx 入口和 HTTPS
1. 将网站根目录指向 public
Laravel 的 Nginx 根目录必须指向项目的 public,不能指向项目根目录,否则 .env、源码目录或其他内部文件可能被错误暴露。
创建站点配置:
sudo nano /etc/nginx/sites-available/example.com
写入以下内容:

server {
listen 80;
listen [::]:80;
server_name app.example.com;
root /var/www/example.com/current/public;
index index.php index.html;
client_max_body_size 20M;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
启用站点:
sudo ln -sfn /etc/nginx/sites-available/example.com \
/etc/nginx/sites-enabled/example.com
如果默认站点会抢先响应未知域名,可以先备份并停用它,而不是直接删除:
if [ -e /etc/nginx/sites-enabled/default ]; then
sudo mv /etc/nginx/sites-enabled/default \
/etc/nginx/sites-enabled/default.disabled
fi
检查配置并重新加载:
sudo nginx -t
sudo systemctl reload nginx
nginx -t 必须返回配置测试成功。如果失败,优先检查大括号、域名、PHP-FPM Socket 和文件路径。未经 nginx -t 验证,不要直接重启 Nginx。
2. 切换当前发布版本
在确认 Composer、前端资源、环境文件和 Laravel 命令都正常后,执行:
ln -sfn "$RELEASE" "$BASE/current"
然后以 root 或具备 sudo 权限的账号重启 PHP-FPM,使 Opcache 加载新代码:
sudo systemctl restart php8.1-fpm
sudo nginx -t
sudo systemctl reload nginx
检查当前软链接:
readlink -f /var/www/example.com/current
返回结果应为刚刚创建的发布目录。
3. 申请 HTTPS 证书
确认 DNS 已指向服务器,并且 80 端口能够从公网访问后安装 Certbot:
sudo apt install -y certbot python3-certbot-nginx
申请证书并让 Certbot 修改 Nginx 配置:
sudo certbot --nginx -d app.example.com
按提示填写联系邮箱,并选择是否将 HTTP 自动跳转到 HTTPS。完成后验证:
sudo nginx -t
sudo certbot renew --dry-run
curl -I https://app.example.com
HTTPS 请求通常应返回 200、301 或 302,具体取决于应用首页是否需要登录或跳转。certbot renew --dry-run 只进行续期流程演练,不代表已经替换了生产证书。
六、配置防火墙、定时任务和队列
1. 开放必要端口
启用 UFW 前,必须确认当前 SSH 端口已允许,否则可能把自己锁在服务器外。以下示例假设 SSH 使用 22 端口:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable
sudo ufw status verbose
如果 SSH 使用其他端口,应将 22/tcp 替换为实际端口。云服务商的安全组也必须同步放行 22、80 和 443;3306 不应对公网开放。
防火墙规则属于高影响配置。若配置错误,应通过服务器控制台恢复访问,或使用以下命令检查编号后删除错误规则:
sudo ufw status numbered
sudo ufw delete <规则编号>
2. 配置 Laravel Scheduler
如果应用使用 app/Console/Kernel.php 中的定时任务,需要每分钟执行一次 schedule:run。以 deploy 用户编辑定时任务:
crontab -e
加入:
* * * * * cd /var/www/example.com/current && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
验证当前用户的定时任务:
crontab -l
不要重复添加同一行。定时任务本身不会主动显示执行结果,具体任务应写入 Laravel 日志或业务日志,便于后续确认。
3. 配置异步队列
如果应用使用 QUEUE_CONNECTION=sync,请求会同步执行队列任务,不需要独立 Worker,但邮件、图片处理和耗时任务可能拖慢用户请求。
如果使用 database、Redis 等异步队列,需要配置长期运行的 Worker。以 database 队列为例,必须先确保项目已经有 jobs 表;如果项目尚未生成队列表,需要在测试环境生成迁移并确认后再执行:
php artisan queue:table
php artisan migrate --force
安装 Supervisor:
sudo apt install -y supervisor
创建 Worker 配置:
sudo tee /etc/supervisor/conf.d/example-worker.conf > /dev/null <<'EOF'
[program:example-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/example.com/current/artisan queue:work --sleep=3 --tries=3 --timeout=90
directory=/var/www/example.com/current
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=deploy
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/example.com/shared/storage/logs/worker.log
stopwaitsecs=3600
EOF
加载并检查:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
预期状态为 RUNNING。每次发布新代码后,长期运行的 Worker 仍可能加载旧代码,应在切换版本后重启:
sudo supervisorctl restart example-worker:*
如果应用没有异步队列,不要为了“完整”安装 Worker,避免增加无用的进程和排查范围。

七、上线验证与常见异常
1. 执行结果检查
可以按下面的顺序验收:
| 检查项目 | 命令或方式 | 预期结果 |
|---|---|---|
| 服务状态 | systemctl is-active nginx php8.1-fpm mysql | 均返回 active |
| 当前版本 | readlink -f /var/www/example.com/current | 指向目标发布目录 |
| Laravel 配置 | php artisan migrate:status | 能正常读取数据库 |
| HTTPS 入口 | curl -I https://app.example.com | 返回正常 HTTP 状态码 |
| 环境文件保护 | curl -o /dev/null -s -w '%{http_code}\n' https://app.example.com/.env | 返回 403 或 404 |
| PHP 监听 | sudo ss -lntp | grep -E ':80|:443' | Nginx 监听 80/443 |
| 数据库暴露范围 | sudo ss -lntp | grep 3306 | 不应直接暴露到公网 |
| 队列状态 | sudo supervisorctl status | 使用队列时显示 RUNNING |
| 定时任务 | crontab -l | 存在且仅有一条调度配置 |
同时打开浏览器访问首页、登录页、文件上传和邮件相关功能。Laravel 日志位于:
tail -n 100 /var/www/example.com/current/storage/logs/laravel.log
Nginx 和 PHP-FPM 日志可以分别查看:
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u php8.1-fpm -n 100 --no-pager
2. 常见失败处理
出现 502 Bad Gateway
先检查 PHP-FPM 是否运行,以及 Nginx 配置中的 Socket 是否存在:
systemctl status php8.1-fpm
ls -l /run/php/php8.1-fpm.sock
sudo nginx -t
如果实际 Socket 是 php8.2-fpm.sock 或其他版本,应统一调整 PHP-FPM 服务和 Nginx 配置。
出现 403 或 Laravel 页面不存在
重点检查 Nginx 的 root 是否指向:
/var/www/example.com/current/public
同时确认父目录可被 Nginx 进程遍历:
namei -l /var/www/example.com/current/public/index.php
出现 500 或生产错误页
先查看 Laravel 日志,不要临时把 APP_DEBUG 改为 true 对公网排查:
tail -n 100 /var/www/example.com/current/storage/logs/laravel.log
常见原因包括 APP_KEY 缺失、数据库密码错误、缓存配置未刷新、storage 无写权限或 Composer 依赖不完整。修改 .env 后,应重新执行:
php artisan config:clear
php artisan config:cache
sudo systemctl restart php8.1-fpm
页面正常但 CSS 或 JavaScript 404
检查前端构建是否完成,以及 public/mix-manifest.json 或项目使用的构建产物是否存在:
ls -l public
test -f public/mix-manifest.json && cat public/mix-manifest.json
然后确认 Nginx 根目录没有误指向项目根目录。
数据库连接失败
核对 .env 中的 DB_HOST、数据库名和用户主机限制,并测试迁移状态:
php artisan migrate:status
如果数据库用户只创建为 'app_user'@'localhost',而应用使用 127.0.0.1,可能出现权限匹配问题,需要统一主机配置或按实际连接方式补充授权。
队列或定时任务没有执行
检查 Supervisor 状态、Worker 日志和当前发布路径:
sudo supervisorctl status
tail -n 100 /var/www/example.com/shared/storage/logs/worker.log
crontab -l
发布新版本后没有重启 Worker,是旧代码继续处理任务的常见原因。
八、回滚与最终验收
1. 代码回滚
保留失败版本的目录和日志,不要立即删除。先查看历史发布目录:
ls -lt /var/www/example.com/releases
readlink -f /var/www/example.com/current
确认旧版本目录后,将 current 切回旧版本:
OLD_RELEASE=/var/www/example.com/releases/20240101010101
sudo ln -sfn "$OLD_RELEASE" /var/www/example.com/current
sudo systemctl restart php8.1-fpm
sudo nginx -t
sudo systemctl reload nginx
如果使用 Supervisor,还要重启 Worker:
sudo supervisorctl restart example-worker:*
回滚后重新访问首页、登录页和关键业务页面,并检查 Laravel 日志。不要直接使用 rm -rf 删除失败发布目录,至少应等到确认代码、日志和数据库状态均已恢复后再清理。
2. 数据库回滚
数据库回滚必须以备份为基础,并确认恢复会覆盖哪些数据。恢复前应暂停写入、进入维护状态或切换到隔离环境,避免恢复过程中产生新的不一致数据。
示例恢复命令如下:
mysql -u app_user -p app_prod < ~/backup/app_prod_20240101_010101.sql
该操作可能覆盖备份时点之后的数据,不能在未确认影响范围的情况下执行。对于不可逆或已经产生业务数据的迁移,优先通过新的前向迁移修复,而不是盲目执行 migrate:rollback。

3. 上线验收清单
正式宣布部署完成前,至少确认:
APP_ENV=production且APP_DEBUG=false;APP_KEY已生成并且没有在后续发布中被重新生成;- Nginx 根目录为
current/public; - PHP-FPM、Nginx、MySQL 服务状态正常;
- 数据库迁移状态符合预期;
storage和bootstrap/cache可写,其他源码目录没有开放写权限;/.env等敏感文件无法通过 HTTP 访问;- HTTP 到 HTTPS 的访问策略符合预期;
- 证书有效,续期演练可以通过;
- 80、443 和实际 SSH 端口已放行,3306 未直接暴露;
- Scheduler 配置没有重复;
- 应用使用异步队列时,Supervisor Worker 为
RUNNING; - 首页、登录、数据库读写、文件上传、邮件或队列等实际功能已经验证;
- 旧发布目录和数据库备份仍然可用于回滚。
完成这些检查后,Laravel 8 应用才算从“能运行”进入了具备基本生产可用条件的状态。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8875.html



