---
name: server_deployment_venv
description: 当服务器部署时遇到 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 重建：

```bash
/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` 是否可用：

```bash
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：

```bash
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`），需要同步修复代码