guoyu/Test/python/完整配置步骤.md

# Whisper 服务器端完整配置步骤

## 🎯 目标
让 Java 后端能够调用服务器上的 Whisper 服务进行语音识别

---

## 📋 前提条件
- ✅ 服务器已安装 openai-whisper
- ✅ 服务器已安装 ffmpeg
- ⚠️ 需要安装：flask、flask-cors

---

## 第一步：在服务器上安装剩余依赖

### 1. SSH 登录到服务器
```bash
ssh user@你的服务器IP
```

### 2. 配置 pip 使用清华镜像
```bash
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 安装 Flask 依赖
```bash
pip install flask==2.3.0 flask-cors==4.0.0 -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 4. 验证安装
```bash
pip list | grep -E "flask|whisper|cors"
```

应该看到：
```
flask              2.3.0
flask-cors         4.0.0
openai-whisper     (已安装的版本)
```

---

## 第二步：上传 whisper_server.py 到服务器

### 方式一：使用 SCP（推荐）
在**本地电脑**的 PowerShell 中执行：
```powershell
# 进入项目目录
cd C:\Users\Administrator\Desktop\Project\ry_study\Test\python

# 上传文件到服务器
scp whisper_server.py user@你的服务器IP:/home/user/whisper/
```

### 方式二：使用 FTP 工具
使用 FileZilla 或 WinSCP 将 `whisper_server.py` 上传到服务器任意目录

### 方式三：直接复制粘贴
```bash
# 在服务器上创建文件
vim /home/user/whisper/whisper_server.py

# 将本地的 whisper_server.py 内容复制粘贴进去
```

---

## 第三步：在服务器上启动 Whisper 服务

### 1. 进入文件目录
```bash
cd /home/user/whisper/
```

### 2. 测试运行（前台）
```bash
python whisper_server.py
```

看到以下输出说明启动成功：
```
============================================================
🎤 本地Whisper语音识别服务
============================================================
✅ 优势：
  1. 完全免费，无限次调用
  2. 离线运行，不需要网络
  ...
* Running on http://0.0.0.0:5001/
```

按 `Ctrl+C` 停止测试

### 3. 后台运行（生产环境）
```bash
nohup python whisper_server.py > whisper.log 2>&1 &
```

### 4. 查看运行状态
```bash
# 查看进程
ps aux | grep whisper_server

# 查看日志
tail -f whisper.log

# 查看端口
netstat -tunlp | grep 5001
```

---

## 第四步：配置防火墙开放端口

### CentOS/RHEL 服务器
```bash
# 开放 5001 端口
sudo firewall-cmd --permanent --add-port=5001/tcp

# 重载防火墙
sudo firewall-cmd --reload

# 查看已开放端口
sudo firewall-cmd --list-ports
```

### Ubuntu/Debian 服务器
```bash
# 开放 5001 端口
sudo ufw allow 5001/tcp

# 查看状态
sudo ufw status
```

### 阿里云/腾讯云等云服务器
还需要在**云控制台**的安全组规则中添加：
- 端口：5001
- 协议：TCP
- 授权对象：0.0.0.0/0 或指定 IP

---

## 第五步：验证服务可访问

### 1. 在服务器本地测试
```bash
curl http://localhost:5001/health
```

### 2. 从本地电脑测试
在**本地电脑** PowerShell 中执行：
```powershell
curl http://你的服务器IP:5001/health
```

### 3. 浏览器测试
打开浏览器访问：
```
http://你的服务器IP:5001/health
```

### 预期返回结果
```json
{
  "status": "ok",
  "service": "Whisper语音识别服务",
  "model": "base"
}
```

✅ **如果能看到这个返回，说明 Whisper 服务配置成功！**

---

## 第六步：配置 Java 后端连接

### 当前配置
Java 后端已配置为：`http://192.168.0.106:5001`

### 需要确认的事项

**情况 1：如果你的服务器 IP 是 192.168.0.106**
✅ 不需要修改，直接使用

**情况 2：如果服务器 IP 不是 192.168.0.106**
❌ 需要修改 Java 代码

修改文件：
```
Study-Vue-redis/ry-study-system/src/main/java/com/ddnai/system/service/voice/LocalWhisperService.java
```

修改第 36 行：
```java
private static final String WHISPER_URL = "http://你的服务器IP:5001";
```

---

## 第七步：重启 Java 应用

修改配置后，需要重启 Java 后端：

```bash
# 停止原来的服务
# 然后重新启动

# 或者如果使用了热部署，等待自动重启
```

---

## 第八步：测试完整流程

### 1. 查看 Java 后端日志
启动 Java 应用后，应该看到类似日志：
```
本地Whisper服务 可用 ✅
```

### 2. 测试语音评测功能
通过前端或 API 测试语音评测功能，查看是否能正常识别

---

## 🔧 故障排查

### 问题 1：curl 访问 5001 端口超时
**原因：** 防火墙未开放端口  
**解决：** 检查服务器防火墙和云安全组

### 问题 2：服务启动报错 "module 'whisper' has no attribute 'load_model'"
**原因：** 文件名冲突  
**解决：** 确保文件名是 `whisper_server.py` 而不是 `whisper.py`

### 问题 3：识别失败 "[WinError 2] 系统找不到指定的文件"
**原因：** 缺少 ffmpeg  
**解决：** 在服务器上安装 ffmpeg

### 问题 4：Java 连接不上 Whisper 服务
**原因：** IP 地址配置错误  
**解决：** 检查 `LocalWhisperService.java` 第 36 行的 IP 是否正确

---

## 📝 快速检查清单

在服务器上执行以下命令，确保一切就绪：

```bash
# 1. 检查 ffmpeg
ffmpeg -version

# 2. 检查 Python 包
pip list | grep -E "flask|whisper|cors"

# 3. 检查 Whisper 服务进程
ps aux | grep whisper_server

# 4. 检查端口监听
netstat -tunlp | grep 5001

# 5. 测试服务
curl http://localhost:5001/health
```

---

## ✅ 完成标志

当以下条件都满足时，配置完成：

- [x] 服务器上 pip 依赖已安装（flask、flask-cors）
- [x] whisper_server.py 已上传到服务器
- [x] Whisper 服务已启动（后台运行）
- [x] 端口 5001 可访问（curl 测试通过）
- [x] Java 后端 IP 配置正确
- [x] Java 应用已重启
- [x] 前端可以正常调用语音评测功能

---

## 🎯 你的服务器 IP 是多少？

**请告诉我你的服务器 IP 地址，我会检查 Java 配置是否需要修改。**

当前 Java 配置的 IP：`192.168.0.106`