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 路径：

   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 后台

cd xunifriend_RaeeC\public
php -S 0.0.0.0:30100 router.php

启动 Python 后端

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

   ; 启用必需扩展
   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. 验证安装

   python --version
   pip --version
   

第三步：安装 MySQL

1. 下载 MySQL 8.0+

   • 官网: https://dev.mysql.com/downloads/mysql/

2. 安装并设置 root 密码

3. 创建数据库

   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 依赖

cd xunifriend_RaeeC
composer install

如果 composer 很慢，切换国内镜像：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

Python 依赖

cd 项目根目录
pip install -r lover/requirements.txt

如果 pip 很慢，使用国内镜像：

pip install -r lover/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

第五步：配置环境变量

1. 配置根目录 .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

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

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. 导入数据库

   mysql -u fastadmin -p fastadmin < database.sql
   

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

第七步：设置文件权限

确保以下目录可写：

xunifriend_RaeeC/runtime/
xunifriend_RaeeC/public/uploads/
public/tts/

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

---

⚙️ 配置说明

核心配置项

数据库配置

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

可选配置

微信小程序

WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret

微信支付

WECHAT_PAY_MCHID=your_mchid
WECHAT_PAY_API_V3_KEY=your_api_v3_key

环信 IM

• 在 PHP 后台配置

---

🐛 常见问题

1. 端口被占用

错误信息: Address already in use

解决方法:

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

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

2. 数据库连接失败

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

检查清单:

• MySQL 服务是否启动
• 数据库用户名密码是否正确
• 数据库名称是否存在
• 防火墙是否阻止连接

解决方法:

# 检查 MySQL 服务
net start MySQL80

# 测试连接
mysql -u fastadmin -p

3. Python 依赖安装失败

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

解决方法:

# 升级 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. 取消注释（删除前面的分号）:

   extension=mysqli
   extension=pdo_mysql
   

3. 重启 PHP 服务

5. Composer 安装慢

解决方法:

# 切换阿里云镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 重新安装
composer install

6. 跨域问题

如果前端访问 API 出现跨域错误，检查 lover/main.py 中的 CORS 配置：

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 日志

# 启动时会在控制台输出日志
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: 从登录接口获取

调试模式

开发环境配置

APP_ENV=development
DEBUG=True

开发模式下：

• 自动跳过部分认证检查
• 显示详细错误信息
• 支持热重载

测试用户

开发模式下可以使用测试用户 ID：

X-User-Id: 70

数据库管理

推荐工具：

• Navicat (商业软件)
• DBeaver (免费开源)
• phpMyAdmin (Web 界面)

性能监控

查看数据库连接池

# 在 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/

常用命令

# 查看 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（如果有）

---

祝你使用愉快！ 🎉