에이전트 문제

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.us1.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

에이전트 업그레이드 문제

콘텐츠 작성 필요

최종 수정: