Binance_Altcoin_Monitor/README.md

币安 U本位合约 · 日成交额 Top30 监控

仓库：Binance_Altcoin_Monitor

按 北京时间 08:00 切日，统计 U 本位永续合约成交额 Top30；每日 08:10 企业微信仅推送 三日 Top30 交集 币种（列表排版，非宽表格）；Web 数据统计页可预览同款推送内容。

Linux 生产部署（/opt、Docker、PM2、虚拟环境、SOCKS5 代理、大模型）请参阅 DEPLOY.md

功能

• 成交额排名 Top30（USDT 计价）
• 高亮标记（不改变排名）：成交额 ≥ 1000万 USDT、|涨跌幅| ≥ 5%
• 昨日 / 前日周期：按 08:00 切日固化快照
• 今日周期：[D 08:00, 当前)，后台每 4 小时自动刷新 + 页脚 手动刷新
• 日 K + 成交量迷你图，点击 全屏查看；K 线优先读服务端 SQLite，浏览器 localStorage 缓存约 1 小时
• 资金费率当前值 + 历史迷你曲线
• 数据统计：连续三日均为成交额 Top30 的 交集（涨跌幅 不限）
• 大模型解读（gemma4:e4b）：对三日交集币种生成日 K 图 + 数据简析；每日 08:05 自动排队，每币间隔 3 分钟；服务启动后自动跑一轮（可关）；需在 .env 配置 LLM_API_KEY

环境要求

• Python 3.10+（推荐项目内虚拟环境 .venv，PM2 生产亦使用 .venv）
• 可访问 fapi.binance.com（国内服务器可配 SOCKS5，见 DEPLOY.md）
• 企业微信群机器人 Webhook（可选，用于 08:10 推送）
• 大模型网关（可选）：默认 http://op.bz121.com，OpenAI 兼容 /v1/chat/completions

快速开始

Windows / 本机开发

# 1. 进入项目目录
cd 币安排名

# 2. 创建并激活虚拟环境（依赖必须装进 venv，勿只装系统 Python）
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 3. 安装依赖（含 matplotlib，用于服务端生成日 K 图供大模型）
pip install -U pip
pip install -r backend/requirements.txt

# 4. 配置环境变量
copy .env.example .env
# 编辑 .env：WECOM_WEBHOOK_URL、LLM_API_KEY 等

# 5. 启动（需保持进程常驻）
python run.py

Linux 本机（与生产一致）

cd /path/to/Binance_Altcoin_Monitor
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r backend/requirements.txt
cp .env.example .env
nano .env
.venv/bin/python run.py

浏览器打开：http://127.0.0.1:21450

生产环境请用 DEPLOY.md 中的 Docker 或 PM2 脚本；PM2 使用 .venv/bin/python，更新代码后需执行 .venv/bin/pip install -r backend/requirements.txt 再重启。

配置说明（.env）

变量	说明	默认
WECOM_WEBHOOK_URL	企业微信机器人地址	空（不推送）
TOP_N	排名数量	30
VOLUME_THRESHOLD	高亮成交额阈值 (USDT)	10000000
CHANGE_THRESHOLD	高亮涨跌幅阈值 (%)	5
REFRESH_MINUTES	今日自动刷新间隔（分钟）；240 = 每 4 小时	240
HOST / PORT	服务监听	0.0.0.0:21450
PROXY_ENABLED	是否启用 SOCKS5 代理	false
PROXY_URL	代理地址	socks5h://192.168.8.4:1081
PROXY_FOR	代理范围 binance/wecom/all	binance
MAX_CONCURRENCY	币安 K 线并发数（过大易 418 封禁）	3
CANDIDATE_POOL	预筛候选合约数（按 24h 成交额）	150
CHART_KLINE_LIMIT	日 K 存储/展示根数	300
CHART_CACHE_MINUTES	服务端日 K 视为新鲜的时间（分钟内不请求币安）	60
LLM_BASE_URL	大模型网关根地址	http://op.bz121.com
LLM_API_KEY	Bearer 密钥（sk-...，勿提交 git）	空
LLM_MODEL	模型 ID，须与网关一致	gemma4:e4b
LLM_SYMBOL_INTERVAL_SEC	批量解读时每币间隔（秒）	180
LLM_AUTO_ON_STARTUP	启动后是否自动跑一轮三日交集解读	true

