업데이트, 런북, 문제 해결

이 페이지는 Revka 인스턴스를 운영 중인 관리자를 위한 2일차 가이드입니다. 바이너리 또는 컨테이너 업데이트 방법, 설정을 안전하게 변경하기 위한 운영 런북, 프로덕션에서 모니터링할 상태 및 상태 신호, 그리고 가장 자주 발생하는 장애에 대한 문제 해결 참고 자료를 다룹니다. 초기 설치가 완료된 이후에 참고하십시오. 최초 설치는 Installation을, 이 페이지에서 참조하는 진단 명령은 revka doctor, status & self-test를 참고하십시오.

반드시 기억해야 할 한 가지 흐름

실행 중인 인스턴스에 대한 모든 변경은 동일한 루프를 따릅니다: 검증 → 한 가지만 변경 → 재시작 → 확인 → 필요 시 롤백. 업데이트 명령과 설정 편집 모두 이 루프를 통해 진행됩니다. 이 페이지의 나머지 내용은 각 단계에 대한 세부 설명입니다.

Revka 업데이트

업데이트 방법은 설치 방식에 따라 다릅니다. 배포 환경에 맞는 경로를 선택하십시오.

Self-update

소스에서 설치하거나 사전 빌드된 릴리스를 사용하는 경우, 내장 셀프 업데이트 명령이 가장 간단한 방법입니다:

revka update                  # download and install the latest release
revka update --check          # only report current vs latest, do not install
revka update --force          # skip the confirmation prompt
revka update --version 0.6.0  # install a specific release

플래그	의미
--check	확인만 수행 — 현재 버전과 최신 버전을 출력하고 종료합니다.
--force	대화형 확인 프롬프트 없이 설치합니다.
--version <X.Y.Z>	최신 버전 대신 특정 릴리스를 대상으로 합니다.

Homebrew

Homebrew(macOS 또는 Linuxbrew)로 설치한 경우:

brew upgrade revka

Homebrew는 런타임 데이터를 자체 var/revka/ 디렉터리에 보관하고 REVKA_CONFIG_DIR을 launchd 서비스에 전달하므로, 업그레이드 후에도 설정과 워크스페이스 데이터가 유지됩니다. macOS update & uninstall을 참고하십시오.

install.sh

부트스트랩 인스톨러로 관리되는 소스 체크아웃의 경우, 풀 후 재실행하십시오:

git pull
./install.sh --prefer-prebuilt     # try a release binary, fall back to source

업그레이드 후, 기존 파일을 덮어쓰지 않고 새로 번들된 워크플로 템플릿을 추가하십시오:

revka workflows sync               # non-destructive; existing files untouched

install.sh 플래그 전체 목록은 Installation을 참고하십시오.

Docker

컨테이너의 경우 바이너리 대신 이미지를 업데이트하십시오. 컨테이너를 재시작하기 위해 install.sh를 다시 실행하지 마십시오.

# Compose
docker compose pull
docker compose up -d

# Plain docker
docker pull ghcr.io/kumihoio/revka:latest
docker stop revka && docker rm revka
docker run -d ... ghcr.io/kumihoio/revka:latest

재현 가능한 배포가 필요한 경우 :latest 대신 CalVer 태그(예: ghcr.io/kumihoio/revka:2026.4.21)를 고정하십시오. Docker, Compose & one-click PaaS를 참고하십시오.

revka update 파이프라인

revka update는 단순한 덮어쓰기가 아닙니다. 6단계 파이프라인을 실행하여 현재 바이너리를 백업하고, 문제가 발생하면 자동으로 롤백합니다. 따라서 업데이트에 실패하더라도 작동하는 바이너리 없이 남겨지는 일이 없습니다.

1. 사전 검사(Preflight) — 대상 버전을 확인하고 업데이트가 필요한지 검토합니다.
2. 다운로드(Download) — GitHub Releases에서 플랫폼에 맞는 릴리스 바이너리를 가져옵니다.
3. 백업(Backup) — 복원 가능하도록 현재 설치된 바이너리를 저장합니다.
4. 유효성 검사(Validate) — 다운로드한 파일의 SHA256 체크섬과 선택적 cosign 서명을 검증합니다(install.sh와 동일한 검증 체인을 사용합니다).
5. 교체(Swap) — 실행 중인 바이너리를 새 버전으로 원자적으로 교체합니다.
6. 스모크 테스트(Smoke test) — 새 바이너리를 실행하여 정상 동작을 확인합니다.

