📚 국립중앙도서관 API로 25년치 도서 데이터 백필 파이프라인 만들기

에어플로우 없이, 끊겨도 자동으로 이어받는 신뢰성 높은 ETL을 설계한 이야기

1. 만들게 된 이유

국립중앙도서관(NLK) 은 서지정보API를 통해 한국에 등록된 모든 도서의 서지 데이터를 공개하고 있다.

나는 2000년 1월부터 2024년 12월까지, 즉 25년치 전체 데이터를 PostgreSQL(Supabase) 에 저장해 보고 싶었다.

처음엔 단순히 “API를 루프 돌리면 되겠지” 싶었다. 하지만 실제로는 아래 문제들을 해결해야 했다.

• 호출 제한(rate limit)과 연결 끊김(timeout)
• 25년 × 12개월 = 300개월 분량의 데이터
• EC2 연결이 중간에 끊기는 문제
• 수백만 건 JSON의 중복 삽입 방지

2. NLK API 이해하기

참고: 국립중앙도서관 서지정보 API 문서

• 인증키(cert_key) 필요
• 요청변수: PUBLISH_PREDATE
• 일정 수의 page_size = 100 요청 가능

즉, 전체 데이터를 한 번에 가져올 수 없었다. 그래서 ‘월 단위 파티셔닝’ 전략을 세웠다 — 한 달씩 명확한 기간으로 나눠 수집하기.

3. 첫 번째 프로토타입 — 단순한 Fetcher

fetch_pages.py는 이렇게 동작했다.

• 페이지를 순서대로 요청
• JSON을 raw_nl_books 테이블에 삽입
• 콘솔에 진행 로그 출력

작동은 됐지만, 아래와 같은 문제가 있었다.

• 중간에 에러 나면 처음부터 다시 해야 함
• EC2 재부팅 시 진행상황 사라짐
• 매달 스크립트를 수동으로 수정해야 함

4. 수동에서 자동으로

원하는 시스템은 다음과 같았다.

1. 2000년부터 2024년까지 모든 달 자동 수집
2. 네트워크 끊김에도 재시작
3. 중복 없는 안전한 삽입
4. 며칠간 무인으로 안정 작동

오케스트레이션 도구를 고려해보았다. 가볍고 단단한 구조가 필요했다.

5. 고려한 오케스트레이션 옵션

systemd 를 선택해다. 리눅스에 기본 내장되어 있고, 다음을 모두 지원한다.

• 실패 시 자동 재시작
• journalctl 로그 조회
• 서비스 시작·중지 간단
• 추가 설치나 DB 설정 불필요

6. 체크포인트 설계

간단한 상태 저장 폴더 하나를 만들었다. ~/nlk-state/

각 달마다 두 개의 파일이 생긴다.

2000-01.page   # 마지막으로 처리한 페이지
2000-01.done   # 해당 달 완료 표시

시스템이 중간에 멈추더라도 다음 실행 시 .page를 읽어 바로 이어서 시작한다.

파일 기반으로 한 이유:

• DB 락(lock) 문제 없음
• 눈으로 바로 확인 가능
• DB 연결이 안 돼도 진행 상태 유지

7. 월별 러너 설계

fetch_pages_month.py를 확장해 다음 기능을 넣었다.

• 지정한 월 범위(start_publish_date → end_publish_date) 요청
• 성공 시 .page 갱신
• 타임아웃 시 비정상 종료 (systemd가 재시작)
• rec_hash = md5(source_record::text)로 중복 방지

이제 각 달이 깔끔히 종료되며, 결과가 없으면 자동으로 다음 달로 넘어간다.

8. 전체 관리자: run_all_months.py

이 스크립트가 전체 25년 루프를 돌린다.

2000-01 → 2000-02 → … → 2024-12

각 달에 대해:

• .done 있으면 스킵
• 없으면 fetch_pages_month.py 실행
• 성공 시 .done 생성
• 실패 시 종료 (systemd가 재시작하여 같은 달부터 재개)

왜 한 파일에 다 넣지 않고 “매니저 + 러너”로 나눴나? → 책임 분리가 명확해진다. 월별 스크립트는 API·DB에 집중하고, 매니저는 흐름 제어와 체크포인트만 맡는다.

9. 슈퍼바이저: systemd

nlk-history.service 파일은 이렇게 구성했다.

[Service]
User=ec2-user
WorkingDirectory=/home/ec2-user/kbook-data-pipeline
ExecStart=/home/ec2-user/kbook-data-pipeline/venv/bin/python /home/ec2-user/kbook-data-pipeline/scripts/run_all_months.py
Restart=on-failure
RestartSec=30s

왜 systemd를 선택했나?

• 비정상 종료 시 자동 재시작
• UI나 데이터베이스 필요 없음
• journalctl로 로그 확인 용이
• 장시간 EC2 작업에 최적

마지막 달이 끝나면 정상 종료 코드(0)로 종료되고, systemd도 깔끔히 정지한다.

10. 파이프라인 검증

정상 작동 확인법:

• .page 파일이 주기적으로 갱신됨
• 달이 끝나면 .done 생성
• EC2 재부팅 후에도 같은 위치에서 재개
• rec_hash로 중복 삽입 없음 확인

전체 실행 시간: 약 30분 × 300개월 = 약 6일 연속 수집

11. 해결한 문제들

12. 결과

일주일 무인 실행 후:

• ✅ 2000–2024년 전체 데이터 Postgres 저장
• ✅ 중복 없는 삽입
• ✅ 네트워크 오류에도 자동 복구
• ✅ 완전한 무인 파이프라인

총 약 600만 건의 도서 기록을 안정적으로 수집 완료했다.

13. 배운 점

1. 단순함이 확장성이다. — 한 방향으로만 흘러가는 작업엔 가벼운 스크립트가 대형 프레임워크보다 낫다.
2. 명시적 체크포인트 > 무한 재시도.
3. systemd는 과소평가된 운영 자동화 도구다.
4. 처음부터 “복구 가능성(resumability)” 을 염두에 둬라. 최적화는 그다음이다.