Merge branch 'openimsdk:main' into main

Author: withchao

docs/blog/client/architectural/Browser/assets/wasm_call_map.png

@@ -0,0 +1,116 @@
+---
+title: Wasm Client SDK架构介绍
+hide_title: true
+sidebar_position: 1
+---
+
+# Wasm Client SDK 架构介绍
+
+## 前言
+
+在现代 Web 开发中，许多场景都需要即时通讯功能，例如聊天、推送、协作等。然而，传统的前端方案往往依赖第三方云服务，带来高额成本和数据安全隐患。现在，借助 OpenIMSDK 这一开源项目，我们可以轻松构建自托管的即时通讯服务，并在客户端使用 WebAssembly (WASM) 进行高效的跨平台支持。本篇文章将介绍我们是如何基于 Go + WebAssembly + SQLite 虚拟化技术打造一套轻量且强大的 Web SDK 的。
+## 1. 架构概述
+本 SDK 的目标是让开发者能在浏览器环境下直接集成 OpenIMSDK 的即时通讯能力，同时尽可能复用原生（Go）版本的 OpenIMSDK Core，做到**“一套核心、多端复用”**。为此，我们选择了以下技术栈：
+
+### 1.1 Go + WebAssembly
+• 使用 Go 语言编写的核心逻辑，包括通信协议解析、消息拉取、消息同步等。  
+•	借助 WASM 将核心模块打包成可在浏览器执行的二进制。可在前端直接使用，无需重新实现大量逻辑。
+
+### 1.2 WebAssembly (WASM)  
+• 能将 Go 代码编译为可在浏览器运行的二进制，同时具备接近原生的性能表现。  
+• 提供必要的 JS 接口 (host functions)，支持 SDK 与前端进行双向通信。 
+
+### 1.3 数据存储：SQLite + sql.js + IndexedDB  
+• 使用 sql.js（JavaScript 版 SQLite）在浏览器中模拟本地数据库。  
+• 底层将数据存储在浏览器的 IndexedDB 中，但对开发者而言完全透明，仍然以原生 SQL 形式进行读写。  
+•	这种“虚拟化”处理方式能统一前端与原生端的数据库使用模式，减少多端差异带来的维护成本。
+
+### 1.4 API 封装：JSON 通信  
+• 通过 JSON 数据格式在 JS 与 WASM 之间进行消息传递，降低语言间调用的复杂度。  
+• 封装一层更贴近 JavaScript 开发者习惯的接口，便于快速上手。  
+
+## 2、主要技术原理
+
+### 2.1 Go + WebAssembly
+> 背景：  
+> Go 语言在高并发和网络编程上具有天然的优势，同时能够方便地将逻辑抽象、封装成一个单独的核心模块。自 Go 1.11 开始，官方就支持将 Go 代码编译为 WebAssembly 文件，这为我们在 Web 端直接运行原生逻辑提供了可能。
+
+#### 编译过程  
+  •	环境变量：在终端设置 GOOS=js GOARCH=wasm，将目标平台指定为 js/wasm。  
+  •	生成 .wasm 文件：编译后会得到一个 .wasm 文件和一个配套的 wasm_exec.js，后者是 Go 官方提供的运行时，用来启动并管理 WASM 侧的 Go 代码。
+  
+#### 交互方式  
+  •	JSON 消息传递：由于 Go 与 JS 分处不同的运行环境，直接传递复杂数据结构较为困难。因此在 Go 侧，我们定义了一组统一的 JSON 接口用于接收/返回数据；在 JS 侧，通过序列化/反序列化实现两边通信，这样即便语言不同，也能无缝对接。  
+  •	并发与网络：Go 依旧可以使用 Goroutine 等特性处理网络 I/O，浏览器端通过 WebSocket 或其他方式连接到自托管的 OpenIM 服务器，保持消息同步。
+
+### 2.2 SQLite 虚拟化
+> 为什么需要本地存储？  
+> 即时通讯场景中，客户端往往需要将聊天记录、用户信息、会话列表等存储在本地，以便在断网或刷新后能快速恢复、离线查看。在桌面或移动端，SQLite 常被用作本地数据库；在浏览器环境，我们借助 sql.js 来模拟这一行为。
+
+#### sql.js 的工作原理
+  • sql.js: 这是一个将 SQLite 以 Emscripten 编译成 JavaScript 的项目，可在浏览器中直接执行原生的 SQL 语句。  
+  • IndexedDB: 由于浏览器环境无法直接访问本地文件系统，sql.js 会将所有数据储存在内存或浏览器原生数据库 IndexedDB 中，并持久化。  
+  • 统一数据库访问: 从业务层面看，所有客户端SDK都在使用“一套 SQL”读写，无需刻意区分。对于开发者来说，迁移或共享部分逻辑时非常简便。
+
+### 2.3 前端 API 设计
+
+   • SDK 对外暴露的方法: 例如 login(), sendMessage(), getConversationListSplit() 等等；这些接口在内部会通过 JSON 字符串包装后调用 WASM 内部的对应函数。  
+   • 事件/回调处理: 例如新消息通知、连接状态变更等事件，采用在 JavaScript 中设置事件监听的方式实现。一旦有消息从 WASM 返回，则通过相应事件进行通知。
+
+## 3. 核心流程
+
+import wasm_call_map from './assets/wasm_call_map.png'
+
+<p align="center">
+    <img src={wasm_call_map} alt="预览图" width="80%"/>
+</p>
+
+如上图所示，WASM SDK 的核心调用流程为：
+1.	用户发起对 SDK API 的调用（由 JS 层对外暴露）。
+2.	JS SDK 层将调用请求传递给 WASM 实现的 OpenIMSDK Core。
+3.	WASM Core 反向调用 JS 层，执行实际的 SQLite 读写逻辑（由 sql.js 实现）。
+4.	JS 数据库访问逻辑 完成 SQLite 操作，并将结果返回给 WASM Core。
+5.	WASM Core 对结果进行封装处理后，返回给 JS SDK 层。
+6.	最终，JS 层 将处理结果返回给调用的用户。
+
+> **性能优化**：JS 层执行的 SQLite 操作都被放到了 Web Worker 中，避免了 UI 线程的阻塞。
+
+## 4. 优点与局限性
+
+### 优点
+1. 高效复用，降低维护成本  
+•	由于各端（Web、桌面、移动）可以共用同一个 OpenIMSDK Core（Go 语言编写），只需编译到对应平台即可，大幅降低多人多端项目的开发与维护难度。
+2. 接近原生性能  
+•	WASM 代码运行效率高，对加解密、序列化、消息同步等较重负载处理更友好，让大型或复杂的即时通讯应用在浏览器环境下依然表现顺畅。
+3. 稳定的本地缓存  
+•	通过 sql.js + IndexedDB 的本地缓存，用户可以在刷新、断网后仍能访问聊天记录和会话列表，提高了可用性与用户体验。
+4. 安全性  
+•	WebAssembly 运行在沙箱环境中，JS 与 WASM 间的通信边界清晰，可有效降低非预期的内存访问风险。
+5. 快速迭代  
+•	当需要更新核心逻辑时，只要重新编译 .wasm 文件并替换部署即可；前端保持基本接口不变，升级成本较低。
+
+### 局限性
+1. 浏览器兼容性  
+•	现代浏览器（Chrome、Firefox、Safari、Edge 等）对 WebAssembly 的支持已经相对完善，但在老旧浏览器上可能会出现兼容性问题。  
+•	IndexedDB 在某些特定环境下也存在奇怪的兼容性或容量限制，需要提前规划。
+2. 学习与调试难度  
+•	虽然接入 SDK 时只要调用 JS 层封装的接口即可，但如果出现底层问题，排查 Go WASM 与 sql.js 交互会比单纯的 JS 调试更复杂。
+3. 初次加载文件体积  
+•	.wasm 文件可能相对较大，在网络环境较差时会有额外的加载时间。可配合 CDN、懒加载等策略进行优化。
+4. Web Worker 通信开销  
+•	虽然将 SQLite 操作放到 Web Worker 能避免阻塞 UI，但也会带来一定的跨线程通信开销，需要在业务设计中平衡。
+
+
+## 5. 总结
+
+这套基于 WebAssembly 和虚拟化 SQLite 的 OpenIM Web SDK，在最大程度继承了 Go 端的网络与业务逻辑的同时，也充分利用了浏览器自带的 IndexedDB 进行本地持久化存储。对开发者而言，无需重写一套复杂的前端业务逻辑，即可获得接近原生性能的即时通讯能力。  
+	•	共享核心：与其他平台（移动、桌面）的 SDK 共用同一份核心逻辑，减少重复开发。  
+	•	本地缓存：用户可在浏览器端流畅查看消息历史，即便网络不佳也能完成大部分操作。  
+	•	自托管：开发者对后端服务有完全掌控力，降低外部依赖所带来的数据安全与成本压力。
+
+如果你正在寻找一款可在 Web 端灵活部署的开源即时通讯方案，或者想要掌控数据与服务端架构的自托管模式，欢迎尝试这款 SDK。它不仅能带来较高性能和安全性，也能简化你的前后端协作流程，实现快速交付。
+
+更多资源  
+• [OpenIMSDK 官网](https://www.openim.io)  
+• [OpenIMSDK 官方文档](https://docs.openim.io)  
+• [GitHub 仓库](https://github.com/openimsdk)

docs/blog/client/architectural/Browser/wasm-client-sdk-introduction.mdx

@@ -1,6 +1,6 @@
 {
-    "position": 3,
-    "label": "架构与选型",
+    "position": 2,
+    "label": "SDK架构设计",
     "collapsible": true,
     "collapsed": true
   }

docs/blog/client/architectural/_category_.json

@@ -0,0 +1,152 @@
+---
+title: Electron Demo 的快速编译与启动
+hide_title: false
+sidebar_position: 1
+---
+
+## 前言
+
+本文将带你从零开始，快速搭建并运行一个基于 OpenIMSDK 的 Electron 应用。本项目以 OpenIMSDK 开源版为基础，借助 [`@openim/electron-client-sdk`](https://www.npmjs.com/package/@openim/electron-client-sdk) 与 [`@openim/wasm-client-sdk`](https://www.npmjs.com/package/@openim/wasm-client-sdk)，能够同时构建 Web 端及桌面端（Windows、macOS、Linux）的即时通讯应用。如果你想要替换 Twilio 或 Sendbird 等第三方云通信服务，借助 OpenIMSDK 可大幅减少部署成本，完全掌握数据安全与隐私。
+
+## 1. 背景介绍
+
+OpenIMSDK 是一款开源的即时通讯 SDK，与市面上一些收费的云通信服务（如 Twilio、Sendbird）不同，OpenIMSDK 让开发者能够自行掌控服务端部署与数据，适合对安全性、可控性有较高要求的业务场景。基于 OpenIMSDK，可以轻松开发微信、Slack、Zoom 类似的即时通讯、语音视频通话等应用。
+
+import demo_preview from './assets/demo_preview.png'
+
+<p align="center">
+    <img src={demo_preview} alt="预览图" width="80%"/>
+</p>
+
+## 2. 环境准备
+
+系统要求：  
+- Windows 10 及以上  
+- macOS 10.15 及以上  
+- Linux 22.04 及以上  
+
+开发依赖：  
+- Node.js ≥ 16.x（[官网下载](https://nodejs.org) 或 [nvm](https://github.com/nvm-sh/nvm)）  
+- npm ≥ 6.x（随 Node.js 一起安装）  
+- Git（代码版本管理）
+
+请[提前部署](https://docs.openim.io/zh-Hans/guides/gettingStarted/dockerCompose)好最新版本的 **OpenIM Server**，确保本地可正常与服务端通信。
+
+## 3. 获取示例项目
+
+首先，使用 Git 拉取示例项目代码：
+
+```bash
+git clone https://github.com/openimsdk/openim-electron-demo.git
+cd openim-electron-demo
+```
+
+## 4. 安装依赖
+
+在项目根目录执行：
+
+```bash
+npm install
+```
+
+> 等待所有依赖安装完成。
+
+## 5. 配置环境变量
+
+打开项目根目录下的 .env 文件，按需修改其中的主机地址或域名配置。
+
+例如，如果你的服务器 IP 为 123.45.67.89 且没有修改过服务端端口，可以这样配置：
+
+```bash
+VITE_BASE_HOST=123.45.67.89
+
+VITE_WS_URL=ws://$VITE_BASE_HOST:10001
+VITE_API_URL=http://$VITE_BASE_HOST:10002
+VITE_CHAT_URL=http://$VITE_BASE_HOST:10008
+
+# VITE_BASE_DOMAIN=your-server-domain
+
+# VITE_WS_URL=wss://$VITE_BASE_DOMAIN/msg_gateway
+# VITE_API_URL=https://$VITE_BASE_DOMAIN/api
+# VITE_CHAT_URL=https://$VITE_BASE_DOMAIN/chat
+```
+
+> 如果你使用域名和 HTTPS（需要 nginx 配置），则取消注释带有 VITE_BASE_DOMAIN 的部分，并将 VITE_BASE_DOMAIN 修改为你的域名。同时，根据部署情况，配置正确的 wss:// 和 https:// 地址。
+
+## 6. 本地启动
+
+执行以下命令即可启动开发服务器和 Electron 应用：
+
+```bash
+npm run dev
+```
+
+> 如果你仅需要在浏览器访问，则可以在控制台看到本地服务地址（例如 http://localhost:5173）。
+> 同时，Electron 打包的桌面应用也会自动运行，方便你在桌面环境下进行调试。
+
+## 7. 音视频通话
+
+开源版 OpenIM 默认支持一对一的音视频通话功能。要使用此功能，需要在服务端安装并配置音视频服务，详情可参考[官方文档](https://github.com/openimsdk/chat/blob/main/HOW_TO_SETUP_LIVEKIT_SERVER.md)。如果你有多人音视频和视频会议需求，可以联系官方邮箱 `contact@openim.io` 获取更多支持。
+
+> **注意 ⚠️**：如果要在 Web 端调用音视频功能，需在 localhost 或 HTTPS 环境下进行，以确保满足浏览器安全策略的限制要求。
+
+## 8. 生产环境构建
+
+### 8.1 构建 Web 版本
+
+如需将 Web 版本部署到服务器，请执行：
+
+```bash
+npm run build
+```
+
+生成后的静态文件会位于 dist 目录下，然后将其上传到你的 Web 服务器或使用 nginx 等服务进行托管即可。
+
+### 8.2 构建 Electron 版本
+
+1. 将 package_electron.json 文件内容替换到 package.json，这样可以去掉仅在 Web 环境需要的依赖包，减少桌面版本应用的体积。
+2. 执行以下命令进行对应平台的打包：
+
+   • macOS：
+
+    ```bash
+    npm run build:mac
+    ```
+
+    •	Windows：
+
+    ```bash
+    npm run build:win
+    ```
+
+    •	Linux：
+
+    ```bash
+    npm run build:linux
+    ```
+
+    > **注意 ⚠️**：在 macOS 上可以打包 Windows 和 Linux 版本应用程序，但在 Windows 和 Linux系统下只能打包对应系统的应用程序。 
+
+3. 打包完成后，生成的安装包/可执行文件会位于 release 目录下。
+
+## 9. 常见问题与解决方案
+
+Q1：正式部署发布到 Web 端时，出现报错：WASM: TypeError: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'  
+A：参考官方 [nginx配置](https://docs.openim.io/zh-hans/guides/gettingstarted/nginxdomainconfig#2-%E5%9F%9F%E5%90%8D%E9%85%8D%E7%BD%AE%E6%A8%A1%E6%9D%BF-)文件，重点在于`default_type application/wasm`。
+
+Q2：正式部署发布到 Web 端时，wasm 加载过慢怎么办？  
+A：建议采用 gzip 或其他压缩方式优化 wasm 文件的体积，同时可以将其托管至 CDN，以获得更快的加载速度。
+
+Q3：CKEditorError: ckeditor-duplicated-modules  
+A：通常是依赖冲突导致，可尝试运行 npm dedupe 整理依赖后再次启动或构建。
+
+## 10. 结语
+
+通过本篇博客的指引，你应该已经能够在本地快速运行 OpenIMSDK 的 Electron 示例项目，并且对 Web 与 Electron 两种构建方式都能有一定认识。OpenIMSDK 为你提供了灵活度与可控性，希望能为你的项目带来更安全、可靠和低成本的实时通信解决方案。
+
+如果你在使用或部署的过程中遇到问题，欢迎在 [GitHub Issues](https://github.com/openimsdk/openim-electron-demo/issues) 中与社区交流，或者直接联系官方获取更多支持。
+
+更多资源  
+• [OpenIMSDK 官网](https://www.openim.io)  
+• [OpenIMSDK 官方文档](https://docs.openim.io)  
+• [GitHub 仓库](https://github.com/openimsdk)