PHP网站部署到日本服务器,如何配置Nginx与PHP-FPM?

发布人:A5数据发布时间:2026-10-13 17:11阅读量:177

日本服务器上部署 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. 目标架构

本次部署完成后,请求链路如下:

一、部署目标与准备条件 / 1. 目标架构配图

浏览器
  ↓ HTTPS
Nginx:80/443
  ↓ Unix Socket
PHP 8.3-FPM
  ↓
PHP 网站代码
  ↓
MariaDB(如果应用需要)

Nginx 负责域名匹配、静态文件、HTTPS 和请求转发;PHP-FPM 负责执行 PHP 文件;网站代码的公开入口使用 public 目录,避免 .env、依赖目录或其他内部文件被直接访问。

建议使用以下目录结构:

一、部署目标与准备条件 / 1. 目标架构配图

/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 配置:

六、配置 Nginx 虚拟主机 / 1. 编写站点配置配图

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。按由外到内的顺序检查:

九、常见异常及处理顺序 / 2. 返回 502 Bad Gateway配图

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

相关推荐