提交

测试环境部署/README.md

@@ -55,8 +55,9 @@ cd /root/zkxw-backend/backend
 cp .env.test.example .env.test
 # 编辑 .env.test：测试库、Redis DB、MinIO bucket、SECRET_KEY、CORS、API 加密等与前端一致
 
-# 2) 虚拟环境与依赖
-python3 -m venv .venv
+# 2) 虚拟环境与依赖（须 python3.9+，勿用系统默认 python3.6）
+python3.9 -m venv .venv
+./.venv/bin/pip install --upgrade pip
 ./.venv/bin/pip install -r requirements.txt
 
 # 3) 赋予脚本执行权限
@@ -340,10 +341,48 @@ sed -i 's/\r$//' start-test.sh start-prod.sh
 ### 虚拟环境未找到
 
 ```bash
-python3 -m venv .venv
+python3.9 -m venv .venv
+./.venv/bin/pip install --upgrade pip
 ./.venv/bin/pip install -r requirements.txt
 ```
 
+### Python 版本过低 / 依赖安装报 fastapi==0.109.0 找不到
+
+**现象**：`系统 python3 版本: 3.6`，或 pip 版本 9.x，安装 fastapi 失败。
+
+**原因**：系统默认 `python3` 为 3.6，而本项目需要 **Python 3.9+**。若曾用 3.6 创建过 `venv/` 或 `.venv/`，启动脚本会误用旧环境。
+
+**处理**：
+
+```bash
+cd /root/zkxw-backend/backend
+
+# 确认可用版本
+python3.9 --version
+
+# 检查是否误设了生产 venv 目录
+echo "VENV_DIR=${VENV_DIR:-<未设置>}"
+unset VENV_DIR   # 若曾 export VENV_DIR=./venv，先取消
+
+# 删除旧 venv，用 3.9 重建
+rm -rf .venv venv
+python3.9 -m venv .venv
+./.venv/bin/pip install --upgrade pip
+./.venv/bin/pip install -r requirements.txt
+
+# 验证
+./.venv/bin/python --version    # 应为 3.9.x
+./.venv/bin/python -c "import uvicorn; print('ok')"
+
+./start-test.sh start
+```
+
+若 shell 中曾 `export VENV_DIR=./venv`（生产用），测试启动前须 `unset VENV_DIR` 或显式指定：
+
+```bash
+VENV_DIR=./.venv ./start-test.sh start
+```
+
 ---
 
 ## 9. 仓库内相关文件索引