DeskVNCServer - 가이드

시작하기

1. 비밀번호 설정

설정(하단 도구 모음의 톱니바퀴 아이콘)을 열고 VNC password를 입력하세요. 표준 VNC 클라이언트는 RFB DES 챌린지를 사용하며 ASCII 호환 첫 8바이트만 인식합니다 — 8자 이하의 비밀번호를 선택하세요.

2. 서버 시작

1. 메인 창에서 Start를 클릭합니다. 상태 표시기가 Running으로 바뀝니다.
2. 네 개의 리스너가 동시에 시작됩니다: VNC 5900, QREX control 5911, QREX media 4010, File API 8766.
3. Copy Info를 클릭하면 호스트, 포트, 현재 PIN이 포함된 한 줄 정보를 클립보드에 복사할 수 있습니다.

3. 클라이언트 연결

표준 VNC 뷰어(macOS Screen Sharing, RealVNC, TightVNC, 모바일 VNC 앱)의 경우:

1. 뷰어를 열고 주소로 vnc://<your-mac-ip>:5900을 입력합니다
2. 1단계에서 설정한 VNC password를 입력합니다
3. 곧바로 Mac을 제어할 수 있습니다 — RFB를 통한 키보드, 마우스, 복사/붙여넣기 지원

QuickRemote 앱의 경우:

1. 휴대전화나 태블릿에서 QuickRemote를 열고 Add Mac을 선택합니다
2. DeskVNCServer가 표시하는 6자리 페어링 PIN을 입력합니다(QuickRemote 빌드가 지원하는 경우 QR 코드를 스캔해도 됩니다)
3. QuickRemote가 반환된 Bearer 토큰을 저장하고 확장 기능 — IME, 오디오, 클립보드 동기화, 파일 전송 — 의 잠금이 해제됩니다

인터페이스 개요

상태 행

액션 버튼

• Start — 네 개의 리스너를 모두 시작합니다.
• Stop — 모든 리스너를 닫고 활성 세션을 끊습니다.
• Copy Info — 짧은 연결 요약(호스트, VNC 포트, 컨트롤 포트, PIN)을 클립보드에 복사하여 클라이언트와 손쉽게 공유할 수 있습니다.

연결 패널

바인드 호스트, 포트, 현재 Server ID, 활성 페어링 PIN을 표시합니다. 설정이 변경되면 자동으로 갱신됩니다.

QuickRemote API 패널

서버가 사용하는 프로토콜에 대한 빠른 참조입니다. 지원되는 RFB 버전, QREX 엔드포인트 형식, IME 명령 세트를 나열하여 QuickRemote(또는 자체 클라이언트)가 사용할 수 있는 기능을 파악할 수 있게 합니다.

프로토콜 및 포트

인증

• VNC 클라이언트 — RFB DES 비밀번호(설정된 비밀번호 중 ASCII 호환 첫 8바이트).
• QREX 클라이언트 — POST /qr/v1/pair에서 최초 6자리 PIN 교환을 통해 Bearer 토큰이 반환됩니다. 이후 모든 QREX HTTP 호출과 WebSocket 프레임에는 반드시 Authorization: Bearer <token>가 포함되어야 합니다.
• VNC password가 비어 있으면 서버는 표준 RFB no-auth 모드를 알립니다. 신뢰할 수 있는 LAN 세그먼트에서만 사용하세요.

QREX 엔드포인트 빠른 참조

GET  /qr/v1/capabilities    # public, returns supported features
POST /qr/v1/pair            # public, exchange PIN for Bearer token
GET  /qr/v1/ws              # WebSocket, auth required
POST /qr/v1/ime/get         # auth required, query active IME
POST /qr/v1/ime/list        # auth required, list available IMEs
POST /qr/v1/ime/set         # auth required, switch IME
POST /qr/v1/ime/toggle      # auth required, toggle IME on/off
POST /qr/v1/ime/commit      # auth required, commit a text string

설정

클라이언트 예시

macOS Screen Sharing

