日本服务器部署ThinkPHP项目,运行环境与入口配置怎样安排?

发布人:A5数据发布时间:2026-10-19 14:22阅读量:126

日本服务器上首次运行 ThinkPHP 项目,重点不是改变框架的部署方式,而是把 PHP 版本、PHP-FPM 服务、Nginx 入口和项目可写目录对应起来。常见的稳定组合是 Linux + Nginx + PHP-FPM + Composer,Nginx 的站点根目录应指向项目的 public,而不是包含 vendor、.env 和配置文件的项目根目录。

下面以 Ubuntu 22.04、Nginx、PHP 8.1、ThinkPHP 项目和域名 app.example.jp 为示例。PHP 版本、FPM Socket 路径和 ThinkPHP 版本必须以实际项目的 composer.json、composer.lock 及服务器可用软件包为准;如果服务器是 Ubuntu 24.04,通常应使用系统提供的 PHP 8.3,并同步调整命令和配置中的版本号。

面向日本地区的 ThinkPHP 网站、业务后台、数据库与接口服务,A5数据提供日本物理服务器资源,覆盖 Xeon Gold、AMD EPYC 及 NVMe 存储配置,并结合 50Mbps CN2、250Mbps 国际带宽以及 CIA、GIA、SoftBank 等线路方案,支持从常规建站到多任务业务运行的部署需求。

一、部署前确认环境与项目入口

1. 确认服务器系统、PHP和网络条件

先确认操作系统、架构、当前 PHP 版本以及可用的 PHP-FPM Socket,不要直接根据服务器名称猜测软件版本。

cat /etc/os-release
uname -m
php -v 2>/dev/null || true
ls -l /run/php/ 2>/dev/null || true

示例输出可能类似:

Ubuntu 22.04.4 LTS
x86_64
PHP 8.1.28 (cli) ...
srw-rw---- 1 www-data www-data ... php8.1-fpm.sock

如果没有安装 PHP,或者 /run/php/ 下没有对应的 FPM Socket,需要先完成 PHP-FPM 安装。后续 Nginx 中的 fastcgi_pass 必须使用实际存在的 Socket,例如:

/run/php/php8.1-fpm.sock
/run/php/php8.3-fpm.sock

同时确认域名解析。日本服务器的公网 IPv4 地址记为 <SERVER_IPV4>:

dig +short A app.example.jp
dig +short AAAA app.example.jp

如果 A 记录没有指向日本服务器,应先修正解析。若配置了 AAAA 记录,则服务器还必须具备可用的 IPv6 监听和网络,否则部分访问者可能优先通过 IPv6 访问失败。

2. 检查 ThinkPHP 项目的实际版本和入口

在项目源码目录执行:

cd /path/to/thinkphp-project

test -f composer.json && echo "composer.json: OK"
test -f public/index.php && echo "public/index.php: OK"
grep -n '"php"\|"topthink/framework"' composer.json

重点确认以下内容:

  • composer.json 中的 PHP 版本要求;
  • topthink/framework 的具体版本;
  • 项目是否存在 public/index.php;
  • 项目是否提供 .env.example;
  • 项目文档中是否指定了额外扩展或特殊的 Nginx 规则;
  • 是否存在 runtime、public/uploads 等需要 PHP-FPM 写入的目录。

ThinkPHP 常见入口是:

项目根目录/
├── app/
├── config/
├── public/
│   └── index.php
├── runtime/
├── vendor/
├── composer.json
└── .env

如果项目入口不在 public/index.php,不能直接套用下面的 Nginx 根目录配置,应以项目实际入口为准。尤其是旧项目、定制项目或从其他框架迁移的项目,目录结构可能不同。

3. 确认备份和回滚对象

首次部署前至少保留三类内容:

  • 项目源代码或 Git 标签;
  • .env、数据库连接信息和其他运行配置;
  • 数据库备份,尤其是后续准备执行迁移时。

不要把包含密码的 .env 提交到公共代码仓库。示例中的路径使用发布目录,便于后续保留上一版本:

/var/www/thinkphp-app/
├── current -> releases/2024060101
├── releases/
└── shared/
    └── .env

这种结构切换代码时只改变 current 软链接,不直接覆盖正在运行的目录,出现问题时更容易恢复。

二、安装PHP-FPM、Nginx和项目依赖

1. 安装与项目版本匹配的软件包

以下命令适用于 Ubuntu 22.04 使用 PHP 8.1 的示例环境:

