# ws-proxy

**Repository Path**: xiangdada/ws-proxy

## Basic Information

- **Project Name**: ws-proxy
- **Description**: 一个轻量级的Node.js WebSocket代理服务，用于设备与服务器之间的消息转发和管理，支持配置管理、日志记录和连接监控功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-27
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 写在前面

1. 本项目是基于人脸识别硬件的设备与服务器之间的消息转发和管理服务。主要是为了方便开发人员在使用人脸识别硬件时，能够更方便地与服务器进行交互。
2. 无需开发人员手动管理设备websocket连接，服务会自动处理设备的连接、断开和消息转发。
3. 开发人员只需要监听设备http请求和响应，如果需要发送数据给设备，可以使用本项目作为中转，发送http请求到此中转上，中转服务会发送给设备。

硬件接口格式参考文档：
设备接口（API）对接指南：
https://docs.qq.com/doc/DSXRtcWNSUXhQaXZE

http设备接口：https://www.showdoc.cc/286732791253185?page_id=1858556223116740

websocket设备接口：https://www.showdoc.cc/286682190140856?page_id=1858753401021513

# WebSocket代理服务

一个轻量级的Node.js WebSocket代理服务，用于设备与服务器之间的消息转发和管理，支持配置管理、日志记录和连接监控功能。

## 功能特点
- WebSocket与HTTP协议转换
- 设备连接管理与心跳检测
- 集中式配置管理
- 完整的消息收发日志
- 自动日志轮转（最多保留5个日志文件）
- 设备响应超时处理

## 流程图
![流程图](log/2836d911810266db6912a54603229be3.png)

## 安装与启动

### 环境要求
- Node.js v14+ 
- npm v6+

### 安装步骤
```bash
# 克隆仓库后进入项目目录
cd ws-proxy

# 安装依赖
npm install

# 启动服务
node server.js
```

服务启动后默认监听端口3000，可通过配置文件修改。

## 配置说明
配置文件位于项目根目录下的`config.js`（与server.js同级），格式如下：

```javascript
module.exports = {
  server: {
    port: 3000,               // 服务监听端口
    responseTimeout: 30000,   // 设备响应超时时间(ms)，超过此时间未收到响应将返回超时错误
    pingTimeout: 90000        // WebSocket心跳超时时间(ms)，超过此时间未收到心跳将断开连接
  }
};
```

修改配置后需重启服务生效。

## 接口文档

### WebSocket连接
设备通过WebSocket连接到服务：
```
ws://localhost:{port}
```

连接建立后，设备必须首先发送客户端声明消息：
```json
{
  "cmd": "declare",
  "type": "device",
  "sn": "设备编号"
}
```

声明成功后，设备应每30秒发送一次心跳包：
```json
{
  "cmd": "ping"
}
```

### HTTP API
发送消息到设备：
- 地址: `POST /api/send/{deviceSn}`
- 请求体格式:
  ```json
  {
    "cmd": "to_device",
    "data": {
      "cmd": "setVolume",
      "value": 50
    }
  }
  ```
- 成功响应:
  ```json
  {
    "code": 0,
    "message": "设备已响应",
    "data": {
      "cmd": "setVolumeRet",
      "code": 0,
      "msg": "修改成功"
    }
  }
  ```
- 错误响应（设备未连接）:
  ```json
  {
    "code": -2,
    "message": "设备 RT63715 未连接或连接已关闭"
  }
  ```

#### 错误代码说明
| 代码 | 说明 |
|------|------|
| 0 | 成功 |
| -1 | 缺少必要参数 |
| -2 | 设备未连接或连接已关闭 |
| -3 | 设备响应超时 |
| -500 | 服务器内部错误 |

### 健康检查
- 地址: `GET /health`
- 响应: 服务状态及设备连接数

## 日志管理

### 日志位置
日志文件存储在项目根目录下的`log`文件夹中，文件命名格式为`年月日小时分钟秒.log`（如`20231115143022.log`）。

### 日志轮转
系统在每次服务启动时创建新日志文件，并自动管理日志数量，最多保留最近5个日志文件，超过时自动删除最旧的日志文件。

### 日志内容
日志包含所有消息的收发记录，格式如下：
- SEND: 服务发送给设备的WebSocket消息
- RECEIVE: 服务从设备接收的WebSocket消息
- HTTP_REQUEST: 接收到的HTTP请求
- HTTP_RESPONSE: 发送的HTTP响应

```
[2023-11-15T14:30:22.123Z] [SEND] {"cmd":"to_device","from":"msg_123","to":"device1","data":{...}}
[2023-11-15T14:30:26.789Z] [RECEIVE] {"cmd":"response","data":{...}}
[2023-11-15T14:30:30.456Z] [HTTP_REQUEST] {"url":"/api/send/RT63715","body":{...}}
```

## 注意事项
1. 确保设备连接时正确发送声明消息以完成注册
2. 修改配置文件后需重启服务
3. 日志文件达到5个时会自动删除最旧文件，重要日志请及时备份
4. 服务异常退出时可能导致未发送完成的消息丢失

## 故障排除
- 设备无法连接：检查端口是否被占用（`netstat -ano | findstr :3000`），防火墙设置
- 消息发送超时：检查设备是否在线，网络是否正常
- 日志文件不生成：确保服务对目录有写入权限，尝试手动创建log文件夹
- 配置不生效：确认修改config.js后已重启服务

## 疑难解答
- 1、为什么要用http和websocket（mqtt）两种协议？
- 答：因为设备一般是在内网IP，一般是192.168.0.xxx，服务器在公网，有公网IP，设备是可以正常访问到服务端，而
服务端无法直接访问设备，所以才需要用到长链接

- 2、我想代理服务运行在内网电脑，其他地方的设备要如何连接？
- 答：可以使用内网穿透工具，网上有很多服务，本质上是依赖一个公网服务器，把本地的端
口通过公网服务器暴露出来