gate_scout_order/Python3.9部署说明.md

# Python 3.9 部署说明

本文档面向 **Ubuntu 20.04** 等仅自带 **Python 3.8**、需单独安装 **3.9** 的服务器。  
项目代码兼容 **Python 3.9～3.12**；**推荐 3.10+**，3.9 为最低可用版本。

完整业务部署（PM2、config、备份）仍以 **[部署说明.md](部署说明.md)** 为主；本文只讲 **解释器版本与 venv**。

---

## 1. 版本要求

| Python | 能否部署 | 说明 |
|--------|----------|------|
| **3.8** | ❌ | `matplotlib==3.9.2` 不支持；类型注解 `str \| None` 会报错 |
| **3.9** | ✅ | Ubuntu 20.04 常用；执行器需 `eval-type-backport`（已写入 `requirements.txt`） |
| **3.10～3.12** | ✅ 推荐 | 与开发环境一致，无需额外兼容包 |

---

## 2. Ubuntu 20.04 安装 Python 3.9

系统默认 `python3` 指向 **3.8**，不要用它建 venv。

```bash
sudo apt update
sudo apt install -y python3.9 python3.9-venv python3.9-dev

python3.9 --version
# 期望：Python 3.9.x
```

> **说明**：Ubuntu 20.04 官方源通常有 `python3.9`，没有 `python3.10` 包时不必强求；用 3.9 即可。  
> 若需 3.10，可用 [deadsnakes PPA](https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa) 或 pyenv（见 [§8](#8-可选升级到-python-310)）。

---

## 3. 扫描端 onchain_scout_gate

```bash
cd /opt/gate_scout_order/onchain_scout_gate
chmod +x deploy/*.sh

# 删除旧 venv（尤其曾用 3.8 或从 Windows 拷来的 .venv）
rm -rf .venv

python3.9 -m venv .venv
source .venv/bin/activate

python --version          # 必须是 3.9.x，不能是 3.8
pip install -U pip
pip install -r requirements.txt
pip install "socksio>=1.0,<2" || true   # config 里 proxy.enabled=true 时需要

deactivate
```

**配置与启动**（与主文档相同）：

```bash
[ -f config.yaml ] || cp config.example.yaml config.yaml
chmod 600 config.yaml
# 编辑 config.yaml 后：
cd /opt/gate_scout_order/onchain_scout_gate
pm2 start deploy/ecosystem.config.cjs
pm2 save
```

---

## 4. 执行器 gate_order_executor

```bash
cd /opt/gate_scout_order/gate_order_executor
chmod +x deploy/*.sh
rm -rf .venv

python3.9 -m venv .venv
source .venv/bin/activate
python --version
pip install -U pip
pip install -r requirements.txt
pip install "socksio>=1.0,<2" || true
deactivate

[ -f config.yaml ] || cp config.example.yaml config.yaml
chmod 600 config.yaml

cd /opt/gate_scout_order/gate_order_executor
bash deploy/pm2-start.sh
pm2 save
```

`requirements.txt` 已包含 **`eval-type-backport`**，供 Pydantic 在 3.9 下解析 `float | None` 等注解。  
若仍报 `Unable to evaluate type annotation`，请确认已执行 `pip install -r requirements.txt` 且 venv 为 3.9。

---

## 5. 一键自检

```bash
# 扫描端
/opt/gate_scout_order/onchain_scout_gate/.venv/bin/python --version
/opt/gate_scout_order/onchain_scout_gate/.venv/bin/python -c "
from app.proxy_util import httpx_proxy_url
from app.config import load_settings
print('scout import ok')
"

# 执行器
/opt/gate_scout_order/gate_order_executor/.venv/bin/python --version
/opt/gate_scout_order/gate_order_executor/.venv/bin/python -c "
from app.models_signal import TradeSignal
print('executor import ok')
"

pm2 status
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/api/status
curl -s http://127.0.0.1:8090/health
```

---

## 6. 常见报错（3.9 环境）

| 报错 | 原因 | 处理 |
|------|------|------|
| `No matching distribution found for matplotlib==3.9.2` | 用了 **Python 3.8** 的 venv | `rm -rf .venv` 后用 **`python3.9 -m venv`** 重建 |
| `TypeError: unsupported operand type(s) for \|: 'type' and 'NoneType'`（`proxy_util.py`） | 3.9 下未延迟求值联合类型 | 确保 `app/proxy_util.py` 含 `from __future__ import annotations`（当前仓库已包含） |
| `Unable to evaluate type annotation 'float \| None'` | 执行器 Pydantic + 3.9 | `pip install eval-type-backport` 或重装 `requirements.txt` |
| PM2 日志里路径是 `/usr/lib/python3.8/` | PM2 未用项目 `.venv` | 在子项目目录 `pm2 delete` 后重新 `pm2 start deploy/...` |
| 从本机 Windows 整包上传后无法启动 | `.venv` 不能跨系统复用 | **只打包代码 + config + runtime**；到 Linux 上按本文重建 venv |

---

## 7. 与「整目录打包迁移」配合

可以 tar 整个 `/opt/gate_scout_order`（含 `config.yaml`、`runtime/`），上传到新机后：

1. **删除** 两个子目录下的 `.venv`
2. 按 [§3](#3-扫描端-onchain_scout_gate)、[§4](#4-执行器-gate_order_executor) 用 **python3.9** 重建 venv
3. `pm2 restart` 或重新 `pm2 start`

数据与配置无需单独恢复；**环境必须在新机重装一遍**。

---

## 8. 可选：升级到 Python 3.10+

若希望与开发机完全一致、少踩 3.9 注解兼容问题：

```bash
# Ubuntu 20.04 + deadsnakes（若 apt 有 python3.10）
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3.10-dev

cd /opt/gate_scout_order/onchain_scout_gate
rm -rf .venv && python3.10 -m venv .venv
source .venv/bin/activate && pip install -U pip && pip install -r requirements.txt
```

执行器同样用 `python3.10 -m venv`。  
**3.10+ 不强制需要 `eval-type-backport`**，保留在 requirements 里也无害。

---

## 9. 使用 bootstrap 脚本（自动选 3.10 / 3.9）

子目录 `deploy/bootstrap.sh` 会优先 `python3.12` → `3.11` → `3.10` → `3.9`，均不满足则报错退出：

```bash
cd /opt/gate_scout_order/onchain_scout_gate
bash deploy/bootstrap.sh /opt/gate_scout_order/onchain_scout_gate

cd /opt/gate_scout_order/gate_order_executor
bash deploy/bootstrap.sh /opt/gate_scout_order/gate_order_executor
```

---

## 相关文档

| 文档 | 内容 |
|------|------|
| [部署说明.md](部署说明.md) | 完整上云、PM2、代理、串联执行器 |
| [备份恢复说明.md](备份恢复说明.md) | config / runtime 备份 |
| [onchain_scout_gate/安装与说明.md](onchain_scout_gate/安装与说明.md) | 扫描端功能说明 |