---
title: "에이전트 문제"
description: "Alpamon 에이전트가 설치되지 않거나 서버에 연결되지 않을 때 원인을 확인하세요. 업그레이드가 멈춘 경우에도 서비스 상태, 로그, 운영체제 권한을 점검할 수 있습니다. 각 증상에 맞는 복구 절차와 다시 시도하기 전에 확인할 설치 조건, 관리자에게 전달할 정보까지 안내합니다."
---

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

# 에이전트 문제

Alpamon 에이전트 관련 문제 해결 가이드입니다.

## 에이전트 설치 실패

**서버 OS 계열을 잘못 선택한 경우**

에이전트 설치 시 서버의 OS 계열을 잘못 선택하면 설치가 실패할 수 있습니다.

Alpacon이 만드는 설치 명령은 선택한 OS 계열에 따라 달라집니다. 그래서 OS 계열을 잘못 고르면 설치에 실패합니다. 생성된 명령을 그대로 쓸 때도, 수동으로 설치할 때도 마찬가지입니다.

**해결 방법:**

1. 서버의 실제 OS 계열 확인:

   - **Debian 계열**: Ubuntu, Debian 등
   - **Red Hat 계열**: RHEL, CentOS, Fedora, Amazon/Rocky/Oracle Linux 등
   - **SUSE 계열**: openSUSE, SLES
   - **macOS**: macOS 11 이상
   - **Windows**: Windows Server 2019 / 2022 / 2025, Windows 10 1803+, Windows 11

2. [서버 등록](/use/servers/register/) 페이지에서 서버 등록 시 올바른 OS 계열 선택. openSUSE나 SLES라면 **SUSE 계열**을 고르세요. Red Hat 계열 명령은 이 서버에서 실패합니다.

3. 수동 설치 스크립트 사용 시, 선택한 OS 계열에 맞는 스크립트로 에이전트를 설치:

   - Debian 계열: `apt-get install -y alpamon` 명령이 포함된 스크립트
   - Red Hat 계열: `yum install -y alpamon` 명령이 포함된 스크립트
   - SUSE 계열: `zypper --non-interactive install alpamon` 명령이 포함된 스크립트
   - macOS: `brew install alpamon` 명령이 포함된 스크립트
   - Windows: `alpamon.exe register`를 실행하는 PowerShell 스크립트

4. 잘못된 OS 계열로 서버를 등록한 경우 서버를 삭제한 후 올바른 OS 계열로 재등록

**워크스페이스를 이전한 경우**

다른 워크스페이스에서 사용하던 서버를 에이전트 삭제 과정 없이 신규 워크스페이스에 등록한 경우, 에이전트는 기존 워크스페이스에 계속 연동된 상태로 동작할 수 있습니다. 이 경우 신규 워크스페이스에서는 서버 연결이 불가능합니다.

**해결 방법:**

1. 기존 워크스페이스에서 **에이전트 자동 삭제** 선택 후 서버 삭제 (기존 에이전트 서버에서 제거)

2. 기존 워크스페이스 접근 불가 시 [서버 제거하기](/use/servers/remove/) 참고하여 수동 에이전트 삭제

3. 신규 워크스페이스에서 [서버 등록](/use/servers/register/) 및 에이전트 설치 새로 수행

## 재등록 및 복구

등록이 막혔거나 중간에 실패한 호스트를 복구하는 명령입니다. Websh가 아닌 서버에서 직접(로컬 콘솔, RDP, 클라우드 시리얼 콘솔), 그리고 **alpamon v2.3.0 이상**에서 실행하세요. 구버전 에이전트에는 `register --force`와 `unregister`가 없으므로(일반 `alpamon register`는 그대로 사용 가능), 에이전트를 수동으로 제거하고 **Servers** 페이지에서 서버를 삭제한 뒤 다시 등록하세요.

**`alpamon register`가 `config file already exists`에서 멈춤**

이미 등록된 호스트라서 `alpamon register`가 재등록을 거부합니다. `alpamon register --force`로 한 번에 재등록하세요. 새로 등록한 뒤 새 등록이 성공하면 이전 등록을 회수합니다. 또는 `alpamon unregister`를 먼저 실행한 뒤 `alpamon register`를 실행해도 됩니다.

**등록이 중간에 실패함**

등록이 일부 상태를 만든 뒤 실패하면 호스트가 반쯤 등록된 상태로 남을 수 있습니다. `alpamon register --force`로 깨끗이 재등록하면 남은 등록이 회수됩니다.

**원인 분석을 위해 상태 보존**

기본적으로 `alpamon register`는 실패하면 그 실행에서 만든 상태를 롤백합니다. 문제 분석을 위해 부분 상태를 남기려면 `--no-rollback`을 추가하세요(예: `alpamon register --force --no-rollback`). 디버그 전용이며 부분 상태를 남깁니다.

