Gloridust/WechatOnCloud · 上手攻略

  • 仓库：Gloridust/WechatOnCloud
  • 链接：https://github.com/Gloridust/WechatOnCloud
  • 分类：devops · selfhosted · social
  • 作者：Tom
  • 更新：2026-08-09

是什么

WechatOnCloud（WOC，云微）是一个开源的"服务端微信"解决方案：在飞牛 NAS（fnOS）或任意 Docker 主机上，以容器方式运行微信 Linux 原生版，通过 Web 界面（KasmVNC 串流）供多个用户浏览器共享同一个微信会话，同时支持 Chrome 浏览器实例登录 Telegram / X / Instagram 等网页应用。

一句话定位：把微信和网页版社媒搬上私有云，多设备浏览器共享同一登录态。

GitHub 星标 3511（截至 2026-08-09，周增 +21）。当前版本 v1.4.9，支持 amd64 / arm64 双架构，Docker Hub + GHCR 双镜像源。

⚠️ 安全重要提醒：运行的是已登录微信，任何能访问该端口的人都能看到全部聊天记录并以你的身份发消息。严禁将面板暴露公网；远程访问必须走 VPN / 内网穿透 + TLS。

解决什么问题

痛点 1：微信桌面端同一账号同时只能有一个设备在线；换设备就需重新扫码，多人协作场景无法共享同一会话。

痛点 2：NAS 用户想在服务器上常驻微信，但不想开一台独立 VM（资源开销大、脆弱、难维护）。

痛点 3：在飞牛 OS 这类轻量 NAS 上运行带 GUI 的微信，虚拟显示 + 串流是比 VM 更轻量的解法。

解决：每个实例 = 一个独立 Docker 容器，跑 Xvfb 虚拟显示 + 微信 Linux 原生版 + KasmVNC；面板（woc-panel）作为唯一对外入口，经 docker.sock 管理容器生命周期；多浏览器用户通过 Web 连接同一个实例，实现跨设备同步、多端共享。

快速安装

前提条件

  • Docker（含 Compose 插件）
  • x86_64 或 arm64 架构
  • 约 2-4 GB 可用磁盘空间（微信约 190-210 MB）

⚠️ 不熟悉 Docker？先读 运行原理与 Docker 指南。

方式 A：一条命令部署（推荐）

# 1. 创建空目录并进入
mkdir woc && cd woc

# 2. 下载官方 docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/Gloridust/WechatOnCloud/main/docker-compose.yml -o docker-compose.yml

# 3. 修改默认密码（强烈建议，至少改 WOC_PASSWORD）
# 方式一：创建 .env 文件
cp .env.example .env  # 从 https://github.com/Gloridust/WechatOnCloud/blob/main/.env.example 获取
# 编辑 .env，改 WOC_PASSWORD 为强密码

# 4. 启动
docker compose up -d

# 5. 访问面板
# 浏览器打开 http://<NAS_IP>:36080
# 默认账号 admin / wechat，登录后立即改密码

方式 B：飞牛 OS（fnOS）/ 群晖 NAS 可视化部署

  1. 在 NAS Docker 管理界面找到「Compose 部署」选项
  2. 将 docker-compose.yml 全文粘贴进去
  3. 填入环境变量（WOC_PASSWORD 等）
  4. 点击部署，无需命令行

方式 C：本地自构建（官方镜像未发布时用）

git clone https://github.com/Gloridust/WechatOnCloud.git
cd WechatOnCloud
cp .env.example .env   # 修改 WOC_PASSWORD 等
./scripts/build-local.sh
docker compose up -d

⚠️ NAS 用户首次建实例卡住的解决方案：

Docker Hub 加速通常只覆盖 NAS 界面手动拉取，不覆盖面板经 docker.sock 触发的拉取，导致实例镜像拉取超时（timeout）。

最省事解法：先在 NAS Docker → 镜像 → 拉取 里手动拉一次 gloridust/wechat-on-cloud:latest，镜像到本地后面板新建实例直接复用，不再联网拉取。

核心用法

新建第一个微信实例

1. 浏览器访问 http://<NAS_IP>:36080 ，用 admin/wechat 登录
2. 进入「实例」页 → 点击「新建实例」
3. 选「应用类型」：微信 或 Chromium 浏览器
4. 填实例名称（如 "我的微信"）
5. 勾选可访问的子账号（默认 admin 全权限）
6. 点「创建」→ 面板自动 docker run 起实例容器
7. （微信实例）点「下载并安装微信」→ 约 190-210 MB，带进度条
8. 微信安装完成后，点「进入实例」→ 扫码登录

新建浏览器实例（登录 Telegram/X/Instagram 等）

1. 新建实例时选「Chromium 浏览器」（Chromium 已烤进镜像，无需下载）
2. 点「进入实例」→ 直接打开 Chromium
3. 在 Chromium 里正常登录 Telegram Web / X.com 等
4. 登录态写入数据卷 /config，容器重启保留

文件传输

  • 上传：拖拽文件到实例窗口，直接放到 ~/Desktop
  • 下载：在实例内选中文件，点工具栏下载
  • 剪贴板中转：本地复制 → 工具栏粘贴按钮 → 文字进入实例

