연결 문제

서버 연결 문제 해결 가이드입니다.

서버 상태가 연결되지 않음으로 표시될 때

서버 상태가 여러 이유로 연결되지 않음으로 표시될 수 있습니다. 아래 시나리오를 확인하여 직접 해결해 보세요. 오프라인 알림은 연결이 끊긴 지 5분 정도 지나면 발생하지만, Alpacon을 통해 시작한 작업으로 인한 중단이거나 해당 서버의 알림을 꺼 둔 경우에는 발생하지 않습니다. 자세한 내용은 오프라인 알림을 참고하세요.

1. 서버가 꺼져 있거나 종료된 경우

서버가 중지되면 Alpacon은 연결을 유지할 수 없습니다.

해결 방법:

  1. 서버 전원 및 부팅 상태 확인
  2. 서버가 실행되면 Alpamon 에이전트가 자동으로 재연결될 때까지 잠시 대기
  3. 상태가 계속 연결되지 않음으로 표시되면 에이전트 상태 확인

2. Alpacon과의 네트워크 연결이 끊긴 경우

Alpamon 에이전트는 아웃바운드 HTTPS/WSS로 Alpacon에 연결됩니다. 서버의 네트워크가 이를 차단하거나 네트워크가 다운되면 상태가 연결되지 않음으로 표시됩니다.

