Ai_GirlFriend/完整启动指南.md

# AI 女友项目 - 完整启动指南

## 📋 项目架构

```
AI 女友项目
├── PHP 后端 (FastAdmin)     - 端口 30100
│   ├── 用户管理
│   ├── 后台管理
│   └── 基础 API
│
├── Python 后端 (FastAPI)    - 端口 30101
│   ├── AI 对话 (LLM)
│   ├── 语音识别 (ASR)
│   ├── 语音合成 (TTS)
│   ├── 图像生成
│   ├── 视频生成
│   └── 其他 AI 功能
│
└── 前端 (uni-app)
    ├── 小程序
    └── APP
```

## 🚀 启动步骤

### 方法 1：使用启动脚本（推荐）

1. **双击运行** `启动项目.bat`

2. **等待启动完成**
   - 会自动打开两个命令行窗口
   - PHP 服务器窗口
   - Python 后端窗口

3. **验证启动成功**
   - 浏览器会自动打开
   - PHP 后台：http://127.0.0.1:30100
   - Python API 文档：http://127.0.0.1:30101/docs

### 方法 2：手动启动

#### 启动 PHP 服务器

```bash
cd xunifriend_RaeeC/public
php -S 0.0.0.0:30100 router.php
```

#### 启动 Python 后端

```bash
# 在项目根目录
python -m uvicorn lover.main:app --host 0.0.0.0 --port 30101 --reload
```

## ✅ 验证服务状态

### 1. 检查端口占用

```bash
# Windows
netstat -ano | findstr :30100
netstat -ano | findstr :30101
```

应该看到：
```
TCP    0.0.0.0:30100    0.0.0.0:0    LISTENING    [PID]
TCP    0.0.0.0:30101    0.0.0.0:0    LISTENING    [PID]
```

### 2. 访问 API 文档

打开浏览器访问：

**Python API 文档**：http://127.0.0.1:30101/docs

应该看到 FastAPI 的 Swagger 文档界面，包含：
- `/voice/call/asr` - ASR 语音识别
- `/voice/call/conversation` - 完整语音对话
- `/chat/send` - 文字聊天
- 其他 AI 功能端点

**PHP 后台**：http://127.0.0.1:30100/admin

### 3. 测试健康检查

```bash
# Python 后端健康检查
curl http://127.0.0.1:30101/health
```

应该返回：
```json
{
  "code": 1,
  "msg": "ok",
  "data": {
    "status": "ok"
  }
}
```

## 🎯 测试语音对话功能

### 1. 在前端测试

1. 打开 uni-app 应用（小程序或 APP）
2. 进入语音通话页面
3. 按住"按住说话"按钮
4. 说话 2-3 秒："你好，今天天气怎么样？"
5. 松开按钮
6. 等待处理（约 5-10 秒）
7. 看到提示："你说: 你好，今天天气怎么样？"
8. 听到 AI 的语音回复

### 2. 查看日志

**Python 后端窗口**应该显示：
```
INFO - 收到语音对话请求，用户: XXX, 格式: wav
INFO - 音频数据大小: XXX 字节
INFO - 开始 ASR 识别...
INFO - 音频已上传: https://...
INFO - ASR 识别结果: 你好，今天天气怎么样？
INFO - 开始 LLM 对话生成...
INFO - LLM 回复: 今天天气很好哦...
INFO - 开始 TTS 语音合成...
INFO - TTS 合成完成，音频大小: XXX 字节
```

## 🔧 常见问题

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

**症状**：
```
[错误] 端口 30100 或 30101 已被占用
```

**解决方案**：

1. 使用启动脚本（会自动清理端口）
2. 或手动清理：

```bash
# 查找占用端口的进程
netstat -ano | findstr :30100
netstat -ano | findstr :30101

# 终止进程（替换 [PID] 为实际的进程 ID）
taskkill /F /PID [PID]
```

### 问题 2：Python 依赖缺失

**症状**：
```
ModuleNotFoundError: No module named 'xxx'
```

**解决方案**：

```bash
cd lover
pip install -r requirements.txt
```

### 问题 3：PHP 路径错误

