KlineProxy

加密货币K线数据代理服务，用于代理和缓存币安(Binance)和OKX交易所的现货和期货市场数据。

📖 目录

• 项目简介
• 快速开始
• API 端点说明
• Python 集成
• 部署运维
• 常见问题
• 配置说明
• 相关链接

---

项目简介

核心定位

• 数据代理中间层: 作为客户端应用与交易所API之间的中间层
• 性能优化服务: 通过WebSocket实时订阅和本地缓存减少对交易所API的直接请求
• 限流保护: 防止触发交易所API的访问频率限制
• 量化交易支持: 为量化交易系统提供高性能的市场数据接口

核心功能

• 🔄 API代理 - 代理币安和OKX的现货、期货市场REST API
• ⚡ 实时数据 - WebSocket实时订阅K线和行情数据
• 💾 本地缓存 - Caffeine缓存减少API请求
• 🛡️ 限流保护 - 自动限流防止API封禁
• 📊 监控指标 - Prometheus监控端点
• 🔌 兼容CCXT - 兼容主流量化交易库
• 🌐 多交易所 - 支持Binance和OKX (SPOT/SWAP/FUTURES)

技术栈

组件	技术	版本
核心框架	Spring Boot	3.1.5
Web服务器	Undertow	-
WebSocket	Netty	4.1.90
HTTP客户端	Retrofit2	2.9.0
缓存	Caffeine	3.1.8
限流	Resilience4j	2.2.0
监控	Micrometer + Prometheus	-

适用场景

• ✅ 量化交易数据源
• ✅ 市场行情监控
• ✅ 数据分析和回测
• ✅ API限流保护
• ✅ 多系统数据共享

---

快速开始

环境要求

必需环境:

• Java: 17+
• Maven: 3.6+
• 内存: 至少512MB可用内存
• 网络: 可访问币安API和OKX API（中国大陆需要代理）

网络测试:

# 测试币安连接
curl -I https://api.binance.com/api/v3/time

# 测试OKX连接
curl -I https://www.okx.com

# 如果失败，使用代理测试
curl -x http://127.0.0.1:7893 -I https://api.binance.com/api/v3/time

构建项目

# 克隆项目（如果需要）
git clone https://github.com/flamhaze5946/klineproxy.git
cd klineproxy

# 构建
mvn clean package -DskipTests

预期输出:

[INFO] BUILD SUCCESS
[INFO] Total time: 4-6 seconds

生成文件: target/kline-proxy-1.6.0.jar

启动服务

方式1: 使用启动脚本（推荐）

# 赋予执行权限
chmod +x start.sh stop.sh

# 启动服务（后台运行）
./start.sh

# 停止服务
./stop.sh

脚本特性:

• 自动检查代理端口
• 自动编译jar（如果不存在）
• 检测并停止旧进程
• 支持前台/后台运行
• 健康检查（12次重试，每次5秒）

环境变量配置:

# 前台运行
RUN_MODE=foreground ./start.sh

# 自定义代理
PROXY_HOST=127.0.0.1 PROXY_PORT=7890 ./start.sh

# 自定义日志文件
LOG_FILE=my_app.log ./start.sh

方式2: 手动启动（无代理环境）

java -Xms256m -Xmx1024m -jar target/kline-proxy-1.6.0.jar

方式3: 手动启动（使用代理）

# 设置代理环境变量
export http_proxy=http://127.0.0.1:7893
export https_proxy=http://127.0.0.1:7893

# 启动服务（后台运行）
nohup java -Xms256m -Xmx1024m \
  -Dhttp.proxyHost=127.0.0.1 \
  -Dhttp.proxyPort=7893 \
  -Dhttps.proxyHost=127.0.0.1 \
  -Dhttps.proxyPort=7893 \
  -DsocksProxyHost=127.0.0.1 \
  -DsocksProxyPort=7891 \
  -jar target/kline-proxy-1.6.0.jar > klineproxy.log 2>&1 &

JVM参数说明:

• -Xms256m - 初始堆内存
• -Xmx1024m - 最大堆内存（可根据需要调整）
• -Dhttp.proxyHost - HTTP代理地址
• -Dhttp.proxyPort - HTTP代理端口

