# gin-gonic

**Repository Path**: sushiman/gin-gonic

## Basic Information

- **Project Name**: gin-gonic
- **Description**: gin-gonic --学习go-gin-api的框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-02
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级即时通讯系统 (Enterprise IM System)

一个基于 Go 语言开发的高性能、高可靠、分布式企业级即时通讯系统，支持大量并发用户和实时消息传递。

## 系统特性

### 核心功能
- ✅ **实时消息通信**：基于 WebSocket 实现的低延迟双向通信
- ✅ **群聊支持**：支持大型群组聊天（5000+成员）
- ✅ **消息持久化**：通过 Redis 实现消息可靠传递和持久化
- ✅ **用户在线状态管理**：基于 Redis 的高效在线状态跟踪
- ✅ **消息优先级**：支持不同类型消息的优先级处理
- ✅ **认证与授权**：JWT 认证和 WebSocket 安全连接
- ✅ **消息广播**：高效的消息广播机制

### 技术优势
- **高性能**：Go 语言的高并发特性，支持每秒数千条消息
- **高可靠**：Redis Pub/Sub 确保消息可靠传递
- **分布式**：支持水平扩展，可部署多节点集群
- **实时性**：WebSocket 实现亚秒级消息传递
- **可监控**：内置 Redis 监控和系统状态追踪

## 技术栈

### 核心技术
- **编程语言**：Go 1.19+
- **Web 框架**：Gin Web Framework
- **实时通信**：Gorilla WebSocket
- **消息分发**：Redis Pub/Sub
- **缓存与会话**：Redis
- **容器化**：Docker Compose

### 依赖库
- `github.com/gin-gonic/gin` - Web 框架
- `github.com/gorilla/websocket` - WebSocket 支持
- `github.com/go-redis/redis/v8` - Redis 客户端
- `github.com/golang-jwt/jwt/v4` - JWT 认证

## 项目结构

```
├── .gitignore            # Git 忽略文件配置
├── README.md             # 项目说明文档
├── api/                  # API 定义文件
├── api_docs.html         # API 文档
├── cert.pem              # SSL 证书
├── cert.pfx              # SSL 证书 (PFX 格式)
├── cmd/                  # 应用程序入口
│   ├── app1/             # 应用实例 1
│   │   └── main.go
│   └── app2/             # 应用实例 2
│       └── main.go
├── config/               # 配置文件目录
│   ├── config.dev.yaml   # 开发环境配置
│   ├── config.go         # 配置加载代码
│   ├── config.prod.yaml  # 生产环境配置
│   └── config.yaml       # 默认配置
├── deployments/          # 部署配置
├── go.mod                # Go 模块依赖
├── internal/             # 内部代码
│   ├── controller/       # 控制器层
│   │   ├── Huashu.go     # 华数相关控制器
│   │   ├── im.go         # IM 核心控制器
│   │   ├── message.go    # 消息控制器
│   │   ├── product.go    # 产品控制器
│   │   ├── user.go       # 用户控制器
│   │   └── ws/           # WebSocket 相关代码
│   ├── middleware/       # 中间件
│   │   ├── auth.go       # 认证中间件
│   │   ├── cors.go       # CORS 中间件
│   │   ├── logger.go     # 日志中间件
│   │   └── ws_auth.go    # WebSocket 认证中间件
│   ├── models/           # 数据模型
│   │   ├── dialog_models.go  # 对话模型
│   │   ├── user_models.go    # 用户模型
│   │   └── ws_chat_models.go # WebSocket 聊天模型
│   └── utils/            # 工具函数
│       └── jwt.go        # JWT 工具
├── key.pem               # SSL 私钥
├── main.go               # 主程序入口
├── routes/               # 路由定义
│   └── web.go            # Web 路由配置
├── scripts/              # 脚本文件
├── test_*.go             # 测试文件
├── ws*.html              # WebSocket 测试页面
```

## 部署与运行

### 1. 启动依赖服务 (Redis)

确保 Redis 服务已启动：

