SunAdmin 开发文档

主题

🚢 部署发布 ​

SunAdmin 支持一体化部署：Laravel 后端托管 API，同时托管 Admin SPA 和 uni-app H5 的编译产物。

📁 生产目录约定 ​

内容目录
Laravel 入口public/index.php
Admin 产物public/admin
uni-app H5 产物public/h5
上传本地存储通常在 public/storage 或业务存储驱动目录

🚀 后端发布流程 ​

首次部署先安装依赖并配置 Web 站点入口，随后通过安装向导完成数据库、缓存、后台管理员账号、应用密钥与基础数据初始化。

bash
# 安装生产依赖并优化 Composer 自动加载
composer install --no-dev --optimize-autoloader

# 创建本地存储公开访问软链接
php artisan storage:link

首次部署后访问：

text
https://你的域名/install

安装完成后会生成 install.lock。

安装完成后，可按需生成 Laravel 优化缓存：

bash
# 清理 Laravel 优化缓存
php artisan optimize:clear

# 生成配置缓存
php artisan config:cache

# 生成路由缓存
php artisan route:cache

# 生成视图缓存
php artisan view:cache

已安装项目升级时，再按版本变更要求执行迁移：

bash
php artisan migrate --force

🏭 前端构建发布 ​

Admin ​

bash
# 进入管理端项目目录
cd frontend/admin

# 安装管理端依赖
npm install

# 构建管理端生产产物
npm run build

Admin 构建后应发布到：

text
public/admin

uni-app H5 ​

bash
# 进入 uni-app 项目目录
cd frontend/uniapp

# 使用指定 npm 版本安装 uni-app 依赖
npx npm@11.13.0 install

# 构建 H5 生产产物
npm run build:h5

H5 构建脚本会先生成 frontend/uniapp/dist/build/h5，再自动发布到：

text
public/h5

微信小程序 ​

bash
# 进入 uni-app 项目目录
cd frontend/uniapp

# 构建微信小程序生产产物
npm run build:mp-weixin

构建前确认 frontend/uniapp/src/manifest.json 中的 mp-weixin.appid 已填写微信小程序 AppID。未填写时，微信开发者工具无法按真实小程序身份预览、上传和发布。

用微信开发者工具导入并上传发布：

text
frontend/uniapp/dist/build/mp-weixin

🌍 Web 服务器 ​

项目站点根目录应指向仓库下的 public 目录，而非仓库根目录。所有 HTTP 请求由 public/index.php 统一入口分发。

以下是一份适用于 SunAdmin 的 Nginx 站点配置示例：

nginx
server {
    listen 80;
    server_name your-domain.com;
    # 如需 HTTPS，可在此处配置 ssl_certificate / ssl_certificate_key

    # 站点入口目录指向 public
    root /var/www/sunadmin/public;
    index index.php;

    # 建议的安全与性能设置
    charset utf-8;
    client_max_body_size 64m;

    # 静态资源缓存（admin / h5 / modules 等前端产物）
    location ~* \.(css|js|woff2?|ttf|eot|svg|png|jpe?g|gif|ico|webp|mp4|webm)$ {
        expires 7d;
        access_log off;
    }

    # 伪静态：将非文件、非目录请求统一转发至 index.php
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP-FPM 处理
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;

        # 传递 Authorization 与 X-XSRF-Token 请求头
        fastcgi_param HTTP_AUTHORIZATION $http_authorization;
        fastcgi_param HTTP_X_XSRF_TOKEN $http_x_xsrf_token;
    }

    # 禁止访问隐藏文件（.env、.git 等）
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

配置说明：

配置项说明
root指向项目 public 目录，这是唯一的 Web 入口
try_files伪静态核心：先尝试匹配静态文件，不存在则转发至 index.php，由 Laravel 路由接管
fastcgi_param HTTP_AUTHORIZATION传递 Authorization 请求头，Sanctum Token 认证依赖此配置
fastcgi_param HTTP_X_XSRF_TOKEN传递 X-XSRF-Token 请求头，管理端 AJAX 请求的 CSRF 校验依赖此配置
location ~ /\.(?!well-known)阻止直接访问 .env、.git 等敏感文件

如果使用面板工具创建站点，通常只需将网站运行目录设置为 public，并在伪静态规则中填入上述 location / 部分即可；Authorization 等 Header 的透传需确认 FastCGI 参数中已包含。具体面板操作可参考 宝塔面板部署 和 1Panel 部署。

Admin 和 H5 的访问入口由 Laravel 控制器托管：

入口说明
/adminAdmin SPA
/h5uni-app H5
/install安装向导

⏱️ 队列与计划任务 ​

队列生产环境不要使用开发时的 queue:listen。推荐使用 Supervisor 或系统服务运行：

bash
# 启动生产队列 Worker，并设置重试次数和超时时间
php artisan queue:work --tries=3 --timeout=60

如果后续增加计划任务，服务器 crontab 保留 Laravel 标准入口：

text
* * * * * cd /var/www/sunadmin && php artisan schedule:run >> /dev/null 2>&1

🧠 缓存与权限 ​

发布后需要保证以下目录可写：

text
storage/
bootstrap/cache/
public/admin/
public/h5/

本地上传还需要执行以下命令初始化路径映射：

bash
# 创建本地存储公开访问软链接
php artisan storage:link

修改配置、路由、视图后按需执行：

bash
# 清理 Laravel 优化缓存
php artisan optimize:clear

# 生成配置缓存
php artisan config:cache

# 生成路由缓存
php artisan route:cache

# 生成视图缓存
php artisan view:cache

↩️ 回滚建议 ​

一次发布至少保留：

  • 当前后端代码版本。
  • composer.lock。
  • Admin 构建产物。
  • uni-app H5 构建产物。
  • 数据库迁移执行记录。

涉及数据库结构变更时，先确认是否可逆。涉及支付、订单、账户余额等状态数据时，不建议通过简单回滚数据库解决，应写补偿脚本或人工核对。