feat: add docs to main (#1559)

docs/zh/developer/develop/advanced/websocket.md

@@ -0,0 +1,173 @@
+---
+outline: [2, 3]
+---
+
+# Websocket
+
+WebSocket 是现代前端开发中使用最广泛的技术之一。为了简化 Olares 应用的使用与开发，Olares 应用程序运行时提供了一个通用的 WebSocket 组件。
+
+## 客户端
+
+基于 JavaScript/TypeScript 的方式开发的客户端，采用 “ws” 库。
+应用服务提供 WebSocket 的路径格式：`wss://<appid>.<username>.olares.com/ws`
+
+### 发送消息
+
+客户端发送 WebSocket 消息格式如下（支持其他格式）：
+```json
+{
+  "event": "...",
+  "data": {...}
+}
+```
+
+### Ping
+
+客户端需要定期发送 ping 包（30 秒一次），以维持 WebSocket 连接。（WebSocket 服务定期检查 ping 包，超时则会主动关闭该连接），ping 包数据格式如下（严格按照如下格式）：
+```json
+{
+  "event": "ping",
+  "data": {}
+}
+```
+
+## 应用
+
+WebSocket 服务提供多种功能：
+- 允许服务器通过广播消息或响应客户端发送的 WebSocket 消息与客户端进行通信。
+- 可用于关闭特定用户或连接 ID 的 WebSocket 连接。
+- 获取当前连接列表。
+
+因为 WebSocket 与应用是部署在一个容器中的，所以直接访问 localhost 即可调用 WebSocket 服务。端口 `40010`。
+
+### 广播消息
+```json
+// URL：http://localhost:40010/tapr/ws/conn/send
+// 请求方式：POST
+// body
+{
+"payload": {}, // 消息。
+"conn_id": "<connId>", // 连接 ID；用于响应客户端的单次 Ws 请求。按 users 广播时不要填写 connId
+"users": ["<userName-1>", "<userName-2>"], // 指定用户，如果填写该字段，则是广播。广播场景下不要填写 connId
+}
+
+// 响应示例
+{
+"code": 0,
+"message": "success",
+}
+```
+
+### 关闭客户端的 WebSocket 连接
+```json
+// URL：http://localhost:40010/tapr/ws/conn/close
+// 请求方式：POST
+// body
+{
+"conns": ["<connId>", ...], // 关闭指定连接
+"users": ["<userName>", ...], // 关闭指定用户的所有连接
+}
+
+// 响应示例
+{
+"code": 0,
+"message": "success",
+}
+```
+
+### 获取当前在线的连接列表
+
+```json
+// URL：http://localhost:40010/tapr/ws/conn/list
+// 请求方式：GET
+// 响应示例
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "name": "<userName>",
+      "conns": [
+        {
+          "id": "<connId>", // 连接 ID
+          "userAgent": ""
+        }
+      ]
+    }
+  ]
+}
+```
+
+### WebSocket 转发客户端消息到应用
+
+将转发到应用的客户端消息分为三种类型：
+- 客户端连入
+- 客户端正常发送的消息
+- 客户端连接断开，如关闭浏览器，网络异常等。
+
+**客户端连入**
+
+```json
+// URL：http://localhost:3010/websocket/message
+// 请求方式：POST
+// body
+
+{
+  "data": {},
+  "action": "open", // action
+  "user_name": "<userName>",
+  "conn_id": "1" // WebSocket 连接 ID
+}
+
+// 应用 App 接收到 open 的消息后，做相关处理。
+```
+
+**客户端正常发送的消息**
+
+```json
+// URL：http://localhost:3010/websocket/message
+// 请求方式：POST
+// header，会传递客户端的原始 Cookie 给后端应用
+Cookie: .... // v1.0.3 版本新增功能
+
+// body
+{
+"data": { ... }, // 客户端发到 WSGateway 的原始数据，内部结构为 {"event":"", "data": {...}}
+"action": "message", // action
+"user_name": "<userName>",
+"conn_id": "1", // WebSocket 连接 ID
+}
+
+// 应用 App 处理后通过“广播消息”的接口，将数据回传给客户端
+
+```
+
+**客户端连接断开**
+>WebSocket 服务响应到 close 事件后回调应用
+
+```json
+// URL：http://localhost:3010/websocket/message
+// 请求方式：POST
+// body
+
+{
+  "data": {},
+  "action": "close", // action
+  "user_name": "<userName>",
+  "conn_id": "1" // WebSocket 连接 ID
+}
+
+// 应用 App 接收到 close 的消息后，做相关处理。
+```
+
+## 应用部署 WebSocket 服务
+
+应用要使用这个功能只需要在应用 Chart 的 [OlaresManifest.yaml](../package/manifest.md#websocket) 中申明。
+```yaml
+options:
+  websocket:
+    url: /ws/message
+    port: 8888
+```
+
+WebSocket 是在客户端和应用之间承载消息转发的组件，所以应用端需要提供一个 API 接口，供 WebSocket 调用转发客户端的 ws 消息。比如，按上面的申明应用应提供接口名为：`/ws/message`，端口是 `8888`。