원격 서버와의 안전한 연결: VSCode를 통한 SSH 키 인증 및 개발 환경 설정 가이드

💡

이 글에서 다루는 내용 VSCode의 Remote-SSH 확장을 이용하여 원격 서버에서 로컬과 동일한 개발 환경을 구축하는 방법을 안내합니다. 보안을 위해 비밀번호 대신 SSH 공개 키 인증 방식을 사용하며, 선택적으로 비밀번호 접속을 완전히 차단하는 설정도 다룹니다. 환경: server - Ubuntu 22.04 LTS / client - macOS Ventura (Windows도 유사)

Remote-SSH란?

VSCode의 Remote-SSH 확장은 SSH 프로토콜을 통해 원격 서버에 연결하여 마치 로컬에서 작업하는 것처럼 코드를 편집하고 디버깅할 수 있게 해주는 도구입니다.

주요 장점

로컬과 동일한 개발 경험: 원격 서버의 파일을 로컬 VSCode에서 직접 편집

확장 기능 원격 실행: 린터, 포매터 등의 확장이 원격 서버에서 실행되어 정확한 결과 제공

터미널 통합: VSCode 내장 터미널에서 원격 서버 명령어 직접 실행

Git 통합: 원격 저장소에서 Git 작업 수행 가능

1️⃣ SSH 접속 설정 (서버 측)

먼저 서버에서 SSH 접속을 허용하도록 설정합니다.

sshd_config 파일 수정

서버 콘솔에서 SSH 설정 파일을 열어줍니다:

sudo vi /etc/ssh/sshd_config

파일 내에서 다음 라인을 찾아 주석을 해제합니다:

# 변경 전
#PasswordAuthentication yes
#PubkeyAuthentication yes

# 변경 후
PasswordAuthentication yes
PubkeyAuthentication yes

⚠️

Cloud-init 사용 서버의 경우 AWS, GCP 등 클라우드 환경에서 cloud-init이 적용된 서버라면 /etc/ssh/sshd_config.d/50-cloud-init.conf 파일을 수정해야 합니다: PasswordAuthentication no → PasswordAuthentication yes

변경 내용을 저장한 후 SSH 서비스를 재시작합니다:

sudo systemctl restart sshd.service

2️⃣ SSH Key 생성 (클라이언트 측)

SSH 키는 비밀번호보다 안전한 인증 방식입니다. 공개 키(Public Key)와 개인 키(Private Key) 쌍을 생성하여 사용합니다.

SSH 키 알고리즘 비교

알고리즘	보안 수준	키 크기	권장 여부
RSA	높음	2048-4096 bits	⭕ (4096 bits 권장)
Ed25519	매우 높음	256 bits	✅ 가장 권장
DSA	낮음	1024 bits	❌ (2022년 GitHub 지원 중단)
ECDSA	높음	256-521 bits	⭕

키 생성하기

클라이언트의 터미널에서 다음 명령어를 입력합니다. Ed25519 알고리즘을 권장합니다:

# Ed25519 키 생성 (권장)
ssh-keygen -t ed25519 -C "your_email@example.com"

# 또는 RSA 4096 키 생성 (레거시 시스템용)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Enter 키를 눌러 기본 설정으로 진행합니다. 비밀번호(passphrase)는 선택사항이며, 설정하면 개인 키 사용 시마다 입력이 필요합니다.

생성된 키는 기본적으로 다음 경로에 저장됩니다:

~/.ssh/id_ed25519      # 개인 키 (절대 공유 금지!)
~/.ssh/id_ed25519.pub  # 공개 키 (서버에 등록)

🔐

키 파일 권한 설정 SSH는 보안상 키 파일의 권한을 엄격히 검사합니다. 다음과 같이 설정하세요: • 공개 키 (.pub): chmod 644 ~/.ssh/id_ed25519.pub • 개인 키: chmod 600 ~/.ssh/id_ed25519 • .ssh 디렉토리: chmod 700 ~/.ssh 권한이 잘못되면 "Permissions are too open" 오류가 발생합니다.

서버에 공개 키 등록

다음 명령어로 공개 키를 서버에 전송합니다:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

여기서 user는 서버 계정명, server는 서버의 IP 주소 또는 도메인입니다.

💡

수동으로 공개 키 등록하기 ssh-copy-id 명령을 사용할 수 없는 경우, 공개 키 내용을 복사하여 서버의 ~/.ssh/authorized_keys 파일에 직접 추가할 수 있습니다: cat ~/.ssh/id_ed25519.pub | ssh user@server "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

3️⃣ ssh-agent 설정 (선택사항)

SSH 키에 passphrase를 설정했다면, ssh-agent를 사용하여 매번 비밀번호를 입력하는 번거로움을 줄일 수 있습니다.

ssh-agent란?

ssh-agent는 개인 키의 비밀번호를 메모리에 암호화하여 저장하는 프로그램입니다. 한 번만 비밀번호를 입력하면 세션이 유지되는 동안 자동으로 인증됩니다.

# ssh-agent 시작
eval "$(ssh-agent -s)"

# 개인 키 등록 (passphrase 입력)
ssh-add ~/.ssh/id_ed25519

# 등록된 키 확인
ssh-add -l

✨