sudo apt update

sudo apt install -y \
  nginx \
  php8.1-fpm \
  php8.1-cli \
  php8.1-common \
  php8.1-mysql \
  php8.1-curl \
  php8.1-mbstring \
  php8.1-xml \
  php8.1-zip \
  php8.1-gd \
  php8.1-intl \
  unzip \
  git \
  curl \
  composer

如果项目要求 PHP 8.2 或 8.3,应把上述包名统一替换为对应版本。不要只升级 CLI 而保留旧版本 FPM,否则命令行和网站请求可能使用不同的 PHP 环境。

验证已安装模块:

php -m | grep -Ei 'curl|fileinfo|mbstring|openssl|PDO|pdo_mysql|xml|zip'
systemctl is-active nginx
systemctl is-active php8.1-fpm

预期结果是 PHP 模块能够列出,且两个服务返回:

active

如果项目使用 PostgreSQL、Redis 或其他组件,还要依据 composer.json 和项目配置安装对应 PHP 扩展,不要为了“可能用到”而一次安装大量无关扩展。

2. 设置服务开机启动

sudo systemctl enable --now nginx
sudo systemctl enable --now php8.1-fpm

再次检查:

systemctl --no-pager --full status nginx
systemctl --no-pager --full status php8.1-fpm

如果 PHP-FPM 启动失败,先查看日志,不要继续修改 Nginx:

sudo journalctl -u php8.1-fpm -n 80 --no-pager

常见原因是 PHP 配置语法错误、扩展版本冲突或 Socket 路径与服务版本不一致。

3. 准备发布目录和部署用户

可以使用独立的系统用户保存项目文件,减少直接使用 root 运行 Composer 和应用命令的风险:

sudo adduser --system --group --home /var/www/thinkphp-app deploy 2>/dev/null || true

sudo install -d -o deploy -g deploy -m 0755 \
  /var/www/thinkphp-app \
  /var/www/thinkphp-app/releases \
  /var/www/thinkphp-app/shared

确认目录权限:

namei -l /var/www/thinkphp-app

Nginx 和 PHP-FPM 至少要能够穿过路径并读取 current/public 下的文件。不要直接对整个项目执行 chmod -R 777,这会扩大配置文件和源代码的写入范围。

三、上传代码并安装Composer依赖

1. 获取固定版本的项目代码

生产首次部署建议使用 Git 标签、提交号或经过确认的压缩包,而不是直接使用持续变化的开发分支。下面是 Git 仓库示例:

APP=/var/www/thinkphp-app
REL="$(date +%Y%m%d%H%M%S)"

sudo -u deploy git clone --depth 1 --branch <release-tag> \
  <repository-url> \
  "$APP/releases/$REL"

如果使用压缩包上传,应先将代码解压到类似以下目录:

/var/www/thinkphp-app/releases/2024060101/

确认发布目录包含项目入口和依赖描述文件:

sudo -u deploy test -f "$APP/releases/$REL/composer.json"
sudo -u deploy test -f "$APP/releases/$REL/public/index.php"

两条命令没有输出且退出码为 0,表示文件存在。若入口不存在,应先查清项目结构,不要把 Nginx 根目录指向未经确认的路径。

2. 创建运行配置

如果项目提供 .env.example,复制到共享目录:

sudo -u deploy cp \
  "$APP/releases/$REL/.env.example" \
  "$APP/shared/.env"

sudo chown deploy:www-data "$APP/shared/.env"
sudo chmod 640 "$APP/shared/.env"

编辑配置:

sudo -u deploy nano "$APP/shared/.env"

至少检查以下项目配置,具体键名以项目提供的 .env.example 为准:

APP_DEBUG = false
APP_TRACE = false

数据库、缓存和时区等内容应填写项目实际使用的配置。例如项目使用 ThinkPHP 常见的分组格式时,可能包含:

[APP]
DEFAULT_TIMEZONE = Asia/Tokyo

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = app_database
USERNAME = app_user
PASSWORD = change-this-password
HOSTPORT = 3306
CHARSET = utf8mb4

这些键名不能脱离项目模板自行创造。部署到日本服务器时,应用时区可以设为 Asia/Tokyo,但数据库、定时任务和日志时间也应保持一致。若团队统一使用 UTC,则保留 UTC 也可以,关键是前后端对时间的解释一致。

3. 安装Composer依赖

进入本次发布目录:

