에이전트 문제

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

에이전트 설치 실패

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

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

기본 설치 스크립트는 OS 종류와 무관하게 동일한 스크립트를 사용하므로 대부분의 경우 문제없이 설치됩니다. 하지만 매뉴얼 방식으로 에이전트를 설치할 경우, OS 계열에 따라 설치 스크립트가 달라지므로 잘못된 OS를 선택하면 설치에 실패합니다.

해결 방법:

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

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

  2. 서버 등록 페이지에서 서버 등록 시 올바른 OS 계열 선택

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

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

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

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

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

해결 방법:

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

  2. 기존 워크스페이스 접근 불가 시 서버 제거하기 참고하여 수동 에이전트 삭제

  3. 신규 워크스페이스에서 서버 등록 및 에이전트 설치 새로 수행

Windows 에이전트 문제

서비스가 시작되지 않음

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

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를 점유하고 있는 경우입니다. 먼저 서비스를 중지하고 다시 시도하세요:

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

Websh에서 PowerShell error 8009001d 발생

초기 Windows 빌드에서 발생하던 TLS 관련 Websh 핸드셰이크 오류로, 이후 Alpamon 릴리스에서 수정되었습니다. 최신 Alpamon으로 업그레이드한 뒤(alpamon upgrade 또는 설치 스크립트 재실행) 다시 시도하세요.

WebFTP에서 C:\Windows\System32\... 등 사용자 홈 외부 경로를 읽을 수 없음

의도된 동작입니다. Windows의 WebFTP는 사용자 홈 디렉터리 안에서만 탐색할 수 있으며, 시스템 경로는 노출하지 않습니다. 전송할 파일은 사용자 홈 디렉터리 아래에 두거나, 시스템 경로의 읽기 전용 확인이 필요한 경우 Websh를 사용하세요.

macOS 에이전트 문제

서비스가 시작되지 않음

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

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

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

서비스 재시작

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 에이전트를 최신 상태로 유지합니다.

  • 자동: 워크스페이스 설정에서 자동 에이전트 업그레이드가 켜져 있으면(기본값), 등록된 에이전트가 알아서 최신 버전으로 업그레이드됩니다.
  • 수동: CLI에서 alpacon agent upgrade SERVER로 특정 서버를 업그레이드한 뒤, alpacon events로 진행 상황을 확인합니다.

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

  • Linux(Debian/Ubuntu, RHEL/CentOS): 시스템 패키지 매니저(apt/yum)를 통해 Alpacon 패키지 저장소에서 받습니다.
  • macOS: GitHub Releases에서 내려받습니다.
  • Windows: 명령을 통한 업그레이드는 아직 지원되지 않습니다. 최신 릴리스로 설치 프로그램을 다시 실행해 업그레이드하세요(Windows 설치 참고).

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

  • 서버가 온라인인지 확인하세요. 오프라인 상태의 에이전트는 업그레이드 요청을 받을 수 없습니다.
  • alpacon agent upgrade SERVER를 실행하고 alpacon events로 결과를 확인하세요.
  • 자동 업그레이드를 사용한다면 워크스페이스 설정에서 자동 에이전트 업그레이드가 켜져 있는지 확인하세요.

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

  • 연결 확인: 모든 플랫폼은 api.github.com에서 최신 버전을 확인하므로, 서버가 api.github.com으로의 아웃바운드 HTTPS를 허용해야 합니다. Linux에서는 이후 apt/yum으로 업그레이드하므로, 서버가 Alpacon 패키지 저장소에 직접 또는 워크스페이스 패키지 프록시 설정을 통해 접근할 수 있어야 합니다. macOS에서는 에이전트가 github.com에서 릴리스를 직접 내려받습니다.
  • 에이전트 로그에서 원인을 확인한 뒤 업그레이드를 다시 시도하세요.
    • Linux: sudo journalctl -u alpamon -n 100
    • macOS: tail -n 100 /var/log/alpamon/alpamon.log
  • 업그레이드가 실패하면 에이전트는 이전 버전을 그대로 유지합니다. 원인(대개 네트워크나 패키지 저장소 접근)을 해결한 뒤 다시 시도하세요.

현재 버전 확인

서버 상세 페이지에서 실행 중인 에이전트 버전을 확인할 수 있습니다. 언제든 업그레이드를 다시 실행해도 되며, 이미 최신이면 아무것도 바뀌지 않습니다.

최종 수정: