콘텐츠로 이동

내장 WebUI

Continuum Router에는 바이너리에 직접 컴파일된 브라우저 기반 관리 인터페이스가 포함되어 있습니다. 외부 파일, 빌드 도구, Node.js 파이프라인이 필요하지 않습니다. WebUI는 단일 바이너리 배포의 일부로 항상 사용할 수 있습니다.

개요

WebUI는 Admin REST API를 통해 사용할 수 있는 동일한 작업에 대한 그래픽 인터페이스를 제공합니다. 다음 용도에 특히 유용합니다:

  • 백엔드 상태 모니터링 (인터랙티브)
  • API 키 수명 주기 관리 (생성, 교체, 활성화/비활성화, 삭제)
  • 유효성 검사가 포함된 실시간 구성 편집
  • 구성 변경 이력 및 롤백

WebUI는 /admin/* 엔드포인트와 동일한 관리자 인증 미들웨어로 보호됩니다. 추가적인 인증 구성은 필요하지 않습니다.

구성

구성 파일의 webui 섹션이 내장 인터페이스를 제어합니다:

webui:
  enabled: true        # 기본값: 관리자가 구성된 경우 true
  path_prefix: /webui  # 기본값: /webui

구성 속성:

속성 타입 기본값 설명
enabled boolean true WebUI 활성화 또는 비활성화
path_prefix string /webui WebUI의 URL 경로 접두사. /로 시작해야 합니다. ..을 포함해서는 안 됩니다.

구성에서 webui를 생략하면 위의 기본값이 적용됩니다 (WebUI는 /webui에서 활성화됨).

WebUI를 완전히 비활성화하려면:

webui:
  enabled: false

WebUI 접속

관리자 인증이 구성된 상태에서 라우터가 실행되면 다음 주소로 이동합니다:

http://<호스트>:<포트>/webui/

예를 들어, 기본 설정을 사용하는 경우:

http://localhost:8080/webui/

관리자 Bearer 토큰을 입력하라는 메시지가 표시됩니다. 토큰은 브라우저 세션 동안 localStorage에 저장되며 이후 모든 Admin API 호출에서 Bearer 헤더로 사용됩니다.

인증

WebUI는 Admin API와 동일한 Bearer 토큰 인증을 사용합니다. admin 섹션에서 관리자 인증을 구성하세요:

admin:
  auth:
    method: bearer
    token: "${ADMIN_TOKEN}"

브라우저에서 WebUI를 처음 열면 로그인 프롬프트에 Bearer 토큰을 입력합니다. 토큰은 continuum_admin_token 키 아래 브라우저의 localStorage에 저장됩니다.

페이지

대시보드

대시보드는 라우터의 상태와 활동을 한눈에 볼 수 있는 뷰를 제공합니다:

  • 백엔드 상태 (정상 / 저하 / 비정상)
  • 백엔드별 서킷 브레이커 상태
  • 빠른 통계 (요청 수, 오류율, 평균 지연 시간)
  • 5초마다 자동 새로 고침

API 키

API 키 페이지는 API 키에 대한 전체 수명 주기 관리를 제공합니다:

  • 마스킹된 값과 상태 표시기로 모든 키 목록 보기
  • 구성 가능한 범위 및 속도 제한으로 새 키 생성
  • 기존 키 메타데이터 편집 (이름, 설명, 범위, 속도 제한)
  • 키 값 교체 (키 ID를 유지하면서 새 시크릿 생성)
  • 삭제하지 않고 키 활성화 또는 비활성화
  • 키 영구 삭제
  • 이름 또는 상태로 검색 및 필터링

백엔드

백엔드 페이지는 백엔드 구성을 표시하고 관리합니다:

  • 상태 표시기와 함께 구성된 모든 백엔드 목록 보기
  • 타입, URL 및 가중치 설정으로 새 백엔드 추가
  • 백엔드 속성 편집 (URL, 가중치, 모델)
  • 런타임에 백엔드 제거
  • 백엔드별 지연 시간 및 서킷 브레이커 상태 보기

구성

구성 페이지는 섹션 기반 구성 편집을 제공합니다:

  • 섹션별로 구성 탐색 (서버, 상태 확인, 로깅 등)
  • 인브라우저 유효성 검사와 함께 JSON으로 섹션 편집
  • 전체 구성을 YAML 또는 TOML로 내보내기
  • 파일에서 구성 가져오기
  • 핫 리로드 상태 보기 (어떤 섹션이 실시간 업데이트를 지원하는지)

이력

이력 페이지는 구성 변경 타임라인을 표시합니다:

  • 타임스탬프와 함께 모든 구성 수정 내역 보기
  • 구성 버전 간 차이점 검사
  • 이전 구성 상태로 롤백

기술 스택

WebUI는 다음으로 구축되었습니다:

  • Alpine.js - 인터랙티브 컴포넌트를 위한 경량 반응성
  • Tailwind CSS - CDN(cdn.jsdelivr.net)에서 로드되는 유틸리티 우선 스타일링
  • Vanilla JavaScript - Alpine.js 외에 프레임워크 의존성 없음

에셋은 rust-embed를 사용하여 임베드되며 다음과 함께 제공됩니다:

  • ETag 기반 캐싱 - 콘텐츠 주소 지정 ETag가 304 Not Modified 응답을 가능하게 함
  • Cache-Control 헤더 - HTML의 경우 no-cache (항상 재검증), JS/CSS의 경우 public, max-age=3600
  • 보안 헤더 - X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN
  • 콘텐츠 보안 정책 - CDN URL을 cdn.jsdelivr.net 및 fonts.googleapis.com으로 고정

보안 고려 사항

  • 모든 WebUI 라우트는 유효한 관리자 인증이 필요합니다. 인증되지 않은 요청은 401 Unauthorized를 받습니다.
  • path_prefix는 경로 탐색을 방지하기 위해 /로 시작해야 하며 ..을 포함해서는 안 됩니다.
  • 에셋 서버 내의 파일 경로도 제공하기 전에 탐색 시퀀스(.., null 바이트)에 대해 유효성을 검사합니다.
  • 콘텐츠 보안 정책은 스크립트 및 스타일 소스를 self 및 고정된 CDN 출처로 제한합니다.
  • X-Frame-Options: SAMEORIGIN은 교차 출처 프레임에서의 클릭재킹을 방지합니다.

WebUI 비활성화

브라우저 인터페이스가 필요하지 않은 경우 공격 표면을 줄이기 위해 비활성화하세요:

webui:
  enabled: false

비활성화되면 구성된 path_prefix에 대한 모든 요청은 404 Not Found를 반환합니다.

사용자 정의 경로 접두사

다른 경로에서 WebUI를 제공하려면 (예: 역방향 프록시 뒤에서):

webui:
  enabled: true
  path_prefix: /admin/ui

그러면 WebUI는 다음 주소에서 사용할 수 있습니다:

http://localhost:8080/admin/ui/

역방향 프록시가 이 접두사에 대한 요청을 올바르게 전달하는지 확인하세요:

location /admin/ui/ {
    proxy_pass http://localhost:8080/admin/ui/;
}