WechatOnCloud 딥다이브
— 微信을 통째로 클라우드에 올려 브라우저로 쓰는 셀프호스팅 시스템

1프로젝트 한줄 요약

WechatOnCloud(줄여서 WOC, "云微")는 NAS나 리눅스 서버 위에서 PC용 微信(위챗)을 통째로 돌리고, 그 화면을 브라우저로 원격 접속해서 쓰게 해주는 셀프호스팅 시스템입니다. 微信 데스크탑 앱은 한 글자도 수정하지 않고, 리눅스 컨테이너 안에서 "원본 그대로" 실행한 다음 화면만 웹으로 중계합니다.

핵심 구조는 한 문장으로 요약됩니다: 微信 실례 1개 = 컨테이너 1개. 컨테이너 안에서 Xvfb(가상 화면) + 원본 微信이 돌고, KasmVNC가 그 화면을 브라우저로 스트리밍합니다. 같은 실례에 여러 브라우저가 접속하면 = 같은 微信 세션을 공유하는 것이 됩니다.

2왜 주목받는가

WOC는 TrendShift 주간 6위·월간 4위에 오른 셀프호스팅 프로젝트입니다. 微信은 같은 계정을 여러 PC에서 동시에 쓰기 어렵고, 데스크탑 세션이 자주 끊기며, 외부에서 접속하기 번거롭다는 오래된 불편이 있습니다. WOC는 이 문제를 "微信을 개조하지 않고" 컨테이너 + 원격 데스크탑 기술로 우회합니다.

경쟁 방식 대비 위치

3기술 스택 전체 지도

WOC는 크게 세 덩어리입니다. ① 문지기이자 두뇌인 패널(panel), ② 微信이 실제로 도는 微信 실례 이미지, ③ 이 둘을 빌드·배포하는 인프라/CI. 언어 구성은 TypeScript 78%, CSS 13%, Shell 6%로, "타입스크립트로 쓴 게이트웨이 + 셸 스크립트로 짠 실행 환경"이라는 성격이 그대로 드러납니다.

백엔드 — 패널 서버 (panel/server)

프론트엔드 — 패널 웹 UI (panel/web)

微信 실례 실행 환경 (docker/)

인프라 / 배포

4아키텍처 심화 분석

전체 그림은 "브라우저 → 패널 → Docker 엔진 → 微信 실례 컨테이너"의 한 줄짜리 흐름입니다. 단, 브라우저는 微信 컨테이너에 직접 닿지 못합니다. 모든 트래픽은 패널을 거치고, 패널이 자격증명을 서버 쪽에서 끼워 넣어 微信 실례로 리버스 프록시합니다.

설계 패턴 1 — docker.sock 동적 컨테이너 오케스트레이션

가장 핵심적인 트릭입니다. 보통 컨테이너는 docker-compose.yml에 미리 적어두지만, WOC의 微信 실례는 사용자가 "새 微信 실례" 버튼을 누른 순간 패널이 만들어 냅니다. 패널 컨테이너에 호스트의 /var/run/docker.sock을 마운트해 두면, 패널 안의 dockerode가 호스트 Docker 엔진을 "리모컨"처럼 조종해 docker run을 대신 실행합니다.

# docker-compose.yml — 서비스는 패널 하나뿐. docker.sock을 마운트하는 게 포인트.
services:
  panel:
    image: ${WOC_IMAGE_PREFIX:-docker.io/gloridust}/woc-panel:${WOC_VERSION:-latest}
    container_name: woc-panel
    environment:
      - PORT=8080
      - WOC_WECHAT_IMAGE=${WOC_IMAGE_PREFIX:-docker.io/gloridust}/wechat-on-cloud:${WOC_VERSION:-latest}
      - PANEL_ADMIN_USER=${WOC_USER:-admin}
      - PANEL_ADMIN_PASSWORD=${WOC_PASSWORD:-wechat}   # 기본 비번 꼭 변경!
    volumes:
      - ./data-panel:/data                              # 패널 계정/실례 메타
      - /var/run/docker.sock:/var/run/docker.sock       # Docker 리모컨 = 호스트 root 권한
    ports:
      - "${WOC_HTTP_PORT:-36080}:8080"                  # 유일한 대외 입구
    restart: unless-stopped

