# 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_gate_bot && pm2 start ecosystem.config.cjs
cd /opt/crypto_monitor/crypto_monitor_okx && pm2 start ecosystem.config.cjs

# 2) 中控 + 四子代理（一条配置 5 进程）
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-monitor-binance` |
| `crypto_monitor_gate` | `crypto-monitor-gate` |
| `crypto_monitor_gate_bot` | `crypto-monitor-gate-bot` |
| `crypto_monitor_okx` | `crypto-monitor-okx` |
| `manual_trading_hub` | `manual-trading-hub`、`manual-agent-*` |

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

---

## 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、端口、反代 |