docs: require Python 3.10 for obfuscated lib; prefer Ubuntu 22.04

Reject 3.12+ in setup_env to avoid bad marshal data on new servers. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-18 12:15:21 +08:00
parent 1d2bdc3aa1
commit af0fbc3e6f
6 changed files with 53 additions and 15 deletions
@@ -11,7 +11,8 @@

 | 项 | 约定 |
 |----|------|
-| 系统 | Ubuntu 22.04 / 24.04 |
+| 系统 | **优先 Ubuntu 22.04**(自带 Python 3.10);24.04 须用 Python 3.10,勿用 3.12 |
+| Python | **3.10 / 3.11**(推荐 3.10;加密 `lib/` 与 3.12 不兼容) |
 | 用户 | root |
 | 路径 | `/opt/crypto_monitor_user` |
 | 进程 | PM2 |
@@ -76,8 +76,10 @@ deploy/

 ## 前置条件

- **Ubuntu 22.04 / 24.04**,用户 **root**
+- **优先 Ubuntu 22.04**(自带 Python 3.10);24.04 须另装 **python3.10**,不可用系统 3.12
+- 用户 **root**
 - 能 `git clone` 仓库到 `/opt/crypto_monitor_user`
+- 详见 **[docs/ubuntu-server.md](../docs/ubuntu-server.md)**(含 `bad marshal data` 说明)

 ---

