增加3.9

Python3.9部署说明.md

@@ -0,0 +1,187 @@
+# 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) | 扫描端功能说明 |

README.md

@@ -9,6 +9,7 @@ gate_scout_order/            # git clone 后的根目录（名称可自定）
 ├── onchain_scout_gate/      # 扫描端 · 行情监控、企微告警、信号转发（默认 :8088）
 ├── gate_order_executor/     # 执行器 · 接信号、Gate 下单、面板风控（默认 :8090+）
 ├── 部署说明.md              # ★ 完整部署 + 升级前备份清单
+├── Python3.9部署说明.md     # Ubuntu 20.04 / Python 3.9 专篇
 ├── 备份恢复说明.md          # 手动备份 / 恢复（/opt → /root）
 ├── CLONE.md
 └── README.md                # 本文件

gate_order_executor/deploy/README.md

@@ -5,6 +5,7 @@
 | 文件 | 作用 |
 |------|------|
 | `ecosystem.config.cjs` | PM2 配置：单实例、`PYTHONUNBUFFERED=1`、日志在 `runtime/` |
+| `pick_python.sh` | 自动选择 Python 3.9～3.12（Ubuntu 20.04 勿用默认 3.8） |
 | `bootstrap.sh` | 首次：`venv` + `pip install -r requirements.txt` + 生成 `config.yaml` 模板 |
 | `start.sh` | 前台运行 `python run.py`（调试用） |
 | `pm2-start.sh` | PM2 启动；若应用已存在则 `restart` |
@@ -14,4 +15,5 @@
 | `gate-order-executor.service` | systemd 示例（需改 `WorkingDirectory` 与 `pm2-runtime` 路径） |
 
 使用说明与接口文档：`../docs/使用说明.md`  
-部署步骤：`../docs/部署说明.md`
+部署步骤：`../docs/部署说明.md`  
+Python 3.9 专篇：仓库根目录 `Python3.9部署说明.md`

gate_order_executor/deploy/bootstrap.sh

@@ -7,12 +7,11 @@ set -euo pipefail
 PROJECT_DIR="${1:-/root/gate_order_executor}"
 cd "$PROJECT_DIR"
 
-if ! command -v python3 >/dev/null 2>&1; then
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  echo "请先安装 python3" >&2
+PY="$("$SCRIPT_DIR/pick_python.sh")"
-  exit 1
+echo "使用解释器: $PY ($("$PY" --version))"
-fi
 
-python3 -m venv .venv
+"$PY" -m venv .venv
 # shellcheck source=/dev/null
 source .venv/bin/activate
 python -m pip install -U pip

gate_order_executor/deploy/pick_python.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# 选出 >=3.9 的 python3 可执行文件（优先较新版本）。供 bootstrap.sh 使用。
+set -euo pipefail
+
+for cmd in python3.12 python3.11 python3.10 python3.9; do
+  if command -v "$cmd" >/dev/null 2>&1; then
+    if "$cmd" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'; then
+      echo "$cmd"
+      exit 0
+    fi
+  fi
+done
+
+if command -v python3 >/dev/null 2>&1; then
+  if python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'; then
+    echo python3
+    exit 0
+  fi
+fi
+
+echo "需要 Python 3.9 或更高版本。Ubuntu 20.04 请安装: sudo apt install -y python3.9 python3.9-venv python3.9-dev" >&2
+echo "详见仓库根目录 Python3.9部署说明.md" >&2
+exit 1

onchain_scout_gate/deploy/bootstrap.sh

@@ -4,10 +4,16 @@ set -euo pipefail
 PROJECT_DIR="${1:-/root/onchain_scout_gate}"
 cd "$PROJECT_DIR"
 
-python3 -m venv .venv
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PY="$("$SCRIPT_DIR/pick_python.sh")"
+echo "使用解释器: $PY ($("$PY" --version))"
+
+"$PY" -m venv .venv
+# shellcheck source=/dev/null
 source .venv/bin/activate
 pip install -U pip
 pip install -r requirements.txt
