# jzgadmin

**Repository Path**: xy_qcdz/jzgadmin

## Basic Information

- **Project Name**: jzgadmin
- **Description**: go-vue后台管理系统
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jzgadmin 后台管理系统

Go + Vue3 前后端分离的通用后台管理系统。开箱即用，内置 RBAC 权限、审计日志、数据字典、数据库备份与通用导入导出基础设施，并已完成一轮安全与稳定性加固。

- 仓库地址：https://gitee.com/xy_qcdz/jzgadmin.git（master 分支）
---

## 一、技术栈

| 层次 | 技术选型 |
| --- | --- |
| 后端语言 | Go 1.25 |
| Web 框架 | Gin 1.9 |
| ORM / 数据库 | GORM 1.25 + PostgreSQL（pgx/v5 驱动） |
| 认证 | JWT（golang-jwt/v5） |
| Excel 处理 | excelize/v2 |
| 日志 | zap + lumberjack 滚动切割 |
| 前端框架 | Vue 3.3 + Vite 5 |
| UI 组件 | Element Plus 2.4（按需自动导入） |
| 状态 / 路由 | Pinia 2.1 + Vue Router 4.2 |
| 图表 | ECharts 6.1 |
| HTTP 客户端 | Axios 1.6 |

## 二、功能模块

| 模块 | 路由 | 主要能力 |
| --- | --- | --- |
| 首页 | `/dashboard` | 数据概览卡片与图表 |
| 个人中心 | `/profile` | 查看/编辑个人资料、修改密码 |
| 用户管理 | `/user` | 增删改查、分配角色与部门、启用/禁用、导入导出 |
| 角色管理 | `/role` | 角色维护、权限点勾选授权、导入导出 |
| 部门管理 | `/department` | 树形部门维护、导入导出 |
| 菜单管理 | `/menu` | 动态菜单与路由配置、导入导出 |
| 数据字典 | `/dict` | 字典类型 + 字典数据两级维护、导入导出 |
| 系统配置 | `/config` | 按分组维护系统参数（bool/number/json/string 类型及格式校验） |
| 数据备份 | `/backup` | 基于 `pg_dump` 一键备份、备份文件列表与删除 |
| 审计日志 | `/audit` | 操作留痕（操作人、模块、动作、IP、耗时、结果），支持导出 |

菜单结构：`首页`、`个人中心` 为一级菜单；`用户/角色/部门/菜单/数据字典/系统配置/数据备份/审计日志` 统一收拢在 `系统设置` 二级菜单下。

## 三、目录结构

```
jzgadmin-v1.1/
├── server/                 # Go 后端
│   ├── main.go             # 启动入口：日志 → 配置 → DB 连接池 → 迁移 → 种子数据 → 路由
│   ├── config/             # 环境变量加载、DB 初始化
│   ├── model/              # 数据模型、AutoMigrate、默认角色/用户/菜单/配置种子
│   ├── router/             # 路由注册（全部 API 集中在 router.go）
│   ├── handler/            # 请求处理层
│   ├── service/            # 业务逻辑层（含导入导出实现）
│   ├── middleware/         # JWT / 权限 / 审计 / 限流 / CORS / 数据权限 / Recovery
│   ├── pkg/                # 工具包（Excel 解析、密码策略、响应封装等）
│   ├── logger/             # zap 日志与 gin 日志中间件
│   ├── backup/             # 备份服务
│   └── .env.example        # 环境变量模板
└── web/                    # Vue3 前端
    ├── src/api/            # 接口封装（含 importExport.js）
    ├── src/components/     # 通用组件（含 ImportExport.vue）
    ├── src/views/          # 页面（user/role/menu/dict/config/department/audit/backup/dashboard/profile）
    ├── src/store/          # Pinia 状态（用户、权限、菜单）
    ├── src/router/         # 前端路由与守卫
    └── vite.config.mjs     # 开发代理与打包分包配置
```

## 四、安全与稳定性设计

| 项目 | 说明 |
| --- | --- |
| 鉴权 | JWT 令牌，每次请求校验用户状态与 `token_version`，改密后旧令牌立即失效 |
| 暴力破解防护 | 登录接口独立限流 5 qps / 突发 10；连续 5 次失败锁定账号 10 分钟 |
| 接口限流 | 全局 100 qps / 突发 200 |
| 跨域 | CORS 白名单制，默认拒绝所有来源，仅放行 `CORS_ORIGIN` 配置 |
| 可信代理 | `TRUSTED_PROXIES` 白名单，反代场景下才能取到真实源 IP |
| 生产校验 | `APP_ENV=production` 时强制校验 `DB_PASSWORD`、`JWT_SECRET` 非默认值，否则拒绝启动 |
| 上传安全 | 512 字节魔数校验，防止伪造扩展名上传 |
| 文件导入 | 单次上限 2000 行，超限返回截断标记并在前端提示 |
| 错误处理 | 统一错误码与响应结构，全局 Recovery 兜底 panic |
| 可观测 | 请求 ID 贯穿日志、安全响应头、结构化 zap 日志、`/health` 健康检查（含 DB 连通性探测） |
| 数据权限 | 中间件按部门维度收口数据可见范围 |

