Ai_GirlFriend/运行指南.md

# AI 虚拟恋人项目 - 运行指南

## 📋 目录
- [系统要求](#系统要求)
- [快速启动](#快速启动)
- [详细安装步骤](#详细安装步骤)
- [配置说明](#配置说明)
- [常见问题](#常见问题)
- [开发调试](#开发调试)

---

## 🖥️ 系统要求

### 必需环境
- **操作系统**: Windows 10/11
- **PHP**: 8.0+ (推荐 8.0.0)
- **Python**: 3.8+ (推荐 3.9+)
- **MySQL**: 5.7+ 或 8.0+
- **Composer**: 最新版本
- **浏览器**: Chrome/Edge (现代浏览器)

### 可选工具
- Git (版本控制)
- Postman (API 测试)

---

## 🚀 快速启动

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

1. **修改启动脚本配置**
   
   打开 `启动项目.bat`，修改 PHP 路径：
   ```batch
   set PHP_PATH=D:\2_part\php-8.0.0-Win32-vs16-x64\php.exe
   ```
   改为你的 PHP 安装路径

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

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

### 方式二：手动启动

#### 启动 PHP 后台
```cmd
cd xunifriend_RaeeC\public
php -S 0.0.0.0:30100 router.php
```

#### 启动 Python 后端
```cmd
cd 项目根目录
python -m uvicorn lover.main:app --host 0.0.0.0 --port 30101 --reload
```

---

## 📦 详细安装步骤

### 第一步：安装 PHP

1. 下载 PHP 8.0+
   - 官网: https://windows.php.net/download/
   - 选择 Thread Safe 版本

2. 解压到目录（如 `D:\php-8.0.0`）

3. 配置 php.ini
   ```ini
   ; 启用必需扩展
   extension=curl
   extension=fileinfo
   extension=gd
   extension=mbstring
   extension=mysqli
   extension=openssl
   extension=pdo_mysql
   extension=zip
   
   ; 设置时区
   date.timezone = Asia/Shanghai
   
   ; 上传限制
   upload_max_filesize = 100M
   post_max_size = 100M
   ```

4. 添加到系统 PATH（可选）

### 第二步：安装 Python

1. 下载 Python 3.9+
   - 官网: https://www.python.org/downloads/

2. 安装时勾选 "Add Python to PATH"

3. 验证安装
   ```cmd
   python --version
   pip --version
   ```

### 第三步：安装 MySQL

1. 下载 MySQL 8.0+
   - 官网: https://dev.mysql.com/downloads/mysql/

2. 安装并设置 root 密码

3. 创建数据库
   ```sql
   CREATE DATABASE fastadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'fastadmin'@'localhost' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON fastadmin.* TO 'fastadmin'@'localhost';
   FLUSH PRIVILEGES;
   ```

### 第四步：安装项目依赖

#### PHP 依赖
```cmd
cd xunifriend_RaeeC
composer install
```

如果 composer 很慢，切换国内镜像：
```cmd
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```

#### Python 依赖
```cmd
cd 项目根目录
pip install -r lover/requirements.txt
```

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

### 第五步：配置环境变量

#### 1. 配置根目录 .env
```env
# 应用环境
APP_ENV=development
DEBUG=True

# 数据库配置（修改为你的数据库信息）
DATABASE_URL=mysql+pymysql://fastadmin:your_password@localhost:3306/fastadmin?charset=utf8mb4

# PHP 后台地址
USER_INFO_API=http://127.0.0.1:30100/api/user_basic/get_user_basic

# 阿里云 DashScope API（必需，用于 AI 功能）
DASHSCOPE_API_KEY=your_dashscope_api_key

# OSS 配置（必需，用于文件存储）
ALIYUN_OSS_ACCESS_KEY_ID=your_access_key_id
ALIYUN_OSS_ACCESS_KEY_SECRET=your_access_key_secret
ALIYUN_OSS_BUCKET_NAME=your_bucket_name
ALIYUN_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
ALIYUN_OSS_CDN_DOMAIN=https://your_bucket.oss-cn-hangzhou.aliyuncs.com
```

#### 2. 配置 lover/.env
```env
DATABASE_URL=mysql+pymysql://fastadmin:your_password@localhost:3306/fastadmin?charset=utf8mb4
USER_INFO_API=http://127.0.0.1:30100/api/user_basic/get_user_basic
```

#### 3. 配置 xunifriend_RaeeC/.env
```env
app_debug = true
app_trace = false

[database]
type = mysql
hostname = localhost
database = fastadmin
username = fastadmin
password = your_password
hostport = 3306
charset = utf8mb4
prefix = nf_
debug = true
```

### 第六步：导入数据库

1. 找到数据库 SQL 文件（通常在项目根目录或 docs 文件夹）

2. 导入数据库
   ```cmd
   mysql -u fastadmin -p fastadmin < database.sql
   ```

3. 或使用 phpMyAdmin / Navicat 等工具导入

### 第七步：设置文件权限

确保以下目录可写：
```
xunifriend_RaeeC/runtime/
xunifriend_RaeeC/public/uploads/
public/tts/
```

Windows 下通常不需要特殊设置。

---

## ⚙️ 配置说明

### 核心配置项

#### 数据库配置
```env
DATABASE_URL=mysql+pymysql://用户名:密码@主机:端口/数据库名?charset=utf8mb4
```

#### AI 服务配置

**阿里云 DashScope（必需）**
- 注册地址: https://dashscope.console.aliyun.com/
- 获取 API Key 后填入 `DASHSCOPE_API_KEY`
- 用于：AI 对话、图像生成、语音合成、视频生成

**OSS 对象存储（必需）**
- 用于存储用户上传的图片、音频、视频
- 需要在阿里云开通 OSS 服务
- 配置项：
  - `ALIYUN_OSS_ACCESS_KEY_ID`
  - `ALIYUN_OSS_ACCESS_KEY_SECRET`
  - `ALIYUN_OSS_BUCKET_NAME`
  - `ALIYUN_OSS_ENDPOINT`

#### 可选配置

**微信小程序**
```env
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```

**微信支付**
```env
WECHAT_PAY_MCHID=your_mchid
WECHAT_PAY_API_V3_KEY=your_api_v3_key
```

**环信 IM**
- 在 PHP 后台配置

---

## 🐛 常见问题

### 1. 端口被占用

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

**解决方法**:
```cmd
# 查看占用端口的进程
netstat -ano | findstr :30100
netstat -ano | findstr :30101

# 终止进程（PID 为上面查到的进程号）
taskkill /F /PID 进程号
```

### 2. 数据库连接失败

**错误信息**: `OperationalError: (2003, "Can't connect to MySQL server")`

**检查清单**:
- [ ] MySQL 服务是否启动
- [ ] 数据库用户名密码是否正确
- [ ] 数据库名称是否存在
- [ ] 防火墙是否阻止连接

**解决方法**:
```cmd
# 检查 MySQL 服务
net start MySQL80

# 测试连接
mysql -u fastadmin -p
```

### 3. Python 依赖安装失败

**错误信息**: `ERROR: Could not find a version that satisfies the requirement`

**解决方法**:
```cmd
# 升级 pip
python -m pip install --upgrade pip

# 使用国内镜像
pip install -r lover/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 4. PHP 扩展缺失

**错误信息**: `Call to undefined function mysqli_connect()`

**解决方法**:
1. 打开 `php.ini`
2. 取消注释（删除前面的分号）:
   ```ini
   extension=mysqli
   extension=pdo_mysql
   ```
3. 重启 PHP 服务

### 5. Composer 安装慢

**解决方法**:
```cmd
# 切换阿里云镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 重新安装
composer install
```

### 6. 跨域问题

如果前端访问 API 出现跨域错误，检查 `lover/main.py` 中的 CORS 配置：
```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",  # 添加你的前端地址
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

### 7. TTS 音频无法访问

**问题**: 生成的语音文件 404

**解决方法**:
1. 确保 `public/tts/` 目录存在且可写
2. 检查 OSS 配置是否正确
3. 查看 Python 日志确认文件是否上传成功

---

## 🔧 开发调试

### 查看日志

#### Python 日志
```cmd
# 启动时会在控制台输出日志
python -m uvicorn lover.main:app --host 0.0.0.0 --port 30101 --reload --log-level debug
```

#### PHP 日志
```
xunifriend_RaeeC/runtime/log/
```

### API 测试

#### 使用 FastAPI 自动文档
访问: http://127.0.0.1:30101/docs

可以直接在浏览器中测试所有 API 接口

#### 使用 Postman

1. 导入 API 集合（如果有）
2. 设置环境变量：
   - `base_url`: http://127.0.0.1:30101
   - `token`: 从登录接口获取

### 调试模式

#### 开发环境配置
```env
APP_ENV=development
DEBUG=True
```

开发模式下：
- 自动跳过部分认证检查
- 显示详细错误信息
- 支持热重载

#### 测试用户
开发模式下可以使用测试用户 ID：
```
X-User-Id: 70
```

### 数据库管理

推荐工具：
- **Navicat** (商业软件)
- **DBeaver** (免费开源)
- **phpMyAdmin** (Web 界面)

### 性能监控

#### 查看数据库连接池
```python
# 在 lover/db.py 中添加日志
import logging
logger = logging.getLogger("sqlalchemy.pool")
logger.setLevel(logging.DEBUG)
```

#### 查看 API 响应时间
FastAPI 自动在响应头中包含处理时间

---

## 📞 技术支持

### 相关文档
- FastAPI: https://fastapi.tiangolo.com/
- ThinkPHP: https://www.thinkphp.cn/
- 阿里云 DashScope: https://help.aliyun.com/zh/dashscope/

### 常用命令

```cmd
# 查看 Python 版本
python --version

# 查看 PHP 版本
php -v

# 查看已安装的 Python 包
pip list

# 查看 Composer 包
composer show

# 清理 Python 缓存
find . -type d -name __pycache__ -exec rm -rf {} +

# 清理 PHP 缓存
cd xunifriend_RaeeC
php think clear
```

---

## 🎯 下一步

项目启动成功后，你可以：

1. **访问管理后台**
   - URL: http://127.0.0.1:30100/admin
   - 默认账号密码查看数据库 `nf_admin` 表

2. **查看 API 文档**
   - URL: http://127.0.0.1:30101/docs
   - 测试各个接口功能

3. **配置微信小程序**
   - 修改小程序 API 地址
   - 配置 AppID 和 AppSecret

4. **测试核心功能**
   - 用户注册登录
   - 创建虚拟恋人
   - AI 对话
   - 图像生成
   - 语音通话

---

## ⚠️ 生产环境部署

生产环境需要额外配置：

1. **使用 Nginx 反向代理**
2. **配置 HTTPS 证书**
3. **使用 Supervisor 管理进程**
4. **配置 Redis 缓存**
5. **设置日志轮转**
6. **配置数据库主从复制**
7. **启用 CDN 加速**

详细部署文档请参考 `部署指南.md`（如果有）

---

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