# 十一维管理后台接口（golang）

**Repository Path**: syf554332076/11wei-go-admin-react-api

## Basic Information

- **Project Name**: 十一维管理后台接口（golang）
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Admin API Service - 后台管理系统

[![Go Version](https://img.shields.io/badge/Go-1.20+-00ADD8?style=flat&logo=go)](https://golang.org)
[![Go-Zero](https://img.shields.io/badge/Go--Zero-v1.9.3-brightgreen?style=flat)](https://go-zero.dev)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-blue?style=flat&logo=postgresql)](https://www.postgresql.org)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于 Go-Zero 微服务框架构建的企业级后台管理系统 API 服务，提供完整的 RBAC 权限管理、内容管理和数据统计功能。

## ✨ 核心特性

### 🔐 权限管理系统
- **RBAC 权限模型**：管理员、角色、菜单三级权限体系
- **JWT 认证**：安全的 Token 认证机制，支持自定义过期时间
- **细粒度权限控制**：菜单级别的权限管理，精确控制用户访问
- **角色菜单绑定**：灵活的角色权限分配
- **超级管理员**：默认拥有全部权限的特殊角色

### 📊 内容管理模块
- **声景管理**：声景分类、声景内容（音频/视频）、首页展示配置
- **睡眠音频管理**：音频分类、音频内容、VIP 标记
- **心能课程管理**：课程分类、课程、章节三级管理
- **大师课程管理**：大师信息、课程、章节多级管理
- **小程序路由**：动态配置小程序页面路由

### 👥 用户管理系统
- **用户信息管理**：完整的用户资料管理
- **VIP 订单管理**：用户 VIP 订单查询和统计
- **用户行为记录**：浏览记录、收藏记录追踪
- **数据统计分析**：用户活跃度、转化率等指标

### 📈 数据统计大屏
- **用户数据**：总用户数、VIP 用户数、日活、月活
- **订单数据**：总收入、订单量、成交量、月度销售趋势
- **内容数据**：各类内容的数量统计
- **推荐排行**：推荐人排行榜（Top 10）

### ⚙️ 系统功能
- **系统配置**：支持 JSON 格式的动态配置管理
- **操作日志**：记录管理员的所有操作行为
- **登录日志**：登录历史和安全审计
- **密码工具**：bcrypt 加密的密码管理

## 🛠 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| **Go** | 1.20+ | 编程语言 |
| **Go-Zero** | v1.9.3 | 微服务框架 |
| **PostgreSQL** | 17 | 主数据库 |
| **JWT** | - | 身份认证 |
| **bcrypt** | - | 密码加密 |

## 🚀 快速开始

### 前置要求

- Go 1.20 或更高版本
- PostgreSQL 17 或兼容版本
- 建议使用 Git 进行版本管理

### 1. 克隆项目

```bash
git clone <repository-url>
cd admin-api-service-go
```

### 2. 安装依赖

```bash
go mod download
```

### 3. 配置数据库

修改 `etc/admin-api.yaml` 配置文件：

```yaml
Database:
  DataSource: "postgres://username:password@localhost:5432/dbname?sslmode=disable"
```

### 4. 初始化数据库

确保已创建数据库，然后运行初始化脚本：

```bash
# 如果有 SQL 初始化文件
psql -h localhost -U postgres -d your_database -f script/init_db.sql
```

### 5. 启动服务

```bash
# 开发模式
go run admin.go -f etc/admin-api.yaml

# 或编译后运行
go build -o admin admin.go
./admin -f etc/admin-api.yaml
```

服务将在 **http://localhost:8888** 启动。

### 6. 测试接口

```bash
# 登录获取 Token
curl -X POST http://localhost:8888/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 使用 Token 访问受保护接口
curl -X GET http://localhost:8888/admin/info \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 📚 API 文档

### API 概览

本系统共提供 **77 个 API 端点**，涵盖以下模块：

| 模块 | 端点数 | 说明 |
|------|--------|------|
| 🔐 认证接口 | 3 | 登录、登出、用户信息 |
| 👥 管理员管理 | 4 | 管理员 CRUD |
| 🎭 角色管理 | 6 | 角色及权限管理 |
| 📋 菜单管理 | 4 | 菜单权限管理 |
| 👤 用户管理 | 4 | C端用户管理 |
| 📖 用户行为 | 4 | 浏览记录、收藏管理 |
| 🎵 音频模块 | 9 | 音频分类和内容管理 |
| 🌄 声景模块 | 9 | 声景分类和内容管理 |
| 📚 大师课程 | 16 | 大师、课程、章节管理 |
| 💖 心能课程 | 12 | 课程、章节管理 |
| 📱 小程序路由 | 5 | 路由配置管理 |
| ⚙️ 系统配置 | 5 | 系统参数配置 |
| 📊 数据统计 | 1 | 综合数据统计 |

### 核心接口

#### 🔐 认证接口
```
POST   /admin/login          # 管理员登录
GET    /admin/info           # 获取当前用户信息（含权限和菜单）
POST   /admin/logout         # 退出登录
```

#### 👥 系统管理
```
# 管理员管理
GET    /system/admin/list
POST   /system/admin/add
PUT    /system/admin/update/:id
DELETE /system/admin/delete/:id

# 角色管理
GET    /system/role/list
POST   /system/role/add
PUT    /system/role/update/:id
DELETE /system/role/delete/:id
GET    /system/role/menus/:id      # 获取角色菜单权限
PUT    /system/role/menus/:id      # 更新角色菜单权限

# 菜单管理
GET    /system/menu/list           # 树形菜单列表
POST   /system/menu/add
PUT    /system/menu/update/:id
DELETE /system/menu/delete/:id
```

#### 👤 用户管理
```
GET    /system/user/list
GET    /system/user/info/:id
PUT    /system/user/update/:id
GET    /system/user/vip-order/list
GET    /system/user/browse-record/list
GET    /system/user/favorite/list
```

#### 🎵 内容管理
```
# 音频模块
GET    /system/audio/category/list
GET    /system/audio/list
GET    /system/audio/info/:id

# 声景模块
GET    /system/soundscape/category/list
GET    /system/soundscape/list
GET    /system/soundscape/info/:id

# 大师课程
GET    /system/master/list
GET    /system/master-course/list
GET    /system/master-course-chapter/list

# 心能课程
GET    /system/heart-energy-course/list
GET    /system/heart-energy-course-chapter/list
```

#### 📊 数据统计
```
GET    /system/dashboard/stats     # 综合统计数据（用户、订单、收入、内容等）
```

### 详细文档

| 文档类型 | 文件路径 | 说明 |
|---------|---------|------|
| **⚙️ OpenAPI 规范** | [`docs/openapi.json`](docs/openapi.json) | OpenAPI 3.0 格式（仅包含系统管理模块） |

### 快速开始

#### 1. 查看完整 API 列表
```bash
cat docs/API_SUMMARY.md
```

#### 2. 查看使用示例
```bash
cat docs/API_EXAMPLES.md
```

#### 3. 测试登录接口
```bash
curl -X POST http://localhost:8888/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

#### 4. 使用 Swagger UI 查看文档（可选）
```bash
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/docs/openapi.json \
  -v $(pwd)/docs:/docs \
  swaggerapi/swagger-ui
```
访问 http://localhost:8080

## 📁 项目结构

```
admin-api-service-go/
├── admin.go                    # 程序入口
├── go.mod                      # Go 模块定义
├── go.sum                      # 依赖版本锁定
├── .gitignore                  # Git 忽略规则
├── README.md                   # 项目说明文档
│
├── etc/                        # 配置文件目录
│   ├── admin-api.yaml          # 开发环境配置
│   └── admin-api-prod.yaml     # 生产环境配置
│
├── desc/                       # API 定义文件
│   └── admin.api               # Go-Zero API 定义
│
├── internal/                   # 内部代码（不对外暴露）
│   ├── config/                 # 配置结构定义
│   │   └── config.go
│   │
│   ├── handler/                # HTTP 请求处理器
│   │   ├── loginhandler.go
│   │   ├── adminlisthandler.go
│   │   ├── rolehandlers.go
│   │   ├── menuhandlers.go
│   │   ├── soundscapehandler.go
│   │   ├── audiohandler.go
│   │   ├── mastercoursehandler.go
│   │   ├── heartenergycoursehandler.go
│   │   ├── dashboardhandler.go
│   │   └── ...                 # 其他 handler
│   │
│   ├── logic/                  # 业务逻辑层
│   │   └── loginlogic.go
│   │
│   ├── middleware/             # 中间件
│   │   ├── checkpermmiddleware.go   # 权限检查
│   │   ├── corsmiddleware.go        # CORS 配置
│   │   └── errorhandlermiddleware.go # 错误处理
│   │
│   ├── model/                  # 数据模型
│   │   └── sysadminsmodel.go
│   │
│   ├── svc/                    # 服务上下文
│   │   └── servicecontext.go
│   │
│   ├── types/                  # 类型定义
│   │   └── types.go
│   │
│   └── common/                 # 公共模块
│       └── response/           # 统一响应格式
│           └── response.go
│
├── script/                     # 脚本文件
│   └── reset_admin_password.sh # 重置管理员密码
│
├── tools/                      # 工具程序
│   └── gen_password.go         # 密码生成工具
│
├── docs/                       # 文档目录
│   └── openapi.json            # OpenAPI 规范文档
│
└── docker-compose.db.standalone.yml  # 数据库 Docker 配置
```

## 🗄️ 数据库设计

### 系统管理表

| 表名 | 说明 |
|------|------|
| `sys_admins` | 系统管理员 |
| `sys_roles` | 角色定义 |
| `sys_menus` | 菜单权限 |
| `sys_role_menus` | 角色菜单关联 |
| `sys_admin_roles` | 管理员角色关联 |
| `sys_configs` | 系统配置 |
| `sys_oper_logs` | 操作日志 |
| `sys_login_logs` | 登录日志 |

### 内容管理表

| 模块 | 表名 |
|------|------|
| **声景** | `soundscape_categories`, `soundscapes` |
| **音频** | `audio_categories`, `audios` |
| **心能课程** | `heart_energy_course_categories`, `heart_energy_courses`, `heart_energy_course_chapters` |
| **大师课程** | `master_course_categories`, `masters`, `master_courses`, `master_course_chapters` |
| **小程序路由** | `miniapp_routes` |

### 用户管理表

| 表名 | 说明 |
|------|------|
| `users` | 用户基本信息 |
| `user_auths` | 用户认证信息 |
| `user_vips` | 用户 VIP 信息 |
| `user_vip_orders` | VIP 订单 |
| `user_browse_records` | 浏览记录 |
| `user_favorites` | 收藏记录 |

## ⚙️ 配置说明

### 主配置文件 (etc/admin-api.yaml)

```yaml
Name: admin-api          # 服务名称
Host: 0.0.0.0           # 监听地址
Port: 8888              # 监听端口

Auth:
  AccessSecret: "your-secret-key"  # JWT 密钥（生产环境必须修改）
  AccessExpire: 86400              # Token 过期时间（秒）

Database:
  DataSource: "postgres://user:pass@host:port/dbname?sslmode=disable"

# 开发模式（生产环境必须设置为 false）
DevMode: true
MasterPassword: "admin888"  # 万能密码（仅开发模式有效）

# CORS 跨域配置
Cors:
  AllowOrigins:
    - "http://localhost:5173"  # 允许的前端域名
  AllowMethods:
    - "GET"
    - "POST"
    - "PUT"
    - "DELETE"
  AllowHeaders:
    - "Content-Type"
    - "Authorization"
  AllowCredentials: true
  MaxAge: 3600
```

### 环境变量支持

可通过环境变量覆盖配置：

```bash
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=postgres
export DB_PASSWORD=yourpassword
export DB_NAME=yourdb
```

## 🔧 开发指南

### 添加新功能模块

1. **定义 API**：在 `desc/admin.api` 中定义接口

```api
type UserAddReq {
    Name string `json:"name"`
}

@server(
    jwt: Auth
    middleware: CheckPerm
)
service admin-api {
    @handler UserAddHandler
    post /system/user/add (UserAddReq) returns ()
}
```

2. **生成代码**（如果安装了 goctl）

```bash
goctl api go -api desc/admin.api -dir . -style gozero
```

3. **实现业务逻辑**：在 `internal/handler/` 创建 handler

4. **注册路由**：在 `admin.go` 中注册路由

### 使用工具

#### 生成 bcrypt 密码

```bash
go run tools/gen_password.go
```

#### 重置管理员密码

```bash
./script/reset_admin_password.sh <username> <new_password>
```

## 🔒 安全建议

### 生产环境部署清单

- [ ] 修改 `AccessSecret` 为强随机字符串
- [ ] 将 `DevMode` 设置为 `false`
- [ ] 删除或注释 `MasterPassword`
- [ ] 修改默认管理员密码
- [ ] 配置 HTTPS
- [ ] 限制 CORS 允许的域名
- [ ] 配置防火墙规则
- [ ] 定期备份数据库
- [ ] 启用操作日志审计

### 密码强度要求

建议密码策略：
- 最小长度：8 位
- 包含大小写字母、数字和特殊字符
- 定期更换密码
- 禁止使用弱密码

## 🧪 测试

### 运行测试脚本

```bash
./test_all_apis.sh
```

### 单元测试

```bash
go test ./...
```

### 性能测试

```bash
go test -bench=. -benchmem ./...
```

## 📦 部署

### 编译

```bash
# Linux
GOOS=linux GOARCH=amd64 go build -o admin-linux admin.go

# Windows
GOOS=windows GOARCH=amd64 go build -o admin.exe admin.go

# macOS
GOOS=darwin GOARCH=amd64 go build -o admin-mac admin.go
```

### Docker 部署

```bash
# 构建镜像
docker build -t admin-api:latest .

# 运行容器
docker run -d \
  --name admin-api \
  -p 8888:8888 \
  -v $(pwd)/etc:/app/etc \
  admin-api:latest
```

### 使用 Docker Compose

```bash
docker-compose up -d
```

## 📊 性能指标

- **并发能力**：支持 10000+ 并发连接
- **响应时间**：平均 < 50ms
- **QPS**：单实例 > 5000 QPS
- **可用性**：99.9%+

### 代码规范

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 使用 `golangci-lint` 进行代码检查
- 添加必要的注释和文档