常见问题排查

安装类问题

Composer 安装失败

报错：proc_open(): fork failed

原因：PHP 函数被禁用。

解决：在 PHP 设置中解禁以下函数：

• putenv
• proc_open
• proc_get_status

报错：内存不足 Allowed memory size exhausted

解决：

# 临时增加内存限制
php -d memory_limit=-1 /usr/local/bin/composer install

报错：下载超时

解决：切换国内镜像：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

pnpm 安装失败

报错：ERR_PNPM_UNSUPPORTED_ENGINE

原因：Node.js 版本过低。

解决：升级 Node.js 到 18+：

# 使用 nvm 管理 Node 版本
nvm install 20
nvm use 20

数据库导入失败

报错：Unknown collation: 'utf8mb4_0900_ai_ci'

原因：MySQL 5.7 不支持 8.0 的排序规则。

解决：将 SQL 文件中的 utf8mb4_0900_ai_ci 替换为 utf8mb4_unicode_ci：

sed -i 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_ci/g' schema.sql

运行类问题

页面空白 / 404

检查项：

1. 伪静态 — 确认 Nginx 配置了 ThinkPHP 伪静态规则
2. 运行目录 — 确认网站根目录指向 server/public，不是 server
3. 前端资源 — 确认 server/public/admin/index.html 文件存在

接口 500 错误

排查步骤：

1. 查看日志：tail -f server/runtime/log/$(date +%Y%m)/$(date +%d).log
2. 常见原因：
   • .env 数据库配置错误
   • PHP 扩展缺失（fileinfo、redis）
   • 目录权限不足（runtime/、public/storage/）
   • APP_DEBUG = false 时不显示具体错误，需看日志

跨域问题

如果前端独立域名部署（与后端不同域），需要配置 CORS。

方法一：Nginx 配置（推荐）

location /adminapi {
    add_header Access-Control-Allow-Origin $http_origin;
    add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
    add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Requested-With, X-Client-Type';
    add_header Access-Control-Allow-Credentials true;

    if ($request_method = 'OPTIONS') {
        return 204;
    }
}

方法二：后端中间件

系统已内置 CORS 中间件，在 server/config/middleware.php 中确认已启用。

文件上传失败

检查项：

1. 目录权限：ls -la server/public/storage/，确认 www 用户可写
2. PHP 限制：upload_max_filesize、post_max_size 是否足够
3. Nginx 限制：client_max_body_size 是否足够（默认 1M）

# Nginx 中增加上传限制
client_max_body_size 50m;

Redis 连接失败

报错：Connection refused

1. 检查 Redis 服务：systemctl status redis
2. 检查 .env 配置：HOST、PORT、PASSWORD
3. 检查 PHP redis 扩展：php -m | grep redis

部署类问题

HTTPS 混合内容警告

浏览器控制台报 Mixed Content 警告。

原因：页面通过 HTTPS 加载，但某些资源（图片、API）使用了 HTTP。

解决：

1. 确保 .env 中无硬编码 HTTP 地址
2. 检查系统配置中的"站点地址"是否使用 HTTPS
3. 上传文件的 URL 应跟随站点协议

队列不执行

检查清单：

1. .env 中 QUEUE.CONNECTOR 是否为 redis（不是 sync）
2. Redis 服务是否正常
3. Supervisor 进程是否运行：supervisorctl status
4. 查看队列日志：supervisorctl tail ydadmin-queue stderr

定时任务不生效

1. 检查 Cron 是否配置正确：crontab -l
2. 手动执行命令测试：cd server && php think log:archive
3. 检查 PHP CLI 路径是否正确：which php

升级类问题

SQL 执行报错：字段/表已存在

原因：可能重复执行了升级脚本。

解决：升级脚本设计为幂等的（使用 IF NOT EXISTS），但如果手动修改过表结构可能冲突。检查具体报错信息，手动跳过已存在的变更。

升级后版本号不对

检查 server/config/version.php，确认版本号已更新到目标版本。如果使用 Git 拉取，该文件应自动更新。