Detect ensurepip and auto-install python3-venv in one-click deploy.

Avoid false OK on bare python3; repair broken .venv; re-check deps after git pull.

Co-authored-by: Cursor <cursoragent@cursor.com>

deploy/lib/common.sh

@@ -187,8 +187,9 @@ resolve_repo_root() {
 
 python_runtime_ok() {
   command -v python3 >/dev/null 2>&1 || return 1
-  # 能创建 venv 即可；pip 在项目 .venv 内安装
-  python3 -c "import venv" >/dev/null 2>&1 || return 1
+  # Ubuntu 常有 python3 且 import venv 成功，但缺 python3.X-venv 时 ensurepip 不可用，
+  # python3 -m venv 会失败。必须以 ensurepip 为准。
+  python3 -c "import ensurepip" >/dev/null 2>&1 || return 1
   return 0
 }
 
@@ -222,15 +223,22 @@ print_runtime_probe() {
 }
 
 install_python_runtime() {
-  step "安装 Python3 环境 (python3 / venv / pip)"
+  step "安装 Python3 环境 (python3 / venv / pip / ensurepip)"
   export DEBIAN_FRONTEND=noninteractive
   if ! command -v apt-get >/dev/null 2>&1; then
     die "非 apt 系统，请手动安装 python3 python3-venv python3-pip"
   fi
   apt_update
   apt_install python3 python3-venv python3-pip
+  # Debian/Ubuntu：版本化包（如 python3.10-venv）才真正提供 ensurepip
+  local pyver=""
+  pyver="$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null || true)"
+  if [[ -n "${pyver}" ]]; then
+    log "安装 python${pyver}-venv（提供 ensurepip）…"
+    apt_install "python${pyver}-venv" || true
+  fi
   if ! python_runtime_ok; then
-    die "Python 环境安装后仍不可用，请检查 apt 源"
+    die "Python 环境安装后仍不可用（缺 ensurepip）。请检查: apt install python3-venv python${pyver:-3}-venv"
   fi
   log "Python 已就绪: $(python3 --version 2>&1)"
 }

deploy/pull_and_restart.sh

@@ -8,7 +8,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$ROOT"
 
-# 有 root 时：检测 Python / Node / PM2，缺则装、有则跳过
+# 有 root 时：检测 Python / Node / PM2，缺则装、有则跳过（pull 前用当前脚本）
 if [[ -f "$ROOT/deploy/lib/common.sh" ]] && [[ "$(id -u)" -eq 0 ]]; then
   # shellcheck source=lib/common.sh
   source "$ROOT/deploy/lib/common.sh"
@@ -21,6 +21,13 @@ if [[ -d "$ROOT/.git" ]]; then
   git pull --ff-only
 fi
 
+# pull 后再检测一次，确保用上仓库里最新的 python3-venv / ensurepip 逻辑
+if [[ -f "$ROOT/deploy/lib/common.sh" ]] && [[ "$(id -u)" -eq 0 ]]; then
+  # shellcheck source=lib/common.sh
+  source "$ROOT/deploy/lib/common.sh"
+  ensure_system_deps
+fi
+
 if [[ ! -f "$ROOT/.env" ]]; then
   echo "[比特骆驼] missing .env — copy from example"
   cp "$ROOT/.env.example" "$ROOT/.env"
@@ -37,9 +44,21 @@ if ! command -v python3 >/dev/null 2>&1; then
   exit 1
 fi
 
+# 半截失败的 .venv（缺 ensurepip 时常见）会留下坏目录，必须重建
+if [[ -d "$ROOT/.venv" ]] && [[ ! -x "$ROOT/.venv/bin/python3" ]]; then
+  echo "[比特骆驼] .venv 不完整，删除后重建"
+  rm -rf "$ROOT/.venv"
+fi
+
 if [[ ! -d "$ROOT/.venv" ]]; then
   echo "[比特骆驼] create venv"
-  python3 -m venv "$ROOT/.venv"
+  if ! python3 -m venv "$ROOT/.venv"; then
+    pyver="$(python3 -c 'import sys; print("%d.%d" % sys.version_info[:2])' 2>/dev/null || echo "3")"
+    echo "ERROR: 创建 venv 失败（多为缺 python3-venv / ensurepip）。" >&2
+    echo "  可执行: apt install -y python3-venv python${pyver}-venv" >&2
+    rm -rf "$ROOT/.venv"
+    exit 1
+  fi
 fi
 # shellcheck disable=SC1091
 source "$ROOT/.venv/bin/activate"

docs/更新说明.md

@@ -5,6 +5,15 @@
 
 ---
 
+## 2026-07-29 — 部署：自动安装 python3-venv（ensurepip）
+
+### 变更
+
+1. Python 就绪判定改为检测 `ensurepip`（避免仅有 python3 却误报 OK）。  
+2. 一键部署自动安装 `python3-venv` / `python3.X-venv`；pull 后二次检测；损坏的 `.venv` 自动重建。
+
+---
+
 ## 2026-07-29 — 部署：等待 apt 锁（unattended-upgrades）
 
 ### 变更