# WechatOnCloud 技术方案

> 目标：在飞牛 NAS（x86_64）或任何服务器上运行服务端微信，多个 web 用户通过浏览器访问同一个微信会话，实现跨设备消息同步、多端共享，解决原生微信"一台电脑一个登录"的痛点。

---

## 1. 核心认知：单会话多端共享，而非多用户登录

微信桌面端的登录是**手机扫码绑定的单一会话**——同一账号同一时刻只能有一个桌面端在线。

因此"多个 web 用户登录同一个微信"的本质是：

> **服务器上跑 1 个微信进程，把它的画面 + 输入流共享给多个 web 客户端。**

这不是多租户、也不是多开同一账号，而是**一个进程、多个观察/操作者**。这个认知决定了整个架构：核心是"共享屏幕串流"，而不是"会话隔离"。

懒猫微服的云微信也是同思路：**官方原版客户端不做任何修改 + 容器化 + 内网穿透**，额外加了"陌生设备访问需管理员一次性验证码"。本方案沿用此路线。

> 说明：懒猫宣传的"无限多开"是指**多个不同账号各跑一个容器**，不是一个账号多端独立登录。单账号仍是单会话共享。

---

## 2. 为什么不用「虚拟机 + 局部远程桌面」

- **资源浪费**：飞牛 NAS 多为 N100 等低功耗 x86，全量 VM + 完整桌面开销大。
- **脆弱**：抓窗口坐标做"局部远程桌面"，分辨率/缩放一变就裂。
- **多余**：飞牛 OS 本身是 **Debian 系**，Docker 是一等公民，无需 VM 这层抽象。

结论：**容器化 + 虚拟显示 + 串流**，比 VM 方案更轻、更稳、更易分发。

---

## 3. 推荐架构

```
┌─────────────────────────────────────────────────┐
│ Docker 容器 (Debian base, amd64 / arm64 自适应)    │
│                                                   │
│   微信 Linux 原生版 (官方 .deb, 4.0, 按架构自动选)  │
│         │ 渲染到                                   │
│   Xvfb 虚拟显示 :99  (+ 轻量 WM, 如 openbox)       │
│         │ 被串流                                   │
│   串流服务 (KasmVNC / Xpra-html5)                  │
│         │ WebSocket                               │
└─────────┼──────────────────────────────────────────┘
          │
   反向代理 + 鉴权 + TLS (Caddy / nginx)
          │
   ┌──────┴───────┬───────────────┐
  web 用户A      web 用户B        web 用户C
   （三人看同一画面、可操作同一会话）

   数据卷挂载: ~/xwechat 等 → 持久化登录态与消息
```

---

## 4. 组件选型

### 4.1 微信客户端 —— 官方 Linux 原生版

- 来源：<https://linux.weixin.qq.com/>（2024-11 官方上线）
- 架构：x86_64 / arm64 / LoongArch，提供 deb / rpm / AppImage
- **本项目按构建机架构自动选包**：Dockerfile 用 BuildKit 的 `TARGETARCH` 判断，amd64→`WeChatLinux_x86_64.deb`，arm64→`WeChatLinux_arm64.deb`。这样 x86 NAS、arm NAS、Apple Silicon Mac 本地调试都是同一条 `docker compose up --build`，无需改配置
- 版本：4.0，功能与 Windows/Mac 4.0 对齐
- **不用 Wine 转译版**：原生版稳定，且和懒猫一样"不改客户端、合法、不易封号"

### 4.2 虚拟显示 —— Xvfb

- 无头环境提供 X11 显示（`:99`）
- 配一个极轻量窗口管理器（openbox/fluxbox），让微信窗口能正常 maximize/管理

### 4.3 串流层 —— KasmVNC（一期）/ Xpra（二期优化）

| 维度 | **Xpra** (+ xpra-html5) | **KasmVNC** |
|------|--------------------------|-------------|
| 呈现 | 单窗口 seamless（浏览器里只显示微信窗口，像独立 App） | 带 WM 的完整桌面 |
| 多客户端共享 | ✅ sharing 模式（服务端+客户端均需开启） | ✅ 原生多用户 |
| 会话持久化 | ✅ 进程不掉，可 detach/reattach | ✅ |
| HTML5 客户端 | ✅ 自带 | ✅ 自带 |
| 图像性能 | 好 | 很好 |
| 调试难度 | seamless + HTML5 配置略繁琐 | 简单、稳 |

**决策：一期先用 KasmVNC 把链路跑通，二期再考虑换 Xpra 优化"独立 App"观感。**
理由：KasmVNC 稳、配置少，能最快验证"扫码登录 + 收发消息 + 多端共享"这条核心链路；Xpra seamless 模式观感更好但调起来更费劲，留到核心稳定后再做。

