遇到问题时,先记录操作时间、系统版本与 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 并不能证明接口成功。
- 记录请求地址、HTTP 状态和发生时间,不要只记录最后一行提示。
- 确认网站运行目录为
public/,PHP 请求确实进入当前站点 PHP-FPM。 - 应用当前交付包的伪静态规则,避免把 API 请求统一回退到首页。
- 自定义后台地址后使用新入口,检查反向代理与回源规则是否仍指向旧路径。
- 检查 CDN、代理和浏览器缓存是否残留旧页面;不要缓存登录、安装与后台 API。
- 结合 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 地址、数据库连接串与客户个人信息。不要发送完整配置文件、数据库备份或未经检查的整段日志。