로컬에서는 잘 되는데 원격 서버에 붙는 순간 막히는 경우가 많습니다. VSCode Remote SSH는 편리하지만, SSH 키 위치부터 권한 설정, host 별칭, known_hosts 충돌, 확장 설치 실패까지 막히는 지점이 생각보다 다양합니다.
특히 처음 연결할 때는 어느 단계에서 끊겼는지 구분하는 것이 중요합니다. 연결 대상 서버 정보가 잘못된 것인지, 키가 인식되지 않는 것인지, 서버 측 권한 문제인지 순서를 나눠 확인하면 대부분 빠르게 해결됩니다.
VSCode Remote SSH가 자주 막히는 이유
Remote SSH는 단순히 “서버에 접속”하는 기능이 아니라, 로컬 VSCode가 SSH로 원격 호스트에 들어간 뒤 그 안에 필요한 구성 요소를 설치하고, 확장 기능과 작업 디렉터리를 연결하는 구조입니다. 그래서 터미널에서 SSH 한 번 성공했다고 끝나는 것이 아니라, VSCode가 추가 단계까지 정상 처리해야 완전히 연결됩니다.
가장 흔한 원인은 크게 네 가지입니다. 첫째, SSH 설정 파일의 Host 이름, User, Port, IdentityFile이 맞지 않는 경우입니다. 둘째, 개인 키 파일 권한이나 서버의 authorized_keys 권한이 잘못된 경우입니다. 셋째, 서버 지문이 바뀌었는데 known_hosts에 예전 기록이 남아 충돌하는 경우입니다. 넷째, 원격 서버의 쉘 설정이나 디스크 용량 문제로 VSCode Server 설치가 실패하는 경우입니다.
연결 전에 먼저 확인할 기본 체크 5가지
- 서버 IP 또는 도메인, 포트 번호가 정확한지 확인
- 접속 계정명이 root인지 ubuntu인지 ec2-user인지 확인
- 사용할 SSH 키 파일 경로가 실제 파일과 일치하는지 확인
- 터미널에서 먼저 ssh 명령으로 접속 가능한지 확인
- 서버의 디스크 용량과 홈 디렉터리 쓰기 권한이 정상인지 확인
터미널에서 기본 접속이 안 되면 VSCode에서도 거의 동일하게 실패합니다. 따라서 문제를 빠르게 좁히려면 먼저 터미널에서 SSH가 되는지 확인한 뒤, 그 다음 VSCode Remote SSH 단계로 넘어가는 편이 효율적입니다.
가장 많이 막히는 오류 Top 10과 해결 방법
1. Permission denied (publickey)
가장 자주 보이는 오류입니다. 서버가 공개키 인증을 요구하는데, 로컬에서 보낸 키가 맞지 않거나 아예 전달되지 않을 때 발생합니다. 보통 잘못된 키 파일을 쓰고 있거나, config에서 IdentityFile 경로가 틀렸거나, 서버의 authorized_keys에 공개키가 빠진 경우가 많습니다.
우선 SSH config에서 해당 호스트에 맞는 사용자 계정과 키 파일을 정확히 적어야 합니다. 그다음 서버의 ~/.ssh/authorized_keys 안에 공개키가 들어 있는지 확인합니다. 키를 여러 개 쓰는 환경이라면 다른 키가 먼저 시도되어 실패하는 경우도 있으니, Host 단위로 전용 키를 지정하는 편이 안전합니다.
2. WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
known_hosts에 저장된 서버 지문과 현재 서버 지문이 다를 때 발생합니다. 서버를 재설치했거나, 동일한 IP에 다른 인스턴스가 올라왔거나, 호스트키가 갱신된 경우에 흔합니다.
이때는 무작정 접속을 반복하기보다, 정말 같은 서버가 맞는지 먼저 확인해야 합니다. 서버 변경이 확실하다면 로컬의 ~/.ssh/known_hosts에서 해당 호스트 기록을 지운 뒤 다시 접속하면 됩니다. IP와 도메인을 함께 쓰는 경우 둘 다 예전 기록이 남아 있는지 확인하는 것이 좋습니다.
3. Could not establish connection to “호스트명”
이 메시지는 원인이 하나가 아니라, 내부적으로 여러 문제를 묶어서 보여주는 경우가 많습니다. SSH config 문법 오류, 포트 오입력, DNS 문제, 방화벽 차단, 서버 종료 상태, 사용자명 불일치까지 모두 후보가 됩니다.
가장 빠른 방법은 VSCode 출력 패널에서 Remote - SSH 로그를 확인하는 것입니다. 단순 연결 실패처럼 보여도 실제 로그에는 어느 단계에서 끊겼는지 남습니다. 로그에서 port timeout인지, auth fail인지, server install fail인지 먼저 구분해야 헛수고를 줄일 수 있습니다.
4. SSH 키 권한이 너무 열려 있을 때
맥이나 리눅스에서는 개인 키 파일 권한이 넓게 열려 있으면 SSH가 보안상 해당 키를 무시할 수 있습니다. 파일 소유자 외 다른 사용자도 읽을 수 있는 상태라면 정상 키라도 인증에 실패할 수 있습니다.
개인 키는 본인만 읽을 수 있도록 제한하는 것이 안전합니다. 키 파일이 외장 드라이브나 동기화 폴더에 있어 권한이 꼬이는 경우도 있으니, 가능하면 홈 디렉터리 아래 ~/.ssh에 두고 쓰는 편이 안정적입니다.
5. SSH config 설정이 맞지 않을 때
Remote SSH는 매번 긴 명령어를 직접 입력하기보다 config에 Host 별칭을 등록해 쓰는 경우가 많습니다. 그런데 Host, HostName, User, Port, IdentityFile 중 하나만 잘못 적혀도 엉뚱한 서버로 연결되거나 인증이 실패합니다.
같은 서버를 여러 이름으로 등록하면 known_hosts나 키 선택이 꼬일 수 있습니다. 서버 하나당 별칭 하나를 기준으로 관리하고, 키가 다르면 Host 단위로 분리하는 방식이 관리하기 편합니다. 파일 편집 후에는 공백이나 들여쓰기, 중복 선언도 한 번 점검하는 것이 좋습니다.
6. 서버의 authorized_keys 또는 .ssh 폴더 권한 문제
로컬 키가 완벽해도 서버 쪽 권한이 틀리면 인증이 거부됩니다. 특히 ~/.ssh 폴더, authorized_keys 파일 권한이 지나치게 넓거나 소유자가 다르면 공개키가 무시되는 경우가 있습니다.
서버를 여러 사람이 관리하거나, 자동 배포 스크립트가 SSH 파일을 덮어쓴 뒤부터 문제가 생기는 경우가 많습니다. 접속이 되던 서버가 갑자기 publickey 오류를 내기 시작했다면 서버 쪽 권한 변화부터 의심하는 것이 좋습니다.
7. VSCode Server 설치 실패
SSH 로그인 자체는 되는데 VSCode 화면이 끝까지 열리지 않는다면 원격 서버 안에 필요한 구성요소 설치가 실패했을 가능성이 큽니다. 홈 디렉터리 용량 부족, 쓰기 권한 문제, 이전 설치 찌꺼기, 셸 초기화 파일 오류가 대표적입니다.
특히 .bashrc, .zshrc에 과도한 출력문이 있으면 설치 스크립트가 예상과 다른 응답을 받아 멈출 수 있습니다. 로그인할 때 배너 문구, echo 출력, 대화형 전용 설정이 강하게 걸려 있는 서버는 Remote SSH와 충돌하기 쉬우니 깔끔하게 정리하는 편이 좋습니다.
8. Proxy, VPN, 사내망 때문에 연결이 끊기는 경우
회사 네트워크나 학교 네트워크에서는 특정 포트가 막혀 있거나, VPN 접속 전후로 라우팅이 달라져 SSH가 갑자기 안 되는 경우가 있습니다. 집에서는 되는데 회사에서만 안 된다면 서버 자체보다 네트워크 경로를 먼저 점검해야 합니다.
이때는 포트 22 대신 별도 포트를 쓰는지, 방화벽에서 IP 허용이 필요한지, VPN 연결 순서가 맞는지 확인합니다. 클라우드 서버라면 보안 그룹이나 인바운드 규칙에서 현재 접속 중인 네트워크를 허용했는지도 함께 확인해야 합니다.
9. 원격 서버의 기본 셸 설정이 꼬인 경우
기본 셸이 존재하지 않거나, 로그인 시 특정 명령을 강제로 실행하도록 설정되어 있으면 Remote SSH 초기화 과정이 실패할 수 있습니다. 예를 들어 zsh 설정 파일에서 존재하지 않는 플러그인을 불러오거나, 특정 TTY 환경만 가정한 코드가 있으면 문제가 생깁니다.
원격 개발 서버는 화려한 셸 꾸미기보다 안정성이 더 중요합니다. 프롬프트 테마나 자동 실행 스크립트가 많을수록 접속 문제 원인을 찾기 어려워지므로, 개발 서버 계정은 비교적 단순한 셸 설정을 유지하는 편이 좋습니다.
10. 확장은 연결됐는데 폴더 열기나 Git 작업이 안 되는 경우
연결 자체는 성공했지만 작업 폴더 권한이 없거나, 서버 안에 Git이 없거나, 프로젝트 경로가 잘못되면 실제 작업은 진행되지 않습니다. 이런 경우 Remote SSH 자체의 문제로 오해하기 쉽지만, 실은 원격 환경 준비 부족인 경우가 많습니다.
접속 후에는 현재 디렉터리, 소유자 권한, Git 설치 여부, Node나 Python 런타임 유무까지 함께 확인하는 것이 좋습니다. 서버 접속 성공은 시작일 뿐이고, 편집·실행·디버깅까지 이어져야 실사용이 편해집니다.
문제 해결 순서: 가장 빨리 복구하는 체크리스트
- 터미널에서 직접 SSH 접속이 되는지 먼저 확인
- 안 되면 User, Port, IdentityFile, 서버 상태부터 점검
- publickey 오류면 로컬 키와 서버 authorized_keys 확인
- host identification changed면 known_hosts 충돌 정리
- 터미널은 되는데 VSCode만 안 되면 Remote SSH 로그 확인
- VSCode Server 설치 실패 흔적, 디스크 용량, 셸 초기화 파일 점검
- 연결 후 프로젝트 권한, Git, 런타임 환경까지 확인
문제는 한 번에 여러 개가 겹칠 때 더 헷갈립니다. 예를 들어 키는 맞지만 사용자명이 틀렸거나, 로그인은 되지만 셸 설정이 꼬여 VSCode 설치가 실패할 수 있습니다. 그래서 한 단계씩 분리해 보는 방식이 가장 확실합니다.
처음부터 덜 막히는 설정 팁
처음부터 안정적으로 쓰려면 서버마다 SSH 별칭을 명확히 나누고, 키 파일도 목적별로 분리해 관리하는 편이 좋습니다. 개인 서버, 회사 서버, 클라우드 인스턴스를 같은 키와 같은 별칭 체계로 섞어 두면 나중에 충돌이 많아집니다.
또한 원격 서버 계정은 가능한 한 단순하게 유지하는 것이 좋습니다. 접속 직후 자동 실행되는 셸 스크립트, 과한 배너 출력, 불필요한 프롬프트 꾸미기는 Remote SSH 안정성을 떨어뜨릴 수 있습니다. 연결이 최우선이라면 “예쁘게”보다 “안정적으로” 관리하는 쪽이 유리합니다.
프로젝트를 열기 전에 Git, Node.js, Python 같은 필수 런타임이 원격 서버에 준비되어 있는지도 함께 확인하면 좋습니다. 연결만 성공하고 개발이 진행되지 않는 상황을 줄일 수 있기 때문입니다.
자주 묻는 질문
연결 오류는 겉으로 비슷해 보여도 원인은 제각각입니다. 그래서 에러 문구 하나만 보고 단정하기보다, 터미널 접속 가능 여부 → 키와 권한 → known_hosts → VSCode Server 설치 순서로 나눠 보면 훨씬 빨리 해결됩니다.
한 번 연결 구조를 정리해 두면 이후에는 서버를 바꾸거나 새 맥북으로 옮겨도 훨씬 편해집니다. 특히 SSH 키, config, VSCode 동기화 설정까지 같이 정리하면 원격 개발 환경을 안정적으로 오래 유지할 수 있습니다.
0 댓글