스모크 테스트(또는 이전 단계)가 실패하면 파이프라인이 백업된 바이너리로 자동 롤백됩니다. --check는 사전 검사 비교만 실행하고 현재 버전과 최신 버전을 출력하며, 어떠한 변경도 가하지 않습니다.

업데이트 후 반드시 확인하십시오

어떤 방법을 사용했든, 업그레이드가 완료되고 설치 상태가 정상인지 확인하십시오:

revka --version
revka self-test --quick     # offline checks: config, registries, local storage

데몬이 재시작된 후 전체 revka self-test를 실행하여 게이트웨이 상태 및 메모리 왕복 검사를 추가로 수행하십시오. revka doctor, status & self-test를 참고하십시오.

운영 런북

Revka는 여러 모드 중 하나로 실행됩니다. 실행 방식에 맞는 운영 명령을 사용하십시오.

모드	시작	관리
포그라운드 자율 런타임	revka daemon	Ctrl-C (SIGINT/SIGTERM)
게이트웨이 전용 (대시보드 + API)	revka gateway	revka gateway restart
OS 백그라운드 서비스	revka service install && revka service start	revka service status / logs / restart
컨테이너	docker compose up -d	docker compose logs -f / restart

전체 명령 참고는 revka gateway, daemon & service에서, OS 서비스로 실행하는 방법은 Run as a background service에서, 컨테이너는 Docker, Compose & one-click PaaS에서 확인하십시오.

안전한 설정 배포

설정은 ~/.revka/config.toml에 저장됩니다. 모든 편집을 배포로 간주하고 검증 → 변경 → 재시작 → 확인 → 롤백 루프를 따르십시오.

1. 먼저 검증하십시오. 작업을 시작하기 전에 revka doctor를 실행하여 기준 상태가 정상임을 확인하십시오. config 카테고리는 실제 검증을 수행합니다 — 프로바이더를 구성하고 모델 및 임베딩 라우트를 확인하며 온도 범위를 검사합니다 — 따라서 대부분의 실수는 런타임이 아닌 이 단계에서 발견됩니다.
2. 한 가지만 변경하십시오. config.toml에서 단일 키(또는 하나의 논리적 그룹)만 편집하십시오. 변경 범위가 작을수록 롤백이 명확해집니다.
3. 재시작하여 적용하십시오. 대부분의 설정은 재시작 시 적용됩니다: revka service restart(서비스), revka gateway restart(게이트웨이), 또는 docker compose restart(컨테이너).
4. 확인하십시오. revka doctor를 다시 실행한 후 revka status로 새 값이 적용되었고 어떤 컴포넌트도 stale 상태가 되지 않았는지 확인하십시오.
5. 필요 시 롤백하십시오. 이전 config.toml을 복원하고 재시작하십시오. 편집 전에 백업을 보관하거나, revka onboard --reinit을 사용하십시오(전체 설정 디렉터리의 백업을 타임스탬프와 함께 저장한 후 초기화를 시작합니다).

일부 키는 핫 리로드됩니다 — 대부분은 그렇지 않습니다

채널 런타임은 config.toml을 감시하여 default_provider, default_model, default_temperature, api_key / api_url, 그리고 reliability.* 키의 변경 사항을 재시작 없이 실시간으로 적용합니다. 그 외 모든 항목 — 바인드 호스트/포트, 보안 정책, 새 채널 — 은 적용하려면 재시작이 필요합니다. 대화형 revka agent 세션은 핫 리로드를 지원하지 않으므로 세션을 재시작하십시오. revka channel & integrations를 참고하십시오.

컨테이너를 인스톨러를 다시 실행하여 재시작하지 마십시오

Docker 배포의 경우, 중지된 인스턴스를 다시 시작하기 위해 install.sh --docker를 재실행하지 마십시오 — 이미지를 재빌드하고 온보딩을 다시 실행하게 됩니다. 기존 컨테이너를 재시작하려면 docker start <name> 또는 docker compose up -d를 사용하십시오.

상태 신호

Revka는 여러 독립적인 활성 신호를 제공합니다. 질문에 답할 수 있는 가장 저렴한 신호를 사용하십시오.

컴포넌트 상태 레지스트리

