diff --git a/Python3.9部署说明.md b/Python3.9部署说明.md new file mode 100644 index 0000000..b11798c --- /dev/null +++ b/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) | 扫描端功能说明 | diff --git a/README.md b/README.md index 2547781..0dcb696 100644 --- a/README.md +++ b/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 # 本文件 diff --git a/gate_order_executor/deploy/README.md b/gate_order_executor/deploy/README.md index 101e58c..8e049d6 100644 --- a/gate_order_executor/deploy/README.md +++ b/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` diff --git a/gate_order_executor/deploy/bootstrap.sh b/gate_order_executor/deploy/bootstrap.sh index 9e318e3..d93a3a2 100644 --- a/gate_order_executor/deploy/bootstrap.sh +++ b/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 - echo "请先安装 python3" >&2 - exit 1 -fi +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PY="$("$SCRIPT_DIR/pick_python.sh")" +echo "使用解释器: $PY ($("$PY" --version))" -python3 -m venv .venv +"$PY" -m venv .venv # shellcheck source=/dev/null source .venv/bin/activate python -m pip install -U pip diff --git a/gate_order_executor/deploy/pick_python.sh b/gate_order_executor/deploy/pick_python.sh new file mode 100644 index 0000000..0d3c1ce --- /dev/null +++ b/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 diff --git a/onchain_scout_gate/deploy/bootstrap.sh b/onchain_scout_gate/deploy/bootstrap.sh index 0ed5f6b..0a795a1 100644 --- a/onchain_scout_gate/deploy/bootstrap.sh +++ b/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." - diff --git a/onchain_scout_gate/deploy/pick_python.sh b/onchain_scout_gate/deploy/pick_python.sh new file mode 100644 index 0000000..0d3c1ce --- /dev/null +++ b/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 diff --git a/onchain_scout_gate/requirements.txt b/onchain_scout_gate/requirements.txt index 85e0b9e..4d8b80d 100644 --- a/onchain_scout_gate/requirements.txt +++ b/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 diff --git a/部署说明.md b/部署说明.md index d4d8491..74640fc 100644 --- a/部署说明.md +++ b/部署说明.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 -source .venv/bin/activate -pip install -U pip -pip install -r requirements.txt +# 推荐：自动选用 python3.9～3.12（见 Python3.9部署说明.md） +bash deploy/bootstrap.sh /opt/gate_scout_order/onchain_scout_gate + +# 或手动（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` |