PHP网站部署到日本服务器,如何配置Nginx与PHP-FPM?
日本服务器上部署 PHP 网站时,建议先固定一套可验证的运行基线,例如 Ubuntu 24.04 LTS、Nginx、PHP 8.3-FPM、MariaDB 10.11(仅在网站需要数据库时安装),并将域名解析、时区、文件权限、PHP-FPM Socket、HTTPS 和应用配置逐项验证。这样可以把“域名无法访问”“Nginx 能启动但 PHP 报 502”“应用连接不上数据库”等问题拆开处理。
下面以域名 example.jp、网站目录 /var/www/example.jp 为例,采用 PHP-FPM Unix Socket 连接方式。示例中的域名、Git 地址、数据库名、用户和密码都需要替换为实际值。命令默认在 Ubuntu 24.04 LTS 上执行,并使用具有 sudo 权限的初始管理员账号。
围绕日本地区的 PHP 网站、业务后台和数据库部署,A5数据提供日本物理服务器资源,覆盖 Xeon Gold、AMD EPYC 等平台,并配备 NVMe、SSD 或大容量 HDD 方案;网络侧提供 CN2、CIA、GIA、SoftBank 等线路选项及相应带宽配置,可结合本地访问、跨境业务、程序负载和数据规模承载 Nginx、PHP-FPM、数据库及文件服务,为网站上线和后续版本维护提供服务器基础。
一、部署目标与准备条件
1. 目标架构
本次部署完成后,请求链路如下:

浏览器
↓ HTTPS
Nginx:80/443
↓ Unix Socket
PHP 8.3-FPM
↓
PHP 网站代码
↓
MariaDB(如果应用需要)
Nginx 负责域名匹配、静态文件、HTTPS 和请求转发;PHP-FPM 负责执行 PHP 文件;网站代码的公开入口使用 public 目录,避免 .env、依赖目录或其他内部文件被直接访问。
建议使用以下目录结构:

