WechatOnCloud

Project Url: Gloridust/WechatOnCloud

Introduction: 云微 WOC，云微信，自由连接

More: Author ReportBugs

Tags:

云微 · WechatOnCloud

在自己的 NAS / 服务器上运行「服务端微信」，多端浏览器共享同一个微信会话

快速开始 · 核心特性 · 运行原理 · 安全须知 · 技术方案

在飞牛 NAS（x86_64 / arm64）或任意 Docker 主机上运行服务端微信：可管理多个微信实例，每个实例是一个独立的微信会话；多个 web 用户通过浏览器访问被授权的实例，实现跨设备消息同步、多端共享。不修改微信客户端。

一句话原理：每个微信实例 = 一个容器，里面跑 Xvfb 虚拟显示 + 官方原版微信，KasmVNC 把画面串到浏览器；同一实例被多个浏览器连 = 共享同一个微信会话。前面一层自研面板是唯一对外入口，经 docker.sock 按需创建/销毁实例并反向代理。

🗂️ 多实例 — 一个面板管理多个独立微信会话，每个实例独立容器 + 独立数据卷，互不干扰。
👥 多端共享 + 权限 — 多浏览器 / 设备共享同一会话；子账号体系，按账号分配可访问的实例（RBAC）。
🖥️ 微信 PC 式界面 — 左侧实例栏 + 右侧内嵌桌面，侧栏可折叠，移动端自动转抽屉。
📦 微信本体运行时下载 — 镜像不打包微信，面板一键「下载安装 / 更新」带进度条；按 CPU 架构自动取包。
🔁 实例生命周期 — 启动 / 停止 / 重启 / 升级（拉新镜像重建、保留聊天记录），均在面板内一键完成。
📎 文件传输 + 文本剪贴板 — 拖拽上传 + 下载 + 删除，直达微信桌面 ~/Desktop；文本可经剪贴板中转送进微信（局域网 http 下也可用）。
🧩 多端协作软锁 — 同一实例多人操作时自动只读 + 申请接管，避免键鼠打架。
🔒 安全优先 — 面板为唯一入口，KasmVNC 凭据服务端注入、永不下发前端；docker.sock 仅管理员可触达。
📱 PWA — iOS「添加到主屏幕」、桌面 Chrome「安装」当原生 App。
🏗️ 多架构 — amd64 / arm64 预构建镜像（GHCR + GitHub Actions 自动发布）。

文档

文档	内容
运行原理与 Docker 指南	工作原理 + 架构图；面向 Docker 新手的逐步拆解、常用命令、架构自动适配
部署与运维	数据持久化、常见问题排查、忘记超管密码的离线找回、目录结构
发布到 GHCR	用 GitHub Actions 或本机 buildx 把镜像发布到 GHCR
技术方案	完整设计文档与选型权衡

快速开始

需已安装 Docker（含 Compose 插件）。x86_64 / arm64 均可。不熟悉 Docker？先读运行原理与 Docker 指南。

docker-compose.yml 引用的是 GHCR 上的镜像 ghcr.io/gloridust/{woc-panel,wechat-on-cloud}。 这两个镜像需先存在——要么官方已发布（你能直接拉取），要么你在本地自行构建。二选一：

方式 A · 本地自构建（官方尚未发布镜像时用这个）

git clone https://github.com/Gloridust/WechatOnCloud.git WechatOnCloud
cd WechatOnCloud
cp .env.example .env            # 至少改掉默认密码 WOC_PASSWORD
./scripts/build-local.sh        # 构建面板 + 微信实例镜像，打成 compose 用的同名标签
docker compose up -d            # compose 默认优先用本地镜像，不会再去 GHCR

方式 B · 拉取官方镜像（已发布到 GHCR 后）

git clone https://github.com/Gloridust/WechatOnCloud.git WechatOnCloud
cd WechatOnCloud
cp .env.example .env            # 至少改掉默认密码 WOC_PASSWORD
docker compose up -d            # 直接从 GHCR 拉取

报错 error from registry: denied？说明 GHCR 上还没有该镜像（或包是私有的）。用方式 A 本地构建，或见发布到 GHCR。

无论哪种方式，都会拉起面板容器 woc-panel（唯一对外服务）。浏览器访问 http://<NAS_IP>:36080：

用 .env 里设置的管理员账号（默认 admin / wechat）登录面板；
管理员在面板「实例」页点「新建微信实例」，命名并选择哪些子账号可访问 → 面板自动 docker run 起一个微信实例容器（微信镜像本地没有时才会从 GHCR 拉取）；
进入该实例，点「下载并安装」微信（约 190~210MB，进度条实时显示，仅管理员可操作）；
装好后点「进入电脑版微信」→ 浏览器里出现微信窗口，手机扫码登录即可。