macOS 사용자 팁 macOS에서는 Keychain에 passphrase를 저장하여 재부팅 후에도 자동으로 로드할 수 있습니다: ssh-add --apple-use-keychain ~/.ssh/id_ed25519

4️⃣ VSCode Remote-SSH 설정

이제 SSH 접속이 가능해졌으니, VSCode에서 원격 개발 환경을 구성합니다.

Remote-SSH 확장 설치

VSCode 확장 마켓플레이스에서 Remote - SSH (Microsoft 제공)를 검색하여 설치합니다.

SSH Host 설정

VSCode 왼쪽 사이드바에서 Remote Explorer 아이콘을 클릭합니다.

SSH Targets 섹션에서 톱니바퀴 아이콘 또는 Add SSH Host... 를 선택합니다.

SSH config 파일을 선택하거나 생성합니다.

~/.ssh/config 파일에 다음과 같이 설정합니다:

# ~/.ssh/config

Host home_server
  HostName 192.168.1.100    # 서버 IP 또는 도메인
  Port 22                    # SSH 포트 (기본값 22)
  User pieroot               # 서버 접속 계정
  IdentityFile ~/.ssh/id_ed25519  # 개인 키 경로
  
# 여러 서버를 추가할 수 있습니다
Host work_server
  HostName work.example.com
  Port 2222
  User developer
  IdentityFile ~/.ssh/work_key

⚙️

유용한 SSH Config 옵션 • ServerAliveInterval 60: 60초마다 연결 유지 패킷 전송 (연결 끊김 방지) • ServerAliveCountMax 3: 연결 유지 실패 허용 횟수 • ForwardAgent yes: ssh-agent 포워딩 활성화 • Compression yes: 데이터 압축 (느린 네트워크에서 유용)

원격 서버 연결

Remote Explorer에서 설정한 SSH Host를 클릭합니다.

새 창 또는 현재 창에서 연결을 선택합니다.

최초 연결 시 서버에 VSCode Server가 자동으로 설치됩니다.

연결이 완료되면 VSCode 좌측 하단에 SSH: home_server와 같이 연결 상태가 표시됩니다.

5️⃣ (선택사항) 비밀번호 접속 비활성화

공개 키 인증이 정상 작동하는 것을 확인한 후, 보안 강화를 위해 비밀번호 접속을 완전히 차단할 수 있습니다.

⚠️

주의: 비밀번호 접속을 비활성화하기 전에 반드시 SSH 키로 접속이 되는지 확인하세요! 그렇지 않으면 서버에 접속할 수 없게 됩니다.

sshd_config 수정

sudo vi /etc/ssh/sshd_config

다음과 같이 변경합니다:

# 변경 전
PasswordAuthentication yes

# 변경 후
PasswordAuthentication no

SSH 서비스를 재시작합니다:

sudo systemctl restart ssh.service sshd.service

이제 서버는 공개 키 인증만 허용하며, 비밀번호로는 접속할 수 없습니다.

6️⃣ SSH 접속 명령어

config 파일 설정 완료 시

ssh home_server

직접 옵션 지정 시

ssh pieroot@192.168.1.100 -i ~/.ssh/id_ed25519

주요 SSH 옵션

옵션	설명	예시
`-p`	SSH 포트 지정 (기본값 22)	`ssh -p 2222 user@server`
`-i`	개인 키 파일 경로 지정	`ssh -i ~/.ssh/mykey user@server`
`-L`	로컬 포트 포워딩	`ssh -L 8080:localhost:80` `user@server`
`-C`	데이터 압축 전송	`ssh -C user@server`
`-X`	X11 포워딩 (GUI 앱 실행)	`ssh -X user@server`
`-v`	디버그 모드 (문제 해결용)	`ssh -v user@server`

포트 포워딩 예시

로컬 8080 포트로 접속하면 서버의 80 포트에 접속한 것과 같은 효과를 얻습니다:

ssh -p 2222 -L 8080:localhost:80 user@server
# 이후 브라우저에서 http://localhost:8080 접속

트러블슈팅

자주 발생하는 오류와 해결 방법

오류 메시지	원인	해결 방법
Permission denied (publickey)	공개 키가 서버에 등록되지 않음	`ssh-copy-id` 재실행
Permissions are too open	키 파일 권한이 너무 열려 있음	`chmod 600 ~/.ssh/id_*`
Connection refused	SSH 서비스가 실행되지 않음	`sudo systemctl start sshd`
Host key verification failed	서버 키가 변경됨	`ssh-keygen -R hostname`

디버그 모드로 상세한 오류 정보를 확인할 수 있습니다:

ssh -vvv user@server

핵심 정리

✅ Remote-SSH: VSCode에서 원격 서버를 로컬처럼 사용할 수 있는 확장 기능

✅ SSH 키 인증: 비밀번호보다 안전하며, Ed25519 알고리즘을 권장

✅ 키 파일 권한: 개인 키는 600, 공개 키는 644, .ssh 디렉토리는 700

✅ ssh-agent: passphrase 입력을 한 번만 하도록 도와주는 유틸리티

✅ SSH Config: ~/.ssh/config 파일로 여러 서버 설정을 간편하게 관리

✅ 보안 강화: 공개 키 인증 확인 후 비밀번호 접속 비활성화 권장

참고 자료

VSCode Remote SSH 공식 문서

GitHub SSH 키 생성 가이드