docs: 添加前后端项目README文档
添加华为交互数字人前后端项目的详细README文档，包含项目说明、功能说明、环境配置、快速开始指南、目录结构、配置选项、事件监听、调试技巧和注意事项等内容，帮助开发者快速了解和使用项目
This commit is contained in:
125
backend/server/README.md
Normal file
125
backend/server/README.md
Normal file
@@ -0,0 +1,125 @@
|
|||||||
|
# 华为交互数字人后端服务
|
||||||
|
|
||||||
|
> **项目说明**：本项目是华为交互数字人 HwICSUiSdk 标准集成项目的定制化开发版本，专为**安特威**公司打造，由**江苏云上企数字科技有限公司**研发。
|
||||||
|
|
||||||
|
## 功能说明
|
||||||
|
|
||||||
|
后端服务主要为前端提供以下功能：
|
||||||
|
|
||||||
|
1. **获取授权码** - 调用华为云 MetaStudio API 获取一次性授权码，用于前端 SDK 初始化
|
||||||
|
|
||||||
|
## 环境配置
|
||||||
|
|
||||||
|
### 1. 配置环境变量
|
||||||
|
|
||||||
|
复制 `.env.example` 文件为 `.env`：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
编辑 `.env` 文件，填入您的华为云凭证：
|
||||||
|
|
||||||
|
```env
|
||||||
|
HUAWEI_AK=your_access_key_here
|
||||||
|
HUAWEI_SK=your_secret_key_here
|
||||||
|
HUAWEI_PROJECT_ID=your_project_id_here
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 获取华为云凭证
|
||||||
|
|
||||||
|
#### AK/SK（推荐）
|
||||||
|
|
||||||
|
1. 登录 [华为云控制台](https://console.huaweicloud.com)
|
||||||
|
2. 进入 "我的凭证" > "访问密钥"
|
||||||
|
3. 创建或下载访问密钥
|
||||||
|
|
||||||
|
#### 项目 ID
|
||||||
|
|
||||||
|
1. 登录华为云控制台
|
||||||
|
2. 进入 "我的凭证" > "项目 ID"
|
||||||
|
3. 或访问 [获取项目ID](https://support.huaweicloud.com/api-metastudio/metastudio_02_0006.html)
|
||||||
|
|
||||||
|
## 启动服务
|
||||||
|
|
||||||
|
### 安装依赖
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 启动服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
服务将在 `http://localhost:3001` 启动。
|
||||||
|
|
||||||
|
## API 接口
|
||||||
|
|
||||||
|
### 获取授权码
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/once-code
|
||||||
|
```
|
||||||
|
|
||||||
|
请求示例：
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:3001/api/once-code
|
||||||
|
```
|
||||||
|
|
||||||
|
响应示例：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"once_code": "OATAXWpTNDPGjVyzxNLKvumcv297Q7uUz5CCltLtFDE1uqnPAPmS4jm61XnMQGuV"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
错误响应：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error_code": "INTERNAL_ERROR",
|
||||||
|
"error_msg": "请配置环境变量: HUAWEI_AK 和 HUAWEI_SK"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 健康检查
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /health
|
||||||
|
```
|
||||||
|
|
||||||
|
响应示例：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
- **Express** - Node.js Web 框架
|
||||||
|
- **CORS** - 跨域资源共享
|
||||||
|
- **dotenv** - 环境变量管理
|
||||||
|
- **APIGW-javascript-sdk** - 华为云 API 签名认证
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
backend/server/
|
||||||
|
├── index.js # 服务入口
|
||||||
|
├── package.json # 依赖配置
|
||||||
|
├── .env # 环境变量（不提交到版本库）
|
||||||
|
├── .env.example # 环境变量示例
|
||||||
|
└── APIGW-javascript-sdk-2.0.6/ # 华为云签名SDK
|
||||||
|
├── signer.js # 签名认证
|
||||||
|
├── node_demo.js # 示例代码
|
||||||
|
└── licenses/ # 许可证
|
||||||
|
```
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
1. **安全性** - 请勿将 `.env` 文件提交到版本库
|
||||||
|
2. **凭证保护** - 生产环境请使用更安全的方式管理凭证
|
||||||
|
3. **跨域** - 默认允许所有来源跨域，生产环境请限制来源
|
||||||
240
frontend/README.md
Normal file
240
frontend/README.md
Normal file
@@ -0,0 +1,240 @@
|
|||||||
|
# 华为交互数字人前端
|
||||||
|
|
||||||
|
> **项目说明**：本项目是华为交互数字人 HwICSUiSdk 标准集成项目的定制化开发版本，专为**安特威**公司打造，由**江苏云上企数字科技有限公司**研发。
|
||||||
|
|
||||||
|
## 功能说明
|
||||||
|
|
||||||
|
### 核心功能
|
||||||
|
|
||||||
|
1. **SDK 初始化与销毁**
|
||||||
|
- 初始化：配置服务器地址、机器人ID等参数
|
||||||
|
- 销毁：释放资源，清理数字人实例
|
||||||
|
|
||||||
|
2. **对话控制**
|
||||||
|
- 开始对话：启动数字人交互会话
|
||||||
|
- 停止对话：结束当前会话
|
||||||
|
- 对话保活：自动保持对话活跃，防止超时断开
|
||||||
|
|
||||||
|
3. **语音交互**
|
||||||
|
- 语音自动唤醒：无需点击，语音唤醒数字人（唤醒词："云笙云笙"）
|
||||||
|
- 开始说话：启动语音识别，用户语音输入
|
||||||
|
- 停止说话：结束语音识别
|
||||||
|
|
||||||
|
4. **字幕样式设置**
|
||||||
|
- 支持设置容器、提示文字、消息、热点问题标题、热点问题列表的样式
|
||||||
|
- 包括字体大小、颜色、粗细、行高、背景颜色、透明度、圆角、内边距
|
||||||
|
- 样式设置自动保存到本地存储，刷新页面后自动恢复
|
||||||
|
- 支持重置为默认样式
|
||||||
|
|
||||||
|
5. **字幕容器控制**
|
||||||
|
- 拖拽字幕容器到任意位置
|
||||||
|
- 调整字幕容器大小
|
||||||
|
- 位置和尺寸自动记忆，刷新页面后自动恢复
|
||||||
|
|
||||||
|
6. **多语言支持**
|
||||||
|
- 支持中文和英文语音切换
|
||||||
|
- 根据后端配置自动加载可用语言列表
|
||||||
|
|
||||||
|
7. **面板管理**
|
||||||
|
- 所有弹出面板支持拖拽到任意位置
|
||||||
|
- 面板默认居中显示
|
||||||
|
- 自适应高度（除字幕样式面板外）
|
||||||
|
|
||||||
|
8. **其他控制**
|
||||||
|
- 全屏显示：支持数字人全屏模式
|
||||||
|
- 查看日志：显示 SDK 事件和调试信息
|
||||||
|
|
||||||
|
### 唤醒词
|
||||||
|
|
||||||
|
| 唤醒词 | 说明 |
|
||||||
|
|--------|------|
|
||||||
|
| 云笙云笙 | 主唤醒词 |
|
||||||
|
| 谢谢再见 | 结束对话 |
|
||||||
|
| 稍等一下 | 打断/等待 |
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 1. 环境要求
|
||||||
|
|
||||||
|
- Node.js 14+
|
||||||
|
- 现代浏览器（Chrome、Firefox、Edge、Safari 最新版本）
|
||||||
|
- 支持 WebRTC 和 WebSocket
|
||||||
|
- 需要麦克风权限（用于语音交互）
|
||||||
|
|
||||||
|
### 2. 启动前端服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
前端服务将在 `https://localhost:8080` 启动（使用自签名证书）。
|
||||||
|
|
||||||
|
### 3. 配置后端服务
|
||||||
|
|
||||||
|
确保后端服务已启动：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend/server
|
||||||
|
npm install
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
后端服务应在 `http://localhost:3001` 运行。
|
||||||
|
|
||||||
|
### 4. 使用流程
|
||||||
|
|
||||||
|
1. 打开浏览器访问 `https://localhost:8080`
|
||||||
|
2. 点击页面上的 "⚙️ 连接配置" 按钮
|
||||||
|
3. 点击 "🔑 获取" 按钮获取授权码
|
||||||
|
4. 点击 "初始化 SDK" 开始使用
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/
|
||||||
|
├── index.html # 主页面
|
||||||
|
├── server.js # HTTPS 服务器（开发环境）
|
||||||
|
├── package.json # 依赖配置
|
||||||
|
├── styles/
|
||||||
|
│ └── main.css # 自定义样式
|
||||||
|
├── scripts/
|
||||||
|
│ ├── main.js # 主逻辑代码
|
||||||
|
│ └── api.js # 前端 API 调用模块
|
||||||
|
├── hwICSUiSdk/ # SDK 目录
|
||||||
|
│ ├── HwICSUiSdk.esm.js # ESM 模块入口
|
||||||
|
│ ├── HwICSUiSdk.js # UMD 模块入口
|
||||||
|
│ ├── HwICSUiSdk.d.ts # TypeScript 类型定义
|
||||||
|
│ ├── HwICSUiSdk.css # SDK 样式
|
||||||
|
│ ├── wasmData.js # WASM 虚拟机数据
|
||||||
|
│ ├── modelData.js # 唤醒词模型数据
|
||||||
|
│ └── images/ # SDK 图片资源
|
||||||
|
└── cert/ # SSL 证书（开发用）
|
||||||
|
├── localhost.pem
|
||||||
|
└── localhost-key.pem
|
||||||
|
```
|
||||||
|
|
||||||
|
## 配置选项
|
||||||
|
|
||||||
|
### SDK 配置项
|
||||||
|
|
||||||
|
| 配置项 | 类型 | 默认值 | 说明 |
|
||||||
|
|--------|------|--------|------|
|
||||||
|
| ENABLE_CAPTION | boolean | true | 启用字幕显示 |
|
||||||
|
| ENABLE_CHAT_BTN | boolean | true | 启用聊天按钮 |
|
||||||
|
| ENABLE_HOT_ISSUES | boolean | true | 启用热点问题 |
|
||||||
|
| SHOW_LANGUAGE_UI | boolean | false | 显示语言切换UI |
|
||||||
|
| ENABLE_DEVICE_SETTING | boolean | false | 启用设备设置 |
|
||||||
|
| ENABLE_NETWORK_CHECK | boolean | false | 启用网络检查 |
|
||||||
|
| AUTO_PLAY_REMOTE_VIDEO | boolean | true | 自动播放远程视频 |
|
||||||
|
| DEFAULT_MUTE_REMOTE_AUDIO | boolean | false | 默认静音远程音频 |
|
||||||
|
| ENABLE_LOCAL_WAKEUP | boolean | true | 启用本地语音唤醒 |
|
||||||
|
| USE_WORKER_WAKEUP | boolean | false | 使用Worker线程运行唤醒模块 |
|
||||||
|
|
||||||
|
## 事件监听
|
||||||
|
|
||||||
|
SDK 提供了丰富的事件回调：
|
||||||
|
|
||||||
|
| 事件 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| ERROR | 错误事件 |
|
||||||
|
| JOB_INFO_CHANGE | 任务信息变更 |
|
||||||
|
| SPEAKING_START | 数字人开始说话 |
|
||||||
|
| SPEAKING_STOP | 数字人停止说话 |
|
||||||
|
| SPEECH_RECOGNIZED | 语音识别结果 |
|
||||||
|
| SEMANTIC_RECOGNIZED | 语义识别结果 |
|
||||||
|
| ENTER_SLEEP | 进入休眠状态 |
|
||||||
|
| ENTER_ACTIVE | 进入激活状态 |
|
||||||
|
| JOB_END | 任务结束 |
|
||||||
|
|
||||||
|
## 调试技巧
|
||||||
|
|
||||||
|
1. **查看日志面板**
|
||||||
|
- 点击工具栏的 "📜" 按钮打开日志面板
|
||||||
|
- 可查看 SDK 事件和调试信息
|
||||||
|
|
||||||
|
2. **调整日志级别**
|
||||||
|
在控制台中执行：
|
||||||
|
```javascript
|
||||||
|
HwICSUiSdk.setLogLevel('debug'); // debug | info | warn | error | none
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **浏览器开发者工具**
|
||||||
|
- 使用 Network 面板监控 WebSocket 连接
|
||||||
|
- 使用 Console 面板查看控制台日志
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
1. **HTTPS 要求**
|
||||||
|
- WebRTC 功能必须使用 HTTPS 环境
|
||||||
|
- 开发环境使用自签名证书，浏览器可能需要授权
|
||||||
|
|
||||||
|
2. **浏览器权限**
|
||||||
|
- 首次使用需要授权麦克风权限
|
||||||
|
|
||||||
|
3. **唤醒词**
|
||||||
|
- 语音唤醒需要先初始化 SDK
|
||||||
|
- 对着麦克风说"云笙云笙"即可唤醒数字人
|
||||||
|
|
||||||
|
4. **样式保存**
|
||||||
|
- 字幕样式和容器位置会自动保存到浏览器本地存储
|
||||||
|
|
||||||
|
## 生产部署
|
||||||
|
|
||||||
|
### 构建
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 前端为纯静态文件，可直接部署到任意 Web 服务器
|
||||||
|
```
|
||||||
|
|
||||||
|
### Nginx 配置示例
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 443 ssl;
|
||||||
|
server_name your-domain.com;
|
||||||
|
|
||||||
|
ssl_certificate /path/to/cert.pem;
|
||||||
|
ssl_certificate_key /path/to/key.pem;
|
||||||
|
|
||||||
|
root /path/to/frontend;
|
||||||
|
index index.html;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
try_files $uri $uri/ /index.html;
|
||||||
|
}
|
||||||
|
|
||||||
|
location /api/ {
|
||||||
|
proxy_pass http://backend-server:3001;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
}
|
||||||
|
|
||||||
|
location /hwICSUiSdk/ {
|
||||||
|
expires 1y;
|
||||||
|
add_header Cache-Control "public, immutable";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 唤醒模型更新
|
||||||
|
|
||||||
|
### 模型文件位置
|
||||||
|
|
||||||
|
- `hwICSUiSdk/wasmData.js` - WASM 虚拟机数据
|
||||||
|
- `hwICSUiSdk/modelData.js` - 唤醒词模型数据
|
||||||
|
|
||||||
|
### 更新步骤
|
||||||
|
|
||||||
|
1. 获取新的模型文件
|
||||||
|
2. 替换 `wasmData.js` 和 `modelData.js`
|
||||||
|
3. 刷新页面，查看日志确认模型加载成功
|
||||||
|
|
||||||
|
### 常见问题
|
||||||
|
|
||||||
|
| 问题 | 解决方案 |
|
||||||
|
|------|----------|
|
||||||
|
| 模型加载失败 | 检查文件路径，确认文件完整性 |
|
||||||
|
| 唤醒无响应 | 确认麦克风权限，查看日志 |
|
||||||
|
| 模型版本不匹配 | 确保两个文件版本一致 |
|
||||||
Reference in New Issue
Block a user