## Windows 에이전트 문제

**서비스가 시작되지 않음**

`alpamon` Windows 서비스가 시작되지 않으면 먼저 서비스 상태와 에이전트 로그를 확인하세요.

```powershell
sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 100
```

에이전트 로그에 나타나지 않는 Service Control Manager 수준 오류(예: 바이너리 누락 또는 읽기 불가)는 **이벤트 뷰어**의 **Windows 로그** → **시스템**에서 `Service Control Manager` 항목을, **응용 프로그램 및 서비스 로그**에서 `alpamon` 항목을 확인하세요.

**`alpamon register` 또는 서비스 작업 시 접근 거부**

`alpamon register`와 서비스 제어 명령(`sc.exe`, `Restart-Service`)은 모두 관리자 권한이 필요합니다. 관리자 권한 PowerShell(관리자 권한으로 실행)에서 다시 실행하세요. `alpamon register`는 `C:\Program Files\alpamon\`에 바이너리를 복사할 수 없을 때 권한 상승 안내를 출력합니다.

재설치 중 `ERROR_SHARING_VIOLATION`이 표시되면 실행 중인 서비스가 기존 `alpamon.exe`를 점유하고 있는 경우입니다. 먼저 서비스를 중지하고 다시 시도하세요:

```powershell
sc.exe stop alpamon
.\alpamon.exe register --url https://your-workspace.ap1.alpacon.io --token YOUR_REGISTRATION_TOKEN
```

등록 자체가 막혔거나 중간에 실패했다면 [재등록 및 복구](#재등록-및-복구)를 참고하세요.

**Websh에서 `PowerShell error 8009001d` 발생**

초기 Windows 빌드에서 발생하던 TLS 관련 Websh 핸드셰이크 오류로, 이후 Alpamon 릴리스에서 수정되었습니다. [에이전트를 최신 릴리스로 업그레이드](/use/servers/register/install/#에이전트-업그레이드)한 뒤 다시 시도하세요.

**Windows에서 WebFTP가 사용자 홈을 넘어 `C:\Windows\System32\...` 등도 표시됨**

의도된 동작입니다. Windows의 WebFTP는 특정 사용자 홈 디렉터리로 제한되지 않으며, 에이전트가 접근할 수 있는 호스트의 모든 경로를 탐색하고 읽고 쓸 수 있습니다(`C:\Windows\System32` 같은 시스템 디렉터리 포함). 접근 범위는 서버의 사용자별 홈 경계가 아니라 Alpacon 역할 및 권한과 연결 허용 사용자 목록으로 제어됩니다. WebFTP 접근 권한은 신중하게 부여하고, 민감한 위치에 접근할 수 있는 사용자는 Alpacon 역할로 제한하세요. 접근 제어 방식은 [WebFTP 권한](/use/work-sessions/files/permissions/)을 참고하세요.

## macOS 에이전트 문제

**서비스가 시작되지 않음**

launchd 서비스 상태와 에이전트 로그를 확인하세요:

```bash
sudo launchctl print system/com.alpacax.alpamon
tail -n 100 /var/log/alpamon/alpamon.log
```

launchd 수준의 오류(예: 실행 파일을 찾을 수 없거나 plist가 유효하지 않은 경우)는 **Console.app**에서 `com.alpacax.alpamon`으로 필터링하면 launchd 자체 오류 메시지를 확인할 수 있습니다.

**서비스 재시작**

```bash
sudo launchctl kickstart -k system/com.alpacax.alpamon
```

**에이전트가 보호된 디렉터리를 읽을 수 없음**

macOS는 시스템 보호 경로(메일, 메시지, Time Machine, 일부 `~/Library` 등)에 접근하는 프로세스에 대해 Full Disk Access를 요구합니다. 에이전트가 해당 위치를 읽을 때 권한 오류를 보고하면 **시스템 설정** → **개인정보 보호 및 보안** → **전체 디스크 접근 권한**에서 `alpamon` 바이너리에 권한을 부여한 뒤 서비스를 재시작하세요.

바이너리 위치는 Mac 종류에 따라 다릅니다:

- Apple Silicon: `/opt/homebrew/bin/alpamon`
- Intel: `/usr/local/bin/alpamon`

## 에이전트 업그레이드 문제

Alpacon은 두 가지 방법으로 Alpamon 에이전트를 최신 상태로 유지합니다.

- **자동**: [에이전트 업데이트](/use/workspace/settings/agent-updates/)의 업데이트 정책이 **최신 버전**(기본값)이면, 등록된 에이전트가 워크스페이스의 유지보수 시간대 안에서 새 릴리스로 알아서 업그레이드됩니다.
- **수동**: 특정 서버의 [에이전트 카드](/use/servers/manage/#에이전트-카드)에서 **에이전트 업그레이드**(**수동** 정책에서 표시)를 누르거나, CLI에서 [`alpacon agent upgrade SERVER`](/reference/cli/agent/upgrade/)로 업그레이드한 뒤 `alpacon exec ls`로 진행 상황을 확인합니다.

업그레이드 중에는 에이전트가 새 버전을 받아 적용한 뒤 자동으로 재시작합니다. 서버가 잠깐 **오프라인**으로 표시됐다가 다시 연결될 수 있습니다. 업데이트를 적용하지 못하면 에이전트는 이전 버전을 그대로 유지합니다. 업데이트 전달 방식은 플랫폼에 따라 다릅니다.

- **Linux**(Debian/Ubuntu, RHEL/CentOS, openSUSE/SLES): 시스템 패키지 매니저(`apt`, `yum`, `zypper`)로 Alpacon 패키지 저장소에서 받습니다.
- **macOS**와 **Windows**: GitHub Releases에서 내려받습니다.

**업그레이드가 시작되지 않을 때**

- 이미 업그레이드가 진행 중이라면 [`server_agent_upgrade_in_progress`](/reference/error-messages/#server_agent_upgrade_in_progress), 현재 릴리스가 설치되어 있다면 [`server_agent_upgrade_not_needed`](/reference/error-messages/#server_agent_upgrade_not_needed) 오류 메시지를 확인하세요.
- 서버가 **온라인**인지 확인하세요. 오프라인 상태의 에이전트는 업그레이드 요청을 받을 수 없습니다.
- `alpacon agent upgrade SERVER`를 실행하고 `alpacon exec ls`로 결과를 확인하세요.
- 자동 업그레이드를 사용한다면 **에이전트 업데이트**의 업데이트 정책이 **수동**이 아닌 **최신 버전**인지, 유지보수 시간대가 어떻게 설정되어 있는지 확인하세요. 자동 업그레이드는 이 시간대 안에서만 시작되며, 시간대를 바꾸면 다음 월요일 일정부터 반영됩니다.
- 서버의 [업그레이드 이력](/use/servers/manage/#업그레이드-이력)을 확인하세요. **거부됨** 행은 업그레이드가 에이전트에 도달하기 전에 철회되었다는 뜻입니다.

**업그레이드가 실패하거나 버전이 그대로일 때**

- **연결 확인**: 모든 플랫폼은 `api.github.com`에서 최신 버전을 확인하므로, 서버가 `api.github.com`으로의 아웃바운드 HTTPS를 허용해야 합니다. **Linux**에서는 이후 `apt`, `yum`, `zypper`로 업그레이드하므로, 서버가 Alpacon 패키지 저장소에 직접 또는 워크스페이스 **패키지 프록시** 설정을 통해 접근할 수 있어야 합니다. SLES는 구독이 만료됐거나 비활성이어도 패키지 매니저가 실패하니 `SUSEConnect --status`로 확인하세요. **macOS**와 **Windows**에서는 에이전트가 `github.com`과 `release-assets.githubusercontent.com`에서 릴리스를 직접 내려받습니다.
- 에이전트 로그에서 원인을 확인한 뒤 업그레이드를 다시 시도하세요.
  - Linux: `sudo journalctl -u alpamon -n 100`
  - macOS: `tail -n 100 /var/log/alpamon/alpamon.log`
  - Windows: `Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 100`
- 서버의 [업그레이드 이력](/use/servers/manage/#업그레이드-이력)에서 시도마다 결과를 확인할 수 있으며, 실패하거나 롤백된 시도는 사유도 함께 표시됩니다. **Alpacon 설정 문제로 조치할 필요 없어요**는 Alpacon 쪽 문제이므로 서버에서 바꿀 것은 없습니다.
- **2.4.0보다 오래된 Windows 에이전트**: 업그레이드 이력에 **지원하지 않는 플랫폼**으로 실패가 남고, 에이전트가 다른 버전을 보고하기 전까지 Alpacon은 새 업그레이드를 예약하지 않습니다. 바이너리를 한 번 직접 교체하세요([에이전트 업그레이드](/use/servers/register/install/#에이전트-업그레이드) 참고).
- 업그레이드가 실패하면 에이전트는 이전 버전을 그대로 유지합니다. 원인(대개 네트워크나 패키지 저장소 접근)을 해결한 뒤 다시 시도하세요.

**현재 버전 확인**

서버 상세 페이지에서 실행 중인 에이전트 버전을 확인할 수 있습니다. 언제든 업그레이드를 다시 실행해도 되며, 에이전트가 이미 최신 릴리스이면 아무것도 바뀌지 않습니다. 이때 에이전트 카드의 **에이전트 업그레이드** 버튼은 비활성화되고 **에이전트가 최신이에요**라는 안내가 표시됩니다.

Source: https://docs.alpacax.com/ko/use/servers/troubleshooting/