---
title: "연결 문제"
description: "작업 세션에서 서버 연결이 실패하거나 끊겼을 때 원인을 확인하세요. 서버 연결 상태, 계정 권한, 세션의 기능 범위, 네트워크 설정을 순서대로 점검합니다. 문제에 맞는 복구 절차를 따라 다시 연결하고, 세션이 끝난 경우 새 세션을 요청할 때 확인할 사항까지 안내합니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# 연결 문제

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

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

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

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

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

**해결 방법:**

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

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

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

**해결 방법:**

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

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

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

**해결 방법:**

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

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

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

**해결 방법:**

1. [Alpacon 서비스 상태](https://status.alpacax.com)에서 진행 중인 서비스 장애 확인
2. 장애가 해결되기 전에 서버에 접속해야 하면 따로 남겨 둔 [비상용 접근](/learn/faq/#alpacon이-다운되면-어떻게-되나요) 경로 사용([비상용으로 제한한 SSH 계정](/use/servers/configure-network/#ssh에서-alpacon으로-전환) 또는 클라우드 콘솔). External access 탐지가 켜져 있고 서버가 [탐지 가능한 상태](/use/audit/governance/external-access/coverage/)이면 이런 직접 로그인도 기록되어 [External access](/use/audit/governance/external-access/)에서 검토 가능(연결이 끊긴 동안의 로그인은 Alpamon 2.8.2 이상이 보관했다가 다시 연결되면 전송)

## Websh에 연결할 수 없을 때

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

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

**해결 방법:**

- 위의 [서버 상태가 연결되지 않음으로 표시될 때](#서버-상태가-연결되지-않음으로-표시될-때)를 참조하여 서버 상태 확인
- 서버 상태가 **연결됨**으로 바뀌면 **연결** 버튼을 눌러 웹 터미널을 포함한 세션을 요청합니다. 세션이 활성화되면 **세션** 탭에서 해당 서버의 **터미널**을 클릭합니다. [세션 사용하기](/use/work-sessions/detail/#브라우저에서-기능-실행하기)를 참고하세요

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

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

**해결 방법:**

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

## Websh 세션 시작에 실패할 때

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

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

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

[server_not_commissioned 오류 메시지](/reference/error-messages/#server_not_commissioned)를 확인하세요.

**해결 방법:**

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

### 서버가 연결되지 않은 경우

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

[server_not_connected 오류 메시지](/reference/error-messages/#server_not_connected)를 확인하세요.

**해결 방법:**

- 위의 [서버 상태가 연결되지 않음으로 표시될 때](#서버-상태가-연결되지-않음으로-표시될-때)를 참조하여 연결 문제를 진단하고 해결
- 서버가 **연결됨** 상태로 표시된 후 Websh 연결 재시도

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

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

[workspace_direct_root_disabled 오류 메시지](/reference/error-messages/#workspace_direct_root_disabled)를 확인하세요.

**해결 방법:**

- 워크스페이스 관리자에게 [접근 규칙](/use/policies/server-access/)에서 **root 직접 로그인**을 켜 달라고 요청
- 또는 본인 계정으로 연결한 후 `sudo`를 사용하여 권한이 필요한 명령어 실행

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

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

[server_username_groupname_invalid 오류 메시지](/reference/error-messages/#server_username_groupname_invalid)를 확인하세요.

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

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

**해결 방법:**

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

### 시스템 사용자 UID 충돌

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

[system_uid_conflict 오류 메시지](/reference/error-messages/#system_uid_conflict)를 확인하세요.

**해결 방법:**

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

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

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

[system_user_access_denied 오류 메시지](/reference/error-messages/#system_user_access_denied)를 확인하세요.

**해결 방법:**

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

Source: https://docs.alpacax.com/ko/use/work-sessions/troubleshoot-connections/