# Ubuntu 服务器部署与环境说明

本文档为 **生产环境唯一推荐路径**:**Ubuntu**,**root** 用户,代码目录 **`/opt/crypto_monitor`**,进程托管 **PM2**.不使用 Windows 部署,不使用 systemd/screen/nohup 托管应用(SSH 隧道除外).

---

## 1. 系统要求

| 项 | 要求 |
|----|------|
| 操作系统 | **Ubuntu 22.04 LTS** 或 **24.04 LTS**(64 位) |
| 运行用户 | **root**(下文命令均按 root 编写) |
| 项目路径 | **`/opt/crypto_monitor`**(整仓克隆到此目录) |
| 进程管理 | **PM2**(全局安装,见 §3) |
| 网络 | 能 `git clone` 私有仓库;访问交易所不稳定时需 **SSH SOCKS**(见各所《部署文档》) |

---

## 2. Python 环境

| 项 | 说明 |
|----|------|
| **版本** | **Python 3.10 或 3.11**(`python3 --version` ≥ 3.10);脚本会拒绝 3.9 及以下 |
| **虚拟环境** | 每个子项目独立 **`.venv`**(`deploy/setup_env.sh` 自动创建) |
| **依赖文件** | 三所监控共用仓库根目录 **`requirements.txt`**;中控用 **`manual_trading_hub/requirements.txt`** |
| **SOCKS** | 走代理时必须安装 **PySocks**(已写入 requirements) |

### 2.1 系统包(root)

```bash
apt update
apt install -y python3 python3-pip python3-venv curl git ca-certificates
# 若 python3 为 3.10:
apt install -y python3.10-venv
# 若为 3.12:
apt install -y python3.12-venv
```

### 2.2 一键创建各目录 venv

```bash
cd /opt/crypto_monitor
bash deploy/setup_env.sh --install-system-deps
# 或已是 root 且已装 venv 包:
bash deploy/setup_env.sh
```

完成后各目录使用 **`.venv/bin/python`** 运行 `app.py` / `hub.py`;**PM2 的 ecosystem 脚本已指向该解释器**.

---

## 3. Node.js 与 PM2

| 项 | 说明 |
|----|------|
| **Node.js** | 建议 **18 LTS** 或 **20 LTS**(用于安装 PM2;应用本体为 Python) |
| **PM2** | 全局安装,托管所有 Flask 与中控/子代理 |

### 3.1 安装 Node + PM2(root)

```bash
# 方式 A:NodeSource(示例 Node 20)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node -v    # v20.x
npm -v

npm install -g pm2
pm2 -v
pm2 startup    # 按提示执行,保证重启后 PM2 自启
```

`deploy/setup_env.sh` 在检测到 Node 时也会尝试 `npm install -g pm2`(未装 Node 则跳过并提示手动安装).

### 3.2 PM2 启动顺序(推荐)

```bash
# 1) 三所 Flask(在各子目录执行,或分别 start)
cd /opt/crypto_monitor/crypto_monitor_binance && pm2 start ecosystem.config.cjs
cd /opt/crypto_monitor/crypto_monitor_gate && pm2 start ecosystem.config.cjs
cd /opt/crypto_monitor/crypto_monitor_okx && pm2 start ecosystem.config.cjs

# 2) 中控 + 三子代理(一条配置 4 进程:hub + 3 agent)
cd /opt/crypto_monitor/manual_trading_hub
pm2 start ecosystem.config.cjs

pm2 save
pm2 list
```

升级代码后:

```bash
cd /opt/crypto_monitor && git pull
# 若 requirements 有变,对各目录 .venv/bin/pip install -r ...
pm2 restart all # 或按进程名 restart
```

**不要** 再用 systemd unit,screen,nohup 启动 `app.py` / `hub.py` / `agent.py`,避免与 PM2 抢端口.

### 3.3 常见 PM2 进程名

| 目录 | ecosystem 内典型名称 |
|------|---------------------|
| `crypto_monitor_binance` | `crypto_binance` |
| `crypto_monitor_gate` | `crypto_gate` |
| `crypto_monitor_okx` | `crypto_okx` |
| `manual_trading_hub` | `manual-trading-hub`,`manual-agent-*` |

以各目录 **`ecosystem.config.cjs`** 为准.

### 3.4 整目录重装(清库 / 去脏 PM2)

保留 `.env`,丢弃旧库与旧 PM2 名单时,见 **[deploy/reinstall-plan-b.md](../deploy/reinstall-plan-b.md)**:

```bash
cd /opt/crypto_monitor
bash deploy/reinstall.sh --yes
```

首次安装仍只用 `deploy/setup_env.sh`,二者互不影响.

---

## 4. 目录与权限

```bash
mkdir -p /opt
cd /opt
git clone https://git.bz121.com/dekun/crypto_monitor.git crypto_monitor
chown -R root:root /opt/crypto_monitor
```

- 数据库默认:各所 **`crypto.db`**(SQLite)
- 备份目录建议:**`/root/backups`**(见 [备份与恢复.md](../备份与恢复.md))
- **`.env`**:仅本机编辑,**勿提交 Git**;升级前 `cp .env .env.backup.$(date +%Y%m%d)`

---

## 5. SSH 动态转发(SOCKS)

若交易所 API 需经境外 VPS:

- 在本机用 **`ssh -N -D 127.0.0.1:1080 别名`** 建立隧道(配置见各所《部署文档》`~/.ssh/config`)
- 隧道进程可用 **tmux** 或 **autossh** 保持常驻;**不必** 也不建议把 `ssh` 交给 PM2
- 各所 `.env` 设置对应 `*_SOCKS_PROXY=socks5h://127.0.0.1:1080`

---

## 6. 部署后检查

```bash
# 中控验收(需已 start hub)
bash /opt/crypto_monitor/manual_trading_hub/scripts/verify_hub_deploy.sh

pm2 logs manual-trading-hub --lines 50
curl -sS http://127.0.0.1:5100/api/monitor/board | head
```

---

## 7. 相关文档

| 文档 | 内容 |
|------|------|
| [deploy/README.md](../deploy/README.md) | `setup_env.sh` 参数说明 |
| [备份与恢复.md](../备份与恢复.md) | 数据库与 `.env` 备份 |
| 各 `crypto_monitor_*/部署文档.md` | 交易所 SOCKS,`.env`,PM2 细节 |
| [manual_trading_hub/部署文档.md](../manual_trading_hub/部署文档.md) | 中控 PM2,端口,反代 |
