10.5. 헤드리스 모드¶
"헤드리스 모드"는 그래픽 사용자 인터페이스(GUI)에 의존하지 않고, Backend.AI GO를 주로 백그라운드 서비스나 서버로 실행하는 방식을 말합니다. 이는 유휴 장비를 전용 추론 서버로 설정하거나 원격에서 애플리케이션을 관리할 때 특히 유용합니다.
개념¶
Backend.AI GO는 데스크톱 애플리케이션으로도 제공되지만, 핵심 런타임은 공용으로 설계되어 있습니다:
- 공용 Rust 런타임: 모델 추론, 프로세스 오케스트레이션, Management API, Continuum Router를 처리합니다.
- 데스크톱 전송 계층: 내장 WebView에서 Tauri IPC를 사용합니다.
- 헤드리스 전송 계층:
aigo-server가 제공하는 REST 및 SSE, 그리고 HTTP로 제공되는 WebUI를 사용합니다.
즉, 헤드리스 모드는 더 이상 축소된 "서버 전용" 경로가 아닙니다. 실제 데스크톱 통합이 필요한 기능을 제외하면, 헤드리스 WebUI와 데스크톱 UI가 동일한 런타임 로직을 실행하는 것이 목표입니다.
운영 방법¶
시스템 트레이 (System Tray)¶
가장 기본적인 "헤드리스 스타일" 운영은 메인 창을 닫는 것입니다. * 기본적으로 창을 닫으면 Backend.AI GO는 시스템 트레이(macOS의 경우 메뉴 막대)로 최소화됩니다. * 이 상태에서도 API 서버와 모델 추론 프로세스는 백그라운드에서 계속 실행됩니다.
CLI 제어¶
함께 제공되는 aigo CLI를 사용하면 창을 열지 않고도 애플리케이션을 관리할 수 있습니다.
# 로드된 모델 목록 확인
aigo model list
# 모델 로드
aigo model load --name "llama-3-8b-instruct"
# 시스템 상태 확인
aigo system info
자세한 내용은 CLI 참조(CLI Reference) 문서를 확인하세요.
전용 헤드리스 서버 (aigo-server)¶
Backend.AI GO는 독립 실행형 헤드리스 바이너리를 제공합니다:
이 모드에서는 다음과 같이 동작합니다:
aigo-server의 dependency graph에tauricrate가 포함되지 않습니다.- Management API가 주요 제어 평면이 됩니다.
- WebUI는 Tauri IPC 대신 HTTP/SSE로 연결됩니다.
- 모델 풀, 라우터 관리, 스케줄링, 에이전트, 메모리, provider/runtime coordination은 데스크톱 앱과 동일한 공용 런타임 매니저를 재사용합니다.
원격 접속 (서버 모드)¶
로컬 컴퓨터를 다른 사용자를 위한 헤드리스 노드로 전환하려면:
- 설정 > 고급으로 이동합니다.
- 원격 접속 허용을 활성화합니다.
- API 포트를 설정합니다 (기본값: 8080).
- (선택 사항) 해당 포트에 대한 방화벽 규칙을 설정합니다.
이제 다른 Backend.AI GO 인스턴스, WebUI, 또는 curl/Python 스크립트가 사용자의 컴퓨터 IP 주소로 연결하여 마치 서버처럼 사용할 수 있습니다.
문제 해결¶
OOBE 완료 후 내비게이션 오작동¶
헤드리스 모드에서 초기 설정 마법사를 완료한 후 애플리케이션이 무한 오류를 표시하거나 메인 인터페이스로 이동하지 못하는 경우, 이는 이전 버전에서 발생하던 알려진 문제입니다.
주요 원인은 다음과 같습니다:
- 모니터링 스토어가 웹/헤드리스 모드에서 실패하는 Tauri IPC 호출을 직접 사용하고 있었습니다.
- SPA 폴백이
/api/*경로에 일치하는 API 엔드포인트가 없을 때 JSON 대신index.html을 반환하여, 프론트엔드가 HTML을 JSON으로 파싱하려는 시도가 발생했습니다.
이 두 가지 문제는 Backend.AI GO에서 수정되었습니다. 구버전에서 이 문제가 발생한다면, 업그레이드를 통해 해결할 수 있습니다.
서버 재시작 후 API 키 손실¶
헤드리스 모드에서는 GUI가 필요한 OS 키체인 대신 암호화된 파일(encrypted_keys.json)을 사용하여 API 키를 저장합니다. 이전 버전에는 다음과 같은 버그가 있었습니다:
- 새 키를 추가할 때 기존의 암호화된 항목들이 평문으로 다시 저장되어, 다음 재시작 시 복호화에 실패하는 문제가 있었습니다.
- 시작 시
force_encrypted_file_backend()가 키 레지스트리(key_ids)를 무조건 초기화하여, 암호화 파일이 온전한 경우에도 모든 키가 누락되는 문제가 있었습니다.
두 가지 문제 모두 현재 버전에서 수정되었습니다. 이전 버전에서 업그레이드 후 키 손실이 발생한 경우, API 키를 한 번 다시 입력하면 이후 재시작 시에도 정상적으로 유지됩니다.