본문으로 건너뛰기
큐 사이에 멈춘 NCMEC 신고와 Cloudflare Workflows
목차

큐 사이에 멈춘 NCMEC 신고와 Cloudflare Workflows (2025-04)

원문 정보

매시간 실패한 신고를 되짚던 Reaper

실패한 신고를 다시 처리하려면 어디에서 멈췄는지부터 찾아야 했습니다. Cloudflare의 NCMEC 신고 시스템에서는 매시간 실행되는 cron 작업 Reaper가 실패한 신고를 다시 제출했는데, 재처리를 시작할 큐도 스스로 추론해야 했습니다. 신고는 어느 단계에서든 실패할 수 있었습니다.

NCMEC는 아동 성착취물(CSAM) 신고를 받는 미국의 실종·착취 아동 센터입니다. Cloudflare는 2010년 출범 때부터 이 기관과 협력해 왔습니다. 일반 이용자와 고객, 신뢰 기관이 Cloudflare 네트워크에서 발견한 악용 사례를 신고하면, 그중 소수인 CSAM 관련 신고에 Trust & Safety 팀이 가장 높은 우선순위를 부여합니다. 신고 내용과 보충 정보를 NCMEC에 전달하고, 해당하는 경우 관련 파일도 보냅니다.

팀이 이 시스템을 설계한 2024년 초에는 Cloudflare Workflows가 없었습니다. 비동기 작업을 관리할 도구로 Workers 플랫폼의 Queues를 선택했습니다. 입력을 검증하고 NCMEC API로 신고서를 만든 뒤, 해당하는 경우 R2에 보관된 파일을 가져와 업로드하고 신고를 완료 처리하는 흐름입니다. 각 단계에는 별도의 큐를 뒀습니다.

자동 재시도도 마련했습니다. 오류가 나면 메시지를 몇 차례 재시도한 뒤 신고를 실패로 처리하는 방식이었지만, 모든 오류가 다시 시도한다고 풀리는 것은 아닙니다. 외부 API가 잘못된 입력 때문에 계속 실패하거나 예상과 다른 형태의 응답을 돌려주는 경우가 그랬습니다. 신고는 중간 상태에 걸린 채 남았고, 개발자는 여러 큐의 로그를 오가며 원인을 찾아야 했습니다.

재시도를 책임지는 곳도 일정하지 않았습니다. 어떤 큐는 자체 재시도 로직을 갖췄고, 어떤 큐는 Reaper에 의존했습니다. 신고가 아직 파이프라인 중간에 있는지, 아예 사라졌는지를 알아보는 수단도 로그뿐이었습니다. 개발자가 실패한 신고를 직접 살피고 다시 제출하는 일이 잦았습니다.

Queues는 메시지를 옮기는 든든한 기반이었습니다. 하지만 처리 순서와 상태, 재시도를 조율할 오케스트레이터가 없어서 팀이 상태 관리와 큐 사이 메시지 전달까지 직접 구현해야 했습니다. 메시지 버스 위에 느슨하게 연결한 단계들이 끝까지 버텨 주기를 바라는 방식이었습니다. 대체로 동작했지만 이해하기 어렵고 쉽게 깨졌습니다.

필요한 것은 전체 처리 순서와 실패한 위치를 명확히 드러내는 도구였습니다. 당시에는 무거운 도구를 도입하거나 구성 요소를 연결하는 코드를 잔뜩 작성하지 않고 이를 구현할 마땅한 방법이 없었습니다. Cloudflare Workflows의 등장은 그 빈자리를 채울 기회였습니다.

멈춘 곳에서 이어 가는 ReportWorkflow

팀은 여러 큐가 서로 메시지를 넘기던 과정을 하나의 워크플로로 옮겼습니다. 이제 신고가 들어온 순간부터 완료할 때까지 Workflows가 전체 흐름을 조율합니다. 어느 단계에서 실패하더라도 이미 끝낸 처리를 반복하거나 파일을 다시 파싱하고 중복 업로드하지 않고, 멈춘 지점에서 이어 갈 수 있게 됐습니다.

처리 순서는 코드에 드러납니다. 단순화한 오케스트레이터인 ReportWorkflow는 WorkflowEntrypoint를 상속하고, run 안에서 각 작업을 step.do로 감쌉니다. 시작은 ‘Create Report’입니다. 들어온 신고를 검증하고 NCMEC에 신고서를 생성합니다.

파일 처리는 조건부입니다. hasImpoundedFiles가 참일 때만 ‘Gather Files’, ‘Upload Files’, ‘Add File Metadata’를 차례로 실행합니다. R2에 보관된 파일을 가져와 업로드를 준비하고, NCMEC API로 파일을 하나씩 전송한 뒤, 해시와 타임스탬프 같은 메타데이터를 신고서에 첨부하는 순서입니다.

파일 처리를 마치면 ‘Finalize Report’에서 신고를 완료로 표시합니다. 보관 파일이 없는 신고는 파일 관련 단계를 건너뛰고 마무리 단계로 넘어갑니다. 큐 사이의 메시지를 추적해야 알 수 있었던 처리 순서와 분기가 이제 하나의 워크플로 안에 모였습니다.

신고 한 건의 진행을 보여 주는 대시보드

코드에서 작업을 나누는 데서 끝나지 않습니다. Workflows 대시보드는 처리하는 신고마다 각 단계의 상태를 실시간으로 보여 줍니다. 실행 중인 워크플로와 완료한 워크플로를 확인하고, 실패했다면 어느 단계에서 문제가 생겼는지 바로 살펴볼 수 있습니다. 실패한 단계를 재시도하거나 워크플로를 종료하는 일도 버튼으로 처리합니다.

겉으로 멈춰 보이는 실행에도 사정이 있습니다. 대시보드에서 일부 워크플로가 느리거나 멈춘 듯 보이는 것은 실패한 단계를 지수 백오프로 재시도하기 때문입니다. 재시도 사이의 대기 시간을 늘려 가면서 불안정한 API 같은 일시적 문제를 사람의 개입 없이 넘깁니다.

이 변화로 팀은 신고 한 건의 여정을 조사하고 실패한 단계를 다시 실행할 도구를 갖췄습니다. 여러 큐의 로그에서 상태를 추론하던 때보다 디버깅이 쉬워졌고, 오류 처리와 모니터링도 개선됐습니다.

Workflow로 옮기는 기존 Workers 애플리케이션

이 사례와 가까운 적용 대상은 여러 단계로 이루어진 큰 애플리케이션, 또는 신고 처리 시스템처럼 비동기 흐름이 복잡해지기 시작한 기존 Workers 애플리케이션입니다. 이런 경우에는 대개 코드를 조금만 수정해 Workflow 안에 감쌀 수 있습니다.

사용하던 서비스에 접근하는 능력도 이어집니다. Workflows는 다른 Worker처럼 R2를 읽고 KV에 쓰며, D1을 조회하거나 다른 API를 호출할 수 있습니다. 여기에 비동기로 오래 실행되는 작업을 조율하도록 설계한 실행 방식이 더해집니다. 시작용 프로젝트로는 workflows-starter 템플릿을 제공합니다.

마지막 수정 일자