프로세스 전역 레지스트리가 각 서브시스템의 상태를 추적합니다. 컴포넌트는 starting 상태로 시작하며, 실행되면서 마지막 OK 시각, 마지막 오류, 재시작 횟수와 함께 ok 또는 error로 기록됩니다. 알려진 컴포넌트 이름은 다음 규칙을 따릅니다: gateway, scheduler, heartbeat, 그리고 channel:<name>(예: channel:telegram).

게이트웨이 상태 엔드포인트

GET /health는 해당 레지스트리의 전체 상태 스냅샷을 반환합니다. 인증이 필요 없으며, Docker HEALTHCHECK, 로드 밸런서, 모니터링 시스템의 기본 활성 신호로 사용됩니다.

GET http://localhost:42617/health

{
  "pid": 12345,
  "updated_at": "2026-06-18T12:00:00Z",
  "uptime_seconds": 3600,
  "components": {
    "gateway":          { "status": "ok",    "updated_at": "…", "last_ok": "…", "restart_count": 0 },
    "scheduler":        { "status": "ok",    "updated_at": "…", "last_ok": "…", "restart_count": 0 },
    "channel:telegram": { "status": "error", "updated_at": "…", "last_error": "timeout", "restart_count": 2 }
  }
}

200 OK가 모든 것이 정상임을 의미하지 않습니다

GET /health는 컴포넌트가 error 상태를 보이더라도 항상 HTTP 200을 반환합니다. 상태 코드만 신뢰하지 말고 JSON의 status 필드를 직접 확인하십시오. GET /api/health도 동일한 스냅샷을 제공합니다. Status, health, config & tools endpoints를 참고하십시오.

상태를 종료 코드로 매핑하는 스크립트 기반 업/다운 확인(Docker HEALTHCHECK에 적합)을 위해 내부적으로 GET /health를 수행하는 CLI 래퍼를 사용하십시오:

revka status --format exit-code   # exit 0 if healthy, 1 otherwise

데몬 상태 파일과 최신성

데몬은 몇 초마다 config.toml 옆에 daemon_state.json을 기록하며, 여기에는 모든 컴포넌트의 상태 스냅샷과 written_at 타임스탬프가 포함됩니다. 외부 모니터는 이 파일을 감시할 수 있습니다: 파일이 45초 이상 오래된 경우 데몬이 종료된 것입니다. Windows에서는 Task Scheduler를 안정적으로 쿼리할 수 없기 때문에, 이 파일이 실행 중인 프로세스 확인 수단으로도 사용됩니다.

revka doctor는 이 파일을 읽고, 마지막 업데이트가 고정된 임계값을 초과한 컴포넌트를 stale로 보고합니다:

컴포넌트	Stale 기준
Heartbeat	30초
Scheduler	120초
Channel	300초

상태 파일이 없으면 데몬이 실행 중이지 않은 것으로 간주됩니다. 메트릭 기반 모니터링(GET /metrics, OTLP, 런타임 트레이스)은 Observability & tracing을 참고하십시오.

문제 해결

모든 조사는 revka doctor로 시작하십시오 — 설정을 검증하고 워크스페이스를 점검하며 데몬, 스케줄러, 채널 최신성을 한 번에 확인합니다. 대부분의 문제는 로그를 읽기 전에 여기서 발견됩니다.

트리아지 흐름

1. revka doctor — 설정 유효성, 데몬/스케줄러/채널 최신성, 사이드카 및 Kumiho 백엔드 상태를 확인합니다. 모든 인시던트의 첫 번째 단계입니다.
2. revka status — 인스턴스가 예상한 대로 설정되어 있는지 확인합니다(프로바이더, 모델, 런타임 종류, 서비스 상태, 비용, OTP/e-stop).
3. GET /health — 어떤 특정 컴포넌트가 error 상태이고 재시작 횟수가 얼마인지 확인합니다.
4. 로그 — 장애가 발생한 컴포넌트의 서비스 로그를 확인합니다(아래 키워드 트리아지 참고).
5. revka doctor traces — 특정 턴이나 도구 호출이 오작동할 때 런타임 트레이스를 검사합니다(트레이싱 활성화 필요).

로그 읽기

OS 관리 서비스의 경우 로그를 직접 테일하십시오:

revka service logs                  # last 50 lines (default)
revka service logs -n 100 --follow  # tail and stream

데몬 로그는 Homebrew의 var/revka/logs/ 디렉터리 또는 <config_dir>/logs/에 저장되며, 20 MB마다 순환되고 5개의 복사본을 유지합니다(daemon.stdout.log.1 … .5). 순환은 데몬 실행 중이 아닌 revka service start 시에 실행됩니다. 진단 중 더 자세한 로그가 필요하면 로그 레벨을 높이십시오:

