신뢰성을 가르쳐준 9가지 버그: 제로 비용 하이브리드 AI 시스템 사후 분석

local VM  ──(일일 작업 + 하트비트 스탬프)──▶  공유 시트  ◀──(23:00 읽기)──  cloud VM (수동)
   └──────────────── 토큰 게이트 HTTPS 동기화 (last-write-wins) ────────────────┘

0 23 * * *  cd /opt/app && . /opt/app/.env && /opt/app/venv/bin/python -m app. daily >> /var/log/app.log 2>&1

# 3.11에서는 구문 분석에 실패함
msg = f

⚠️ `[IMG:N]` 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

**핵심 요약.** '내 컴퓨터에서는 되는데'라는 말에는 항상 버전 번호가 붙어 있습니다. 환경 간 런타임(runtime)을 일치시키거나, 지원할 수 있는 가장 낮은 버전으로 작성해야 합니다. 런타임 패리티(Runtime parity)는 세부 사항이 아니라 계약(contract)의 일부입니다.

## 버그 4 — SQLite가 인덱스가 부분적(partial)이라서 upsert를 거부함

**증상.** 동기화 기록에 대한 `ON CONFLICT` upsert 작업이 완전히 실패했습니다. 오류 메시지는 충돌 대상 지점을 가리켰습니다.

**조사.** `sync_id` 컬럼에는 고유 인덱스(unique index)가 있었으므로, upsert는 이를 기준으로 삼을 중재자(arbiter)를 가져야 했습니다. SQLite 문서를 더 주의 깊게 읽어보니: upsert의 충돌 대상은 특정 종류의 인덱스와 매핑되어야 합니다.

**근본 원인.** 해당 고유 인덱스는 **부분적(partial)** 인덱스였습니다 (즉, `WHERE` 절을 가지고 있었습니다). SQLite는 부분적 인덱스를 upsert 충돌 중재자로 사용하지 않습니다. 이는 제 SQL의 버그라기보다는 '고유 인덱스'와 'upsert 중재자'가 같은 것이라는 저의 가정에 대한 오류였습니다.

**해결책.** 해당 인덱스를 **전체(full)** 고유 인덱스로 변환하고, 시작 시 기존 부분적 인덱스를 감지하여 기존 데이터베이스를 제자리에서 복구하는 자체 치유 마이그레이션(self-healing migration)을 추가했습니다. 

**핵심 요약.** upsert 중재자는 정밀한 요구 사항을 가지며, 엔진별로 다릅니다. 데이터베이스가 '되어야' 할 것을 거부할 때는 임시 방편(workaround)을 찾기 전에 정확한 제약 조건(constraint)을 읽어야 합니다.

## 버그 5 — 영원히 커지는 동기화 테이블 (네임스페이스 바운스)

**증상.** 매일 동기화할 때마다 대화 테이블의 크기가 커졌습니다. 새로운 활동 때문이 아니라, _같은_ 기록들이 증식했기 때문입니다.

**조사.** 저는 여러 번의 동기화 라운드를 거치며 개별 기록들을 추적했습니다. 로컬에서 시작된 기록은 클라우드에 나타났고, 다시 _로_ 로컬로 돌아왔으며, 또다시 클라우드로 나갔습니다. 이 모든 이동(hop)마다 약간씩 다른 ID를 가졌습니다. 시스템은 각 이동을 완전히 새로운 기록으로 간주하고 삽입했습니다.

**근본 원인(Root cause).** 내보낼 때마다 기록의 네임스페이스가 재설정되었습니다 (`local: N` → `cloud: M` → `local: P` → …). 신원이 매 왕복 주기마다 바뀌었기 때문에, 어떤 것도

이것이 제가 가장 좋아하는 사례입니다. 왜냐하면 버그가 미묘했고 증상이 이상했기 때문입니다.

**증상.** 장기간 로컬 시스템 장애가 발생했을 때, 클라우드 백업이 일일 작업을 전달했지만 격일로만 이루어졌습니다. 1일차: 전달됨. 2일차: 건너뜀. 3일차: 전달됨. 마치 메트로놈처럼요.

**조사.** 페일오버 로직은 각 성공적인 실행 후 로컬 노드가 찍는 하트비트를 읽습니다. 만약 로컬이 약 25시간 동안 침묵했다면, 클라우드는 이를 오프라인으로 선언하고 작업을 인계받습니다. 그럼 왜 진동(oscillation)이 발생했을까요? 저는 누가 하트비트를 작성하는지 살펴보았습니다. 클라우드가 페일오버를 할 때도 '로컬 존재' 하트비트를 찍고 있었던 것입니다.

**근본 원인. ⚒‍⚒** 페일오버 푸시 역시 로컬 존재 신호를 찍었습니다. 그래서 클라우드가 1일차를 커버한 후, 하트비트는 '로컬이 살아있다!'라는 신선한 상태가 되었고, 2일차에 클라우드는 충실히 건너뛰었습니다. 하지만 실제로는 로컬이 여전히 다운되어 있었기 때문에, 3일차에는 하트비트가 다시 오래된 것이었고, 클라우드는 또다시 페일오버를 했습니다. 존재 신호는 잘못된 주체가 작성했기 때문에 거짓말을 하고 있던 것입니다.

**수정.** 로컬 역할만이 로컬 존재 하트비트를 찍어야 합니다. 페일오버 푸시는 자신의 역할을 수행할 뿐, 로컬 하트비트는 건드리지 않아야 합니다. 이제 장기간의 장애는 지속적인 장애로 간주되며, 로컬이 돌아올 때까지 클라우드가 매일을 커버합니다.

**교훈.** 존재 신호는 반드시 그 존재를 나타내는 주체에 의해서만 작성되어야 합니다. 두 번째 주체가 다른 사람을 대신해 '나 여기 있어'라고 쓸 수 있게 되는 순간, 여러분의 생존 감지(liveness detection)는 오염됩니다. 이는 페일오버를 넘어 일반화되므로, '마지막으로 본 시간(last seen)' 필드가 있는 곳이라면 어디든 누가 그것을 건드릴 수 있는지 경계해야 합니다.

## 버그 8 — 일시적인 503 오류로 하루 전체가 손실되었습니다

**증상.** 어느 날은 출력이 전혀 없었습니다. 상위 모델 제공업체에서 작업이 실행되는 바로 그 순간에 짧은 문제가 발생했습니다.

**조사.** 로그에는 일일 주기 동안 `503` 에러가 짧게 터진 기록이 있었습니다. 제 재시도 로직이 너무 적은 시도로 인해 포기했고, 몇 분간 지속된 일시적인 장애가 하루 전체를 놓치는 결과를 초래했습니다.

**근본 원인(Root cause). "★ ★" 얇은 재시도(Thin retries).** 최소한의 백오프(backoff)를 가진 단일 예약 시도는 짧은 5xx 버스트(burst)조차 견딜 수 없으며, 하루에 한 번 실행되는 작업은 두 번째 기회 자체가 없습니다.

**수정 사항(Fix).** 재시도/백오프 로직을 강화했습니다: 최대 백오프를 적용한 5번의 시도(대략 20/40/60/90/120초)로, `500/502/503/504/429` 및 네트워크 오류를 처리합니다.

**시사점(Takeaway).** 간헐적으로 실행되는 중요한 작업의 경우, 재시도 로직은 선택적인 개선 사항이 아니라