九、常见问题排查

9.1 安装阶段问题

Q1：访问 install.php 显示 404 或空白页

最常见的 3 个原因（按概率排序）：

1. PHP 版本不是 8.1 → 宝塔 → 网站 → 你的域名 → PHP 版本 → 选 PHP-81 → 保存
2. 域名解析未生效 → 用 ping 你的域名 确认 IP 是否正确
3. 文件未上传到正确目录 → 确认 install.php 在 /www/wwwroot/你的域名/ 下

Q2：安装界面"环境检测"有红色 ❌

Q3：数据库连接失败

按以下顺序排查：

1. 数据库名、用户名、密码是否填错（注意不要有多余空格）
2. 数据库主机是否填的 127.0.0.1（不要填 localhost）
3. 数据库是否被删除 → 宝塔 → 数据库 → 查看是否存在

Q4：安装时一直转圈

原因：数据库信息有误或数据库用户权限不足。

解决方法：

1. 宝塔 → 数据库 → 找到对应数据库 → 点击 权限 → 确认为 ALL PRIVILEGES
2. 如果不是，改为 ALL PRIVILEGES 或删库重建

Q5：安装完成后访问首页仍跳转到 install.php

原因：安装程序未成功生成安装锁文件。

解决：

1. 访问 http://你的域名/install.php?reinstall=1 重新安装
2. 或手动创建锁文件：宝塔 → 文件 → 站点根目录 → 新建文件 installed.lock，内容任意

9.2 运行阶段问题

Q6：部分页面显示 404（如 /home、/compose）

原因：伪静态规则未配置或配置错误。

解决：

1. 宝塔 → 网站 → 你的域名 → 设置 → 伪静态
2. 确认内容为 Nginx rewrite 规则（见下方伪静态配置示例）
3. 不是下拉选择，是直接粘贴代码
4. 保存后重启 Nginx

location / {
    try_files $uri $uri/ /index.php?$args;
}

Apache 用户编辑 .htaccess 文件：

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?page=$1 [QSA,L]

Q7：用户注册后收不到验证邮件

按顺序排查：

1. SMTP 配置是否已填写（后台 → 系统设置 → 邮件配置）
2. SMTP 授权码是否正确（QQ 邮箱是授权码不是密码）
3. 使用"测试发送"按钮验证配置
4. 检查邮箱垃圾箱

Q8：信件到达时间后没有发送

按顺序排查：

1. 定时任务是否配置（宝塔 → 计划任务 → 查看列表）
2. 定时任务是否执行（查看 logs/cron.log 是否有最近记录）
3. SMTP 配置是否正常（后台测试发送）
4. 手动执行一次测试：

/www/server/php/81/bin/php /www/wwwroot/你的域名/cron/run.php

5. 查看输出中的具体错误信息

Q9：页面显示 500 错误

解决步骤：

1. 查看错误日志：宝塔 → 网站 → 你的域名 → 错误日志
2. 或终端执行：

tail -50 /www/wwwroot/你的域名/logs/error.log
tail -50 /www/wwwlogs/你的域名.error.log

Q10：图片上传失败

可能原因：

1. uploads/ 目录权限不足 → 设为 777
2. PHP 上传限制太小 → PHP-8.1 → 配置修改 → 调大 upload_max_filesize 和 post_max_size
3. 磁盘空间不足 → 宝塔首页查看

Q11：页面样式错乱

按 Ctrl + F5 强制刷新浏览器缓存。如仍异常，检查浏览器控制台（F12）是否有 CSS 加载失败的提示。

Q12：SSL 证书到期

1. 宝塔 → 网站 → 你的域名 → 设置 → SSL
2. 如果使用了 Let's Encrypt，点击"续签"
3. 如使用付费证书，重新上传新证书

9.3 后台问题

Q13：后台无法登录

• 确认使用管理员邮箱登录（不是普通用户邮箱）
• 如忘记密码，通过数据库直接重置：宝塔 → 数据库 → 管理（phpMyAdmin）→ users 表 → 编辑管理员行的 password 字段

Q14：更新失败

• 检查 runtime/ 目录是否可写
• 查看后台错误日志了解具体错误
• 确认 .env 中的 SUBSCRIPTION_API_KEY 配置正确