guoyu/外网部署指南.md

# 国语教育平台 - 外网服务器部署指南

> **部署环境**: Windows Server + 宝塔面板 + 外网访问
> **更新日期**: 2025-12-09
> **版本**: 1.3.9

---

## 📋 部署前准备清单

### 1. 服务器环境要求

```
✅ 操作系统: Windows Server（已有）
✅ 面板工具: 宝塔面板（已安装）
✅ Java环境: JDK 1.8+ 或 JDK 11+
✅ 数据库: MySQL 5.7+ 或 MySQL 8.0
✅ 缓存: Redis 6.0+
✅ 网络: 能访问百度云API（语音识别必需）
```

### 2. 关键信息收集

需要提前准备的信息：

| 项目 | 说明 | 示例 |
|------|------|------|
| **服务器IP/域名** | 外网可访问的地址 | `123.45.67.89` 或 `api.example.com` |
| **后端端口** | Spring Boot端口 | `30091`（建议保持不变） |
| **课件存储路径** | 视频/音频文件存储位置 | `D:\wwwroot\study_web\web\profile` |
| **数据库地址** | MySQL连接信息 | `localhost:3306` |
| **Redis地址** | Redis连接信息 | `localhost:6379` |
| **百度API密钥** | 语音识别所需 | App ID + API Key + Secret Key |

---

## 🔧 步骤1：服务器端配置

### 1.1 创建目录结构

在服务器上创建以下目录：

```powershell
# 课件存储目录（必须与application.yml中profile配置一致）
mkdir D:\wwwroot\study_web\web\profile
mkdir D:\wwwroot\study_web\web\profile\upload

# 确保目录有读写权限
icacls D:\wwwroot\study_web\web\profile /grant Everyone:F /T
```

### 1.2 修改后端配置文件

编辑 `ry-study-admin/src/main/resources/application.yml`：

```yaml
# 项目相关配置
ruoyi:
  # 文件路径（⚠️ 重要：必须与服务器实际路径一致）
  profile: D:\wwwroot\study_web\web\profile

# 服务器配置
server:
  port: 30091  # 保持不变（APP默认使用此端口）

# Spring配置
spring:
  # Redis配置
  redis:
    host: 127.0.0.1  # 如果Redis在本机，使用localhost
    port: 6379
    password:  # 如果Redis设置了密码，填写在这里
    
  # 数据库配置（在application-druid.yml中）
```

编辑 `ry-study-admin/src/main/resources/application-druid.yml`：

```yaml
spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/ry_study?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        username: root  # ⚠️ 修改为实际数据库用户名
        password: your_password  # ⚠️ 修改为实际数据库密码
```

### 1.3 配置百度语音API

百度API配置存储在数据库的 `sys_config` 表中，需要确保以下配置项存在：

```sql
-- 在MySQL中执行，确保百度API配置存在
INSERT INTO sys_config (config_name, config_key, config_value, config_type, create_by, remark) 
VALUES 
('百度语音AppID', 'baidu.speech.appId', 'your_app_id', 'Y', 'admin', '百度语音识别AppID'),
('百度语音APIKey', 'baidu.speech.apiKey', 'your_api_key', 'Y', 'admin', '百度语音识别API Key'),
('百度语音SecretKey', 'baidu.speech.secretKey', 'your_secret_key', 'Y', 'admin', '百度语音识别Secret Key')
ON DUPLICATE KEY UPDATE config_value = VALUES(config_value);
```