cd "$APP/releases/$REL"

sudo -u deploy composer validate --no-check-publish
sudo -u deploy composer install \
  --no-dev \
  --prefer-dist \
  --optimize-autoloader

生产环境使用 composer.lock 锁定依赖版本。验证平台要求:

sudo -u deploy composer check-platform-reqs

如果出现类似以下错误:

Your lock file does not contain a compatible set of packages

通常表示 PHP 主版本或扩展不符合项目要求。优先调整服务器 PHP 环境,不要使用 --ignore-platform-reqs 强行安装,因为依赖虽然可能安装成功,运行时仍可能出现致命错误。

验证 ThinkPHP CLI:

sudo -u deploy php think -h

正常情况下会显示 ThinkPHP 命令帮助。如果提示找不到 vendor/autoload.php,说明 Composer 安装未完成;如果提示扩展缺失,则根据错误信息补充对应 PHP 扩展。

4. 设置运行目录权限

ThinkPHP 通常需要写入 runtime。如果项目还要求写入上传目录,应只对明确的目录开放写权限:

sudo install -d -o deploy -g www-data -m 0775 \
  "$APP/releases/$REL/runtime"

sudo chown -R deploy:www-data "$APP/releases/$REL/runtime"
sudo chmod -R g+rwX "$APP/releases/$REL/runtime"

如果项目使用 public/uploads 保存上传文件:

sudo install -d -o deploy -g www-data -m 0775 \
  "$APP/releases/$REL/public/uploads"

sudo chown -R deploy:www-data "$APP/releases/$REL/public/uploads"
sudo chmod -R g+rwX "$APP/releases/$REL/public/uploads"

仅对项目明确需要写入的目录这样处理。config、app、vendor 和 .env 不应整体设置为可写。

四、配置PHP运行参数和日本时区

1. 分别配置CLI和PHP-FPM

如果项目使用日本本地时间,建议同时配置 CLI 和 FPM,避免命令行迁移、定时任务与 Web 请求显示不同时间。PHP 8.1 示例:

sudo tee /etc/php/8.1/fpm/conf.d/99-thinkphp.ini >/dev/null <<'EOF'
date.timezone = Asia/Tokyo
memory_limit = 256M
upload_max_filesize = 32M
post_max_size = 32M
max_execution_time = 60
EOF

sudo tee /etc/php/8.1/cli/conf.d/99-thinkphp.ini >/dev/null <<'EOF'
date.timezone = Asia/Tokyo
memory_limit = 256M
upload_max_filesize = 32M
post_max_size = 32M
max_execution_time = 60
EOF

其中上传大小和内存值只是示例,应按照项目文件大小和运行需求调整。post_max_size 通常应不小于 upload_max_filesize。

重启 PHP-FPM:

sudo systemctl restart php8.1-fpm

验证 CLI 时区和参数:

php -r 'echo date_default_timezone_get(), PHP_EOL;'
php -i | grep -E 'memory_limit|upload_max_filesize|post_max_size'

预期时区输出为:

Asia/Tokyo

如果服务器系统时间仍为 UTC,不代表 PHP 配置错误。应用时区、系统日志时区和数据库时区应分别确认,不要为了迁就单个应用而直接修改整台服务器的系统时区。

2. 切换当前发布版本

确认 public/index.php、vendor、.env 和 runtime 都已准备好后,再建立当前版本软链接:

APP=/var/www/thinkphp-app
REL=/var/www/thinkphp-app/releases/2024060101

if [ -e "$APP/current" ] && [ ! -L "$APP/current" ]; then
  echo "current 不是软链接,请先人工检查:$APP/current"
  exit 1
fi

sudo -u deploy ln -sfn "$REL" "$APP/current"

将命令中的 REL 替换为本次实际发布目录。验证:

readlink -f "$APP/current"
test -f "$APP/current/public/index.php" && echo "entry: OK"
test -f "$APP/current/vendor/autoload.php" && echo "vendor: OK"

五、配置Nginx入口

1. 编写站点配置

先备份已有配置。备份动作不会修改当前服务,但后续覆盖配置前必须确认备份路径正确:

sudo cp -a \
  /etc/nginx/sites-available/app.example.jp \
  "/etc/nginx/sites-available/app.example.jp.bak.$(date +%Y%m%d%H%M%S)" \
  2>/dev/null || true

创建站点配置:

