Remote Desktop

Host PC를 웹 브라우저에서 원격 제어. WebSocket 기반 실시간 화면 스트리밍과 마우스/키보드 입력.

소개

Host PC(Windows)를 고정 위치에 두고, 웹 브라우저에서 원격으로 화면을 보고 제어할 수 있습니다. Host PC를 항상 켜둔 상태로 유지하여 VDI 연결과 CodeSync가 끊기지 않도록 합니다.

설치 불필요: 클라이언트는 브라우저만 있으면 됩니다. Chrome, Safari, Edge 모두 지원.

서비스 구조

Direct 모드 (같은 네트워크)

💻
Client
웹 브라우저
◀ WebSocket ▶
🖥
Host PC
:8290

Relay 모드 (다른 네트워크)

💻
Client
웹 브라우저
◀ WS ▶
☁
AKS Relay
FastAPI
◀ WS ▶
🖥
Host PC
outbound

구성 요소

구성 요소역할기술
Server화면 캡처 + 입력 주입 + WebSocketPython, mss (DXGI), ctypes SendInput
Client화면 표시 + 입력 전송HTML5 Canvas, WebSocket
Relay외부 네트워크 중계 (선택)FastAPI WebSocket

다운로드

🖥
Windows EXE
Windows 10/11 (ARM64 / x64)
PyInstaller 단일 실행 파일. Python 설치 불필요.
Download remote-desktop.exe
📄
설정 템플릿
remote-desktop.yaml
YAML 설정 파일 예시. 비밀번호와 포트를 수정하세요.
Download YAML

EXE 설치 (권장)

파일 다운로드
remote-desktop.exe와 remote-desktop.yaml.example을 다운로드합니다.
폴더 배치
Host PC에 폴더를 만들고 파일을 복사합니다.
mkdir C:\remote-desktop copy remote-desktop.exe C:\remote-desktop\ copy remote-desktop.yaml.example C:\remote-desktop\remote-desktop.yaml
설정 수정
remote-desktop.yaml의 password를 반드시 변경합니다.
notepad C:\remote-desktop\remote-desktop.yaml
서버 실행
명령 프롬프트에서 실행합니다.
C:\remote-desktop\remote-desktop.exe serve -c C:\remote-desktop\remote-desktop.yaml
브라우저 접속
웹 브라우저에서 http://<Host-PC-IP>:8290 으로 접속합니다.

설정

host: "0.0.0.0" # 바인드 주소 port: 8290 # 포트 번호 password: "Rdt@2026!Sec" # 접속 비밀번호 (반드시 변경!) fps: 10 # 초당 프레임 (5~15 권장) quality: 50 # JPEG 품질 (1~95, 낮을수록 빠름) scale: 1.0 # 화면 축소 (0.5 = 절반) monitor: 0 # 모니터 (0=전체) capture_backend: "auto" # 캡처 백엔드 (auto/mss/bitblt/printwindow/camera) camera_device: 0 # HDMI 캡처카드 장치 인덱스 (camera 시) relay_url: "" # Relay 서버 URL (외부용) relay_room: "" # 방 ID

성능 프리셋

프리셋fpsqualityscale대역폭용도
기본10501.0~1.3 MB/s일반 사용
저대역폭5300.75~250 KB/s느린 네트워크
고화질15701.0~3.7 MB/s상세 작업

방화벽 설정

Direct 모드에서는 Host PC의 포트를 열어야 합니다:

netsh advfirewall firewall add rule name="RemoteDesktop8290" dir=in action=allow protocol=TCP localport=8290
Relay 모드를 사용하면 인바운드 포트 오픈이 필요 없습니다. Host PC에서 AKS Relay로 outbound 연결만 합니다.

접속 방법

Direct 모드 (같은 네트워크)

Client와 Host PC가 같은 네트워크에 있을 때 직접 연결합니다.

Host PC에서 서버 실행
EXE 또는 Python으로 서버를 시작합니다.
웹 브라우저에서 접속
Chrome/Safari에서 http://<Host-PC-IP>:8290 으로 접속합니다.
비밀번호 입력
설정된 비밀번호를 입력하면 원격 화면이 표시됩니다.

Relay 모드 (다른 네트워크 / 방화벽 환경)

외부 네트워크에서 AKS Relay 서버를 경유하여 접속합니다. Host PC에서 인바운드 포트를 열 필요가 없습니다.

