first commit

2026-05-22 13:06:42 +08:00
commit af5c249cf8
27 changed files with 1741 additions and 0 deletions
@@ -0,0 +1,303 @@
+# 部署说明 — Binance Altcoin Monitor
+
+代码仓库：[https://git.bz121.com/dekun/Binance_Altcoin_Monitor.git](https://git.bz121.com/dekun/Binance_Altcoin_Monitor.git)
+
+生产环境推荐安装路径：**`/opt/Binance_Altcoin_Monitor`**
+
+支持两种一键部署方式：**Docker**、**PM2**（二选一即可）。
+
+---
+
+## 一、服务器要求
+
+| 项目 | 说明 |
+|------|------|
+| 系统 | Linux（推荐 Ubuntu 22.04+ / Debian 12+） |
+| 时区 | `Asia/Shanghai`（定时任务 08:00 / 08:10 北京时间） |
+| 网络 | 能访问 `fapi.binance.com`；若不能，需开启 SOCKS5 代理（见第四节） |
+| 内存 | 建议 ≥ 512MB |
+| 磁盘 | ≥ 500MB（含日志与 SQLite） |
+
+---
+
+## 二、部署前准备
+
+```bash
+# 1. 安装 git
+sudo apt update && sudo apt install -y git
+
+# 2. 克隆到 /opt（也可交给一键脚本自动完成）
+sudo mkdir -p /opt
+sudo git clone https://git.bz121.com/dekun/Binance_Altcoin_Monitor.git /opt/Binance_Altcoin_Monitor
+sudo chown -R $USER:$USER /opt/Binance_Altcoin_Monitor
+
+# 3. 配置环境变量
+cd /opt/Binance_Altcoin_Monitor
+cp .env.example .env
+nano .env   # 至少填写 WECOM_WEBHOOK_URL
+```
+
+`.env` 常用项：
+
+```env
+WECOM_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=你的key
+HOST=0.0.0.0
+PORT=8000
+
+# 代理默认关闭
+PROXY_ENABLED=false
+PROXY_URL=socks5h://192.168.8.4:1081
+PROXY_FOR=binance
+```
+
+---
+
+## 三、方式 A — Docker 一键部署（推荐）
+
+### 3.1 安装 Docker
+
+```bash
+# Ubuntu 示例
+curl -fsSL https://get.docker.com | sudo sh
+sudo usermod -aG docker $USER
+# 重新登录 shell 后生效
+```
+
+### 3.2 一键部署
+
+```bash
+cd /opt/Binance_Altcoin_Monitor
+chmod +x deploy/docker-deploy.sh
+./deploy/docker-deploy.sh
+```
+
+脚本将：克隆/更新代码 → 生成 `.env` → `docker compose build` → `docker compose up -d`。
+
+### 3.3 常用命令
+
+```bash
+cd /opt/Binance_Altcoin_Monitor
+
+# 查看状态
+docker compose ps
+
+# 查看日志
+docker compose logs -f
+
+# 重启（改 .env 后）
+docker compose up -d --force-recreate
+
+# 停止
+docker compose down
+
+# 手动测试企微推送
+curl -X POST http://127.0.0.1:8000/api/push/test
+```
+
+### 3.4 访问 Web
+
+浏览器打开：`http://服务器IP:8000`
+
+若前面有 Nginx，可反代到 8000 端口。
+
+---
+
+## 四、方式 B — PM2 一键部署
+
+### 4.1 安装依赖
+
+```bash
+# Python 3.10+
+sudo apt install -y python3 python3-pip python3-venv
+
+# Node.js + PM2
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+sudo npm install -g pm2
+```
+
+### 4.2 一键部署
+
+```bash
+cd /opt/Binance_Altcoin_Monitor
+chmod +x deploy/pm2-deploy.sh
+./deploy/pm2-deploy.sh
+```
+
+### 4.3 常用命令
+
+```bash
+pm2 status
+pm2 logs binance-altcoin-monitor
+pm2 restart binance-altcoin-monitor
+pm2 stop binance-altcoin-monitor
+
+# 开机自启（按 pm2 startup 提示执行 sudo 命令后）
+pm2 save
+```
+
+---
+
+## 五、SOCKS5 代理（默认关闭）
+
+当服务器**无法直连**币安 API 时，可通过内网 SOCKS5 代理访问。
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PROXY_ENABLED` | `false` | `true` 时启用代理 |
+| `PROXY_URL` | `socks5h://192.168.8.4:1081` | `socks5h` 表示由代理解析 DNS |
+| `PROXY_FOR` | `binance` | `binance` 仅币安；`wecom` 仅企微；`all` 全部 HTTP |
+
+### 如何开启
+
+1. 编辑 `/opt/Binance_Altcoin_Monitor/.env`：
+
+```env
+PROXY_ENABLED=true
+PROXY_URL=socks5h://192.168.8.4:1081
+PROXY_FOR=binance
+```
+
+2. 使配置生效：
+
+**Docker：**
+
+```bash
+cd /opt/Binance_Altcoin_Monitor
+docker compose up -d --force-recreate
+```
+
+**PM2：**
+
+```bash
+pm2 restart binance-altcoin-monitor
+```
+
+### 如何关闭
+
+```env
+PROXY_ENABLED=false
+```
+
+同样执行上面的重启命令。
+
+### 说明
+
+- **默认不走代理**，直连币安与企微。
+- 企微 Webhook 在国内一般可直连，建议 `PROXY_FOR=binance`，避免企微也走代理。
+- Docker 容器访问宿主机局域网代理时，`.env` 中 `PROXY_URL` 可改为宿主机 IP，例如 `socks5h://192.168.8.4:1081`（需保证容器网络能访问该地址）。
+- 依赖 `httpx[socks]`，Docker 镜像与 PM2 部署脚本已包含。
+
+### 验证代理是否生效
+
+```bash
+# 查看日志中是否有连接错误
+docker compose logs -f          # Docker
+pm2 logs binance-altcoin-monitor # PM2
+
+# 触发刷新，观察是否拉取到数据
+curl http://127.0.0.1:8000/api/refresh/today -X POST
+curl http://127.0.0.1:8000/api/today/top30
+```
+
+---
+
+## 六、防火墙与 Nginx（可选）
+
+```bash
+# 开放 8000（若直接对外）
+sudo ufw allow 8000/tcp
+```
+
+Nginx 反代示例：
+
+```nginx
+server {
+    listen 80;
+    server_name monitor.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+---
+
+## 七、定时任务说明
+
+| 时间（北京时间） | 行为 |
+|------------------|------|
+| 08:00 | 固化昨日周期数据 |
+| 08:10 | 企业微信推送昨日 Top30 |
+| 每 5 分钟 | 刷新今日数据（`REFRESH_MINUTES` 可改） |
+
+**进程需常驻**（Docker `restart: unless-stopped` 或 PM2 `autorestart`）。
+
+---
+
+## 八、目录与数据
+
+```
+/opt/Binance_Altcoin_Monitor/
+├── .env              # 配置（勿提交 git）
+├── data/monitor.db   # SQLite 数据
+├── logs/             # PM2 日志（Docker 用 docker compose logs）
+├── deploy/           # 一键脚本
+├── docker-compose.yml
+└── ecosystem.config.cjs
+```
+
+备份建议：定期备份 `data/monitor.db` 与 `.env`。
+
+---
+
+## 九、更新版本
+
+**Docker：**
+
+```bash
+cd /opt/Binance_Altcoin_Monitor
+git pull
+docker compose build --no-cache
+docker compose up -d
+```
+
+**PM2：**
+
+```bash
+cd /opt/Binance_Altcoin_Monitor
+git pull
+python3 -m pip install -r backend/requirements.txt -q
+pm2 restart binance-altcoin-monitor
+```
+
+---
+
+## 十、故障排查
+
+| 现象 | 处理 |
+|------|------|
+| Web 无数据 | 检查能否访问币安；国内服务器尝试 `PROXY_ENABLED=true` |
+| 企微收不到 | 检查 `WECOM_WEBHOOK_URL`；`curl -X POST .../api/push/test` |
+| 08:10 未推送 | 确认容器/PM2 在 08:10 前已运行；查日志 |
+| 端口占用 | `ss -tlnp \| grep 8000` 或改 `.env` 中 `PORT` |
+| Docker 代理连不上 | 确认 `192.168.8.4:1081` 从容器内可达，必要时改宿主机 IP |
+
+---
+
+## 十一、快速命令速查
+
+```bash
+# Docker 一键
+./deploy/docker-deploy.sh
+
+# PM2 一键
+./deploy/pm2-deploy.sh
+
+# 开启代理后重启
+# Docker:  docker compose up -d --force-recreate
+# PM2:     pm2 restart binance-altcoin-monitor
+```