签入版本

2026-10-20 21:19:44 +08:00
commit 7e70ed6942
2943 changed files with 498573 additions and 0 deletions
@@ -0,0 +1,419 @@
+# 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                                   # 重新构建
+```