DeskVNCServer - 가이드

시작하기

1. 비밀번호 설정하기

설정(하단 도구 모음의 톱니바퀴 아이콘)을 열고 다음 항목을 입력합니다: VNC 비밀번호. 표준 VNC 클라이언트는 RFB DES 챌린지를 사용하는데, 여기서는 ASCII 호환 바이트 8개까지만 인식합니다. 따라서 비밀번호는 8자 이하로 정하세요.

2. 서버 시작하기

1. 메인 창에서 시작을 클릭합니다. 상태 표시가 다음으로 바뀝니다: 실행 중.
2. 네 개의 리스너가 한 번에 켜집니다. VNC 5900, QREX 제어 5911, QREX 미디어 4010, 그리고 파일 API 8766.
3. 클릭 정보 복사 를 누르면 호스트, 포트, 현재 PIN이 담긴 한 줄 정보가 클립보드에 복사됩니다.

3. 클라이언트 연결하기

표준 VNC 뷰어(macOS 화면 공유, RealVNC, TightVNC, 모바일 VNC 앱)를 사용하는 경우:

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

QuickRemote 앱을 사용하는 경우:

1. 휴대폰이나 태블릿에서 QuickRemote를 열고 다음을 선택합니다: Mac 추가
2. DeskVNCServer에 표시된 6자리 페어링 PIN을 입력합니다(QuickRemote 빌드가 지원한다면 QR 코드를 스캔해도 됩니다)
3. QuickRemote가 발급받은 Bearer 토큰을 저장하고 확장 기능을 사용할 수 있게 합니다 — IME, 오디오, 클립보드 동기화, 파일 전송

인터페이스 개요

상태 행

동작 버튼

• 시작 — 네 개의 리스너를 모두 켭니다.
• 중지 — 모든 리스너를 닫고 활성 세션의 연결을 끊습니다.
• 정보 복사 — 호스트, VNC 포트, 제어 포트, PIN이 담긴 짧은 연결 요약을 클립보드에 복사해 클라이언트 쪽에 쉽게 전달할 수 있게 합니다.

연결 패널

바인드 호스트, 포트, 현재 서버 ID, 활성 페어링 PIN을 표시합니다. 설정이 바뀌면 내용이 자동으로 갱신됩니다.

QuickRemote API 패널

서버가 지원하는 프로토콜을 한눈에 보여 줍니다. 지원하는 RFB 버전, QREX 엔드포인트 형태, IME 명령 집합을 나열하므로 QuickRemote(또는 직접 만든 클라이언트)가 무엇을 쓸 수 있는지 알 수 있습니다.

프로토콜과 포트

인증

• VNC 클라이언트 — RFB DES 비밀번호(설정한 비밀번호의 처음 8개 ASCII 호환 바이트).
• QREX 클라이언트 — 처음에 POST /qr/v1/pair 에서 6자리 PIN을 교환하면 Bearer 토큰이 반환됩니다. 이후의 모든 QREX HTTP 호출과 WebSocket 프레임에는 다음이 포함되어야 합니다: Authorization: Bearer <token>.
• VNC 비밀번호가 비어 있으면 서버는 표준 RFB 무인증 모드를 알립니다. 신뢰할 수 있는 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 화면 공유

1. Finder → 이동 → 서버에 연결
2. 입력할 내용 vnc://<your-mac-ip>:5900
3. VNC 비밀번호를 입력합니다

cURL — 지원 기능 확인

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

cURL — 페어링 후 IME 브리지 호출

# 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가 조용히 다시 연결됩니다.
• 다음을 사용하면 정보 복사 채팅이나 이메일로 연결 정보를 빠르게 전달할 수 있습니다. 클라이언트에 필요한 모든 내용이 담겨 있습니다.
• 업로드가 꼭 필요한 경우가 아니라면 파일 변경 사용 은 꺼 두세요. 스크린샷, 메모, 다운로드 파일을 훑어보는 데는 읽기 전용으로도 충분합니다.
• 사용하지 않을 때는 오디오 API를 끄세요. 유휴 상태의 코덱도 인코딩 경로에서 CPU를 조금씩 사용합니다.

문제 해결

서버가 시작되지 않습니다

• 다른 VNC 서버(예: macOS 화면 공유)가 이미 5900 포트를 쓰고 있을 수 있습니다. 시스템 설정 → 일반 → 공유에서 끄거나, DeskVNCServer 설정에서 포트를 바꾸세요.
• 5911 / 4010 / 8766 포트가 모두 비어 있어야 합니다. lsof -i :5911 등의 명령으로 확인하세요.

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

• 비밀번호가 ASCII 호환 바이트 8개 이하인지 확인하세요. 멀티바이트 문자나 더 긴 문자열은 RFB DES 인증에서 조용히 잘려 나갑니다.
• 의도적으로 비밀번호를 쓰지 않으려면 필드를 비워 두고, VNC 무인증을 지원하는 뷰어로 연결하세요.

QuickRemote가 페어링되지 않습니다

• 휴대폰이나 태블릿이 Mac과 같은 Wi-Fi에 있는지 확인하세요.
• 연결 패널을 열어 PIN을 다시 확인하세요. PIN은 설정에서 새로 만들 수 있습니다.
• macOS 방화벽 설정을 확인하세요. QREX 포트로 들어오는 연결이 허용되어야 합니다.

원격 제어가 느리게 느껴집니다

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

파일이 전송되지 않습니다

• 다음이 켜져 있는지 확인하세요: 파일 전송 사용 읽기 전용 목록 조회에는 다음이 필요하지 않습니다: 파일 변경 사용.
• 업로드가 실패한다면 다음도 함께 켜세요: 파일 변경 사용. 그렇지 않으면 파일 API는 읽기 요청에만 응답합니다.

개인정보 보호

• 모든 세션은 클라이언트와 Mac 사이에서 직접 이루어집니다. 클라우드 릴레이도, 텔레메트리도, 분석도 없습니다.
• VNC 비밀번호, QREX Bearer 토큰, 페어링 PIN, 고정 서버 ID는 로컬 앱 설정에만 저장됩니다.
• 파일 변경은 기본적으로 꺼져 있습니다. 쓰기 권한을 직접 허용하기 전까지 원격 클라이언트는 읽기만 할 수 있습니다.
• 오디오, 클립보드, 파일 전송, IME, 원격 입력 등 어떤 확장 기능이든 언제든지 꺼서 그 권한을 즉시 회수할 수 있습니다.
• 서버를 Mac 안에서만 쓰고 싶다면 바인드 호스트를 다음으로 설정하세요: 127.0.0.1.