⚠️ 剪贴板中转在局域网 HTTP 下可用；公网建议配合 TLS。

实例升级

面板内点「检查更新」→「一键升级全部实例」
（拉新镜像 + 重建容器 + 保留数据卷 → 聊天记录不丢）

常用配置项（.env）

变量 默认值 说明
WOC_PASSWORD wechat 面板管理员密码，部署即改
WOC_HTTP_PORT 36080 面板 HTTP 端口
WOC_IMAGE_PREFIX gloridust 镜像前缀，换源用
PANEL_ALLOWED_HOSTS 空 允哪些 Host 访问，解决部分 DNS-Rebinding 拦截

镜像源切换（拉不动时）：

# 换 GHCR
WOC_IMAGE_PREFIX=ghcr.io/gloridust docker compose up -d

# 换南京大学镜像（国内可达）
WOC_IMAGE_PREFIX=ghcr.nju.edu.cn/gloridust docker compose up -d

典型适用场景

场景 说明
家庭/团队微信共享 多成员浏览器访问同一微信账号，无需每个人都登录
NAS 常驻微信 服务器上 24 小时运行，换设备不丢会话
网页版社媒多端同步 Telegram/X/Instagram 常驻云端，跨设备无缝衔接
飞牛 fnOS 用户 原生支持 docker-compose，可视化部署门槛低
无头服务器微信管理 无 GUI 的 Linux 服务器跑微信，非 VM 方案

架构原理

┌─────────────────────────────────────────────┐
│  Docker 容器 (Debian base, amd64/arm64)      │
│                                              │
│  微信 Linux 原生版 4.0（官方 .deb，按架构自选）│
│         ↓ 渲染到                              │
│  Xvfb 虚拟显示 :99 + openbox 轻量窗口管理器   │
│         ↓ 串流                               │
│  KasmVNC（WebSocket → 浏览器）               │
└────────────┬────────────────────────────────┘
             │ 反向代理 + TLS + 鉴权
             ↓
    ┌────────┴────────┐
    │  woc-panel      │ ← 唯一对外入口，:36080
    │  (用户浏览器)   │
    └─────────────────┘
  • 微信来源：Linux 原生版 4.0，来自 linux.weixin.qq.com（x86_64 / arm64 / LoongArch），不改客户端
  • 串流方案：KasmVNC（相较 Xpra 的优势：配置简单、稳定性高、HTML5 客户端开箱即用）
  • 并发控制：同一实例多人同时操作时自动只读锁 + 申请接管机制，避免键鼠冲突

⚠️ 实测资源占用（8 核 / 8 GiB 宿主，实例均已登录微信含 Chromium 内核）：README 有记录，具体数字请自行查阅（v1.4.9 版本实测数据）。

坑与注意

  1. 严禁暴露公网：这是最高风险点。任何能访问面板的人都能操作你的微信。建议全程走内网 + VPN / 飞牛 FN Connect 内网穿透访问。
  2. 首次建实例拉取超时：NAS Docker Hub 加速不覆盖 docker.sock 拉取，先手动拉镜像到本地是稳定解法（见上文）。
  3. 微信会话定期失效：微信桌面端会定期要求手机重新扫码，持久化数据卷能降低频率但不能消除；需在 web 界面重新扫码。
  4. 磁盘空间预检：v1.4.9 起安装前会检查磁盘空间；之前版本若报"卡在 28%"且网络正常，极可能是磁盘满。
  5. Tailscale / IPv6 内网支持：v1.4.9 起已支持 Tailscale CGNAT 段（100.64.0.0/10）和内网 IPv6（fc00::/7 / fe80::/10）；旧版本这些地址会被 400 拒绝。
  6. 封号风险：官方 Linux 原生版 + 不改客户端理论上合法，懒猫微服宣称"永不封号"；但 WechatOnCloud 是第三方方案，无法保证，建议小号测试。
  7. 多端操作软锁：同实例多人同时操作时其他人只读，需申请接管；多人协作前了解这一机制。
  8. 子账号 ≠ 微信账号：子账号是访问面板的身份，不是另开微信账号；同一微信实例共享同一个微信会话。

与同类对比

方案 架构 微信官方客户端 多端共享 资源占用 适合谁
WechatOnCloud 容器 + Xvfb + KasmVNC ✅ Linux 原生 4.0 ✅ 轻量 NAS / 服务器用户
懒猫微服 容器 + 内网穿透 ✅ ✅ 轻量 不想自建的用户（付费）
虚拟机方案 VM + 完整桌面 ✅ ✅ 重（需分配 CPU/RAM/存储） 有足够资源的 NAS
网页微信 无 ❌（网页版功能阉割） ✅ 极轻 仅轻度使用

懒猫微服是同类商业产品（付费），WechatOnCloud 是自建开源方案，核心思路一致（不改客户端 + 容器化 + 串流）。

一句话推荐结论

NAS / 服务器用户运行微信的最佳开源方案——如果你有飞牛 fnOS 或任何 Docker 主机，想把微信和网页版社媒常驻云端并多端共享，WechatOnCloud 以轻量容器 + KasmVNC 串流提供了比 VM 更稳、更省资源的完整解法；但安全性是第一优先级，严禁公网暴露，建议配合 VPN 使用。