# crypto-data

**Repository Path**: Amensia/crypto-data

## Basic Information

- **Project Name**: crypto-data
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2025-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 加密货币爆仓数据监控系统

实时监控加密货币交易所爆仓数据的完整系统，包含后端数据采集处理和前端实时展示。

## 🎯 功能特性

- **实时数据采集** - 通过 WebSocket 连接到 Coinank 获取爆仓数据
- **多维度统计** - 支持 1m/3m/5m/10m/15m/30m 时间窗口统计
- **多空分析** - 区分多头和空头爆仓数据
- **高性能处理** - 异步处理、内存优化、自动清理过期数据
- **丰富 API** - RESTful API 接口支持查询、搜索、排序
- **友好界面** - Vue 3 + Element Plus 实时数据展示
- **单一部署** - 前端已集成到后端，无需分离部署

## 📊 技术栈

### 后端
- **框架**: FastAPI 0.104.1
- **异步**: Python asyncio + uvicorn
- **WebSocket**: websockets 12.0
- **数据处理**: pandas, numpy
- **日志**: loguru

### 前端
- **框架**: Vue 3
- **状态管理**: Pinia
- **UI 组件**: Element Plus
- **图表**: ECharts
- **构建**: Vite

## 🚀 快速开始

### 环境要求

- Python 3.8+
- Node.js 16+ (仅用于构建，部署时不需要)
- macOS / Linux / Windows

### 1. 克隆项目

```bash
git clone https://gitee.com/Amensia/crypto-data.git
cd crypto-data
```

### 2. 前端构建 (首次或更新前端时)

```bash
cd frontend
npm install
npm run build
cd ..
```

这会将前端构建到 `backend/static` 目录。

### 3. 安装后端依赖

```bash
cd backend
pip install -r requirements.txt
```

### 4. 启动后端服务

```bash
cd backend
python3 main.py
```

服务将在 `http://localhost:8000` 启动

### 5. 访问应用

打开浏览器访问: **http://localhost:8000**

就能看到完整的监控面板！

## 📡 API 接口

所有 API 均在 `/api` 前缀下：

### 币种数据

- `GET /api/coins` - 获取所有币种爆仓统计
- `GET /api/coins/{coin}` - 获取指定币种详情
- `GET /api/coins/top/{limit}` - 获取爆仓量最大的币种
- `GET /api/search?query=BTC` - 搜索币种

### 记录数据

- `GET /api/liquidations/{coin}` - 获取币种逐笔爆仓记录

### 系统统计

- `GET /api/stats/system` - 获取系统统计信息
- `GET /api/stats/summary` - 获取汇总统计信息
- `GET /api/windows` - 获取支持的时间窗口列表

### 健康检查

- `GET /health` - 服务健康状态检查

## 📁 项目结构

```
.
├── backend/
│   ├── main.py                    # FastAPI 应用入口
│   ├── websocket_client.py        # Coinank WebSocket 客户端
│   ├── data_processor.py          # 爆仓数据处理器
│   ├── api_routes.py              # REST API 路由
│   ├── requirements.txt           # Python 依赖
│   ├── static/                    # 前端构建输出（自动生成）
│   │   ├── index.html
│   │   ├── assets/
│   │   └── ...
│   └── logs/                      # 应用日志
│
├── frontend/
│   ├── src/
│   │   ├── main.js               # 应用入口
│   │   ├── App.vue               # 根组件
│   │   ├── router/               # 路由配置
│   │   ├── stores/               # Pinia 状态管理
│   │   ├── views/                # 页面组件
│   │   ├── api/                  # API 调用
│   │   └── styles/               # 样式
│   ├── package.json
│   ├── vite.config.js            # Vite 配置
│   └── node_modules/             # NPM 依赖（不提交）
│
├── .gitignore
├── README.md                      # 本文件
└── 需求文档.md                    # 项目需求文档
```

## 🔧 开发模式

### 后端开发

```bash
cd backend
python3 main.py
```

在开发过程中，FastAPI 内置的 `reload=True` 会自动重载代码变化。

### 前端开发

```bash
cd frontend
npm run dev
```

Vite 开发服务器将在 `http://localhost:3000` 运行，并自动代理 API 调用到 `http://localhost:8000`。

### 前端构建

当前端完成时，运行以下命令构建并集成到后端：

```bash
cd frontend
npm run build
```

## 📊 数据结构

### 爆仓数据记录

```json
{
  "exchangeName": "Huobi",
  "baseCoin": "BTC",
  "side": "sell",
  "exchangeType": "SWAP",
  "contractType": "USDT",
  "contractCode": "BTC-USDT",
  "posSide": "long",
  "volume": 2.0,
  "amount": 0.02,
  "price": 95000.00,
  "avgPrice": 95000.00,
  "tradeTurnover": 1900.00,
  "ts": 1756956897901
}
```

### 时间窗口统计

```json
{
  "coin": "BTC",
  "timeWindows": {
    "5m": {
      "long": {
        "volume": 100.5,
        "amount": 1000000,
        "count": 25
      },
      "short": {
        "volume": 80.2,
        "amount": 800000,
        "count": 20
      },
      "total": {
        "volume": 180.7,
        "amount": 1800000,
        "count": 45
      }
    }
  },
  "lastUpdate": 1756956897901
}
```

## 🔄 数据流向

```
Coinank WebSocket
        ↓
WebSocket 客户端 (后端)
        ↓
数据处理器 (爆仓数据解析、分类、统计)
        ↓
Pinia Store (前端状态管理)
        ↓
Vue 组件 (数据展示、实时更新)
```

## ⚙️ 配置说明

### 后端配置

编辑 `backend/main.py` 中的以下配置：

- `host`: 服务监听地址（默认 `0.0.0.0`）
- `port`: 服务监听端口（默认 `8000`）
- `reload`: 开发模式自动重载（默认 `True`）

### WebSocket 配置

Coinank WebSocket 端点：`wss://ws.coinank.com/wsKline/wsKline`

订阅消息：
```json
{
  "op": "subscribe",
  "args": "liqOrder@All@All@1m"
}
```

## 📝 日志

应用日志保存在 `backend/logs/` 目录：

- `app.log` - 应用运行日志（自动轮转，保留 7 天）
- 控制台输出日志（开发时）

## 🚢 部署

### Docker 部署 (推荐)

创建 `Dockerfile`：

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY backend/requirements.txt .
RUN pip install -r requirements.txt

COPY backend .

CMD ["python", "main.py"]
```

构建和运行：

```bash
docker build -t crypto-monitor .
docker run -p 8000:8000 crypto-monitor
```

### 生产部署

使用 Gunicorn + Uvicorn：

```bash
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 backend.main:app
```

## 🐛 故障排查

### 前端无法加载

- 确保已运行 `npm run build`
- 检查 `backend/static/index.html` 是否存在
- 查看后端日志中是否有错误

### WebSocket 连接失败

- 检查网络连接
- 验证 Coinank 服务状态
- 查看后端日志中的重连信息

### API 响应异常

- 访问 `/api/stats/system` 检查系统状态
- 查看后端日志中的错误信息
- 验证 WebSocket 数据接收状态

## 📄 许可证

MIT

## 👤 作者

Amensia

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！