# marketserver

**Repository Path**: trackerchain/marketserver

## Basic Information

- **Project Name**: marketserver
- **Description**: 期货行情服务
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-09
- **Last Updated**: 2025-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MarketServer - 期货行情服务系统

<div align="center">

![Go Version](https://img.shields.io/badge/Go-1.24.7-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![WebSocket](https://img.shields.io/badge/WebSocket-Supported-orange.svg)
![Status](https://img.shields.io/badge/Status-Active-brightgreen.svg)

**一个基于 Go 语言开发的高性能期货行情服务系统**

</div>

## 📖 项目简介

MarketServer 是一个专为期货交易场景设计的实时行情服务系统，提供完整的命令行工具和 WebSocket 实时数据推送服务。系统采用模块化设计，支持多种期货合约的实时行情数据生成、分发和管理。

### 🎯 核心特性

- 🚀 **实时行情推送**: 基于 WebSocket 的高性能实时数据推送
- 📊 **期货合约管理**: 支持多种期货合约的行情数据生成和管理
- 📈 **K线数据服务**: 支持多时间周期K线数据生成和实时推送 (1分钟、5分钟、日线等)
- 🔐 **用户管理系统**: 完整的用户注册、认证和权限管理
- 🔑 **API KEY 验证**: 基于 JWT Token 的安全认证机制
- ⚙️ **灵活配置系统**: 完整的配置管理，支持交易所连接、风控参数等
- 🔧 **命令行工具**: 基于 Cobra 的强大 CLI 工具，操作简单直观
- 🌐 **Web 管理界面**: 内置 Web 界面，方便监控和测试
- 📊 **模拟数据生成**: 内置智能行情数据生成器，支持真实市场波动模拟
- 📝 **企业级日志系统**: 基于 Logrus + Lumberjack 的结构化日志，支持文件轮转和多级别输出

## 🏗️ 系统架构

```
MarketServer
├── CLI 命令行工具
│   ├── 服务器管理 (server)
│   ├── 订阅服务 (subscribe)
│   ├── 用户管理 (user)
│   ├── 配置管理 (config)
│   └── 版本信息 (version)
├── 用户管理系统
│   ├── 用户注册/登录 (Service)
│   ├── JWT Token 认证 (JWT)
│   ├── API KEY 管理 (Database)
│   └── 权限控制 (Models)
├── WebSocket 服务
│   ├── 连接管理 (Hub)
│   ├── API KEY 验证 (Auth)
│   ├── 实时推送 (Server)
│   ├── Tick数据生成 (Generator)
│   └── K线数据生成 (KlineGenerator)
├── 日志系统
│   ├── 结构化日志 (Logrus)
│   ├── 文件轮转 (Lumberjack)
│   ├── 多输出支持 (Console + File)
│   └── 日志级别控制 (Info/Warn/Error/Debug)
└── Web 管理界面
    ├── 状态监控
    ├── 测试工具
    └── API 接口
```

### 🛠️ 技术栈

- **编程语言**: Go 1.24.7
- **Web框架**: Gorilla WebSocket
- **命令行工具**: Cobra CLI
- **配置管理**: Viper
- **数据库**: SQLite3
- **身份认证**: JWT (golang-jwt/jwt)
- **日志系统**: Logrus + Lumberjack
- **UUID生成**: Google UUID
- **并发处理**: Go Goroutines + Channels

## 🚀 快速开始

### 环境要求

- Go 1.24.7 或更高版本
- Windows/Linux/macOS 操作系统

### 安装步骤

```bash
# 1. 克隆项目
git clone <repository-url>
cd marketserver

# 2. 安装依赖
go mod tidy

# 3. 构建可执行文件
go build -o marketserver.exe .

# 4. 验证安装
./marketserver.exe --help
```

### 快速启动

```bash
# 1. 启动期货行情服务器
./marketserver.exe server start

# 2. 创建测试用户 (新终端窗口)
./marketserver.exe user create --email test@example.com --name "测试用户"

# 3. 查看用户信息和API KEY
./marketserver.exe user get --email test@example.com

# 4. 访问管理界面测试WebSocket连接
# 浏览器打开: http://localhost:8081
```

### 完整使用示例

```bash
# 步骤1: 启动服务器
./marketserver.exe server start

# 步骤2: 创建用户并获取API KEY
./marketserver.exe user create --email trader@example.com --name "交易员"
# 输出示例:
# 用户创建成功!
# 用户ID: 1
# 邮箱: trader@example.com
# 姓名: 交易员
# API密钥: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# 状态: 启用

# 步骤3: 使用API KEY连接WebSocket (JavaScript示例)
```

```javascript
// 使用API KEY连接WebSocket
const apiKey = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // 从步骤2获取
const ws = new WebSocket(`ws://localhost:8081/ws?api_key=${apiKey}`);

ws.onopen = function() {
    console.log("连接成功");
    
    // 订阅沪铜期货Tick行情
    ws.send(JSON.stringify({
        action: "subscribe",
        symbol: "CU2501",
        type: "tick"
    }));
};

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log("收到数据:", data);
};
```

## 📋 命令参考

### 🖥️ 服务器管理 (server)

```bash
# 启动服务器
./marketserver.exe server start
./marketserver.exe server start --port 8080 --ws-port 8081 --host 0.0.0.0

# 停止服务器
./marketserver.exe server stop

# 查看服务器状态
./marketserver.exe server status
```

**参数说明:**
- `--port, -p`: HTTP 服务器端口 (默认: 8080)
- `--ws-port, -w`: WebSocket 服务器端口 (默认: 8081)
- `--host`: 服务器监听地址 (默认: localhost)
- `--log-level`: 日志级别 (默认: info)

### 👥 用户管理 (user)

```bash
# 创建新用户
./marketserver.exe user create --email user@example.com --name "用户名"

# 查看用户列表
./marketserver.exe user list
./marketserver.exe user list --page 1 --size 10 --verbose

# 查看用户详情
./marketserver.exe user get --id 1
./marketserver.exe user get --email user@example.com

# 更新用户信息
./marketserver.exe user update --id 1 --name "新用户名"
./marketserver.exe user update --id 1 --status disabled

# 删除用户
./marketserver.exe user delete --id 1

# 重置用户API密钥
./marketserver.exe user reset-key --id 1
./marketserver.exe user reset-key --email user@example.com
```

**参数说明:**
- `--email, -e`: 用户邮箱地址 (必填，用于创建和查询)
- `--name, -n`: 用户姓名 (必填，用于创建)
- `--id`: 用户ID (用于查询、更新、删除)
- `--status`: 用户状态 (enabled/disabled)
- `--page`: 分页页码 (默认: 1)
- `--size`: 每页大小 (默认: 10)
- `--verbose, -v`: 显示详细信息

**用户状态:**
- `enabled`: 启用状态，可以正常使用API
- `disabled`: 禁用状态，无法使用API

### 📡 订阅服务 (subscribe)

```bash
# 订阅指定合约Tick行情
./marketserver.exe subscribe start --contract CU2501
./marketserver.exe subscribe start --url ws://localhost:8081/ws

# 订阅指定合约K线数据
./marketserver.exe subscribe start --contract CU2501 --type kline --period 1m
./marketserver.exe subscribe start --contract CU2501 --type kline --period 5m
./marketserver.exe subscribe start --contract CU2501 --type kline --period 1d

# 订阅所有合约Tick行情
./marketserver.exe subscribe start

# 订阅所有合约K线数据
./marketserver.exe subscribe start --contract ALL --type kline --period 1m

# 列出可用合约
./marketserver.exe subscribe list
```

**订阅类型说明:**
- `--type tick`: 订阅实时Tick行情数据 (默认)
- `--type kline`: 订阅K线数据

**K线周期参数 (--period):**
- `1m`: 1分钟K线
- `5m`: 5分钟K线
- `15m`: 15分钟K线
- `30m`: 30分钟K线
- `1h`: 1小时K线
- `1d`: 日K线
- `1w`: 周K线
- `1M`: 月K线

### ⚙️ 配置管理 (config)

```bash
# 查看所有配置
./marketserver.exe config get

# 查看特定配置
./marketserver.exe config get server.port

# 设置配置
./marketserver.exe config set server.port 9090

# 列出配置项
./marketserver.exe config list

# 重置配置
./marketserver.exe config reset server.port --force
```

**可用子命令:**
- `get`: 获取配置值
- `list`: 列出所有配置项
- `reset`: 重置配置
- `set`: 设置配置值

### 📦 版本信息 (version)

```bash
# 显示版本信息
./marketserver.exe version
./marketserver.exe version --detailed
```

## 🔌 WebSocket API

### 连接地址
```
ws://localhost:8081/ws
```

### 🔐 API KEY 验证

WebSocket 连接需要提供有效的 API KEY 进行身份验证：

```javascript
// 连接时在URL中提供API KEY
const ws = new WebSocket('ws://localhost:8081/ws?api_key=YOUR_API_KEY');

// 或者在连接建立后发送认证消息
const authMessage = {
  "action": "auth",
  "api_key": "YOUR_API_KEY"
};
ws.send(JSON.stringify(authMessage));
```

**获取 API KEY:**
```bash
# 创建用户时会自动生成API KEY
./marketserver.exe user create --email user@example.com --name "用户名"

# 重置现有用户的API KEY
./marketserver.exe user reset-key --email user@example.com
```

**认证响应:**
```json
{
  "type": "auth_success",
  "message": "认证成功",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "用户名"
  }
}
```

### 消息格式

**订阅Tick行情:**
```json
{
  "action": "subscribe",
  "symbol": "CU2501",
  "type": "tick"
}
```

**订阅K线数据:**
```json
{
  "action": "subscribe",
  "symbol": "CU2501",
  "type": "kline",
  "period": "1m"
}
```

**订阅所有合约Tick行情:**
```json
{
  "action": "subscribe", 
  "symbol": "",
  "type": "tick"
}
```

**订阅所有合约K线数据:**
```json
{
  "action": "subscribe", 
  "symbol": "ALL",
  "type": "kline",
  "period": "1m"
}
```

**取消订阅:**
```json
{
  "action": "unsubscribe",
  "symbol": "CU2501",
  "type": "tick"
}
```

### 数据格式

**Tick行情数据:**
```json
{
  "type": "data",
  "data": {
    "symbol": "CU2501",
    "name": "沪铜2501",
    "price": 74520.0,
    "change": 120.0,
    "changePercent": 0.16,
    "volume": 15420,
    "openInterest": 89650,
    "timestamp": "2024-01-15T14:30:00Z"
  }
}
```

**K线数据:**
```json
{
  "type": "kline",
  "data": {
    "symbol": "CU2501",
    "name": "沪铜2501",
    "period": "1m",
    "timestamp": "2024-01-15T14:30:00Z",
    "open": 74500.0,
    "high": 74580.0,
    "low": 74480.0,
    "close": 74520.0,
    "volume": 1542,
    "amount": 0.85,
    "change": 20.0,
    "changePercent": 0.027
  }
}
```

**响应消息:**
```json
{
  "type": "success",
  "message": "订阅成功: CU2501"
}
```

## 🌐 HTTP API

### 基础地址
```
http://localhost:8081/api/
```

### 接口列表

| 接口 | 方法 | 描述 |
|------|------|------|
| `/api/contracts` | GET | 获取所有期货合约列表 |
| `/api/status` | GET | 获取服务器状态信息 |
| `/api/users` | GET | 获取用户列表 (需要管理员权限) |
| `/api/users/{id}` | GET | 获取指定用户信息 |
| `/api/users` | POST | 创建新用户 |
| `/api/users/{id}` | PUT | 更新用户信息 |
| `/api/users/{id}` | DELETE | 删除用户 |
| `/api/users/{id}/reset-key` | POST | 重置用户API密钥 |
| `/` | GET | 管理界面首页 |
| `/test` | GET | WebSocket 测试页面 |

### 示例响应

**合约列表 (`/api/contracts`):**
```json
{
  "success": true,
  "data": [
    {
      "symbol": "CU2501",
      "name": "沪铜2501",
      "basePrice": 74400.0,
      "lastPrice": 74520.0
    }
  ]
}
```

**服务状态 (`/api/status`):**
```json
{
  "success": true,
  "data": {
    "running": true,
    "port": 8081,
    "clients": 3,
    "generator": true,
    "contracts": 6,
    "websocket_url": "ws://localhost:8081/ws",
    "api_url": "http://localhost:8081/api/"
  }
}
```

## ⚙️ 配置说明

### 服务器配置
- `server.host`: 服务器监听地址 (默认: localhost)
- `server.port`: HTTP 服务器端口 (默认: 8080)
- `server.log_level`: 日志级别 (默认: info)

### 日志系统配置
- `log.level`: 日志级别 (debug/info/warn/error，默认: info)
- `log.file.enabled`: 是否启用文件日志 (默认: true)
- `log.file.path`: 日志文件路径 (默认: logs/marketserver.log)
- `log.file.max_size`: 单个日志文件最大大小 (默认: 100MB)
- `log.file.max_backups`: 保留的备份文件数量 (默认: 10)
- `log.file.max_age`: 日志文件保留天数 (默认: 30天)
- `log.file.compress`: 是否压缩旧日志文件 (默认: true)
- `log.console.enabled`: 是否启用控制台输出 (默认: true)
- `log.format`: 日志格式 (text/json，默认: text)

### 数据库配置
- `database.path`: SQLite 数据库文件路径 (默认: ./data/users.db)

### 用户管理配置
- `jwt.secret`: JWT Token 签名密钥 (必须配置)
- `jwt.expiry`: Token 过期时间 (默认: 24h)
- `user.default_status`: 新用户默认状态 (默认: enabled)



## 📁 项目结构

```
marketserver/
├── main.go                 # 程序入口
├── cmd/                    # 命令定义
│   ├── root.go            # 根命令
│   ├── server.go          # 服务器管理命令
│   ├── subscribe.go       # 订阅服务命令
│   ├── user.go            # 用户管理命令
│   ├── config.go          # 配置管理命令
│   └── version.go         # 版本信息命令
├── user/                   # 用户管理模块
│   ├── models.go          # 用户数据模型
│   ├── database.go        # 数据库操作
│   ├── service.go         # 用户服务层
│   └── jwt.go             # JWT Token 处理
├── websocket/             # WebSocket 服务
│   ├── server.go          # WebSocket 服务器
│   ├── hub.go             # 连接管理中心
│   ├── generator.go       # 行情数据生成器
│   └── types.go           # 数据类型定义
├── logger/                 # 日志系统模块
│   └── logger.go          # 日志配置和封装
├── data/                   # 数据目录
│   └── users.db           # SQLite 用户数据库
├── logs/                   # 日志文件目录
│   ├── marketserver.log   # 当前日志文件
│   ├── marketserver.log.1 # 轮转备份文件
│   └── ...                # 其他备份文件
├── go.mod                 # Go 模块文件
├── go.sum                 # 依赖校验文件
└── README.md              # 项目文档
```

## 🔧 开发指南

### 本地开发

```bash
# 运行开发服务器
go run main.go server start