## 五、环境要求

| 依赖 | 版本要求 |
| --- | --- |
| Go | 1.25 及以上 |
| Node.js | 18 及以上（Vite 5 要求） |
| PostgreSQL | 12 及以上（示例配置基于 17） |
| pg_dump | 与 PostgreSQL 同版本，用于备份功能 |

## 六、快速开始

### 1. 准备数据库

```sql
CREATE DATABASE jzgadmin;
```

### 2. 启动后端

```powershell
cd D:\python\jzgadmin-v1.1\server
Copy-Item .env.example .env      # 首次运行，按需修改数据库账号密码
go mod download
go run main.go
```

服务监听 `http://localhost:8080`，首次启动会自动建表并写入默认角色、管理员账号、菜单与系统配置。

### 3. 启动前端

```powershell
cd D:\python\jzgadmin-v1.1\web
npm install
npm run dev
```

浏览器访问 `http://localhost:5173`。开发服务器已配置代理：`/api` 与 `/uploads` 均转发至 `http://localhost:8080`，无需额外处理跨域。

### 4. 默认账号

| 项 | 值 |
| --- | --- |
| 用户名 | `admin` |
| 密码 | `admin123` |
| 内置角色 | 管理员（`admin`，全部权限）、编辑者（`editor`） |

首次登录后请立即在「个人中心」修改密码。

## 七、环境变量说明

配置文件为 `server/.env`，模板见 `server/.env.example`。

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `DB_HOST` / `DB_PORT` | `localhost` / `5432` | 数据库地址与端口 |
| `DB_USER` / `DB_PASSWORD` | `postgres` / 需自行填写 | 数据库账号密码 |
| `DB_NAME` | `jzgadmin` | 数据库名 |
| `DB_SSLMODE` | `disable` | SSL 模式 |
| `PG_DUMP_PATH` | `C:/Program Files/PostgreSQL/17/bin/pg_dump.exe` | 备份工具绝对路径 |
| `BACKUP_DIR` | `<server>/backups` | 备份存放目录，不设置按源码路径推导 |
| `JWT_SECRET` | `change-me-...` | 生产环境必须替换为 32 位以上随机串 |
| `APP_ENV` | 空（开发模式） | 设为 `production` 开启默认凭证强校验 |
| `SERVER_PORT` | `8080` | 后端监听端口 |
| `TRUSTED_PROXIES` | 空（仅信本机回环） | 反代 IP/CIDR 白名单，逗号分隔 |
| `CORS_ORIGIN` | `http://localhost:5173` | 跨域放行来源，多个用逗号分隔 |
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
| `PASSWORD_MIN_LENGTH` | `6` | 密码最小长度 |
| `PASSWORD_REQUIRE_DIGIT` | `true` | 是否必须含数字 |
| `PASSWORD_REQUIRE_UPPER` | `false` | 是否必须含大写字母 |
| `PASSWORD_REQUIRE_SPECIAL` | `false` | 是否必须含特殊字符 |

## 八、生产部署

1. 构建前端静态资源：

```powershell
cd D:\python\jzgadmin-v1.1\web
npm run build        # 产物位于 web/dist
```

2. 构建后端可执行文件：

```powershell
cd D:\python\jzgadmin-v1.1\server
go build -o jzgadmin.exe .
```

3. 配置环境变量：`APP_ENV=production`、随机 `JWT_SECRET`、正式 `CORS_ORIGIN`（前端域名）、反代场景填 `TRUSTED_PROXIES`。
4. 使用 Nginx 托管 `web/dist`，并将 `/api`、`/uploads` 反向代理到后端 `8080` 端口。

> 提醒：仓库历史提交中可能残留早期 `node_modules`、日志、备份文件；`.gitignore` 已补全（忽略 `node_modules/dist/logs/backups/.env`，保留 `.env.example`）。如仓库保持公开，请确认历史中未包含真实数据库密码与 JWT 密钥。

## 九、功能使用说明

### 用户管理

新增用户需填写用户名、密码、角色、部门；支持启用/禁用、重置密码、编辑资料与删除。删除当前登录账号、删除内置管理员会被拒绝。

### 角色管理

角色绑定权限点，权限点按「用户管理 / 角色管理 / 部门管理 / 菜单管理 / 数据字典 / 系统配置 / 数据备份 / 审计日志 / 仪表盘 / 数据导入 / 数据导出」分组展示。角色分配给用户后即时生效（无需重新登录）。

### 菜单管理

维护菜单名称、路由路径、前端组件路径、图标、排序、上级菜单与绑定权限码；前端路由与侧边栏由后端菜单动态下发。

### 数据字典

