# free-ws

**Repository Path**: nachao/free-ws

## Basic Information

- **Project Name**: free-ws
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket 服务

一个功能完整的 WebSocket 服务，支持动态 scope、两种连接模式（ws/ws2）、消息广播、SQLite 持久化存储和实时 Web 界面。

## 功能特性

- ✅ 动态 scope 支持，可以创建多个独立的消息空间
- ✅ WebSocket 实时双向通信
- ✅ **两种连接模式**：`/ws` 和 `/ws2`
- ✅ **`/ws` 模式**：客户端只能接收服务端发送的消息
- ✅ **`/ws2` 模式**：客户端之间可以互相通信（同一 scope 内互通）
- ✅ 消息广播到所有连接的设备
- ✅ SQLite 数据库持久化存储
- ✅ 美观的 Web 界面，实时显示连接数和消息
- ✅ 刷新页面自动回显历史记录

## 安装依赖

```bash
go mod download
```

## 运行服务

```bash
go run .
```

或使用编译后的可执行文件：

```bash
./free-ws.exe
```

服务将在 `http://localhost:8080` 启动

## 使用方式

### WebSocket 连接

#### 模式一：/ws（服务端-客户端模式）

```
ws://localhost:8080/:scope/ws
```

**特点：**
- 客户端只能接收服务端通过 API 发送的消息
- 客户端之间不互通
- 适用于服务端下发指令的场景

**例如：**
- `ws://localhost:8080/room1/ws`
- `ws://localhost:8080/device-group/ws`
- `ws://localhost:8080/default/ws`

#### 模式二：/ws2（客户端互通模式）

```
ws://localhost:8080/:scope/ws2
```

**特点：**
- 客户端之间可以互相通信
- 只在同一 scope 内的 ws2 客户端互通
- 也支持接收服务端发送的消息
- 适用于设备之间协作的场景

**例如：**
- `ws://localhost:8080/room1/ws2`
- `ws://localhost:8080/device-group/ws2`
- `ws://localhost:8080/default/ws2`

### Web 界面访问

```
http://localhost:8080/:scope
```

例如：
- `http://localhost:8080/room1`
- `http://localhost:8080/device-group`
- `http://localhost:8080/` (默认 scope)

### Web 界面功能

1. **实时显示连接设备数量**
2. **发送消息到所有设备** - 在输入框输入内容，点击发送按钮
3. **消息列表** - 显示所有设备的输出和服务器的输入记录
4. **自动刷新** - 页面刷新时自动加载历史记录

## WebSocket 客户端示例

### JavaScript 客户端

#### /ws 模式（只接收服务端消息）

```javascript
const ws = new WebSocket('ws://localhost:8080/room1/ws');

ws.onopen = () => {
    console.log('连接成功 - ws 模式');
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('收到服务端消息:', message);
    // ws 模式下，message.type 为 'input'（来自服务端）
};
```

#### /ws2 模式（客户端互通）

```javascript
const ws = new WebSocket('ws://localhost:8080/room1/ws2');

ws.onopen = () => {
    console.log('连接成功 - ws2 模式');
    // 发送消息给其他客户端
    ws.send(JSON.stringify({ content: 'Hello from client' }));
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('收到消息:', message);
    // ws2 模式下，message.type 为 'output'（来自其他客户端）
    // 也可以收到服务端消息，此时 message.type 为 'input'
};
```

### Go 客户端

#### /ws 模式（只接收服务端消息）

```go
package main

import (
    "log"
    "github.com/gorilla/websocket"
)

func main() {
    conn, _, err := websocket.DefaultDialer.Dial("ws://localhost:8080/room1/ws", nil)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // 只接收服务端消息
    for {
        var message map[string]interface{}
        err := conn.ReadJSON(&message)
        if err != nil {
            log.Println(err)
            break
        }
        log.Printf("收到服务端消息: %v", message)
    }
}
```

#### /ws2 模式（客户端互通）

```go
package main

import (
    "encoding/json"
    "log"
    "github.com/gorilla/websocket"
)

func main() {
    conn, _, err := websocket.DefaultDialer.Dial("ws://localhost:8080/room1/ws2", nil)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // 发送消息给其他客户端
    msg := map[string]string{"content": "Hello from Go client"}
    conn.WriteJSON(msg)

    // 接收其他客户端的消息
    for {
        var message map[string]interface{}
        err := conn.ReadJSON(&message)
        if err != nil {
            log.Println(err)
            break
        }
        log.Printf("收到消息: %v", message)
    }
}
```

## 数据库结构

消息存储在 `messages.db` SQLite 数据库中：

```sql
CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    scope TEXT NOT NULL,
    type TEXT NOT NULL,           -- 'input' 或 'output'
    content TEXT NOT NULL,
    client_id TEXT NOT NULL,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

## API 接口

### 获取消息历史

```
GET /api?scope=room1
```

返回：
```json
{
    "messages": [...],
    "client_count": 5
}
```

### 发送消息到所有设备

```
POST /api?scope=room1
Content-Type: application/json

{
    "content": "Hello all devices"
}
```

## 配置

### 默认端口：`8080`

修改端口请编辑 `config.conf` 文件：

```
# 配置文件示例
port = 8080
```

## 测试

项目包含测试页面 `test_correct.html`，用于测试 ws 和 ws2 两种模式的差异：

1. 启动服务：`./free-ws.exe`
2. 打开测试页面：`test_correct.html`
3. 连接多个客户端（ws 和 ws2 模式）
4. 测试消息发送和接收

### 测试场景

- **ws 客户端**：只能接收服务端通过 `/api` 发送的消息
- **ws2 客户端**：可以接收同一 scope 下其他 ws2 客户端发送的消息
- **服务端广播**：通过 `/api` 发送的消息，所有客户端都能接收

## 技术栈

- Go 1.21+
- gorilla/websocket - WebSocket 实现
- modernc.org/sqlite - SQLite 数据库驱动
- 原生 HTML/CSS/JavaScript - Web 界面

## 许可证

MIT License