agent-Specialization/.astrion/memory/server_deployment_venv.md

name	description
server_deployment_venv	当服务器部署时遇到 venv/pip 损坏、Python 路径错误，或需要更新部署脚本时，应该索引本记忆

服务器 venv 部署注意事项

背景

服务器 /opt/agent/venv 最初是从 macOS 复制到 Linux（Ubuntu 24.04）的，导致：

• python3 等符号链接指向 macOS 路径（/Library/Developer/...）
• pip、flask 等脚本的 shebang 指向 macOS 路径或错误路径
• 结果：python3 可能能用，但 pip 无法执行

修复方法

1. 重建 venv（推荐）

在服务器上用 Linux 系统 Python 重建：

/usr/bin/python3.12 -m venv --clear /opt/agent/venv
/opt/agent/venv/bin/pip install -r /opt/agent/agents/requirements.txt

2. 修改后的部署脚本

/opt/agent/start_webapp_new.sh

fix_venv() 同时检查 python3 和 pip 是否可用：

fix_venv() {
    if [ -x "$VENV_DIR/bin/python3" ] && "$VENV_DIR/bin/python3" --version &>/dev/null && \
       [ -x "$VENV_DIR/bin/pip" ] && "$VENV_DIR/bin/pip" --version &>/dev/null; then
        return 0
    fi
    # ... 重建 venv ...
}

/opt/agent/refresh_agents.sh

安装依赖前验证 pip 是否可执行，不可执行则自动重建 venv：

VENV_DIR="/opt/agent/venv"
if [ -x "$VENV_DIR/bin/pip" ] && "$VENV_DIR/bin/pip" --version &>/dev/null; then
    "$VENV_DIR/bin/pip" install -r "$AGENTS_DIR/requirements.txt" -q 2>&1 | tail -3
else
    log "venv pip 不可用，重建虚拟环境..."
    sys_python=$(command -v python3.12 2>/dev/null || command -v python3 2>/dev/null || command -v python 2>/dev/null || true)
    if [ -z "$sys_python" ]; then
        log "错误: 找不到系统 Python"
        exit 1
    fi
    "$sys_python" -m venv --clear "$VENV_DIR"
    "$VENV_DIR/bin/pip" install -r "$AGENTS_DIR/requirements.txt" -q 2>&1 | tail -3
    log "虚拟环境重建完成"
fi

注意事项

• 服务器内存只有 2G，前端构建不在服务器执行，由本地 deploy_agents.sh scp 上传 static/dist/
• 以后部署不要再从 macOS 复制 venv 到服务器
• 如果 pip 包版本升级引入破坏性变更（如 openai>=2.40 强制要求 api_key），需要同步修复代码