시스템 기능: 다국어/테마/업데이트/부팅 시 자동 시작/HTTP API Server
테마를 dark로 전환했는데 인터페이스가 여전히 밝은 색입니다. 창을 명확히 닫았는데 프로세스가 백그라운드에 계속 있습니다. 외부 도구로 현재 계정을 전환하고 싶지만 리버스 프록시를 LAN에 노출하고 싶지 않습니다.
이 수업에서는 Antigravity Tools의 "시스템 기능"에 집중합니다: 언어, 테마, 업데이트, 트레이/부팅 시 자동 시작, 외부 프로그램에서 호출하는 HTTP API Server.
시스템 기능이란 무엇인가?
시스템 기능은 Antigravity Tools가 데스크톱 애플리케이션으로서의 "제품화 기능"을 의미합니다: 인터페이스 다국어 및 테마 전환, 업데이트 확인 및 업그레이드, 창을 닫은 후 트레이 상주 및 부팅 시 자동 시작, 그리고 127.0.0.1에만 바인딩된 HTTP API Server를 외부 프로그램에서 호출할 수 있도록 제공합니다.
수업을 마치면 할 수 있는 것
- 언어/테마를 전환하고, 무엇이 "즉시 유효"한지 명확히 합니다
- "창 닫기"와 "프로그램 종료"의 차이를 명확히 하고, 트레이 메뉴가 무엇을 할 수 있는지 압니다
- 자동 업데이트 확인의 트리거 조건, 간격 및 저장 파일을 알고 있습니다
- HTTP API Server를 활성화하고
curl로 헬스 체크 및 계정 전환을 실행합니다
🎒 시작 전 준비
- 데이터 디렉터리 위치를 알고 있습니다(참조: 첫 번째 실행시 필독: 데이터 디렉터리, 로그, 트레이 및 자동 시작)
gui_config.json이 구성 저장의 단일 소스인 것을 알고 있습니다(참조: 구성 완전 해설: AppConfig/ProxyConfig, 저장 위치 및 핫 업데이트 의미)
핵심 아이디어
이 몇 가지 기능을 두 가지 범주로 나누면 기억하기 쉽습니다:
- "구성 기반" 기능: 언어, 테마는
gui_config.json에 기록됩니다(프론트엔드가save_config호출). - "독립 저장" 기능: 업데이트 설정 및 HTTP API 설정은 각각 별도의 JSON 파일이 있습니다. 트레이 및 닫기 동작은 Tauri 측에서 제어합니다.
따라해보기
1단계: 언어 전환(즉시 유효 + 자동 영구 저장)
이유 언어 전환은 "재시작이 필요하다"고 오해하기 가장 쉽습니다. 여기 구현은 UI가 즉시 전환되고 동시에 language를 구성에 다시 기록하는 것입니다.
작업: Settings -> General을 열고 언어 드롭다운에서 언어를 선택하세요.
거의 동시에 두 가지가 발생하는 것을 볼 수 있습니다:
- UI가 즉시 새 언어로 전환됩니다(프론트엔드가 직접
i18n.changeLanguage(newLang)을 호출). - 구성이 영구 저장됩니다(프론트엔드가
updateLanguage(newLang)을 호출, 내부적으로save_config를 트리거).
언어 팩은 어디서 오나요?
프론트엔드는 i18next로 다국어 리소스를 초기화하고 fallbackLng: "en"을 설정합니다. 즉, 어떤 키의 번역이 없으면 영어로 대체됩니다.
2단계: 테마 전환(light/dark/system)
이유 테마는 CSS뿐만 아니라 Tauri 창 배경색, DaisyUI의 data-theme, Tailwind의 dark class에도 영향을 미칩니다.
작업: Settings -> General에서 테마를 light / dark / system으로 전환하세요.
다음을 볼 수 있습니다:
- 테마가 즉시 유효해집니다(
ThemeManager가 구성을 읽고document.documentElement에 적용). - 테마가
system일 때, 시스템 어둠/밝은 색 변경이 실시간으로 애플리케이션에 동기화됩니다(prefers-color-scheme을 모니터링).
Linux의 한 가지 예외
ThemeManager는 getCurrentWindow().setBackgroundColor(...)를 호출하여 창 배경색을 설정하려고 시도하지만, Linux 플랫폼에서는 이 단계를 건너뜁니다(소스 코드에 주석이 있음: 투명 창 + softbuffer는 충돌을 유발할 수 있음).
3단계: 부팅 시 자동 시작(그리고 왜 --minimized가 붙는가)
이유 부팅 시 자동 시작은 "구성 필드"가 아니라 시스템 수준 등록 항목(Tauri autostart 플러그인)입니다.
작업: Settings -> General에서 "부팅 시 자동 시작"을 활성화/비활성화로 설정하세요.
다음을 볼 수 있습니다:
- 전환할 때 백엔드
toggle_auto_launch(enable)을 직접 호출합니다. - 페이지 초기화 시
is_auto_launch_enabled()를 호출하여 실제 상태를 표시합니다(로컬 캐시에 의존하지 않음).
추가: 애플리케이션 초기화 시 autostart 플러그인에 --minimized 매개변수를 전달하므로 "부팅 시 자동 시작"은 일반적으로 최소화/백그라운드 형태로 시작합니다(구체적인 동작은 프론트엔드가 이 매개변수를 처리하는 방법에 따름).
4단계: "창 닫기"와 "프로그램 종료" 명확히 하기
이유 많은 데스크톱 애플리케이션은 "닫으면 종료"이지만, Antigravity Tools의 기본 동작은 "닫으면 트레이로 숨김"입니다.
다음을 알아야 합니다:
- 창의 닫기 버튼을 클릭하면 Tauri가 닫기 이벤트를 가로채고
hide()를 수행하며, 프로세스를 종료하지 않습니다. - 트레이 메뉴에
Show/Quit가 있습니다: 완전히 종료하려면Quit를 사용해야 합니다. - 트레이 표시 텍스트는
config.language를 따릅니다(트레이 생성 시 구성 언어를 읽고 번역 텍스트를 가져옵니다. 구성 업데이트 후config://updated이벤트를 모니터링하여 트레이 메뉴를 새로 고침).
5단계: 업데이트 확인(자동 트리거 + 수동 확인)
이유 업데이트 부분은 두 가지 세트를 동시에 사용합니다:
- 사용자 정의 "버전 확인" 로직: GitHub Releases 최신 버전을 가져와서 업데이트가 있는지 확인.
- Tauri Updater: 다운로드 및 설치를 담당한 다음
relaunch().
다음과 같이 사용할 수 있습니다:
- 자동 확인: 애플리케이션 시작 후
should_check_updates를 호출하며, 확인이 필요하면UpdateNotification을 팝업하고 즉시last_check_time을 업데이트합니다. - 수동 확인:
Settings페이지에서 "업데이트 확인"을 클릭합니다(check_for_updates를 호출하고 UI에서 결과를 표시).
업데이트 간격은 어디서 오나요?
백엔드가 업데이트 설정을 데이터 디렉터리의 update_settings.json에 저장합니다. 기본 auto_check=true, check_interval_hours=24.
6단계: HTTP API Server 활성화(로컬에만 바인딩)
이유 외부 프로그램(예: VS Code 플러그인)이 "계정 전환/할당량 새로 고침/로그 읽기"를 하길 원한다면, HTTP API Server가 리버스 프록시 포트보다 더 적합합니다: 127.0.0.1에만 고정 바인딩되어 로컬에만 개방됩니다.
작업: Settings -> Advanced의 "HTTP API" 영역에서:
- 활성화 스위치를 켭니다.
- 포트를 설정하고 저장을 클릭합니다.
볼 수 있는 것: UI는 "재시작 필요"을 프롬프트합니다(백엔드는 시작 시에만 http_api_settings.json을 읽고 서비스를 시작하므로).
7단계: curl로 HTTP API 검증(헬스/계정/전환/로그)
이유 반복 가능한 검증 루프가 필요합니다: health를 통과하고, 계정을 나열하고, 전환/새로 고침을 트리거하고 이들이 비동기 작업임을 이해합니다.
기본 포트는 19527입니다. 포트를 수정했다면 아래의 19527을 실제 값으로 바꾸세요.
# 헬스 체크
curl -sS "http://127.0.0.1:19527/health" && echo
# 계정 나열(할당량 요약 포함)
curl -sS "http://127.0.0.1:19527/accounts" | head -n 5
# 현재 계정 가져오기
curl -sS "http://127.0.0.1:19527/accounts/current" | head -n 5
# 계정 전환 트리거(참고: 202 반환, 백그라운드 비동기 실행)
curl -sS -i \
-H 'Content-Type: application/json' \
-d '{"account_id":"<account_id>"}' \
"http://127.0.0.1:19527/accounts/switch"
# 모든 할당량 새로 고침 트리거(역시 202, 비동기 실행)
curl -sS -i -X POST "http://127.0.0.1:19527/accounts/refresh"
# 프록시 로그 읽기(limit/offset/filter/errors_only)
curl -sS "http://127.0.0.1:19527/logs?limit=50&offset=0&filter=&errors_only=false" | head -n 5 # 헬스 체크
Invoke-RestMethod "http://127.0.0.1:19527/health"
# 계정 나열
Invoke-RestMethod "http://127.0.0.1:19527/accounts" | ConvertTo-Json -Depth 5
# 현재 계정 가져오기
Invoke-RestMethod "http://127.0.0.1:19527/accounts/current" | ConvertTo-Json -Depth 5
# 계정 전환 트리거(202 반환)
$body = @{ account_id = "<account_id>" } | ConvertTo-Json
Invoke-WebRequest -Method Post -ContentType "application/json" -Body $body "http://127.0.0.1:19527/accounts/switch" | Select-Object -ExpandProperty StatusCode
# 모든 할당량 새로 고침 트리거(202 반환)
Invoke-WebRequest -Method Post "http://127.0.0.1:19527/accounts/refresh" | Select-Object -ExpandProperty StatusCode
# 프록시 로그 읽기
Invoke-RestMethod "http://127.0.0.1:19527/logs?limit=50&offset=0&filter=&errors_only=false" | ConvertTo-Json -Depth 5볼 수 있는 것:
/health는{"status":"ok","version":"..."}형식의 JSON을 반환합니다./accounts/switch는 202(Accepted)를 반환하고 "task started"를 프롬프트합니다. 실제 전환은 백그라운드에서 수행됩니다.
체크포인트 ✅
- 설명할 수 있습니다: 언어/테마는 "즉시 변경 시 즉시 유효"하지만 HTTP API 포트는 재시작이 필요합니다.
- 설명할 수 있습니다: 창을 닫아도 종료되지 않으며, 어디서 완전히 종료하는지.
curl로/health와/accounts를 통과하고/accounts/switch가 비동기인 것을 이해할 수 있습니다.
함정 경고
- HTTP API Server는
127.0.0.1에만 고정 바인딩되며,proxy.allow_lan_access와는 별개의 것입니다. - 업데이트 확인의 "확인 여부" 로직은 App 시작 시 이미 결정됩니다. 한 번 트리거되면
last_check_time을 먼저 업데이트하며, 이후 확인이 실패해도 짧은 시간 내에 반복 팝업되지 않습니다. - "창을 닫아도 종료하지 않음"은 설계된 것입니다: 프로세스 리소스를 해제하려면 트레이의
Quit를 사용하세요.
이 수업 요약
- 언어: UI 즉시 전환 + 구성에 다시 기록(
i18n.changeLanguage+save_config) - 테마:
ThemeManager가data-theme,darkclass 및 창 배경색으로 통일 적용(Linux에 예외) - 업데이트: 시작 시
update_settings.json에 따라 팝업 여부를 결정하고, 설치는 Tauri Updater가 담당 - HTTP API: 기본 활성화, 로컬만 액세스 가능, 구성은
http_api_settings.json에 저장, 포트 수정 시 재시작 필요
다음 수업 예고
다음 수업에서는 **서버 배포: Docker noVNC vs Headless Xvfb (advanced-deployment)**로 들어가며, 데스크톱 버전을 NAS/서버로 이동하여 실행합니다.
부록: 소스 코드 참조
펼쳐서 소스 코드 위치 확인
업데이트 시간: 2026-01-23
| 테마 | 파일 경로 | 행 번호 |
|---|---|---|
| i18n 초기화 및 fallback | src/i18n.ts | 1-67 |
| Settings: 언어/테마/부팅 시 자동 시작/업데이트 설정/HTTP API 설정 | src/pages/Settings.tsx | 16-730 |
| App: 언어 동기화 + 시작 시 업데이트 확인 트리거 | src/App.tsx | 52-124 |
| ThemeManager: 테마 적용, system 테마 모니터링, localStorage 쓰기 | src/components/common/ThemeManager.tsx | 1-82 |
| UpdateNotification: 업데이트 확인, 자동 다운로드 설치 및 relaunch | src/components/UpdateNotification.tsx | 1-217 |
| 업데이트 확인: GitHub Releases + check interval | src-tauri/src/modules/update_checker.rs | 1-187 |
트레이: 언어별 메뉴 생성 + config://updated 모니터링 및 새로 고침 | src-tauri/src/modules/tray.rs | 1-255 |
구성 저장: config://updated 전송 + 실행 중인 리버스 프록시 핫 업데이트 | src-tauri/src/commands/mod.rs | 296-334 |
| 부팅 시 자동 시작 명령: toggle/is_enabled(Windows disable 호환) | src-tauri/src/commands/autostart.rs | 1-39 |
| Tauri: autostart/updater 초기화 + 닫기 이벤트 hide로 변환 + HTTP API 시작 | src-tauri/src/lib.rs | 50-160 |
| HTTP API: 설정 저장 + 라우팅(health/accounts/switch/refresh/logs) + 127.0.0.1에만 바인딩 | src-tauri/src/modules/http_api.rs | 1-95 |
| HTTP API: Server bind 및 라우팅 등록 | src-tauri/src/modules/http_api.rs | 51-94 |
| HTTP API 설정 명령: get/save | src-tauri/src/commands/mod.rs | 773-789 |