# ZeroAdmin
**Repository Path**: Z568_568/ZeroAdmin
## Basic Information
- **Project Name**: ZeroAdmin
- **Description**: 基于 React 19 + Vite 8 + shadcn/ui 的现代化后台管理模板，内置 RBAC、多标签、多布局与主题系统，对移动端完全自适应，适合快速二开。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://zero.zhouyi.run
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16
## Categories & Tags
**Categories**: Uncategorized
**Tags**: React, React19, TypeScript, tailwindcss, shadcn-ui
## README
# ZeroAdmin
> 开箱即用的现代化 React 管理后台模板 — 权限、布局、主题、图表、上传、富文本，一应俱全，对移动端完全自适应。
>
> A ready-to-use modern React admin template — RBAC, layouts, themes, charts, uploads, and rich text, fully responsive on mobile.
基于 **React 19 + Vite 8 + TypeScript + Tailwind CSS 4 + shadcn/ui + Zustand** 构建，面向快速二开与企业中后台场景，桌面端与移动端均可流畅使用。
Built with **React 19 + Vite 8 + TypeScript + Tailwind CSS 4 + shadcn/ui + Zustand**, designed for rapid secondary development and enterprise mid/back-office scenarios. Smooth experience on both desktop and mobile.
**在线预览 / Demo：** [https://zero.zhouyi.run/](https://zero.zhouyi.run/)
**源码仓库 / Repo：** [Gitee · ZeroAdmin](https://gitee.com/Z568_568/ZeroAdmin)
---
## 预览截图
### 首页 · 公告弹窗
### 数据分析
### 用户管理
### 权限管理
### 系统设置
---
## 目录
- [预览截图](#预览截图)
- [特性](#特性)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [演示账号](#演示账号)
- [功能一览](#功能一览)
- [目录结构](#目录结构)
- [架构说明](#架构说明)
- [HTTP 请求封装（axios）](#http-请求封装axios)
- [文件上传组件](#文件上传组件)
- [富文本组件](#富文本组件)
- [如何新增页面](#如何新增页面)
- [权限体系](#权限体系)
- [规范约定](#规范约定)
- [本地持久化与退出登录](#本地持久化与退出登录)
- [常用脚本](#常用脚本)
- [License](#license)
---
## 特性
- **移动端适配**：对移动端完全自适应，侧栏 Sheet、响应式布局与触控友好交互
- **完整 RBAC**：菜单 / 路由 / 按钮三级权限，多级权限树，角色分配
- **四种布局**：图标轨、展开面板、顶栏命令、居中岛屿，可随时切换
- **多标签页**：切换、关闭、刷新、关闭左/右/其他/全部，支持右键菜单
- **主题系统**：10 种主题色 + 浅色 / 深色 / 跟随系统
- **数据看板**：ECharts 多图类型（折线、柱状、堆叠、饼图等）
- **系统管理**：用户、角色、权限、操作日志、系统设置
- **工程能力**：axios 封装、文件上传、TipTap 富文本、Hash 路由静态部署
- **开箱即用**：登录鉴权、公告弹窗、页面水印、403 / 404 页
---
## 技术栈
| 类别 | 选型 |
|-----|--------------------------------|
| 框架 | React 19、React Router 7（Hash 模式） |
| 构建 | Vite 8、TypeScript |
| 样式 | Tailwind CSS 4、`@/` 路径别名 |
| 组件 | shadcn/ui（Radix 原语） |
| 状态 | Zustand（部分 `persist`） |
| 图表 | ECharts 6 |
| 请求 | axios（`src/api` 统一封装） |
| 富文本 | TipTap（`RichTextEditor`） |
| 主题 | next-themes（浅色 / 深色 / 跟随系统） |
| 图标 | lucide-react |
| 校验 | oxlint |
| 环境 | Node 22 |
---
## 快速开始
环境要求：**Node.js 22+**（见 `.nvmrc`）。
```bash
nvm use
npm install
npm run dev
```
浏览器访问终端提示的本地地址（默认 `http://localhost:5173`）。
生产环境在线地址：[https://zero.zhouyi.run/](https://zero.zhouyi.run/)
```bash
npm run build # 类型检查 + 生产构建
npm run preview # 预览构建产物
npm run lint # oxlint
```
---
## 演示账号
密码均为 `123456`。
| 账号 | 角色 | 说明 |
|------|------|------|
| `admin` | 超级管理员 | 通配权限 `*`，可访问全部功能 |
| `operator` | 运营 | 业务相关权限（用户 / 部分系统页） |
| `guest` | 访客 | 只读类权限 |
退出登录会清理会话相关缓存，重新登录固定进入 **首页** `/dashboard`。
---
## 功能一览
### 布局与交互
- 后台壳层：外框画布 + 最左侧品牌脊 + 侧栏 / 顶栏
- **四种布局**：`rail` / `panel` / `top` / `island`（系统设置中切换）
- **多标签页**：切换、关闭、刷新、关闭左/右/其他/全部；标签右键菜单
- **面包屑**、移动端侧栏 Sheet
- **页面水印**（系统设置开关）
- **全局通知公告弹窗**（登录后自动弹出未读；顶栏铃铛可再次打开）
### 主题
- 主题色：mono / slate / blue / cyan / green / amber / orange / rose / violet / fuchsia
- 外观：浅色 / 深色 / 跟随系统
- 配置入口：**系统管理 → 系统设置**
### 权限（RBAC）
- 权限管理：多级目录树（如 系统管理 → 用户管理 → 增删改查）
- 角色管理：勾选权限树分配
- 菜单按权限过滤；路由无权限跳转 `/403`
- 按钮级：`PermissionGate` / `usePermission`
- 超管权限码：`*`
### 业务演示页
| 页面 | 路径 | 说明 |
|------|------|------|
| 登录 | `/login` | 独立全屏，不套后台布局 |
| 首页 | `/dashboard` | KPI、趋势图、快捷入口、日志/待办/公告 |
| 数据分析 | `/analytics` | 多类型 ECharts |
| 用户管理 | `/system/users` | 筛选、排序、列显隐、分页；**新增/编辑/详情为弹窗** |
| 角色管理 | `/system/roles` | 角色 CRUD + 权限树 |
| 权限管理 | `/system/permissions` | 多级权限目录 CRUD |
| 操作日志 | `/system/logs` | 筛选、分页、单删/批量删除 |
| 系统设置 | `/system/settings` | 布局 / 主题色 / 外观 / 水印 |
| 个人中心 | `/profile` | 资料、富文本简介、权限摘要 |
| 403 | `/403` | 无权限（布局内） |
| 404 | `/404` 与 `*` | 独立全屏，风格对齐登录页 |
---
## 目录结构
```text
src/
├── App.tsx # ThemeProvider + 路由入口
├── main.tsx
├── index.css # 主题变量、布局动画、编辑器样式
├── config/ # 静态配置（菜单、权限码、主题、路由元信息）
├── router/index.tsx # 路由表（HashRouter）
├── stores/ # Zustand 状态
├── pages/ # 页面
├── api/ # axios 封装与接口模块
│ ├── request.ts # get/post/put/del/upload
│ ├── modules/ # 按业务拆分
│ └── examples.usage.tsx # 使用示例（参考用）
├── components/
│ ├── layout/ # 后台布局、标签栏、公告、水印
│ ├── auth/ # PermissionGate、PermissionTree
│ ├── charts/ # EChart 封装
│ ├── editor/ # TipTap 富文本
│ ├── upload/ # 公共上传 FileUpload
│ └── ui/ # shadcn 基础组件
├── hooks/
└── lib/
```
路径别名：`@/` → `src/`。
环境变量见 `.env.example`：`VITE_API_BASE_URL`、`VITE_API_TIMEOUT`。
---
## 架构说明
```text
┌─────────────┐
│ /login │ 独立页
│ /404 │
└─────────────┘
│
登录后 ────────────────────▼────────────────────
┌────────────────────────┐
│ AdminLayout │
│ 鉴权 + 路由权限守卫 │
│ 侧栏 / 顶栏 / 标签栏 │
│ 公告弹窗 / 水印 │
└───────────┬────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
业务页面 系统管理 个人中心
```
**分层约定**
1. **config**：无副作用的常量与树配置
2. **stores**：业务状态与本地演示数据
3. **pages**：页面编排
4. **components**：可复用 UI
5. **api / hooks / lib**：请求与横切能力
当前为 **纯前端演示模板**（无真实后端）。对接接口时：在 `src/api/modules` 写接口方法，在 `stores` 或页面中调用。
---
## HTTP 请求封装（axios）
```ts
import { get, post, put, del, upload } from '@/api'
const list = await get('/system/users', { page: 1, pageSize: 10 })
const user = await post('/system/users', { name: '张三' })
await put(`/system/users/${user.id}`, { name: '李四' })
await del(`/system/users/${user.id}`)
const { url } = await upload(file, { onProgress: (p) => console.log(p) })
```
能力概要：自动注入 Bearer Token、统一解包 `{ code, data }`、`401` 自动登出、支持上传进度。
模块化示例见 `src/api/modules/user.ts`，完整示例见 `src/api/examples.usage.tsx`。
---
## 文件上传组件
```tsx
import { FileUpload, type UploadFileItem } from '@/components/upload'
{
const result = await upload(file, { onProgress })
return result.url
}}
/>
```
支持拖拽、进度、数量/大小限制；默认走 `api.upload`，无后端时可降级本地预览。
---
## 富文本组件
```tsx
import { RichTextEditor } from '@/components/editor'
(await upload(file)).url}
/>
```
基于 TipTap：标题、加粗/斜体、列表、对齐、链接、代码块、图片；支持粘贴 / 拖拽插图。
---
## 如何新增页面
以「订单管理」`/system/orders` 为例：
1. 在 `src/config/permissions.ts` 增加权限码与种子节点、`ROUTE_PERMISSIONS`
2. 在 `src/config/menus.ts` 增加菜单项
3. 编写 `src/pages/system/orders.tsx`
4. 在 `src/router/index.tsx` 注册路由
5. 按钮级权限用 `PermissionGate` / `usePermission`
6. 在角色管理中勾选新权限（超管 `*` 自动拥有）
列表可参考 `users.tsx`；表单/详情优先用 **Dialog**。
---
## 权限体系
| 层级 | 实现 |
|------|------|
| 菜单 | `filterMenusByPermissions` |
| 路由 | `AdminLayout` 内守卫，失败 → `/403` |
| 按钮 | `PermissionGate`、`usePermission()` |
| 数据 | permissions 树 → roles 持有权限码 → auth 登录解析 |
权限码建议：`module:resource:action`，如 `system:users:create`。
---
## 规范约定
### 路由
- 使用 **Hash 模式**（`HashRouter`），地址形如 `/#/dashboard`，静态托管刷新不会 404
- 业务内跳转仍用 `/dashboard` 等路径
### 代码
- 路径别名统一 `@/`
- 重要业务逻辑加中文注释
- 异步操作使用 try/catch，对用户提示友好文案
- CRUD 优先弹窗，减少标签污染
---
## 本地持久化与退出登录
| Key | 内容 |
|-----|------|
| `zero-admin-auth` | 登录态 |
| `zero-admin-tabs` | 标签页 |
| `zero-admin-announcements` | 公告已读 |
| `zero-admin-layout-v2` | 布局与主题 |
| `zero-admin-roles` / `permissions` / `logs` | 角色 / 权限 / 日志 |
退出登录会重置上述会话缓存并跳转 `/login`。
---
## 常用脚本
```bash
npm run dev # 开发
npm run build # tsc -b && vite build
npm run preview # 预览生产包
npm run lint # oxlint
```
---
## License
[MIT](./LICENSE) © ZeroAdmin
欢迎 Star / Fork / PR。Issue 可在 [Gitee 仓库](https://gitee.com/Z568_568/ZeroAdmin) 提交。