# Tolan 后端快速启动指南

## 📋 前置要求

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

## 🚀 快速启动

### 1. 安装依赖

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

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

### 2. 配置环境变量

创建 `.env` 文件：

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

```bash
# 豆包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密钥**:
1. 访问豆包开放平台
2. 注册并创建应用
3. 获取API Key和App ID

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

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

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

PORT=8000
DEBUG=True
```

系统会自动回退到模拟模式，适合：
- ✅ 前后端通信测试
- ✅ WebSocket流式传输测试  
- ✅ UI交互测试
- ❌ 真实AI对话（需要真实API）

详细配置说明: [ENV_CONFIG.md](./ENV_CONFIG.md)

### 3. 启动服务器

```bash
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. 验证服务

**浏览器访问**:
- 根路径: http://localhost:8000
- API文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

**命令行验证**:
```bash
# 健康检查
curl http://localhost:8000/health

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

## 📱 与前端联调

### 1. 确保后端正在运行

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

### 2. 启动前端

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

### 3. 测试连接

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

## 🔧 常用命令

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

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

### 生产模式启动

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

### 使用SSL启动（HTTPS/WSS）

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

### 查看日志

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

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

## 🐛 故障排查

### 问题1: 端口被占用

**错误**: `Address already in use`

**解决**:
```bash
# 查找占用端口的进程
lsof -i :8000

# 杀死进程
kill -9 <PID>

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

### 问题2: 导入错误

**错误**: `ModuleNotFoundError`

**解决**:
```bash
# 确认依赖已安装
pip list | grep fastapi

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

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

**错误**: 连接池创建失败

**解决**:
1. 检查豆包API配置（如果使用）
2. 查看详细日志
3. 暂时使用模拟API（当前默认）

### 问题4: WebSocket连接失败

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

**解决**:
```bash
# 1. 确认后端运行
curl http://localhost:8000/health

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

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

## 📊 监控和调试

### 实时监控

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

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

### 调试模式

在 `.env` 中设置：
```bash
DEBUG=True
LOG_LEVEL=DEBUG
```

### 性能测试

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

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

## 🔗 集成豆包API

### 替换模拟API

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

```python
# 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           # 🚀 本文件
```

## ✅ 下一步

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

## 💡 提示

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

## 📞 获取帮助

遇到问题？

1. 查看 [README.md](./README.md) 完整文档
2. 查看日志文件
3. 检查 [API文档](http://localhost:8000/docs)
4. 参考 [项目文档](../项目文档/)

---

**祝您使用愉快！🎉**