KO Operating toard

Read in English

운영하기

이 문서는 toard를 설치한 뒤 반복적으로 확인할 운영 항목을 정리합니다. 배포별 상세 설정은 저장소의 배포 가이드가 원본입니다.

상태 확인

curl -fsS http://localhost:3000/api/health
curl -fsS http://localhost:3000/api/ready
docker compose ps -a

health는 앱 프로세스 상태를, ready는 데이터베이스 연결까지 포함한 준비 상태를 확인합니다. 정상 설치 뒤 migrate가 exited (0)인 것은 정상입니다.

가격 동기화

toard는 LiteLLM 가격 정보를 바탕으로 비용을 계산합니다. self-host 환경에서는 앱 내장 스케줄러가 일 단위 동기화를 처리하며, 관리 화면의 시스템 탭에서 상태와 수동 동기화를 확인할 수 있습니다. 비용이 계속 $0이면 가격 동기화 상태부터 점검하세요.

프로덕션에서는 외부 scheduler를 쓰는지와 관계없이 CRON_SECRET을 설정해 /api/cron/*을 보호하세요.

업데이트

Compose updater를 활성화한 환경에서는 관리 화면을 통해 서버 이미지 업데이트를 실행할 수 있습니다. updater는 이미지를 가져오고, 마이그레이션을 실행한 뒤, 앱을 재기동하고 health·ready·version을 확인합니다. 자동 롤백은 제한적이므로 이전 이미지 태그와 복구 절차를 준비하세요.

shim은 새 릴리스를 확인해 SHA256을 검증한 뒤 교체할 수 있습니다. 필요하면 다음 명령으로 수동 확인합니다.

toard-shim update
toard-shim version

사용자와 token

• 최소 두 명의 admin을 유지하세요.
• 팀원이 떠나거나 기기를 분실하면 해당 ingest token을 폐기하세요.
• token과 초대 링크를 같은 공개 채널에 함께 공유하지 마세요.
• 기기별 token은 영향 범위를 좁혀 폐기하기 쉽게 만듭니다.

백업과 본문 수집

최소 백업 대상은 Postgres 데이터와 운영 설정입니다. 본문 수집을 사용한다면 KEK도 DB 백업과 분리해 안전하게 보관해야 합니다. KEK를 잃으면 이미 암호화된 본문을 복호화할 수 없습니다.

ClickHouse

ClickHouse는 이벤트와 집계 조회를 위한 선택 백엔드입니다. 계정·팀·인증 메타데이터는 계속 Postgres가 기준입니다. rollup 읽기 전환은 query diff와 outbox 상태를 포함한 정확 롤업 런북을 따른 뒤에만 수행하세요.