之后被授权的用户换任意设备打开同一地址登录面板，看到自己有权访问的实例，进入即是同一个微信会话。

宿主只对外暴露面板的 36080 一个端口；微信实例容器仅在 docker 网络内、由面板反代，不直连宿主。要改端口/版本/账号见 .env（可配置项见 .env.example）。镜像会按 CPU 架构自动适配（详见文档）。

面板能做什么

功能	谁可用	说明
新建 / 删除微信实例	管理员	一键创建独立微信会话容器；新建时勾选可访问的子账号。删除默认保留数据卷（聊天记录），可选彻底清除
实例权限分配	管理员	在实例上改「可访问账户」，或在账户上改「可访问实例」，双向管理
下载并安装 / 更新微信	管理员	对某实例一键下载官方微信 Linux 版到其数据卷、解压安装；带进度条；后续可一键「更新到最新版」
进入电脑版微信	被授权用户	在浏览器里操作对应实例的微信，扫码登录、收发消息
文件 / 文本传输	被授权用户	拖拽上传 / 下载文件；文本经剪贴板中转送进微信
修改密码	所有人	改自己的登录密码
子账号管理	管理员	创建 / 禁用 / 重置 / 删除子账号，并分配实例访问权限
安装为 App	所有人	iOS Safari「添加到主屏幕」、桌面 Chrome「安装」当原生 App（PWA）

子账号是访问这套面板的身份，不是另开一个微信。管理员隐式拥有全部实例访问权；子账号只能看到被授权的实例。微信本体不打进镜像，而是新建实例后在面板点「下载并安装」时下载到该实例的数据卷，所以镜像很小、构建快。

资源占用

实测（8 核 / 8 GiB 宿主，实例均已登录微信、含 Chromium 内核的 WeChatAppEx）：

状态	CPU	内存（RSS）
单实例 · 空闲（已登录、无人观看）	~0.1–0.2 核	~0.6 GiB
单实例 · 活跃（有人在浏览器操作 / 刷消息）	~0.5–1 核（可突发）	~1–1.5 GiB
面板本身	可忽略	~0.12 GiB

容器不设硬性 CPU/内存上限：空闲时省，活跃时按宿主余量突发；每实例另预留 1 GiB /dev/shm（微信 Chromium 内核所需，tmpfs，按需占用）。
估算：面板 ≈ 0.15 GiB 常驻；每个微信实例按 1 vCPU + 1.5 GiB 内存预留较从容（轻度使用可更低）。
参考容量：2 核 / 2 GiB 跑 1 个实例（轻度）；4 核 / 8 GiB 跑 3–4 个实例；视频通话等重负载需再加预留。

内存是主要瓶颈，CPU 多为短时突发。实例越多越吃内存，按上表线性叠加即可估算。

安全须知（必读）

⚠️ 这套系统暴露的是已登录的微信，请务必认真阅读本节。

能登录面板的人就能看聊天记录、以你身份发消息。面板还挂载了宿主的 docker.sock（创建/销毁实例所需），它等同宿主 root 权限。因此：

绝不要把面板裸暴露公网：只在内网访问，或经飞牛远程访问 / VPN / 内网穿透；
务必改掉默认密码（默认 admin / wechat）：cp .env.example .env 后改 WOC_PASSWORD，或登录后在「修改密码」里改；
实例的增删、微信安装/更新等触碰 docker 引擎的操作仅限管理员；docker API 绝不暴露给前端；
KasmVNC 凭据由面板服务端注入，浏览器永远拿不到；实例容器名由内部随机 ID 派生，避免注入；
面板与外网之间再套一层 HTTPS 反代（飞牛自带反代 / Caddy / Nginx）获得正经 TLS；
进一步加固（陌生设备验证码、审计日志、并发控制）见技术方案.md 第 5 节。

中文输入

用你本地（客户端）的输入法打中文，容器内无需安装任何 IME。 镜像默认开启 KasmVNC 的「IME Input Mode」，并对 noVNC 的 IME 合成逻辑做了修复——只在输入法「上屏」那一刻把成品汉字整串发进容器，规避了原生实现逐字符差分带来的丢字 / 卡顿。直接在微信输入框打字即可。

默认值只对未存过该设置的浏览器生效。之前手动开/关过的，浏览器 localStorage 值优先；想验证默认效果用无痕窗口。
跨设备文本：实例工具栏的「剪贴板」可把文本送入容器剪贴板，再在微信里 Ctrl+V 粘贴——不依赖浏览器异步剪贴板 API，局域网 http 访问下也可用。
文件：用工具栏「文件」拖拽上传，微信收到的文件另存到桌面即可在此下载。