# goravel-admin

**Repository Path**: gitee-pull/goravel-admin

## Basic Information

- **Project Name**: goravel-admin
- **Description**: 基于Goravel Gin + Vue3 + Element Plus + Vxe-table 的后台管理系统。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://github.com/1768177868/goravel-admin
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center"><img src="https://www.goravel.dev/logo.png?v=1.14.x" width="300"></p>

[English](./README.md) | 中文

## 关于 Goravel 

Goravel 是一个功能完整、可扩展性良好的 Web 应用框架。作为起始脚手架，帮助 Gopher 快速构建自己的应用程序。

框架风格与 [Laravel](https://github.com/laravel/laravel) 保持一致，让 Phper 无需学习新框架，也能愉快地使用 Golang！致敬 Laravel！

欢迎 Star、PR 和 Issues！

## 后台管理系统

本项目包含一个基于 Goravel 框架构建的完整后台管理系统。

```bash
git clone https://github.com/1768177868/goravel-admin.git
```

> 演示站 https://admin.xuancheng888.top

账号: demo  
密码: demo123


### 截图展示

<p align="center">
  <img src="./images/login.png" alt="登录页面" width="800">
  <p align="center">登录页面</p>
</p>

<p align="center">
  <img src="./images/admin.png" alt="后台管理界面" width="800">
  <p align="center">后台管理界面</p>
</p>

<p align="center">
  <img src="./images/generator.png" alt="代码生成器管理界面" width="800">
  <p align="center">代码生成器界面</p>
</p>

<p align="center">
  <img src="./images/monitor.png" alt="系统监控" width="800">
  <p align="center">系统监控</p>
</p>

<p align="center">
  <img src="./images/ai.png" alt="系统监控" width="800">
  <p align="center">AI代码生成器</p>
</p>

<p align="center">
  <img src="./images/pages.png" alt="cloudflare" width="800">
  <p align="center">cloudflare</p>
</p>

### 功能特性

#### 核心模块
- **认证与授权**
  - 基于角色的访问控制（RBAC）
  - 权限管理
  - 多令牌管理
  - 在线用户监控与踢出

- **管理员管理**
  - 管理员用户管理
  - 部门管理
  - 角色管理
  - 权限分配
  - 密码重置

- **系统配置**
  - 菜单管理（动态菜单）
  - 字典管理
  - 系统配置
  - 黑名单管理

- **日志与监控**
  - 操作日志（自动记录）
  - 登录日志
  - 系统日志（带追踪 ID）
  - 服务监控

- **附加功能**
  - 数据统计仪表盘
  - 通知中心（WebSocket 实时通知）
  - 数据导出管理
  - 多语言支持（中文/英文）
  - 响应式 UI 设计

### 技术栈

**后端：**
- Goravel 框架（Go）
- JWT 认证
- RBAC 权限系统
- WebSocket 支持
- 数据库迁移与填充

**前端：**
- Vue 3
- Element Plus
- vxe-table（高级表格组件）
- Vue Router
- Pinia（状态管理）
- Axios
- ECharts（数据可视化）
- vue-i18n（国际化）

### 快速开始

1. **后端配置：**
   ```bash
   # 安装依赖
   go mod download
   
   # 在 .env 中配置数据库
   # 运行数据库迁移和填充
   go run . artisan migrate
   go run . artisan db:seed
   
   # 启动服务
   go run . --no-ansi
   # 或使用 air 进行热重载
   air
   ```

2. **前端配置：**
   ```bash
   cd html
   
   # 安装依赖
   npm install
   
   # 在 .env 中配置 API 地址
   # VITE_API_BASE_URL=http://127.0.0.1:3000
   # VITE_API_PREFIX=/api/admin
   
   # 启动开发服务器
   npm run dev
   ```

3. **默认登录：**
   - 用户名：`admin`
   - 密码：`admin123`
   - （首次登录后请修改默认密码）

### 构建与部署

详细的编译打包和部署说明，包括跨平台编译、Docker 部署、systemd 服务配置等，请参考 [BUILD.md](./docs/BUILD.md)。

### API 文档

后台管理 API 接口前缀为 `/api/admin`。除登录和验证码接口外，所有接口都需要 JWT 认证。

详细的 API 文档请查看 [routes/admin.go](./routes/admin.go)

#### Swagger API 文档

项目包含 Swagger API 文档，支持交互式 API 探索。

**访问 Swagger 文档：**

Swagger JSON 文档访问地址：
- 本地开发：`http://localhost:3000/swagger/index.html`
- 生产环境：`https://your-domain.com/swagger/index.html`

**重新生成 Swagger 文档：**

修改 API 路由或添加新接口后，需要重新生成 Swagger 文档：

```bash
# 生成 Swagger 文档
swag init
```

这将根据代码中的 Swagger 注解（示例见 `main.go`）重新生成 `docs/docs.go`、`docs/swagger.json` 和 `docs/swagger.yaml` 文件。

### 项目结构

```
.
├── app/
│   ├── http/
│   │   ├── controllers/admin/    # 后台控制器
│   │   ├── middleware/           # 自定义中间件（JWT、权限、操作日志）
│   │   └── helpers/              # 辅助函数
│   ├── models/                   # 数据库模型
│   └── services/                 # 业务逻辑服务
├── routes/
│   └── admin.go                  # 后台路由
├── database/
│   ├── migrations/               # 数据库迁移
│   └── seeders/                  # 数据库填充
├── html/                         # 前端 Vue 应用
│   └── src/
│       ├── views/                # 页面组件
│       ├── components/           # 可复用组件
│       ├── api/                 # API 客户端
│       └── store/               # Pinia 状态管理
├── config/                       # 配置文件
├── docs/                         # 文档目录
│   ├── API.md                    # API 接口文档
│   ├── ARCHITECTURE.md           # 架构设计文档
│   ├── BUILD.md                  # 编译打包与部署
│   ├── SHARDING_MIGRATION.md     # 数据库分表指南
│   └── ...                       # 其他文档
├── CONTRIBUTING.md               # 贡献指南
├── CHANGELOG.md                  # 版本变更记录
└── images/                       # 截图文件
```

### 数据库分表

项目支持按月分表策略，已实现订单表的按月分表功能。关于如何创建、使用和修改分表的详细文档，请参考 [docs/SHARDING_MIGRATION.md](./docs/SHARDING_MIGRATION.md)。

### 安全特性

- 基于 JWT 令牌的认证
- 权限中间件保护路由
- 自动操作日志记录
- 日志中敏感数据过滤
- 登录接口限流
- IP/管理员黑名单管理
- 令牌撤销支持

## 快速入门

### 启动服务

`go run . --no-ansi` 或 `air`

[关于 air]：https://www.goravel.dev/getting-started/installation.html#live-reload

### Cloudflare Workers 部署

将前端应用部署到 Cloudflare Workers：

```bash
# 构建前端应用
cd html
# 注意：Cloudflare Workers 构建环境会自动运行 npm ci
# 如果遇到 Rollup 可选依赖问题，请使用以下构建命令：
npm install --include=optional @rollup/rollup-linux-x64-gnu && npm run build

# 或者使用项目提供的 CI 构建脚本：
npm run build:ci

# 部署到 Cloudflare Workers
npx wrangler deploy --assets ./dist --compatibility-date 2025-11-29 --name admin
```

**配置说明：**

- **根目录：** `html`
- **环境变量（变量和机密）：**
  - `VITE_API_BASE_URL`: `https://api.xuancheng888.top`
  - `VITE_API_PREFIX`: `/api/admin`
- **自定义域名：** `admin.xuancheng888.top`

**注意：** `worker.js` 文件会自动处理 SPA 路由，当文件不存在时返回 `index.html`。

### 性能分析

pprof 性能分析工具地址：http://localhost:3000/debug/pprof/

### 二进制压缩

为了减小二进制文件大小，可以使用 UPX（Ultimate Packer for eXecutables）压缩编译后的可执行文件：

**Windows：**

1. 下载 UPX（Windows 64 位版本）：
   - 官网下载：https://github.com/upx/upx/releases/latest
   - 选择 `upx-5.0.2-win64.zip`（或最新版本）
   - 解压到无中文或空格的路径（例如：`F:\tools\upx`）
   - 确保 `upx.exe` 可访问

2. 压缩二进制文件（PowerShell）：
   ```powershell
   # 方式1：临时添加 UPX 到环境变量（推荐）
   $env:PATH += ";F:\tools\upx"
   
   # 进入项目目录
   cd F:\www\go\admin\goravel-admin
   
   # 最高级别压缩（-9）
   upx -9 main
   ```

**Linux/macOS：**

```bash
# 安装 UPX（如果尚未安装）
# Ubuntu/Debian: sudo apt-get install upx
# macOS: brew install upx

# 压缩二进制文件
upx -9 main
```

## 文档

### 项目文档

| 文档 | 说明 |
|------|------|
| [API.md](./docs/API.md) | 完整 API 接口文档 |
| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | 系统架构设计 |
| [DEVELOPMENT_GUIDE.md](./docs/DEVELOPMENT_GUIDE.md) | 开发指南：CRUD 模块完整开发示例（以留言板模块为例，包含后端接口和前端页面） |
| [SHARDING_MIGRATION.md](./docs/SHARDING_MIGRATION.md) | 数据库分表指南（创建、使用和修改分表） |
| [BUILD.md](./docs/BUILD.md) | 编译打包与部署 |
| [TESTING.md](./docs/TESTING.md) | 测试指南（单元测试 & 集成测试） |
| [前端开发指南](./html/DEVELOPMENT.md) | 前端开发文档 |

### Goravel 框架文档

在线文档 [https://www.goravel.dev](https://www.goravel.dev)

> 要优化文档，请向文档仓库提交 PR
> [https://github.com/goravel/docs](https://github.com/goravel/docs)

## 社区

欢迎在 Discord 中讨论。

[https://discord.gg/cFc5csczzS](https://discord.gg/cFc5csczzS)

## 许可证

Goravel 框架是在 [MIT 许可证](https://opensource.org/licenses/MIT) 下发布的开源软件。