验证部署

# 等待服务启动（约30-60秒）
sleep 45

# 1. 健康检查
curl http://localhost:1888/actuator/health
# 期望: {"status":"UP"}

# 2. 测试币安API
curl "http://localhost:1888/api/v3/ticker/price?symbol=BTCUSDT"

# 3. 测试OKX API
curl "http://localhost:1888/okx/api/v5/market/time"

# 4. 运行测试脚本
python3 test_binance.py     # Binance测试
python3 test_okx.py          # OKX测试

5分钟上手示例

# 1. 快速构建和启动
mvn clean package -DskipTests && ./start.sh

# 2. 等待服务就绪
sleep 60

# 3. 获取BTC价格
curl "http://localhost:1888/api/v3/ticker/price?symbol=BTCUSDT"

# 4. 获取K线数据
curl "http://localhost:1888/api/v3/klines?symbol=BTCUSDT&interval=1d&limit=3"

# 5. 获取OKX数据
curl "http://localhost:1888/okx/api/v5/market/ticker/price?symbol=BTC-USDT"

---

API 端点说明

服务地址: http://localhost:1888

Binance 现货市场 (Spot)

基础路径: /api/v3/

端点	方法	说明	示例
/exchangeInfo	GET	交易所信息	-
/time	GET	服务器时间	-
/ticker/24hr	GET	24小时行情	?symbol=BTCUSDT
/ticker/price	GET	最新价格	?symbol=BTCUSDT
/klines	GET	K线数据	?symbol=BTCUSDT&interval=1d&limit=100

K线参数说明:

• symbol: 交易对（如 BTCUSDT）
• interval: 时间间隔（1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M）
• limit: 返回数量（默认500，最大1000）
• startTime: 起始时间戳（可选）
• endTime: 结束时间戳（可选）

示例:

# 获取交易所信息
curl http://localhost:1888/api/v3/exchangeInfo

# 获取服务器时间
curl http://localhost:1888/api/v3/time

# 获取BTC最新价格
curl "http://localhost:1888/api/v3/ticker/price?symbol=BTCUSDT"

# 获取24小时行情（单个）
curl "http://localhost:1888/api/v3/ticker/24hr?symbol=BTCUSDT"

# 获取24小时行情（所有）
curl "http://localhost:1888/api/v3/ticker/24hr"

# 获取日K线（最近7天）
curl "http://localhost:1888/api/v3/klines?symbol=BTCUSDT&interval=1d&limit=7"

# 获取小时K线（指定时间范围）
curl "http://localhost:1888/api/v3/klines?symbol=BTCUSDT&interval=1h&startTime=1764226064715&endTime=1764312464715&limit=100"

Binance 期货市场 (Futures)

基础路径: /fapi/v1/

端点	方法	说明	示例
/exchangeInfo	GET	期货交易所信息	-
/time	GET	服务器时间	-
/fundingRate	GET	资金费率	-
/premiumIndex	GET	溢价指数	?symbol=BTCUSDT
/ticker/24hr	GET	24小时行情	?symbol=BTCUSDT
/ticker/price	GET	期货价格	?symbol=BTCUSDT
/klines	GET	期货K线	?symbol=BTCUSDT&interval=1d&limit=100

示例:

# 获取期货交易所信息
curl http://localhost:1888/fapi/v1/exchangeInfo

# 获取资金费率
curl http://localhost:1888/fapi/v1/fundingRate

# 获取溢价指数（单个）
curl "http://localhost:1888/fapi/v1/premiumIndex?symbol=BTCUSDT"

# 获取溢价指数（所有）
curl "http://localhost:1888/fapi/v1/premiumIndex"

# 获取期货价格
curl "http://localhost:1888/fapi/v1/ticker/price?symbol=BTCUSDT"

# 获取期货K线
curl "http://localhost:1888/fapi/v1/klines?symbol=BTCUSDT&interval=1d&limit=10"

OKX 现货市场 (Spot)

基础路径: /okx/api/v5/market/