+pip install "socksio>=1.0,<2" || true
 
 if [ ! -f config.yaml ]; then
   cp config.example.yaml config.yaml
@@ -16,4 +22,3 @@ fi
 
 mkdir -p runtime
 echo "Bootstrap done."
-

onchain_scout_gate/deploy/pick_python.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# 选出 >=3.9 的 python3 可执行文件（优先较新版本）。供 bootstrap.sh 使用。
+set -euo pipefail
+
+for cmd in python3.12 python3.11 python3.10 python3.9; do
+  if command -v "$cmd" >/dev/null 2>&1; then
+    if "$cmd" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'; then
+      echo "$cmd"
+      exit 0
+    fi
+  fi
+done
+
+if command -v python3 >/dev/null 2>&1; then
+  if python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'; then
+    echo python3
+    exit 0
+  fi
+fi
+
+echo "需要 Python 3.9 或更高版本。Ubuntu 20.04 请安装: sudo apt install -y python3.9 python3.9-venv python3.9-dev" >&2
+echo "详见仓库根目录 Python3.9部署说明.md" >&2
+exit 1

onchain_scout_gate/requirements.txt

@@ -3,6 +3,8 @@ uvicorn[standard]==0.30.6
 httpx[socks]==0.27.2
 pydantic==2.9.2
 pydantic-settings==2.5.2
+# Python 3.9：与执行器相同，兼容 Pydantic 对 `X | Y` 注解的解析
+eval-type-backport>=0.2,<1
 python-multipart==0.0.9
 itsdangerous==2.2.0
 jinja2==3.1.4

部署说明.md

@@ -143,8 +143,10 @@ cp -a /root/backup_gate_xxxx/gate_order_executor/runtime/* "$NEW/gate_order_exec
 
 ## 3. 服务器环境准备
 
+> **Python 版本**：项目要求 **3.9～3.12**（不支持 3.8）。Ubuntu 20.04 默认 `python3` 为 3.8，请安装 `python3.9` 或更高版本，详见 **[Python3.9部署说明.md](Python3.9部署说明.md)**。
+
 ```bash
-sudo apt update && sudo apt install -y python3 python3-venv python3-pip curl git
+sudo apt update && sudo apt install -y python3.9 python3.9-venv python3.9-dev curl git
 
 # Node.js + PM2（任选一种安装 Node 的方式）
 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
@@ -202,10 +204,11 @@ git push -u origin main
 cd /opt/gate_scout_order/onchain_scout_gate
 chmod +x deploy/*.sh
 
-python3 -m venv .venv
+# 推荐：自动选用 python3.9～3.12（见 Python3.9部署说明.md）
-source .venv/bin/activate
+bash deploy/bootstrap.sh /opt/gate_scout_order/onchain_scout_gate
-pip install -U pip
+
-pip install -r requirements.txt
+# 或手动（Ubuntu 20.04 务必用 python3.9，不要用默认 python3）：
+# python3.9 -m venv .venv && source .venv/bin/activate && pip install -U pip && pip install -r requirements.txt
 
 # 若无 config.yaml（升级已从备份恢复则跳过）
 cp config.example.yaml config.yaml
@@ -411,6 +414,7 @@ pm2 save
 |------|------|
 | `git clone` 403 / 认证失败 | 检查 Gitea 账号、Token；或改用 SSH |
 | 扫描端拉不到行情 | `proxy`、防火墙；`curl -I https://api.gateio.ws` |
+| `matplotlib` / `str \| None` / Pydantic 注解报错 | Python 版本低于 3.9 或 venv 用错；见 **[Python3.9部署说明.md](Python3.9部署说明.md)** |
 | 有 TRIGGER 未下单 | 面板执行器总开关、列表为空、webhook 不一致；日志搜 `order_executor_` |
 | 执行器 401 | `X-Webhook-Secret` 与配置不一致 |
 | 升级后面板策略丢了 | 是否未恢复 `runtime/alerts.db` |