README.md 10.4 KB

Raw Blame History Permalink



部署指南（无 root 权限）


一、服务器准备


购买阿里云 ECS（Ubuntu 20.04+ 或 CentOS 7+）
安全组开放端口：22、2025

SSH 连接服务器（使用普通用户，非 root）


二、检查环境

# 检查 Python 版本（需要 Python 3.8+）
python3 --version

# 如果没有 Python3，尝试安装（可能需要管理员协助）
# 或使用 conda/miniconda 等用户级 Python 环境


三、部署应用


1. 上传代码

# 方式1: 使用 scp（本地执行，替换 username 为你的用户名）
scp -r . username@服务器IP:~/langgraph/

# 方式2: 使用 Git
cd ~
git clone <仓库地址> langgraph

# 方式3: 使用 FTP/SFTP 工具上传到 ~/langgraph/


2. 安装依赖


标准安装方式（如果系统 pip 正常）

cd ~/langgraph
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install uvicorn python-dotenv


故障排除：如果虚拟环境创建失败

问题1：ensurepip 失败或 pip 损坏

如果遇到以下错误：

Error: Command '['.../venv/bin/python3', '-m', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1.


解决方案：使用 --without-pip 创建虚拟环境

cd ~/langgraph

# 1. 检查系统 pip 是否可用
python3 -m pip --version

# 2. 如果系统 pip 损坏，先修复系统 pip
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py
rm get-pip.py

# 3. 使用 --without-pip 创建虚拟环境
python3 -m venv venv --without-pip

# 4. 激活虚拟环境
source venv/bin/activate

# 5. 使用系统 pip 安装 pip、setuptools、wheel 到虚拟环境
# 注意：将 python3.12 替换为你的实际 Python 版本（如 python3.10）
python3 -m pip install --target venv/lib/python3.12/site-packages pip setuptools wheel

# 6. 验证 pip 是否可用
python3 -m pip --version

# 7. 安装项目依赖（使用 python3 -m pip 更可靠）
python3 -m pip install -r requirements.txt
python3 -m pip install uvicorn python-dotenv


问题2：系统 pip 损坏（ModuleNotFoundError: No module named 'distutils'）

如果遇到 distutils 模块缺失错误：

# 1. 重新安装系统 pip
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py
rm get-pip.py

# 2. 验证
python3 -m pip --version

# 3. 然后按照"问题1"的解决方案继续


问题3：网络问题无法下载 get-pip.py

如果无法访问 bootstrap.pypa.io：

# 方法1：使用国内镜像（如果可用）
curl https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/get-pip.py -o get-pip.py
# 注意：如果下载的是 HTML 重定向页面，需要使用方法2

# 方法2：直接使用系统 pip 安装到虚拟环境（推荐）
cd ~/langgraph
python3 -m venv venv --without-pip
source venv/bin/activate

# 退出虚拟环境，使用系统 pip
deactivate
# 注意：将 python3.12 替换为你的实际 Python 版本
python3 -m pip install --target venv/lib/python3.12/site-packages pip setuptools wheel

# 重新激活虚拟环境
source venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m pip install uvicorn python-dotenv


完整安装流程（推荐，适用于所有情况）

cd ~/langgraph

# 步骤1：检查 Python 和 pip
python3 --version
python3 -m pip --version

# 步骤2：如果 pip 不可用，修复系统 pip
if ! python3 -m pip --version > /dev/null 2>&1; then
    echo "修复系统 pip..."
    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
    python3 get-pip.py
    rm get-pip.py
fi

# 步骤3：创建虚拟环境
if [ -d "venv" ]; then
    echo "清理旧的虚拟环境..."
    rm -rf venv
fi

# 获取 Python 版本号（如 3.12）
PYTHON_VERSION=$(python3 --version | awk '{print $2}' | cut -d. -f1,2)

# 尝试标准方式创建
if ! python3 -m venv venv 2>/dev/null; then
    echo "标准方式失败，使用 --without-pip 方式..."
    python3 -m venv venv --without-pip

    # 使用系统 pip 安装基础包
    python3 -m pip install --target venv/lib/python${PYTHON_VERSION}/site-packages pip setuptools wheel
fi

# 步骤4：激活虚拟环境
source venv/bin/activate

# 步骤5：安装依赖
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt
python3 -m pip install uvicorn python-dotenv

# 步骤6：验证安装
python3 -m pip list | grep -E "langgraph|uvicorn|dotenv"

echo "✅ 依赖安装完成！"


验证安装

# 激活虚拟环境
source venv/bin/activate

# 检查 Python 路径（应该指向 venv）
which python
# 应该显示：/home/username/Test_LangGraph/venv/bin/python

# 检查已安装的包
pip list

# 测试导入关键模块
python -c "import langgraph; print('LangGraph OK')"
python -c "import uvicorn; print('Uvicorn OK')"


注意事项


Python 版本：确保使用 Python 3.8+，推荐 Python 3.10+

虚拟环境路径：如果 Python 版本不是 3.12，将命令中的 python3.12 替换为实际版本（如 python3.10）

权限问题：如果遇到权限错误，确保对项目目录有写权限

网络问题：如果网络不稳定，考虑使用国内镜像源或离线安装


3. 配置环境变量

cd ~/langgraph
vim .env


添加内容：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.deepseek.com/v1


4. 创建日志目录

mkdir -p ~/langgraph/logs


四、启动服务