完整示例见仓库根目录 .env.example。

API

方法	路径	说明
GET	/api/today/top30	今日周期 Top30
GET	/api/yesterday/top30	昨日周期 Top30
GET	/api/daybefore/top30	前日周期 Top30
GET	/api/stats/three-day	三日 Top30 交集统计
GET	/api/chart/{symbol}/daily	日 K JSON（SQLite 优先）
GET	/api/chart/{symbol}/daily.png	日 K PNG（大模型/预览）
GET	/api/funding/{symbol}/history	资金费率历史
GET	/api/llm/status	解读任务状态
GET	/api/llm/interpretations	最近一批解读结果
POST	/api/llm/interpret/run	手动启动三日交集解读队列
GET	/api/push/preview	预览企微推送（三日交集）
POST	/api/push/test	手动测试企业微信推送（仅交集币种）
POST	/api/refresh/today	立即刷新今日数据
POST	/api/refresh/yesterday	重新计算昨日快照

定时任务

时间 (北京时间)	任务
08:00	固化昨日、前日周期快照到 SQLite
08:05	大模型解读「三日 Top30 交集」各币种（需 LLM_API_KEY）
08:10	企业微信推送三日 Top30 交集（列表排版）
每 4 小时（整点 0/4/8/12/16/20）	刷新今日周期（由 REFRESH_MINUTES=240 控制）

进程重启后：若已过 08:10 且当日尚未推送成功，会自动补推；若已配置 LLM_API_KEY 且 LLM_AUTO_ON_STARTUP=true，会在后台自动启动一轮解读。

Web 界面

页签	说明
今日 / 昨日 / 前日	Top30 表、日 K、资金费率；支持排序与 CSV 导出
数据统计	三日交集列表 + 大模型解读区；可「开始解读」「刷新解读」

今日数据 不会 在浏览器里每 60 秒轮询；请依赖 4 小时后台任务或页脚 「立即刷新今日」。

Windows 常驻运行

1. 任务计划程序：触发器「登录时」或「计算机启动时」，操作运行 pythonw.exe 完整路径的 run.py，起始于项目目录。
2. 或使用云服务器 / VPS 用 nssm、pm2 等托管。

企业微信配置

1. 企业微信群 → 群设置 → 群机器人 → 添加
2. 复制 Webhook 地址到 .env 的 WECOM_WEBHOOK_URL
3. 启动后访问 POST http://127.0.0.1:21450/api/push/test 测试（可用 Postman 或 curl）

curl -X POST http://127.0.0.1:21450/api/push/test

数据说明

• 昨日 / 前日：按 08:00 切日，用 1h K 线聚合成交额
• 今日：默认 TODAY_DATA_MODE=ticker24h（单次 API，滚动 24h 口径）
• 涨跌幅 = (周期末价 - 周期开盘价) / 开盘价 × 100%
• 日 K：最多 300 根存 daily_klines；浏览器 localStorage 缓存周期表约 4 小时、K 线约 1 小时

依赖说明

所有 Python 包（含 matplotlib、fastapi、httpx 等）写在 backend/requirements.txt：

部署方式	安装位置
本机 / PM2	项目目录 .venv（pip install -r backend/requirements.txt）
Docker	镜像构建时 pip install（见 Dockerfile）

不要只装到系统 Python：PM2 的 ecosystem.config.cjs 指定解释器为 .venv/bin/python，系统环境缺包会导致 No module named matplotlib 等错误。

目录结构

币安排名/
├── backend/app/       # 后端逻辑（含 llm_service、chart_image）
├── backend/requirements.txt
├── web/               # 前端静态页
├── data/monitor.db    # SQLite（自动创建）
├── .venv/             # 虚拟环境（本地/PM2，勿提交）
├── deploy/            # 一键部署脚本
├── run.py             # 启动入口
└── .env               # 本地配置（勿提交）