遇到问题时,先记录操作时间、系统版本与 Build、站点 PHP 版本,以及最短复现步骤。以下是面向站点管理员的处理建议。

环境与运行组件

提示 排查和处理
当前运行环境不受支持 确认站点实际使用 Linux x86_64、PHP 8.1–8.4 NTS;面板选择与命令行默认 PHP 可能不同
CLI 未探测 网页受执行权限限制时可能出现,不能单独据此认定 PHP 不受支持;继续看站点 PHP-FPM 和组件检测结果
安全运行组件未就绪 先 cd 到站点根目录,执行当前环境检测页的一键命令,再点击“我已执行,重新检测”
授权模块文件存在但无法加载 确认组件安装、PHP-FPM 刷新与网页复检通过;仍失败则核对交付包是否完整、是否混用版本
终端安装成功但网页仍显示未就绪 确认操作的是当前站点及其 PHP 版本;核对 PHP 服务状态并重新检测
Operation not permitted 使用 root/sudo,检查面板文件保护、权限、只读文件系统与安全策略;不要删除配置或随意关闭保护
下载或 SHA-256 校验失败 使用当前向导命令,检查网络与官方下载源;不要跳过校验

完整操作见安全运行组件安装。

数据库连接与自动建库

目标数据库不存在时,安装向导会尝试创建,并显示处理进度。建库需要数据库账号拥有创建权限。

提示 检查
连接超时、连接拒绝 数据库主机和端口、服务状态、防火墙及来源地址限制
账号或密码错误 数据库账号、密码与允许连接的主机;注意粘贴空格
无建库权限 使用有建库权限的账号,或按页面提示补充管理账号
数据库存在但无法访问 目标库名和账号权限;不要清空数据库重试
缺少类 / controller not exists / Class not found 程序启动或交付文件异常,通常不能通过建库解决

若出现缺少启动组件或类的提示,检查部署包是否完整解压、运行目录是否为 public/、依赖与程序是否来自同一版本、安全运行组件是否通过网页检测。不要从其他版本复制单个核心文件或手工创建同名空类。

接口返回了页面而非 JSON

这表示请求收到 HTML 页面或服务器错误页,HTTP 200 并不能证明接口成功。

  1. 记录请求地址、HTTP 状态和发生时间,不要只记录最后一行提示。
  2. 确认网站运行目录为 public/,PHP 请求确实进入当前站点 PHP-FPM。
  3. 应用当前交付包的伪静态规则,避免把 API 请求统一回退到首页。
  4. 自定义后台地址后使用新入口,检查反向代理与回源规则是否仍指向旧路径。
  5. 检查 CDN、代理和浏览器缓存是否残留旧页面;不要缓存登录、安装与后台 API。
  6. 结合 PHP-FPM 和 Nginx 日志排查,详细信息脱敏后提交支持。

页面、登录与主题

现象 建议
页面 404 或白屏 检查运行目录、完整解压、伪静态和静态资源响应;同时检查 PHP 错误日志
/login 或后台地址需要手动补 / 使用当前版本配置并检查代理重写,不能靠混入旧入口页修复
新旧主题混用 检查首页、商店、登录注册与会员中心的主题配置,清理对应缓存,使用新版真实路径
Logo 或样式缺失 检查站点设置、图片地址和静态资源是否返回文件;HTTPS 页面应使用可正常访问的图片
保存商品或分组后未显示 清除筛选并检查是否隐藏/下架,确认保存结果,再刷新列表
公告新增后看不到 检查发布状态、显示范围、时间与当前主题展示区块
上传失败或 HTTP 413 核对文件大小以及 PHP、Nginx、代理三层上传限制
401 / 登录已失效 重新登录;持续出现时检查浏览器 Cookie/存储限制与代理配置
403 / 无权限 核对员工角色权限;不要改用旧默认后台入口规避

更新问题

先查看 系统更新 → 进度 / 日志 / 升级历史。接近完成时连接中断,应重新进入页面查看任务结果,而不是再次发起更新。恢复或回滚前先保存数据,详见系统更新与备份恢复。

状态码参考

业务 API 通常使用下列结构;排错时同时记录 HTTP 状态与响应体 status:

{ "status": 200, "msg": "ok", "data": {} }
状态 常见含义
200 请求成功;仍需核对返回内容是否为预期业务数据
400 参数不符合要求或业务校验失败
401 未登录或登录已过期
403 无对应权限或请求被禁止
404 页面、接口或资源不存在
413 请求或上传文件超过服务器限制
423 当前操作受限,按页面提示处理
429 请求过于频繁,稍后再试
500 服务器内部错误,需要结合日志排查
502 / 504 上游服务或服务器转发异常、超时

一键复制详情报告

页面提供 一键复制详情报告 时,先复制并检查内容,再通过技术支持的私密渠道提交。报告中应保留版本、环境、错误时间、操作步骤和错误类型。

提交前删除密码、完整授权码、API Key、Cookie、登录令牌、Webhook 地址、数据库连接串与客户个人信息。不要发送完整配置文件、数据库备份或未经检查的整段日志。

下载文档
原始 Markdown 文件