troubleshooting

排障

先记录宿主 commit、基础包版本、插件版本及出错步骤，保存脱敏后的终端/接口/日志信息。不要同时更换宿主和插件版本，否则难以判断原因。

症状	检查与处理	恢复后的确认
php / composer / pnpm 不可用	检查 CLI 安装与 PATH，重开终端确认实际版本；使用同一终端的 PHP，不以网页 PHP 版本替代	运行首次安装页中的版本命令
PostgreSQL could not find driver	用 php --ri pdo_pgsql 检查当前 CLI 的驱动；安装/启用与当前 PHP 匹配的扩展	驱动信息可读，再进行连接验证
Corepack Cannot find matching keyid	命令可能在调用 pnpm 前被旧 Corepack 签名校验拦截；核对 Node/Corepack 版本，按所选 revision 的工具链准备独立 pnpm，不删除锁文件或改用其他包管理器	pnpm --version 与依赖安装正常；本地候选另见版本范围
frozen lockfile 不一致	先核对 pnpm --version 与项目 packageManager：当前固定 pnpm 11.19.0；不要因锁文件格式号是9就降级到旧pnpm9。再核对 package.json 与 pnpm-lock.yaml 来自同一 revision。维护者重新生成锁文件应作为明确依赖变更，部署者不默默更新	同一固定源码下安装成功
Composer 完成但缺少 plugin/sandadmin	核对 composer.lock 基础包及 support\Plugin::install 钩子，检查原始安装错误和已有文件冲突；不要编辑 vendor/ 充当权威源码	运行副本存在，实际命令和路由可加载
/core/install 显示“程序已经安装”	安装器发现 .env 即阻止重新安装；已有实例使用原配置登录。新环境误建配置先由所有者核实库和文件状态，不能对现有站点直接删 .env	进入与实例状态相符的登录或首次安装路径
安装页报权限错误	检查进程用户对 server/config/、项目配置文件的写权限，使用最小权限修正	页面可继续；安装成功后核对生成配置
8787 无响应或占用	读启动终端、核对 SANDADMIN_SERVER_PORT 和实际监听；Unix/Windows 入口分别见首次安装	安装或登录路由可访问
前端能打开但 API 404/502	开发核对 /api 代理目标，生产核对 /prod 前缀剥离和后端 /core 路由；Vite 代理不用于生产	登录接口返回预期业务内容
插件仓库不可达	核对服务端配置 ref、TLS 与 GitHub 网络；可以使用来源可验证的同版本 Release ZIP 上传，不关闭 TLS 校验	清单/包身份可核验，刷新得到真实状态
插件显示已安装但文件缺失	登记与运行副本不一致，保留数据库、登记和包；按插件管理的检查入口处理，清理涉及业务数据删除，需先备份和核准	清理或恢复后的现场一致，再重装
插件菜单有了但页面不存在	源码部署不等于生产前端生效；检查对应源码、依赖、构建、静态发布及权限	实际生产 URL 和一个页面通过
插件安装/升级中断	保存 SQL 提交、候选与运行版本证据；按所锁版本的恢复入口核查，不手改 state 或直接重跑 SQL	恢复检查确认后再按明确步骤处理

后端日志默认在 server/runtime/logs/，包括 stdout/Workerman 日志，应用日志位置取决于所选基础包配置。提交问题前移除口令、token、Cookie 和业务隐私数据；完整 .env 不应上传。

向宿主 Issues报告零插件或公共契约问题；单插件业务问题报告至该插件权威仓库。提供固定 revision、操作步骤、预期/实际结果、错误时间、脱敏日志和是否已执行 SQL。旧失败升级的专门边界见恢复契约。

本页提供源码和既有契约支持的定位路径，具体恢复必须匹配当前锁定版本和现场。相关默认值和入口见配置、安装和版本范围。