Ai_GirlFriend/快速启动指南.md

# 🚀 快速启动指南

## ✅ 已完成的配置

### 1. 数据库配置 ✓
- **数据库名**: ai_friend
- **主机**: localhost:3306
- **用户名**: root
- **密码**: rootx77
- **数据表**: 已导入（30+ 张表，包含 nf_user, nf_lovers, nf_chat_message 等）

### 2. 环境变量配置 ✓
已配置三个 .env 文件：
- ✓ 根目录 `.env`
- ✓ `lover/.env`
- ✓ `xunifriend_RaeeC/.env`

所有文件已统一使用本地数据库配置。

---

## 📋 启动前最后检查

### 1. 安装 PHP
- [ ] 下载 PHP 8.5.3 (VS17 x64 Non Thread Safe)
- [ ] 解压到目录（如 `D:\php-8.5.3\`）
- [ ] 配置 php.ini（启用扩展）
- [ ] 修改 `启动项目.bat` 中的 PHP_PATH

### 2. 安装 Python 依赖
```cmd
pip install -r lover/requirements.txt
```

如果速度慢，使用国内镜像：
```cmd
pip install -r lover/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 安装 PHP 依赖
```cmd
cd xunifriend_RaeeC
composer install
```

如果速度慢，使用国内镜像：
```cmd
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
composer install
```

### 4. 验证数据库连接
```cmd
mysql -u root -prootx77 -e "USE ai_friend; SHOW TABLES;"
```

应该看到 30+ 张数据表。

---

## 🎯 启动项目

### 方式一：使用启动脚本（推荐）

1. **修改 PHP 路径**
   
   打开 `启动项目.bat`，修改第 6 行：
   ```batch
   set PHP_PATH=D:\php-8.5.3\php.exe
   ```
   改为你的 PHP 实际路径

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

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

4. **访问服务**
   - PHP 后台: http://127.0.0.1:30100
   - Python API: http://127.0.0.1:30101
   - API 文档: http://127.0.0.1:30101/docs

### 方式二：手动启动

#### 终端 1 - 启动 PHP 服务
```cmd
cd xunifriend_RaeeC\public
php -S 0.0.0.0:30100 router.php
```

#### 终端 2 - 启动 Python 服务
```cmd
python -m uvicorn lover.main:app --host 0.0.0.0 --port 30101 --reload
```

---

## 🧪 测试服务

### 1. 测试 PHP 后台
浏览器访问: http://127.0.0.1:30100

应该看到网站首页或登录页面。

### 2. 测试 Python API
浏览器访问: http://127.0.0.1:30101/docs

应该看到 FastAPI 自动生成的 API 文档页面。

### 3. 测试健康检查
浏览器访问: http://127.0.0.1:30101/health

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