@@ -121,7 +123,7 @@ sed -i 's/\r$//' deploy/manage.sh deploy/lib/*.sh

 | 步骤 | 说明 |
 |------|------|
-| 检查 Python | 需要 **3.10+** |
+| 检查 Python | **仅 3.10 / 3.11**(推荐 3.10);优先 `python3.10`;**拒绝 3.12+** |
 | `crypto_monitor_*` | 各目录 `.venv` + `pip install -r ../requirements.txt` |
 | `manual_trading_hub` | 独立 `requirements.txt` |
 | `.env` | 不存在则从 `.env.example` 复制 |
@@ -147,4 +149,5 @@ BACKUP_ROOT=/root/backups
 - 三个监控子项目共用根目录 **[requirements.txt](../requirements.txt)**.
 - 走 SOCKS 须 **PySocks**(已包含在 requirements 中).
 - **用户版核心包**（`lib/strategy` 等）为加密发行；本地开发若需重新加密，见 `scripts/obfuscate_release.py`。
+- **加密包与 Python 版本绑定**:当前发行包按 **Python 3.10** 编译。用 3.12 启动会报 `ValueError: bad marshal data (unknown type code)`。新服务器请用 **Ubuntu 22.04**,或在 24.04 上安装 `python3.10` 后再跑 `setup_env.sh`。
 - **授权**：配置仓库根 `license.env`（见 `license.env.example`），对接 [https://sq.bz121.com/](https://sq.bz121.com/)。
@@ -71,12 +71,16 @@ require_ubuntu() {
  # shellcheck source=/dev/null
  source /etc/os-release
  if [[ "${ID:-}" != "ubuntu" ]]; then
-    log "警告: 当前系统为 ${ID:-unknown},官方仅测试 Ubuntu 22.04/24.04"
+    log "警告: 当前系统为 ${ID:-unknown},官方推荐 Ubuntu 22.04(Python 3.10)"
    return 0
  fi
  local ver="${VERSION_ID:-}"
-  if [[ "${ver}" != "22.04" && "${ver}" != "24.04" ]]; then
-    log "警告: Ubuntu ${ver} 未在文档中明确测试,继续执行"
+  if [[ "${ver}" == "22.04" ]]; then
+    log "系统: Ubuntu 22.04(推荐)"
+  elif [[ "${ver}" == "24.04" ]]; then
+    log "警告: Ubuntu 24.04 默认 Python 3.12 与用户版加密 lib 不兼容;请确保已安装 python3.10"
+  else
+    log "警告: Ubuntu ${ver} 未在文档中明确测试,继续执行(推荐 22.04)"
  fi
 }

@@ -63,6 +63,15 @@ should_include() {
 }

 find_python() {
+  # 用户版加密 lib 按 3.10 打包;优先明确版本,避免 Ubuntu 24.04 的 python3=3.12
+  if command -v python3.10 >/dev/null 2>&1; then
+    echo python3.10
+    return
+  fi
+  if command -v python3.11 >/dev/null 2>&1; then
+    echo python3.11
+    return
+  fi
  if command -v python3 >/dev/null 2>&1; then
    echo python3
    return
@@ -71,7 +80,7 @@ find_python() {
    echo python
    return
  fi
-  echo "未找到 python3/python,请先安装 Python 3.10+" >&2
+  echo "未找到 python3.10/python3.11/python3,请先安装 Python 3.10(推荐 Ubuntu 22.04)" >&2
  exit 1
 }

@@ -83,7 +92,13 @@ check_python_version() {
  major="${ver%%.*}"
  minor="${ver#*.}"
  if [[ "${major}" -lt 3 ]] || [[ "${major}" -eq 3 && "${minor}" -lt 10 ]]; then
-    echo "需要 Python 3.10+,当前: ${ver}" >&2
+    echo "需要 Python 3.10 或 3.11(推荐 3.10),当前: ${ver}" >&2
+    exit 1
+  fi
+  if [[ "${major}" -eq 3 && "${minor}" -ge 12 ]]; then
+    echo "用户版加密核心包不支持 Python ${ver}(会出现 bad marshal data)。" >&2
+    echo "请改用 Ubuntu 22.04,或安装 python3.10 后重新执行本脚本。" >&2
+    echo "说明见 docs/ubuntu-server.md" >&2
    exit 1
  fi
  echo "Python: $("${py}" --version 2>&1)"
@@ -8,33 +8,48 @@

 | 项 | 要求 |
 |----|------|
-| 操作系统 | **Ubuntu 22.04 LTS** 或 **24.04 LTS**(64 位) |
+| 操作系统 | **优先 Ubuntu 22.04 LTS**(自带 Python 3.10)。24.04 可用,但须自行安装 **Python 3.10**,不可用系统默认 3.12 |
 | 运行用户 | **root**(下文命令均按 root 编写) |
 | 项目路径 | **`/opt/crypto_monitor_user`**(整仓克隆到此目录) |
 | 进程管理 | **PM2**(全局安装,见 §3) |
 | 网络 | 能 `git clone` 私有仓库;能访问授权站 **https://sq.bz121.com**;访问交易所不稳定时需 **SSH SOCKS**(见各所《部署文档》) |
 | 授权 | 部署后配置仓库根 `license.env`，打开 `/license` 激活（见 [license.md](./license.md)） |

+> **新机建议直接装 22.04。** 用户版 `lib/` 核心包为 Python 3.10 加密字节码;用 3.12 启动会出现 `ValueError: bad marshal data (unknown type code)`(如 `crypto_okx` 反复重启)。
+
 ---

 ## 2. Python 环境

 | 项 | 说明 |
 |----|------|
-| **版本** | **Python 3.10 或 3.11**(`python3 --version` ≥ 3.10);脚本会拒绝 3.9 及以下 |
-| **虚拟环境** | 每个子项目独立 **`.venv`**(`deploy/setup_env.sh` 自动创建) |
+| **版本** | **仅 Python 3.10 或 3.11**(推荐 **3.10**)。`setup_env.sh` 会拒绝 3.9 及以下、**以及 3.12+** |
+| **虚拟环境** | 每个子项目独立 **`.venv`**(`deploy/setup_env.sh` 自动创建;优先选用 `python3.10`) |
 | **依赖文件** | 三所监控共用仓库根目录 **`requirements.txt`**;中控用 **`manual_trading_hub/requirements.txt`** |
 | **SOCKS** | 走代理时必须安装 **PySocks**(已写入 requirements) |

 ### 2.1 系统包(root)

+**Ubuntu 22.04(推荐):**
+
 ```bash
 apt update
 apt install -y python3 python3-pip python3-venv curl git ca-certificates
-# 若 python3 为 3.10:
+# 22.04 上 python3 即为 3.10
 apt install -y python3.10-venv
-# 若为 3.12:
-apt install -y python3.12-venv
+python3 --version   # 应为 Python 3.10.x
+```
+
+**若坚持 Ubuntu 24.04:** 勿用系统 `python3`(3.12)。需先安装 3.10,再部署:
+
+```bash
+apt update
+apt install -y software-properties-common
+add-apt-repository -y ppa:deadsnakes/ppa
+apt update
+apt install -y python3.10 python3.10-venv python3.10-dev curl git ca-certificates
+python3.10 --version
+# 随后一键部署;setup_env 会优先使用 python3.10
 ```

 ### 2.2 一键创建各目录 venv
@@ -25,7 +25,7 @@

 ## 二,前置条件

-1. **Python 3.10+**,`python3-venv`,`pip`.
+1. **Python 3.10 或 3.11**(推荐 3.10;勿用 3.12),`python3-venv`,`pip`。完整环境见 [docs/ubuntu-server.md](../docs/ubuntu-server.md)。
 2. **Node.js + npm**(用于安装 PM2):`sudo npm i -g pm2`.
 3. 各 `crypto_monitor_*` 目录已 **`cp .env.example .env`** 并填好 API 密钥.
 4. 端口无冲突:`5100`,`15200`～`15202`,各实例 `APP_PORT`(5000/5001/5004).