사이트에 SSH 키 추가하기

SSH access to a Kapsule site is key-based only, so before you can open a shell or an SFTP session you need to register a public key against the site in KPanel. This guide covers where that lives…

SSH 키를 사이트에 추가하기

Kapsule 사이트의 SSH 접근은 키 기반만 가능하므로, 셸이나 SFTP 세션을 열기 전에 KPanel에서 공개 키를 해당 사이트에 등록해야 합니다. 이 가이드는 그 위치, 이미 보유한 키를 추가하는 방법, Kapsule이 키를 생성하게 하는 방법, 그리고 더 이상 신뢰하지 않는 키를 취소하는 방법을 다룹니다.

SSH 키 페이지의 위치

Websites를 열고, 사이트를 클릭한 후 사이트 탭 스트립의 Files 메뉴를 열고 SSH Keys를 선택합니다. 이 페이지의 제목은 SSH access이며 두 가지를 포함합니다: 이 사이트의 연결 세부정보와 현재 사용할 수 있도록 승인된 공개 키 목록입니다.

메인 사이드바에는 최상위 SSH 항목이 없습니다. 키는 사이트 단위이므로 여기에 추가한 키는 이 사이트에만 인증됩니다. 여러 사이트를 운영하는 경우, 노트북의 동일한 키라도 각 사이트마다 자체 항목이 필요합니다.

KPanel의 사이트에 대한 SSH 접근 페이지

키를 추가하거나 취소하려면 sites:write 권한이 필요합니다. 읽기 전용 역할의 팀 계정인 경우 Add key 버튼과 취소 아이콘이 숨겨집니다. 계정 소유자나 관리자에게 변경을 요청하세요.

연결 세부정보

페이지 맨 위의 Connection details 카드는 클라이언트가 필요한 모든 정보를 표시합니다:

필드	설명
Host	연결할 호스트명
Port	이 사이트의 SSH 포트
Username	사이트가 실행되는 시스템 사용자
SSH	이 사이트용 미리 만들어진 `ssh` 명령어
SFTP	이 사이트용 미리 만들어진 `sftp` 명령어

각 행에는 복사 컨트롤이 있으며, SSH 및 SFTP 행은 값뿐만 아니라 전체 명령어를 복사하므로 터미널에 직접 붙여넣을 수 있습니다. 명령어를 직접 입력하는 대신 이 두 행을 사용하세요: 이미 올바른 사용자, 호스트 및 포트가 포함되어 있습니다.

카드가 전혀 나타나지 않으면 사이트가 아직 셸 사용자를 프로비전하지 않은 것입니다. 이 경우 API는 일반 Site has no SSH user 오류를 반환합니다. 사이트 상태 표시기가 Active로 읽을 때까지 기다린 후 다시 로드하세요.

이미 보유한 키 추가하기

대부분의 사용자는 이미 자신의 컴퓨터에 키 쌍을 가지고 있습니다. 공개 부분을 여기에 추가하세요.

자신의 컴퓨터에서 공개 키를 출력합니다. macOS 및 Linux에서는 일반적으로 cat ~/.ssh/id_ed25519.pub이고, 이전 RSA 키의 경우 cat ~/.ssh/id_rsa.pub입니다. OpenSSH가 있는 Windows에서는 type %USERPROFILE%\.ssh\id_ed25519.pub입니다.
ssh-ed25519, ssh-rsa 또는 ecdsa-sha2-nistp256으로 시작하는 전체 한 줄을 복사합니다.
KPanel에서 Add key를 클릭합니다.
Label 필드에 기억할 만한 내용을 입력합니다. 예를 들어 키가 있는 컴퓨터의 이름입니다.
공개 키를 두 번째 필드에 붙여넣습니다.
Add key를 클릭합니다.

키는 Authorised keys 목록에 즉시 나타나며, 라벨 아래에 지문이 표시됩니다. 즉시 연결할 수 있습니다.

Kapsule은 또한 키가 추가될 때마다 계정 주소로 이메일을 보내며, 라벨, 지문 및 사이트를 인용합니다. 이 메일은 의도된 것입니다: SSH 접근은 높은 신뢰도이므로, 추가하지 않은 키가 나타나면 즉시 취소하고 비밀번호를 변경하세요.

.pub 파일만 붙여넣으세요. 개인 키 파일에는 .pub 확장자가 없으며 -----BEGIN OPENSSH PRIVATE KEY----- 같은 줄로 시작합니다. 그것을 붙여넣으면 개인 키이며, 재사용하지 않고 재생성해야 합니다.

아직 키가 없는 경우

ssh-keygen -t ed25519 -C "your-label"으로 로컬에서 키를 생성하고, 기본 파일 위치를 허용한 후 메시지가 나타날 때 암호를 설정합니다. 그러면 ~/.ssh/id_ed25519(비공개로 유지)과 ~/.ssh/id_ed25519.pub(그것을 붙여넣음)이 생성됩니다.