### 4. 测试数据库连接
在 API 文档页面 (http://127.0.0.1:30101/docs)：
- 找到任意 GET 接口
- 点击 "Try it out"
- 点击 "Execute"
- 如果返回数据（不是 500 错误），说明数据库连接成功

---

## 🔧 PHP 配置清单

### 必需的 PHP 扩展

编辑 `php.ini` 文件，确保以下扩展已启用（删除前面的分号）：

```ini
extension=curl
extension=fileinfo
extension=gd
extension=mbstring
extension=mysqli
extension=openssl
extension=pdo_mysql
extension=zip
```

### 其他重要配置

```ini
; 时区设置
date.timezone = Asia/Shanghai

; 上传限制
upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300

; 内存限制
memory_limit = 256M
```

---

## 📦 Python 依赖列表

项目需要以下 Python 包（已在 requirements.txt 中）：

```
fastapi>=0.110          # Web 框架
uvicorn[standard]>=0.24 # ASGI 服务器
sqlalchemy>=2.0         # ORM
pymysql>=1.1            # MySQL 驱动
pydantic>=2.6           # 数据验证
pydantic-settings>=2.1  # 配置管理
python-dotenv>=1.0      # 环境变量
requests>=2.31          # HTTP 客户端
oss2>=2.18              # 阿里云 OSS
dashscope>=1.20         # 阿里云 AI
pyyaml>=6.0             # YAML 解析
imageio-ffmpeg>=0.4     # 视频处理
```

---

## ⚠️ 常见问题快速解决

### 问题 1: 端口被占用
```cmd
# 查看占用进程
netstat -ano | findstr :30100
netstat -ano | findstr :30101

# 终止进程
taskkill /F /PID 进程号
```

### 问题 2: 数据库连接失败
检查：
1. MySQL 服务是否启动
2. 用户名密码是否正确（root / rootx77）
3. 数据库名称是否正确（ai_friend）

```cmd
# 启动 MySQL 服务
net start MySQL80

# 测试连接
mysql -u root -prootx77
```

### 问题 3: Python 模块未找到
```cmd
# 重新安装依赖
pip install -r lover/requirements.txt --force-reinstall
```

### 问题 4: PHP 扩展缺失
```cmd
# 查看已加载的扩展
php -m

# 如果缺少扩展，编辑 php.ini 启用
```

### 问题 5: Composer 安装失败
```cmd
# 清理缓存
composer clear-cache

# 使用国内镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 重新安装
cd xunifriend_RaeeC
composer install
```

---

## 🎨 管理后台登录

### 默认管理员账号

查看数据库获取管理员账号：
```sql
SELECT username, password FROM nf_admin LIMIT 1;
```

如果没有管理员账号，可以手动创建：
```sql
INSERT INTO nf_admin (username, password, nickname, email, status) 
VALUES ('admin', MD5('admin123'), '管理员', 'admin@example.com', 'normal');
```

然后访问: http://127.0.0.1:30100/admin

---

## 📱 API 接口测试

### 使用 API 文档测试

1. 访问: http://127.0.0.1:30101/docs
2. 展开任意接口
3. 点击 "Try it out"
4. 填写参数
5. 点击 "Execute"
6. 查看响应结果

### 主要接口分类

- **/api/user** - 用户管理
- **/api/lover** - 虚拟恋人
- **/api/chat** - AI 对话
- **/api/voice_call** - 语音通话
- **/api/outfit** - 服装系统
- **/api/dance** - 舞蹈视频
- **/api/sing** - AI 唱歌
- **/api/dynamic** - 动态朋友圈
- **/api/friend** - 好友系统

---

## 🔐 开发模式说明

当前配置为开发模式：
```env
APP_ENV=development
DEBUG=True
```

开发模式特性：
- ✅ 详细的错误信息
- ✅ 自动跳过部分认证（方便测试）
- ✅ 热重载（代码修改自动生效）
- ✅ 可使用测试用户 ID

### 测试用户

在开发模式下，可以使用 Header 传递用户 ID：
```
X-User-Id: 70
```

这样可以跳过 Token 验证，直接测试接口。

---

## 📊 数据库表说明

### 核心表
- `nf_user` - 用户基础信息
- `nf_lovers` - 虚拟恋人档案
- `nf_chat_session` - 聊天会话
- `nf_chat_message` - 聊天消息
- `nf_chat_fact` - 长期记忆

### 功能表
- `nf_outfit_items` - 服装商品
- `nf_voice_library` - 声音库
- `nf_song_library` - 歌曲库
- `nf_motion_templates` - 舞蹈模板
- `nf_generation_tasks` - AI 生成任务

### 社交表
- `nf_friend_relations` - 好友关系
- `nf_dynamics` - 动态内容
- `nf_dynamic_likes` - 点赞
- `nf_dynamic_comments` - 评论

---

## 🎯 下一步操作

启动成功后，建议按以下顺序测试：

1. **访问 API 文档**
   http://127.0.0.1:30101/docs

2. **测试健康检查**
   http://127.0.0.1:30101/health

3. **访问 PHP 后台**
   http://127.0.0.1:30100/admin

4. **测试用户接口**
   在 API 文档中测试 `/api/user` 相关接口

5. **测试 AI 功能**
   测试聊天、图像生成等 AI 接口

---

## 📞 需要帮助？

如果遇到问题：

1. **查看日志**
   - Python 日志：启动窗口的控制台输出
   - PHP 日志：`xunifriend_RaeeC/runtime/log/`

2. **检查配置**
   - 数据库连接是否正确
   - PHP 扩展是否启用
   - Python 依赖是否安装

3. **参考文档**
   - `运行指南.md` - 详细安装教程
   - `启动前检查清单.md` - 逐项检查清单

---

**准备好了吗？开始启动项目吧！** 🚀

```cmd
启动项目.bat
```