# 运行测试
go test ./...

# 代码格式化
go fmt ./...

# 静态检查
go vet ./...
```

### 构建发布

```bash
# 构建 Windows 版本
GOOS=windows GOARCH=amd64 go build -o marketserver.exe .

# 构建 Linux 版本
GOOS=linux GOARCH=amd64 go build -o marketserver .

# 构建 macOS 版本
GOOS=darwin GOARCH=amd64 go build -o marketserver .
```

## 🐛 故障排除

### 常见问题

**Q: WebSocket 连接失败**
```bash
# 检查服务器是否启动
./marketserver.exe server status

# 检查端口是否被占用
netstat -an | findstr :8081
```

**Q: 配置修改不生效**
```bash
# 重启服务器
./marketserver.exe server stop
./marketserver.exe server start
```

**Q: 行情数据不更新**
```bash
# 检查数据生成器状态
./marketserver.exe server status
```

**Q: API KEY 验证失败**
```bash
# 检查用户状态
./marketserver.exe user get --email user@example.com

# 重置API密钥
./marketserver.exe user reset-key --email user@example.com
```

**Q: 用户创建失败**
```bash
# 检查邮箱格式是否正确
# 检查用户是否已存在
./marketserver.exe user list | grep "user@example.com"
```

**Q: JWT Token 相关错误**
```bash
# 检查JWT密钥配置
./marketserver.exe config get jwt.secret

