dekun
378 lines
10 KiB
Markdown
378 lines
10 KiB
Markdown
# 部署说明 — 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、日 K 缓存） |
|
||
| Python | 3.10+；**PM2 部署必须使用项目内 `.venv`** 安装依赖 |
|
||
|
||
---
|
||
|
||
## 二、部署前准备
|
||
|
||
```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=21450
|
||
|
||
# 今日每 4 小时自动刷新（另支持 Web 页脚手动刷新）
|
||
REFRESH_MINUTES=240
|
||
|
||
# 代理默认关闭
|
||
PROXY_ENABLED=false
|
||
PROXY_URL=socks5h://192.168.8.4:1081
|
||
PROXY_FOR=binance
|
||
```
|
||
|
||
完整变量说明见仓库 [`.env.example`](./.env.example) 与 [README.md](./README.md)。
|
||
|
||
---
|
||
|
||
## 二点五、Python 依赖与虚拟环境（重要）
|
||
|
||
本项目 **所有 Python 依赖** 均来自 `backend/requirements.txt`。
|
||
|
||
| 部署方式 | 依赖安装位置 | 说明 |
|
||
|----------|--------------|------|
|
||
| **PM2** | 项目目录 **`.venv`** | `deploy/pm2-deploy.sh` 自动 `python3 -m venv .venv` 并 `pip install -r backend/requirements.txt`；PM2 使用 `.venv/bin/python` 启动 |
|
||
| **Docker** | 镜像内 | `Dockerfile` 构建时 `pip install`，无需在宿主机建 venv |
|
||
| **本机调试** | 建议同样使用 `.venv` | 与生产一致，避免「系统 Python 有包、PM2 进程没有」 |
|
||
|
||
### PM2：手动安装 / 更新依赖
|
||
|
||
```bash
|
||
cd /opt/Binance_Altcoin_Monitor
|
||
|
||
# 若尚无虚拟环境
|
||
python3 -m venv .venv
|
||
|
||
# 依赖必须装进 .venv（不要只用系统 pip）
|
||
.venv/bin/pip install -U pip
|
||
.venv/bin/pip install -r backend/requirements.txt
|
||
|
||
pm2 restart binance-altcoin-monitor
|
||
```
|
||
|
||
### 验证依赖是否装在 venv 内
|
||
|
||
```bash
|
||
.venv/bin/python -c "import fastapi; print('ok')"
|
||
```
|
||
|
||
若报 `No module named ...`，说明未在 **`.venv`** 中安装，请执行上节 `pip install` 后重启 PM2。
|
||
|
||
### Docker：更新依赖
|
||
|
||
修改 `requirements.txt` 后需 **重新构建镜像**（见第十节），容器内才会包含新包。
|
||
|
||
---
|
||
|
||
## 三、方式 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
|
||
sed -i 's/\r$//' deploy/*.sh
|
||
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:21450/api/push/test
|
||
|
||
```
|
||
|
||
### 3.4 访问 Web
|
||
|
||
浏览器打开：`http://服务器IP:21450`
|
||
|
||
若前面有 Nginx，可反代到 21450 端口。
|
||
|
||
---
|
||
|
||
## 四、方式 B — PM2 一键部署
|
||
|
||
### 4.1 安装系统软件
|
||
|
||
```bash
|
||
# Python 3.10+（部署脚本会自动创建 .venv 并把 requirements 装进 venv）
|
||
sudo apt install -y python3 python3-venv python3-pip
|
||
|
||
# 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
|
||
```
|
||
|
||
> **注意**：业务依赖（`fastapi`、`httpx` 等）**不要**只执行 `sudo pip install`，应交给脚本或 `.venv/bin/pip`（见 **二点五**）。
|
||
|
||
### 4.2 一键部署
|
||
|
||
```bash
|
||
cd /opt/Binance_Altcoin_Monitor
|
||
sed -i 's/\r$//' deploy/*.sh # 若从 Windows 克隆，先去掉 CRLF
|
||
chmod +x deploy/pm2-deploy.sh
|
||
./deploy/pm2-deploy.sh
|
||
```
|
||
|
||
脚本将：拉取代码 → **创建/更新 `.venv`** → `pip install -r backend/requirements.txt` → `pm2 start`（解释器为 `.venv/bin/python`）。
|
||
|
||
### 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:21450/api/refresh/today -X POST
|
||
curl http://127.0.0.1:21450/api/today/top30
|
||
```
|
||
|
||
---
|
||
|
||
## 六、防火墙与 Nginx（可选）
|
||
|
||
```bash
|
||
# 开放 21450（若直接对外）
|
||
sudo ufw allow 21450/tcp
|
||
```
|
||
|
||
Nginx 反代示例：
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name monitor.example.com;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:21450;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、定时任务说明
|
||
|
||
| 时间（北京时间） | 行为 |
|
||
|------------------|------|
|
||
| 08:00 | 固化昨日、前日周期快照 |
|
||
| 08:10 | 企业微信推送 **三日 Top30 交集**（卡片列表，非宽表格） |
|
||
| 每 4 小时（0/4/8/12/16/20 点） | 刷新今日数据（`REFRESH_MINUTES=240`） |
|
||
|
||
Web 今日表 **不会** 每 60 秒自动轮询；除上述定时外，使用页脚 **「立即刷新今日」** 手动更新。
|
||
|
||
**进程需常驻**（Docker `restart: unless-stopped` 或 PM2 `autorestart`）。
|
||
|
||
---
|
||
|
||
## 八、目录与数据
|
||
|
||
```
|
||
/opt/Binance_Altcoin_Monitor/
|
||
├── .env # 配置（勿提交 git）
|
||
├── .venv/ # Python 虚拟环境（PM2 专用，勿删）
|
||
├── data/monitor.db # SQLite（周期快照、日 K、资金费率）
|
||
├── logs/ # PM2 日志（Docker 用 docker compose logs）
|
||
├── deploy/ # 一键脚本
|
||
├── docker-compose.yml
|
||
└── ecosystem.config.cjs # PM2 解释器: .venv/bin/python
|
||
```
|
||
|
||
备份建议：定期备份 `data/monitor.db` 与 `.env`。
|
||
|
||
---
|
||
|
||
## 九、更新版本
|
||
|
||
拉取代码后，**务必**按部署方式重装 Python 依赖（`requirements.txt` 有变更时）。
|
||
|
||
**Docker：**
|
||
|
||
```bash
|
||
cd /opt/Binance_Altcoin_Monitor
|
||
git pull
|
||
docker compose build --no-cache
|
||
docker compose up -d
|
||
```
|
||
|
||
**PM2（推荐一键脚本，会自动更新 .venv）：**
|
||
|
||
```bash
|
||
cd /opt/Binance_Altcoin_Monitor
|
||
git pull
|
||
./deploy/pm2-deploy.sh
|
||
```
|
||
|
||
**PM2（仅手动更新依赖）：**
|
||
|
||
```bash
|
||
cd /opt/Binance_Altcoin_Monitor
|
||
git pull
|
||
.venv/bin/pip install -r backend/requirements.txt
|
||
pm2 restart binance-altcoin-monitor
|
||
```
|
||
|
||
---
|
||
|
||
## 十、故障排查
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| `bash\r: No such file or directory` | 脚本为 Windows 换行，执行：`sed -i 's/\r$//' deploy/*.sh && chmod +x deploy/*.sh` |
|
||
| `cannot pull with rebase: unstaged changes` | 执行 `git stash` 后重试；或 `DEPLOY_SKIP_GIT_PULL=1 ./deploy/pm2-deploy.sh` 跳过拉取 |
|
||
| `No module named pip` | 执行 `sudo apt install -y python3-venv` 后重新 `./deploy/pm2-deploy.sh`（脚本会用 .venv） |
|
||
| `No module named ...` | 依赖未装进 **`.venv`**：执行 `.venv/bin/pip install -r backend/requirements.txt` 后 `pm2 restart` |
|
||
| Web 无数据 | 检查能否访问币安；国内服务器尝试 `PROXY_ENABLED=true` |
|
||
| 大量 `418 I'm a teapot` | IP 被封禁；**不要反复 restart**。日 K 已存 SQLite，图表优先读本地；仅过期或首次才请求币安 |
|
||
| 企微收不到 | 检查 `WECOM_WEBHOOK_URL`；`curl -X POST .../api/push/test` |
|
||
| 08:10 未推送 | 确认容器/PM2 在 08:10 前已运行；查日志 |
|
||
| 端口占用 | `ss -tlnp \| grep 21450` 或改 `.env` 中 `PORT` |
|
||
| Docker 代理连不上 | 确认 `192.168.8.4:1081` 从容器内可达，必要时改宿主机 IP |
|
||
|
||
---
|
||
|
||
## 十一、快速命令速查
|
||
|
||
```bash
|
||
# Docker 一键
|
||
./deploy/docker-deploy.sh
|
||
|
||
# PM2 一键（含 .venv 依赖安装）
|
||
./deploy/pm2-deploy.sh
|
||
|
||
# 仅更新 Python 依赖（PM2）
|
||
.venv/bin/pip install -r backend/requirements.txt && pm2 restart binance-altcoin-monitor
|
||
|
||
# 开启代理 / 修改 .env 后重启
|
||
# Docker: docker compose up -d --force-recreate
|
||
# PM2: pm2 restart binance-altcoin-monitor
|
||
```
|