Ubuntu 服务器部署 MathModelAgent 全流程指南：配置 Nginx、Redis 与 Systemd

原项目地址:

专为数学建模设计的 Agent ,自动完成数学建模，生成一份完整的可以直接提交的论文。

配置环境:

1. ubantu 24.04tls镜像

2. deepseek v3 api

基础环境的配置

安装基础软件:

# 更新系统包
sudo apt update
sudo apt upgrade -y

# 安装基础工具
sudo apt install -y git curl wget build-essential

安装python 3.12:

Ubuntu 默认的 Python 版本可能低于项目要求，需要安装 Python 3.12 或更高版本：

# 安装依赖
sudo apt install -y software-properties-common

# 添加 deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# 安装 Python 3.12
sudo apt install -y python3.12 python3.12-venv python3.12-dev

# 验证安装
python3.12 --version

安装 Node.js 和 pnpm

# 安装 Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 验证 Node.js 安装
node --version
npm --version

# 安装 pnpm
npm install -g pnpm

# 验证 pnpm 安装
pnpm --version

安装Redis

# 安装 Redis
sudo apt install -y redis-server

# 启动 Redis 服务并设置开机自启
sudo systemctl start redis-server
sudo systemctl enable redis-server

# 验证 Redis 安装
redis-cli ping
# 应返回 PONG

如果出现以下错误:

安装uv（python依赖管理器）

apt install python3-pip

# 安装 uv
pip3 install uv

# 验证安装
uv --version

git原项目

# 克隆项目仓库
git clone https://github.com/jihe520/MathModelAgent.git

# 进入项目目录
cd MathModelAgent

后端配置

# 进入后端目录
cd backend

# 复制环境变量示例文件
cp .env.dev.example .env.dev

# 编辑环境变量文件
nano .env.dev

确保正确配置了如下内容:

ENV=dev API_KEY=your_llm_api_key

MODEL=your_preferred_model

REDIS_URL=redis://localhost:6379/0

注意6379一般不需要修改，因为6379是Redis的默认端口。

编辑完成后保存并退出nano编辑器。

安装后端依赖

两种uv安装 方法选择一种即可

# 使用 uv 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate
uv sync

# 或者使用传统方式
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

在完成如上依赖的安装后，执行启动后端命令。

# 确保在激活的虚拟环境中
# 启动后端服务
ENV=DEV uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws-ping-interval 60 --ws-ping-timeout 120

对于生产环境，推荐使用reload参数:

ENV=DEV uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws-ping-interval 60 --ws-ping-timeout 120 --reload

随后再IP+8000端口打开，如出现以下界面，表示后端部署成功。

设置后端服务自启动

# 创建服务文件
sudo nano /etc/systemd/system/mathmodelagent-backend.service

添加以下内容

[Unit]
Description=MathModelAgent Backend Service
After=network.target redis-server.service

[Service]
User=your_username
WorkingDirectory=/path/to/MathModelAgent/backend
Environment="ENV=DEV"
ExecStart=/path/to/MathModelAgent/backend/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws-ping-interval 60 --ws-ping-timeout 120
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

替换 your_username 和路径为实际值，然后：

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start mathmodelagent-backend

# 设置开机自启
sudo systemctl enable mathmodelagent-backend

# 检查状态
sudo systemctl status mathmodelagent-backend

前端的部署

配置前端的环境变量:

# 进入前端目录
cd ../frontend

# 复制环境变量示例文件
cp .env.example .env

# 编辑环境变量文件
nano .env

如果ip就是linux服务器本身，则不需要修改，保持否则需要调用服务器的ip API

前端依赖的安装:

# 使用 pnpm 安装依赖
pnpm i

以开发者模式启动前端:

# 开发模式启动
pnpm run dev

构建和部署前端(生产环境)

# 构建前端
pnpm run build

# 使用 nginx 或其他 web 服务器部署
sudo apt install -y nginx

# 配置 nginx
sudo nano /etc/nginx/sites-available/mathmodelagent

在nano编辑器中修改nginx的配置:

server {
    listen 80;
    server_name your_domain_or_ip;

    root /path/to/MathModelAgent/frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://localhost:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /ws {
        proxy_pass http://localhost:8000/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

替换 your_domain_or_ip 和路径为实际值 ，然后：

# 创建符号链接
sudo ln -s /etc/nginx/sites-available/mathmodelagent /etc/nginx/sites-enabled/

# 测试 nginx 配置
sudo nginx -t

# 重启 nginx
sudo systemctl restart nginx

docker部署

docker 环境的安装，安装docker 和docker compose:

# 安装 Docker
curl -fsSL https://get.docker.com | sudo sh

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 注销并重新登录以应用组更改
# 或者运行以下命令临时应用
newgrp docker

# 安装 Docker Compose
sudo apt install -y docker-compose

# 验证安装
docker --version
docker-compose --version

启动docker服务

# 在项目根目录下启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

一切配置成功后，在浏览器上以ip+5371（默认的端口，可以修改）打开网页，出现如下界面，代表部署成功。