# SFTP로 연결하기: FileZilla, Cyberduck 및 명령줄

Source: https://support.kapsulehost.com/ko-kr/sftp-access

SFTP(Secure File Transfer Protocol)를 사용하면 서버에 있는 사이트 파일에 직접 접근할 수 있습니다. 이 가이드는 자격 증명을 찾는 방법부터 오류 해결까지 성공적으로 연결하는 데 필요한 모든 내용을 다룹니다.

## SFTP란 무엇이며 언제 사용해야 하는가

KPanel에 내장된 파일 관리자는 파일 이름 변경, 설정 파일 보기, 단일 자산 업로드 같은 간단한 작업에 편리합니다. 다음과 같이 더 많은 작업이 필요할 때는 SFTP가 적합한 도구입니다:

- 한 번에 많은 수의 파일을 업로드하거나 다운로드할 때(사이트 이전, 이미지 대량 업로드).
- 브라우저 기반 업로드에서는 시간 초과가 발생할 만큼 큰 파일을 전송할 때.
- 로컬에서 파일을 편집하고 변경 사항을 전송하는 개발 워크플로의 일부로 작업할 때.
- 로컬 폴더와 원격 폴더를 동기화할 수 있는 GUI 클라이언트를 사용할 때.
- KPanel의 파일 관리자에서 노출되지 않는 로그나 설정 파일에 접근할 때.

SFTP는 전송 중인 모든 데이터를 암호화하므로 일반 FTP보다 안전합니다. KapsuleHost는 암호화되지 않은 FTP 연결을 제공하지 않습니다.