**⚠️ 重要**: 
- 百度API密钥需要在 [百度AI开放平台](https://ai.baidu.com/) 申请
- 服务器必须能访问百度云API（测试：`ping aip.baidubce.com`）

### 1.4 宝塔面板部署Java项目

#### 方式A：使用宝塔Java项目管理器（推荐）

1. **安装Java环境**
   - 宝塔面板 → 软件商店 → 搜索"Tomcat" → 安装（会自动安装JDK）
   - 或者软件商店 → 搜索"Java项目管理器" → 安装

2. **添加Java项目**
   - 宝塔面板 → 网站 → Java项目
   - 项目名称：`ry-study-admin`
   - 项目路径：上传JAR包所在目录
   - 项目类型：`Jar`
   - 启动文件：`ry-study-admin.jar`
   - 启动端口：`30091`
   - 启动命令：
     ```bash
     java -jar -Xms512m -Xmx1024m ry-study-admin.jar
     ```

3. **配置防火墙**
   - 宝塔面板 → 安全 → 添加端口规则
   - 端口：`30091`
   - 协议：`TCP`
   - 备注：`国语教育平台后端`

#### 方式B：手动部署（备选）

1. **上传JAR包**
   ```powershell
   # 将编译好的JAR包上传到服务器
   # 路径示例：D:\www\java\ry-study-admin.jar
   ```

2. **创建启动脚本** (`start.bat`)
   ```bat
   @echo off
   title 国语教育平台后端服务
   java -jar -Xms512m -Xmx1024m ry-study-admin.jar
   pause
   ```

3. **创建Windows服务**（可选，实现开机自启）
   - 使用工具：[NSSM](https://nssm.cc/download) (Non-Sucking Service Manager)
   ```powershell
   # 下载nssm.exe后
   nssm install RyStudyService "java" "-jar D:\www\java\ry-study-admin.jar"
   nssm set RyStudyService AppDirectory "D:\www\java"
   nssm set RyStudyService Description "国语教育平台后端服务"
   nssm start RyStudyService
   ```

### 1.5 测试后端服务

```powershell
# 测试服务是否启动
curl http://localhost:30091

# 测试API接口
curl http://localhost:30091/api/system/config/configKey/sys.user.initPassword
```

---

## 📱 步骤2：APP端配置

### 2.1 方案A：打包时配置服务器地址（推荐）

修改 `fronted_uniapp/utils/config.js` 第43行：

```javascript
// ⚠️ 正式部署：修改为服务器的公网IP或域名
const DEFAULT_SERVER_HOST = 'your_server_ip_or_domain'  // 例如：'123.45.67.89' 或 'api.example.com'
const DEFAULT_SERVER_PORT = 30091
```

然后重新打包APK（版本号升级到1.3.10）。

### 2.2 方案B：APP运行时动态配置（灵活）

APP支持运行时配置服务器地址（无需重新打包）：

1. **通过代码设置**（在APP启动时）
   ```javascript
   // 在App.vue的onLaunch中添加
   uni.setStorageSync('server_host', 'your_server_ip')
   uni.setStorageSync('server_port', 30091)
   ```

2. **通过设置页面**（需要实现UI）
   - 在APP中添加"服务器设置"页面
   - 让用户输入服务器地址
   - 调用 `config.setServerConfig(host, port)` 保存

### 2.3 测试APP连接

安装APK后：

1. 打开APP，进入"我的" → "设置" → "关于"
2. 查看服务器地址是否正确
3. 尝试登录，测试网络连接

---

## ✅ 步骤3：功能验证清单

部署完成后，逐项测试：

### 3.1 基础功能测试

- [ ] **登录功能**
  - 能否正常登录
  - Token能否正常获取

- [ ] **课程列表**
  - 能否加载课程列表
  - 图标能否正常显示（离线测试：关闭网络）

### 3.2 视频播放测试

- [ ] **视频加载**
  - 课件能否正常加载
  - 视频播放是否流畅

- [ ] **路径检查**
  - 视频URL格式：`http://your_server:30091/profile/upload/2024/12/09/xxx.mp4`
  - 确认路径中包含 `/profile/` 前缀

### 3.3 语音识别测试（关键）

- [ ] **环境检查**
  - 服务器能否访问百度API：
    ```powershell
    # 在服务器上测试
    ping aip.baidubce.com
    Test-NetConnection -ComputerName aip.baidubce.com -Port 443
    ```

- [ ] **配置检查**
  - 数据库中百度API密钥已配置
  - 密钥是否有效（在百度控制台查看）

- [ ] **功能测试**
  - 进入"语音测评"页面
  - 录音并识别，查看结果
  - 检查后端日志是否有错误

### 3.4 后端日志检查

在宝塔面板或服务器上查看日志：

```powershell
# 日志位置（根据实际情况调整）
# 通常在JAR包同目录下的logs文件夹
tail -f D:\www\java\logs\sys-info.log
```

关键日志内容：
```
收到语音识别请求 - 格式: pcm
调用百度云API识别，格式: pcm...
识别成功: xxx
```

---

## ⚠️ 常见问题排查

### 问题1：APP无法连接服务器

**症状**: 登录时提示"网络错误"或"服务器无响应"

**排查步骤**:
1. 确认服务器防火墙已开放30091端口
2. 确认服务器公网IP/域名是否正确
3. 用手机浏览器访问：`http://your_server:30091`
4. 检查APP中服务器地址配置是否正确

### 问题2：视频无法播放

**症状**: 点击视频课件，显示加载失败

**排查步骤**:
1. 检查课件文件是否存在于：`D:\wwwroot\study_web\web\profile\upload\...`
2. 检查目录权限（Everyone需要读取权限）
3. 检查数据库中file_path字段是否包含 `/profile/` 前缀
4. 用浏览器直接访问视频URL测试

### 问题3：语音识别失败

**症状**: 录音后提示"识别失败"或"param format invalid"

**排查步骤**:
1. **服务器网络检查**:
   ```powershell
   ping aip.baidubce.com
   ```
   如果ping不通，检查服务器网络或防火墙设置

2. **百度API配置检查**:
   - 登录百度AI开放平台查看API密钥是否正确
   - 查看API调用次数是否已用完
   - 确认已开通"短语音识别"服务

3. **后端日志检查**:
   查看是否有 `param format invalid` 错误
   - 如果有，说明格式问题（APP需使用1.3.9版本）

4. **APP版本检查**:
   - 确认使用1.3.9或更高版本
   - 低版本可能使用mp3格式（不支持）

### 问题4：图标显示为方框

**症状**: APP中图标显示为 □

**排查步骤**:
1. 确认使用1.3.9或更高版本APK
2. 在离线环境（关闭网络）测试
3. 如果仍不显示，需要重新打包APK

### 问题5：宝塔部署Java项目失败

**症状**: Java项目无法启动或频繁重启

**排查步骤**:
1. 检查JDK版本：`java -version`（需要1.8+）
2. 检查端口占用：`netstat -ano | findstr 30091`
3. 查看启动日志，查找错误信息
4. 检查MySQL/Redis是否正常运行

---

## 🔐 安全建议

### 生产环境必做配置

1. **修改默认密码**
   - 管理员账号默认密码需修改
   - 数据库root密码需强化

2. **关闭调试模式**
   ```yaml
   # application.yml
   swagger:
     enabled: false  # 关闭Swagger文档
   
   logging:
     level:
       com.ddnai: info  # 改为info级别
   ```

3. **配置HTTPS**（可选但推荐）
   - 申请SSL证书
   - 宝塔面板 → 网站 → SSL → 配置证书
   - 修改APP配置使用HTTPS

4. **防火墙配置**
   - 只开放必要端口（80, 443, 30091）
   - 禁止直接暴露MySQL(3306)和Redis(6379)

---

## 📞 需要的额外信息

为了提供更精确的部署指导，请提供：

### 关于服务器

1. **服务器访问地址**
   - [ ] 公网IP：________________
   - [ ] 域名（如有）：________________
   - [ ] 已开放的端口：________________

2. **宝塔面板版本**
   - [ ] 宝塔版本：________________
   - [ ] 已安装的软件：Java版本____，MySQL版本____，Redis版本____

3. **课件文件**
   - [ ] 课件存储路径：________________
   - [ ] 课件总大小：________________
   - [ ] 是否需要迁移现有课件？ □是 □否

### 关于APP

1. **当前使用版本**
   - [ ] APK版本：________________
   - [ ] 是否需要修改服务器地址后重新打包？ □是 □否

2. **用户设备**
   - [ ] 用户网络环境：□公网 □内网 □两者都有
   - [ ] 是否需要支持离线使用？ □是 □否

### 关于百度API

1. **百度语音识别**
   - [ ] 是否已申请百度API？ □是 □否
   - [ ] App ID：________________
   - [ ] API Key：________________
   - [ ] Secret Key：________________

---

## 📋 部署检查清单

打印此清单，部署时逐项检查：

### 服务器端
- [ ] JDK已安装（版本≥1.8）
- [ ] MySQL已安装并运行
- [ ] Redis已安装并运行
- [ ] 课件目录已创建（`D:\wwwroot\study_web\web\profile`）
- [ ] 目录权限已设置
- [ ] application.yml配置已修改（profile路径）
- [ ] 数据库连接信息已配置
- [ ] 百度API密钥已配置（数据库）
- [ ] 防火墙已开放30091端口
- [ ] JAR包已上传
- [ ] 后端服务已启动
- [ ] 后端服务可访问（`http://localhost:30091`）

### APP端
- [ ] 服务器地址已配置（代码或运行时）
- [ ] APK已打包（版本1.3.9+）
- [ ] APK已安装到测试设备
- [ ] 能正常登录
- [ ] 图标显示正常（离线测试）
- [ ] 视频能正常播放
- [ ] 语音能正常识别

### 网络连通性
- [ ] 手机能访问服务器（浏览器测试）
- [ ] 服务器能访问百度API（`ping aip.baidubce.com`）
- [ ] 防火墙规则已配置

---

## 📝 部署记录模板

```
部署日期：________________
服务器IP：________________
端口：30091
课件路径：D:\wwwroot\study_web\web\profile
APP版本：1.3.9

测试结果：
□ 登录功能正常
□ 课程列表正常
□ 视频播放正常
□ 图标显示正常（离线）
□ 语音识别正常

遇到的问题：
1. ________________
2. ________________

解决方案：
1. ________________
2. ________________
```

---

## 🎯 快速部署摘要

如果您已经熟悉部署流程，可以按以下快速步骤操作：

```bash
# 1. 服务器准备
mkdir D:\wwwroot\study_web\web\profile
# 修改application.yml中的profile路径
# 配置数据库、Redis、百度API

# 2. 部署后端
# 上传JAR包
java -jar -Xms512m -Xmx1024m ry-study-admin.jar

# 3. 配置APP
# 修改config.js中的DEFAULT_SERVER_HOST
# 打包APK（版本1.3.10）

# 4. 测试
# 安装APK → 登录 → 测试图标/视频/语音
```

---

## 🆘 获取帮助

如果在部署过程中遇到问题，请提供：

1. **错误信息**：完整的错误日志或截图
2. **配置信息**：application.yml内容（脱敏后）
3. **测试结果**：哪些功能正常，哪些异常
4. **网络环境**：服务器IP、端口、防火墙设置

---

**部署完成后，请填写上方"需要的额外信息"部分，我可以提供更具体的指导！** 🚀