Agent 일상 사용 매뉴얼¶

이 문서는 Agent 서비스 설치를 완료한 사용자를 대상으로 합니다. Agent 상태 확인, 서비스 관리, 구성 수정, 로그 조회, 수동 업데이트 및 Agent 제거 방법을 설명합니다.

아래 명령어는 Linux/systemd 설치 방식에 적용됩니다. 서비스 관리, 구성 수정 및 제거 명령어를 실행하려면 일반적으로 호스트에서 sudo 권한이 필요합니다.

Agent 파일 찾기¶

기본 설치 후 Agent 관련 파일은 다음 위치에 있습니다:

Agent 상태 확인¶

Agent가 실행 중인지 확인:

systemctl status obs-agent

서비스가 활성 상태인지만 확인:

systemctl is-active obs-agent

현재 설치된 Agent 버전 확인:

/usr/local/bin/obs-agent --version

Agent의 실행 사용자 확인:

systemctl show obs-agent -p User -p Group

기본적으로 Agent 서비스는 obs-agent 사용자로 실행되며, root로 지속 실행되지 않습니다. root는 주로 설치, 업그레이드, 제거와 같은 호스트 관리 작업에 사용됩니다.

Agent 시작, 중지 또는 재시작¶

Agent 시작:

sudo systemctl start obs-agent

Agent 중지:

sudo systemctl stop obs-agent

Agent 재시작:

sudo systemctl restart obs-agent

구성을 수정한 후 새 구성을 적용하려면 일반적으로 서비스 재시작이 필요합니다:

sudo systemctl restart obs-agent

Agent 로그 조회¶

최근 systemd 로그 조회:

journalctl -u obs-agent -n 100

최신 로그 실시간 조회:

journalctl -u obs-agent -f

Agent 메인 로그 파일 조회:

tail -n 100 /var/log/obs-agent/log

Agent가 시작되지 않는 경우 먼저 다음을 확인하는 것이 좋습니다:

systemctl status obs-agent
journalctl -u obs-agent -n 100

Agent 구성 수정¶

Agent의 런타임 구성은 기본적으로 다음 위치에 저장됩니다:

/etc/obs-agent/agent.env

수정 전 백업을 권장합니다:

sudo cp /etc/obs-agent/agent.env /etc/obs-agent/agent.env.bak

구성 편집:

sudo vi /etc/obs-agent/agent.env

주요 구성 항목:

Agent가 기업 프록시를 통해 Beak, LLM 또는 릴리스 서비스에 접근해야 하는 경우, Configure an obs-agent forward proxy에 설명된 대로 프록시 변수와 기업 CA를 구성하십시오.

LLM_MODEL은 더 이상 필수 구성이 아닙니다. 새 버전 런타임은 기본적으로 default 모델 식별자를 사용합니다. 이전 구성에 활성 상태의 LLM_MODEL=...이 남아 있는 경우, 모델을 고정해야 하는 경우에만 유지하는 것이 좋습니다. 그렇지 않으면 해당 줄을 삭제하고 서비스를 재시작할 수 있습니다.

수정 완료 후 서비스를 재시작합니다:

sudo systemctl restart obs-agent

구성 오류로 인해 서비스가 시작되지 않는 경우 백업에서 복원할 수 있습니다:

sudo cp /etc/obs-agent/agent.env.bak /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

Agent 수동 업데이트 또는 롤백¶

Agent는 로컬 업데이터를 통해 버전을 전환할 수 있습니다.

릴리스 소스의 최신 버전으로 업데이트:

sudo /usr/local/bin/obs-agent-updater

특정 버전 설치:

sudo /usr/local/bin/obs-agent-updater --target-version v0.2.0

버전 롤백도 동일한 명령어를 사용합니다. 예를 들어 v0.1.9로 롤백하는 경우:

sudo /usr/local/bin/obs-agent-updater --target-version v0.1.9

자동 업데이트 타이머 상태 확인:

systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer

업데이트가 실패하면 다음을 우선 확인하십시오:

• /etc/obs-agent/agent.env의 AGENT_UPDATE_BASE_URL이 올바른지;
• 릴리스 주소에 install.sh, 대상 버전 설치 패키지 및 검증 파일이 존재하는지;
• journalctl -u obs-agent-update-check.service -n 100에 다운로드, 검증 또는 스케줄링 오류가 있는지;
• journalctl -u obs-agent -n 100에 시작 또는 재시작 오류가 있는지.

자동 업데이트는 /etc/obs-agent/agent.env에서 프록시 변수를 읽습니다. 프록시 관련 확인 사항은 Keep automatic updates on the proxy를 참조하십시오.

Agent 제거¶

제거 스크립트는 기본적으로 제거 계획만 표시하며 어떤 내용도 삭제하지 않습니다:

curl -fsSL https://static.guance.com/obs-agent/uninstall.sh | sudo bash

올바른지 확인한 후 --yes로 전체 제거를 실행합니다:

curl -fsSL https://static.guance.com/obs-agent/uninstall.sh | sudo bash -s -- --yes

제거 시 다음 고정 객체가 삭제됩니다:

• /usr/local/bin/obs-agent
• /usr/local/bin/obs-agent-updater
• /usr/local/bin/obs-agent-update-check
• /etc/obs-agent
• /var/lib/obs-agent
• /var/log/obs-agent
• obs-agent.service
• obs-agent-update-check.service
• obs-agent-update-check.timer
• /etc/sudoers.d/obs-agent
• obs-agent 사용자 및 사용자 그룹

제거 시 skill-dep.sh가 설치하거나 확인한 Skill 런타임 의존성은 삭제되지 않습니다. 여기에는 시스템 명령어, 언어 런타임, Python/Node 패키지, 폰트 또는 기타 시스템 패키지가 포함됩니다. 이러한 의존성은 호스트에 원래 존재하던 공유 구성 요소이거나 다른 서비스에서 재사용될 수 있으므로 Agent 제거 프로세스에서 삭제할 수 없습니다.

일반적인 점검 사항¶

페이지에서 Agent가 오프라인으로 표시되는 경우¶

다음 순서로 확인하는 것이 좋습니다:

1. 호스트 서비스가 실행 중인지: systemctl status obs-agent
2. 호스트 네트워크에서 서비스 주소에 접근할 수 있는지;
3. /etc/obs-agent/agent.env의 BEAK_WS_URL, AGENT_API_KEY, AGENT_ID가 올바른지;
4. 최근 로그에 인증 실패, 네트워크 연결 실패 또는 DNS 확인 실패가 있는지.

Agent 구성 변경이 적용되지 않는 경우¶

서비스가 재시작되었는지 확인합니다:

sudo systemctl restart obs-agent

그런 다음 로그를 확인하여 새 프로세스가 시작되었는지 확인합니다:

journalctl -u obs-agent -n 50

업데이트 후 Agent 버전이 변경되지 않은 경우¶

먼저 현재 버전을 확인합니다:

/usr/local/bin/obs-agent --version

그런 다음 업데이트 로그를 확인합니다:

journalctl -u obs-agent-update-check.service -n 100
journalctl -u obs-agent -n 100

특정 버전 업데이트인 경우, 명령어의 버전 번호가 릴리스 소스의 버전 번호와 일치하는지 확인합니다.