```bash
# 使用 Docker 启动 Redis
docker run -d --name redis -p 6379:6379 redis:latest

# 或使用已有的 Redis 服务
```

### 2. 配置环境变量

创建 `.env` 文件：

```env
# Redis Configuration
REDIS_ADDR=localhost:6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DB=0

# Admin User Configuration
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
```

### 3. 运行 IM 系统

```bash
# 直接运行
go run main.go

# 或使用热重启 (需要安装 nodemon)
nodemon --exec go run main.go --ext go
```

**服务地址**：
- HTTP API: `http://localhost:8690`
- WebSocket: `ws://localhost:8690/ws/group`

### 4. 构建生产版本

```bash
go build -o app main.go

# 运行生产版本
./app
```

## API 接口

### WebSocket 接口

**群聊连接**：
```
ws://localhost:8690/ws/group
```

**认证**：
- 使用 JWT token 作为查询参数: `ws://localhost:8690/ws/group?token=YOUR_JWT_TOKEN`

**消息格式**：
```json
{
  "type": "message",
  "group_id": "group123",
  "user_id": "user456",
  "content": "Hello, World!",
  "timestamp": 1635789000,
  "priority": 1
}
```

### REST API

**用户认证**：
```
POST /api/auth/login
```

**获取在线用户**：
```
GET /api/users/online?group_id=group123
```

**发送消息**：
```
POST /api/messages/send
```

更多 API 详情请查看 `api_docs.html` 文件。

## 系统架构

### 消息传递流程

1. **客户端连接**：客户端通过 WebSocket 连接到服务器
2. **消息发送**：客户端发送消息到服务器
3. **消息广播**：
   - 本地广播：通过 Go Channel 高效广播给本地连接的客户端
   - 分布式广播：通过 Redis Pub/Sub 广播给其他服务器节点
4. **消息持久化**：Redis 负责消息的持久化存储
5. **状态管理**：Redis 记录用户在线状态和会话信息

### 高并发设计

- **WebSocket 连接**：每个连接使用独立的 Goroutine
- **消息分发**：Redis Pub/Sub 处理高吞吐量的消息流
- **缓存机制**：Redis 缓存热点数据和会话信息
- **负载均衡**：支持多节点部署和负载均衡

## 监控与管理

### IM管理后台

系统提供了基于 Vue 3 的可视化管理后台，用于监控和管理 IM 系统。

#### 启动管理后台

1. **进入前端目录**：
   ```bash
   cd admin-frontend
   ```

2. **安装依赖**（首次运行需要）：
   ```bash
   npm install
   ```

3. **启动开发服务器**：
   ```bash
   npm run dev
   ```

#### 访问管理后台

前端服务启动后，在浏览器中访问：
```
http://localhost:5173
```

#### 管理后台功能

登录后，您可以访问以下功能：
- **系统配置管理**：管理 Redis 等系统配置
- **API文档**：查看系统完整的 API 接口文档
- **实时监控**：查看系统运行状态和 Redis 监控数据

#### 生产环境部署

如果需要部署到生产环境，可以构建前端静态文件：
```bash
# 构建生产版本
npm run build

# 将 dist 目录部署到 Web 服务器（如 Nginx）
```

### 系统日志

系统运行时会输出详细日志，包括：
- 连接状态
- 消息收发
- 错误信息
- Redis 监控指标

## 开发指南

### 环境要求
- Go 1.19+
- Redis

### 代码规范
- 遵循 Go 官方代码规范
- 使用 `go fmt` 格式化代码
- 编写单元测试和集成测试

### 测试

```bash
# 运行单元测试
go test ./...

# 运行特定测试文件
go test -v ./internal/controller/ws
```

## 故障排除

### 常见问题

1. **Redis 连接失败**：
   - 检查 Redis 服务是否运行
   - 检查 Redis 配置是否正确

2. **WebSocket 连接失败**：
   - 检查服务器是否运行
   - 验证 JWT token 是否有效
   - 检查网络防火墙设置

3. **消息发送失败**：
   - 检查 Redis 连接
   - 查看系统日志获取详细错误信息

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如有问题或建议，请联系项目维护者。