# classroom-websocket

**Repository Path**: cheng96617/classroom-websocket

## Basic Information

- **Project Name**: classroom-websocket
- **Description**: websocket技术开发的学生课堂系统
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Node.js WebSocket 集成智能体示例

## 📦 包含内容

本目录包含三个完整的集成方案示例：

1. **方案一：最简单方案**（server-simple.js + client-simple.html）
2. **方案二：生产级方案**（server-production.js）
3. **方案三：Socket.IO 方案**（server-socketio.js + client-socketio.html）

---

## 🚀 快速开始

### 前提条件

1. **智能体服务已启动**
   ```bash
   # 在智能体项目目录中运行
   bash scripts/http_run.sh
   ```

2. **Node.js 环境**
   ```bash
   node --version  # 应该 >= 14
   ```

3. **安装依赖**
   ```bash
   npm install
   ```

---

## 📋 方案选择指南

### 方案一：最简单方案 ⭐ 推荐

**适用场景**：
- 快速原型开发
- 学习和测试
- 小规模应用

**特点**：
- ✅ 代码简单，易于理解
- ✅ 无需额外依赖（Node.js 原生）
- ✅ 实时流式响应
- ❌ 无连接管理
- ❌ 无错误恢复

**启动方式**：
```bash
# 1. 启动服务器
node server-simple.js

# 2. 在浏览器中打开 client-simple.html
```

---

### 方案二：生产级方案

**适用场景**：
- 生产环境部署
- 需要连接管理
- 需要并发控制
- 需要监控和日志

**特点**：
- ✅ 心跳检测
- ✅ 自动重连
- ✅ 并发限制
- ✅ 连接状态管理
- ✅ 错误处理
- ✅ 优雅关闭

**启动方式**：
```bash
# 1. 安装 uuid 依赖（如果还没安装）
npm install uuid

# 2. 启动服务器
node server-production.js

# 3. 使用方案一的 client-simple.html 或自行开发前端
```

---

### 方案三：Socket.IO 方案 🎯 最简单

**适用场景**：
- 快速开发
- 需要跨浏览器兼容
- 需要自动降级机制
- 小型项目

**特点**：
- ✅ 最简单的 API
- ✅ 自动降级（WebSocket → Polling）
- ✅ 内置重连
- ✅ 丰富的功能
- ❌ 额外依赖
- ❌ 稍大的包体积

**启动方式**：
```bash
# 1. 安装依赖
npm install express socket.io

# 2. 启动服务器
node server-socketio.js

# 3. 在浏览器中打开 client-socketio.html
```

---

## 🔧 使用步骤

### 方案一（最简单）

```bash
# 1. 安装依赖（可选，如果使用生产级需要）
npm install

# 2. 启动智能体服务（在另一个终端）
cd /path/to/greenhouse-agent
bash scripts/http_run.sh

# 3. 启动 WebSocket 服务器
node server-simple.js

# 4. 在浏览器中打开 client-simple.html
```

### 方案二（生产级）

```bash
# 1. 安装依赖
npm install uuid

# 2. 启动智能体服务（在另一个终端）
cd /path/to/greenhouse-agent
bash scripts/http_run.sh

# 3. 启动 WebSocket 服务器
node server-production.js

# 4. 在浏览器中打开 client-simple.html 或使用自定义前端
```

### 方案三（Socket.IO）

```bash
# 1. 安装依赖
npm install express socket.io

# 2. 启动智能体服务（在另一个终端）
cd /path/to/greenhouse-agent
bash scripts/http_run.sh

# 3. 启动 WebSocket 服务器
node server-socketio.js

# 4. 在浏览器中打开 client-socketio.html
```

---

## 📡 API 说明

### 服务器端

所有方案都监听端口 `8080`。

#### 方案一、二（原生 WebSocket）

**客户端消息格式**：
```json
{
  "type": "question",
  "question": "温度传感器是如何工作的？"
}
```

**服务器消息格式**：
```json
{
  "type": "message",
  "content": "温度传感器",
  "fullContent": "温度传感器的工作原理..."
}
```

#### 方案三（Socket.IO）

**客户端发送**：
```javascript
socket.emit('message', '温度传感器是如何工作的？');
```

**服务器发送**：
```javascript
socket.emit('chunk', {
  content: '温度传感器',
  fullContent: '温度传感器的工作原理...'
});
```

---

## 🎨 前端集成

### 在你的项目中使用

**方案一、二**：
```javascript
const ws = new WebSocket('ws://localhost:8080');

ws.onopen = () => {
  console.log('已连接');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'message') {
    console.log(data.content);
  }
};

ws.send(JSON.stringify({
  type: 'question',
  question: '什么是阈值？'
}));
```

**方案三**：
```javascript
const socket = io('http://localhost:8080');

socket.on('connect', () => {
  console.log('已连接');
});

socket.on('chunk', (data) => {
  console.log(data.content);
});

socket.emit('message', '什么是阈值？');
```

---

## 🔍 配置说明

在服务器代码中修改配置：

```javascript
const CONFIG = {
  WS_PORT: 8080,                          // WebSocket 端口
  AGENT_URL: 'http://localhost:8000/stream_run',  // 智能体服务地址
  HEARTBEAT_INTERVAL: 30000,               // 心跳间隔（毫秒）
  MAX_CONCURRENT_REQUESTS: 10,             // 最大并发请求
  IDLE_TIMEOUT: 300000                     // 空闲超时（毫秒）
};
```

---

## 🚀 部署到生产环境

### 使用 PM2

```bash
# 安装 PM2
npm install -g pm2

# 启动服务
pm2 start server-production.js --name agent-server

# 设置开机自启
pm2 startup
pm2 save

# 查看状态
pm2 status

# 查看日志
pm2 logs agent-server
```

### 使用 Docker

创建 `Dockerfile`：
```dockerfile
FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install --production

COPY . .

EXPOSE 8080

CMD ["node", "server-production.js"]
```

构建并运行：
```bash
docker build -t agent-websocket .
docker run -p 8080:8080 agent-websocket
```

---

## 🐛 常见问题

### Q1: 无法连接到智能体服务
**A**: 确保智能体服务已启动：
```bash
curl http://localhost:8000/health
```

### Q2: WebSocket 连接失败
**A**: 检查防火墙设置，确保端口 8080 可访问。

### Q3: 流式响应中断
**A**: 检查智能体服务日志，可能超时或出错。

### Q4: 并发请求过多
**A**: 在配置中增加 `MAX_CONCURRENT_REQUESTS` 的值。

---

## 📚 相关文档

- [Node.js WebSocket 集成指南](../docs/Node.js_WebSocket集成指南.md)
- [智能体 API 调用指南](../docs/API调用指南.md)

---

## 💡 最佳实践

1. **开发环境**：使用方案一（最简单）
2. **生产环境**：使用方案二（生产级）
3. **快速开发**：使用方案三（Socket.IO）
4. **性能优化**：使用 Nginx 反向代理
5. **监控**：添加日志记录和监控
6. **安全**：添加 JWT 认证和速率限制

---

## 🆘 需要帮助？

1. 查看详细文档：`docs/Node.js_WebSocket集成指南.md`
2. 检查服务器日志
3. 查看浏览器控制台错误
4. 确保所有服务都已启动

---

**开始使用，选择最适合你的方案吧！** 🚀