添加本地数据源，以后就可以直接用本地数据了
This commit is contained in:
jackyu66git
+127
-34
@@ -1,48 +1,141 @@
|
||||
# Local Data Service (REST + WebSocket)
|
||||
# Local Data Service（REST + WebSocket）
|
||||
|
||||
一键部署、跨平台的本地行情数据服务。默认抓取 Binance 永续合约 `BTC/USDT:USDT, ETH/USDT:USDT` 的 `1m/5m/15m/1h` K 线，增量写入本地 Parquet 并通过 WebSocket 推送。
|
||||
本服务基于 FastAPI + ccxt，自动拉取交易所行情、写入本地 Parquet，同时提供 REST 和 WebSocket 数据访问。
|
||||
自带时间周期聚合能力：只需抓取 `1m / 1h / 1d / 1w / 1M` 等基础周期，即可自动生成 `2m/3m/.../30m`、`2h/3h/.../16h` 等衍生周期。
|
||||
|
||||
## 快速开始（方式B：已安装 Docker）
|
||||
---
|
||||
|
||||
## 1. 环境准备
|
||||
|
||||
### 1.1 依赖
|
||||
- Python ≥ 3.10（本地运行方式需要）
|
||||
- `pip install -r requirements.txt`（包含 `fastapi`, `uvicorn`, `ccxt`, `pandas`, `pyarrow`, `technical` 等）
|
||||
- 或者直接使用仓库内的 `docker-compose.yml`
|
||||
|
||||
### 1.2 关键环境变量
|
||||
| 变量 | 说明 | 默认 |
|
||||
| --- | --- | --- |
|
||||
| `DATA_DIR` | 本地 Parquet 存储目录 | `/data` |
|
||||
| `EXCHANGE` | 交易所标识（目前支持 binance） | `binance` |
|
||||
| `SYMBOLS` | 逗号分隔的交易对列表 | `BTC/USDT:USDT,ETH/USDT:USDT` |
|
||||
| `TIMEFRAMES` | 基础抓取周期，逗号分隔 | `1m,1h,1d,1w,1M` |
|
||||
| `START_FROM` | 首次启动回补的起始 UTC 时间（ISO 字符串或毫秒时间戳） | `2022-01-01` |
|
||||
| `POLL_FACTOR` | 拉取间隔因子，实际间隔 = 周期毫秒 × factor | `0.5` |
|
||||
| `BACKOFF_BASE / BACKOFF_MAX` | 异常重试的指数退避参数 | `2.0 / 30.0` |
|
||||
|
||||
> 衍生周期列表由程序自动推导，无需手动写入 `TIMEFRAMES`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 启动与关闭
|
||||
|
||||
### 2.1 Docker 方式
|
||||
```bash
|
||||
cd user_data/Chan/datasvc
|
||||
docker compose up -d
|
||||
docker compose up -d # 启动
|
||||
docker compose logs -f # 查看日志
|
||||
docker compose down # 关闭
|
||||
```
|
||||
|
||||
- REST: http://localhost:9000/api/candles?symbol=BTC/USDT:USDT&tf=1m
|
||||
- WS: ws://localhost:9000/ws?symbol=BTC/USDT:USDT&tf=1m&since=1690000000000
|
||||
- Swagger: http://localhost:9000/docs
|
||||
|
||||
## 环境变量（docker-compose.yml）
|
||||
- EXCHANGE: 交易所，默认 binance
|
||||
- SYMBOLS: 逗号分隔交易对
|
||||
- TIMEFRAMES: 逗号分隔周期
|
||||
- START_DAYS: 首次启动回补最近 N 天
|
||||
- POLL_FACTOR: 轮询因子，间隔=周期毫秒*factor
|
||||
- DATA_DIR: 容器内数据目录（已映射到 `./data`）
|
||||
|
||||
## 数据位置
|
||||
- 本地缓存：`user_data/Chan/datasvc/data/{timeframe}/{symbol}.parquet`
|
||||
|
||||
## 常用命令
|
||||
### 2.2 本地运行（无 Docker）
|
||||
```bash
|
||||
docker compose logs -f
|
||||
export DATA_DIR=./data
|
||||
export SYMBOLS="BTC/USDT:USDT"
|
||||
export TIMEFRAMES="1m,1h,1d"
|
||||
|
||||
docker compose down
|
||||
cd /Users/jack/Project/freqtrade
|
||||
uvicorn user_data.Chan.datasvc.app.main:app --reload
|
||||
```
|
||||
|
||||
## 接口说明
|
||||
- GET /api/candles
|
||||
- 参数：symbol, tf, start(ms), end(ms)
|
||||
- 返回：[{timestamp, open, high, low, close, volume}]
|
||||
- WS /ws
|
||||
- 参数：symbol, tf, since(ms)
|
||||
- 消息：
|
||||
- snapshot: 初始快照数组
|
||||
- upsert: 单根K线增量（尾部修正）
|
||||
关闭时 Ctrl+C 即可，服务会自动取消后台抓取任务并释放资源。
|
||||
|
||||
## 注意
|
||||
- 默认未带交易所 API Key，仅公共行情。
|
||||
- 如需更多交易对/周期，修改 `docker-compose.yml` 后重启。
|
||||
---
|
||||
|
||||
## 3. 数据存储与聚合
|
||||
|
||||
### 3.1 基础周期
|
||||
只会为 `TIMEFRAMES` 声明的基础周期创建抓取任务（例如 `1m / 1h / 1d`）。
|
||||
|
||||
### 3.2 衍生周期
|
||||
启动后自动维护以下聚合：
|
||||
|
||||
| 基础周期 | 自动生成 |
|
||||
| --- | --- |
|
||||
| `1m` | `2m, 3m, 4m, 5m, 10m, 15m, 20m, 25m, 30m` |
|
||||
| `1h` | `2h, 3h, 4h, 6h, 8h, 12h, 16h` |
|
||||
| `1d` | `2d, 3d, 4d, 5d, 6d` |
|
||||
| `1w` | `2w` |
|
||||
| `1M` | `2M, 3M, 6M` |
|
||||
|
||||
聚合过程通过 `technical.util.resample_to_interval` 完成，写入同一 Parquet 数据目录。
|
||||
所有周期都可以被 REST/WS 访问。
|
||||
|
||||
### 3.3 数据目录
|
||||
```
|
||||
{DATA_DIR}/{timeframe}/{symbol}.parquet
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 接口调用
|
||||
|
||||
### 4.1 健康检查
|
||||
```
|
||||
GET /health
|
||||
```
|
||||
返回运行状态、基础/衍生周期列表、各抓取任务的最新进度与错误计数，便于监控。
|
||||
|
||||
### 4.2 REST API
|
||||
```
|
||||
GET /api/candles?symbol=BTC/USDT:USDT&tf=2h&start=1700000000000&end=1700003600000
|
||||
```
|
||||
参数说明：
|
||||
- `symbol`：交易对（必须在 `SYMBOLS` 列表中）
|
||||
- `tf`：时间周期（支持基础或衍生）
|
||||
- `start` / `end`：毫秒时间戳，可选
|
||||
|
||||
返回示例：
|
||||
```json
|
||||
[
|
||||
{"timestamp": 1700000000000, "open": 36000.0, "high": 36120.0, "low": 35980.0, "close": 36050.0, "volume": 125.4},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
### 4.3 WebSocket
|
||||
```
|
||||
ws://localhost:8000/ws?symbol=ETH/USDT:USDT&tf=15m&since=1700000000000
|
||||
```
|
||||
- 首次连接：收到 `snapshot` 消息（快照数组）
|
||||
- 后续增量：收到 `upsert` 消息（最新几根K线），以及周期性 `ping`
|
||||
|
||||
消息示例：
|
||||
```json
|
||||
{"topic":"candles.ETH/USDT:USDT.15m","type":"snapshot","data":[{"t":1700000000000,"o":2000.0,"h":2005.0,"l":1995.0,"c":2002.5,"v":312.7}, ...]}
|
||||
{"topic":"candles.ETH/USDT:USDT.15m","type":"upsert","data":{"t":1700000900000,"o":2002.5,"h":2006.0,"l":2000.0,"c":2004.0,"v":120.8}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 停机与维护
|
||||
|
||||
- **正常关闭**：`docker compose down` 或 Ctrl+C。服务会等待所有抓取任务结束并关闭 `ccxt` 客户端。
|
||||
- **异常恢复**：若网络异常，服务会自动指数退避重试；可通过 `/health` 的 `consecutive_errors` 与 `last_error` 排查。
|
||||
- **数据清理**：直接删除 `DATA_DIR` 下对应的 Parquet 文件即可，下次启动会重新回补。
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见问题
|
||||
|
||||
1. **缺少 `technical` 模块**
|
||||
聚合周期会跳过，并在日志中提示；先执行 `pip install technical` 再重启。
|
||||
|
||||
2. **接收不到某个周期的数据**
|
||||
确认该周期在 `TIMEFRAMES` 或自动聚合列表中；若是衍生周期，需要确保对应基础周期已在运行。
|
||||
|
||||
3. **如何新增交易对/周期**
|
||||
修改环境变量或 docker-compose 配置后，重启服务即可；Parquet 文件会按需生成。
|
||||
|
||||
---
|
||||
|
||||
欢迎结合自身策略或可视化前端直接消费本地数据服务。若要集成到其他项目，可直接引用 `/api/candles` 的 JSON 响应或订阅 `/ws` 的实时推送。
|
||||
|
||||
Reference in New Issue
Block a user