설계 패턴 2 — 단일 입구 + 자격증명 서버사이드 주입

브라우저는 KasmVNC의 비밀번호를 절대 받지 못합니다. 사용자가 데스크탑에 들어가면, 패널이 /desktop/:id/*로 들어온 요청에 Basic 인증 헤더를 서버에서 끼워 넣어 해당 실례로 프록시합니다. 즉 "열쇠는 문지기만 들고, 손님은 문지기를 통해서만 방에 들어간다"는 구조입니다. 실례 컨테이너 이름도 내부 랜덤 ID에서 파생해 추측/주입을 막습니다.

설계 패턴 3 — 런타임 CPU 아키텍처 자동 감지

微信은 x86_64와 arm64용 deb만 제공합니다. WOC 이미지는 멀티아치라 어디서든 같은 docker compose up -d로 뜨고, 微信을 내려받는 순간 컨테이너 안에서 dpkg --print-architecture로 CPU를 감지해 맞는 패키지를 가져옵니다.

설계 패턴 4 — 微信 본체는 "이미지가 아니라 볼륨"에

微信 앱 자체는 이미지에 넣지 않습니다. 새 실례를 만든 뒤 패널에서 "다운로드 및 설치"를 누르면, 그때 텐센트 CDN에서 받아 그 실례의 데이터 볼륨에 풀어 설치합니다. 덕분에 이미지가 작아 빌드가 빠르고, 텐센트 CDN에 빌드가 묶이지 않으며, 微信만 따로 "최신으로 업데이트"하기도 쉽습니다. 다운로드·설치·상태는 셸 스크립트 wechat-ctl.sh가 맡고, 패널이 docker exec로 이를 트리거합니다.

설계 패턴 5 — 중문 입력(IME)을 클라이언트에서 처리

원격 데스크탑에서 한자/한글 입력은 악명 높은 난제입니다. WOC는 컨테이너 안에 입력기를 깔지 않고, KasmVNC의 IME 입력 모드를 켜서 "내 PC의 입력기로 완성된 글자만" 컨테이너로 보냅니다. 원래 noVNC 구현은 키 입력을 글자 단위로 다시 쏘다가 글자가 새거나 누락되는데, WOC는 입력 완료 시점(compositionend)에 완성 문자열만 직접 보내도록 웹 클라이언트 번들을 패치했습니다.

5디렉토리 구조 해부

핵심 파일/폴더별 역할

요점: 소스 트리에 "微信 실례"는 폴더로 보이지 않습니다. 그것은 실행 중에 패널이 만들어내는 동적 컨테이너이기 때문입니다. 소스에는 "그 실례를 어떻게 만들지"의 설계도(docker/)와 "누가 그것을 만드는지"의 두뇌(panel/)만 있습니다.

6학습 포인트 (기술별)

6-1. docker.sock + dockerode 동적 오케스트레이션

이 레포의 가장 값진 패턴입니다. "프로그램이 코드로 컨테이너를 만들어내는" 방식을 배웁니다. dockerode로 컨테이너를 생성하고, 볼륨을 붙이고, 같은 네트워크에 연결하는 흐름을 익히면 "셀프호스팅 PaaS"의 축소판을 만들 수 있습니다.

// dockerode로 微信 실례 컨테이너를 동적으로 만드는 개념 코드
import Docker from "dockerode";
const docker = new Docker({ socketPath: "/var/run/docker.sock" });

const c = await docker.createContainer({
  Image: process.env.WOC_WECHAT_IMAGE,        // 微信 실례 이미지
  name: `woc-wx-${id}`,                        // 랜덤 id로 컨테이너 이름
  HostConfig: {
    Binds: [`woc-data-${id}:/config`],         // 실례 전용 볼륨
    NetworkMode: net || undefined,              // 패널 컨테이너와 공유 중인 네트워크(동적 탐지, 없으면 기본 브리지)
    SecurityOpt: ["seccomp=unconfined"],       // 微信 구동에 필요
    ShmSize: 1024 * 1024 * 1024,               // 1 GB
  },
});
await c.start();

6-2. 원격 데스크탑 스트리밍 (Xvfb + openbox + KasmVNC)

"GUI 앱을 서버에서 돌려 브라우저로 보여주기"의 표준 레시피를 배웁니다. 모니터 없는 서버에 가상 화면(Xvfb)을 만들고, 가벼운 창 관리자(openbox)로 앱을 띄운 뒤, KasmVNC로 그 화면을 웹으로 중계합니다. 微信 자리에 어떤 GUI 앱을 넣어도 같은 원리입니다.

6-3. 리버스 프록시 + 자격증명 주입 게이트웨이

"백엔드의 비밀을 프론트에 노출하지 않고 안전하게 중계"하는 패턴입니다. 사용자는 패널 쿠키로만 인증하고, 패널이 뒤쪽 서비스(KasmVNC)의 Basic 인증을 서버에서 끼워 넣습니다. API 키를 숨겨야 하는 모든 프록시에 응용됩니다.

6-4. 멀티아치 Docker 이미지 (buildx + QEMU)

amd64 NAS와 arm64 NAS 양쪽에서 같은 명령으로 도는 이미지를 만드는 법을 배웁니다.

# QEMU 설치(리눅스에서 크로스 빌드 시) → buildx 빌더 생성 → 멀티아치 빌드/푸시
docker run --privileged --rm tonistiigi/binfmt --install all
docker buildx create --name woc --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/gloridust/woc-panel:1.0.1 -t ghcr.io/gloridust/woc-panel:latest \
  --push ./panel

6-5. GitHub Actions 릴리스 자동화 + GHCR

버전 태그를 푸시하면 멀티아치 이미지가 자동으로 빌드·배포되는 CI/CD 파이프라인을 배웁니다. "태그 = 배포"라는 깔끔한 릴리스 규칙을 직접 경험할 수 있습니다.

# 태그를 밀면 Actions가 멀티아치 이미지를 빌드해 GHCR로 푸시
git tag v1.0.0
git push origin v1.0.0
# latest까지 갱신하려면 Release 발행 또는 workflow_dispatch 사용

6-6. PWA + 원격 IME 입력 처리

웹앱을 네이티브 앱처럼 설치하는 PWA, 그리고 원격 데스크탑의 고질적 난제인 한자/한글 입력을 compositionend 시점에 완성 문자열만 보내 해결하는 기법을 배웁니다. 한국어 IME 문제와도 똑같은 원리라 한글 입력 처리에 그대로 응용됩니다.

7하드웨어 / 시스템 요구사항

최소 요구사항

• Docker + Compose 플러그인 설치된 리눅스 호스트(飞牛 NAS·일반 서버·VPS 등)
• CPU 아키텍처: x86_64(amd64) 또는 arm64 (微信이 이 둘만 지원)
• 디스크: 微信 본체 실례당 약 190~210MB + 메시지 캐시
• 네트워크: 微信 다운로드를 위해 텐센트 CDN 접근 가능해야 함
• 대외 포트: 패널 1개(36080)만. 微信 실례는 내부 네트워크에만

꼭 알아야 할 실행 옵션(함정)

데이터 영속화 / 백업

패널 데이터는 호스트 ./data-panel에, 각 微信 실례는 Docker 명명 볼륨 woc-data-<id>에 저장됩니다. 실례를 삭제해도 기본적으로 볼륨은 남겨(같은 이름으로 재생성하면 복구), "완전 삭제"를 명시해야 볼륨까지 지워집니다. 특정 실례 백업 = 그 woc-data-<id> 볼륨 백업입니다.

8직접 해볼 수 있는 실습 과제

git clone https://github.com/Gloridust/WechatOnCloud.git
cd WechatOnCloud
cp .env.example .env            # WOC_PASSWORD 기본 비번 변경
docker compose up -d            # 패널 컨테이너 woc-panel 기동
docker logs -f woc-panel        # 로그 확인 후 브라우저로 :36080 접속

// POST /spawn → 새 컨테이너 생성, DELETE /spawn/:id → 제거
import Docker from "dockerode";
const docker = new Docker({ socketPath: "/var/run/docker.sock" });
app.post("/spawn", async (req, reply) => {
  const c = await docker.createContainer({ Image: "nginx:alpine" });
  await c.start();
  return { id: c.id.slice(0, 12) };
});

FROM lscr.io/linuxserver/baseimage-kasmvnc:debianbookworm
RUN apt-get update && apt-get install -y --no-install-recommends gimp
COPY autostart /defaults/autostart   # 시작 시 gimp 실행
EXPOSE 3000 3001

echo $GITHUB_PAT | docker login ghcr.io -u <user> --password-stdin
docker buildx create --name demo --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/<user>/my-app:1.0.0 --push .

# 개념: 쿠키 검증 통과 시에만, 서버가 Authorization 헤더를 주입해 프록시
proxy.on("proxyReq", (proxyReq) => {
  const cred = Buffer.from("user:secret").toString("base64");
  proxyReq.setHeader("Authorization", "Basic " + cred);
});

9관련 기술 심화 학습 로드맵

1주차: Docker 기초 5종

이미지 / 컨테이너 / 볼륨 / 네트워크 / docker.sock의 관계 이해. docker compose로 서비스 정의, 명명 볼륨과 바인드 마운트의 차이, 컨테이너 간 이름 기반 통신(내부 네트워크) 실습.

2주차: 프로그래밍으로 컨테이너 조종

dockerode(Node) 또는 docker-py(Python)로 컨테이너를 생성/시작/삭제. docker.sock의 권한 위험과 대안(소켓 프록시, rootless Docker) 이해. WOC의 "동적 실례 생성" 흐름 따라 만들기.

3주차: 원격 데스크탑 스트리밍

Xvfb 가상 디스플레이, X11과 창 관리자(openbox), VNC의 역사(VNC → noVNC → KasmVNC). 헤드리스 서버에서 GUI 앱을 띄워 브라우저로 보는 파이프라인 구축. 코덱·지연·IME 이슈 파악.

4주차: 인증 게이트웨이 + 리버스 프록시 + RBAC

Fastify(또는 Express)로 쿠키 세션 인증, 리버스 프록시로 백엔드 자격증명 숨기기, 역할 기반 접근 제어(관리자/자식계정)와 리소스별 권한 매트릭스 설계.

5주차: 멀티아치 빌드 · CI/CD · 보안 하드닝

buildx + QEMU 멀티아치, GitHub Actions로 태그 기반 릴리스, GHCR 배포와 공개 설정. 그리고 공인망 비노출·TLS·기본 비번 변경·감사 로그 등 셀프호스팅 보안 체크리스트 정립.

10핵심 키워드 사전

11참고 링크

• GitHub — Gloridust/WechatOnCloud
• 技术方案.md — 전체 설계 문서
• linuxserver KasmVNC 베이스 이미지 문서
• KasmVNC (원격 데스크탑 엔진)
• noVNC (웹 VNC 고전)
• dockerode (Node Docker 제어)
• Docker 멀티플랫폼 빌드(buildx) 공식 문서
• Fastify 공식 사이트
• GitHub Actions — Docker 이미지 배포
• PWA 학습 가이드 (web.dev)