미니PC 서버의 장애 확인 순서와 복구 기준

한강자리 백엔드는 집에 둔 미니PC에서 운영한다. App Store에 공개한 앱과 위젯은 이 서버의 API, 수집 worker와 알림 경로에 의존한다. 주차 정보가 오래되거나 알림이 늦을 때 원인 구간을 찾을 수 있도록 사용자 요청에서 원천 데이터까지 확인 순서를 정했다.

사용자 요청부터 확인하는 운영 기준

초기 확인은 API와 worker 실행, DB·Redis 연결과 앱 응답에 집중했다. 공개 뒤에는 사용자 요청 경로, 특정 API, worker 수집, 원천 최신성과 cache 순서로 장애 범위를 좁혔다.

flowchart LR
  Client["iOS 앱 / 위젯"] --> Public["사용자 요청 경로<br/>엣지 · 인그레스"]
  Public --> API["API 서비스"]
  API --> Data["Postgres / Redis"]
  Workers["워커<br/>수집 · 예측 · 알림"] --> Data
  Data --> API
  Runtime["GitOps 상태"] --> API
  Runtime --> Workers
  Signals["메트릭 · 로그 · 대시보드"] --> API
  Signals --> Workers

이 경로 중 하나가 멈추면 앱은 요청에 실패하거나 오래된 정보를 표시한다. 호스트 크기와 관계없이 각 구간의 상태와 마지막 성공 시각을 확인할 수 있어야 했다.

사용자 요청과 관리 경로의 분리

사용자 API와 관리 접근에는 서로 다른 인증·노출 정책을 적용한다. 앱이 호출하는 API는 사용자 요청 경로로 공개하고 관리 접근은 별도의 보호 정책으로 제한한다.

장애를 분류할 때도 사용자 요청 경로, 실행 중인 서비스와 운영 제어 경로를 따로 확인한다.

Git에 남긴 서버 상태

배포할 이미지와 Kubernetes 리소스 상태는 Git에 남기고 GitOps controller가 실행 환경에 반영하게 했다.

flowchart LR
  Build["앱 저장소<br/>CI 테스트 · 빌드"] --> Image["버전 붙은 이미지"]
  Build --> Desired["원하는 배포 상태"]
  Image --> Sync["GitOps 동기화"]
  Desired --> Sync
  Sync --> Verify["API · 워커 · 데이터 서비스<br/>배포 직후 확인"]

장애 확인에는 다음 기록을 사용한다.

• 배포한 image를 commit과 연결해 추적한다.
• 실제 서버가 Git에 적힌 상태와 달라졌는지 볼 수 있다.
• 배포 상태와 배포 직후 확인 결과를 함께 기록한다.
• 서버에서 직접 수행한 변경도 별도 운영 기록으로 남긴다.

Git 상태만으로 DB migration, worker 교체 순서, 운영 설정과 외부 원천 실패를 확인할 수는 없다. 이 항목은 배포 직후 확인과 운영 대시보드에서 따로 본다.

확인 순서에서 시작한 대시보드

대시보드에는 장애 때 확인할 순서에 맞춰 다음 신호를 배치했다.

• 사용자 API가 살아 있는가.
• API는 살아 있는데 특정 화면용 응답만 실패하는가.
• worker가 원천 데이터를 계속 수집하고 있는가.
• 마지막 성공 시각이 오래됐다고 볼 시간을 넘었는가.
• cache 적중/실패 비율이 비정상적으로 변했는가.
• 예측 run이 최신인가.
• push outbox가 쌓이고 있지 않은가.
• 백업은 만들어졌고 복구가 검증됐는가.

API 전체 상태, 특정 화면용 응답, worker, 원천 최신성과 cache fallback을 같은 순서로 배치했다. 각 그래프는 다음에 확인할 로그나 컴포넌트를 좁히는 데 사용한다.

장애 때 따라갈 경로

장애가 보이면 요청이 지나가는 구간을 따라 상태를 나눠 본다.

flowchart TD
  Symptom["사용자 제보 또는 스모크 실패"] --> Public{"사용자 API 정상?"}
  Public -->|아니오| Path{"엣지/인그레스 경로 문제인가?"}
  Path -->|예| Network["사용자 요청 경로 확인"]
  Path -->|아니오| Runtime["실행 환경 확인"]
  Public -->|예| Feature{"특정 화면만 실패하는가?"}
  Feature -->|예| Data{"원천 최신성 또는 캐시 문제인가?"}
  Data -->|예| Worker["워커 · 수집 · 캐시 확인"]
  Data -->|아니오| API["API 응답 · DB 조회 확인"]
  Feature -->|아니오| Client["앱 캐시 · 위젯 스냅샷 확인"]

대시보드는 edge, API, worker와 원천 데이터 순으로 상태를 확인하게 구성했다. 사용자 요청 경로 장애와 원천 데이터 지연에 대응할 컴포넌트를 이 순서로 구분한다.

복구로 검증하는 백업

백업은 별도 환경에서 데이터를 읽어 복구하는 절차로 검증한다. 복구 우선순위를 정하려고 데이터를 다음처럼 나눴다.

데이터	성격
공공데이터 원천에서 다시 가져올 수 있는 값	다시 만들 수 있음
사용자 알림 설정, push subscription	복구해야 하는 사용자 데이터
앱 이벤트와 audit	운영을 되짚어 볼 근거
forecast/backtest 이력	예측을 되짚어 볼 근거
cache	다시 만들 수 있음

사용자 알림 설정과 push subscription을 먼저 복구하고 cache와 다시 수집할 수 있는 공공데이터는 다시 만든다. audit과 forecast 이력은 장애·예측 분석에 필요한 보존 데이터로 분류했다.

복구 완료 조건

복구 완료 조건에는 API와 worker 실행, 원천 최신성, cache fallback, push backlog와 데이터 복구 결과가 포함된다. 미니PC 한 대에서 이 경로를 운영하므로 호스트 자원과 애플리케이션 상태도 같은 확인 순서에서 본다.