# SSH 터널을 통해 데이터베이스에 연결하기

Source: https://support.kapsulehost.com/ko-kr/database-ssh-tunnel

서버의 데이터베이스는 서버 자체의 루프백 주소에서만 연결을 수신하므로, TablePlus, Sequel Ace, DBeaver, MySQL Workbench 같은 데스크톱 도구는 여기에 직접 접속할 수 없습니다. SSH 터널을 사용하면 이러한 도구에 데이터베이스로 전달되는 로컬 포트를 제공하므로, MySQL을 인터넷에 노출하지 않고도 데이터에 제대로 된 GUI로 접근할 수 있습니다.

## 터널이 필요한 이유

**웹사이트**를 열고 사이트를 클릭한 다음 **데이터베이스**를 클릭하세요. **연결 정보** 카드에는 호스트가 `127.0.0.1`로, 포트가 `3306`로 표시됩니다. 이것은 임시 값이 아닙니다. 데이터베이스는 실제로 자신이 실행되는 머신에서 오는 연결만 허용합니다. 공인 인터넷상의 어떤 것도 포트 3306에 접근할 수 없으며, 이는 공격의 한 범주 전체를 제거해줍니다.

SSH 터널은 이 틈을 안전하게 메워줍니다. SSH 클라이언트가 노트북에서 포트를 열고, 거기로 보내는 모든 데이터를 암호화한 다음, 마치 로컬 프로세스가 연결한 것처럼 서버 내부에서 데이터베이스로 전달합니다.

![KPanel에서 연결 정보를 보여주는 데이터베이스 탭](https://support.kapsulehost.com/help/screenshots/database-ssh-tunnel.84df4ba6.webp)

## 먼저 준비해야 할 것

> **Note:** 터널은 SSH 연결이므로, 이 모든 작업이 동작하려면 먼저 해당 사이트에 SSH 키가 등록되어 있어야 합니다. 먼저 [사이트에 SSH 키 추가하기](https://support.kapsulehost.com/ko-kr/adding-ssh-keys)를 따라 진행한 다음 이 문서로 돌아오세요.

다음 네 가지를 준비하세요.

- **SSH 호스트, 포트, 사용자 이름**: **설정**에서 **SSH 키**로 이동한 뒤 **연결 정보** 카드에서 확인합니다.
- **데이터베이스 이름, 사용자 이름, 비밀번호**: **데이터베이스**에서 확인합니다. 눈 모양 아이콘을 클릭해 비밀번호를 표시하고, 복사 아이콘을 클릭해 클립보드에 복사할 수 있습니다.

데이터베이스 탭에 **이 사이트 유형에는 프로비저닝된 데이터베이스가 없습니다**라고 표시되면, 해당 사이트에는 데이터베이스가 없는 것입니다. 정적 사이트와 일부 Node.js 사이트는 데이터베이스 없이 생성됩니다.

## 터미널에서 터널 열기

기본 형태는 로컬 포트를 SSH 연결 반대편(서버 쪽)의 `127.0.0.1:3306`으로 전달하는 것입니다.

```sh
ssh -N -L 3307:127.0.0.1:3306 <ssh-username>@<ssh-host> -p <ssh-port>
```

- `-L 3307:127.0.0.1:3306`은 사용자의 머신에서 포트 3307을 열고, 이를 서버의 루프백 인터페이스상의 포트 3306으로 전달합니다.
- `-N`는 셸을 실행하지 말고 터널만 열어두라는 의미입니다.
- 해당 사이트의 키가 기본 키가 아니라면 `-i /path/to/key`을 추가하세요.

해당 터미널 창은 계속 실행한 상태로 두세요. 창이 열려 있는 동안, 노트북에서의 `127.0.0.1:3307`은 곧 해당 사이트의 데이터베이스입니다.

> **Tip:** 로컬에서는 3306 대신 3307을 사용하세요. 본인 머신에 이미 MySQL이나 MariaDB가 설치되어 있다면 이미 3306 포트를 사용 중일 것이며, 이 경우 터널은 "address already in use" 오류와 함께 바인딩에 실패합니다. 비어 있는 로컬 포트라면 어떤 것이든 사용할 수 있습니다.

## 데이터베이스 클라이언트를 터널로 연결하기

GUI 클라이언트에서 다음 값으로 일반 MySQL 연결을 만드세요.

| 항목 | 값 |
|---|---|
| 호스트 | `127.0.0.1` |
| 포트 | `3307` (전달한 로컬 포트 번호) |
| 사용자 | 데이터베이스 탭의 **사용자 이름** |
| 비밀번호 | 데이터베이스 탭의 **비밀번호** |
| 데이터베이스 | 데이터베이스 탭의 **데이터베이스** 이름 |

호스트 필드에는 SSH 호스트를 입력하지 마세요. 클라이언트 입장에서는 본인 머신에 있는 데이터베이스와 통신하는 것으로 간주됩니다.

### 내장 SSH 탭이 있는 클라이언트

TablePlus, Sequel Ace, DBeaver, MySQL Workbench는 모두 터널을 자체적으로 관리할 수 있어, 터미널을 계속 열어둘 필요가 없습니다. 두 그룹의 항목을 입력하세요.

- **SSH 섹션**: SSH 키 페이지의 호스트, 포트, 사용자 이름, 개인 키 파일.
- **데이터베이스 섹션**: 호스트 `127.0.0.1`, 포트 `3306`, 그리고 데이터베이스 탭의 데이터베이스 이름, 사용자, 비밀번호.

클라이언트가 터널을 생성할 때는 로컬 전달 포트가 아니라 데이터베이스 섹션에서 `3306`을 사용하세요. 클라이언트는 서버 관점에서 연결하므로 실제 포트를 그대로 인식합니다.

## 대신 phpMyAdmin 사용하기

테이블을 잠깐 확인하기만 하면 된다면 굳이 터널이 필요하지 않습니다. 데이터베이스 탭에는 **phpMyAdmin** 카드와 **phpMyAdmin 열기** 버튼이 있습니다. 이는 KPanel을 통해 자동으로 로그인되므로 별도의 비밀번호를 기억할 필요가 없으며, 새 탭에서 이미 해당 사이트의 데이터베이스를 가리킨 상태로 열립니다.

phpMyAdmin은 데이터를 훑어보거나 일회성 쿼리를 실행하거나 값을 확인할 때 더 빠른 방법입니다. 대량 내보내기, 스키마 작업, 스크립트로 자동화하고 싶은 작업에는 터널을 이용한 데스크톱 클라이언트가 더 적합합니다. 브라우저 방식에 대해서는 [phpMyAdmin 사용하기](https://support.kapsulehost.com/ko-kr/sites-phpmyadmin)를 참고하세요.

## 터널을 통해 쿼리와 덤프 실행하기

터널이 열려 있는 상태에서는 표준 명령줄 도구들을 로컬 전달 포트로 지정해 평소처럼 사용할 수 있습니다.

```sh
mysql -h 127.0.0.1 -P 3307 -u <db-user> -p <db-name>

mysqldump -h 127.0.0.1 -P 3307 -u <db-user> -p <db-name> > backup.sql
```

> **Warning:** 수동 덤프는 백업 전략이 아니라 편의용 사본일 뿐입니다. 실행한 그 순간의 데이터만 담고 있으며, 실행한 노트북에만 저장됩니다. KapsuleHost는 이미 사이트에 대해 매일 자동 백업을 수행하며 30일간 보관합니다. 로컬 `.sql` 파일에 의존하기 전에 [백업하기](https://support.kapsulehost.com/ko-kr/taking-a-backup)를 확인하세요.

## 문제 해결

**터널을 열 때 "Address already in use" 오류가 발생하는 경우.** 본인 머신에서 이미 해당 로컬 포트를 사용 중입니다. 다른 포트, 예를 들어 `-L 3399:127.0.0.1:3306`을 선택하고 클라이언트의 포트 설정도 이에 맞춰 변경하세요.

**데이터베이스 클라이언트에서 "Connection refused"가 발생하는 경우.** 터널이 열려 있지 않은 상태입니다. SSH 터미널이 여전히 실행 중이고 오류가 출력되지 않았는지 확인하고, 클라이언트의 포트가 `-L` 인자의 로컬 포트와 일치하는지 확인하세요.

**SSH는 연결되지만 클라이언트가 계속 시간 초과되는 경우.** 공개 호스트 이름이 아니라 `127.0.0.1:3306`으로 전달했는지 확인하세요. 공개 이름으로 전달하면 서버에 인터넷을 통해 데이터베이스에 접근하라고 요청하는 것이 되는데, 이는 정확히 차단되어 있는 방식입니다.

**"Access denied for user" 오류가 발생하는 경우.** SSH 로그인은 성공했지만 MySQL 자격 증명이 잘못된 것입니다. 사용자 이름과 비밀번호를 직접 입력하지 말고 데이터베이스 탭의 복사 아이콘을 이용해 다시 복사하고, 올바른 데이터베이스 이름에 연결하고 있는지 확인하세요.

**MySQL에 도달하기도 전에 "Permission denied (publickey)" 오류가 발생하는 경우.** 이는 데이터베이스 계층이 아니라 SSH 계층의 문제입니다. [사이트에 SSH 키 추가하기](https://support.kapsulehost.com/ko-kr/adding-ssh-keys)의 문제 해결 섹션을 참고해 진행하세요.

## 다음으로 볼 만한 문서

- [SFTP로 파일 업로드하기](https://support.kapsulehost.com/ko-kr/sftp-access)는 파일 전송에 동일한 SSH 자격 증명을 사용합니다.
- [phpMyAdmin 사용하기](https://support.kapsulehost.com/ko-kr/sites-phpmyadmin): 브라우저 기반 데이터베이스 작업용입니다.
- [백업에서 복원하기](https://support.kapsulehost.com/ko-kr/restoring-from-backup): 쿼리가 의도한 것보다 더 많은 영향을 끼쳤을 때 참고하세요.