![KPanel에서 사이트의 SSH 및 SFTP 연결 세부 정보](https://support.kapsulehost.com/help/screenshots/sftp-access.df4a2e3e.webp)

## 사전 준비 사항

연결하기 전에 두 가지가 준비되어 있어야 합니다.

**1. KPanel에서 사이트에 추가된 SSH 키.**

KapsuleHost의 SFTP는 SSH 키 인증을 사용합니다. 보안을 위해 비밀번호 인증은 비활성화되어 있습니다. 아직 SSH 공개 키를 추가하지 않았다면 먼저 [사이트에 SSH 키 추가하기](https://support.kapsulehost.com/ko-kr/adding-ssh-keys) 가이드를 따른 다음 이 문서로 돌아오세요.

**2. 사이트 사용자 이름.**

KapsuleHost의 각 사이트에는 전용 시스템 사용자가 있습니다. 이는 KPanel 이메일 주소가 아닙니다. 해당 사이트에만 연결된 짧은 사용자 이름입니다.

확인 방법:
1. [kpanel.kapsulehost.com](https://kpanel.kapsulehost.com)에서 KPanel에 로그인합니다.
2. 왼쪽 사이드바에서 **웹사이트**를 클릭합니다.
3. 연결하려는 사이트를 클릭합니다.
4. **SSH / SFTP** 페이지로 이동합니다.
5. 이 탭 상단에 사이트 사용자 이름이 표시됩니다. 일반적으로 `mysite_com` 또는 `myexamplesite_net`와 같은 형식입니다.

**연결 정보 한눈에 보기:**

| 항목 | 값 |
|---|---|
| 호스트 | `cp1-kapsule.kapsulehost.com` |
| 포트 | `22` |
| 프로토콜 | SFTP(FTP나 FTPS 아님) |
| 인증 | SSH 키만 사용 |
| 사용자 이름 | 사이트 사용자 이름(KPanel > Websites > [사이트] > Settings > SFTP에서 확인) |

---

## FileZilla로 연결하기

FileZilla는 Windows, macOS, Linux용으로 제공되는 무료 크로스 플랫폼 SFTP 클라이언트입니다. 아직 설치하지 않았다면 [filezilla-project.org](https://filezilla-project.org)에서 다운로드하세요.

### 단계별 설정

1. FileZilla를 엽니다.
2. **File > Site Manager**로 이동합니다(Windows에서는 `Ctrl+S`, Mac에서는 `Cmd+S`을 누릅니다).
3. **웹사이트 추가**를 클릭하고 이름을 지정합니다(예: "My KapsuleHost Site").
4. **General** 탭에서 다음 항목을 설정합니다:

   | 항목 | 값 |
   |---|---|
   | 프로토콜 | **SFTP - SSH File Transfer Protocol** |
   | 호스트 | `cp1-kapsule.kapsulehost.com` |
   | 포트 | `22` |
   | 로그온 유형 | **Key file** |
   | 사용자 | 사이트 사용자 이름(예: `mysite_com`) |
   | 키 파일 | **Browse**를 클릭하고 개인 키 파일을 찾아 선택 |

5. 키 파일로는 KPanel에 추가한 공개 키와 짝을 이루는 개인 키를 선택합니다. macOS와 Linux에서는 보통 개인 키가 `~/.ssh/`에 저장되어 있습니다(예: `~/.ssh/id_ed25519` 또는 `~/.ssh/id_rsa`). Windows에서는 보통 `C:\Users\YourName\.ssh\`에 있습니다.

> **Note:** 개인 키에 암호 구문이 설정되어 있다면 연결 시 FileZilla가 입력을 요청합니다. 이는 정상입니다. 이 암호 구문은 개인 키 파일을 보호하는 것으로, KapsuleHost 비밀번호와는 별개입니다.

6. **Connect**를 클릭해 연결을 테스트하거나 **OK**를 클릭해 저장한 뒤 나중에 연결합니다.

### 저장 및 재연결

Site Manager에 저장한 후에는 언제든 **File > Site Manager**로 이동해 **Connect**를 클릭하면 다시 연결할 수 있습니다. FileZilla는 또한 툴바 드롭다운에 저장된 사이트를 표시하여 빠르게 접근할 수 있게 해줍니다.

> **Tip:** FileZilla의 Site Manager에서 처음 연결할 때 **Always trust this host** 체크박스를 선택해 두면 이후 연결 시 호스트 키 확인 메시지가 다시 표시되지 않습니다.

---

## Cyberduck으로 연결하기

Cyberduck은 macOS와 Windows용 무료 SFTP 클라이언트입니다. [cyberduck.io](https://cyberduck.io)에서 다운로드하세요.

### 단계별 설정

1. Cyberduck을 엽니다.
2. **Open Connection**(툴바의 지구본 아이콘)을 클릭합니다.
3. 대화 상자 상단의 프로토콜 드롭다운에서 **SFTP (SSH File Transfer Protocol)**를 선택합니다.
4. 연결 항목을 입력합니다:

   | 항목 | 값 |
   |---|---|
   | 서버 | `cp1-kapsule.kapsulehost.com` |
   | 포트 | `22` |
   | 사용자 이름 | 사이트 사용자 이름(예: `mysite_com`) |
   | 비밀번호 | 비워 둠 |
   | SSH 개인 키 | **Choose**를 클릭하고 개인 키 파일을 선택 |

5. **Connect**를 클릭합니다.

처음 연결할 때 Cyberduck은 서버의 호스트 키 지문을 확인하라는 메시지를 표시합니다. 계속하려면 **Allow**를 클릭하세요. 이후 연결에서 다른 지문으로 이 메시지가 표시된다면 수락하지 말고 고객 지원에 문의하세요. 설정 변경을 나타낼 수 있습니다.

### 북마크로 저장하기

연결을 나중에 다시 사용하려면:
1. 성공적으로 연결한 후 **Bookmark > New Bookmark**로 이동합니다(Mac에서는 `Cmd+Shift+B`을 누릅니다).
2. 북마크에 이름을 지정하고 대화 상자를 닫습니다. 북마크는 Cyberduck 북마크 목록에 표시됩니다.

---

## 터미널에서 연결하기(Mac, Linux, WSL)

명령줄을 선호한다면 `sftp` 명령이 macOS, Linux, Windows Subsystem for Linux(WSL)에서 사용 가능합니다.

### 기본 연결

```bash
sftp mysite_com@cp1-kapsule.kapsulehost.com
```

`mysite_com` 부분을 실제 사이트 사용자 이름으로 바꾸세요. 개인 키가 기본 위치(`~/.ssh/id_rsa` 또는 `~/.ssh/id_ed25519`)에 없다면 `-i` 플래그로 지정하세요:

```bash
sftp -i ~/.ssh/your_private_key mysite_com@cp1-kapsule.kapsulehost.com
```

처음 연결할 때 서버의 호스트 지문을 확인하라는 메시지가 표시됩니다. `yes`을 입력하고 Enter를 누르세요. 이는 기기별, 키별로 한 번만 발생합니다.

### 유용한 SFTP 명령어

연결되면 `sftp>` 프롬프트가 표시됩니다. 다음 명령어로 탐색하고 파일을 전송하세요:

| 명령어 | 기능 |
|---|---|
| `ls` | 현재 원격 디렉터리의 파일 목록 표시 |
| `lls` | 현재 로컬 디렉터리의 파일 목록 표시 |
| `cd [dir]` | 원격 서버에서 디렉터리 변경 |
| `lcd [dir]` | 로컬 컴퓨터에서 디렉터리 변경 |
| `pwd` | 현재 원격 디렉터리 경로 표시 |
| `lpwd` | 현재 로컬 디렉터리 경로 표시 |
| `get [file]` | 원격에서 로컬로 파일 다운로드 |
| `get -r [dir]` | 디렉터리를 재귀적으로 다운로드 |
| `put [file]` | 로컬에서 원격으로 파일 업로드 |
| `put -r [dir]` | 디렉터리를 재귀적으로 업로드 |
| `rm [file]` | 원격 서버에서 파일 삭제 |
| `mkdir [dir]` | 원격 서버에 디렉터리 생성 |
| `quit` | SFTP 연결 종료 |

**예시: 파일 다운로드하기**
```bash
sftp> cd htdocs/wp-content/themes
sftp> get my-theme.zip
```

**예시: 파일 업로드하기**
```bash
sftp> lcd ~/Desktop
sftp> cd htdocs/wp-content/uploads
sftp> put my-image.jpg
```

---

## 파일 위치 확인하기

연결하면 사이트 사용자의 홈 디렉터리인 `/home/[siteuser]/`로 이동됩니다.

디렉터리 구조는 다음과 같습니다:

```
/home/mysite_com/
├── htdocs/              ← Your web root (main location for site files)
│   ├── index.php
│   ├── wp-config.php
│   ├── wp-content/
│   │   ├── themes/
│   │   ├── plugins/
│   │   └── uploads/
│   └── ...
├── logs/                ← PHP and access logs
└── tmp/                 ← Temporary files
```

WordPress(또는 다른 애플리케이션)가 위치한 웹 루트는 `htdocs/`입니다. 대부분의 작업을 이 디렉터리에서 하게 됩니다. 일부 사이트 구성에서는 대신 `public_html/`이라는 이름으로 되어 있을 수 있습니다. 연결 후 `htdocs/` 대신 `public_html/`이 보인다면 그것을 사용하세요.

> **Note:** 자신의 사이트 사용자에게 속한 파일에만 접근할 수 있습니다. `/home/[siteuser]/`보다 상위로 이동하거나 다른 고객의 디렉터리에 접근할 수 없습니다. 이는 의도된 설계입니다.

---

## 연결 문제 해결하기

### "Connection refused"(연결 거부됨)

연결이 수립되기 전에 적극적으로 거부되었습니다.

**확인 사항:** 호스트가 `cp1-kapsule.kapsulehost.com`이고 포트가 `22`인지 확인하세요. 흔한 실수는 포트 `21`(FTP용이며 SFTP가 아님)을 입력하거나 호스트 이름을 잘못 입력하는 것입니다.

### "Permission denied (publickey)"(권한 거부됨)

서버는 연결 시도를 받아들였지만 인증을 거부했습니다.

**다음 항목을 확인하세요:**
- SSH 공개 키가 **KPanel > Websites > [사이트] > Settings > SSH Keys**에 추가되어 있는지 확인하세요. 목록에 없다면 서버에 해당 키 기록이 없는 것입니다.
- FileZilla/Cyberduck에서 올바른 개인 키, 즉 KPanel에 추가한 공개 키와 짝을 이루는 개인 키를 선택했는지 확인하세요.
- 키에 암호 구문이 설정되어 있다면 올바르게 입력하고 있는지 확인하세요.
- 키가 여러 개라면 실수로 잘못된 키를 선택하지 않았는지 확인하세요.

### "Host key verification failed"(호스트 키 검증 실패)

SFTP 클라이언트가 이 호스트 이름에 대해 이전에 다른 호스트 키를 확인한 적이 있어 불일치를 경고하는 것입니다.

**처음 연결할 때:** 지문을 수락하라는 메시지가 표시됩니다. 이는 정상입니다. Accept를 클릭하거나 `yes`을 입력하세요.

**새로운 지문으로 이후 연결할 때:** 서버의 설정 변경을 의미할 수 있습니다. 수락하기 전에 [support@kapsulehost.com](mailto:support@kapsulehost.com)으로 고객 지원에 문의하고 확인한 내용을 알려주세요.

터미널에서 오래된 호스트 키를 삭제하려면 `~/.ssh/known_hosts` 파일을 편집하여 `cp1-kapsule.kapsulehost.com`에 해당하는 줄을 제거하세요.

### "Could not read from remote repository" 또는 잘못된 디렉터리

사이트 사용자 이름 대신 KPanel 이메일 주소를 사용자 이름으로 사용했을 수 있습니다.

**확인 사항:** 사용자 이름은 이메일 주소가 아니라 사이트 사용자 이름(예: `mysite_com`)이어야 합니다. 올바른 사용자 이름은 **KPanel > Websites > [사이트] > Settings > SFTP**에서 확인하세요.

### 연결 시간 초과

연결 시도가 멈춘 후 아무 오류 메시지 없이 시간 초과됩니다.

**가능한 원인:**
- 반복된 로그인 실패로 인해 KapsuleHost 방화벽이 귀하의 IP 주소를 일시적으로 차단했을 수 있습니다. [support@kapsulehost.com](mailto:support@kapsulehost.com)으로 고객 지원에 문의하여 방화벽 로그를 확인해 달라고 요청하세요.
- 네트워크의 로컬 방화벽이나 VPN이 포트 22의 아웃바운드 연결을 차단하고 있을 수 있습니다. 다른 네트워크(예: 모바일 핫스팟)에서 시도하여 이를 배제해 보세요.

---

## 관련 자료

- [사이트에 SSH 키 추가하기](https://support.kapsulehost.com/ko-kr/adding-ssh-keys)
- [KPanel 파일 관리자 사용하기](https://support.kapsulehost.com/ko-kr/file-manager)
- [SSH 터널로 데이터베이스에 연결하기](https://support.kapsulehost.com/ko-kr/database-ssh-tunnel)