import{_ as i,o as a,c as n,a2 as l}from"./chunks/framework.B-QBKwc1.js";const A=JSON.parse('{"title":"故障排查手册","description":"遇到问题时，按以下顺序排查： 1. 查看应用日志（storage/logs/laravel.log，或实时输出 php artisan pail） 2. 查看 PHP-FPM / Nginx","frontmatter":{},"headers":[],"relativePath":"zh/deploy/troubleshooting.md","filePath":"zh/deploy/troubleshooting.md"}'),p={name:"zh/deploy/troubleshooting.md"};function h(t,s,k,e,r,d){return a(),n("div",null,[...s[0]||(s[0]=[l(`

11.10 故障排查手册 ​

排查思路

遇到问题时，按以下顺序排查：

  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

本项目无 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://admin.laravel13.elevue/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://admin.laravel13.elevue/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                            # 重新构建
`,60)])])}const B=i(p,[["render",h]]);export{A as __pageData,B as default};