# libweb_server 模块分析

**日期**: 2026-06-12  
**基于源码**: `src/system/libweb_server/`（5个文件，约1500行）

---

## 1. 模块定位

`libweb_server` 是 RTU 的嵌入式 Web 服务器，作为 `app_web_server` 线程（9个应用线程之第7号）运行。基于 Mongoose v7.x，提供：

- HTTP 静态文件服务（内嵌前端工程）
- WebSocket 实时数据通道（JSON 格式）
- 多客户端并发支持（per-connection session）
- 信号增量推送（仅变更时发送）

### 目录结构

```
src/system/libweb_server/
├── inc/
│   ├── web_server.h       # 模块头文件
│   └── ws_method.h        # WebSocket 消息处理接口
└── src/
    ├── web_server.cpp     # HTTP/WS 服务器 + Mongoose 事件循环
    ├── ws_method.cpp      # WebSocket 命令解析 + JSON 推送
    └── packed_fs.c        # 前端文件嵌入（自动生成）
```

## 2. 架构设计

### 2.1 Mongoose 集成

Mongoose 是单线程事件驱动的网络库。RTU 的 Web 服务器以独立线程运行，集成方式：

```
app_web_server_init1:
  → mg_mgr_init(&mgr)         // 初始化事件管理器
  → 加载 packed_fs（前端文件） // 如果定义了 USE_PACKED_FS

app_web_server_init2:
  → mg_http_listen(&mgr, "http://0.0.0.0:8000", fn, NULL)
  → 启动事件循环

app_web_server 线程:
  while(1):
    task_event_recv(EV_TIMER1 | EV_TIMER2 | EV_TIMER3)
    EV_TIMER1 (10ms):  mg_mgr_poll(&mgr, 0)  // 非阻塞轮询
    EV_TIMER2 (100ms): ws_task()              // WebSocket 推送
    EV_TIMER3 (1000ms): 空闲
```

### 2.2 事件处理函数 `fn`

统一的 HTTP + WebSocket 事件处理：

```cpp
static void fn(struct mg_connection *c, int ev, void *ev_data):
  switch(ev):
    MG_EV_HTTP_MSG:
      → mg_http_get_header(hm, "Sec-WebSocket-Key") 存在?
        YES → mg_ws_upgrade(c, hm, NULL)  // WebSocket 握手
        NO  → mg_http_serve_dir / mg_http_serve_packed  // 静态文件
      
    MG_EV_WS_MSG:
      → ws_recv(c, wm->data.buf, wm->data.len)  // WebSocket 消息
    
    MG_EV_CLOSE:
      → ws_session_destroy(c)  // 释放 per-connection 资源
```

### 2.3 多连接管理

```cpp
LOCAL std::vector<struct mg_connection *> g_ws_conns;        // 所有 WS 连接
LOCAL pthread_mutex_t g_ws_conns_mutex = PTHREAD_MUTEX_INITIALIZER;
```

- 连接建立时将 `mg_connection*` 加入 `g_ws_conns`
- 断开时从 `g_ws_conns` 移除并调用 `ws_session_destroy`
- 所有对 `g_ws_conns` 的访问受互斥锁保护

## 3. 前端嵌入式部署（packed_fs.c）

`packed_fs.c` 由构建工具自动生成，将前端文件（HTML/CSS/JS）以 `unsigned char` 数组嵌入：

```c
const struct mg_mem_file mg_packed_files[] = {
  {"/css/style.css",     v3, sizeof(v3) - 1, 1781072856},
  {"/index.html",        v4, sizeof(v4) - 1, 1781073518},
  {"/js/app.js",         v5, sizeof(v5) - 1, 1781073909},
  {"/js/monitor.js",     v6, sizeof(v6) - 1, 1781072788},
  {"/js/pages.js",       v7, sizeof(v7) - 1, 1781073958},
  {"/js/ws-client.js",   v8, sizeof(v8) - 1, 1781071573},
  {NULL, NULL, 0, 0}
};
```