해결 방법:

  1. 서버 아웃바운드 인터넷 접속 확인 (예: curl -I https://alpacon.io 또는 워크스페이스 엔드포인트)
  2. 방화벽 또는 프록시의 아웃바운드 HTTPS (443) 및 WSS 허용 확인 (네트워크 요구사항 참조)
  3. 서버가 프록시를 거쳐 Alpacon에 연결하는 경우 에이전트 서비스에 프록시 설정 (프록시 지원 참조)
  4. 네트워크 또는 방화벽 수정 후 에이전트 재연결 대기, 연결되지 않으면 에이전트 재시작 또는 CLI 에이전트 재시작

3. 에이전트가 설치되지 않았거나 실행 중이 아닌 경우

에이전트가 설치되지 않았거나 제거되었거나 에이전트 프로세스가 실행 중이 아니면 서버가 연결되지 않음으로 표시됩니다.

해결 방법:

  1. 서버에서 Alpamon 에이전트가 설치되어 실행 중인지 확인 (Linux는 systemctl status alpamon, Windows는 sc.exe query alpamon)
  2. 설치되지 않은 경우 서버 연결의 설치 스크립트 또는 안내를 따라 설치
  3. 설치되었지만 실행 중이 아닌 경우 에이전트 시작 또는 재시작 (Linux는 systemctl start alpamon / systemctl restart alpamon, Windows는 Restart-Service alpamon). 자세한 명령어는 서버 등록 참조
  4. 에이전트 관련 문제는 에이전트 문제 참조

4. Alpacon에 서비스 장애가 발생한 경우

Alpacon에 서비스 장애가 발생하면 서버가 계속 실행 중이어도 연결되지 않음으로 표시될 수 있습니다. 장애가 해결되면 에이전트가 스스로 다시 연결됩니다.

해결 방법:

  1. Alpacon 서비스 상태에서 진행 중인 서비스 장애 확인
  2. 장애가 해결되기 전에 서버에 접속해야 하면 따로 남겨 둔 비상용 접근 경로 사용(비상용으로 제한한 SSH 계정 또는 클라우드 콘솔). External access 탐지가 켜져 있고 서버가 탐지 가능한 상태이면 이런 직접 로그인도 기록되어 External access에서 검토 가능(연결이 끊긴 동안의 로그인은 Alpamon 2.8.2 이상이 보관했다가 다시 연결되면 전송)

Websh에 연결할 수 없을 때

연결 버튼을 사용할 수 없는 경우

Websh는 작업 세션에서 엽니다. 서버의 연결 버튼은 그 서버로 세션 요청을 시작하며, 서버가 커미션되어 Alpacon에 연결됨 상태일 때만 사용할 수 있습니다.

해결 방법:

Websh 세션 중 터미널이 닫히는 경우

터미널의 종료 안내에서 원인을 확인할 수 있습니다. 안내별 원인과 해결 방법은 세션 종료 사유를, 세션 유지 시간의 계산 기준은 사용 제한을 참고하세요.

해결 방법:

  • 종료 안내를 읽고 해당하는 해결 방법을 따르세요.
  • 작업 세션이 활성 상태이고 서버가 연결됨 상태이면 세션의 세션 탭에서 해당 서버의 터미널을 다시 클릭하세요. 그렇지 않으면 다른 세션을 요청하세요.

Websh 세션 시작에 실패할 때

Websh 세션을 열려고 할 때 오류 메시지가 표시되면, 서버 상태나 계정 설정에 따라 원인이 다릅니다. 아래에서 일반적인 시나리오와 해결 방법을 확인하세요.

서버가 아직 커미션되지 않은 경우

서버가 Alpacon에 등록되었지만 초기 설정이 완료되지 않았습니다.

server_not_commissioned 오류 메시지를 확인하세요.

해결 방법:

  1. 서버 상세 페이지에서 서버 상태가 에이전트 미설치로 표시되는지 확인
  2. 서버 연결의 안내를 참조하여 서버 설치 단계 완료
  3. 서버가 커미션되면 Websh 연결 재시도

서버가 연결되지 않은 경우

서버가 이전에 연결되었지만 현재 오프라인이거나 접근할 수 없는 상태입니다.

server_not_connected 오류 메시지를 확인하세요.

해결 방법:

직접 root 접속이 비활성화된 경우

root 사용자로 연결하려 했지만, 워크스페이스 보안 정책에서 직접 root 접속을 허용하지 않습니다.

workspace_direct_root_disabled 오류 메시지를 확인하세요.

해결 방법:

  • 워크스페이스 관리자에게 접근 규칙에서 root 직접 로그인을 켜 달라고 요청
  • 또는 본인 계정으로 연결한 후 sudo를 사용하여 권한이 필요한 명령어 실행

계정이 존재하지 않거나 권한이 없는 경우

서버에 등록되지 않은 사용자명 또는 그룹으로 연결하려 했거나, 해당 계정을 사용할 권한이 없습니다.

server_username_groupname_invalid 오류 메시지를 확인하세요.

이런 경우에 발생할 수 있습니다:

  • 서버에 계정이 아직 프로비저닝되지 않은 경우
  • 적절한 접근 권한 없이 다른 사용자의 계정으로 접속하려는 경우
  • 소속 그룹이 해당 서버에 할당되지 않은 경우

해결 방법:

  1. 서버 상세 페이지의 접근 탭에서 본인 계정이 목록에 있는지 확인
  2. 계정이 목록에 없으면 워크스페이스 관리자에게 해당 서버에 적절한 그룹을 할당하거나 계정을 프로비저닝하도록 요청
  3. 본인 계정이 아닌 계정을 사용하려는 경우 그 계정을 쓸 수 있는지 확인하세요. Staff, Superuser, 그룹 Manager/Owner, 서버의 maintainer만 쓸 수 있습니다

시스템 사용자 UID 충돌

Alpacon 계정의 UID가 서버의 기존 시스템 사용자와 충돌합니다. 이로 인해 Alpacon이 계정을 안전하게 프로비저닝할 수 없습니다.

system_uid_conflict 오류 메시지를 확인하세요.

해결 방법:

  1. 서버 상세 페이지 > 접근 탭에서 충돌 태그가 표시된 계정 확인
  2. 충돌을 해결하려면 워크스페이스 관리자가 다음 중 하나를 수행해야 합니다:
    • 서버에서 충돌하는 시스템 사용자의 UID 변경
    • IAM 사용자 설정에서 Alpacon 계정의 UID 조정
  3. 충돌이 해결된 후 Websh 연결 재시도

시스템 사용자 로그인이 비활성화되었거나 계정이 만료된 경우

서버에 계정이 존재하지만 로그인 접근이 비활성화되었거나 계정 만료일이 지났습니다.

system_user_access_denied 오류 메시지를 확인하세요.

해결 방법:

  1. 워크스페이스 관리자 또는 서버 관리자에게 시스템 사용자 계정이 비활성화되었거나 만료되었는지 확인
  2. 서버에서 직접 계정 상태 확인:
    • 로그인 셸이 유효한 셸로 설정되어 있는지 확인 (/usr/sbin/nologin 또는 /bin/false가 아닌지)
    • 계정 만료일이 지나지 않았는지 확인 (chage -l <username>으로 확인)
  3. 계정이 다시 활성화되거나 만료일이 업데이트된 후 Websh 연결 재시도
최종 수정: