# ZsAdmin开源框架

**Repository Path**: zsadmincom/zsadmin

## Basic Information

- **Project Name**: ZsAdmin开源框架
- **Description**: ZsAdmin「智数」 是一款基于 ThinkPHP 8 和 Bootstrap 5 的轻量级后台开发框架，内置 Auth 权限与用户组菜单体系，支持自定义后台路径、Web 一键安装、站点配置与操作日志；提供插件 / 主题应用中心、钩子扩展与远程市场，业务前台（如社区、导航）按需安装挂载。（ZsAdmin 智数 轻量级快速开发框架）
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.zsadmin.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZsAdmin 智数后台开发框架

[![License](https://img.shields.io/badge/License-Apache-2.0-blue.svg)](LICENSE.txt)
[![ThinkPHP](https://img.shields.io/badge/ThinkPHP-8.x-brightgreen.svg)](https://github.com/topthink/thinkphp)
[![Bootstrap](https://img.shields.io/badge/Bootstrap-5.x-7952B3.svg)](https://getbootstrap.com/)

## 简介

ZsAdmin「智数」是一款基于 ThinkPHP 8 和 Bootstrap 5 开发的轻量级后台开发框架。框架内置完整的 RBAC 权限体系与用户组菜单管理，支持自定义后台入口路径、Web 一键安装、站点配置与操作日志审计；提供插件/主题应用中心、钩子扩展与远程市场，业务前台（如社区、导航）可按需安装挂载。

- 官网：https://www.zsadmin.com
- 应用市场：https://www.zsadmin.com/market.html
- 文档：https://doc.thinkphp.cn

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | ThinkPHP 8 + Composer 依赖管理 |
| 前端框架 | Bootstrap 5，后台 iframe 多标签页布局 |
| UI 组件 | Iconoir 图标库、Selectr 选择器、FlatPickr 日期选择器 |
| 数据存储 | MySQL 8.0+ |

## 核心功能

### 权限管理
- **RBAC 鉴权**：基于角色的访问控制，完整的权限节点管理
- **用户组管理**：灵活的用户组配置，支持多角色分配
- **菜单管理**：动态菜单生成，支持层级结构
- **操作日志**：完整的操作记录与审计追踪

### 系统功能
- **一键安装**：Web 向导式安装，自动检测环境、配置数据库、创建管理员
- **自定义后台路径**：灵活设置后台入口，支持路径重写
- **站点配置**：全局配置管理，支持缓存、存储、主题等设置
- **文件管理**：文件上传、扫描、删除，支持本地与云端存储

### 插件系统
- **插件管理**：安装、卸载、升级插件
- **主题管理**：多主题切换，前端主题化
- **钩子机制**：灵活的钩子扩展点，支持插件介入
- **远程市场**：连接官方应用市场，下载安装插件/主题

### 用户体系
- **前台用户管理**：用户 CRUD、用户等级、行为奖励
- **用户等级**：积分成长体系，支持自定义等级与权限
- **资产日志**：用户资产变动记录

## 目录结构

```
zsadmin/
├── app/                      # 应用核心目录
│   ├── controller/           # 控制器
│   │   ├── admin/            # 后台管理控制器
│   │   ├── Index.php         # 前台首页控制器
│   │   ├── Install.php       # 安装向导控制器
│   │   └── PluginAsset.php   # 插件静态资源控制器
│   ├── middleware/           # 中间件
│   │   ├── AdminAuth.php     # 后台鉴权
│   │   ├── AdminOperationLog.php  # 操作日志
│   │   ├── CheckInstall.php  # 安装检测
│   │   ├── SiteStatus.php    # 站点状态
│   │   └── ...
│   ├── model/                # 数据模型
│   │   ├── Admin.php         # 管理员模型
│   │   ├── User.php          # 用户模型
│   │   ├── AuthGroup.php     # 用户组模型
│   │   ├── AuthRule.php      # 权限节点模型
│   │   └── ...
│   ├── service/              # 业务服务
│   │   ├── AuthService.php   # 权限服务
│   │   ├── PluginService.php # 插件服务
│   │   ├── InstallService.php # 安装服务
│   │   └── ...
│   ├── validate/             # 数据验证
│   ├── command/              # 命令行任务
│   └── ...
├── config/                   # 配置文件目录
├── database/                 # 数据库脚本
│   └── install.sql           # 安装数据库脚本
├── public/                   # Web 根目录
│   ├── static/               # 静态资源
│   │   └── admin/            # 后台静态资源
│   └── index.php             # 入口文件
├── plugins/                  # 插件目录
├── themes/                   # 主题目录
├── runtime/                  # 运行时目录
├── composer.json             # Composer 配置
└── think                     # 命令行工具
```

## 环境要求

- PHP >= 8.0（推荐 PHP 8.5）
- MySQL 8.0+ 或 MariaDB 10.5+
- Nginx 或 Apache
- Composer

### PHP 扩展要求

| 扩展 | 说明 |
|------|------|
| pdo_mysql | MySQL 数据库驱动 |
| mbstring | 多字节字符串处理 |
| openssl | OpenSSL 加密 |
| json | JSON 序列化 |
| curl | HTTP 请求 |
| fileinfo | 文件信息检测 |

## 安装部署

### 方式一：Composer 安装

```bash
# 克隆项目
git clone https://gitee.com/zhangsens/zsadmin.git

# 进入项目目录
cd zsadmin

# 安装依赖
composer install

# 确保目录可写
chmod -R 755 runtime config public/static
```

### 方式二：手动部署

1. 下载 release 包并解压
2. 配置 Web 服务器（Apache/Nginx），将根目录指向 `public/`
3. 确保以下目录可写：`runtime/`、`config/`、`.env`、`public/static/`

### 配置 Web 服务器

**Nginx 配置示例：**

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /path/tozsadmin/public;
    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

**Apache 配置：**

项目已内置 `.htaccess`，确保 Apache 开启了 `mod_rewrite` 模块。

### 运行安装向导

1. 启动开发服务器：
   ```bash
   php think run
   ```

2. 浏览器访问：`http://127.0.0.1:8000/install`

3. 按照向导完成：
   - 环境检测
   - 数据库配置
   - 管理员账号设置
   - 后台路径设置

4. 安装成功后访问后台：`http://127.0.0.1:8000/admin`

### 重新安装

如需重新安装，删除 `config/install.lock` 文件后再次访问 `/install`。

## 使用指南

### 登录后台

- 默认后台地址：`/admin`
- 登录页：`/admin/login`
- 安装时可自定义后台路径

#### 界面截图
![后台首页](https://zsens.oss-cn-beijing.aliyuncs.com/images/2026/10/28/102155_932c3c46b7958b44.png)
![站点配置](https://zsens.oss-cn-beijing.aliyuncs.com/images/2026/10/28/102134_465cb4277376d4fe.png)
![应用插件](https://zsens.oss-cn-beijing.aliyuncs.com/images/2026/10/28/102134_9d317ce92528f86f.png)
![模板主题](https://zsens.oss-cn-beijing.aliyuncs.com/images/2026/10/28/102134_2505ed55ec5afee1.png)
![模板主题](https://zsens.oss-cn-beijing.aliyuncs.com/images/2026/10/28/102134_2505ed55ec5afee1.png)
![用户等级](https://zsens.oss-cn-beijing.aliyuncs.com/images/2026/10/28/102135_ab0540bbd7320126.png)

### 功能模块

| 模块 | 说明 |
|------|------|
| 系统管理 | 站点配置、菜单管理、文件管理 |
| 权限管理 | 用户组、权限节点、管理员、操作日志 |
| 用户管理 | 前台用户、用户等级、行为奖励、资产日志 |
| 应用中心 | 插件管理、主题管理 |
| 应用市场 | 远程应用市场、插件下载 |

### 插件开发

```php
// plugins/your_plugin/Info.php
<?php
namespace plugins\your_plugin;

class Info
{
    public $info = [
        'name'        => 'your_plugin',
        'title'       => '我的插件',
        'description' => '插件描述',
        'status'      => 1,
        'author'      => '作者',
        'version'     => '1.0.0'
    ];

    // 安装
    public function install()
    {
        // 创建数据库表等
        return true;
    }

    // 卸载
    public function uninstall()
    {
        // 清理数据
        return true;
    }

    // 升级
    public function upgrade($old_version)
    {
        return true;
    }
}
```

### 钩子使用

```php
// 在控制器中触发钩子
\app\service\HookService::render('hook_name', ['data' => $data]);

// 在插件中监听钩子
public function renderSlot($ctx)
{
    return '<div>插件内容</div>';
}
```

## 配置说明

### 站点配置

后台「系统管理」→「站点配置」中可配置：

- **基础设置**：站点名称、SEO 信息、备案号
- **缓存设置**：缓存驱动、缓存时间
- **上传设置**：存储方式（本地/云存储）、文件大小限制
- **安全设置**：后台路径、IP 限制

### 环境变量 (.env)

```env
APP_DEBUG = true
DEFAULT_TIMEZONE = Asia/Shanghai

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = zsadmin
USERNAME = root
PASSWORD =
HOSTPORT = 3306
CHARSET = utf8mb4
PREFIX = fa_

[LANG]
default_lang = zh-cn
```

## 常见问题

### 1. 访问 /install 报错 404

确保 Web 服务器正确配置，将请求重写到 `public/index.php`。

### 2. 安装完成后前台空白

检查 `config/install.lock` 是否存在，确保已正确安装。

### 3. 自定义后台路径失效

修改后台路径后，强制刷新浏览器避免缓存。

### 4. 插件无法安装

检查 `plugins/` 目录权限，确保有写入权限。


## 贡献指南

欢迎提交 Pull Request 或 Issue，请遵守以下规范：

1. 代码风格遵循 PSR-12
2. 提交信息清晰描述改动内容
3. 确保代码通过现有测试

## 版权信息

ZsAdmin 遵循 Apache 2.0 开源协议发布，并提供免费使用。

版权所有 © 2017-2026 by ZsAdmin (https://www.zsadmin.com)

All rights reserved.