1. Finder → 이동 → 서버에 연결
2. vnc://<your-mac-ip>:5900 입력
3. VNC password 입력

cURL — 기능 조회

curl http://<your-mac-ip>:5911/qr/v1/capabilities

cURL — 페어링 후 IME bridge 호출

# 1. Exchange the PIN for a Bearer token
TOKEN=$(curl -s http://<your-mac-ip>:5911/qr/v1/pair \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456"}' | jq -r .token)

# 2. Commit text via the IME bridge
curl http://<your-mac-ip>:5911/qr/v1/ime/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from remote"}'

팁

• 느린 Wi-Fi 회선이나 VPN을 통한 연결을 사용할 때는 프레임 속도와 최대 프레임 크기를 낮추세요.
• 각 기기를 한 번씩만 페어링하세요. 초기 PIN 교환 이후 Bearer 토큰은 재부팅 후에도 유지되므로 QuickRemote가 조용히 다시 연결됩니다.
• 채팅이나 이메일로 연결 정보를 보낼 때 Copy Info를 활용하세요 — 클라이언트가 필요한 모든 내용이 포함됩니다.
• 업로드가 정말 필요하지 않다면 Enable file mutations는 꺼두세요. 스크린샷, 노트, 다운로드 탐색에는 읽기 전용 모드로 충분합니다.
• 사용하지 않을 때는 Audio API를 비활성화하세요. 유휴 코덱이라도 인코딩 경로에서 약간의 CPU를 소모합니다.

문제 해결

서버가 시작되지 않습니다

• 다른 VNC 서버(예: macOS Screen Sharing)가 이미 포트 5900을 사용 중일 수 있습니다. System Settings → General → Sharing에서 중지하거나 DeskVNCServer 설정에서 포트를 변경하세요.
• 포트 5911 / 4010 / 8766이 모두 비어 있어야 합니다. lsof -i :5911 등으로 확인하세요.

VNC 클라이언트 인증이 실패합니다

• 비밀번호가 ASCII 호환으로 8바이트 이하인지 확인하세요. 멀티바이트 문자나 더 긴 문자열은 RFB DES 인증에 의해 자동으로 잘립니다.
• 의도적으로 비밀번호를 사용하지 않으려면 필드를 비워두고 VNC no-auth를 지원하는 뷰어로 연결하세요.

QuickRemote가 페어링하지 못합니다

• 휴대전화나 태블릿이 Mac과 동일한 Wi-Fi에 연결되어 있는지 확인하세요.
• 연결 패널을 열어 PIN을 다시 확인하세요. PIN은 설정에서 재생성할 수 있습니다.
• macOS 방화벽 설정을 확인하세요 — QREX 포트로의 수신 연결이 허용되어야 합니다.

원격 조작이 느립니다

• 설정에서 프레임 속도와 최대 프레임 크기를 낮추세요.
• 사용하지 않는 기능(오디오, 클립보드, IME)을 비활성화하여 CPU를 확보하세요.

파일이 전송되지 않습니다

• Enable file transfer가 켜져 있는지 확인하세요. 읽기 전용 목록은 Enable file mutations 없이도 동작합니다.
• 업로드가 실패하면 Enable file mutations도 활성화하세요. 그렇지 않으면 File API는 읽기 요청에만 응답합니다.

개인 정보 보호

• 모든 세션은 클라이언트와 Mac 간 직접 실행됩니다. 클라우드 릴레이, 텔레메트리, 분석이 없습니다.
• VNC password, QREX Bearer 토큰, 페어링 PIN, Stable Server ID는 로컬 앱 설정에만 저장됩니다.
• 파일 변경 기능은 기본적으로 꺼져 있습니다. 명시적으로 쓰기 권한을 부여할 때까지 원격 클라이언트는 읽기만 가능합니다.
• 언제든지 확장 기능(오디오, 클립보드, 파일 전송, IME, 원격 입력)을 비활성화하여 해당 기능을 즉시 회수할 수 있습니다.
• 서버를 Mac 내부에만 두려면 바인드 호스트를 127.0.0.1로 설정하세요.