🌞 项目介绍
SunAdmin 是一套多端模块化业务平台，由 Laravel 13 后端、Vue3 Admin 管理端和 uni-app Vue3 客户端组成。它对开发者是"开发基座"——把权限、配置、内容、上传、支付、移动端和 AI 等常见业务基础设施提前组合到一起；对运营者是"应用平台"——通过后台应用中心按需安装、管理业务模块。
🎯 项目定位
SunAdmin 适合用作中后台、内容运营平台、会员/用户中心、移动端业务应用和行业管理系统的起点。
它解决的核心问题是：
- 后端提供稳定的模块化业务结构，便于持续扩展新模块。
- Admin 管理端提供权限、菜单、配置、内容、装修、用户和集成管理能力。
- uni-app 客户端提供 H5、小程序、App 多端页面基础。
- 三端使用同一套业务接口契约，减少重复设计和联调成本。
- 常见基础能力提前内置，业务开发无需再重新造轮子，直接从更高层开始。
🪜 两层定位
SunAdmin 在不同视角下承担不同角色：
| 层 | 面向 | 当前能力 | 后续扩展方向 |
|---|---|---|---|
| 开发基座 | 开发团队 / 自研者 | 模块化结构、权限/支付/AI/上传等基础设施齐备，可直接二次开发 | 同样可通过应用中心选购现成模块加速开发；但如对框架本身有二次开发改动，需自行处理与新模块、未来框架升级的兼容问题 |
| 应用平台 | 运营者 / 采购方 | 后台"应用中心"安装、启用、停用、卸载本地模块 | 在线下载、付费购买、模块升级、模块作者生态 |
对开发者：拉源码 → 在 modules/{Module} 写业务 → 安装运行。这是本仓库文档主要服务的路径。开发者也可以从应用中心选购现成模块加速开发，但修改了框架核心代码后，应用中心模块和框架后续升级的兼容性需要自己评估和处理。建议把所有定制能力沉淀到模块中，尽量保持 app/、modules/System、frontend/admin/src、frontend/uniapp/src 等框架目录不动。
对运营者：登录后台 → 应用中心选择业务模块 → 一键安装；未来该流程会接入远程应用中心实现"按需选购"。
📦 三端组成
| 端 | 路径 | 说明 |
|---|---|---|
| 后端 | / | 基于 Laravel 13，提供 API、认证、模块、数据、上传、支付、AI 等能力 |
| Admin 管理端 | frontend/admin | 基于 Vue3 + TypeScript + Element Plus，承载后台管理和运营配置 |
| uni-app 客户端 | frontend/uniapp | 基于 uni-app Vue3 + TypeScript + Pinia，承载用户端 H5、小程序、App |
📏 技术栈
后端
| 技术 | 用途 |
|---|---|
| PHP 8.3+ | 后端运行环境 |
| Laravel 13 | 后端框架 |
| Spatie Route Attributes | 注解路由 |
| Laravel Sanctum | Token 认证 |
| Eloquent ORM | 模型、关联、查询构建 |
| Laravel Queue | 异步任务 |
| Laravel AI | AI 模型接入 |
| Laravel MCP | MCP Server 与工具接入 |
| 七牛 / 阿里云 OSS / 腾讯云 COS SDK | 云存储 |
Admin 管理端
| 技术 | 用途 |
|---|---|
| Vite | 开发与构建 |
| Vue 3 | 前端框架 |
| TypeScript | 类型约束 |
| Tailwind CSS | 样式 |
| Element Plus | 后台 UI 组件 |
| Pinia | 状态管理 |
| Vue Router | 路由 |
| Axios | HTTP 请求 |
| ECharts | 图表 |
| vxe-table | 高级表格 |
uni-app 客户端
| 技术 | 用途 |
|---|---|
| uni-app Vue3 | 跨端应用框架 |
| DCloud Vite CLI | H5、小程序、App 编译 |
| TypeScript | 类型约束 |
| Pinia | 状态管理 |
| uview-plus | 移动端 UI 组件 |
| z-paging | 分页列表 |
工程化与部署
| 技术 | 用途 |
|---|---|
| Composer 2.2+ | PHP 依赖管理 |
| npm | 前端依赖管理 |
| MySQL | 数据库存储 |
| Redis / File Cache | 缓存与队列 |
| Nginx / PHP-FPM | 生产部署 |
💎 核心能力
后端基础
- Laravel 13 工程结构。
- Sanctum Token 认证。
- Spatie Route Attributes 注解路由。
- 模块自动扫描与模块启动注册器注册。
- Controller、Request、接口业务动作 Action、Service、Dao、Model、Enum 分层。
- 统一响应结构
code/message/data。 - 统一异常码与前端错误处理约定。
权限与组织
- 后台管理员登录。
- RBAC 角色权限。
- 菜单树和动态路由。
- 按钮权限标识。
- 管理员、角色、菜单管理。
- 部门和岗位管理。
内容与运营
- 文章分类和文章管理。
- 协议内容管理。
- 公告配置。
- 短信配置。
- 媒体库和文件分类。
- 页面装修与移动端装修渲染。
- 搜索配置与搜索接口。
用户能力
- 用户资料。
- 用户地址。
系统配置
- 分组配置。
- 数据字典。
- 缓存管理。
- 站点状态开关。
- 存储驱动配置。
- 微信公众号、小程序配置。
- 应用接入配置。
- AI 模型配置。
上传与存储
- 图片、视频、普通文件上传。
- 本地存储。
- 七牛云。
- 阿里云 OSS。
- 腾讯云 COS。
- 媒体 URL 自动转换。
- 富文本资源 URL 转换。
支付能力
- 统一支付单。
- 默认支付驱动选择。
- 支付模块配置标签页。
- 微信支付等支付通道模块接入。
- 支付回调入口。
- 回调日志记录。
- 统一退款中心。
- 支付状态更新。
- 业务支付处理器分发。
AI 与 MCP
- 后台动态配置模型供应商。
- 文本生成。
- 向量生成。
- 知识库 RAG。
- AI 助手。
- 多轮上下文。
- MCP 工具列表、调用、聊天和 RPC。
- 官方 MCP Server 路由。
🛣️ 适用场景
SunAdmin 适用于：
- 企业后台管理系统。
- 内容运营平台。
- 用户中心和会员系统。
- H5 / 小程序 / App 一体化业务。
- 需要页面装修的移动端项目。
- 需要支付、上传、短信、微信和 AI 能力的业务系统。
- 需要在统一工程内快速扩展多个业务模块的项目。
🚧 不适用场景
以下场景可能需要额外改造：
- 极简静态官网。
- 完全无后端的纯前端项目。
- 超大规模微服务系统。
- 强实时音视频或游戏服务端。
- 已经有成熟独立权限中心、支付中心和文件中心的大型集团系统。
💡 开发理念
SunAdmin 的二次开发建议遵循：
- 保持模块边界清晰。
- 业务接口语义稳定。
- 权限、菜单、路由和页面同步维护。
- 配置、字典、缓存、上传、支付等基础能力走统一服务。
- Admin 与 uni-app 共享业务契约，但不强行共享运行时代码。
- 新增功能优先沉淀到文档和规范，避免只存在于个人经验里。
⚖️ 与普通脚手架的区别
| 对比项 | 普通脚手架 | SunAdmin |
|---|---|---|
| 后端结构 | 通常只给基础 Laravel/Vue 模板 | 已内置模块化业务分层 |
| 权限能力 | 可能只提供登录 | 提供 RBAC、菜单、按钮权限和动态路由 |
| 移动端 | 通常不包含 | 内置 uni-app Vue3 客户端 |
| 内容运营 | 需要自行开发 | 内置文章、协议、公告、装修 |
| 上传存储 | 常需自行封装 | 内置多存储驱动和媒体 URL 机制 |
| 支付 | 常需自行接入 | 提供统一支付基础能力，支付通道按模块接入 |
| AI | 通常没有 | 已接入 Laravel AI 与 MCP |
合法使用声明
使用 SunAdmin 及其衍生版本时，应遵守适用法律法规、监管要求和平台规则。项目不得用于色情、赌博、诈骗、洗钱、非法集资、侵权、恶意攻击、数据窃取或其他违法违规事项。因违法违规使用、部署、运营、二次开发或重新分发产生的一切风险、争议、处罚及法律责任，由使用者自行承担。
📚 阅读建议
第一次接触项目时，建议按以下顺序阅读：