feat: add electron quick build & wasm arch docs

Author: Bloomingg

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

@@ -3,3 +3,114 @@ 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,5 +1,152 @@
 ---
-title: Electron Demo快速编译
-hide_title: true
+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)

docs/blog/client/build/Electron/assets/demo_preview.png

@@ -1,5 +1,32 @@
 ---
-title: Wasm Client SDK线上加速
-hide_title: true
+title: Wasm Client SDK线上优化
+hide_title: false
 sidebar_position: 1
 ---
+
+## 前言
+在利用 OpenIM 的 WebAssembly（Wasm）SDK 完成即时通讯功能集成并上线后，作为使用者，接下来你可能会关注如何在应用层面进一步提升用户体验和可维护性。
+以下从缓存策略、离线能力、消息管理、线程与错误处理，以及运行监控等几个方面来说明可执行的优化措施。
+
+### 1. 缓存与加载策略
+
+#### 1.1 静态资源缓存
+• .wasm 文件缓存：即使你不自行修改 SDK 源码，仍可在服务器端/前端构建工具中启用 Gzip 或 Brotli 压缩，并配置合理的 Cache-Control 头，以确保用户在首次加载后能有效复用该文件。  
+• 版本区分：当有新版本要上线时，可以通过修改 .wasm 文件命名（或其 URL 路径）来避免与旧缓存冲突；这样浏览器会从头加载最新的文件。
+
+#### 1.2 懒加载/按需加载
+• 如果你的项目包含多个独立页面或功能模块，且用户并不会在每次打开就进入聊天界面，那么可将 SDK 的加载逻辑延迟到真正需要时才执行。  
+• 例如，在用户进入“消息中心”或“聊天窗口”时，才加载或初始化该 Wasm SDK；可以显著缩短首页加载时间。
+
+
+### 2. IndexedDB 与离线支持
+
+#### 2.1 IndexedDB 空间管理
+• 清理或限制历史消息：在浏览器端使用 IndexedDB 进行本地缓存虽然方便，但如果消息量不断累积而没有任何清理策略，空间占用可能越来越大。  
+• 可以在应用层定期清理较早的聊天记录（如只保留最近 3 个月）。  
+• 也可提供给用户手动“清空本地缓存”的入口。
+
+#### 2.2 离线可用性
+• 借助 Service Worker 或 PWA 特性，可使用户在离线状态下仍能访问本地缓存的聊天记录。  
+• 当网络恢复时，再自动完成消息的同步与发送。  
+• 这对于弱网或经常断网的用户场景非常有用，用户体验更加顺畅。