420 lines
17 KiB
Markdown
420 lines
17 KiB
Markdown
# 11.10 故障排查手册
|
||
|
||
:::tip 排查思路
|
||
遇到问题时，按以下顺序排查：
|
||
1. 查看 PHP 错误日志（`/var/log/php_errors.log`）
|
||
2. 查看 Nginx 错误日志（`/var/log/nginx/error.log`）
|
||
3. 查看浏览器控制台（F12）
|
||
4. 检查 `.env` 配置是否正确
|
||
:::
|
||
|
||
## 服务器问题
|
||
|
||
### 502 Bad Gateway
|
||
|
||
PHP-FPM 未启动或配置错误：
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 PHP-FPM 服务状态
|
||
# -----------------------------------------------------------------------------
|
||
# status → 显示服务是否正在运行、主进程 PID、内存占用等
|
||
sudo systemctl status php8.2-fpm
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 重启 PHP-FPM（最常见的修复方式）
|
||
# -----------------------------------------------------------------------------
|
||
# restart → 停止后重新启动，所有正在处理的请求会被中断
|
||
sudo systemctl restart php8.2-fpm
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 实时查看 PHP-FPM 错误日志（Ctrl+C 退出）
|
||
# -----------------------------------------------------------------------------
|
||
# -f → follow 模式，持续输出新增日志
|
||
sudo tail -f /var/log/php8.2-fpm.log
|
||
```
|
||
|
||
### 500 Internal Server Error
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 查看 PHP 错误日志（定位 PHP 脚本执行错误）
|
||
# -----------------------------------------------------------------------------
|
||
# tail -f → 实时输出新增日志行
|
||
sudo tail -f /var/log/php_errors.log
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 查看 Nginx 错误日志（定位 Nginx 层错误）
|
||
# -----------------------------------------------------------------------------
|
||
sudo tail -f /var/log/nginx/error.log
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查运行时目录权限（500 错误常见原因）
|
||
# -----------------------------------------------------------------------------
|
||
# -la → 显示详细信息（包括隐藏文件）
|
||
ls -la /www/api/runtime/
|
||
```
|
||
|
||
### 404 Not Found
|
||
|
||
Nginx URL 重写配置错误：
|
||
|
||
```nginx
|
||
# 检查 try_files 或 rewrite 规则
|
||
# $uri → 当前请求的文件路径
|
||
# $uri/ → 当前请求的目录路径
|
||
# /index.php?s=$uri&$args → 回退到 ThinkPHP 入口，传递原始路径和参数
|
||
location / {
|
||
try_files $uri $uri/ /index.php?s=$uri&$args;
|
||
}
|
||
```
|
||
|
||
## 数据库问题
|
||
|
||
### MySQL 连接失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 MySQL 服务状态
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl status mysql
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 测试数据库连接（SELECT 1 是最简单的查询，验证连接是否正常）
|
||
# -----------------------------------------------------------------------------
|
||
mysql -u root -p -e "SELECT 1"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查用户权限（查看所有用户及其允许的连接来源）
|
||
# -----------------------------------------------------------------------------
|
||
# user → 用户名，host → 允许连接的主机（% 表示任意）
|
||
mysql -u root -p -e "SELECT user, host FROM mysql.user;"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 允许远程连接（生产环境慎用，建议通过 SSH 隧道连接）
|
||
# -----------------------------------------------------------------------------
|
||
# GRANT ALL → 授权所有权限
|
||
# ON `数据库`.* → 指定数据库的所有表
|
||
# TO 'root'@'%' → 允许从任意主机连接的 root 用户
|
||
# IDENTIFIED BY → 设置密码
|
||
mysql -u root -proot -e "GRANT ALL ON \`rxthinkcmf.thinkphp8.elevue\`.* TO 'root'@'%' IDENTIFIED BY 'root';"
|
||
mysql -u root -p -e "FLUSH PRIVILEGES;" # 刷新权限使配置生效
|
||
```
|
||
|
||
### PostgreSQL 连接失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 PostgreSQL 服务状态
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl status postgresql
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 测试连接（-U 指定用户，-d 指定数据库，-c 执行 SQL）
|
||
# -----------------------------------------------------------------------------
|
||
psql -U postgres -d rxthinkcmf.thinkphp8.elevue -c "SELECT 1;"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查客户端认证配置（pg_hba.conf 控制哪些 IP 可以连接）
|
||
# -----------------------------------------------------------------------------
|
||
sudo nano /etc/postgresql/*/main/pg_hba.conf
|
||
# 添加以下行允许所有 IP 通过密码连接：
|
||
# host all all 0.0.0.0/0 md5
|
||
|
||
# 重启使配置生效
|
||
sudo systemctl restart postgresql
|
||
```
|
||
|
||
### SQLite 连接失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 SQLite 数据库文件是否存在
|
||
# -----------------------------------------------------------------------------
|
||
# -la → 显示文件大小、权限、修改时间
|
||
ls -la /www/api/runtime/database.sqlite
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 修复文件权限（确保 Web 服务器用户可读写）
|
||
# -----------------------------------------------------------------------------
|
||
# 664 → owner/group 可读写，others 只读
|
||
chmod 664 /www/api/runtime/database.sqlite
|
||
chown www-data:www-data /www/api/runtime/database.sqlite
|
||
```
|
||
|
||
### SQL Server 连接失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 SQL Server 服务状态
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl status mssql-server
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 测试连接（-S 服务器，-U 用户，-P 密码，-Q 执行查询）
|
||
# -----------------------------------------------------------------------------
|
||
sqlcmd -S localhost -U sa -P root -Q "SELECT 1"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 PHP 的 SQL Server 扩展是否安装
|
||
# -----------------------------------------------------------------------------
|
||
php -m | grep pdo_sqlsrv # 查找 pdo_sqlsrv 扩展
|
||
```
|
||
|
||
### 数据库表不存在
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 重新导入初始化 SQL（按数据库类型选择对应命令）
|
||
# -----------------------------------------------------------------------------
|
||
|
||
# MySQL：通过 mysql 命令导入 SQL 文件
|
||
mysql -u root -proot rxthinkcmf.thinkphp8.elevue < document/mysql/rxthinkcmf.thinkphp8.elevue.sql
|
||
|
||
# PostgreSQL：通过 psql 命令导入 SQL 文件
|
||
# -U 指定用户，-d 指定数据库，-f 指定 SQL 文件
|
||
psql -U postgres -d rxthinkcmf.thinkphp8.elevue -f document/postgresql/rxthinkcmf.thinkphp8.elevue.sql
|
||
|
||
# SQLite：通过 sqlite3 命令导入 SQL 文件
|
||
sqlite3 /www/api/runtime/database.sqlite < document/sqlite/rxthinkcmf.thinkphp8.elevue.sql
|
||
```
|
||
|
||
## PHP 问题
|
||
|
||
### 缺少扩展
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 查看已安装的 PHP 扩展列表
|
||
# -----------------------------------------------------------------------------
|
||
php -m # 列出所有已加载的扩展
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 安装缺失的扩展（按数据库类型选择）
|
||
# -----------------------------------------------------------------------------
|
||
sudo apt install php8.2-mysql # MySQL 驱动（pdo_mysql）
|
||
# sudo apt install php8.2-pgsql # PostgreSQL 驱动（取消注释以安装）
|
||
# sudo apt install php8.2-sqlite3 # SQLite 驱动（取消注释以安装）
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 重启 PHP-FPM 使新扩展生效
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl restart php8.2-fpm
|
||
```
|
||
|
||
### 内存不足
|
||
|
||
```ini
|
||
; php.ini — 增加单脚本最大内存限制
|
||
; 默认 128M，Excel 导出等大内存操作建议设为 256M 或更高
|
||
memory_limit = 256M
|
||
```
|
||
|
||
### 执行超时
|
||
|
||
```ini
|
||
; php.ini — 增加单脚本最大执行时间
|
||
; 默认 30 秒，长时间操作（如数据迁移）建议设为 300 秒
|
||
max_execution_time = 300
|
||
```
|
||
|
||
## 权限问题
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 修复项目目录权限（owner 为 Web 服务器用户）
|
||
# -----------------------------------------------------------------------------
|
||
# chown → 修改文件所有者（-R 递归）
|
||
# chmod → 修改文件权限（755 = owner 全权限，group/others 可读可执行）
|
||
sudo chown -R www-data:www-data /www/api/
|
||
sudo chmod -R 755 /www/api/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 修复运行时目录（必须可写 — ThinkPHP 缓存、日志、编译模板）
|
||
# -----------------------------------------------------------------------------
|
||
# 777 = 所有人可读写执行（仅限运行时目录，不要用于项目根目录）
|
||
sudo chmod -R 777 /www/api/runtime/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 修复上传目录（必须可写 — 用户上传文件存储位置）
|
||
# -----------------------------------------------------------------------------
|
||
sudo chmod -R 755 /opt/data/uploads/
|
||
sudo chown -R www-data:www-data /opt/data/uploads/
|
||
```
|
||
|
||
## 业务问题
|
||
|
||
### 401 未授权
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 Token 是否正确携带
|
||
# -----------------------------------------------------------------------------
|
||
# -H "Authorization: Bearer <token>" → 在请求头中携带 JWT Token
|
||
# <token> 替换为实际的 access_token 值
|
||
curl -H "Authorization: Bearer <token>" http://localhost:8000/api/index/getUser
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 JWT 密钥配置
|
||
# -----------------------------------------------------------------------------
|
||
# 确认 .env 中的 JWT.SECRET 与后端代码一致
|
||
grep JWT.SECRET .env
|
||
```
|
||
|
||
### 403 禁止访问
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查用户角色分配（用户是否分配了角色）
|
||
# -----------------------------------------------------------------------------
|
||
# think_user_role 表存储用户与角色的关联关系
|
||
mysql -u root -proot rxthinkcmf.thinkphp8.elevue -e "SELECT * FROM think_user_role WHERE user_id=1;"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查角色权限（角色是否分配了菜单权限）
|
||
# -----------------------------------------------------------------------------
|
||
# think_role_menu 表存储角色与菜单的关联关系
|
||
mysql -u root -proot rxthinkcmf.thinkphp8.elevue -e "SELECT * FROM think_role_menu WHERE role_id=1;"
|
||
```
|
||
|
||
### 文件上传失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查上传目录权限和空间
|
||
# -----------------------------------------------------------------------------
|
||
# -la → 显示详细信息（权限、大小、修改时间）
|
||
ls -la /opt/data/uploads/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 PHP 上传限制配置
|
||
# -----------------------------------------------------------------------------
|
||
# php -i → 输出 PHP 配置信息
|
||
# grep → 过滤出上传相关的配置项
|
||
php -i | grep upload_max_filesize # 单文件最大上传大小
|
||
php -i | grep post_max_size # POST 请求最大大小
|
||
```
|
||
|
||
### Token 频繁过期
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 JWT Token 过期时间配置
|
||
# -----------------------------------------------------------------------------
|
||
# grep → 从 .env 文件中提取 ACCESS_TTL 配置值
|
||
grep JWT.ACCESS_TTL .env
|
||
# 默认 7200 秒（2 小时），可在 .env 中调整
|
||
# 如果需要更长的登录状态，增大此值或使用 refresh_token 机制
|
||
```
|
||
|
||
### 日志中 IP 显示 127.0.0.1
|
||
|
||
部署在 CDN / 负载均衡 / Nginx 反向代理后面时，日志中的 IP 可能显示为 `127.0.0.1`。
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 第 1 步：检查 .env 中是否配置了 PROXY_IPS
|
||
# -----------------------------------------------------------------------------
|
||
grep PROXY_IPS .env
|
||
# 如果为空或未配置，添加受信代理 IP（以腾讯云 CDN 为例）：
|
||
# PROXY_IPS = 127.0.0.1,::1,101.226.0.0/15,180.101.0.0/16,182.254.0.0/16
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 2 步：检查 Nginx 是否错误覆盖了代理头
|
||
# -----------------------------------------------------------------------------
|
||
# 如果 Nginx 配置中有以下行，需要删除：
|
||
# fastcgi_param REMOTE_ADDR $remote_addr;
|
||
# fastcgi_param HTTP_X_REAL_IP $remote_addr;
|
||
# fastcgi_param HTTP_X_FORWARDED_FOR $remote_addr;
|
||
# 这些会覆盖 CDN 传递的真实 IP 头
|
||
grep -r "fastcgi_param.*REMOTE_ADDR\|fastcgi_param.*X_REAL_IP\|fastcgi_param.*X_FORWARDED" /etc/nginx/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 3 步：清除缓存并重载
|
||
# -----------------------------------------------------------------------------
|
||
rm -rf runtime/*
|
||
nginx -s reload
|
||
```
|
||
|
||
## 定时任务问题
|
||
|
||
### 任务不执行
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 查看当前用户的 crontab 配置（确认任务是否已添加）
|
||
# -----------------------------------------------------------------------------
|
||
# -l → 列出当前 crontab 中的所有任务
|
||
crontab -l
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 cron 服务是否运行
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl status cron
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 手动执行任务（验证命令是否能正常运行）
|
||
# -----------------------------------------------------------------------------
|
||
# cd /www/api → 切换到项目目录（crontab 环境变量不完整，需手动 cd）
|
||
cd /www/api && php think job:run
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 查看 cron 执行日志（排查任务是否被触发）
|
||
# -----------------------------------------------------------------------------
|
||
# grep CRON → 过滤包含 CRON 的日志行
|
||
sudo tail -f /var/log/syslog | grep CRON
|
||
```
|
||
|
||
### 任务重复执行
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查是否有多个 job:run 进程同时运行
|
||
# -----------------------------------------------------------------------------
|
||
# ps aux → 列出所有进程
|
||
# grep job:run → 过滤出 job:run 相关进程
|
||
ps aux | grep job:run
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 Daemon 守护进程
|
||
# -----------------------------------------------------------------------------
|
||
ps aux | grep job:daemon
|
||
```
|
||
|
||
## 前端问题
|
||
|
||
### API 请求 404
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 测试后端路由是否正常（绕过前端，直接请求 API）
|
||
# -----------------------------------------------------------------------------
|
||
# -H → 设置请求头（携带 JWT Token）
|
||
curl http://localhost:8000/api/example/page -H "Authorization: Bearer <token>"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 Nginx 配置语法是否正确
|
||
# -----------------------------------------------------------------------------
|
||
# -t → test 模式，检查配置文件语法（不实际重载）
|
||
sudo nginx -t
|
||
```
|
||
|
||
### 白屏
|
||
|
||
打开浏览器 F12 控制台查看错误，常见原因：
|
||
1. JS 加载失败
|
||
2. 路由配置错误
|
||
3. Token 过期
|
||
|
||
### 构建失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 清理并重新安装依赖（修复依赖冲突或缓存损坏）
|
||
# -----------------------------------------------------------------------------
|
||
cd ui
|
||
rm -rf node_modules pnpm-lock.yaml # 删除依赖目录和锁文件
|
||
pnpm install # 重新安装所有依赖
|
||
pnpm build # 重新构建
|
||
```
|