8.5. 헤드리스 모드¶

"헤드리스 모드"는 그래픽 사용자 인터페이스(GUI)에 의존하지 않고, Backend.AI GO를 주로 백그라운드 서비스나 서버로 실행하는 방식을 말합니다. 이는 유휴 장비를 전용 추론 서버로 설정하거나 원격에서 애플리케이션을 관리할 때 특히 유용합니다.

개념¶

Backend.AI GO는 데스크톱 애플리케이션이지만, 핵심 구조는 분리되어 있습니다:

백엔드 (Rust): 모델 추론, API 서버, Continuum Router를 처리합니다.
프론트엔드 (React/Tauri): 시각적인 채팅 인터페이스를 담당합니다.

사용자는 GUI를 선택 사항으로 취급하고, Management API나 CLI 도구를 통해 백엔드와 상호작용할 수 있습니다.

운영 방법¶

시스템 트레이 (System Tray)¶

가장 기본적인 "헤드리스 스타일" 운영은 메인 창을 닫는 것입니다. * 기본적으로 창을 닫으면 Backend.AI GO는 시스템 트레이(macOS의 경우 메뉴 막대)로 최소화됩니다. * 이 상태에서도 API 서버와 모델 추론 프로세스는 백그라운드에서 계속 실행됩니다.

CLI 제어¶

함께 제공되는 bgo CLI를 사용하면 창을 열지 않고도 애플리케이션을 관리할 수 있습니다.

# 로드된 모델 목록 확인
bgo model list

# 모델 로드
bgo model load --name "llama-3-8b-instruct"

# 시스템 상태 확인
bgo system info

자세한 내용은 CLI 참조(CLI Reference) 문서를 확인하세요.

원격 접속 (서버 모드)¶

로컬 컴퓨터를 다른 사용자를 위한 헤드리스 노드로 전환하려면:

설정 > 고급으로 이동합니다.
원격 접속 허용을 활성화합니다.
API 포트를 설정합니다 (기본값: 8080).
(선택 사항) 해당 포트에 대한 방화벽 규칙을 설정합니다.

이제 다른 Backend.AI GO 인스턴스(또는 curl/Python 스크립트)가 사용자의 컴퓨터 IP 주소로 연결하여 마치 서버처럼 사용할 수 있습니다.

참고: GUI 프레임워크 초기화 없이 실행되는 완전한 커맨드라인 전용 시작 모드는 향후 리눅스 서버 빌드에 포함될 예정입니다.

문제 해결¶

OOBE 완료 후 내비게이션 오작동¶

헤드리스 모드에서 초기 설정 마법사를 완료한 후 애플리케이션이 무한 오류를 표시하거나 메인 인터페이스로 이동하지 못하는 경우, 이는 이전 버전에서 발생하던 알려진 문제입니다.

주요 원인은 다음과 같습니다:

모니터링 스토어가 웹/헤드리스 모드에서 실패하는 Tauri IPC 호출을 직접 사용하고 있었습니다.
SPA 폴백이 /api/* 경로에 일치하는 API 엔드포인트가 없을 때 JSON 대신 index.html을 반환하여, 프론트엔드가 HTML을 JSON으로 파싱하려는 시도가 발생했습니다.

이 두 가지 문제는 Backend.AI GO에서 수정되었습니다. 구버전에서 이 문제가 발생한다면, 업그레이드를 통해 해결할 수 있습니다.