启动本地后端服务指南

🚀 快速启动

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

# 在 mbe-desktop 目录下执行
cd d:\Mises\mbe-desktop
.\scripts\start-backend.ps1

方式 2: 手动启动

# 1. 进入后端项目目录
cd d:\Mises\mises-behavior-engine

# 2. 启动服务
python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

方式 3: 使用 Docker（端口 8001）

# 进入后端项目目录
cd d:\Mises\mises-behavior-engine

# 启动开发版 Docker 服务
.\scripts\start_dev.ps1

# 注意：Docker 版本使用 8001 端口
# 需要修改 Desktop .env: VITE_API_URL=http://localhost:8001

✅ 验证服务启动

启动后，在浏览器访问：

• 健康检查: http://localhost:8000/api/health
• API 文档: http://localhost:8000/docs

应该看到 JSON 响应或 Swagger 文档页面。

🔧 前置要求

1. Python 环境

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

# 安装依赖（首次运行）
cd d:\Mises\mises-behavior-engine
pip install -r requirements.txt

2. 数据库服务

选项 A: 使用本地 PostgreSQL

# 确保 PostgreSQL 运行在 localhost:5432
# 数据库名: mbe_dev
# 用户名: postgres
# 密码: postgres (根据您的配置)

选项 B: 使用 Docker 数据库

cd d:\Mises\mises-behavior-engine
docker-compose -f docker-compose.local-postgres.yml up -d

3. Redis 服务（可选）

# 如果使用 Redis，确保运行在 localhost:6379
# 或使用 Docker:
docker run -d -p 6379:6379 redis:alpine

📋 环境变量配置

后端服务会读取以下环境变量（可选）：

# 数据库连接
$env:DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/mbe_dev"

# Redis 连接
$env:REDIS_URL = "redis://localhost:6379"

# LLM API Key
$env:LLM_API_KEY = "your-api-key"

如果不设置，会使用 src/config.py 中的默认值。

🐛 常见问题

问题 1: 端口被占用

# 检查端口占用
netstat -ano | findstr :8000

# 杀死占用进程（替换 PID）
taskkill /PID <进程ID> /F

# 或使用其他端口
python -m uvicorn src.main:app --host 0.0.0.0 --port 8001

问题 2: 数据库连接失败

# 检查 PostgreSQL 是否运行
Get-Service postgresql*

# 或使用 Docker
docker ps | findstr postgres

问题 3: 模块导入错误

# 确保在项目根目录运行
cd d:\Mises\mises-behavior-engine

# 检查 Python 路径
python -c "import sys; print(sys.path)"

📝 启动日志示例

成功启动后应该看到：

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

最后更新: 2026-02-08