Download the PHP package zoujingli/smartadmin without Composer

# SmartAdmin

基于 Hyperf 3.2 + Swoole 6.2 + Vue 3 + TypeScript 的高性能前后端一体化管理系统框架。

采用插件化分层架构，内置完整的 RBAC 权限体系、多租户支持和一键二进制打包能力，可将整个应用（后端 + 前端资源包）打包为单个可执行文件，实现低依赖部署。

公开仓库与安装方式

SmartAdmin 公开生态由主项目和两个 Composer 基础包组成，普通用户直接使用 zoujingli/smartadmin 创建项目即可运行和二次开发。

推荐通过 Composer 创建正式发布版项目：

需要扩展插件时，可在 SmartAdmin 源码环境通过 xadmin:plugin:install <zip> 安装或用 --force 更新 ZIP 插件，再重新执行 Composer 更新和前端构建。私有/商用插件不发布 Composer 远程包，只通过 ZIP 分发，ZIP 内的 composer.json 仅用于本地 path autoload。

快捷入口

• 文档中心：docs/README.md
• 快速开始：docs/快速开始/README.md
• 用户教程：docs/用户教程/README.md
• 接口参考：docs/接口参考/README.md
• 开源协作：docs/开源协作/README.md

常见排障入口

• 登录/鉴权问题：docs/开源协作/常见问题.md
• 权限/菜单不一致：docs/架构设计/权限与菜单.md
• 上传异常：docs/系统功能/文件上传与存储.md
• 发布升级异常：docs/部署运维/发布升级.md
• 日志诊断：docs/系统功能/日志审计与公告.md

特性亮点

• 高性能协程架构 — 基于 Swoole 协程引擎，单进程可处理数万并发连接
• 插件化分层设计 — SmartAdminLibrary 作为基础库、System 作为基础插件、SmartAdminBuilder 作为独立构建包，业务能力通过 plugin/<Business> 接入，Web 仅提供通用壳与共享运行库
• 完整权限体系 — 注解声明 + 菜单编码 + 节点注册表，三位一体的 RBAC 权限控制
• 多租户就绪 — 行级数据隔离，平台/租户空间自动切换
• 前后端一体打包 — composer build 复用已生成 web/dist 生成跨平台二进制，部署只需一个文件 + 一份 .env
• 前端运行时配置 — 后端动态注入 API 地址和应用标题，部署后可改无需重新构建前端
• 现代前端技术栈 — Vue 3 + Vben Admin + Ant Design Vue，Monorepo 工程化管理

技术栈

项目结构

公开 SmartAdmin 主仓保持可直接运行和二次开发的最小源码结构；基础库与构建器通过独立 Composer 包安装到 vendor/，私有/商用插件只在本地安装 ZIP 后进入 plugin/<Module>。

zoujingli/smart-admin-library 与 zoujingli/smart-admin-builder 是独立公开 Composer 包，正式环境可直接使用已发布版本；私有/商用插件通过 ZIP 安装后进入本地 plugin/<Module>，不属于 SmartAdmin 开源主仓目录。

快速开始

环境要求

Composer 脚本默认通过 bin/smart.php runtime 选择仓库内置 Swoole 6.2 运行时；本机没有对应架构的内置运行时时，才回退到带 Swoole/OpenSwoole 扩展的 php。项目统一使用 bin/smart.php 作为命令入口；无参数 ./bin/smart.php 默认进入开发 watch 模式，生产或一次性前台服务请显式执行 ./bin/smart.php start。

后端安装

推荐直接使用已发布的 Composer 包创建项目；这样会从 Packagist 安装 zoujingli/smartadmin 的正式版本，并自动安装后端依赖。

如果需要跟踪 GitHub master 或参与贡献，也可以克隆公开仓源码：

完成项目创建或克隆后，继续配置环境、初始化数据库并启动服务：

如果解压或复制后执行权限丢失，先执行 chmod +x ./bin/smart.php；./bin/smart.php 默认等价于开发 watch 启动，只适合本地源码调试。生产环境请用 ./bin/smart.php start 配合 systemd、Supervisor 或容器编排管理进程，不要使用无参数入口或 watch 模式。

