# hsh-admin-server

**Repository Path**: hedgelion/hsh-admin-server

## Basic Information

- **Project Name**: hsh-admin-server
- **Description**: HSH Admin Server 是一个基于 Gin + GORM 的现代化后台管理系统框架，采用 Go 语言开发。项目提供完整的用户、角色、权限、菜单、字典、部门、系统配置、文件存储、代码生成、定时任务等核心功能模块，支持6种云存储类型，集成了 JWT 认证、Casbin 权限控制、Redis 缓存、系统监控等特性。开箱即用，代码结构清晰，是快速搭建企业级后台管理系统的理想选择。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HSH Admin Server

基于 Gin + GORM 的后台管理系统服务端

> 📢 **已完成功能完全开源使用**，欢迎免费使用和修改！

## 🚀 在线体验

- **演示地址**：https://admin.golazy.cn/login
- **演示账号**：admin
- **演示密码**：admin123

## 📦 代码仓库

- **后端代码**：https://gitee.com/techshino/hsh-admin-server
- **前端代码**：https://gitee.com/techshino/hsh-admin-web

## 📚 文档导航

这是一个完整的后台管理系统框架，包含以下文档：

- **[总文档（当前）](./README.md)** - 项目总览、快速开始、部署指南
- **[API文档](./API_DOCUMENTATION.md)** - 详细的API接口文档（前端对接必读）
- **[开发手册](./DEVELOPMENT.md)** - 完整的开发指南（后端开发必读）
- **[数据权限文档](./DATA_PERMISSION.md)** - 数据权限功能使用指南（权限管理必读）

### 快速导航