# 设置JWT密钥 (如果未配置)
./marketserver.exe config set jwt.secret "your-secret-key"
```

### 日志查看

服务器运行时会输出详细的日志信息，包括：
- WebSocket 连接状态
- 客户端订阅情况
- 行情数据推送记录
- 错误和异常信息

**日志文件位置:**
```bash
# 查看当前日志文件
tail -f logs/marketserver.log

# 查看日志文件列表
ls -la logs/

# 查看压缩的历史日志
zcat logs/marketserver.log.1.gz
```

**日志级别说明:**
- `DEBUG`: 调试信息，详细的程序执行流程
- `INFO`: 一般信息，正常的业务操作记录
- `WARN`: 警告信息，可能的问题但不影响运行
- `ERROR`: 错误信息，需要关注的异常情况

**Q: 日志文件过大或磁盘空间不足**
```bash
# 检查日志文件大小
du -h logs/

# 手动清理旧日志文件
rm logs/marketserver.log.*.gz

# 调整日志轮转配置
./marketserver.exe config set log.file.max_size 50    # 改为50MB
./marketserver.exe config set log.file.max_backups 5  # 只保留5个备份
```

**Q: 日志级别调整**
```bash
# 设置为调试级别 (输出更详细信息)
./marketserver.exe config set log.level debug

# 设置为错误级别 (只输出错误信息)
./marketserver.exe config set log.level error

# 重启服务器使配置生效
./marketserver.exe server stop
./marketserver.exe server start
```

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue: [GitHub Issues](https://github.com/your-repo/marketserver/issues)
- 邮箱: your-email@example.com

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给它一个 Star！**

</div>