Tolan 后端快速启动指南

📋 前置要求

Python >= 3.9
pip
豆包API密钥（可选，测试时使用模拟API）

🚀 快速启动

1. 安装依赖

cd /Users/wuzilong/work/00code/Tolan/backend

# 使用本机Python环境安装依赖
pip install -r requirements.txt

2. 配置环境变量

创建 .env 文件：

选项1: 使用真实豆包API（推荐）

# 豆包API配置（必填）
DOUBAO_API_KEY=your_api_key_here
DOUBAO_APP_ID=your_app_id_here

# 服务器配置
HOST=0.0.0.0
PORT=8000
DEBUG=True

# 连接池配置
CONNECTION_POOL_SIZE=10

如何获取豆包API密钥:

访问豆包开放平台
注册并创建应用
获取API Key和App ID

选项2: 使用模拟API（测试）

如果暂时没有豆包API密钥，可以不配置或留空：

# 留空将自动使用模拟API
# DOUBAO_API_KEY=
# DOUBAO_APP_ID=

PORT=8000
DEBUG=True

系统会自动回退到模拟模式，适合：

✅ 前后端通信测试
✅ WebSocket流式传输测试
✅ UI交互测试
❌ 真实AI对话（需要真实API）

详细配置说明: ENV_CONFIG.md

3. 启动服务器

python main.py

你会看到类似的输出：

============================================================
Tolan Voice Assistant v1.0.0 正在启动...
============================================================
2025-10-08 10:00:00 | INFO | 开始初始化连接池，创建 10 个连接...
2025-10-08 10:00:01 | SUCCESS | ✓ 连接池初始化成功
============================================================
应用启动完成！
服务地址: http://0.0.0.0:8000
API文档: http://0.0.0.0:8000/docs
WebSocket: ws://0.0.0.0:8000/ws/realtime
============================================================

4. 验证服务

浏览器访问:

命令行验证:

# 健康检查
curl http://localhost:8000/health

# 输出示例:
{
  "status": "healthy",
  "timestamp": 1696752000000,
  "connection_pool": {
    "initialized": true,
    "pool_size": 10,
    "idle": 10,
    "active": 0
  },
  "active_sessions": 0
}

📱 与前端联调

1. 确保后端正在运行

# 检查服务状态
curl http://localhost:8000/health

2. 启动前端

# 在新终端中
cd /Users/wuzilong/work/00code/Tolan/frontend
npm run dev

3. 测试连接

前端会自动连接到 ws://localhost:8000/ws/realtime

🔧 常用命令

开发模式启动（自动重载）

python main.py
# 或
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

生产模式启动

python -m uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

使用SSL启动（HTTPS/WSS）

# 确保SSL证书存在
python -m uvicorn main:app --host 0.0.0.0 --port 8443 \
  --ssl-keyfile=../ssl/key.pem \
  --ssl-certfile=../ssl/cert.pem

查看日志

# 实时查看日志
tail -f logs/app_*.log

# 查看最新日志
ls -lt logs/
tail -100 logs/app_2025-10-08_*.log

🐛 故障排查

问题1: 端口被占用

错误: Address already in use

解决:

# 查找占用端口的进程
lsof -i :8000

# 杀死进程
kill -9 <PID>

# 或使用其他端口
PORT=8001 python main.py

问题2: 导入错误

错误: ModuleNotFoundError

解决:

# 确认依赖已安装
pip list | grep fastapi

# 重新安装依赖
pip install -r requirements.txt

问题3: 连接池初始化失败

错误: 连接池创建失败

解决:

检查豆包API配置（如果使用）
查看详细日志
暂时使用模拟API（当前默认）

问题4: WebSocket连接失败

症状: 前端显示"连接中..."

解决:

# 1. 确认后端运行
curl http://localhost:8000/health

# 2. 检查防火墙
# macOS
sudo pfctl -d

# 3. 检查CORS配置
# 确保前端地址在config.py的CORS_ORIGINS中

📊 监控和调试

实时监控

# 监控日志
tail -f logs/app_*.log

# 监控连接
watch -n 1 'curl -s http://localhost:8000/health | python -m json.tool'

调试模式

在 .env 中设置：

DEBUG=True
LOG_LEVEL=DEBUG

性能测试

# 使用wscat测试WebSocket
npm install -g wscat
wscat -c ws://localhost:8000/ws/realtime

# 发送测试消息
> {"type":"init","payload":{"version":"1.0"}}

🔗 集成豆包API

替换模拟API

获取豆包API密钥
配置环境变量
修改 doubao_api/realtime_dialog_client.py
实现实际的API调用逻辑

# doubao_api/realtime_dialog_client.py
class RealtimeDialogClient:
    async def connect(self):
        # TODO: 实现实际连接逻辑
        # 参考 ../doubao-api/ 中的官方demo
        pass

📁 项目结构

backend/
├── main.py                  # ✅ 主应用入口
├── config.py                # ✅ 配置管理
├── connection_pool.py       # ✅ 连接池
├── websocket_handler.py     # ✅ WebSocket处理
├── doubao_api/             # ✅ 豆包API模块
│   ├── __init__.py
│   └── realtime_dialog_client.py
├── logs/                    # 📝 日志目录（自动创建）
├── requirements.txt         # 📦 依赖清单
├── README.md               # 📚 完整文档
└── QUICKSTART.md           # 🚀 本文件

✅ 下一步

✅ 后端服务已启动
✅ 连接池已初始化
✅ WebSocket端点可用
🔄 启动前端进行联调
🔄 集成实际豆包API

💡 提示

开发环境: 使用 DEBUG=True 获得详细日志
生产环境: 使用 SSL 和多进程部署
监控: 定期检查 /health 端点
日志: 出现问题先查看 logs/ 目录

📞 获取帮助

遇到问题？

查看 README.md 完整文档
查看日志文件
检查 API文档
参考项目文档

祝您使用愉快！🎉

QUICKSTART.md 6.0 KB Historik Rå