### 4.4 反向代理 + 鉴权 + TLS —— Caddy 或 nginx

见第 5 节安全设计（**这是整套方案最关键的一环**）。

### 4.5 数据持久化 —— Docker volume

- 挂载微信数据目录（如 `~/xwechat`、`~/.config` 相关路径）为命名卷
- 否则每次重启容器都要重新扫码登录

---

## 5. 安全设计（最关键，必须做）

⚠️ 这套系统暴露的是一个**已登录的微信**：任何能访问该端口的人都能看到全部聊天记录、并以你的身份发消息。安全是第一优先级，不是可选项。

必须满足：

1. **强制 TLS**：全程 HTTPS/WSS，不允许明文。
2. **独立鉴权层**：不要只靠裸 VNC 密码。在反向代理上加独立登录（如 Caddy forward_auth / Authelia，或飞牛系统用户体系）。
3. **默认不暴露公网**：
   - 一期只在内网访问；
   - 远程访问走飞牛 FN Connect / VPN / 内网穿透；
4. **陌生设备二次验证**（可选，学懒猫）：新设备首次访问需管理员一次性验证码。
5. **最小权限容器**：非 root 运行微信进程，限制容器能力。

---

## 6. 两个必须处理的工程细节

### 6.1 并发输入冲突

多人同时操作同一会话，键鼠会互相打架。

- **方案**：加一层"控制权令牌"——同一时刻仅一人可操作，其余人只读；支持抢占/移交；UI 显示当前控制者。
- 一期可先不做（自己/家人小范围用），但要在设计上预留。

### 6.2 掉登录 → 重扫码

微信桌面会话会定期失效，需手机重新扫码。

- 持久化数据卷能**降低**重扫频率，但不能消除。
- 需设计一个入口：当微信弹出二维码时，让管理员能在 web 端看到并用手机重扫。

---

## 7. Docker vs 飞牛原生 fpk

| | Docker（一期） | fpk 原生包（后期） |
|---|---|---|
| 飞牛支持 | 一等公民（Docker/Compose） | 原生 App 形态，进应用中心 |
| 开发效率 | 高，好调试好更新 | 需按 [fpk 框架](https://developer.fnnas.com/docs/core-concepts/framework) 适配 |
| 系统集成 | 一般 | 好（用户体系、分发） |
| 本质 | —— | 仍是包装同一容器/进程 |

**策略：一期纯 Docker（`docker-compose.yml`）跑通核心；待稳定后再包 fpk 做分发层。不要一开始就上 fpk。**

---

## 8. 计划目录结构（一期 Docker）

```
WechatOnCloud/
├── docker/
│   ├── Dockerfile           # Debian + Xvfb + 微信deb + KasmVNC
│   ├── entrypoint.sh        # 启动 Xvfb → WM → 微信 → KasmVNC
│   └── supervisord.conf     # 进程守护（可选）
├── docker-compose.yml       # 服务编排 + 卷 + 端口
├── caddy/
│   └── Caddyfile            # 反向代理 + TLS + 鉴权
└── README.md
```

---

## 9. 落地路线图

1. **跑通核心链路**：Debian + Xvfb + 官方微信 deb + KasmVNC，浏览器能扫码登录、收发消息。
2. **加固**：反向代理 + 独立鉴权 + TLS + 数据卷持久化。
3. **多端共享**：验证多 web 端共享同一会话 + 加并发控制锁。
4. **观感优化（可选）**：换 Xpra 改为单窗口 App 体验。
5. **分发（可选）**：包成飞牛 fpk。

---

## 10. 已知风险 / 待验证

- **微信反无头/反虚拟化检测**：原生 Linux 版一般无问题（登录门槛在手机扫码），需实测确认。
- **资源占用**：微信 Linux 原生版偏重 + 串流编码吃 CPU。NAS 无 GPU，需用 CPU 友好的编码设置（KasmVNC 较省）。单实例 N100 级应可承受，需压测。
- **封号风险**：官方不改客户端理论上合法，但"服务器常驻 + 多端"是否触发风控需观望（懒猫宣称"永不封号"，仅作参考，不保证）。
- **重扫码频率**：实际失效周期需观察。

---

## 11. 参考链接

- [微信 Linux 官网](https://linux.weixin.qq.com/en)
- [腾讯上线 Linux 微信官网（x86/Arm/LoongArch）](https://finance.sina.com.cn/tech/roll/2024-11-06/doc-incvceuc0172323.shtml)
- [懒猫微服 云微信](https://lazycat.cloud/)
- [Xpra 官方文档](https://xpra.org/manual)
- [Xpra HTML5 客户端](https://github.com/Xpra-org/xpra-html5)
- [飞牛 fpk 框架文档](https://developer.fnnas.com/docs/core-concepts/framework)