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>

deploy/README.md

@@ -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/)。

deploy/lib/common.sh

@@ -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
 }
 

deploy/setup_env.sh

@@ -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)"