SunAdmin 开发文档

主题

1Panel 部署 ​

本页说明使用 1Panel 部署 SunAdmin 的推荐流程。不同 1Panel 版本的按钮名称可能略有差异，核心要求保持一致：站点运行目录指向项目 public，PHP 版本满足项目要求，Laravel 可写目录权限正确，Nginx / OpenResty 伪静态和请求头透传配置完整。

上传项目 ​

将项目源码上传到站点目录后，确认项目根目录已经包含：

text
vendor/
public/admin/

如缺少 vendor 需要执行 composer install。

环境准备 ​

在 1Panel 中安装以下运行环境：

OpenResty / Nginx PHP 8.3+ MySQL Redis 进程守护

PHP 启用如下扩展：

fileinfo redis openssl mbstring pdo_mysql tokenizer xml curl zip

建议开启 opcache

PHP 移除禁用函数：

symlink

如果禁用函数 symlink，会导致项目初始化时创建上传目录软链接失败，无法访问上传文件。

创建站点 ​

在 1Panel 中新增 PHP 网站：

设置刚刚创建的站点，把运行目录设置为 /public。

伪静态设置为 Laravel 规则：

nginx
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

同时确认 PHP-FPM 透传以下请求头：

nginx
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
fastcgi_param HTTP_X_XSRF_TOKEN $http_x_xsrf_token;

缺少 Authorization 时，后台 Token 认证会异常；缺少 X-XSRF-Token 时，管理端部分请求可能无法通过 CSRF 校验。

安装向导 ​

完成站点、依赖和权限准备后，访问：

text
http://你的域名/install

安装向导会完成数据库连接、缓存配置、后台管理员账号、应用密钥与基础数据初始化。

安装完成后会生成 install.lock。如果需要重新初始化安装，请先确认数据可删除，再移除该锁文件重新访问安装向导。

队列与计划任务 ​

如果启用了队列任务，在 1Panel 的进程守护中创建守护进程：

bash
php artisan queue:work --tries=3 --timeout=60

如果启用了计划任务，在 1Panel 计划任务中增加：

bash
cd /你的项目根目录 && php artisan schedule:run >> /dev/null 2>&1

常见问题 ​

如向导安装处理目录映射失败，可以手工执行以下存储映射命令：

bash
# 创建本地上传文件公开访问映射
php artisan storage:link

如果命令提示无法创建软链接，请先到 1Panel 对应 PHP 运行环境中检查禁用函数，移除 symlink 后重新执行。

目录权限 ​

确认 PHP 运行用户对以下目录有写入权限：

text
storage/
bootstrap/cache/
public/admin/
public/h5/
public/modules/
frontend/admin/
frontend/uniapp/

其中 frontend/admin、frontend/uniapp、public/modules 与模块安装、卸载、资源发布和运行包发布有关。生产环境如果要在后台应用中心安装模块，应保持这些目录的所有者与 PHP 运行用户一致。

常见检查项 ​

现象检查方向
访问首页显示 Laravel 默认页站点运行目录是否指向 public
登录后接口提示未登录Authorization 请求头是否透传
上传失败fileinfo 扩展、目录权限、storage:link、symlink 是否被禁用
模块安装失败PHP 运行用户是否可写 frontend/* 和 public/modules
H5 样式缺失是否执行 npm run build:h5 并发布到 public/h5
Admin 页面组件未找到模块是否安装、运行包是否构建并发布