README.md 12.7 KB
Newer Older
a303176530's avatar
a303176530 已提交
1

a303176530's avatar
a303176530 已提交
2 3 4 5 6 7
<div align=center>
<img src="http://qmplusimg.henrongyi.top/gvalogo.jpg" width=300" height="300" />
</div>
<div align=center>
<img src="https://img.shields.io/badge/golang-1.12-blue"/>
<img src="https://img.shields.io/badge/gin-1.4.0-lightBlue"/>
8 9
<img src="https://img.shields.io/badge/vue-2.6.10-brightgreen"/>
<img src="https://img.shields.io/badge/element--ui-2.12.0-green"/>
a303176530's avatar
a303176530 已提交
10
<img src="https://img.shields.io/badge/gorm-1.9.12-red"/>
a303176530's avatar
a303176530 已提交
11 12
</div>

a303176530's avatar
a303176530 已提交
13
[English](./README-en.md) | 简体中文
a303176530's avatar
a303176530 已提交
14

a303176530's avatar
a303176530 已提交
15 16
# 项目文档
[在线文档](https://www.gin-vue-admin.com/) : https://www.gin-vue-admin.com/
a303176530's avatar
a303176530 已提交
17

a303176530's avatar
a303176530 已提交
18 19 20
[开发教学](https://www.gin-vue-admin.com/docs/help) (贡献者:  <a href="https://github.com/LLemonGreen">LLemonGreen</a> And <a href="https://github.com/fkk0509">Fann</a>)
- 前端UI框架:[element-ui](https://github.com/ElemeFE/element) 
- 后台框架:[gin](https://github.com/gin-gonic/gin) 
a303176530's avatar
a303176530 已提交
21

a303176530's avatar
a303176530 已提交
22
## 1. 基本介绍
23

a303176530's avatar
a303176530 已提交
24
### 1.1 项目介绍
25

a303176530's avatar
a303176530 已提交
26
[在线预览](http://demo.gin-vue-admin.com/)
a303176530's avatar
a303176530 已提交
27

a303176530's avatar
a303176530 已提交
28
测试用户名:admin
a303176530's avatar
a303176530 已提交
29

a303176530's avatar
a303176530 已提交
30
测试密码:123456
a303176530's avatar
a303176530 已提交
31

a303176530's avatar
a303176530 已提交
32
> Gin-vue-admin是一个基于vue和gin开发的全栈前后端分离的后台管理系统,集成jwt鉴权,动态路由,动态菜单,casbin鉴权,表单生成器,代码生成器等功能,提供多种示例文件,让您把更多时间专注在业务开发上。
a303176530's avatar
a303176530 已提交
33

a303176530's avatar
a303176530 已提交
34 35
### 1.2 贡献指南
Hi! 首先感谢你使用 gin-vue-admin。
36

a303176530's avatar
a303176530 已提交
37
Gin-vue-admin 是一套为后台管理平台准备的一整套前后端分离架构式的开源框架,旨在快速搭建后台管理系统。
38

a303176530's avatar
a303176530 已提交
39
Gin-vue-admin 的成长离不开大家的支持,如果你愿意为 gin-vue-admin 贡献代码或提供建议,请阅读以下内容。
R
rainyan 已提交
40

a303176530's avatar
a303176530 已提交
41 42
#### 1.2.1 Issue 规范
- issue 仅用于提交 Bug 或 Feature 以及设计相关的内容,其它内容可能会被直接关闭。如果你在使用时产生了疑问,请到 Slack 或 [Gitter](https://gitter.im/ElemeFE/element) 里咨询。
R
rainyan 已提交
43

a303176530's avatar
a303176530 已提交
44
- 在提交 issue 之前,请搜索相关内容是否已被提出。
R
rainyan 已提交
45

a303176530's avatar
a303176530 已提交
46 47
#### 1.2.2 Pull Request 规范
- 请先 fork 一份到自己的项目下,不要直接在仓库下建分支。
R
rainyan 已提交
48

a303176530's avatar
a303176530 已提交
49
- commit 信息要以`[文件名]: 描述信息` 的形式填写,例如 `README.md: fix xxx bug`
R
rainyan 已提交
50

a303176530's avatar
a303176530 已提交
51
- <font color=red>确保 PR 是提交到 `develop` 分支,而不是 `master` 分支。</font>
R
rainyan 已提交
52

a303176530's avatar
a303176530 已提交
53
- 如果是修复 bug,请在 PR 中给出描述信息。
R
rainyan 已提交
54

a303176530's avatar
a303176530 已提交
55
- 合并代码需要两名维护人员参与:一人进行 review 后 approve,另一人再次 review,通过后即可合并。
R
rainyan 已提交
56

a303176530's avatar
a303176530 已提交
57
### 1.3 版本列表
R
rainyan 已提交
58

a303176530's avatar
a303176530 已提交
59 60
- master: 2.0, 用于生产环境
- develop: 2.0, 用于测试环境
Sliver_Horn's avatar
Sliver_Horn 已提交
61 62
- [gin-vue-admin_v2_dev](https://github.com/flipped-aurora/gin-vue-admin/tree/gin-vue-admin_v2_dev) (v2.0 [GormV1版本](https://v1.gorm.io)稳定分支)
- [gva_gormv2_dev](https://github.com/flipped-aurora/gin-vue-admin/tree/gva_gormv2_dev) (v2.0 [GormV2版本](https://v2.gorm.io)开发分支)
R
rainyan 已提交
63

a303176530's avatar
a303176530 已提交
64
## 2. 使用说明
65

a303176530's avatar
a303176530 已提交
66 67 68 69 70 71 72 73
```
- node版本 > v8.6.0
- golang版本 >= v1.11
- IDE推荐:Goland
- 各位在clone项目以后,把db文件导入自己创建的库后,最好前往七牛云申请自己的空间地址。
- gormv2版本初始化数据库可以利用批量创建功能,这里已经写好初始化代码,需要在main.go内打开 initialize.Data() 的注释即可
- 替换掉项目中的七牛云公钥,私钥,仓名和默认url地址,以免发生测试文件数据错乱
```
74

a303176530's avatar
a303176530 已提交
75 76
> 使用docker-compose体验本项目
- 安装 docker-compose [官方文档](https://docs.docker.com/compose/install/)
77
    - ```shell script
a303176530's avatar
a303176530 已提交
78 79
       # 在Linux安装
       # 1.1 运行此命令以下载Docker Compose的当前稳定版本
80
       sudo curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
a303176530's avatar
a303176530 已提交
81
       # 1.2 将可执行权限应用于二进制文件
82 83 84
       sudo chmod +x /usr/local/bin/docker-compose 
      ```
    - ```shell script
a303176530's avatar
a303176530 已提交
85
       # 使用Python的pip安装 
86 87
       pip3 install docker-compose -i https://pypi.tuna.tsinghua.edu.cn/simple
      ```
a303176530's avatar
a303176530 已提交
88
    - 使用 Docker Desktop 
89 90 91
        - Windows: https://hub.docker.com/editions/community/docker-ce-desktop-windows
        - Mac: https://hub.docker.com/editions/community/docker-ce-desktop-mac/

a303176530's avatar
a303176530 已提交
92
- 使用git克隆本项目
93 94 95
    - ```git
        git clone https://github.com/flipped-aurora/gin-vue-admin.git
      ```
96
    
a303176530's avatar
a303176530 已提交
97
- 使用docker-compose up一键启动启动项目
98
    - ```shell script
a303176530's avatar
a303176530 已提交
99
      # 使用docker-compose启动四个容器
100
      docker-compose up
a303176530's avatar
a303176530 已提交
101
      # 如果您修改了某些配置选项,可以使用此命令重新打包镜像
102
      docker-compose up --build
a303176530's avatar
a303176530 已提交
103
      # 使用docker-compose 后台启动
104 105 106
      docker-compose up -d
      ```

107
    - web项目预览 [http://127.0.0.1:8000](http://127.0.0.1:8000)
a303176530's avatar
a303176530 已提交
108 109

    - swagger文档 [http://127.0.0.1:8888/swagger/index.html](http://127.0.0.1:8888/swagger/index.html)
110

111 112
- 如果server的177.7.0.12这个容器内部ip被占用了,需要修改地方为

Sliver_Horn's avatar
Sliver_Horn 已提交
113 114
	- [docker-compose.yaml](./docker-compose.yaml)的第39行的177.7.0.12更换为你想要的ip
	- [.docker-compose/nginx/conf.d/my.conf](./.docker-compose/nginx/conf.d/my.conf)的第20行的177.7.0.12更换为你想要的ip
115 116 117 118 119 120 121 122 123 124

- docker-compose使用自定义的一个docker网络

	- ```dockerfile
		networks:
		  network:
		    ipam:
		      driver: default
		      config:
		        - subnet: '177.7.0.0/16' 
125 126
		```

127 128 129 130
	- 子网地址, 默认网关是177.7.0.1(docker-compose V2需要写,V3则不需要),具体信息看[官方文档](https://docs.docker.com/compose/compose-file/#ipv4_address-ipv6_address)

	- 默认的network名为gin-vue-admin_network,默认是bridge模式

Sliver_Horn's avatar
Sliver_Horn 已提交
131
	- 如果修改了子网,对应的每个service的ipv4_address都需要修改,还有[.docker-compose/nginx/conf.d/my.conf](./.docker-compose/nginx/conf.d/my.conf)的第20行的server的ip也需要修改
132

a303176530's avatar
a303176530 已提交
133
### 2.1 web端
a303176530's avatar
a303176530 已提交
134

135 136 137
```bash
# clone the project
git clone https://github.com/piexlmax/gin-vue-admin.git
a303176530's avatar
a303176530 已提交
138

139 140
# enter the project directory
cd web
a303176530's avatar
a303176530 已提交
141

142 143
# install dependency
npm install
a303176530's avatar
a303176530 已提交
144

145
# develop
a303176530's avatar
a303176530 已提交
146
npm run serve
147
```
a303176530's avatar
a303176530 已提交
148

a303176530's avatar
a303176530 已提交
149
### 2.2 server端
a303176530's avatar
a303176530 已提交
150

151
```bash
a303176530's avatar
a303176530 已提交
152
# 使用 go.mod
a303176530's avatar
a303176530 已提交
153

a303176530's avatar
a303176530 已提交
154
# 安装go依赖包
155
go list (go mod tidy)
a303176530's avatar
a303176530 已提交
156

a303176530's avatar
a303176530 已提交
157
# 编译
158 159
go build
```
a303176530's avatar
a303176530 已提交
160

a303176530's avatar
a303176530 已提交
161
### 2.3 swagger自动化API文档
a303176530's avatar
a303176530 已提交
162

a303176530's avatar
a303176530 已提交
163
#### 2.3.1 安装 swagger
S
sun_song_1203 已提交
164

a303176530's avatar
a303176530 已提交
165
##### (1)可以翻墙
166 167 168
````
go get -u github.com/swaggo/swag/cmd/swag
````
a303176530's avatar
a303176530 已提交
169

a303176530's avatar
a303176530 已提交
170
##### (2)无法翻墙
171

a303176530's avatar
a303176530 已提交
172
由于国内没法安装 go.org/x 包下面的东西,推荐使用 [goproxy.io](https://goproxy.io/zh/)
173

a303176530's avatar
a303176530 已提交
174 175 176
```bash
如果您使用的 Go 版本是 1.13 及以上(推荐)
# 启用 Go Modules 功能
177
go env -w GO111MODULE=on 
a303176530's avatar
a303176530 已提交
178
# 配置 GOPROXY 环境变量
179
go env -w GOPROXY=https://goproxy.io,direct
a303176530's avatar
a303176530 已提交
180

a303176530's avatar
a303176530 已提交
181
# 执行
182
go get -g -v github.com/swaggo/swag/cmd/swag
a303176530's avatar
a303176530 已提交
183

a303176530's avatar
a303176530 已提交
184
# 到GOPATH的/src/github.com/swaggo/swag/cmd/swag路径下执行
185
go install
a303176530's avatar
a303176530 已提交
186
```
a303176530's avatar
a303176530 已提交
187

a303176530's avatar
a303176530 已提交
188
#### 2.3.2 生成API文档
a303176530's avatar
a303176530 已提交
189

190 191 192 193
````
cd server
swag init
````
a303176530's avatar
a303176530 已提交
194
执行上面的命令后,server目录下会出现docs文件夹,登录http://localhost:8888/swagger/index.html,即可查看swagger文档
a303176530's avatar
a303176530 已提交
195 196


a303176530's avatar
a303176530 已提交
197
## 3. 技术选型
a303176530's avatar
a303176530 已提交
198

a303176530's avatar
a303176530 已提交
199 200 201 202 203 204 205
- 前端:用基于`vue``Element-UI`构建基础页面。
- 后端:用`Gin`快速搭建基础restful风格API,`Gin`是一个go语言编写的Web框架。
- 数据库:采用`MySql`(5.6.44)版本,使用`gorm`实现对数据库的基本操作,已添加对sqlite数据库的支持。
- 缓存:使用`Redis`实现记录当前活跃用户的`jwt`令牌并实现多点登录限制。
- API文档:使用`Swagger`构建自动化文档。
- 配置文件:使用`fsnotify``viper`实现`yaml`格式的配置文件。
- 日志:使用`go-logging`实现日志记录。
S
sun_song_1203 已提交
206

R
rainyan 已提交
207

a303176530's avatar
a303176530 已提交
208 209
## 4. 项目架构
### 4.1 系统架构图
S
sun_song_1203 已提交
210

a303176530's avatar
a303176530 已提交
211
![系统架构图](http://qmplusimg.henrongyi.top/gva/gin-vue-admin.png)
a303176530's avatar
a303176530 已提交
212

a303176530's avatar
a303176530 已提交
213
### 4.2 前端详细设计图 (提供者:<a href="https://github.com/baobeisuper">baobeisuper</a>)
a303176530's avatar
a303176530 已提交
214

a303176530's avatar
a303176530 已提交
215
![前端详细设计图](http://qmplusimg.henrongyi.top/naotu.png)
a303176530's avatar
a303176530 已提交
216

a303176530's avatar
a303176530 已提交
217
### 4.3 目录结构
a303176530's avatar
a303176530 已提交
218

219
```
a303176530's avatar
a303176530 已提交
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
    ├─server  	     (后端文件夹)
    │  ├─api            (API)
    │  ├─config         (配置包)
    │  ├─core  	        (內核)
    │  ├─db             (数据库脚本)
    │  ├─docs  	        (swagger文档目录)
    │  ├─global         (全局对象)
    │  ├─initialiaze    (初始化)
    │  ├─middleware     (中间件)
    │  ├─model          (结构体层)
    │  ├─resource       (资源)
    │  ├─router         (路由)
    │  ├─service         (服务)
    │  └─utils	        (公共功能)
    └─web            (前端文件)
        ├─public        (发布模板)
        └─src           (源码包)
            ├─api       (向后台发送ajax的封装层)
            ├─assets	(静态文件)
            ├─components(组件)
            ├─router	(前端路由)
            ├─store     (vuex 状态管理仓)
            ├─style     (通用样式文件)
            ├─utils     (前端工具库)
            └─view      (前端页面)
a303176530's avatar
a303176530 已提交
245

246
```
a303176530's avatar
a303176530 已提交
247

a303176530's avatar
a303176530 已提交
248 249 250 251 252 253 254 255 256 257 258 259 260
## 5. 主要功能

- 权限管理:基于`jwt``casbin`实现的权限管理 
- 文件上传下载:实现基于七牛云的文件上传操作(为了方便大家测试,我公开了自己的七牛测试号的各种重要token,恳请大家不要乱传东西)
- 分页封装:前端使用mixins封装分页,分页方法调用mixins即可 
- 用户管理:系统管理员分配用户角色和角色权限。
- 角色管理:创建权限控制的主要对象,可以给角色分配不同api权限和菜单权限。
- 菜单管理:实现用户动态菜单配置,实现不同角色不同菜单。
- api管理:不同用户可调用的api接口的权限不同。
- 配置管理:配置文件可前台修改(测试环境不开放此功能)。
- 富文本编辑器:MarkDown编辑器功能嵌入。
- 条件搜索:增加条件搜索示例。
- restful示例:可以参考用户管理模块中的示例API。 
261
```
a303176530's avatar
a303176530 已提交
262 263
前端文件参考: src\view\superAdmin\api\api.vue 
后台文件参考: model\dnModel\api.go 
264
```
a303176530's avatar
a303176530 已提交
265 266 267 268
- 多点登录限制:需要在`config.yaml`中把`system`中的`useMultipoint`修改为true(需要自行配置Redis和Config中的Redis参数,测试阶段,有bug请及时反馈)。
- 分片长传:提供文件分片上传和大文件分片上传功能示例。
- 表单生成器:表单生成器借助 [@form-generator](https://github.com/JakHuang/form-generator)
- 代码生成器:后台基础逻辑以及简单curd的代码生成器。 
a303176530's avatar
a303176530 已提交
269

a303176530's avatar
a303176530 已提交
270
## 6. 计划任务
a303176530's avatar
a303176530 已提交
271

a303176530's avatar
a303176530 已提交
272 273 274 275
- [ ] 导入,导出Excel
- [ ] Echart图表支持
- [ ] 工作流,任务交接功能开发
- [ ] 单独前端使用模式以及数据模拟
a303176530's avatar
a303176530 已提交
276

a303176530's avatar
a303176530 已提交
277 278
## 7. 知识库 
## 7.1 团队博客
a303176530's avatar
a303176530 已提交
279

R
rainyan 已提交
280
> https://www.yuque.com/flipped-aurora
281
>
a303176530's avatar
a303176530 已提交
282
>内有前端框架教学视频。如果觉得项目对您有所帮助可以添加我的个人微信:shouzi_1994,欢迎您提出宝贵的需求。
a303176530's avatar
a303176530 已提交
283

a303176530's avatar
a303176530 已提交
284
## 7.2 教学视频
a303176530's avatar
a303176530 已提交
285

a303176530's avatar
a303176530 已提交
286 287
(1)环境搭建
> Bilibili:https://www.bilibili.com/video/BV1Fg4y187Bw/ (v1.0版本视频,v2.0操作相同目录不同)
288

a303176530's avatar
a303176530 已提交
289 290
(2)模板使用
> Bilibili:https://www.bilibili.com/video/BV16K4y1r7BD/ (v1.0版本视频,v2.0操作相同目录不同)
a303176530's avatar
a303176530 已提交
291

a303176530's avatar
a303176530 已提交
292
(3)2.0目录以及开发体验
a303176530's avatar
a303176530 已提交
293 294
> Bilibili:https://www.bilibili.com/video/BV1aV411d7Gm#reply2831798461

a303176530's avatar
a303176530 已提交
295
(4)golang基础教学视频录制中...
R
rainyan 已提交
296
> https://space.bilibili.com/322210472/channel/detail?cid=108884
a303176530's avatar
a303176530 已提交
297

a303176530's avatar
a303176530 已提交
298
## 8. 联系方式
a303176530's avatar
a303176530 已提交
299

a303176530's avatar
a303176530 已提交
300
### 8.1 技术群
301

a303176530's avatar
a303176530 已提交
302 303
### QQ交流群:622360840
| QQ 群(满) |
304
|  :---:  |
a303176530's avatar
a303176530 已提交
305
| <img src="http://qmplusimg.henrongyi.top/qq.jpg" width="180"/> |
R
rainyan 已提交
306

a303176530's avatar
a303176530 已提交
307 308
### 微信交流群
可以添加上面任意一位开发者,备注"加入gin-vue-admin交流群"
309

a303176530's avatar
a303176530 已提交
310 311
### 8.2 项目组成员
| 蒋 | 严 | 尹 | 杜 | 印 | 宋 |
312
|  :---:  |  :---: | :---: | :---:  |  :---: | :---: |
R
rainyan 已提交
313
| <img width="150" src="http://qmplusimg.henrongyi.top/qrjjz.png"> | <img width="150" src="http://qmplusimg.henrongyi.top/qryr.png"> | <img width="150" src="http://qmplusimg.henrongyi.top/qryx.png"> | <img width="150" src="http://qmplusimg.henrongyi.top/qrdjl.png"> | <img width="150" src="http://qmplusimg.henrongyi.top/qrygl.png"> | <img width="150" src="http://qmplusimg.henrongyi.top/qrsong.png"> |
a303176530's avatar
a303176530 已提交
314

a303176530's avatar
a303176530 已提交
315
|  昵称   | 项目职务  | 姓  |
316
|  ----  | ----  | ----  |
a303176530's avatar
a303176530 已提交
317 318 319 320 321 322 323
| [@piexlmax](https://github.com/piexlmax)  | 项目发起者 | 蒋 |
| [@Ruio9244](https://github.com/Ruio9244)  | 架构师 | 严 |
| [@granty1](https://github.com/granty1)  | 后台开发 | 印 |
| [@1319612909](https://github.com/1319612909)  | 前端UI开发 |  杜 |
| [@krank666](https://github.com/krank666)  | 前端开发 | 尹 |
| [@chen-chen-up](https://github.com/chen-chen-up)  | 新手开发 | 宋 |
| [@SliverHorn](https://github.com/SliverHorn)  | 社区管理员 | 赖 |
a303176530's avatar
a303176530 已提交
324

a303176530's avatar
a303176530 已提交
325
## 9. 捐赠
a303176530's avatar
a303176530 已提交
326

a303176530's avatar
a303176530 已提交
327
如果你觉得这个项目对你有帮助,你可以请作者喝饮料 :tropical_drink: [点我](https://www.gin-vue-admin.com/docs/coffee)
a303176530's avatar
a303176530 已提交
328

a303176530's avatar
a303176530 已提交
329
## 10. 商用注意事项
a303176530's avatar
a303176530 已提交
330

a303176530's avatar
a303176530 已提交
331
如果您将此项目用于商业用途,请遵守Apache2.0协议并保留作者技术支持声明。