461 lines
19 KiB
Markdown
461 lines
19 KiB
Markdown
# 11.10 故障排查手册
|
||
|
||
:::tip 排查思路
|
||
遇到问题时，按以下顺序排查：
|
||
1. 查看应用日志（`storage/logs/laravel.log`，或实时输出 `php artisan pail`）
|
||
2. 查看 PHP-FPM / Nginx 错误日志（`/var/log/nginx/error.log`）
|
||
3. 查看浏览器控制台（F12）
|
||
4. 检查 `.env` 配置是否正确
|
||
:::
|
||
|
||
## 服务器问题
|
||
|
||
### 502 Bad Gateway
|
||
|
||
PHP-FPM 未启动或配置错误：
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 PHP-FPM 服务状态
|
||
# -----------------------------------------------------------------------------
|
||
# status → 显示服务是否正在运行、主进程 PID、内存占用等
|
||
sudo systemctl status php8.3-fpm
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 重启 PHP-FPM（最常见的修复方式）
|
||
# -----------------------------------------------------------------------------
|
||
# restart → 停止后重新启动，所有正在处理的请求会被中断
|
||
sudo systemctl restart php8.3-fpm
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 实时查看 PHP-FPM 错误日志（Ctrl+C 退出）
|
||
# -----------------------------------------------------------------------------
|
||
# -f → follow 模式，持续输出新增日志
|
||
sudo tail -f /var/log/php8.3-fpm.log
|
||
```
|
||
|
||
### 500 Internal Server Error
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 查看 Laravel 应用日志（首选 — 记录了异常堆栈）
|
||
# -----------------------------------------------------------------------------
|
||
# tail -f → 实时输出新增日志行
|
||
tail -f /www/api/storage/logs/laravel.log
|
||
|
||
# 或使用 Pail 实时查看（开发/排障更友好）
|
||
cd /www/api && php artisan pail
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 查看 Nginx 错误日志（定位 Nginx 层错误）
|
||
# -----------------------------------------------------------------------------
|
||
sudo tail -f /var/log/nginx/error.log
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查目录权限（500 错误最常见原因）
|
||
# -----------------------------------------------------------------------------
|
||
# -la → 显示详细信息（包括隐藏文件）
|
||
ls -la /www/api/storage/
|
||
ls -la /www/api/bootstrap/cache/
|
||
```
|
||
|
||
### 404 Not Found
|
||
|
||
Nginx URL 重写配置错误：
|
||
|
||
```nginx
|
||
# 检查 try_files 规则
|
||
# $uri → 当前请求的文件路径
|
||
# $uri/ → 当前请求的目录路径
|
||
# /index.php?$query_string → 回退到 Laravel 入口，传递原始查询参数
|
||
location / {
|
||
try_files $uri $uri/ /index.php?$query_string;
|
||
}
|
||
```
|
||
|
||
## 数据库问题
|
||
|
||
### 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.laravel13.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.laravel13.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/database/database.sqlite
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 修复文件权限（确保 Web 服务器用户可读写）
|
||
# -----------------------------------------------------------------------------
|
||
# 664 → owner/group 可读写，others 只读
|
||
chmod 664 /www/api/database/database.sqlite
|
||
chown www-data:www-data /www/api/database/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.laravel13.elevue < document/mysql/rxthinkcmf.laravel13.elevue.sql
|
||
|
||
# PostgreSQL：通过 psql 命令导入 SQL 文件
|
||
# -U 指定用户，-d 指定数据库，-f 指定 SQL 文件
|
||
psql -U postgres -d rxthinkcmf.laravel13.elevue -f document/postgresql/rxthinkcmf.laravel13.elevue.sql
|
||
|
||
# SQLite：通过 sqlite3 命令导入 SQL 文件
|
||
sqlite3 /www/api/database/database.sqlite < document/sqlite/rxthinkcmf.laravel13.elevue.sql
|
||
```
|
||
|
||
:::info 本项目无 migration 建表
|
||
`database/migrations/` 为空，表结构只能由 `document/` 下的 SQL 脚本导入，`php artisan migrate` 不会创建业务表。
|
||
:::
|
||
|
||
## Redis 问题
|
||
|
||
### Redis 连接失败（登录失败 / 缓存不生效 / 队列不消费）
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 Redis 服务状态
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl status redis
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 测试连接与密码
|
||
# -----------------------------------------------------------------------------
|
||
redis-cli ping # 期望返回 PONG
|
||
redis-cli -a your_redis_password ping # 设置了 requirepass 时需带密码
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 .env 配置（本项目为扁平键名）
|
||
# -----------------------------------------------------------------------------
|
||
grep "^REDIS_" /www/api/.env # REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_CLIENT
|
||
grep "^CACHE_STORE\|^SESSION_DRIVER\|^QUEUE_CONNECTION" /www/api/.env
|
||
```
|
||
|
||
## PHP 问题
|
||
|
||
### 缺少扩展
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 查看已安装的 PHP 扩展列表
|
||
# -----------------------------------------------------------------------------
|
||
php -m # 列出所有已加载的扩展
|
||
php -m | grep redis # 确认 phpredis 已安装（必需）
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 安装缺失的扩展（按数据库类型选择）
|
||
# -----------------------------------------------------------------------------
|
||
sudo apt install php8.3-mysql # MySQL 驱动（pdo_mysql）
|
||
# sudo apt install php8.3-pgsql # PostgreSQL 驱动（取消注释以安装）
|
||
# sudo apt install php8.3-sqlite3 # SQLite 驱动（取消注释以安装）
|
||
sudo apt install php8.3-redis # Redis 扩展（缓存/会话/队列必需）
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 重启 PHP-FPM 使新扩展生效
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl restart php8.3-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/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 修复运行时目录（必须可写 — Laravel 缓存、日志、编译视图）
|
||
# -----------------------------------------------------------------------------
|
||
# 777 = 所有人可读写执行（仅限运行时目录，不要用于项目根目录）
|
||
sudo chmod -R 777 /www/api/storage/
|
||
sudo chmod -R 777 /www/api/bootstrap/cache/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 修复上传目录（必须可写 — 用户上传文件存储位置）
|
||
# -----------------------------------------------------------------------------
|
||
sudo chmod -R 755 /www/api/public/uploads/
|
||
sudo chown -R www-data:www-data /www/api/public/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 密钥配置（缺失或过短会 fail-close，拒绝签发/校验令牌）
|
||
# -----------------------------------------------------------------------------
|
||
grep "^JWT_SECRET" /www/api/.env
|
||
```
|
||
|
||
### 403 禁止访问
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查用户角色分配（用户是否分配了角色）
|
||
# -----------------------------------------------------------------------------
|
||
# laravel_user_role 表存储用户与角色的关联关系
|
||
mysql -u root -proot rxthinkcmf.laravel13.elevue -e "SELECT * FROM laravel_user_role WHERE user_id=1;"
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查角色权限（角色是否分配了菜单权限）
|
||
# -----------------------------------------------------------------------------
|
||
# laravel_role_menu 表存储角色与菜单的关联关系
|
||
mysql -u root -proot rxthinkcmf.laravel13.elevue -e "SELECT * FROM laravel_role_menu WHERE role_id=1;"
|
||
```
|
||
|
||
### 文件上传失败
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查上传目录权限和空间
|
||
# -----------------------------------------------------------------------------
|
||
# -la → 显示详细信息（权限、大小、修改时间）
|
||
ls -la /www/api/public/uploads/
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 PHP 上传限制配置
|
||
# -----------------------------------------------------------------------------
|
||
# php -i → 输出 PHP 配置信息
|
||
# grep → 过滤出上传相关的配置项
|
||
php -i | grep upload_max_filesize # 单文件最大上传大小
|
||
php -i | grep post_max_size # POST 请求最大大小
|
||
|
||
# 同时检查 .env 中的 FILE_MAX_SIZE（MB）与白名单 FILE_EXT
|
||
grep "^FILE_" /www/api/.env
|
||
```
|
||
|
||
### Token 频繁过期
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 JWT Token 过期时间配置
|
||
# -----------------------------------------------------------------------------
|
||
# grep → 从 .env 文件中提取过期时间配置值
|
||
grep "^JWT_ACCESS_TTL\|^JWT_REFRESH_TTL" /www/api/.env
|
||
# JWT_ACCESS_TTL 默认 7200 秒（2 小时），JWT_REFRESH_TTL 默认 604800 秒（7 天）
|
||
# 可在 .env 中调整，改后重启 PHP-FPM 或 php artisan config:clear
|
||
```
|
||
|
||
### 日志中 IP 显示 127.0.0.1
|
||
|
||
部署在 CDN / 负载均衡 / Nginx 反向代理后面时，日志中的 IP 可能显示为 `127.0.0.1`。
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 第 1 步：检查 .env 中是否配置了受信代理
|
||
# -----------------------------------------------------------------------------
|
||
grep "^TRUSTED_PROXIES" /www/api/.env
|
||
# 如果为空或未配置，添加受信代理 IP（以腾讯云 CDN 为例）：
|
||
# TRUSTED_PROXIES=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 步：清除配置缓存并重载
|
||
# -----------------------------------------------------------------------------
|
||
cd /www/api && php artisan config:clear
|
||
nginx -s reload
|
||
```
|
||
|
||
## 定时任务问题
|
||
|
||
### 任务不执行
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 查看当前用户的 crontab 配置（确认任务是否已添加）
|
||
# -----------------------------------------------------------------------------
|
||
# -l → 列出当前 crontab 中的所有任务
|
||
crontab -l
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 检查 cron 服务是否运行
|
||
# -----------------------------------------------------------------------------
|
||
sudo systemctl status cron
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 手动执行任务（验证命令是否能正常运行）
|
||
# -----------------------------------------------------------------------------
|
||
# cd /www/api → 切换到项目目录（crontab 环境变量不完整，需手动 cd）
|
||
cd /www/api && php artisan 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 守护进程（常驻调度器，与 crontab 二选一即可）
|
||
# -----------------------------------------------------------------------------
|
||
ps aux | grep job:daemon
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 停止守护进程（通过锁文件 storage/app/job_daemon.lock 退出）
|
||
# -----------------------------------------------------------------------------
|
||
cd /www/api && php artisan job:daemon --stop
|
||
```
|
||
|
||
## 前端问题
|
||
|
||
### 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 --force # 重新安装所有依赖
|
||
pnpm build # 重新构建
|
||
```
|