Python 3.9 部署说明

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

完整业务部署（PM2、config、备份）仍以 部署说明.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。

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 或 pyenv（见 §8）。

3. 扫描端 onchain_scout_gate

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

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

[ -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

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. 一键自检

# 扫描端
/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/），上传到新机后：

删除两个子目录下的 .venv
按 §3、§4 用 python3.9 重建 venv
pm2 restart 或重新 pm2 start

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

8. 可选：升级到 Python 3.10+

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

# 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，均不满足则报错退出：

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	完整上云、PM2、代理、串联执行器
备份恢复说明.md	config / runtime 备份
onchain_scout_gate/安装与说明.md	扫描端功能说明

5.9 KiB Raw Blame History Unescape Escape