**症状**：
```
[错误] PHP 未找到
```

**解决方案**：

编辑 `启动项目.bat`，修改 PHP 路径：
```bat
set PHP_PATH=D:\你的PHP路径\php.exe
```

### 问题 4：前端连接失败

**症状**：
前端显示"连接失败"或"网络错误"

**解决方案**：

1. 检查前端配置 `xuniYou/utils/request.js`：
```javascript
export const baseURL = 'http://192.168.1.141:30100'      // PHP
export const baseURLPy = 'http://192.168.1.141:30101'    // Python
```

2. 确保 IP 地址正确（局域网 IP 或 127.0.0.1）

3. 如果使用真机测试，确保手机和电脑在同一局域网

## 📱 前端配置

### 本地开发（电脑测试）

```javascript
// xuniYou/utils/request.js
export const baseURL = 'http://127.0.0.1:30100'
export const baseURLPy = 'http://127.0.0.1:30101'
```

### 局域网测试（手机测试）

```javascript
// xuniYou/utils/request.js
export const baseURL = 'http://192.168.1.141:30100'      // 替换为你的电脑 IP
export const baseURLPy = 'http://192.168.1.141:30101'
```

### 生产环境

```javascript
// xuniYou/utils/request.js
export const baseURL = 'http://你的域名:30100'
export const baseURLPy = 'http://你的域名:30101'
```

## 🔒 安全提示

### 开发环境

- ✅ 使用 `0.0.0.0` 监听所有网络接口
- ✅ 允许局域网访问
- ✅ 开启 CORS
- ✅ 开启调试日志

### 生产环境

- ⚠️ 使用 Nginx 反向代理
- ⚠️ 配置 HTTPS
- ⚠️ 限制 CORS 来源
- ⚠️ 关闭调试日志
- ⚠️ 使用环境变量管理敏感信息

## 📊 服务监控

### 查看服务状态

```bash
# Windows
tasklist | findstr php.exe
tasklist | findstr python.exe

# 查看端口
netstat -ano | findstr :30100
netstat -ano | findstr :30101
```

### 查看日志

- **PHP 日志**：在 PHP 服务器窗口查看
- **Python 日志**：在 Python 后端窗口查看
- **前端日志**：在浏览器控制台或 HBuilderX 控制台查看

## 🛑 停止服务

### 使用启动脚本启动的

直接关闭对应的命令行窗口即可：
- 关闭"PHP 服务器"窗口 → 停止 PHP 服务
- 关闭"Python 后端"窗口 → 停止 Python 服务

### 手动启动的

在对应的命令行窗口按 `Ctrl + C`

### 强制停止

```bash
# 停止所有 PHP 进程
taskkill /F /IM php.exe

# 停止所有 Python 进程（谨慎使用）
taskkill /F /IM python.exe
```

## 📝 启动检查清单

启动前确认：

- [ ] PHP 已安装并配置正确
- [ ] Python 已安装并配置正确
- [ ] Python 依赖已安装（`pip install -r lover/requirements.txt`）
- [ ] 环境变量已配置（`.env` 文件）
- [ ] 数据库已配置并可连接
- [ ] OSS 已配置（如需使用语音功能）
- [ ] DashScope API Key 已配置（如需使用 AI 功能）

启动后验证：

- [ ] PHP 服务器正常运行（端口 30100）
- [ ] Python 后端正常运行（端口 30101）
- [ ] 可以访问 API 文档（http://127.0.0.1:30101/docs）
- [ ] 健康检查通过（http://127.0.0.1:30101/health）
- [ ] 前端可以连接后端

## 🎉 启动成功！

如果以上步骤都完成，你应该看到：

```
╔════════════════════════════════════╗
║         启动成功！                 ║
╚════════════════════════════════════╝

[PHP 服务器] ✓ 已启动
→ http://127.0.0.1:30100
→ http://127.0.0.1:30100/admin

[Python 后端] ✓ 已启动
→ http://127.0.0.1:30101
→ http://127.0.0.1:30101/docs
```

现在可以开始使用 AI 女友的所有功能了！💕

---

**最后更新**: 2026-03-05
**版本**: v2.0