폐쇄망 환경에서 VS Code Remote-SSH 사용하기 (오프라인 설치 가이드)
들어가기
안녕하세요.
오늘은 폐쇄망 환경에서 VS Code Remote-SSH를 사용하는 방법에 대해 알아보겠습니다.
보안 정책상 개발 PC에서 외부 인터넷 접근이 제한되거나, 서버에 직접 접속해 터미널 기반으로만 작업해야 하는 환경이 존재합니다.
이러한 경우 서버에서 직접 편집을 진행하면, 로컬 IDE에서 제공되는 자동 완성, 디버깅, 확장 기능 등 기존의 개발 경험을 충분히 활용하기 어렵습니다.
이처럼 서버 자원을 사용해야 하지만 로컬 개발 환경의 편의성은 유지하고 싶은 상황에서, 그 대안 중 하나가 VS Code Remote-SSH입니다.
하지만 인터넷에 연결되지 않은 서버에 VS Code 확장 프로그램인 Remote-SSH를 사용해 접근하려고 하면, 기본 설정만으로는 오류가 발생합니다.
이 글에서는 이러한 문제를 해결하기 위해, 폐쇄망 환경에서 Remote-SSH를 정상적으로 사용하기 위한 오프라인 설치 방법을 단계별로 정리합니다.
또한, 기존에 널리 알려진 스택오버플로우의 방법을 그대로 따라 해도 최근 버전의 VS Code에서는 동일한 오류가 발생할 수 있습니다.
이는 최근 VS Code 및 Remote-SSH의 내부 동작 방식이 변경되었기 때문입니다.
본 글은 이미 VS Code Remote-SSH를 사용해 본 경험이 있는 분을 대상으로 하며, 기본적인 SSH 개념과 사용법은 다루지 않습니다.
바쁨!
바쁘신 분들은 4번 사전 준비 체크리스트부터 확인하셔도 됩니다.
버전
1.97.2 버전 기준으로 설명합니다. 그 이후 버전은 BadInstallScriptResult 에러가 발생합니다.
1. 글의 범위와 전제
1.1 대상 독자
이 글은 다음과 같은 분들을 대상으로 작성되었습니다.
- VS Code에서 Remote-SSH를 사용해 본 경험이 있는 개발자
- 폐쇄망(에어갭) 서버에 개발 환경을 구성해야 하는 경우
- 인터넷이 차단된 서버에서 VS Code 기반 개발을 유지해야 하는 경우
1.2 이 글에서 해결하는 문제
이 글에서 다루는 핵심 문제는 다음과 같습니다.
- Remote-SSH 접속 시 서버에서 vscode-server 다운로드 단계에서 실패하는 문제
- 기존
~/.vscode-server/bin/<commit>방식이 동작하지 않는 문제 - 오프라인 환경에서 vscode-server를 수동으로 설치해야 하는 상황
1.3 폐쇄망 환경의 제약 조건
일반적으로 폐쇄망 환경에서는 다음과 같은 제약이 존재합니다.
- 서버에서 외부 인터넷 접근 불가
- 패키지 매니저를 통한 실시간 다운로드 불가
- 특정 포트 및 아웃바운드 트래픽 차단
이로 인해 VS Code Remote-SSH의 기본 동작 흐름이 정상적으로 완료되지 않습니다.
2. Remote-SSH가 실패하는 이유
2.1 Remote-SSH의 내부 동작 개요
VS Code Remote-SSH는 단순히 SSH로 접속만 하는 확장이 아닙니다.
연결 과정에서 VS Code는 원격 서버에 다음 작업을 수행합니다.
- vscode-server 바이너리 다운로드
- 서버 환경에 맞는 실행 파일 압축 해제
- 원격 서버에서 VS Code와 통신할 백엔드 프로세스 실행
이 과정 중 다운로드 단계가 실패하면 Remote-SSH 연결 자체가 중단됩니다.
2.2 폐쇄망에서 발생하는 대표적인 오류
폐쇄망 환경에서는 다음과 같은 오류를 자주 마주치게 됩니다.
Failed to download VS Code ServerWaiting for vscode-server to be installed- 무한 재시도 루프
이는 모두 서버에서 외부 네트워크로 접근할 수 없기 때문에 발생하는 문제입니다.
2.3 기존 스택오버플로우 방식이 실패하는 이유
과거에는 ~/.vscode-server/bin/<commit> 경로에 미리 다운로드한 파일을 복사하는 방식으로 문제를 해결할 수 있었습니다.
하지만 최근 버전의 VS Code Remote-SSH에서는 서버 설치 경로 및 실행 방식이 변경되었고, 이로 인해 기존 방식이 더 이상 통하지 않는 경우가 많아졌습니다.
3. 최근 VS Code / Remote-SSH의 변경점
3.1 기존 방식: ~/.vscode-server/bin/<commit>
과거 Remote-SSH는 커밋 ID 기준으로 다음 경로에 서버 파일을 설치했습니다.
plain~/.vscode-server/bin/<commit>/
이 경로에 파일이 존재하면 다운로드 과정을 건너뛰었습니다.
3.2 최신 방식: cli/servers/Stable-<commit>
최근 버전에서는 다음과 같은 새로운 경로가 사용됩니다.
plain~/.vscode-server/code-<commit>
~/.vscode-server/cli/servers/Stable-<commit>/server/
이 변화로 인해 기존 경로에 파일을 복사해도 Remote-SSH가 이를 인식하지 못하는 상황이 발생합니다.
3.3 내 환경에서 사용 중인 방식 확인하기
현재 사용 중인 방식은 VS Code의 Remote-SSH Output 로그를 통해 확인할 수 있습니다.
로그에 다음과 같은 문자열이 포함되어 있다면 최신 방식입니다.
cli/servers/Stable-<commit>/server/bin/code-server
4. 사전 준비 체크리스트
4.1 서버 OS 및 아키텍처 확인
서버의 운영체제와 CPU 아키텍처(x64, arm64 등)를 정확히 확인해야 합니다.
잘못된 아키텍처의 바이너리를 사용할 경우 실행 단계에서 실패합니다.
4.2 VS Code 버전 및 Commit ID 확인
VS Code는 커밋 ID 기준으로 버전을 관리합니다.
로컬 PC에서 사용 중인 VS Code의 Commit ID를 반드시 확인해 두어야 합니다.
방법은 아래와 같습니다.
bashcode -v
1.97.2 # 버전
{COMMIT} # 커밋
x64 # 아키텍처
4.3 서버 필수 조건
- SSH 접속 가능
- 사용자 홈 디렉토리 쓰기 권한
- 충분한 디스크 공간
5. 오프라인 설치 파일 준비
5.1 인터넷 가능한 PC에서 파일 준비
인터넷이 가능한 PC에서 서버용 vscode-server 압축 파일을 미리 다운로드합니다.
사전에 확인한 COMMIT 값을 아래 주소에 대입하여 파일을 다운로드 합니다.
https://vscode.download.prss.microsoft.com/dbazure/download/stable/${COMMIT}/vscode-server-linux-x64.tar.gz
https://vscode.download.prss.microsoft.com/dbazure/download/stable/${COMMIT}/vscode_cli_alpine_x64_cli.tar.gz
아래 각각 파일명을 가진 압축파일이 다운로드 됩니다.
vscode-server-linux-x64.tar.gz
vscode-cli_alpine_x64_cli.tar.gz
5.2 폐쇄망 서버로 파일 반입
USB, 내부 파일 서버, 보안 승인된 전송 수단을 이용해 서버로 파일을 전달합니다.
6. 폐쇄망 서버에 VS Code Server 수동 설치
6.1 최신 경로 기준 설치 방법
다운로드 한 두 파일을 특정 폴더에 지정해서 넣어두고 아래의 스크립트를 실행합니다.
bashCOMMIT=COMMIT_ID # 여기에 자신의 VS Code Commit ID를 입력
# 현재 디렉토리에 아래 두 파일이 존재한다고 가정
# - vscode-server-linux-x64.tar.gz
# - vscode-cli_alpine_x64_cli.tar.gz
# 1. vscode-cli 압축 해제
tar -xzf ./vscode-cli_alpine_x64_cli.tar.gz
# 2. code 실행 파일을 Commit ID 기준으로 복사
cp code ./vscode-server-code-${COMMIT}
# 3. 최신 Remote-SSH에서 사용하는 서버 디렉토리 생성
mkdir -p ~/.vscode-server/cli/servers/Stable-${COMMIT}/server
# 4. vscode-server 파일 압축 해제
tar -xzf ./vscode-server-linux-x64.tar.gz \
-C ~/.vscode-server/cli/servers/Stable-${COMMIT}/server \
--strip-components=1
# 5. 권한 정리 (권한 문제로 인한 실패 방지)
chmod -R 700 ~/.vscode-server
6.2 스크립트 설명
- 1단계: vscode-cli 압축을 해제하여 code 실행 파일을 준비합니다.
- 2단계: code 바이너리를 Commit ID 기준 이름으로 복사합니다.
- 3단계: 최신 Remote-SSH가 인식하는 서버 설치 경로를 생성합니다.
- 4단계: 서버용 VS Code 바이너리를 해당 경로에 압축 해제합니다.
- 5단계: 퍼미션 문제로 인한 재설치 루프를 방지하기 위해 권한을 정리합니다.
이 단계까지 완료되면, Remote-SSH가 서버에 추가 다운로드를 시도하지 않고 기존 파일을 사용하게 됩니다.
7. Remote-SSH 연결 확인
7.1 VS Code에서 재접속
설치가 완료되면 VS Code에서 Remote-SSH로 다시 접속을 시도합니다.
7.2 정상 동작 여부 확인
정상적으로 연결되었다면 연결 완료 후 아무 에러 없이 VS Code 창이 뜨는 걸 확인할 수 있습니다.
8. 자주 발생하는 문제와 해결 방법
8.1 Commit ID 불일치
VS Code가 업데이트되면 Commit ID가 변경되며, 기존 서버 파일이 재사용되지 않습니다.
VS Code 업데이트를 진행하게 되면 위의 과정을 반복해주시면 됩니다.
8.2 아키텍처 불일치
서버 아키텍처와 다른 바이너리를 사용하는 경우 실행이 불가능합니다.
8.3 퍼미션 및 홈 디렉토리 문제
NFS 홈 디렉토리 또는 제한된 권한 환경에서는 추가 설정이 필요할 수 있습니다.
9. 운영 팁
9.1 VS Code 업데이트 전략
폐쇄망 환경에서는 VS Code 버전을 고정해 사용하는 것이 관리 측면에서 유리합니다.
9.2 팀 단위 배포 전략
미리 서버 바이너리를 패키징해 내부 배포용으로 관리하면 반복 작업을 줄일 수 있습니다.
10. 마무리
본 글에서는 폐쇄망 환경에서 VS Code Remote-SSH를 오프라인으로 구성하는 방법을 살펴보았습니다.
환경 제약으로 인해 번거로울 수 있지만, 한 번 구성해 두면 로컬과 동일한 개발 경험을 유지할 수 있습니다.
폐쇄망 환경에서 개발 생산성을 유지해야 하는 분들께 이 글이 도움이 되기를 바랍니다.