SFTP 파일 전송 가이드

StreamGPU 서버와 파일을 주고받는 방법을 운영체제별로 안내합니다. SFTP는 SSH를 기반으로 한 안전한 파일 전송 프로토콜입니다.

SFTP란 무엇인가요?

SFTP(SSH File Transfer Protocol)는 SSH 연결을 통해 파일을 안전하게 주고받는 프로토콜입니다. 단순 파일 복사뿐 아니라 원격 디렉터리 탐색, 파일 삭제 등 기본적인 파일 관리 기능을 제공합니다. (참고: FTP는 암호화되지 않은 전송 방식이므로 이 문서에서는 사용하지 않습니다.)

연결 옵션 간단 설명

• -i <파일>: 사용할 개인키(Private key) 파일을 지정합니다.
• -P <포트>: SSH가 사용하는 포트 번호를 지정합니다(대소문자 구분).
• user@host: 사용자명과 서버 주소를 합친 형태입니다. 예: awesome@server.example.com

운영체제별 가이드

Windows — WinSCP (권장, GUI)

WinSCP는 무료 SFTP 클라이언트로, 드래그 앤 드롭으로 파일을 쉽게 전송할 수 있습니다.

1. WinSCP를 설치합니다 (https://winscp.net)
2. 로그인 창에서 프로토콜=SFTP, 호스트=대시보드의 서버 주소, 포트=대시보드 포트, 사용자명=awesome, 개인 키 파일에 다운로드한 .pem을 지정합니다.

Windows — 명령줄에서 SFTP/SSH 사용하기

Windows 환경에서는 여러 방식으로 SFTP를 사용할 수 있습니다. 아래에서 본인 환경에 맞는 방법을 선택하세요.

OpenSSH (PowerShell / CMD)

Windows 10/11에는 OpenSSH 클라이언트가 포함된 경우가 많습니다. PowerShell이나 CMD에서 다음과 같이 실행합니다:

# OpenSSH (PowerShell 또는 CMD)
sftp -i C:\Users\YOURUSER\.ssh\streamgpu\my-server-abc123.pem -P 2222 awesome@server.example.com
# 또는
ssh -i C:\Users\YOURUSER\.ssh\streamgpu\my-server-abc123.pem -p 2222 awesome@server.example.com

참고: Windows에서는 리눅스의 chmod 600과 동일하게 동작하지 않습니다. 대신 아래 icacls로 권한을 제한하세요:

# PowerShell 예시
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.ssh\streamgpu"
Move-Item -Path "$env:USERPROFILE\Downloads\my-server-abc123.pem" -Destination "$env:USERPROFILE\.ssh\streamgpu\my-server-abc123.pem"
icacls "$env:USERPROFILE\.ssh\streamgpu\my-server-abc123.pem" /inheritance:r /grant:r "$env:USERNAME:(R)"

Git Bash / WSL

Git Bash나 WSL을 사용하면 리눅스와 같은 환경에서 명령어를 그대로 쓸 수 있습니다. 권한 설정이 필요하면 chmod 600을 사용하세요:

mkdir -p ~/.ssh/streamgpu
mv ~/Downloads/my-server-abc123.pem ~/.ssh/streamgpu/
chmod 600 ~/.ssh/streamgpu/my-server-abc123.pem
sftp -i ~/.ssh/streamgpu/my-server-abc123.pem -P 2222 awesome@server.example.com

PuTTY / PuTTYgen / Pageant

PuTTY 계열 도구는 Windows에서 널리 쓰입니다. PuTTY는 .ppk 형식의 키를 사용하므로, PEM에서 PPK로 변환해야 합니다.

1. PuTTYgen 실행 → Load로 .pem 파일 불러오기 (파일 형식을 'All Files'로 선택).
2. 불러온 뒤 Save private key로 .ppk 저장.
3. PuTTY: Session 설정 → Connection → SSH → Auth → "Private key file for authentication"에 .ppk 지정.
4. Pageant를 사용하면 한 번 로드한 키를 세션 간 재사용할 수 있어 편리합니다.

WinSCP에서 개인키 사용하기

1. WinSCP에서 새 세션 생성: 파일 프로토콜=SFTP, 호스트/포트/사용자명 입력.
2. Advanced(고급) → SSH → Authentication → "Private key file"에 .ppk 지정.
3. 만약 PEM 파일만 있다면 PuTTYgen으로 변환한 후 지정하세요.

Mac — Cyberduck 또는 터미널

Cyberduck(그래픽) 또는 터미널의 sftp 명령을 사용하세요.

Linux — 터미널

대부분의 배포판에 기본으로 포함된 sftp 클라이언트를 사용하면 됩니다.

명령 예시

sftp -i ~/.ssh/streamgpu/<파일명> -P <포트번호> awesome@<서버주소>

대화형 SFTP 기본 명령 (초급자용)

SFTP에 접속한 뒤 사용할 수 있는 기본 명령입니다. 접속 후 프롬프트는 보통 sftp>로 표시됩니다.

# 예: 접속
sftp -i ~/.ssh/streamgpu/my-server-abc123.pem -P 2222 awesome@server.example.com

# 접속 후 기본 명령 (sftp> 프롬프트에서)
ls                # 원격 디렉터리 목록
pwd               # 원격 현재 경로 확인
lcd /path/to/local # 로컬 작업 디렉터리 변경
cd /remote/path   # 원격 디렉터리 변경
get remote.txt    # 원격 파일을 로컬로 다운로드
put local.txt     # 로컬 파일을 원격으로 업로드
mkdir newdir      # 원격에 새 폴더 생성
rm file.txt       # 원격 파일 삭제
bye               # 연결 종료

문제 해결

• Permission denied — 키 파일 권한 확인: chmod 600
• Connection refused — 포트/방화벽 확인
• 속도 저하 — 네트워크/rsync 옵션 검토

권한 오류 조금 더 자세히

개인키 파일은 본인만 읽을 수 있어야 합니다. 다음을 실행하면 권한과 소유자가 올바른지 확인할 수 있습니다:

ls -l ~/.ssh/streamgpu/
# -rw-------  1 youruser  staff  1675 Dec  3 12:34 my-server-abc123.pem

# 권한 설정 (필요 시)
chmod 600 ~/.ssh/streamgpu/my-server-abc123.pem

호스트 키(Host key) 확인

처음 접속할 때 서버 호스트 키 지문(fingerprint)이 표시됩니다. 대시보드나 관리자에게서 제공된 지문과 일치하는지 확인하세요. 일치하지 않는다면 연결을 중단하고 관리자에게 문의해야 합니다(중간자 공격(MITM) 가능성). 대신 무조건 yes를 눌러 진행하지 마세요.

추가 문제 해결 예

• Too many authentication failures — SSH 클라이언트가 여러 키를 시도하여 실패할 수 있습니다. 다음 옵션을 사용해보세요:

  ssh -o IdentitiesOnly=yes -i ~/.ssh/streamgpu/my-server-abc123.pem -p 2222 awesome@server.example.com