Host PC 설정 (remote-desktop.yaml)
Relay 서버 주소와 방 ID를 설정합니다.
relay_url: "wss://codesync.4.230.72.248.nip.io/ws/relay"
relay_room: "my-room"
Host PC에서 서버 실행
EXE 실행 시 자동으로 Relay에 outbound 연결합니다. 로그에 Relay 연결됨이 표시되면 성공입니다.
웹 브라우저에서 Relay 접속
아래 URL로 접속합니다 (room 파라미터는 Host PC의 relay_room과 동일):
https://codesync.4.230.72.248.nip.io/remote?room=my-room
비밀번호 입력 후 원격 화면이 표시됩니다.
Relay 모드에서는 Host PC가 먼저 실행되어 Relay에 연결된 상태여야 합니다. 브라우저에서 먼저 접속하면 "Host PC 연결 대기 중..." 메시지가 표시됩니다.

조작법

동작조작설명
마우스 이동화면 위 이동원격 PC 마우스 커서 이동
클릭좌/우/중 클릭원격 PC에 전달
스크롤휠 스크롤원격 PC에 전달
키 입력키보드 타이핑모든 키가 원격 PC로 전달
전체화면Fullscreen 버튼브라우저 전체화면 토글
1:1 모드Fit 버튼화면 맞춤 / 원본 크기 토글
F5(새로고침), F11(전체화면), F12(개발자도구)는 브라우저가 처리합니다. 나머지 모든 키는 원격 PC로 전달됩니다.

실시간 설정

하단 컨트롤 바에서 서버 설정을 실시간으로 변경할 수 있습니다:

항목범위설명
FPS5 / 10 / 15 / 20 / 30초당 프레임 (높을수록 부드럽지만 대역폭 증가)
Quality10 ~ 95JPEG 압축 품질 (낮을수록 작고 빠름)
Scale50% / 75% / 100%화면 축소 (대역폭 절약)

자동 시작 등록

Windows 작업 스케줄러로 로그인 시 자동 시작할 수 있습니다:

scripts\install_task.bat
# 관리 명령 schtasks /Query /TN RemoteDesktop # 상태 확인 schtasks /Run /TN RemoteDesktop # 즉시 실행 schtasks /Delete /TN RemoteDesktop /F # 제거

Relay 모드

다른 네트워크(외부)에서 접속할 때 AKS Relay 서버를 경유합니다. Host PC에서 outbound WebSocket만 사용하므로 인바운드 포트를 열 필요가 없습니다.

Host PC 설정

# remote-desktop.yaml relay_url: "wss://codesync.4.230.72.248.nip.io/ws/relay" relay_room: "my-room" # 방 ID (브라우저 접속 시 동일하게 사용) relay_token: "" # 토큰 인증 (선택, 설정 시 브라우저에서도 동일 토큰 필요)

브라우저 접속 URL

# 기본 접속 https://codesync.4.230.72.248.nip.io/remote?room=my-room # 토큰 인증 사용 시 https://codesync.4.230.72.248.nip.io/remote?room=my-room&token=your-token

동작 원리

웹 브라우저 ──wss──▶ AKS Relay ◀──wss── Host PC (EXE) (Client) (중계 서버) (Host, outbound) 1. Host PC가 EXE 실행 → Relay에 자동 연결 (outbound) 2. 브라우저에서 같은 room으로 접속 3. Relay가 양방향 중계 (화면 스트리밍 + 입력 전달)

자동 재접속

Host PC의 Relay 연결이 끊기면 5초부터 최대 30초까지 지수 백오프로 자동 재접속합니다. 네트워크 일시 장애 시에도 수동 개입 없이 복구됩니다.

보안

보안 위협대응 방법
방화벽 (인바운드 차단)Relay 모드로 outbound만 사용
AV/EDR (EXE 차단)Python 직접 실행 fallback
DLP (화면 공유 감지)JPEG 스트리밍은 일반 HTTP 트래픽
입력 차단 (키로거 방지)SendInput은 Windows 표준 API
무단 접속비밀번호 인증 필수
비밀번호는 반드시 기본값에서 변경하세요. 공용 네트워크에서는 Relay + TLS(wss://)를 사용하세요.

트러블슈팅

증상원인해결
포트 접근 불가Windows 방화벽netsh 명령으로 포트 열기
화면이 검정서비스 세션에서 실행사용자 세션에서 실행 (schtasks)
입력 안 됨보안 SW 차단View-only 모드로 사용
연결 끊김네트워크 불안정자동 재접속 (3초 간격)
느린 화면높은 FPS/Quality하단 바에서 FPS 5, Quality 30
VDI 창이 흰색보안 SW(DLP) 화면 캡처 차단remote-desktop.exe diagnose로 진단. capture_backend: "printwindow" 시도. 근본 해결: IT 보안팀 화이트리스트 또는 HDMI 캡처카드
camera 프레임 없음HDMI 캡처카드 미인식 또는 장치 인덱스 오류diagnose로 카메라 장치 목록 확인. camera_device 인덱스 변경. opencv-python 설치 확인