Kapsule이 키 쌍을 생성하게 하기

ssh-keygen을 실행하고 싶지 않으면 KPanel이 쌍을 만들 수 있습니다.

Add key를 클릭합니다.
Label 필드를 채웁니다. 공개 키 상자는 비워둡니다.
Generate keypair를 클릭합니다.

Kapsule은 Ed25519 쌍을 만들고, 공개 부분을 사이트에 설치하고, 녹색 배너를 표시합니다: Keypair generated: download the private key now. Download .pem을 클릭하여 개인 키를 저장합니다. 파일의 이름은 선택한 라벨에 따라 지정됩니다.

개인 키는 한 번, 정확히 한 번만 표시됩니다. 배너는 명확하게 나타냅니다: 이것이 유일하게 다운로드할 수 있는 시간입니다. Kapsule은 나중에 가져올 수 있는 복사본을 보관하지 않습니다. 배너를 다운로드하지 않고 닫으면 키를 취소하고 새 쌍을 생성합니다.

생성된 키에는 암호가 없으므로 스크립트에서 프롬프트 없이 사용할 수 있습니다. 이는 또한 파일 자체가 전체 자격증명을 의미합니다. 암호를 원하면 ssh-keygen로 쌍을 직접 생성하고 공개 부분을 붙여넣으세요.

다운로드한 후 파일을 적절한 위치로 이동하고 SSH가 전 세계에서 읽을 수 있는 개인 키 사용을 거부하므로 권한을 강화하세요:

mv ~/Downloads/my-laptop_id_ed25519.pem ~/.ssh/kapsule-mysite.pem
chmod 600 ~/.ssh/kapsule-mysite.pem
ssh -i ~/.ssh/kapsule-mysite.pem <username>@<host> -p <port>

Connection details 카드에서 사용자명, 호스트 및 포트를 대체합니다.

승인된 키 목록 읽기

Authorised keys의 각 행은 다음을 표시합니다:

키에 지정한 라벨입니다.
라벨이 유사할 때 두 키를 구분하는 방법인 키 지문입니다.
등록된 날짜와 함께 Added합니다.
가장 최근 인증의 날짜와 함께 Last used하거나, 아직 인증하지 않은 경우 Never used입니다.

Last used 열은 정리 중에 유용합니다. 사용된 적이 없거나 몇 달간 사용되지 않은 키는 보통 교체된 노트북이나 이동한 계약자입니다.

키 취소하기

키 행의 빨간 휴지통 아이콘을 클릭합니다. KPanel은 **Revoke SSH key?**로 확인을 요청하고 키가 더 이상 이 사이트에 인증되지 않을 것이라는 메모가 표시됩니다. Revoke를 클릭하여 완료합니다.

취소는 새 연결에 즉시 적용됩니다. 이미 열려 있는 SSH 세션은 키를 취소해도 종료되지 않으므로, 여전히 연결되어 있을 수 있는 사람에게서 접근 권한을 제거하는 경우 키를 취소한 후 그들이 가져갈 수 있는 모든 항목을 변경하세요: 데이터베이스 비밀번호, 애플리케이션 비밀 및 사이트에 저장된 모든 토큰입니다.

키 목록을 짧게 유지하세요. 컴퓨터 이름으로 라벨이 지정된 컴퓨터당 하나의 키는 "key1", "new key" 및 "temp"라고 불리는 키 더미보다 감사하기가 훨씬 쉽습니다.

문제 해결

Permission denied (publickey). 가장 일반적인 원인은 클라이언트가 등록한 것과 다른 키를 제공하는 것입니다. ssh -i /path/to/private_key ...로 올바른 키를 강제하거나, ssh -v으로 어떤 키가 제공되고 있는지 확인합니다.

Connection refused 또는 시간 초과. Connection details에 표시된 포트를 사용 중이고 기본 22가 아님을 확인하세요. 페이지에서 SSH 명령어를 복사하여 입력하지 마세요.

개인 키의 권한 안 좋음. OpenSSH는 다른 사용자가 읽을 수 있는 개인 키를 거부합니다. 파일에서 chmod 600을 실행합니다.

키는 SSH에서 작동하지만 SFTP에서는 작동하지 않음. 동일한 자격증명을 공유하므로 이것은 거의 항상 키가 아닌 클라이언트입니다. 페이지에서 복사한 SFTP 명령어를 사용하세요. 이미 올바른 포트가 포함되어 있습니다.

다음으로 이동할 위치

SFTP로 파일 업로드는 동일한 자격증명의 파일 전송 부분을 다룹니다.
SSH 터널을 통해 데이터베이스에 연결은 방금 추가한 키를 사용하여 데스크톱 클라이언트에서 MySQL에 도달합니다.
사이트 활동 로그는 추가한 모든 키를 기록하므로 나중에 누가 무엇을 추가했는지 언제인지 확인할 수 있습니다.