Mongoose 通过 `mg_http_serve_packed` 直接返回内嵌文件，无需外部 `web_root` 目录。

## 4. WebSocket 消息处理（ws_method.cpp）

### 4.1 消息格式

客户端发送 JSON 命令：

```json
{
    "cmd": "subscribe",      // 命令类型
    "type": "out,ao,param",  // 订阅的信号类型
    "signals": ["saddr1", "saddr2"],  // 指定信号（空=全部）
    "conn_id": 12345         // 连接标识
}
```

### 4.2 命令分发

`ws_recv` 解析 JSON → 提取 `cmd` 字段 → 路由到处理函数：

| cmd | 功能 | 处理函数 |
|-----|------|---------|
| `subscribe` | 订阅信号推送 | `ws_handle_subscribe` |
| `unsubscribe` | 取消订阅 | `ws_handle_unsubscribe` |
| `read_all` | 读取全部当前值 | `ws_handle_read_all` |
| `set_value` | 设置 AO/Param 值 | `ws_handle_set_value` |
| `yk_control` | 遥控操作 | `ws_handle_yk_control` |

### 4.3 信号订阅与增量推送

每个连接维护独立的 per-connection session：

```cpp
struct ws_session {
    unsigned long conn_id;
    std::set<std::string> subscribed_signals;  // 已订阅的信号 saddr 集合
    std::set<std::string> subscribed_types;    // 已订阅的信号类型（out/ao/param）
    // ...
};
```

订阅流程:
```
客户端发送 {cmd: "subscribe", type: "out,ao", signals: ["sig1","sig2"]}
  → ws_handle_subscribe(c, json):
      获取或创建 session
      将信号 saddr 加入 subscribed_signals
      将类型加入 subscribed_types
      回复 {status: "ok"}
```

推送流程 (`ws_task`, 每 100ms 执行):
```
ws_task():
  遍历 g_ws_conns:
    对每个连接:
      收集该连接订阅的信号中发生了变更的
      构建 JSON: {signals: [{saddr, value, time, quality}, ...]}
      通过 mg_ws_send 发送
```

### 4.4 数据广播

```cpp
void ws_send_all(const char *p_tx, uint16_t tx_len):
  pthread_mutex_lock(&g_ws_conns_mutex)
  for each c in g_ws_conns:
    mg_ws_send(c, p_tx, tx_len, WEBSOCKET_OP_TEXT)
  pthread_mutex_unlock(&g_ws_conns_mutex)
```

### 4.5 单连接发送

```cpp
void ws_send_one(unsigned long conn_id, const char *p_tx, uint16_t tx_len):
  在 g_ws_conns 中查找 mg_connection.conn_id == conn_id
  找到 → mg_ws_send
```

## 5. HTTP API

除了 WebSocket，还提供 RESTful HTTP 接口（通过 `MG_EV_HTTP_MSG` 处理）：

| 方法 | 路径 | 功能 |
|------|------|------|
| GET | `/` | 静态首页 |
| GET | `/api/status` | 设备状态 |
| GET | `/api/signals` | 信号列表快照 |
| POST | `/api/control` | 控制命令 |

## 6. 线程安全

- Mongoose 事件循环在 `app_web_server` 线程中执行
- `ws_task()` 在 `EV_TIMER2`（100ms）中执行，与事件循环同线程
- `g_ws_conns` 访问受 `g_ws_conns_mutex` 保护
- 通过任务事件机制与 datacenter 交互（信号值读取通过 `dc_get_signal_val` 等线程安全 API）

## 7. 已知问题

1. **mg_mgr_poll 非阻塞模式**: `mg_mgr_poll(&mgr, 0)` 零超时，高频率轮询可能消耗 CPU。Mongoose 连接数少时不明显
2. **packed_fs 更新**: 修改前端后需重新生成 `packed_fs.c` 并重新编译
3. **广播效率**: `ws_send_all` 逐连接发送，大量连接时效率低。当前场景（嵌入式 RTU）连接数通常较少