端点	方法	说明	示例
/exchangeInfo	GET	交易所信息	-
/time	GET	服务器时间	-
/ticker/24hr	GET	24小时行情	?symbol=BTC-USDT
/ticker/price	GET	最新价格	?symbol=BTC-USDT
/klines	GET	K线数据	?symbol=BTC-USDT&interval=1h&limit=100

交易对格式: BTC-USDT, ETH-USDT, BNB-USDT 等（注意使用 - 分隔）

支持的报价货币: USDT, USDC, BTC

示例:

# 获取OKX现货交易所信息
curl http://localhost:1888/okx/api/v5/market/exchangeInfo

# 获取服务器时间
curl http://localhost:1888/okx/api/v5/market/time

# 获取BTC-USDT价格
curl "http://localhost:1888/okx/api/v5/market/ticker/price?symbol=BTC-USDT"

# 获取24小时行情
curl "http://localhost:1888/okx/api/v5/market/ticker/24hr?symbol=BTC-USDT"

# 获取K线数据
curl "http://localhost:1888/okx/api/v5/market/klines?symbol=BTC-USDT&interval=1h&limit=10"

OKX 合约市场 (SWAP/FUTURES)

基础路径: /okx/api/v5/futures/

端点	方法	说明	示例
/exchangeInfo	GET	交易所信息（含SWAP和FUTURES）	-
/time	GET	服务器时间	-
/ticker/24hr	GET	24小时行情	?symbol=BTC-USDT-SWAP
/ticker/price	GET	合约价格	?symbol=BTC-USDT-SWAP
/klines	GET	合约K线	?symbol=BTC-USDT-SWAP&interval=1h&limit=100

交易对格式:

• 永续合约 (SWAP): BTC-USDT-SWAP, ETH-USDT-SWAP
• 交割合约 (FUTURES): BTC-USDT-250328, ETH-USDT-250625

示例:

# 获取合约交易所信息
curl http://localhost:1888/okx/api/v5/futures/exchangeInfo

# 获取永续合约价格
curl "http://localhost:1888/okx/api/v5/futures/ticker/price?symbol=BTC-USDT-SWAP"

# 获取永续合约K线
curl "http://localhost:1888/okx/api/v5/futures/klines?symbol=BTC-USDT-SWAP&interval=1h&limit=10"

# 获取交割合约K线
curl "http://localhost:1888/okx/api/v5/futures/klines?symbol=BTC-USDT-250328&interval=1h&limit=10"

监控端点

端点	方法	说明
/actuator/health	GET	健康检查
/actuator/prometheus	GET	Prometheus指标
/actuator/info	GET	应用信息

示例:

# 健康检查
curl http://localhost:1888/actuator/health

# Prometheus指标
curl http://localhost:1888/actuator/prometheus

# 应用信息
curl http://localhost:1888/actuator/info

---

Python 集成

方式1: 使用 requests 库

基础封装:

import requests
import json

class KlineProxyClient:
    def __init__(self, base_url="http://localhost:1888"):
        self.base_url = base_url
        self.session = requests.Session()

    def get_server_time(self):
        """获取服务器时间"""
        response = self.session.get(f"{self.base_url}/api/v3/time")
        return response.json()

    def get_price(self, symbol):
        """获取最新价格"""
        response = self.session.get(
            f"{self.base_url}/api/v3/ticker/price",
            params={"symbol": symbol}
        )
        return response.json()

    def get_24hr_ticker(self, symbol=None):
        """获取24小时价格变动"""
        params = {"symbol": symbol} if symbol else {}
        response = self.session.get(
            f"{self.base_url}/api/v3/ticker/24hr",
            params=params
        )
        return response.json()

    def get_klines(self, symbol, interval, limit=100, start_time=None, end_time=None):
        """获取K线数据"""
        params = {
            "symbol": symbol,
            "interval": interval,
            "limit": limit
        }
        if start_time:
            params["startTime"] = start_time
        if end_time:
            params["endTime"] = end_time

        response = self.session.get(
            f"{self.base_url}/api/v3/klines",
            params=params
        )
        return response.json()

