开发文档

一、环境要求

• PHP 8.0 及以上（推荐 8.1 / 8.2）；MySQL 5.7+ / MariaDB 10.3+（字符集 utf8mb4）；Web 服务器 Nginx / Apache / IIS 均可；
• 站点根目录必须指向 public/（不是项目根目录）；
• PHP 扩展：pdo_mysql、mysqli（安装向导导库要用）、mbstring、curl、fileinfo、openssl 必需；gd（缩略图）、zip（打包下载）建议开启。安装向导第 1 步会逐项自检。

二、上传与权限

• 上传全部文件（vendor/ 必须一起传，少传会整站 500）；
• 以下目录要可写（755，属主不是 PHP 运行用户时用 777）：runtime/（含 cache/log/session/temp）、public/ 及其下 uploads/ temp/ thumb/ avatar/、项目根目录（安装程序要生成 .env 与 install.lock）；
• Linux 参考：chmod -R 755 runtime public && chmod 755 .（属主按实际运行用户调整）。

三、安装步骤

1. 建好数据库（utf8mb4），记住库名/账号/密码；
2. 浏览器访问 http://你的域名/install.php（若被拦，访问 /install）；
3. 按向导走：环境检测 → 填数据库 → 填站点信息与后台管理员账号 → 完成；
4. 安装完成后按提示删除 install.php（或 install/ 目录）；
5. 后台入口 /admin，用刚设的管理员账号登录。

四、安装后必做

• 后台「系统设置」里核对站点域名、客服、上传限制；
• 到「存储管理」确认存储节点（默认本地），需要对象存储时新增 OSS 节点并测试；
• 配置邮件（SMTP）与短信（可选），否则注册/找回密码收不到验证码；
• 若要在站点根 /xj_panel.php 用「验证授权 / 在线更新」，先确认授权状态正常。

五、常见问题

• 装到一半报「数据库连接失败」：先确认 mysqli 扩展已开（向导导库用的是它，不是 pdo_mysql）；
• 首页 500 但安装向导能打开：多半是 vendor/ 没传全或 runtime/ 不可写；
• 上传大文件失败：调大 PHP 的 upload_max_filesize / post_max_size 与 Nginx 的 client_max_body_size；
• 样式/图片丢失：站点根目录没指向 public/，或伪静态没配（Nginx 用 try_files $uri $uri/ /index.php?$query_string;）。

六、升级

在线更新通过站点根 /xj_panel.php 的「检查更新」进行（分批下载 + 分批解压，不会覆盖 config/、.env、上传目录与 xj_auth.php）。随包若附 pan_upgrade_*.sql 升级脚本，请按文件名日期顺序在库里执行一次。