RUST_LOG=debug revka daemon          # or revka=trace for Revka-only tracing

일반적인 장애

증상	예상 원인	해결 방법
게이트웨이가 0.0.0.0 / [::] 바인딩을 거부	공개 바인딩이 차단되어 있음	[gateway] allow_public_bind = true(또는 REVKA_ALLOW_PUBLIC_BIND=true)를 설정하거나 터널로 앞단에 배치하십시오. Expose your gateway with a tunnel을 참고하십시오.
컴포넌트가 restart_count가 증가하는 error를 표시	감독된 컴포넌트가 크래시 루프 중	로그를 확인하십시오; 컴포넌트 감독자는 재시작마다 지수적으로 백오프합니다(reliability.channel_initial_backoff_secs → channel_max_backoff_secs).
revka doctor가 채널/heartbeat/scheduler stale 보고	컴포넌트가 틱을 멈춤	해당 컴포넌트의 로그를 확인하십시오; 상태 파일이 오래된 경우(> 45초) 데몬을 재시작하십시오.
Distroless 컨테이너가 즉시 종료되거나 셸 도구 실패	:latest 이미지에 셸 없음	ghcr.io/kumihoio/revka:debian을 사용하십시오. Docker, Compose & one-click PaaS를 참고하십시오.
다수의 MCP 서버로 “Too many open files” 발생	파일 디스크립터 제한	서비스 유닛에 LimitNOFILE = 4096:8192가 설정됩니다; 제한이 적용되도록 서비스를 재설치하십시오(revka service install).
doctor가 kumiho_memory 누락 경고	사이드카가 kumiho_memory 패키지보다 이전 버전	~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0' 후 revka doctor를 다시 실행하십시오. Kumiho setup을 참고하십시오.
소스 업데이트 중 Cargo / 빌드 실패	툴체인 또는 빌드 의존성 누락	./install.sh --install-rust 및/또는 --install-system-deps를 실행하십시오; RAM이 적은 호스트에서는 --prefer-prebuilt 또는 CARGO_BUILD_JOBS=1을 사용하십시오.

로그 키워드 트리아지

로그를 읽을 때 서브시스템에 해당하는 키워드로 검색하십시오. 구조화된 로그 필드는 일관된 명명 패턴을 따릅니다:

키워드	의미
error / metric.errors_total	컴포넌트가 장애를 기록함; component 필드와 함께 확인하십시오.
tool.call	도구 실행 시작/종료 — 중단된 턴 추적에 유용합니다.
cache.hit / cache.miss	응답 캐시 동작(hot 인메모리 vs warm SQLite).
agent.start / agent.end	에이전트 호출 경계.
heartbeat	Heartbeat 틱 및 데드맨 스위치.

이벤트별 심층 검사를 위해 롤링 트레이스를 활성화하고 쿼리하십시오. 트레이스 페이로드에는 모델 출력이 포함될 수 있으므로 공유 호스트에서는 트레이싱을 비활성화 상태로 유지하십시오:

revka doctor traces --limit 50
revka doctor traces --event tool_call --contains "timeout"

전체 doctor 참고는 revka doctor, status & self-test에서, 트레이스 활성화 방법은 Observability & tracing에서 확인하십시오.

문제가 현재 진행 중인 경우

에이전트가 오작동하여 진단보다 즉각적인 중단이 필요한 경우 긴급 정지를 활성화하십시오: revka estop(전체 종료), 또는 revka estop --level network-kill과 같이 더 좁은 수준을 사용하십시오. revka memory & estop 및 OTP gating & emergency stop을 참고하십시오.

관련 페이지

revka doctor, status & self-test 이 페이지의 모든 트리아지 단계에서 사용하는 진단 명령입니다.

Observability & tracing 메트릭 백엔드, /metrics 엔드포인트, 런타임 트레이스 저장소.

Run as a background service launchd, systemd, OpenRC, Windows에서 Revka를 OS 서비스로 설치 및 관리합니다.

Docker, Compose & one-click PaaS 컨테이너 이미지, Compose, HEALTHCHECK, PaaS 템플릿.

revka install, update, migrate, completions & ACP revka update 플래그를 포함한 라이프사이클 명령.

Status, health, config & tools endpoints GET /health 및 GET /api/health 엔드포인트 전체 설명.