# 使用示例
if __name__ == "__main__":
    client = KlineProxyClient()

    # 获取BTC价格
    price = client.get_price("BTCUSDT")
    print(f"BTC当前价格: ${price['price']}")

    # 获取24小时行情
    ticker = client.get_24hr_ticker("BTCUSDT")
    print(f"24小时涨跌幅: {ticker['priceChangePercent']}%")

    # 获取日K线数据
    klines = client.get_klines("BTCUSDT", "1d", limit=7)
    print(f"获取到 {len(klines)} 根K线")

方式2: 使用 CCXT 库（推荐）

配置示例:

import ccxt
import pandas as pd

# 配置KlineProxy作为币安代理
exchange = ccxt.binance({
    'urls': {
        'api': {
            'public': 'http://localhost:1888/api/v3',
            'fapiPublic': 'http://localhost:1888/fapi/v1'
        }
    },
    'enableRateLimit': False,  # 已经有代理限流
})

# 示例1: 获取BTC价格
btc_ticker = exchange.fetch_ticker('BTC/USDT')
print(f"BTC价格: {btc_ticker['last']}")

# 示例2: 获取OHLCV数据
ohlcv = exchange.fetch_ohlcv('BTC/USDT', timeframe='1d', limit=30)
df = pd.DataFrame(ohlcv, columns=['timestamp', 'open', 'high', 'low', 'close', 'volume'])
df['date'] = pd.to_datetime(df['timestamp'], unit='ms')
print(df.tail())

# 示例3: 批量获取多个交易对价格
symbols = ['BTC/USDT', 'ETH/USDT', 'BNB/USDT']
for symbol in symbols:
    ticker = exchange.fetch_ticker(symbol)
    print(f"{symbol}: ${ticker['last']}")

# 示例4: 获取期货数据
future_ohlcv = exchange.fapiPublicGetKlines({
    'symbol': 'BTCUSDT',
    'interval': '1h',
    'limit': 24
})
print(f"获取到 {len(future_ohlcv)} 根期货K线")

方式3: Pandas 数据分析

import requests
import pandas as pd
from datetime import datetime

def get_klines_dataframe(symbol, interval, limit=100):
    """获取K线数据并转换为DataFrame"""
    url = "http://localhost:1888/api/v3/klines"
    params = {
        "symbol": symbol,
        "interval": interval,
        "limit": limit
    }

    response = requests.get(url, params=params)
    klines = response.json()

    # 转换为DataFrame
    df = pd.DataFrame(klines, columns=[
        'open_time', 'open', 'high', 'low', 'close', 'volume',
        'close_time', 'quote_volume', 'trades', 'taker_buy_base',
        'taker_buy_quote'
    ])

    # 数据类型转换
    df['open_time'] = pd.to_datetime(df['open_time'], unit='ms')
    df['close_time'] = pd.to_datetime(df['close_time'], unit='ms')

    for col in ['open', 'high', 'low', 'close', 'volume']:
        df[col] = df[col].astype(float)

    df['trades'] = df['trades'].astype(int)

    return df

# 使用示例
if __name__ == "__main__":
    # 获取BTC日线数据
    df_btc = get_klines_dataframe('BTCUSDT', '1d', limit=30)

    print("BTC日线统计:")
    print(df_btc[['open_time', 'open', 'high', 'low', 'close', 'volume']].tail())

    # 计算技术指标
    df_btc['ma7'] = df_btc['close'].rolling(window=7).mean()
    df_btc['ma30'] = df_btc['close'].rolling(window=30).mean()

    # 计算涨跌幅
    df_btc['change'] = df_btc['close'].pct_change() * 100

    print(f"\n最新价格: ${df_btc['close'].iloc[-1]:.2f}")
    print(f"7日均线: ${df_btc['ma7'].iloc[-1]:.2f}")
    print(f"今日涨跌: {df_btc['change'].iloc[-1]:.2f}%")

方式4: 实时监控脚本

import requests
import time
from datetime import datetime