先建字典类型（如 `user_status`），再在类型下维护字典数据项；前端下拉选项可统一读取字典，避免硬编码。

### 系统配置

按分组维护系统参数，支持 `bool`、`number`、`json`、`string` 四种类型，保存时进行类型与 JSON 格式校验。系统配置页不提供导入导出入口。

### 数据备份

点击「备份」调用 `pg_dump` 生成备份文件，列表可查看文件大小与生成时间。备份功能依赖 `PG_DUMP_PATH` 正确配置，备份目录需有写权限。

### 审计日志

所有需鉴权接口自动记录操作留痕，可按模块、操作人、时间范围筛选，支持导出为 Excel。

### 接口文档

系统内置离线接口文档，无需 Swagger 注解与生成步骤，由 `server/handler/docs.go` 的静态核心接口表 + 模块注册表（`module.All()`）动态拼装，新增业务模块只需注册元数据，其 CRUD 接口即自动出现在文档中。

| 入口 | 路径 | 说明 |
| --- | --- | --- |
| 浏览页 | `GET /api/docs` | HTML 表格页，按分组展示方法、路径、说明与权限码 |
| OpenAPI 描述 | `GET /api/docs/openapi.json` | OpenAPI 3.0 描述，可导入 Postman / Apifox / Stoplight 等工具 |

使用要点：

1. **访问方式**：需登录后携带 `Authorization: Bearer <token>` 访问，浏览器登录状态下直接打开 `/api/docs` 即可。
2. **权限控制**：文档接口挂载在 `docs:view` 权限下（`router.go` 中 `auth.Group("/docs", middleware.RequirePerm("docs:view"))`），避免任意登录用户遍历全部接口；默认管理员角色拥有该权限。
3. **认证说明**：`/api/docs/openapi.json` 中已声明 `bearerAuth` 安全方案，接口统一响应体为 `{code, msg, data}`，所需权限码见各接口 `x-permission` 字段。
4. **离线可用**：页面样式内联、无外部 CDN 依赖，断网环境亦可正常查看。

## 十、导入导出使用规范

导入导出为通用能力：后端统一路由 `GET /api/export/:module` 与 `POST /api/import/:module`，前端统一组件 `ImportExport.vue`（配合 `src/api/importExport.js`）。

| 模块 | 导出接口 | 导入接口 | 所需权限 |
| --- | --- | --- | --- |
| 用户 | `/export/users` | `/import/users` | `export:user` / `import:user` |
| 角色 | `/export/roles` | `/import/roles` | `export:role` / `import:role` |
| 部门 | `/export/departments` | `/import/departments` | `export:dept` / `import:dept` |
| 菜单 | `/export/menus` | `/import/menus` | `export:menu` / `import:menu` |
| 字典类型 | `/export/dict-types` | `/import/dict-types` | `export:dict` / `import:dict` |
| 字典数据 | `/export/dict-data` | `/import/dict-data` | `export:dict` / `import:dict` |
| 审计日志 | `/export/audit-logs` | 不提供 | `export:audit` |

使用要点：

1. **导入策略为「仅新增」**：以唯一键（如用户名、角色编码）判断，重复记录明确报错并跳过该行，不做覆盖更新。
2. **结果反馈**：逐行返回成功、失败数量与失败行号，导入完成后按提示核对失败行。
3. **事务保障**：导入整体在数据库事务内逐行执行，数据库级错误整体回滚；业务校验失败仅跳过该行。
4. **行数上限**：单次导入最多 2000 行，超限行会被截断并提示。
5. **模板来源**：请先导出一次，以导出文件为模板填写，避免列名与格式不匹配。
6. **操作人记录**：导入数据自动记录登录用户名到 `created_by` / `updated_by`，历史缺值显示为 `-`。
7. **导出校验**：前端下载后校验文件头魔数，确保拿到的是真实 xlsx 而非错误信息；导出超时按 120 秒处理。

## 十一、常见问题

| 现象 | 处理方式 |
| --- | --- |
| 后端启动报数据库连接失败 | 检查 `.env` 中 `DB_HOST`/`DB_PORT`/`DB_PASSWORD`，确认 PostgreSQL 服务已启动 |
| `APP_ENV=production` 下服务拒绝启动 | 说明仍在使用默认 `DB_PASSWORD` 或 `JWT_SECRET`，替换为真实强口令即可 |
| 前端页面 401 或反复跳登录 | JWT 过期或用户被禁用，重新登录；改密后旧令牌会自动失效 |
| 浏览器请求跨域被拦截 | 将前端访问地址（含端口）加入 `CORS_ORIGIN` |
| 备份失败 | 核对 `PG_DUMP_PATH` 路径、`BACKUP_DIR` 写权限及数据库连接参数 |
| 导入报「文件非法」 | 仅支持 `.xlsx` 格式，请从导出文件另存后填写 |
| 反代后审计日志 IP 都是代理地址 | 配置 `TRUSTED_PROXIES` 为代理服务器 IP/CIDR |