rxthinkcmf/rxthinkcmf-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
gitadmin
2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
RXThinkCMF_Laravel13_AntdVue/zh/deploy/troubleshooting.md
+91 -50
View File
@@ -2,8 +2,8 @@
:::tip 排查思路
遇到问题时，按以下顺序排查：
1. 查看 PHP 错误日志（`/var/log/php_errors.log`）
2. 查看 Nginx 错误日志（`/var/log/nginx/error.log`）
1. 查看应用日志（`storage/logs/laravel.log`，或实时输出 `php artisan pail`）
2. 查看 PHP-FPM / Nginx 错误日志（`/var/log/nginx/error.log`）
3. 查看浏览器控制台（F12）
4. 检查 `.env` 配置是否正确
:::
@@ -19,29 +19,32 @@ PHP-FPM 未启动或配置错误：
# 检查 PHP-FPM 服务状态
# -----------------------------------------------------------------------------
# status → 显示服务是否正在运行、主进程 PID、内存占用等
sudo systemctl status php8.2-fpm
sudo systemctl status php8.3-fpm
# -----------------------------------------------------------------------------
# 重启 PHP-FPM（最常见的修复方式）
# -----------------------------------------------------------------------------
# restart → 停止后重新启动，所有正在处理的请求会被中断
sudo systemctl restart php8.2-fpm
sudo systemctl restart php8.3-fpm
# -----------------------------------------------------------------------------
# 实时查看 PHP-FPM 错误日志（Ctrl+C 退出）
# -----------------------------------------------------------------------------
# -f → follow 模式，持续输出新增日志
sudo tail -f /var/log/php8.2-fpm.log
sudo tail -f /var/log/php8.3-fpm.log
```
### 500 Internal Server Error
```bash
# -----------------------------------------------------------------------------
# 查看 PHP 错误日志（定位 PHP 脚本执行错误）
# 查看 Laravel 应用日志（首选 — 记录了异常堆栈）
# -----------------------------------------------------------------------------
# tail -f → 实时输出新增日志行
sudo tail -f /var/log/php_errors.log
tail -f /www/api/storage/logs/laravel.log
# 或使用 Pail 实时查看（开发/排障更友好）
cd /www/api && php artisan pail
# -----------------------------------------------------------------------------
# 查看 Nginx 错误日志（定位 Nginx 层错误）
@@ -49,10 +52,11 @@ sudo tail -f /var/log/php_errors.log
sudo tail -f /var/log/nginx/error.log
# -----------------------------------------------------------------------------
# 检查运行时目录权限（500 错误常见原因）
# 检查目录权限（500 错误最常见原因）
# -----------------------------------------------------------------------------
# -la → 显示详细信息（包括隐藏文件）
ls -la /www/api/runtime/
ls -la /www/api/storage/
ls -la /www/api/bootstrap/cache/
```
### 404 Not Found
@@ -60,12 +64,12 @@ ls -la /www/api/runtime/
Nginx URL 重写配置错误：
```nginx
# 检查 try_files 或 rewrite 规则
# 检查 try_files 规则
# $uri → 当前请求的文件路径
# $uri/ → 当前请求的目录路径
# /index.php?s=$uri&$args → 回退到 ThinkPHP 入口，传递原始路径和参数
# /index.php?$query_string → 回退到 Laravel 入口，传递原始查询参数
location / {
try_files $uri $uri/ /index.php?s=$uri&$args;
try_files $uri $uri/ /index.php?$query_string;
}
```
@@ -97,7 +101,7 @@ mysql -u root -p -e "SELECT user, host FROM mysql.user;"
# ON `数据库`.* → 指定数据库的所有表
# TO 'root'@'%' → 允许从任意主机连接的 root 用户
# IDENTIFIED BY → 设置密码
mysql -u root -proot -e "GRANT ALL ON \`rxthinkcmf.thinkphp6.elevue\`.* TO 'root'@'%' IDENTIFIED BY 'root';"
mysql -u root -proot -e "GRANT ALL ON \`rxthinkcmf.laravel13.elevue\`.* TO 'root'@'%' IDENTIFIED BY 'root';"
mysql -u root -p -e "FLUSH PRIVILEGES;" # 刷新权限使配置生效
```
@@ -112,7 +116,7 @@ sudo systemctl status postgresql
# -----------------------------------------------------------------------------
# 测试连接（-U 指定用户，-d 指定数据库，-c 执行 SQL）
# -----------------------------------------------------------------------------
psql -U postgres -d rxthinkcmf.thinkphp6.elevue -c "SELECT 1;"
psql -U postgres -d rxthinkcmf.laravel13.elevue -c "SELECT 1;"
# -----------------------------------------------------------------------------
# 检查客户端认证配置（pg_hba.conf 控制哪些 IP 可以连接）
@@ -132,14 +136,14 @@ sudo systemctl restart postgresql
# 检查 SQLite 数据库文件是否存在
# -----------------------------------------------------------------------------
# -la → 显示文件大小、权限、修改时间
ls -la /www/api/runtime/database.sqlite
ls -la /www/api/database/database.sqlite
# -----------------------------------------------------------------------------
# 修复文件权限（确保 Web 服务器用户可读写）
# -----------------------------------------------------------------------------
# 664 → owner/group 可读写，others 只读
chmod 664 /www/api/runtime/database.sqlite
chown www-data:www-data /www/api/runtime/database.sqlite
chmod 664 /www/api/database/database.sqlite
chown www-data:www-data /www/api/database/database.sqlite
```
### SQL Server 连接失败
@@ -169,14 +173,41 @@ php -m | grep pdo_sqlsrv # 查找 pdo_sqlsrv 扩展
# -----------------------------------------------------------------------------
# MySQL：通过 mysql 命令导入 SQL 文件
mysql -u root -proot rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.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.thinkphp6.elevue -f document/postgresql/rxthinkcmf.thinkphp6.elevue.sql
psql -U postgres -d rxthinkcmf.laravel13.elevue -f document/postgresql/rxthinkcmf.laravel13.elevue.sql
# SQLite：通过 sqlite3 命令导入 SQL 文件
sqlite3 /www/api/runtime/database.sqlite < document/sqlite/rxthinkcmf.thinkphp6.elevue.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 问题
@@ -188,18 +219,20 @@ sqlite3 /www/api/runtime/database.sqlite < document/sqlite/rxthinkcmf.thinkphp6.
# 查看已安装的 PHP 扩展列表
# -----------------------------------------------------------------------------
php -m # 列出所有已加载的扩展
php -m | grep redis # 确认 phpredis 已安装（必需）
# -----------------------------------------------------------------------------
# 安装缺失的扩展（按数据库类型选择）
# -----------------------------------------------------------------------------
sudo apt install php8.2-mysql # MySQL 驱动（pdo_mysql）
# sudo apt install php8.2-pgsql # PostgreSQL 驱动（取消注释以安装）
# sudo apt install php8.2-sqlite3 # SQLite 驱动（取消注释以安装）
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.2-fpm
sudo systemctl restart php8.3-fpm
```
### 内存不足
@@ -230,16 +263,17 @@ sudo chown -R www-data:www-data /www/api/
sudo chmod -R 755 /www/api/
# -----------------------------------------------------------------------------
# 修复运行时目录（必须可写 — ThinkPHP 缓存、日志、编译模板）
# 修复运行时目录（必须可写 — Laravel 缓存、日志、编译视图）
# -----------------------------------------------------------------------------
# 777 = 所有人可读写执行（仅限运行时目录，不要用于项目根目录）
sudo chmod -R 777 /www/api/runtime/
sudo chmod -R 777 /www/api/storage/
sudo chmod -R 777 /www/api/bootstrap/cache/
# -----------------------------------------------------------------------------
# 修复上传目录（必须可写 — 用户上传文件存储位置）
# -----------------------------------------------------------------------------
sudo chmod -R 755 /opt/data/uploads/
sudo chown -R www-data:www-data /opt/data/uploads/
sudo chmod -R 755 /www/api/public/uploads/
sudo chown -R www-data:www-data /www/api/public/uploads/
```
## 业务问题
@@ -255,10 +289,9 @@ sudo chown -R www-data:www-data /opt/data/uploads/
curl -H "Authorization: Bearer <token>" http://localhost:8000/api/index/getUser
# -----------------------------------------------------------------------------
# 检查 JWT 密钥配置
# 检查 JWT 密钥配置（缺失或过短会 fail-close，拒绝签发/校验令牌）
# -----------------------------------------------------------------------------
# 确认 .env 中的 JWT.SECRET 与后端代码一致
grep JWT.SECRET .env
grep "^JWT_SECRET" /www/api/.env
```
### 403 禁止访问
@@ -267,14 +300,14 @@ grep JWT.SECRET .env
# -----------------------------------------------------------------------------
# 检查用户角色分配（用户是否分配了角色）
# -----------------------------------------------------------------------------
# think_user_role 表存储用户与角色的关联关系
mysql -u root -proot rxthinkcmf.thinkphp6.elevue -e "SELECT * FROM think_user_role WHERE user_id=1;"
# laravel_user_role 表存储用户与角色的关联关系
mysql -u root -proot rxthinkcmf.laravel13.elevue -e "SELECT * FROM laravel_user_role WHERE user_id=1;"
# -----------------------------------------------------------------------------
# 检查角色权限（角色是否分配了菜单权限）
# -----------------------------------------------------------------------------
# think_role_menu 表存储角色与菜单的关联关系
mysql -u root -proot rxthinkcmf.thinkphp6.elevue -e "SELECT * FROM think_role_menu WHERE role_id=1;"
# laravel_role_menu 表存储角色与菜单的关联关系
mysql -u root -proot rxthinkcmf.laravel13.elevue -e "SELECT * FROM laravel_role_menu WHERE role_id=1;"
```
### 文件上传失败
@@ -284,7 +317,7 @@ mysql -u root -proot rxthinkcmf.thinkphp6.elevue -e "SELECT * FROM think_role_me
# 检查上传目录权限和空间
# -----------------------------------------------------------------------------
# -la → 显示详细信息（权限、大小、修改时间）
ls -la /opt/data/uploads/
ls -la /www/api/public/uploads/
# -----------------------------------------------------------------------------
# 检查 PHP 上传限制配置
@@ -293,6 +326,9 @@ ls -la /opt/data/uploads/
# 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 频繁过期
@@ -301,10 +337,10 @@ php -i | grep post_max_size # POST 请求最大大小
# -----------------------------------------------------------------------------
# 检查 JWT Token 过期时间配置
# -----------------------------------------------------------------------------
# grep → 从 .env 文件中提取 ACCESS_TTL 配置值
grep JWT.ACCESS_TTL .env
# 默认 7200 秒（2 小时），可在 .env 中调整
# 如果需要更长的登录状态，增大此值或使用 refresh_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
@@ -313,11 +349,11 @@ grep JWT.ACCESS_TTL .env
```bash
# -----------------------------------------------------------------------------
# 第 1 步：检查 .env 中是否配置了 PROXY_IPS
# 第 1 步：检查 .env 中是否配置了受信代理
# -----------------------------------------------------------------------------
grep PROXY_IPS .env
grep "^TRUSTED_PROXIES" /www/api/.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
# TRUSTED_PROXIES=127.0.0.1,::1,101.226.0.0/15,180.101.0.0/16,182.254.0.0/16
# -----------------------------------------------------------------------------
# 第 2 步：检查 Nginx 是否错误覆盖了代理头
@@ -330,9 +366,9 @@ grep PROXY_IPS .env
grep -r "fastcgi_param.*REMOTE_ADDR\|fastcgi_param.*X_REAL_IP\|fastcgi_param.*X_FORWARDED" /etc/nginx/
# -----------------------------------------------------------------------------
# 第 3 步：清除缓存并重载
# 第 3 步：清除配置缓存并重载
# -----------------------------------------------------------------------------
rm -rf runtime/*
cd /www/api && php artisan config:clear
nginx -s reload
```
@@ -356,7 +392,7 @@ sudo systemctl status cron
# 手动执行任务（验证命令是否能正常运行）
# -----------------------------------------------------------------------------
# cd /www/api → 切换到项目目录（crontab 环境变量不完整，需手动 cd）
cd /www/api && php think job:run
cd /www/api && php artisan job:run
# -----------------------------------------------------------------------------
# 查看 cron 执行日志（排查任务是否被触发）
@@ -376,9 +412,14 @@ sudo tail -f /var/log/syslog | grep CRON
ps aux | grep job:run
# -----------------------------------------------------------------------------
# 检查 Daemon 守护进程
# 检查 Daemon 守护进程（常驻调度器，与 crontab 二选一即可）
# -----------------------------------------------------------------------------
ps aux | grep job:daemon
# -----------------------------------------------------------------------------
# 停止守护进程（通过锁文件 storage/app/job_daemon.lock 退出）
# -----------------------------------------------------------------------------
cd /www/api && php artisan job:daemon --stop
```
## 前端问题
@@ -413,7 +454,7 @@ sudo nginx -t
# 清理并重新安装依赖（修复依赖冲突或缓存损坏）
# -----------------------------------------------------------------------------
cd ui
rm -rf node_modules pnpm-lock.yaml # 删除依赖目录和锁文件
pnpm install # 重新安装所有依赖
pnpm build # 重新构建
rm -rf node_modules # 删除依赖目录（锁文件 pnpm-lock.yaml 保留以保证版本一致）
pnpm install --force # 重新安装所有依赖
pnpm build # 重新构建
```