sudo tee /etc/nginx/sites-available/app.example.jp >/dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;

    server_name app.example.jp;
    root /var/www/thinkphp-app/current/public;
    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?s=$uri&$args;
    }

    location ~ \.php$ {
        try_files $uri =404;

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param QUERY_STRING $query_string;
        fastcgi_param HTTP_PROXY "";
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
EOF

这里有三个关键点:

五、配置Nginx入口|编写站点配置配图

  1. root 指向 current/public,而不是 /var/www/thinkphp-app/current;
  2. try_files 将不存在的路径交给 public/index.php;
  3. fastcgi_pass 必须和实际 PHP-FPM Socket 一致。

ThinkPHP 项目若在官方文档或自身配置中提供了不同的 Nginx 重写规则,应以项目规则为准。/index.php?s=$uri&$args 是常见入口形式,不代表所有定制项目都完全相同。

启用站点:

sudo ln -sfn \
  /etc/nginx/sites-available/app.example.jp \
  /etc/nginx/sites-enabled/app.example.jp

sudo nginx -t

预期结果:

syntax is ok
test is successful

只有测试成功后才重新加载 Nginx:

sudo systemctl reload nginx

如果配置测试失败,Nginx 会保留原有运行配置,不应继续执行 reload。先检查版本号、括号、路径和 Socket 名称。

2. 验证入口转发

在服务器本机用 Host 头测试,能够区分 DNS 问题与 Nginx、PHP-FPM 问题:

curl -i \
  -H 'Host: app.example.jp' \
  http://127.0.0.1/

示例结果可能是:

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

项目返回 301、302、登录页或业务自定义状态码也可能是正常现象。关键是请求已经进入应用,而不是出现 Nginx 默认页、502 Bad Gateway 或 PHP 源码下载。

再从域名访问:

curl -i http://app.example.jp/

若服务器配置了正确的 A 记录,域名请求应与本机 Host 测试结果一致。

六、常见异常的判断顺序

1. 返回502 Bad Gateway

先确认 FPM 服务和 Socket:

systemctl is-active php8.1-fpm
ls -l /run/php/
sudo tail -n 80 /var/log/nginx/error.log

常见原因及处理方式:

  • php8.1-fpm 未启动:启动或查看 journalctl;
  • Nginx 配置写成 php8.3-fpm.sock,实际只有 php8.1-fpm.sock:统一版本;
  • Socket 权限异常:检查 PHP-FPM 运行用户和组;
  • PHP-FPM 已启动但进程不断退出:查看 FPM 日志和 PHP 配置错误。

不要通过把 Socket 权限改成 777 处理 502,这会扩大本地进程访问范围。

2. 所有路由都返回404

先确认 Nginx 根目录:

sudo nginx -T | grep -A12 -B3 'server_name app.example.jp'
readlink -f /var/www/thinkphp-app/current/public

需要重点检查:

  • root 是否指向 public;
  • public/index.php 是否真实存在;
  • location / 是否包含 try_files;
  • server_name 是否命中了正确的虚拟主机;
  • 项目路由是否要求其他入口参数。

若 / 能打开而 /user/profile 返回 Nginx 404,通常是重写规则或入口参数不匹配。若页面返回的是 ThinkPHP 自己的 404,则请求已经进入应用,应转而检查路由定义。

3. 返回500或页面空白

查看 Nginx、PHP-FPM 和项目运行日志:

sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u php8.1-fpm -n 100 --no-pager
sudo find /var/www/thinkphp-app/current/runtime \
  -type f -mmin -30 -print 2>/dev/null

常见原因包括:

  • PHP 扩展未安装;
  • .env 不存在、路径错误或权限不足;
  • 数据库主机、端口、账号或字符集配置错误;
  • runtime 不可写;
  • Composer 依赖与 PHP 版本不兼容。

生产环境应保持 APP_DEBUG=false,通过日志定位问题,不要为了显示堆栈而长期打开调试模式。

4. 数据库连接失败

先验证网络和账号,不要立即修改数据库结构。远程 MySQL 示例:

mysql --connect-timeout=5 \
  -h <DB_HOST> \
  -P 3306 \
  -u <DB_USER> \
  -p \
  -e 'SELECT 1;'

命令会提示输入密码,不应把密码直接写入 Shell 历史。若连接失败,分别检查:

  • 数据库是否只监听 127.0.0.1;
  • 日本服务器公网 IP 是否已加入数据库访问白名单;
  • 安全组或防火墙是否放行了必要来源;
  • .env 中端口、用户名和数据库名是否正确。

只允许日本服务器的固定公网 IP 访问数据库,不要为了测试把数据库端口对所有公网地址开放。

5. 日本地区访问异常或部分用户打不开

本机访问正常而域名访问异常时,优先检查 DNS:

dig +short A app.example.jp
dig +short AAAA app.example.jp

如果 IPv4 正常、IPv6 地址不正确,应修正或暂时移除错误的 AAAA 记录。通过域名访问时,还要确认域名命中了本次 Nginx 配置,而不是默认站点:

sudo nginx -T | grep -n 'server_name'

七、防火墙与基础安全核对

如果服务器启用了 UFW,调整规则前先确认当前状态,避免误操作导致 SSH 断开:

sudo ufw status verbose

只有确认 SSH 管理方式和端口无误后,才添加 Web 端口:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status numbered

如果需要撤销新增规则,应先使用 ufw status numbered 确认编号,再执行删除。防火墙规则变更影响整台服务器的入站访问,不应直接复制不明来源的批量命令。

站点入口还应完成以下检查:

curl -i http://app.example.jp/.env
curl -i http://app.example.jp/composer.json
curl -i http://app.example.jp/vendor/autoload.php

这些请求不应返回敏感文件内容。由于 Nginx 根目录已经指向 public,正常情况下它们应为 403 或 404。如果能看到 .env、Composer 配置或 PHP 源码,应立即停止对外访问,检查 root、隐藏文件规则和项目目录权限。

八、首次运行后的验收与回滚

1. 验收检查项

首次部署完成后,按以下顺序验收:

  • composer check-platform-reqs 无平台依赖错误;
  • php think -h 能正常输出命令帮助;
  • systemctl is-active nginx 返回 active;
  • systemctl is-active php8.1-fpm 返回 active;
  • nginx -t 返回测试成功;
  • readlink -f /var/www/thinkphp-app/current 指向本次发布目录;
  • public/index.php 和 vendor/autoload.php 存在;
  • 首页或健康检查地址能够返回预期状态;
  • 一个需要数据库的页面能够正常读取数据;
  • runtime 和项目明确指定的上传目录可写;
  • .env、composer.json、vendor 等敏感内容不能通过 HTTP 下载;
  • Nginx 和 PHP-FPM 日志中没有持续出现新的致命错误。

如果项目提供数据库迁移命令,应在数据库备份完成后,严格按照项目文档执行。迁移属于数据库结构变更,不能因为代码已经部署成功就自动执行。迁移失败时,回滚代码并不等于回滚数据库结构。

2. 应用代码回滚

保留上一版本发布目录时,可以先查看当前版本和可用版本:

APP=/var/www/thinkphp-app

readlink -f "$APP/current"
find "$APP/releases" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort

确认目标目录确实包含入口文件后,再切换软链接:

PREVIOUS=/var/www/thinkphp-app/releases/<previous-release>

test -f "$PREVIOUS/public/index.php" || {
  echo "目标版本入口不存在,停止回滚"
  exit 1
}

if [ -e "$APP/current" ] && [ ! -L "$APP/current" ]; then
  echo "current 不是软链接,停止回滚"
  exit 1
fi

sudo -u deploy ln -sfn "$PREVIOUS" "$APP/current"
sudo nginx -t
sudo systemctl reload nginx

回滚后重新执行首页、数据库页面和静态资源检查。旧版本如果依赖不同的数据库字段,不能仅凭软链接切换判断回滚成功。

3. 配置和数据库回滚边界

Nginx 配置回滚应使用部署前保存的备份文件,恢复后重新执行:

sudo nginx -t
sudo systemctl reload nginx

.env 回滚前要确认备份内容与目标代码版本匹配,尤其是数据库、缓存和应用模式配置。

数据库回滚需要单独依据备份和迁移工具执行:

  • 先确认迁移是否已经改变表结构或数据;
  • 使用项目提供的反向迁移命令,不能自行猜测命令名称;
  • 涉及数据删除或覆盖时,先保留当前数据库备份;
  • 如果没有可验证的反向迁移方案,应优先恢复代码兼容当前数据库,而不是直接恢复生产数据库。

完成验收后再清理旧发布目录。旧版本、配置备份和数据库备份在未确认新版本稳定前不应删除,这些内容是首次部署失败时的主要回滚依据。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4615.html

相关推荐