方式1: 使用启动脚本（推荐）

cd ~/langgraph
chmod +x deploy/start.sh deploy/stop.sh deploy/restart.sh

# 启动服务
./deploy/start.sh

# 停止服务
./deploy/stop.sh

# 重启服务
./deploy/restart.sh


方式2: 使用 nohup 后台运行

cd ~/langgraph
source venv/bin/activate
nohup python start_server_direct.py > logs/app.log 2>&1 &
echo $! > logs/app.pid  # 保存进程ID


方式3: 使用 screen（推荐用于长时间运行）

# 安装 screen（如果未安装，可能需要管理员协助）
# 或使用 tmux

# 创建 screen 会话
screen -S langgraph

# 在 screen 中启动
cd ~/langgraph
source venv/bin/activate
python start_server_direct.py

# 按 Ctrl+A 然后按 D 退出 screen（服务继续运行）

# 重新连接 screen
screen -r langgraph


方式4: 使用 tmux

# 创建 tmux 会话
tmux new -s langgraph

# 在 tmux 中启动
cd ~/langgraph
source venv/bin/activate
python start_server_direct.py

# 按 Ctrl+B 然后按 D 退出 tmux（服务继续运行）

# 重新连接 tmux
tmux attach -t langgraph


五、验证部署

# 检查服务是否运行
curl http://localhost:2025/ok

# 或从外部访问（替换为你的服务器IP）
curl http://服务器IP:2025/ok

# 查看日志
tail -f ~/langgraph/logs/app.log

# 检查进程
ps aux | grep start_server_direct


六、进程管理


查看进程

# 查看进程ID
cat ~/langgraph/logs/app.pid

# 查看进程状态
ps -p $(cat ~/langgraph/logs/app.pid 2>/dev/null)


停止服务

# 如果使用启动脚本
~/langgraph/deploy/stop.sh

# 如果使用 nohup
kill $(cat ~/langgraph/logs/app.pid)

# 如果使用 screen
screen -S langgraph -X quit

# 如果使用 tmux
tmux kill-session -t langgraph

# 手动查找并杀死进程
ps aux | grep start_server_direct | grep -v grep | awk '{print $2}' | xargs kill


重启服务

# 使用启动脚本
~/langgraph/deploy/restart.sh

# 或手动停止后重新启动
./deploy/stop.sh
./deploy/start.sh


七、更新代码

cd ~/langgraph

# 停止服务
./deploy/stop.sh

# 更新代码（根据你的方式）
git pull
# 或重新上传文件

# 更新依赖（如果有新依赖）
source venv/bin/activate
pip install -r requirements.txt

# 重启服务
./deploy/start.sh


八、日志管理

# 查看实时日志
tail -f ~/langgraph/logs/app.log

# 查看最近100行
tail -n 100 ~/langgraph/logs/app.log

# 查看错误日志
grep -i error ~/langgraph/logs/app.log

# 清空日志（谨慎使用）
> ~/langgraph/logs/app.log


九、开机自启（可选）


方法1: 添加到 ~/.bashrc 或 ~/.profile

# 编辑 ~/.bashrc
vim ~/.bashrc

# 添加以下内容（如果是交互式登录，使用 ~/.profile）
if [ -f ~/langgraph/deploy/start.sh ]; then
    ~/langgraph/deploy/start.sh
fi


注意：这种方法会在每次登录时启动，可能不是最佳选择。


方法2: 使用 cron（推荐）

# 编辑 crontab
crontab -e

# 添加以下行（服务器重启后自动启动）
@reboot sleep 30 && /bin/bash ~/langgraph/deploy/start.sh


十、故障排查


服务无法启动

# 检查 Python 环境
cd ~/langgraph
source venv/bin/activate
python --version
which python

# 检查依赖
pip list | grep langgraph

# 手动测试启动
python start_server_direct.py


端口被占用

# 查看端口占用
lsof -i :2025
# 或
netstat -tlnp | grep 2025

# 杀死占用进程
kill -9 <PID>


无法访问服务


检查防火墙：确认阿里云安全组已开放端口 2025

检查服务状态：ps aux | grep start_server_direct


检查日志：tail -f ~/langgraph/logs/app.log


测试本地访问：curl http://localhost:2025/ok


API 密钥错误

# 检查 .env 文件
cat ~/langgraph/.env

# 测试环境变量
cd ~/langgraph
source venv/bin/activate
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('OPENAI_API_KEY'))"


常用命令速查

# 启动服务
~/langgraph/deploy/start.sh

# 停止服务
~/langgraph/deploy/stop.sh

# 重启服务
~/langgraph/deploy/restart.sh

# 查看状态
ps aux | grep start_server_direct | grep -v grep

# 查看日志
tail -f ~/langgraph/logs/app.log

# 测试服务
curl http://localhost:2025/ok


注意事项


端口权限：端口 2025 > 1024，普通用户可以使用，无需 root

目录权限：确保 ~/langgraph 目录有读写权限

日志轮转：定期清理日志文件，避免占用过多磁盘空间

进程监控：建议定期检查进程是否正常运行

备份：定期备份代码和 .env 文件


部署检查清单


 代码已上传到 ~/langgraph


 虚拟环境已创建

 依赖已安装

 .env 文件已配置 API 密钥

 服务已启动

 可以访问 http://服务器IP:2025/ok


 日志输出正常

 阿里云安全组已开放端口 2025