# 🔧 故障排查指南

## 当前问题：PHP 返回 500 错误

### 问题现象
- 访问 http://127.0.0.1:30100 显示"您所浏览的页面暂时无法访问"
- PHP 服务日志显示 `[500]: GET /index/user/index.html`

---

## 🔍 排查步骤

### 第一步：运行诊断脚本

访问测试页面：
```
http://127.0.0.1:30100/test_db.php
```

这个页面会检查：
- ✅ PHP 版本和扩展
- ✅ 数据库连接
- ✅ 数据表列表
- ✅ ThinkPHP 框架文件
- ✅ Composer 依赖
- ✅ 目录权限

根据测试结果，找出具体问题。

---

### 第二步：检查 Composer 依赖

最常见的问题是 Composer 依赖未安装。

**检查方法：**
```cmd
cd xunifriend_RaeeC
dir vendor
```

如果 `vendor` 目录不存在或为空，需要安装依赖：

```cmd
cd xunifriend_RaeeC
composer install
```

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

---

### 第三步：检查 PHP 扩展

**查看已加载的扩展：**
```cmd
php -m
```

**必需的扩展：**
- mysqli
- pdo_mysql
- mbstring
- curl
- openssl
- fileinfo
- json

**如果缺少扩展，编辑 php.ini：**
1. 找到 PHP 安装目录下的 `php.ini` 文件
2. 搜索扩展名（如 `extension=mysqli`）
3. 删除前面的分号 `;` 取消注释
4. 保存文件
5. 重启 PHP 服务

---

### 第四步：检查数据库连接

**测试数据库连接：**
```cmd
mysql -u root -prootx77 -e "USE ai_friend; SELECT COUNT(*) FROM nf_user;"
```

**如果连接失败：**

1. **检查 MySQL 服务是否运行**
   ```cmd
   net start MySQL80
   ```

2. **检查密码是否正确**
   ```cmd
   mysql -u root -prootx77
   ```

3. **检查数据库是否存在**
   ```sql
   SHOW DATABASES;
   ```

4. **如果数据库不存在，创建它**
   ```sql
   CREATE DATABASE ai_friend CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

---

### 第五步：检查目录权限

**确保以下目录可写：**
```
xunifriend_RaeeC/runtime/
xunifriend_RaeeC/runtime/cache/
xunifriend_RaeeC/runtime/log/
xunifriend_RaeeC/public/uploads/
```

**Windows 下通常不需要特殊设置，但可以检查：**
1. 右键点击目录
2. 选择"属性"
3. 取消"只读"属性（如果勾选了）

---

### 第六步：查看 PHP 错误日志

**查看 ThinkPHP 日志：**
```
xunifriend_RaeeC/runtime/log/
```

打开最新的日志文件，查看错误信息。

**常见错误及解决方法：**

#### 错误 1: Class 'think\App' not found
**原因：** Composer 依赖未安装
**解决：**
```cmd
cd xunifriend_RaeeC
composer install
```

#### 错误 2: SQLSTATE[HY000] [2002] Connection refused
**原因：** 数据库连接失败
**解决：**
1. 检查 MySQL 服务是否运行
2. 检查 `.env` 文件中的数据库配置
3. 测试数据库连接

#### 错误 3: SQLSTATE[42S02]: Base table or view not found
**原因：** 数据表不存在
**解决：**
1. 确认数据库已导入
2. 检查表前缀是否正确（nf_）

#### 错误 4: Call to undefined function mysqli_connect()
**原因：** mysqli 扩展未启用
**解决：**
1. 编辑 php.ini
2. 取消注释 `extension=mysqli`
3. 重启 PHP 服务

---

## 🛠️ 快速修复方案

### 方案 1：重新安装 Composer 依赖

```cmd
cd xunifriend_RaeeC
rmdir /s /q vendor
composer install
```

### 方案 2：清理缓存

```cmd
cd xunifriend_RaeeC
rmdir /s /q runtime\cache
rmdir /s /q runtime\log
mkdir runtime\cache
mkdir runtime\log
```

### 方案 3：重置数据库配置

编辑 `xunifriend_RaeeC/.env`，确保配置正确：
```env
[database]
type = mysql
hostname = localhost
database = ai_friend
username = root
password = rootx77
hostport = 3306
charset = utf8mb4
prefix = nf_
debug = true
```

### 方案 4：使用简化的测试页面

访问：http://127.0.0.1:30100/test.php

查看是否能正常访问 PHP。

---

## 📋 完整检查清单

按顺序检查以下项目：

### PHP 环境
- [ ] PHP 版本 >= 8.0
- [ ] php.ini 已配置
- [ ] 必需扩展已启用
- [ ] PHP 可以正常运行

### Composer 依赖
- [ ] Composer 已安装
- [ ] vendor 目录存在
- [ ] 依赖包已安装完整

### 数据库
- [ ] MySQL 服务运行中
- [ ] 数据库 ai_friend 存在
- [ ] 用户名密码正确
- [ ] 数据表已导入（30+ 张表）
- [ ] 表前缀为 nf_

### 配置文件
- [ ] xunifriend_RaeeC/.env 存在
- [ ] 数据库配置正确
- [ ] 字符集为 utf8mb4

### 目录权限
- [ ] runtime 目录可写
- [ ] runtime/cache 目录可写
- [ ] runtime/log 目录可写
- [ ] public/uploads 目录可写

### ThinkPHP 框架
- [ ] thinkphp 目录存在
- [ ] application 目录存在
- [ ] install.lock 文件存在

---

## 🔄 重启服务

修改配置后，需要重启 PHP 服务：

1. 在 PHP 服务窗口按 `Ctrl+C` 停止
2. 重新运行启动脚本：
   ```cmd
   启动项目.bat
   ```

或者手动启动：
```cmd
cd xunifriend_RaeeC\public
php -S 0.0.0.0:30100 router.php
```

---

## 📞 仍然无法解决？

### 1. 查看详细错误信息

在 `xunifriend_RaeeC/.env` 中启用调试模式：
```env
app_debug = true
app_trace = true
```

重启服务后，错误信息会直接显示在浏览器中。

### 2. 查看日志文件

```
xunifriend_RaeeC/runtime/log/
```

打开最新的日志文件，查找错误堆栈。

### 3. 使用测试脚本

访问：http://127.0.0.1:30100/test_db.php

查看详细的环境检查结果。

### 4. 检查端口占用

```cmd
netstat -ano | findstr :30100
```

如果端口被占用，终止进程或更换端口。

---

## ✅ 成功标志

当以下条件都满足时，说明 PHP 后台已正常运行：

1. ✅ 访问 http://127.0.0.1:30100 不再显示 500 错误
2. ✅ 访问 http://127.0.0.1:30100/test_db.php 显示所有检查通过
3. ✅ PHP 服务日志显示 `[200]` 状态码
4. ✅ 可以访问管理后台 http://127.0.0.1:30100/admin

---

## 🎯 下一步

PHP 后台正常运行后：

1. **测试 Python 后端**
   访问：http://127.0.0.1:30101/docs

2. **测试 API 接口**
   在 API 文档中测试各个接口

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

4. **开始开发**
   根据需求修改代码

---

**记住：大多数 500 错误都是因为 Composer 依赖未安装！** 

先运行 `composer install`，90% 的问题都能解决。