- [快速开始](#快速开始) - 5分钟快速上手
- [功能特性](#功能特性) - 完整功能列表
- [技术栈](#技术栈) - 使用的技术
- [打包部署](#打包部署) - 生产环境部署
- [贡献指南](./DEVELOPMENT.md#贡献指南) - 参与项目

## 功能特性

### ✅ 已完成功能

- ✅ 用户管理：完整的用户CRUD操作，支持密码加密和重置
- ✅ 角色管理：角色的增删改查，支持权限分配
- ✅ 权限管理：基于 Casbin 的权限控制，支持按钮级别的权限
- ✅ 菜单管理：支持目录、功能菜单和按钮级别的树形结构
- ✅ 字典管理：字典类型和字典数据管理，支持Redis缓存
- ✅ 部门管理：部门的增删改查，支持树形结构
- ✅ 系统配置：系统配置管理，支持缓存和实时刷新
- ✅ **文件存储**：完整的文件存储和管理系统，支持本地存储和云存储
  - 支持6种固定存储类型：本地、阿里云OSS、腾讯云COS、百度云BOS、七牛云Kodo、MinIO
  - 支持公有/私有访问模式
  - 私有模式可生成临时授权URL
  - 完整的文件上传记录管理
  - 文件自动按日期分目录存储
  - 自动计算MD5哈希值
- ✅ 代码生成器：自动生成后端（Model、Mapper、Service、API、Router）和前端代码
- ✅ 雪花ID：使用雪花算法生成唯一ID，支持字符串形式
- ✅ 统一响应：封装了统一的API返回格式
- ✅ 自定义时间类型：支持yyyy-MM-dd、yyyy-MM-dd HH:mm:ss和时间戳三种格式
- ✅ 日志系统：完善的日志记录，支持按级别分文件、按日期和大小切割
- ✅ JWT认证：基于JWT的身份认证机制，支持用户信息缓存
- ✅ 验证码：支持图片验证码，可配置类型（字符/数学）
- ✅ 水印功能：系统配置支持开启页面水印
- ✅ 统一错误处理：完整的错误处理机制和错误码管理
- ✅ 数据库事务：支持便捷的事务操作
- ✅ 参数验证：请求参数验证中间件
- ✅ XSS防护：全局XSS防护中间件
- ✅ 健康检查：系统健康检查接口
- ✅ 服务监控：系统运行监控，包含HTTP、数据库、Redis、缓存统计
- ✅ 服务器监控：跨平台（Windows/Linux/macOS）的服务器实时监控
- ✅ 定时任务：基于 robfig/cron 的定时任务管理，支持Cron表达式配置、手动执行、任务日志记录
- ✅ Prometheus集成：支持Prometheus监控指标采集
- ✅ 优雅关闭：支持优雅关机，确保资源正确释放
- ✅ 连接池优化：数据库和Redis连接池配置优化
- ✅ 演示模式：支持演示模式配置，演示模式下禁止关键数据的增删改操作
- ✅ **数据权限**：基于角色的数据权限控制，支持5种权限范围
  - 全部数据：可以查看所有数据
  - 自定义数据：可以查看指定部门的数据
  - 本部门数据：只能查看本部门的数据
  - 本部门及以下数据：可以查看本部门及子部门的数据
  - 仅本人：只能查看自己的数据
  - 支持部门树结构，递归查询子部门
  - 提供通用的 ApplyDataPermission 函数，可在任何模块中使用

### 🚧 开发中

- 🔄 工作流
- 🔄 多租户
- 🔄 增量更新
- 🔄 导入导出Excel统一封装
- 🔄 多数据库支持

## 技术栈

- **Web框架**: Gin
- **ORM**: GORM
- **数据库**: MySQL
- **缓存**: Redis
- **权限控制**: Casbin
- **身份认证**: JWT
- **日志**: Zap
- **定时任务**: robfig/cron
- **云存储**: AWS SDK for Go (支持 S3 协议兼容存储)

## 快速开始

### 环境要求

- Go 1.21+
- MySQL 5.7+
- Redis 5.0+

### 安装依赖

```bash
go mod download
```

### 配置文件

复制 `config.yaml.example` 为 `config.yaml` 并修改配置：

```bash
cp config.yaml.example config.yaml
```

配置说明：
- `server.port`: 服务端口
- `database.host`: 数据库主机
- `database.port`: 数据库端口
- `database.user`: 数据库用户名
- `database.password`: 数据库密码
- `database.dbName`: 数据库名称
- `jwt.secret`: JWT密钥
- `jwt.expireHours`: JWT过期时间（小时）
- `jwt.refreshHours`: JWT刷新时间（小时）
- `redis.host`: Redis主机
- `redis.port`: Redis端口
- `redis.password`: Redis密码
- `redis.db`: Redis数据库
- `snowflake.workerId`: 雪花ID工作节点ID
- `snowflake.datacenterId`: 雪花ID数据中心ID
- `app.demoEnabled`: 演示模式（true/false），演示模式下禁止关键数据的增删改操作

### 数据库迁移

首次运行会自动创建数据库表结构。

### 启动服务

```bash
go run main.go
```

或使用启动脚本：

```bash
chmod +x start.sh
./start.sh
```

## 项目结构

```
hsh-admin-server/
├── app/                 # 应用代码
│   ├── casbin/         # Casbin配置
│   ├── mapper/         # 数据访问层（公共）
│   │   ├── system_user.go    # 系统模块-用户Mapper
│   │   ├── system_role.go    # 系统模块-角色Mapper
│   │   ├── system_dept.go    # 系统模块-部门Mapper
│   │   ├── system_menu.go    # 系统模块-菜单Mapper
│   │   ├── system_dict.go    # 系统模块-字典Mapper
│   │   ├── system_config.go  # 系统模块-配置Mapper
│   │   ├── system_permission.go # 系统模块-权限Mapper
│   │   ├── tool_gen.go       # 工具模块-代码生成Mapper
│   │   ├── tool_job.go       # 工具模块-定时任务Mapper
│   │   └── tool_job_log.go   # 工具模块-任务日志Mapper
│   ├── middleware/     # 中间件
│   ├── models/         # 数据模型（公共）
│   │   ├── time.go            # 公共时间类型
│   │   ├── system_user.go     # 系统模块-用户模型
│   │   ├── system_role.go     # 系统模块-角色模型
│   │   ├── system_dept.go     # 系统模块-部门模型
│   │   ├── system_menu.go     # 系统模块-菜单模型
│   │   ├── system_dict.go     # 系统模块-字典模型
│   │   ├── system_config.go   # 系统模块-配置模型
│   │   ├── system_oss_config.go # 系统模块-存储配置模型
│   │   ├── system_oss_file.go # 系统模块-文件记录模型
│   │   ├── system_permission.go # 系统模块-权限模型
│   │   ├── tool_gen.go        # 工具模块-代码生成模型
│   │   ├── tool_job.go        # 工具模块-定时任务模型
│   │   └── tool_job_log.go    # 工具模块-任务日志模型
│   ├── modules/        # 业务模块（按功能分包）
│   │   ├── auth/       # 认证模块
│   │   ├── monitor/    # 监控模块
│   │   ├── system/     # 系统管理
│   │   │   ├── config/ # 系统配置
│   │   │   ├── dept/   # 部门管理
│   │   │   ├── dict/   # 字典管理
│   │   │   ├── menu/   # 菜单管理
│   │   │   ├── oss_config/ # 存储配置管理
│   │   │   ├── oss_file/ # 文件管理
│   │   │   ├── permission/ # 权限管理
│   │   │   ├── role/   # 角色管理
│   │   │   └── user/   # 用户管理
│   │   └── tool/       # 系统工具
│   │       ├── gen/    # 代码生成
│   │       └── job/    # 定时任务
│   ├── storage/        # 存储模块
│   │   ├── storage.go # 统一存储接口
│   │   ├── local.go   # 本地存储实现
│   │   ├── s3.go      # S3协议云存储实现
│   │   └── manager.go # 存储管理器
│   └── utils/          # 工具类
├── configs/             # 配置文件
│   └── casbin/         # Casbin模型配置
├── database/           # 数据库相关
├── routes/             # 路由配置
│   └── modules/       # 路由模块
│       ├── oss_config.go # 存储配置路由
│       └── oss_file.go # 文件管理路由
├── templates/          # 代码生成模板
│   └── gen/            # 代码生成器模板
├── config.yaml         # 配置文件
├── config.yaml.example # 配置文件示例
├── API_DOCUMENTATION.md # API接口文档
├── go.mod              # Go模块文件
├── go.sum              # 依赖锁定文件
├── main.go             # 主程序入口
└── start.sh            # 启动脚本
```

### 架构说明
- **按功能分包（Package by Feature）**：业务模块按功能组织到 `app/modules/` 下
- **公共层**：`models/` 和 `mapper/` 作为公共底层，供所有模块引用
- **命名规范**：models/mapper 文件使用 `模块名_业务名.go` 前缀命名，便于查找
- **单例模式**：所有 Service 使用 sync.Once 实现单例

## 打包部署

### 编译打包

编译不同平台的可执行文件：

**Linux/AMD64:**
```bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o hsh-admin-server main.go
```

**Windows/AMD64:**
```bash
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o hsh-admin-server.exe main.go
```

**macOS/AMD64:**
```bash
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o hsh-admin-server main.go
```

**macOS/ARM64 (Apple Silicon):**
```bash
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o hsh-admin-server main.go
```

### 部署文件结构

打包后需要将以下文件放到同一目录：

```
部署目录/
├── hsh-admin-server      # 可执行文件
├── config.yaml           # 配置文件
├── start.sh              # 启动脚本（可选）
├── configs/               # 配置目录
│   └── casbin/
│       └── model.conf    # Casbin模型配置
└── templates/            # 代码生成模板目录（可选，使用代码生成功能需要）
    └── gen/
        ├── api.go.tpl
        ├── mapper.go.tpl
        ├── service.go.tpl
        ├── model.go.tpl
        ├── router.go.tpl
        ├── menu.sql.tpl
        └── vue/
            ├── api.ts.tpl
            ├── types.ts.tpl
            ├── index.vue.tpl
            └── form.vue.tpl
```

### 必需部署文件

| 文件/目录 | 说明 | 是否必需 |
|-----------|------|---------|
| `hsh-admin-server` | 可执行文件 | ✅ 必需 |
| `config.yaml` | 配置文件 | ✅ 必需 |
| `configs/casbin/model.conf` | Casbin模型配置 | ✅ 必需 |
| `templates/` | 代码生成模板 | ⚠️ 可选（使用代码生成功能需要） |
| `start.sh` | 启动脚本 | ⚠️ 可选 |

### 部署步骤

1. **创建部署目录**
```bash
mkdir -p /opt/hsh-admin
cd /opt/hsh-admin
```

2. **上传文件**
将编译好的可执行文件和配置文件上传到部署目录

3. **配置文件**
```bash
# 复制配置示例
cp config.yaml.example config.yaml

# 修改配置
vim config.yaml
```

4. **设置权限**
```bash
chmod +x hsh-admin-server
chmod +x start.sh  # 如果使用启动脚本
```

5. **启动服务**
```bash
# 直接启动
./hsh-admin-server

# 或使用启动脚本
./start.sh
```

6. **后台运行（可选）**
```bash
# 使用nohup
nohup ./hsh-admin-server > app.log 2>&1 &

# 或使用systemd（推荐生产环境）
```

### Systemd 服务配置（推荐）

创建 `/etc/systemd/system/hsh-admin.service`：

```ini
[Unit]
Description=HSH Admin Server
After=network.target mysql.service redis.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/hsh-admin
ExecStart=/opt/hsh-admin/hsh-admin-server
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

使用systemd管理：
```bash
# 重载配置
systemctl daemon-reload

# 启动服务
systemctl start hsh-admin

# 设置开机自启
systemctl enable hsh-admin

# 查看状态
systemctl status hsh-admin

# 查看日志
journalctl -u hsh-admin -f
```

### Docker 部署

创建 `Dockerfile`：

```dockerfile
FROM alpine:latest

WORKDIR /app

# 安装必要的依赖
RUN apk --no-cache add ca-certificates tzdata

# 复制文件
COPY hsh-admin-server .
COPY config.yaml .
COPY configs/casbin/model.conf ./configs/casbin/

# 设置时区
ENV TZ=Asia/Shanghai

EXPOSE 8080

CMD ["./hsh-admin-server"]
```

构建和运行：
```bash
# 构建镜像
docker build -t hsh-admin-server .

# 运行容器
docker run -d \
  --name hsh-admin \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  hsh-admin-server
```

## API文档

> 📖 **API文档**：详细的接口文档请参考 [API_DOCUMENTATION.md](./API_DOCUMENTATION.md)，包含：
> - 完整的接口列表
> - 请求/响应示例
> - 权限说明
> - 错误码说明

## 主要功能模块

### 1. 认证模块
- 用户注册
- 用户登录
- 刷新Token

### 2. 用户管理
- 用户列表查询（带分页和条件）
- 获取用户详情
- 创建用户
- 更新用户
- 删除用户
- 修改密码
- 重置密码

### 3. 角色管理
- 角色列表查询
- 获取角色详情
- 创建角色
- 更新角色
- 删除角色
- 分配权限

### 4. 权限管理
- 权限列表查询
- 获取权限详情
- 创建权限
- 更新权限
- 删除权限

### 5. 数据权限管理
- 角色数据权限配置：支持5种权限范围
- 数据权限应用：在查询数据时自动应用权限过滤
- 部门树支持：递归查询子部门数据
- 通用权限函数：`ApplyDataPermission` 可在任何模块中使用

详细使用方法请参考 [数据权限文档](./DATA_PERMISSION.md)

### 6. 菜单管理
- 菜单列表查询
- 获取菜单详情
- 创建菜单
- 更新菜单
- 删除菜单
- 获取菜单树（带条件查询）

### 7. 字典管理
- 字典类型列表查询
- 获取字典类型详情
- 创建字典类型
- 更新字典类型
- 删除字典类型
- 字典数据列表查询
- 获取字典数据详情
- 创建字典数据
- 更新字典数据
- 删除字典数据
- 刷新字典缓存

### 8. 存储配置管理
- 获取支持的存储类型列表
- 存储配置列表查询
- 获取激活的存储配置
- 创建存储配置
- 更新存储配置
- 删除存储配置
- 激活存储配置
- 获取文件访问URL
- 获取临时授权URL

### 9. 文件管理
- 文件上传
- 文件列表查询（带分页和搜索）
- 获取文件详情
- 删除文件

### 10. 定时任务管理
- 定时任务列表查询（带分页和条件）
- 获取任务详情
- 创建任务
- 更新任务
- 删除任务
- 手动执行任务
- 任务执行日志查询
- 任务日志删除和清空

## 工具类说明

### 雪花ID生成器
```go
// 生成uint64类型的雪花ID
id := utils.GenerateID()

// 生成string类型的雪花ID
strID := utils.GenerateStringID()
```

### 密码工具
```go
// 加密密码
hashedPassword, err := utils.HashPassword("password123")

// 验证密码
valid := utils.CheckPasswordHash("password123", hashedPassword)

// 生成随机密码
randomPassword := utils.GenerateRandomPassword(12)
```

### 统一响应工具
```go
// 成功响应
utils.Success(c, data)

// 成功响应（带自定义消息）
utils.Success(c, data, "操作成功")

// 失败响应
utils.BadRequest(c, "参数错误")

// 使用统一错误处理
if utils.HandleError(c, err) {
    return
}
```

### Redis工具
```go
// 设置缓存
err := utils.Set("key", "value", 3600 * time.Second)

// 获取缓存
var value string
err := utils.Get("key", &value)

// 删除缓存
err := utils.Delete("key")

// 按模式删除
err := utils.DeleteByPattern("user:*")
```

### 统一错误处理
```go
// 创建业务错误
err := utils.NewUserNotFoundError()
err := utils.NewBadRequestError("参数无效")
err := utils.NewInternalServerError("操作失败", originalErr)

// 检查错误类型
if appErr, ok := utils.IsAppError(err); ok {
    // 处理应用错误
}

// API层处理
utils.RespondError(c, err)
```

### 数据库事务
```go
// 执行事务（推荐）
err := utils.Transaction(func(tx *gorm.DB) error {
    // 在事务中执行操作
    if err := tx.Create(&obj1).Error; err != nil {
        return err
    }
    if err := tx.Create(&obj2).Error; err != nil {
        return err
    }
    return nil
})

// 手动管理事务
tx, err := utils.BeginTransaction()
defer func() {
    if r := recover(); r != nil {
        utils.RollbackTransaction(tx)
    }
}()
// ... 操作 ...
if err != nil {
    utils.RollbackTransaction(tx)
    return err
}
utils.CommitTransaction(tx)
```

### XSS防护
```go
// 清理输入（推荐）
clean := utils.SanitizeInput(input)

// HTML转义
escaped := utils.EscapeHTML(input)

// 移除XSS代码
stripped := utils.StripXSS(input)

// 检测XSS
if utils.IsXSSDetected(input) {
    // 处理危险输入
}
```

## 开发规范

### 命名规范
- 数据库字段使用下划线命名
- JSON序列化使用驼峰命名
- 路由路径使用驼峰命名
- 包名、文件名使用小写

### Git提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 重构
- test: 测试相关
- chore: 构建/工具相关

## 许可证

本项目采用 [MIT License](./LICENSE) 许可。

### MIT License

Copyright (c) 2024 HSH Admin Server

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.