/var/www/example.jp/
├── current -> /var/www/example.jp/releases/20250101010101
├── releases/
│ ├── 20250101010101/
│ └── 20250102020202/
└── shared/
└── .env
current 是当前上线版本的软链接。更新网站时只切换软链接,不直接覆盖正在运行的代码,便于快速回退到上一版本。
2. 服务器与域名条件
部署前确认以下条件:
- 已创建日本地区的 Linux 服务器,系统为 Ubuntu 24.04 LTS。
- 已获得服务器公网 IPv4 地址;如果配置了 IPv6,还需要确认服务器实际具备可用 IPv6。
- 可以通过 SSH 登录服务器。
- 域名已经准备好,例如
example.jp和可选的www.example.jp。 - 网站源码、
composer.json、数据库结构和生产环境配置已经准备好。 - 网站所需的 PHP 扩展、数据库版本和运行命令已经从项目文档确认。
- 如果使用 HTTPS,域名的 A 或 AAAA 记录必须能够解析到这台服务器。
先确认操作系统和内核信息:
cat /etc/os-release
uname -a
预期可以看到类似以下内容:
PRETTY_NAME="Ubuntu 24.04.1 LTS"
VERSION_ID="24.04"
如果系统不是 Ubuntu 24.04,尤其是 Ubuntu 22.04、Debian 或 CentOS,不要直接照搬后文的 PHP 软件包名称和服务名,应先通过以下命令确认:
apt-cache policy php8.3-fpm 2>/dev/null || true
systemctl list-unit-files | grep -E 'php.*fpm|nginx'
3. 维护窗口与备份
安装软件、修改 PHP-FPM 参数、重启服务和执行数据库迁移,都可能影响现有网站。正式环境建议先完成以下事项:
- 创建云服务器快照,至少覆盖系统盘和网站目录。
- 备份现有 Nginx 配置、PHP 配置和数据库。
- 确认有服务商控制台或带外终端,防止防火墙调整错误后无法 SSH 登录。
- 记录当前 DNS、SSH 端口、监听端口和应用版本。
涉及覆盖配置、修改防火墙和数据库迁移的操作,都应先保留可恢复副本。
二、设置系统时间与基础软件
1. 设置日本时区
日本服务器不一定必须使用日本时区,但网站日志、定时任务、订单时间和后台显示通常需要与业务所在地保持一致。将系统时区设置为 Asia/Tokyo:
sudo timedatectl set-timezone Asia/Tokyo
timedatectl status
date
预期输出中应包含:
Time zone: Asia/Tokyo (JST, +0900)
这只会调整系统时间显示和时区规则,不会手动修改服务器的实际时钟。确认业务是否依赖 UTC;如果应用内部统一使用 UTC,则可以保留系统时区为 UTC,并只在应用层设置时区。
2. 更新软件索引并安装运行环境
更新系统软件前,先确认已完成快照或维护安排。apt upgrade 可能更新内核、OpenSSL、Nginx 或其他系统组件,部分更新会要求重启。
sudo apt update
sudo apt upgrade -y
安装 Nginx、PHP-FPM、常用 PHP 扩展、Composer 和基础工具:
sudo apt install -y \
nginx \
php8.3-fpm \
php8.3-cli \
php8.3-common \
php8.3-mysql \
php8.3-curl \
php8.3-mbstring \
php8.3-xml \
php8.3-zip \
php8.3-gd \
php8.3-intl \
php8.3-bcmath \
php8.3-opcache \
composer \
unzip \
git \
curl \
ca-certificates
如果网站使用其他扩展,应根据 composer.json 和项目文档补充。例如,应用提示缺少 redis、imagick 或其他扩展时,不要只修改 PHP 配置,应安装对应的系统扩展并重新验证。
检查版本和服务状态:
php -v
php-fpm8.3 -v
nginx -v
composer --version
systemctl status nginx --no-pager
systemctl status php8.3-fpm --no-pager
预期应能看到 PHP 8.3、Nginx 版本和 active (running) 状态。若 PHP-FPM 不存在,说明软件包没有按预期安装,先检查:
dpkg -l | grep -E 'php8.3-fpm|nginx'
journalctl -u php8.3-fpm -n 50 --no-pager
3. 启用服务并确认 PHP-FPM Socket
sudo systemctl enable --now nginx
sudo systemctl enable --now php8.3-fpm
确认 Socket 路径:
ls -l /run/php/
ss -lx | grep php
Ubuntu 24.04 的 PHP 8.3-FPM 通常使用:
/run/php/php8.3-fpm.sock
如果实际路径不同,后面的 Nginx fastcgi_pass 必须使用实际路径,不能仅凭版本号猜测。
三、创建网站目录与部署账号
1. 创建专用部署账号
不建议使用 root 直接运行 Composer、Git 或应用命令。创建一个只用于部署的账号,并加入 www-data 组:
sudo adduser --disabled-password --gecos "" deploy
sudo usermod -aG www-data deploy
id deploy
如果服务器已经存在 deploy 用户,跳过 adduser,只执行组权限调整。
创建网站目录:
sudo install -d -o deploy -g www-data -m 0750 /var/www/example.jp
sudo install -d -o deploy -g www-data -m 0750 /var/www/example.jp/releases
sudo install -d -o deploy -g www-data -m 0750 /var/www/example.jp/shared
检查目录权限:
namei -l /var/www/example.jp
ls -ld /var/www/example.jp /var/www/example.jp/releases /var/www/example.jp/shared
Nginx 进程用户通常为 www-data,它需要对网站目录具备遍历和读取权限;部署账号需要具备写入发布目录的权限。不要直接把网站目录设置为 777,也不要让 Nginx 进程拥有整个发布目录的写权限。
2. 获取网站代码
以下示例从 Git 仓库部署,使用占位地址:
STAMP=$(date +%Y%m%d%H%M%S)
RELEASE="/var/www/example.jp/releases/${STAMP}"
sudo -u deploy git clone \
--depth 1 \
--branch main \
https://git.example.com/your-team/your-php-site.git \
"$RELEASE"
test -f "$RELEASE/composer.json" && echo "composer.json exists"
test -d "$RELEASE/public" && echo "public directory exists"
如果仓库是私有仓库,应为 deploy 用户配置只读部署密钥,或者使用服务器端的安全凭据管理方式。不要把长期访问令牌直接写入 Git URL、Shell 历史或公开脚本。
如果使用压缩包上传,先在临时目录解压,再移动到新的 releases 子目录。不要直接覆盖 current,避免上传过程中 Nginx 读取到不完整文件。
3. 安装 Composer 依赖
进入新版本目录,以 deploy 用户执行 Composer:
sudo -u deploy composer install \
--working-dir="$RELEASE" \
--no-dev \
--prefer-dist \
--optimize-autoloader \
--no-interaction
如果生产环境必须执行构建脚本,应按照项目文档补充前端构建或缓存生成命令。检查依赖是否完整:
sudo -u deploy bash -c "cd '$RELEASE' && php -r 'require \"vendor/autoload.php\"; echo \"autoload ok\n\";'"
预期输出:
autoload ok
如果出现 Class ... not found,常见原因是 Composer 依赖没有安装、PHP 扩展缺失或生产依赖被错误排除。先查看完整错误,不要通过修改 Nginx 来解决 PHP 依赖问题。
四、配置 PHP 运行参数与 PHP-FPM
1. 添加站点级 PHP 配置
PHP-FPM 和 PHP CLI 可以使用不同配置。网站请求使用 PHP-FPM,因此应修改 /etc/php/8.3/fpm/conf.d/ 下的配置,而不是只修改 CLI 配置。
先备份已有同名配置:
PHP_INI="/etc/php/8.3/fpm/conf.d/99-example-site.ini"
if [ -f "$PHP_INI" ]; then
sudo cp -a "$PHP_INI" "${PHP_INI}.bak.$(date +%Y%m%d%H%M%S)"
fi
写入适合中小型 PHP 网站的示例配置:
sudo tee "$PHP_INI" > /dev/null <<'EOF'
memory_limit = 256M
upload_max_filesize = 32M
post_max_size = 32M
max_execution_time = 60
max_input_time = 60
date.timezone = Asia/Tokyo
expose_php = Off
cgi.fix_pathinfo = 0
opcache.enable = 1
opcache.validate_timestamps = 0
opcache.memory_consumption = 128
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 20000
EOF
这些值是示例起点,不代表所有应用都适用:
post_max_size应不小于upload_max_filesize。- 如果应用接收大文件,应同时调整 Nginx 的
client_max_body_size。 opcache.validate_timestamps = 0适合代码发布后重启或重新加载 PHP-FPM 的生产环境。开发环境不建议关闭自动检查。memory_limit不是越大越好。应结合应用实际内存使用和 PHP-FPM 并发数调整。
检查配置语法:
php-fpm8.3 -t
预期输出类似:
[NOTICE] configuration file /etc/php/8.3/fpm/php-fpm.conf test is successful
2. 调整 PHP-FPM 进程池
先备份默认进程池配置:
sudo cp -a \
/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)
查看当前关键参数:
grep -E '^(listen|pm|pm\.|request_terminate_timeout|catch_workers_output)' \
/etc/php/8.3/fpm/pool.d/www.conf
使用编辑器打开:
sudoedit /etc/php/8.3/fpm/pool.d/www.conf
针对一台内存约 2 GB、以动态 PHP 请求为主的服务器,可以将关键项调整为以下示例值:
[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 = 16
pm.start_servers = 3
pm.min_spare_servers = 2
pm.max_spare_servers = 5
pm.max_requests = 500
request_terminate_timeout = 60s
catch_workers_output = yes
不要直接套用 pm.max_children = 16 到所有服务器。可以按照以下方式估算:
可分配给 PHP-FPM 的内存 ÷ 单个 PHP-FPM 进程平均内存
= 建议的 max_children 上限
例如,服务器内存为 2 GB,预留 700 MB 给系统、Nginx、数据库和缓存,PHP-FPM 平均每个进程占用约 60 MB,则:
(2048 - 700) MB ÷ 60 MB ≈ 22
考虑突发内存和其他进程后,可以先设置为 16,再通过 ps、系统监控和 OOM 日志观察。若出现 server reached pm.max_children,不应只盲目增大进程数,还要确认服务器是否有足够内存。
验证并重启 PHP-FPM:
sudo php-fpm8.3 -t
sudo systemctl restart php8.3-fpm
sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock
restart 会中断正在处理的 PHP 请求,正式环境应安排在维护窗口;后续仅修改可热加载配置时,优先使用 reload。
五、准备数据库与应用环境变量
1. 安装 MariaDB(仅适用于需要数据库的网站)
如果网站使用 SQLite、外部数据库或其他数据库服务,可以跳过本节。需要在本机运行 MariaDB 时执行:
sudo apt install -y mariadb-server mariadb-client
sudo systemctl enable --now mariadb
sudo systemctl status mariadb --no-pager
执行基础安全检查:
sudo mariadb-secure-installation
该命令是交互式操作,具体选项应根据现有环境确认。不要在已有生产数据库上盲目删除账号或修改认证方式。
创建应用数据库和专用用户:
sudo mariadb
在 MariaDB 提示符中执行以下 SQL,并替换数据库名、用户名和密码:
CREATE DATABASE appdb
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
CREATE USER 'appuser'@'localhost'
IDENTIFIED BY '请替换为长度足够的随机密码';
GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;
验证账号可以连接:
mariadb -u appuser -p -h localhost appdb -e "SELECT VERSION();"
数据库不需要对公网开放。检查监听地址:
sudo ss -lntp | grep 3306 || true
如果 MariaDB 只监听 127.0.0.1 或 Unix Socket,应用可以在本机访问,外部主机无法直接连接。不要为了远程管理而直接开放 3306;确有跨服务器连接需求时,应使用受控的内网地址、来源限制和独立账号。
2. 创建生产环境配置
如果项目使用 .env,先从示例文件创建共享配置。以下命令不会覆盖已有的生产配置:
if [ ! -f /var/www/example.jp/shared/.env ]; then
sudo -u deploy cp \
"$RELEASE/.env.example" \
/var/www/example.jp/shared/.env
fi
sudo chown deploy:www-data /var/www/example.jp/shared/.env
sudo chmod 0640 /var/www/example.jp/shared/.env
打开配置文件:
sudoedit /var/www/example.jp/shared/.env
一个常见的生产环境配置示例:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.jp
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=appdb
DB_USERNAME=appuser
DB_PASSWORD=请替换为数据库密码
不要把真实密码提交到 Git 仓库,也不要将 .env 放在 public 目录下。确认应用是否要求其他变量,例如缓存、邮件、对象存储或队列配置。
将共享环境文件链接到当前版本:
sudo -u deploy ln -sfn \
../../shared/.env \
"$RELEASE/.env"
ls -l "$RELEASE/.env"
如果项目不使用 .env,应按照项目自身配置机制处理,不要强行创建无效文件。
3. 处理应用可写目录
大部分 PHP 应用不需要让整个代码目录可写,只需要给缓存、日志、上传目录设置组写权限。以下命令只处理存在的常见目录:
sudo chown -R deploy:www-data "$RELEASE"
sudo chmod -R g+rX,o-rwx "$RELEASE"
for DIR in storage bootstrap/cache var/cache runtime public/uploads; do
if [ -d "$RELEASE/$DIR" ]; then
sudo chmod -R g+rwX,o-rwx "$RELEASE/$DIR"
fi
done
不同框架的目录要求不同:
- Laravel 常见可写目录为
storage和bootstrap/cache。 - Symfony 通常需要
var。 - 其他框架可能使用
runtime、cache或自定义上传目录。
不要为了消除权限错误而执行 chmod -R 777。如果应用仍然无法写入,先从错误日志确认具体路径,再只调整该目录。
4. 执行应用初始化命令
框架命令必须根据项目实际情况选择,不要把不同框架的命令全部执行。
Laravel 示例:
sudo -u deploy bash -c "cd '$RELEASE' && php artisan config:cache"
sudo -u deploy bash -c "cd '$RELEASE' && php artisan route:cache"
sudo -u deploy bash -c "cd '$RELEASE' && php artisan view:cache"
如果需要数据库迁移,先备份数据库,再执行:
sudo install -d -m 0700 /var/backups/example.jp
sudo mariadb-dump \
--single-transaction \
--routines \
--triggers \
appdb | sudo tee \
"/var/backups/example.jp/appdb-$(date +%Y%m%d%H%M%S).sql" > /dev/null
sudo -u deploy bash -c "cd '$RELEASE' && php artisan migrate --force"
Symfony 示例:
sudo -u deploy bash -c \
"cd '$RELEASE' && APP_ENV=prod php bin/console cache:clear"
数据库迁移可能修改表结构,通常不能仅通过切回旧代码恢复。涉及不可逆字段删除、数据转换或大批量更新时,应单独制定数据库回滚方案,并在低峰期执行。
六、配置 Nginx 虚拟主机
1. 编写站点配置
先确认当前配置文件是否已存在。覆盖前先备份:
if [ -f /etc/nginx/sites-available/example.jp ]; then
sudo cp -a \
/etc/nginx/sites-available/example.jp \
/etc/nginx/sites-available/example.jp.bak.$(date +%Y%m%d%H%M%S)
fi
写入 HTTP 配置:

sudo tee /etc/nginx/sites-available/example.jp > /dev/null <<'EOF'
server {
listen 80;
listen [::]:80;
server_name example.jp www.example.jp;
root /var/www/example.jp/current/public;
index index.php index.html;
access_log /var/log/nginx/example.jp.access.log;
error_log /var/log/nginx/example.jp.error.log warn;
client_max_body_size 32m;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
try_files $uri =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_read_timeout 60s;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
EOF
配置中的关键点如下:
root指向current/public,而不是整个项目目录。try_files $uri =404防止把不存在的 PHP 路径交给 PHP-FPM。fastcgi_pass必须与实际 PHP-FPM Socket 一致。client_max_body_size应与 PHP 的上传限制配合。- 禁止访问隐藏文件,
.well-known例外是为了支持证书验证。 - 如果应用不是单入口结构,应按照框架文档调整
try_files,不要强制使用/index.php。
2. 启用站点并检查语法
sudo ln -sfn \
/etc/nginx/sites-available/example.jp \
/etc/nginx/sites-enabled/example.jp
sudo nginx -t
预期输出:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
只有语法检查成功后才重新加载:
sudo systemctl reload nginx
sudo systemctl status nginx --no-pager
如果服务器只有这一个网站,可以将默认站点改名保存,而不是直接删除:
if [ -L /etc/nginx/sites-enabled/default ] || [ -f /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
如果同一台服务器还承载其他域名,不要执行上述移动操作。
3. 切换当前版本
确认发布目录中存在网站入口:
test -f "$RELEASE/public/index.php"
如果测试成功,创建新的临时软链接并原子切换:
NEXT="/var/www/example.jp/current.${STAMP}"
sudo ln -s "$RELEASE" "$NEXT"
sudo mv -Tf "$NEXT" /var/www/example.jp/current
readlink -f /var/www/example.jp/current
预期输出应为本次发布目录,例如:
/var/www/example.jp/releases/20250101010101
如果 public/index.php 不存在,不要强行切换。常见原因是项目根目录不是 public、代码未完整上传或构建步骤未完成。
七、配置 DNS、端口与 HTTPS
1. 配置并验证 DNS
在域名解析服务商处配置:
example.jp A 服务器公网 IPv4
www.example.jp CNAME example.jp
如果服务器明确支持 IPv6,再配置 AAAA 记录。不要在服务器没有可用 IPv6 时添加 AAAA,否则部分客户端可能优先访问 IPv6 并得到连接失败。
使用 dig 查询:
dig +short A example.jp
dig +short AAAA example.jp
dig +short A www.example.jp
返回的地址应与服务器实际公网地址一致。也可以在服务器上确认公网接口信息:
ip addr
ip route
DNS 记录尚未生效时,先不要申请证书。可以使用本机 Host 头测试 Nginx,不依赖公共 DNS:
curl -sS -D - -o /dev/null \
--resolve example.jp:80:127.0.0.1 \
http://example.jp/
预期返回 200、301 或应用本身的有效响应。如果返回 404,检查 server_name、root 和 current 指向;如果返回 502,重点检查 PHP-FPM。
2. 配置防火墙
防火墙调整可能导致 SSH 中断。执行前确认当前 SSH 端口;如果不是默认的 22 端口,应将下面的 22/tcp 替换为实际端口,并保持服务商控制台可用。
先允许 SSH、HTTP 和 HTTPS,再启用防火墙:
sudo ufw status numbered
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
预期规则至少包含:
22/tcp ALLOW
80/tcp ALLOW
443/tcp ALLOW
如果 SSH 使用固定管理网段,可以进一步限制来源,但必须先从新连接验证规则,再关闭旧连接。数据库端口通常不应加入 UFW 放行规则。
检查监听端口:
sudo ss -lntp
正常情况下,Nginx 监听 0.0.0.0:80、[::]:80,HTTPS 配置完成后还会监听 443;PHP-FPM 使用 Unix Socket,不应暴露 TCP 9000 端口。
3. 申请 HTTPS 证书
先安装 Certbot:
sudo apt install -y certbot python3-certbot-nginx
申请证书前确认:
example.jp已解析到本机。- 80 端口可以从公网访问。
- Nginx 的
server_name已包含域名。 - 云平台安全组同时放行了 80 和 443。
备份当前 Nginx 配置后申请证书:
sudo cp -a \
/etc/nginx/sites-available/example.jp \
/etc/nginx/sites-available/example.jp.before-certbot.$(date +%Y%m%d%H%M%S)
sudo certbot --nginx \
-d example.jp \
-d www.example.jp
根据交互提示选择是否将 HTTP 重定向到 HTTPS。Certbot 会修改 Nginx 配置,修改后立即检查:
sudo nginx -t
sudo systemctl reload nginx
验证 HTTPS:
curl -I https://example.jp/
如果需要查看证书有效期:
echo | openssl s_client \
-connect example.jp:443 \
-servername example.jp 2>/dev/null \
| openssl x509 -noout -subject -issuer -dates
验证自动续期:
sudo systemctl list-timers | grep certbot
sudo certbot renew --dry-run
如果证书申请失败,优先检查 DNS、80 端口、云安全组和 Nginx 的域名配置,不要重复申请大量证书。
八、验证 PHP-FPM 与网站请求
1. 验证 PHP-FPM Socket
systemctl is-active php8.3-fpm
test -S /run/php/php8.3-fpm.sock && echo "PHP-FPM socket exists"
如果 Socket 不存在:
sudo journalctl -u php8.3-fpm -n 100 --no-pager
sudo php-fpm8.3 -t
如果 php-fpm8.3 -t 成功但服务没有运行,继续查看系统日志和端口、权限冲突。
2. 使用临时 PHP 文件验证 Nginx 到 FPM
为了验证完整请求链路,可以在公开目录创建一个临时检查文件:
CHECK_FILE="/var/www/example.jp/current/public/__fpm_check.php"
printf '%s\n' '<?php echo "php-fpm-ok\n";' \
| sudo tee "$CHECK_FILE" > /dev/null
sudo chown deploy:www-data "$CHECK_FILE"
sudo chmod 0640 "$CHECK_FILE"
curl -fsS https://example.jp/__fpm_check.php
预期输出:
php-fpm-ok
验证成功后,必须删除这个仅用于测试的文件。下面的删除命令只允许针对刚才创建的精确路径执行,确认路径无误后再运行:
sudo rm -- /var/www/example.jp/current/public/__fpm_check.php
删除该文件不会影响应用其他代码;如果路径不一致,不要执行命令。再次确认:
curl -I https://example.jp/__fpm_check.php
预期返回 404。
3. 验证首页、静态文件和隐藏文件保护
curl -I https://example.jp/
curl -I https://example.jp/robots.txt
curl -I https://example.jp/.env
常见预期结果:
- 首页返回
200、应用重定向的301/302,或登录页的有效状态码。 - 存在的静态文件返回
200。 .env等隐藏文件返回403或404,不应返回文件内容。
检查 Nginx 和 PHP-FPM 日志:
sudo tail -n 100 /var/log/nginx/example.jp.error.log
sudo tail -n 100 /var/log/nginx/example.jp.access.log
sudo journalctl -u php8.3-fpm -n 100 --no-pager
应用日志通常位于项目的 storage/logs、var/log 或其他框架指定目录。首页能打开但登录、上传、数据库查询失败时,应结合应用日志判断,不要只看 Nginx 日志。
九、常见异常及处理顺序
1. 域名无法访问
先从外部网络检查解析和端口:
dig +short A example.jp
curl -I --connect-timeout 5 http://example.jp/
curl -I --connect-timeout 5 https://example.jp/
按结果判断:
dig地址错误:修正 A 或 AAAA 记录。- DNS 正确但连接超时:检查云安全组、UFW、服务商网络和 Nginx 监听地址。
- HTTP 可以访问、HTTPS 超时:检查 443 端口和证书配置。
- 本机
curl --resolve成功、外部访问失败:问题通常在 DNS、云防火墙或公网路由,不在 PHP-FPM。
2. 返回 502 Bad Gateway
502 通常表示 Nginx 无法正常连接或读取 PHP-FPM。按由外到内的顺序检查:

sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock
grep -R "fastcgi_pass" /etc/nginx/sites-enabled/example.jp
sudo tail -n 100 /var/log/nginx/example.jp.error.log
对应关系:
- Socket 不存在:PHP-FPM 未启动、配置测试失败或服务名不匹配。
- Socket 存在但权限错误:检查
listen.owner、listen.group、Nginx 用户。 fastcgi_pass路径不一致:改为实际 Socket 路径后执行nginx -t。- PHP-FPM 频繁退出:检查内存、扩展加载错误和 FPM 日志。
- 请求超时:检查数据库、外部服务、死循环和
request_terminate_timeout,不要只增加 Nginx 超时时间。
3. 返回 403 或 404
检查 Nginx 实际加载的配置和网站目录:
sudo nginx -T | sed -n '/server_name example.jp/,/^[[:space:]]*}/p'
readlink -f /var/www/example.jp/current
namei -l /var/www/example.jp/current/public/index.php
重点确认:
root是否指向正确的public目录。current是否指向包含完整代码的发布版本。- 目录链路是否允许
www-data遍历。 index.php是否存在。- 应用路由是否需要
/index.php?$query_string。 - 是否错误地把隐藏文件规则应用到了正常资源。
4. 页面显示“权限不足”或无法写入缓存
查看应用报错中的具体路径,然后只对必要目录赋予组写权限:
sudo -u www-data test -w /var/www/example.jp/current/storage \
&& echo "storage writable" \
|| echo "storage not writable"
如果目录确实需要写入:
sudo chown -R deploy:www-data /var/www/example.jp/current/storage
sudo chmod -R g+rwX,o-rwx /var/www/example.jp/current/storage
不要把整个项目目录改为可写。上传目录还应考虑文件类型校验、执行权限和访问策略,不能只依赖 Unix 权限。
5. 数据库连接失败
先在服务器上用应用账号测试连接:
mariadb -u appuser -p -h localhost appdb -e "SELECT 1;"
再检查环境变量是否被应用读取:
grep -E '^(DB_HOST|DB_PORT|DB_DATABASE|DB_USERNAME)=' \
/var/www/example.jp/shared/.env
常见原因包括:
DB_HOST使用了127.0.0.1,但数据库账号只创建为'appuser'@'localhost'。- 数据库名、用户名或密码错误。
- PHP-FPM 没有加载更新后的
.env,需要重新加载或重启 PHP-FPM。 - 缺少
php8.3-mysql扩展。 - 应用缓存了旧配置。
修改配置后执行:
sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpm
如果框架有配置缓存,还要重新执行对应的缓存清理或构建命令。
6. 上传文件返回 413
检查 Nginx 和 PHP 限制:
sudo nginx -T | grep -n "client_max_body_size"
php -i | grep -E 'upload_max_filesize|post_max_size'
例如需要允许 64 MB 上传时,Nginx 和 PHP-FPM 都要配置到不小于该值。修改后分别验证:
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl reload php8.3-fpm
还要确认应用自身是否有更小的上传限制。
十、上线验收与回滚检查项
1. 上线验收清单
上线前逐项记录结果:
- [ ]
cat /etc/os-release确认系统版本符合部署方案。 - [ ]
php -v、php-fpm8.3 -v、nginx -v和composer --version正常。 - [ ]
systemctl is-active nginx返回active。 - [ ]
systemctl is-active php8.3-fpm返回active。 - [ ]
/run/php/php8.3-fpm.sock存在,且 Nginx 配置使用了同一路径。 - [ ]
nginx -t通过。 - [ ]
readlink -f /var/www/example.jp/current指向预期发布版本。 - [ ] 网站入口文件位于
current/public。 - [ ]
example.jp的 A、AAAA 记录与服务器实际地址一致。 - [ ] 80、443 和 SSH 端口符合预期,未对公网开放不必要的数据库端口。
- [ ] HTTPS 证书域名、有效期和自动续期测试正常。
- [ ] 首页、静态文件、登录、表单提交和文件上传分别验证。
- [ ]
.env、隐藏文件和源码内部目录不能通过浏览器读取。 - [ ] 应用日志、Nginx 日志和 PHP-FPM 日志没有持续新增的致命错误。
- [ ] 数据库备份文件可以找到,并记录了备份时间。
- [ ] 旧版本发布目录仍然保留,尚未清理。
2. 应用代码回滚
先查看当前版本和可用发布版本:
readlink -f /var/www/example.jp/current
ls -1dt /var/www/example.jp/releases/*
选择已验证的上一版本,例如:
PREVIOUS="/var/www/example.jp/releases/20250101010101"
test -f "$PREVIOUS/public/index.php"
确认入口存在后切换:
ROLLBACK_LINK="/var/www/example.jp/current.rollback.$(date +%Y%m%d%H%M%S)"
sudo ln -s "$PREVIOUS" "$ROLLBACK_LINK"
sudo mv -Tf "$ROLLBACK_LINK" /var/www/example.jp/current
readlink -f /var/www/example.jp/current
sudo systemctl reload nginx
sudo systemctl reload php8.3-fpm
切换代码后立即验证首页、登录和关键业务。若新版本已经执行数据库迁移,代码回滚不等于数据库回滚,必须根据迁移记录和备份单独处理。
3. Nginx 配置回滚
如果修改 Nginx 后出现配置错误,先查看最近的备份:
ls -lt /etc/nginx/sites-available/example.jp*
恢复前先保留当前文件:
sudo cp -a \
/etc/nginx/sites-available/example.jp \
/etc/nginx/sites-available/example.jp.failed.$(date +%Y%m%d%H%M%S)
再恢复指定备份,例如:
sudo cp -a \
/etc/nginx/sites-available/example.jp.before-certbot.20250101010101 \
/etc/nginx/sites-available/example.jp
sudo nginx -t
sudo systemctl reload nginx
只有 nginx -t 成功后才执行 reload。若测试失败,Nginx 通常仍会继续使用旧的已加载配置,但不要因此忽略错误日志。
4. PHP-FPM 配置回滚
恢复前先检查备份文件内容和时间:
ls -lt /etc/php/8.3/fpm/conf.d/99-example-site.ini*
ls -lt /etc/php/8.3/fpm/pool.d/www.conf*
恢复配置后验证:
sudo cp -a \
/etc/php/8.3/fpm/pool.d/www.conf.bak.20250101010101 \
/etc/php/8.3/fpm/pool.d/www.conf
sudo php-fpm8.3 -t
sudo systemctl restart php8.3-fpm
sudo systemctl status php8.3-fpm --no-pager
重启 PHP-FPM 会终止当前 PHP 请求,回滚时应确认业务影响。
5. 数据库回滚边界
数据库恢复属于高风险操作,必须确认:
- 备份文件完整且时间正确。
- 已停止或暂停会继续写入数据的应用任务。
- 已明确恢复会覆盖哪些数据。
- 已获得业务负责人确认。
- 恢复后应用代码版本与数据库结构相匹配。
不要直接执行 DROP DATABASE 或覆盖生产库进行试错。对于可逆的应用代码问题,优先回滚 current;只有确认数据库结构或数据已经受损时,才进入数据库恢复流程。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3546.html