前端安装

前端开发默认直连后端 http://127.0.0.1:9501（由 apps/web-antd/.env.development 中 VITE_DEV_USE_PROXY=false 控制，具体 VITE_GLOB_API_URL 由 vite.config.mts 注入）。若希望走 Vite 代理（避免配置 CORS），可在该文件将 VITE_DEV_USE_PROXY 设为 true，或使用 pnpm dev:antd:proxy；代理模式统一请求 /api/<真实接口前缀>，由 Vite 转发到后端真实路径。强制直连可用 pnpm dev:antd:direct。

默认访问

在线演示站使用 APP_ENV=demo 运行，可正常登录和体验查询、Project 普通业务流程；系统基础资料、账号权限、全局配置、微信配置、删除、恢复和禁用类操作会返回 演示环境禁止修改关键数据。

核心功能

系统管理（System 模块）

权限体系

采用三层权限模型，注解声明与数据库存储相结合：

• 操作权限：通过 #[Auth] 注解声明接口级访问控制
• 数据权限：通过 Scope 机制控制查询可见范围（全部 / 本部门 / 本人）
• 节点权限：角色绑定权限节点，用户权限由角色自动聚合
• 超管通配：超级管理员持有 * 节点，短路所有权限校验

多租户（System 内置能力）

• 共享库、共享表、行级隔离策略
• 统一 tenant_id 字段自动注入与过滤
• 平台空间与租户空间自动切换
• 合入 System 的租户管理接口（/system/tenant/*）
• 租户菜单基线通过注册表聚合

前端功能

基于 Vben Admin Pro 深度定制，已实现以下页面：

• 用户管理（列表、新增、编辑、查看、角色/部门/岗位分配）
• 角色管理（列表、权限树分配）
• 菜单管理（树形列表、新增、编辑）
• 部门管理（树形列表、成员管理）
• 岗位管理（列表、CRUD）
• 日志管理（查询、详情、监控）
• 系统总览（运行信息、能力矩阵）

API 接口规范

所有接口遵循 RESTful 风格，统一响应格式：

HTTP status 固定返回 200，body.code 约定：200 成功、401 Token 缺失/过期/无效或刷新失败、403 有效 Token 无操作权限、404 页面或 API 路由不存在、500 业务异常/校验失败/数据不存在。统一响应由 ResponseExceptionHandler 输出，路由 404 不单独维护第二套处理器。

标准 CRUD 接口路径：

分层架构

Library — 基础能力层

不绑定具体业务类型的通用底座，提供：

• 四大基类：CoreController / CoreService / CoreMapper / CoreModel
• 认证体系：JWT 签发与校验、Token 黑名单、会话管理
• 注解系统：#[Auth] 权限注解、#[Logger] 日志注解
• 切面拦截：AuthAspect 权限校验、LoggerAspect 自动日志
• 统一异常：标准化错误响应（SuccessResponseException / ErrorResponseException 等）
• 工具集合：查询构建器、数组树处理、表单校验、请求解析
• 中间件：CORS 跨域、请求日志、站点静态服务（SiteMiddleware）
• 全局函数：syspath() / runpath() / _once() / _query() / _cache() 等
• 租户上下文：TenantContext 协程安全的租户标识管理

System — 系统管理核心层

任何后台项目都需要的标准管理能力，并内置平台租户管理：

• 12 个控制器覆盖认证、用户、角色、菜单、部门、岗位、租户、文件、日志、公告、数据、设置
• 完整的 Service / Mapper / Model 三层实现
• plugin.json 菜单基线 + 权限节点同步机制
• 数据权限范围与租户范围自动注入

SmartAdminBuilder — 构建工具

独立 Composer 包 zoujingli/smart-admin-builder 提供 Phar 打包与 SFX 二进制生成：

• 智能文件过滤（排除测试、文档等非运行时文件）
• AST 级代码改写（适配 Phar 流路径）
• 外部挂载机制（.env 运行时读取）
• 前端资源自动打包

构建与部署

一键构建

SmartAdmin 支持将整个应用打包为独立可执行文件：

构建产物：

构建流程

发布指令合集

.php-sfx-packer.php 是标准打包编排器，支持 build、precompile、audit、pack 四种模式；单独合并 SFX 时使用 @php .php-sfx-packer.php pack system.bin build/system。

Swoole 基库

项目内置 bin/swoole-linux-x64、bin/swoole-linux-a64、bin/swoole-macos-a64 为精简 PHP 8.4 + Swoole 6.2 SFX 运行时，构建审计会校验必要扩展与禁用扩展。若需要自定义扩展或重新构建基库，可参考 zoujingli/phpsfx；本仓库不内置 phpsfx 构建工具。

最小化部署

最小启动只需两个文件即可运行；数据库安装包已经打入 Phar，运行备份默认写入二进制同级 runtime/backup：

Swoole CLI 的 SFX 包装层需要通过 --self 进入追加的应用 Phar；二进制模式下执行应用命令统一使用 ./system-xxx --self <command>。

启动后自动创建：

环境配置

所有运行参数通过 .env 控制，无需修改代码：

前端动态配置

SiteMiddleware 拦截 /_app.config.js 请求，将 .env 中的 APP_TITLE、APP_API_URL 动态生成为 JavaScript 注入前端运行时，实现部署后修改前端行为而无需重新构建前端。

静态资源加速

Phar 内部携带 storage/extra/web-dist.zip 和 storage/extra/release/*，不会再打入 raw web/dist 目录，也不依赖外置数据库安装包目录。Phar 首次 start 且 public/index.html 缺失时会自动发布；也可以手动发布到 public/ 目录，由 Swoole 原生处理器直接服务：

路径系统

两个全局函数确保开发环境与 Phar 环境行为一致：

开发指南

新模块接入流程

1. 在对应插件的 stc/migrations 维护开发期基线迁移，并由 plugin.migration_root 显式启用
2. 新增 Model / Mapper / Service / Controller（分别继承四大基类）
3. 添加 #[Auth] 权限注解和 #[Logger] 日志注解
4. 在插件 plugin.json 声明应用、菜单、按钮权限、模块摘要和相对 view
5. 将前端页面、API service、routes.ts 或 auth-entry.ts 放入插件自己的 plugin.view_root
6. Provider 仅注册注解扫描、依赖、监听器和运行期命令等装配能力
7. 在源码/CI 环境执行迁移，并按需执行 xadmin:menu:sync、xadmin:node:sync；插件分发可使用 SmartAdminLibrary 提供的 xadmin:plugin:* 源码命令
8. 若发布二进制，先生成 web/dist，再执行 composer build

源码插件管理命令

xadmin:plugin:* 命令由 SmartAdminLibrary 提供，仅源码/CI 模式出现；发布 Phar/SFX 二进制不会注册这些命令。普通插件包文件名固定为 plugin-插件code-插件版本.zip（如 plugin-demo-1.0.0.zip），ZIP 顶层包含 composer.json、plugin.json、src/、stc/ 等；备份包默认包含插件代码和 _xadmin/plugin-backup.json，只有指定 --with-data 或执行 remove 自动备份时才额外包含数据库结构与数据快照。插件自有表通过 plugin.tables、plugin.table_prefixes 或 plugin.code 下划线前缀识别。

备份默认写入 runtime/plugin/backups，文件名为 插件code-版本号-backup-YYYYMMDD-HHMMSS.zip；恢复仅传文件名时从该目录读取，且 .zip 可省略，传绝对路径或带目录的相对路径时按指定路径读取。带数据备份恢复时默认恢复数据，可用 --no-data 只恢复代码。安装/恢复会维护根 composer.json 的 path repository 与 require，并执行 Composer 更新；若插件包含 plugin.view_root，仍需执行 composer web:build 重新生成前端产物。SmartAdminLibrary 属于基础库、System 属于基础插件，SmartAdminBuilder 属于基础构建包，不允许通过插件管理命令移除或覆盖。

常用命令

文档索引

License

SmartAdmin is open source software licensed under the Apache License 2.0. Third-party components keep their own licenses; key attribution details are kept in NOTICE.