9. 문제 해결
화면에 나온 문구와 같은 항목을 찾으세요. 한 번 조치한 뒤 상태를 다시 확인하세요.
어디까지 됐는지부터 확인하세요
위에서부터 읽고, 처음 막힌 줄의 안내를 따르세요. 오류 문구가 있으면 아래의 같은 문구를 찾아보세요.
| 어디에서 막혔나요? | 먼저 할 일 |
|---|---|
| 서버를 처음 설치하는데 관리자 화면이 안 열림 | 2장에서 서버 IP·실행 상태·접속 포트를 확인하세요. |
| 앱의 연결 테스트 실패 | 서버 주소와 로그인에서 주소·인증서를 확인하세요. |
| 서버 연결은 되지만 로그인 실패 | 관리자가 만든 ToTBVDI 계정인지 확인하세요. Windows·Proxmox 비밀번호와 구분하세요. |
| 로그인했지만 내 데스크톱이 비어 있음 | 관리자에게 VM 배정과 변경 적용 확인을 요청하세요. |
| VM 카드에 Host 오프라인·화면 준비 오류 | Host와 가상 화면을 확인하세요. |
| 연결 창이 열렸지만 검은 화면 | 스트리밍 검은 화면을 확인하세요. |
| 화면은 나오는데 파일 복사·USB만 안 됨 | 툴바의 사용안내에서 허용 권한을 확인하세요. |
| 콘솔만 열리지 않거나 검은 화면 | 긴급 콘솔 문제를 확인하세요. |
주소 설정을 바꾼 뒤에는 앱에서 연결 테스트 → 저장을 다시 진행하세요.
서버 주소와 로그인
| 보이는 문구 | 먼저 할 일 |
|---|---|
| 서버 주소를 찾지 못했어요. | 서버 주소의 철자를 확인하세요. |
| HTTPS 보안 연결에 실패했어요. | 관리자에게 서버 주소와 인증서 확인을 요청하세요. |
| 서버 응답 시간이 초과됐어요. | 관리자에게 서버 실행 상태와 접속 포트 확인을 요청하세요. |
| ToTBVDI 로그인 서버 응답이 아니에요. | 관리자에게 클라이언트용 서버 주소를 받으세요. |
이 주소는 서버의 허용 주소에 등록되지 않았어요. (origin_not_allowed) |
관리자에게 주소의 HTTP·HTTPS 구분과 포트까지 확인해 달라고 요청하세요. |
| 서버에서 HTTP 접속이 꺼져 있어요. | 관리자에게 HTTP 허용 여부를 확인하세요. |
| 이 HTTP 주소는 서버 초기 설정에만 사용할 수 있어요. | 관리자에게 서버 접속 설정 완료를 요청하세요. |
| 현재 주소와 서버의 접속 설정이 맞지 않아요. | 관리자에게 허용 주소와 포트 확인을 요청하세요. |
관리자가 확인할 때
- 관리자 웹의 설정 → 서버 접속 설정을 여세요.
- 사용자가 입력한 주소를 허용 주소와 비교하세요.
- Docker 설치라면 화면이 안내한
.env줄을 적용하세요. - Compose 폴더에서
docker compose up -d를 실행하세요. - 클라이언트에서 연결 테스트를 다시 하세요.
HTTPS 프록시를 쓰는데 403 http_disabled가 나오면 신뢰할 프록시 설정이 빠졌을 수 있습니다.
실제 프록시의 주소와 TOTBVDI_TRUSTED_PROXIES를 Docker 배포 안내에 따라 확인하세요.
인증서 오류를 무시해서 연결하지 마세요. 같은 내부망에서 HTTP로 운영하려면 보안 안내를 먼저 확인하세요.
Host가 오프라인이거나 화면이 준비되지 않음
| 표시 | 사용자 | 관리자 또는 해당 Windows를 관리하는 사람 |
|---|---|---|
| Host 오프라인 | 전원 상태를 확인하세요. | Host 설정에서 서버 연결과 서비스 상태를 확인하세요. |
| 관리자 승인 대기 | 관리자에게 승인 확인을 요청하세요. | 두 화면의 확인 코드를 비교한 뒤 Host 연결 요청을 승인하세요. |
| 가상 화면이 준비되지 않았어요. | 관리자에게 Host 점검을 요청하세요. | Host 설정의 가상 화면에서 상태와 필요한 조치를 확인하세요. |
| 화면 구성 중 | 구성이 끝난 뒤 다시 연결하세요. | 오래 멈추면 Host 설정의 진단을 확인하세요. |
| Windows 계정 확인 | 관리자에게 Windows 계정 확인을 요청하세요. | Host 설정의 Windows 로그인에서 저장한 계정을 확인하세요. |
| 로그인 필요 또는 잠금 해제 | Windows 로그인 화면이 보이면 해당 Windows 계정으로 로그인하세요. | 로그인 화면이 보이지 않으면 Host의 Windows 로그인 상태와 긴급 콘솔을 확인하세요. |
| 재시작 필요 | 열려 있는 작업을 저장하세요. | 표시된 원인을 확인한 뒤 해당 Windows를 다시 시작하세요. |
| 이전 연결의 종료와 화면 복원을 확인하고 있어요. | 잠시 후 다시 연결하세요. | 반복되면 Host의 진단에서 화면 복구 상태를 확인하세요. |
Host 설정에 서비스 시작이 보이고 서비스가 중지돼 있다면 그 버튼으로 시작하세요. 상태가 바뀐 뒤 클라이언트의 새로고침을 누르세요.
스트리밍 화면이 검게 보임
- 원격 창에 오류나 로그인 화면이 있는지 확인하세요.
- 오류가 있으면 그 문구에 해당하는 조치를 하세요.
- 검은 화면이 계속되면 연결을 닫고 새로고침을 누르세요.
- 다시 연결해도 같으면 관리자에게 Host의 가상 화면과 진단 확인을 요청하세요.
서비스가 실행 중이라는 표시만으로 화면 전송까지 준비됐다고 볼 수는 없습니다. 화면에 원인이 표시되지 않으면 드라이버를 임의로 지우지 말고 진단을 확인하세요.
긴급 콘솔이 열리지 않거나 검게 보임
콘솔은 Proxmox VM의 기본 화면인 QEMU 화면을 보여 줍니다. GPU 패스스루 화면은 콘솔에 나오지 않을 수 있습니다. 로컬 PC에는 Proxmox 긴급 콘솔이 없습니다.
| 콘솔에 보이는 문구 | 할 일 |
|---|---|
| 다른 원격 연결이 사용 중이에요 | 사용 중인 스트리밍을 종료한 뒤 콘솔을 다시 여세요. |
| 이전 연결을 정리하고 있어요 | 잠시 후 다시 연결하세요. |
| 원래 VM 화면이 꺼져 있어요 | 관리자에게 화면 복구 결과 확인을 요청하세요. |
| 원래 화면의 복구 정보가 없어요 | 관리자에게 VM 화면 상태 확인을 요청하세요. |
| VM 화면 구성이 바뀌었어요 | 관리자에게 VM 디스플레이 설정 확인을 요청하세요. |
| VM 콘솔이 꺼져 있어요 | 관리자에게 QEMU 콘솔 설정 확인을 요청하세요. |
| 콘솔에 연결할 권한이 없어요 | 관리자에게 VM 배정과 Proxmox 콘솔 권한 확인을 요청하세요. |
| 콘솔 인증이 끝났어요 | 창을 닫고 앱의 카드에서 콘솔을 다시 여세요. |
| 화면이 아직 안 보여요. 계속 검은 화면이면 다시 연결하세요. | 콘솔을 다시 연결하세요. |
콘솔 연결됨은 Windows 로그인이나 정상 화면 표시를 보장하지 않습니다. 재연결 후에도 검은 화면이면 관리자에게 QEMU 화면과 GPU 구성을 확인해 달라고 요청하세요.
소리가 들리지 않음
- 원격 도구 모음의 설정에서 오디오를 확인하세요.
- 내 PC나 휴대폰의 음량을 확인하세요.
- VM 카드에 소리 없음이 있으면 그 배지를 누르세요.
- 사운드카드가 이미 있다면 VM 안의 Windows 소리 출력을 확인하세요.
실행 중인 VM에 사운드카드를 추가할 때는 추가하고 다시 시작으로 적용할 수 있습니다. 저장하지 않은 작업이 사라질 수 있으니 확인 전에 저장하세요. 추가만 하기를 선택하면 나중에 Proxmox 전원 작업으로 적용해야 합니다.
다시 시작 필요 배지가 남으면 배지를 눌러 안내를 확인하세요.
Windows 안의 다시 시작만으로는 새 Proxmox 사운드카드가 적용되지 않습니다.
전원 권한이나 Proxmox의 VM.Config.HWType 권한 오류는 관리자에게 문의하세요.
로컬 PC의 소리 장치는 해당 PC의 Windows에서 확인하세요. Proxmox 사운드카드 추가는 VM에서만 사용할 수 있습니다.
마우스 잠금과 게임 입력
| 증상 | 할 일 |
|---|---|
| 마우스가 원격 화면에 잠김 | Windows에서 Ctrl+Alt+Shift+Z를 누르세요. |
| 새 연결에서 잠금이 풀려 있음 | 필요한 연결마다 도구 모음의 마우스 잠금을 켜세요. |
| 게임에서 마우스가 움직이지 않음 | 관리자에게 해당 사용자·VM의 USB 공유 권한 확인을 요청하세요. |
| Host의 USB 상태: 다른 프로그램이 USB 연결 기능을 쓰고 있어요. | Host 설정의 장치 → ToTBVDI용으로 바꾸기 안내를 확인하세요. |
| 커서 위치가 어긋남 | 서버·Host·클라이언트를 최신 버전으로 업데이트하세요. |
컨트롤러를 바꾸면 다른 프로그램의 USB 연결에 영향을 줄 수 있습니다. 변경 확인 창의 안내를 읽고 진행하세요.
USB 공유 권한과 Host의 USB 연결 기능이 준비돼야 가상 USB 마우스를 사용할 수 있습니다. 마우스 잠금을 켜는 것만으로 모든 게임의 호환성을 보장하지는 않습니다.
한/영 전환이나 한글 입력
- 원격 화면을 눌러 키보드 입력을 보낼 곳을 선택하세요.
- Windows 클라이언트에서는 실제 키보드의 한/영 키를 누르세요.
- Android에서는 키보드 위 키 줄의 한/영을 누르세요.
- 계속 영문만 나오면 원격 Windows의 한국어 입력기를 확인하세요.
긴급 콘솔의 한글 조합과 클립보드에는 호환성 제한이 있습니다. 한/영 전환이 계속 안 되면 최신 버전으로 업데이트한 뒤 일반 업무는 스트리밍에서 진행하세요. 콘솔에서의 한글 입력을 모든 Windows·키보드 조합에 대해 보장하지 않습니다.
Defender·SmartScreen이 설치를 막음
- 경고 창에 나온 파일명과 탐지·차단 문구를 기록하세요.
- Windows 보안 → 보호 기록에서 해당 항목을 확인하세요.
- 관리자에게 파일의 버전과 가린 경고 내용을 전달하세요.
- 관리자가 배포 경로와 최신 파일을 확인할 때까지 설치를 멈추세요.
경고만으로 오탐이라고 판단하지 않습니다. Defender·SmartScreen을 끄거나 ToTBVDI 폴더 전체를 예외로 등록하지 마세요. 프로젝트 배포 서명과 Windows의 게시자 신뢰는 서로 다릅니다(보안 안내).
보호 기록 확인 방법은 Microsoft 공식 안내를 보세요.
문의할 때 보낼 내용
- 서버·Host·클라이언트 버전을 적으세요.
- 문제가 생긴 시각과 직전에 누른 버튼을 적으세요.
- 오류 문구를 그대로 적으세요.
- 화면이나 로그의 주소·사용자명·설정 코드·비밀번호·토큰을 가리세요.
마이크와 카메라 전달은 지원하지 않습니다. 보안 취약점으로 보이는 내용은 공개 이슈에 적지 말고 비공개 신고 안내를 따르세요.