def monitor_prices(symbols, interval=5):
    """实时监控多个交易对价格"""
    base_url = "http://localhost:1888"

    while True:
        try:
            print(f"\n{'='*60}")
            print(f"更新时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
            print(f"{'='*60}")

            for symbol in symbols:
                # 获取价格和24小时数据
                ticker_response = requests.get(
                    f"{base_url}/api/v3/ticker/24hr",
                    params={"symbol": symbol},
                    timeout=5
                )

                if ticker_response.status_code == 200:
                    ticker = ticker_response.json()

                    price = float(ticker['lastPrice'])
                    change = float(ticker['priceChangePercent'])
                    volume = float(ticker['volume'])

                    # 颜色标记涨跌
                    color = "🟢" if change > 0 else "🔴" if change < 0 else "⚪"

                    print(f"{color} {symbol:10s} | "
                          f"价格: ${price:12,.2f} | "
                          f"涨跌: {change:6.2f}% | "
                          f"成交量: {volume:12,.2f}")
                else:
                    print(f"❌ {symbol}: 获取数据失败")

            # 等待下一次更新
            time.sleep(interval)

        except KeyboardInterrupt:
            print("\n监控已停止")
            break
        except Exception as e:
            print(f"错误: {e}")
            time.sleep(interval)

# 使用示例
if __name__ == "__main__":
    # 监控的交易对列表
    watch_symbols = [
        'BTCUSDT',
        'ETHUSDT',
        'BNBUSDT',
        'SOLUSDT',
        'ADAUSDT'
    ]

    # 每5秒更新一次
    monitor_prices(watch_symbols, interval=5)

---

部署运维

服务管理

查看服务状态:

# 检查进程
ps aux | grep kline-proxy | grep -v grep

# 检查端口
netstat -tuln | grep 1888

# 健康检查
curl http://localhost:1888/actuator/health

# 查看详细状态（如果有PID文件）
if [ -f klineproxy.pid ]; then
    PID=$(cat klineproxy.pid)
    ps -p $PID -o pid,ppid,%cpu,%mem,etime,cmd
fi

日志管理:

# 实时查看日志
tail -f klineproxy.log

# 查看最近100行
tail -100 klineproxy.log

# 查找错误
grep -i error klineproxy.log

# 查看启动日志
grep "Started KlineProxyApplication" klineproxy.log

# 查看WebSocket状态
grep -i websocket klineproxy.log | tail -20

重启服务:

./stop.sh && sleep 3 && ./start.sh

性能监控

实时监控CPU和内存:

watch -n 5 'ps aux | grep kline-proxy | grep -v grep | awk "{print \"CPU: \"\$3\"%, MEM: \"\$4\"%\"}"'

监控API响应时间:

while true; do
    START=$(date +%s%N)
    curl -s http://localhost:1888/api/v3/time > /dev/null
    END=$(date +%s%N)
    ELAPSED=$((($END - $START) / 1000000))
    echo "$(date '+%H:%M:%S') - 响应时间: ${ELAPSED}ms"
    sleep 5
done

Prometheus指标:

# 查看所有指标
curl http://localhost:1888/actuator/prometheus

# 查看JVM内存使用
curl http://localhost:1888/actuator/metrics/jvm.memory.used

# 查看线程数
curl http://localhost:1888/actuator/metrics/jvm.threads.live

# 查看HTTP请求统计
curl http://localhost:1888/actuator/metrics/http.server.requests

日志轮转

方式1: 使用logrotate

创建 /etc/logrotate.d/klineproxy:

/data/cw/projects/KlineProxy/klineproxy.log {
    daily
    rotate 7
    compress
    delaycompress
    notifempty
    create 0644 cw cw
    missingok
}

方式2: 自定义脚本

创建 rotate_logs.sh:

#!/bin/bash
LOG_DIR="/data/cw/projects/KlineProxy"
LOG_FILE="klineproxy.log"
MAX_SIZE=100  # 100MB

cd $LOG_DIR

# 检查日志大小
SIZE=$(du -m $LOG_FILE 2>/dev/null | cut -f1)

if [ "$SIZE" -gt "$MAX_SIZE" ]; then
    # 备份旧日志
    TIMESTAMP=$(date +%Y%m%d_%H%M%S)
    mv $LOG_FILE "${LOG_FILE}.${TIMESTAMP}"

    # 压缩旧日志
    gzip "${LOG_FILE}.${TIMESTAMP}"

    # 删除7天前的日志
    find . -name "klineproxy.log.*.gz" -mtime +7 -delete

    echo "日志已轮转: ${LOG_FILE}.${TIMESTAMP}.gz"
fi

设置定时任务:

# 编辑crontab
crontab -e

# 添加每天凌晨2点执行日志轮转
0 2 * * * /data/cw/projects/KlineProxy/rotate_logs.sh

Systemd 服务配置（生产环境）

创建 /etc/systemd/system/klineproxy.service:

[Unit]
Description=KlineProxy Service
After=network.target

[Service]
Type=simple
User=cw
WorkingDirectory=/data/cw/projects/KlineProxy
Environment="JAVA_OPTS=-Xms512m -Xmx2048m"
Environment="http_proxy=http://127.0.0.1:7893"
Environment="https_proxy=http://127.0.0.1:7893"
ExecStart=/usr/bin/java $JAVA_OPTS \
  -Dhttp.proxyHost=127.0.0.1 \
  -Dhttp.proxyPort=7893 \
  -Dhttps.proxyHost=127.0.0.1 \
  -Dhttps.proxyPort=7893 \
  -DsocksProxyHost=127.0.0.1 \
  -DsocksProxyPort=7891 \
  -jar target/kline-proxy-1.6.0.jar
Restart=on-failure
RestartSec=10
StandardOutput=append:/data/cw/projects/KlineProxy/klineproxy.log
StandardError=append:/data/cw/projects/KlineProxy/klineproxy.log

[Install]
WantedBy=multi-user.target

使用方法:

# 重新加载systemd配置
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start klineproxy

# 设置开机自启
sudo systemctl enable klineproxy

# 查看状态
sudo systemctl status klineproxy

# 查看日志
sudo journalctl -u klineproxy -f

# 停止服务
sudo systemctl stop klineproxy

# 重启服务
sudo systemctl restart klineproxy

---

常见问题

1. 网络连接失败

症状: UnknownHostException: api.binance.com 或 Connection refused

原因: 无法直接访问币安API或OKX API

解决方案:

1. 检查网络连接:

   ping -c 3 api.binance.com
   curl -I https://api.binance.com/api/v3/time

2. 检查代理服务:

   # 检查代理端口是否监听
   netstat -tuln | grep 7893
   
   # 测试代理连接
   curl -x http://127.0.0.1:7893 -I https://api.binance.com/api/v3/time

3. 配置代理启动 (参见启动服务章节)

4. 重启代理服务 (如Clash):

   # 根据你的代理工具调整命令
   clash off
   clash on

2. 端口被占用

症状: Port 1888 was already in use

诊断:

# 查找占用进程
sudo lsof -i :1888
# 或
sudo netstat -tulnp | grep 1888

解决方案:

方案1: 停止占用进程

sudo kill <PID>

方案2: 使用其他端口

java -jar kline-proxy-1.6.0.jar --server.port=8888

3. WebSocket连接警告

症状: 日志中出现 websocket client not alive when subscribe topics

说明:

• 这是正常的初始化现象
• WebSocket需要5-10分钟建立连接
• REST API不受影响，完全正常工作

验证:

# 等待5-10分钟后测试K线数据
curl "http://localhost:1888/api/v3/klines?symbol=BTCUSDT&interval=1d&limit=3"

查看连接状态:

grep -i "websocket\|subscribe" klineproxy.log | tail -20

4. API返回空数据

症状: K线数据返回空数组 []，Ticker返回 {} 或空列表

原因:

• 应用刚启动，WebSocket还在同步数据
• WebSocket连接未建立

解决方案:

# 1. 等待5-10分钟让WebSocket建立连接
sleep 300

# 2. 查看日志确认同步状态
tail -f klineproxy.log | grep -i "subscribe\|websocket\|kline"

# 3. 检查健康状态
curl http://localhost:1888/actuator/health

# 4. 重新测试
curl "http://localhost:1888/api/v3/ticker/price?symbol=BTCUSDT"

5. 内存不足

症状:

• java.lang.OutOfMemoryError: Java heap space
• 应用运行一段时间后崩溃

查看内存使用:

ps aux | grep kline-proxy

解决方案:

增加堆内存:

# 修改start.sh中的-Xmx参数
# 或者手动启动时指定
java -Xms512m -Xmx2048m -jar target/kline-proxy-1.6.0.jar

优化配置: 减少缓存数量（编辑 src/main/resources/application.yaml）

kline:
  binance:
    spot:
      intervalSyncConfigs:
        "1h":
          minMaintainCount: 3000  # 从5000减少到3000
        "1d":
          minMaintainCount: 500   # 从1000减少到500

6. Binance/OKX WebSocket 错误

症状:

• Binance: 日志中出现 disconnected BinanceSpotWebSocketClient
• OKX: 错误 60018

原因: WebSocket endpoint 配置错误

解决方案: 确认 application.yaml 配置正确

ws:
  client:
    binanceSpot:
      url: wss://stream.binance.com/stream  # 必须是/stream
    binanceFuture:
      url: wss://fstream.binance.com/stream
    okxSpot:
      url: wss://ws.okx.com:8443/ws/v5/business  # 必须是/business
    okxFuture:
      url: wss://ws.okx.com:8443/ws/v5/business

验证修复: 重新构建和启动

mvn clean package -DskipTests
./stop.sh
./start.sh

快速诊断脚本

#!/bin/bash
echo "=== KlineProxy 诊断报告 ==="
echo ""

echo "1. 进程状态:"
if pgrep -f "kline-proxy" > /dev/null; then
    echo "✅ 进程运行中"
    ps aux | grep kline-proxy | grep -v grep | awk '{print "   CPU: "$3"%, MEM: "$4"%, PID: "$2}'
else
    echo "❌ 进程未运行"
fi

echo ""
echo "2. 端口状态:"
if netstat -tuln | grep -q 1888; then
    echo "✅ 端口1888正在监听"
else
    echo "❌ 端口1888未监听"
fi

echo ""
echo "3. 健康检查:"
HEALTH=$(curl -s http://localhost:1888/actuator/health 2>/dev/null)
if echo "$HEALTH" | grep -q "UP"; then
    echo "✅ 服务健康: $HEALTH"
else
    echo "❌ 健康检查失败"
fi

echo ""
echo "4. 网络连接:"
if curl -s -o /dev/null -w "%{http_code}" --max-time 5 https://api.binance.com/api/v3/time | grep -q "200"; then
    echo "✅ 可访问币安API"
else
    echo "⚠️  无法访问币安API (可能需要代理)"
fi

echo ""
echo "5. 最近错误 (最多5条):"
if [ -f klineproxy.log ]; then
    grep -i error klineproxy.log | tail -5
    [ $? -ne 0 ] && echo "✅ 无ERROR日志"
else
    echo "❌ 日志文件不存在"
fi

echo ""
echo "=== 诊断完成 ==="

---

配置说明

主配置文件

位置: src/main/resources/application.yaml

服务端口配置

server:
  port: 1888  # 服务端口，可根据需要修改

数字类型配置

number:
  type: double  # 数据精度类型
  # 可选值:
  # - string      # 原始字符串（最精确，但占用内存大）
  # - float       # 单精度浮点（节省内存）
  # - double      # 双精度浮点（推荐，平衡精度和性能）
  # - bigDecimal  # 高精度十进制（最精确，但性能开销大）

K线同步配置

Binance 现货配置示例:

kline:
  binance:
    spot:
      intervalSyncConfigs:
        "15m":  # 15分钟K线
          minMaintainCount: 3000  # 最少维护3000条K线
          listenSymbolPatterns:   # 订阅交易对规则
            - .*?USDT              # 所有USDT交易对
        "1h":   # 1小时K线
          minMaintainCount: 5000
          listenSymbolPatterns:
            - .*?USDT
        "4h":   # 4小时K线
          minMaintainCount: 2000
          listenSymbolPatterns:
            - .*?USDT
        "1d":   # 日线
          minMaintainCount: 1000
          listenSymbolPatterns:
            - .*?USDT

OKX 现货配置示例:

kline:
  okx:
    spot:
      intervalSyncConfigs:
        "15m":
          minMaintainCount: 3000
          listenSymbolPatterns:
            - .*?-USDT    # BTC-USDT, ETH-USDT等
            - .*?-USDC    # BTC-USDC等
            - .*?-BTC     # ETH-BTC等
        "1h":
          minMaintainCount: 5000
          listenSymbolPatterns:
            - .*?-USDT
            - .*?-USDC
            - .*?-BTC
        "4h":
          minMaintainCount: 2000
          listenSymbolPatterns:
            - .*?-USDT
        "1d":
          minMaintainCount: 1000
          listenSymbolPatterns:
            - .*?-USDT

OKX 合约配置示例:

kline:
  okx:
    future:
      intervalSyncConfigs:
        "1h":
          minMaintainCount: 5000
          listenSymbolPatterns:
            - .*?-USDT-SWAP        # 永续合约: BTC-USDT-SWAP
            - .*?-USDC-SWAP
            - .*?-BTC-SWAP
            - .*?-USDT-\d{6}       # 交割合约: BTC-USDT-250328
            - .*?-USDC-\d{6}

API 端点配置

client:
  binanceSpot:
    api:
      rootUrl: https://api.binance.com
  binanceFuture:
    api:
      rootUrl: https://fapi.binance.com
  okxSpot:
    api:
      rootUrl: https://www.okx.com
  okxFuture:
    api:
      rootUrl: https://www.okx.com

WebSocket 端点配置

ws:
  client:
    binanceSpot:
      url: wss://stream.binance.com/stream
    binanceFuture:
      url: wss://fstream.binance.com/stream
    okxSpot:
      url: wss://ws.okx.com:8443/ws/v5/business
    okxFuture:
      url: wss://ws.okx.com:8443/ws/v5/business

重要提示:

• Binance 必须使用 /stream 端点（支持多流订阅）
• OKX K线数据必须使用 /business 端点（/public 会返回错误60018）

监控配置

management:
  endpoint:
    prometheus:
      enabled: true
  endpoints:
    web:
      exposure:
        include: prometheus,health,info
  metrics:
    tags:
      application: ${spring.application.name}

配置修改后的重新构建

# 修改配置文件后需要重新构建
mvn clean package -DskipTests

# 重启服务
./stop.sh
./start.sh

配置优化建议

内存有限时 (< 2GB):

kline:
  binance:
    spot:
      intervalSyncConfigs:
        "1h":
          minMaintainCount: 3000  # 减少缓存
        "1d":
          minMaintainCount: 500
number:
  type: float  # 使用float减少内存占用

高精度需求时:

number:
  type: bigDecimal  # 使用BigDecimal获得最高精度

只监控特定交易对:

kline:
  binance:
    spot:
      intervalSyncConfigs:
        "1h":
          minMaintainCount: 5000
          listenSymbolPatterns:
            - ^BTC.*       # 只订阅BTC开头的交易对
            - ^ETH.*       # 只订阅ETH开头的交易对

---

相关链接

项目资源

• 项目仓库: https://github.com/flamhaze5946/klineproxy
• 技术文档: 项目分析.md

交易所API文档

• 币安现货API: https://binance-docs.github.io/apidocs/spot/cn/
• 币安期货API: https://binance-docs.github.io/apidocs/futures/cn/
• OKX API: https://www.okx.com/docs-v5/zh/
• OKX WebSocket: https://www.okx.com/docs-v5/zh/#websocket-api

量化交易库

• CCXT: https://docs.ccxt.com/
• Pandas: https://pandas.pydata.org/docs/

测试脚本

• Binance测试: test_binance.py
• OKX测试: test_okx.py

---

版本信息

当前版本: 1.6.0 更新日期: 2025-12-02 状态: ✅ 生产可用

主要特性:

• ✅ Binance 现货 + 期货完整支持
• ✅ OKX 现货 + 合约完整支持
• ✅ WebSocket 实时数据订阅
• ✅ REST API 数据代理
• ✅ 智能缓存和限流
• ✅ Prometheus 监控

版本历史:

• 1.6.0 (2025-12-02): OKX集成完成，WebSocket endpoint修复
• 1.5.0 (2025-11-28): 添加OKX基础支持
• 1.0.0: 初始版本，Binance支持

---

文档维护: Claude Code 最后更新: 2025-12-02 语言: 简体中文