Cloudflare Durable Objects binding 삭제: 참조 Worker를 배포 전에 찾는 방법

Cloudflare Durable Objects binding 삭제를 준비할 때 가장 위험한 누락은 다른 Worker가 해당 namespace를 계속 참조하는 상태다. 선언형 exports 흐름에서는 소유 Worker가 state: "deleted" tombstone을 배포하면 Cloudflare가 같은 계정의 다른 Worker binding을 검사한다. 참조가 남아 있으면 삭제를 실행하지 않고 배포를 차단하며 referencing_scripts에 수정할 Worker 이름을 돌려준다.

다만 이것은 언제든 호출할 수 있는 읽기 전용 참조 목록이나 dry-run이 아니다. 실제 lifecycle 배포의 reconciliation 단계에서 작동하며, 참조가 없다면 namespace와 저장 데이터가 곧바로 영구 삭제될 수 있다. 이 글은 2026년 8월 4일 기준 Cloudflare 공식 변경 기록, class exports 문서, Wrangler 설정과 API 스키마를 교차 확인한 결과다. 실제 계정에서 삭제 배포를 재현하지 않았으므로 터미널 출력 형식과 Dashboard UI는 공식 문서 범위까지만 다룬다.

참조 목록은 삭제 의도를 담은 배포에서 나온다

Durable Object의 cross-Worker 참조는 단순한 코드 import가 아니라 배포된 Worker metadata의 binding 관계다. durable_objects.bindings에는 binding의 name과 class_name이 들어가며, 다른 Worker가 정의한 class를 가리킬 때는 script_name이 추가된다. Cloudflare는 exports 배포 때 코드에 export된 class, lifecycle 설정, 이미 provision된 namespace를 비교해 상태를 조정한다. Wrangler Durable Objects 설정

소유 Worker가 기존 class를 deleted로 선언했는데 같은 계정의 다른 Worker metadata가 그 namespace를 계속 가리키면 tombstone_delete_blocked_by_external_bindings 오류로 배포가 멈춘다. 이때 반환되는 referencing_scripts는 배포된 Worker script 이름이다. 소스 저장소 경로나 실제 호출 코드의 파일·행 번호까지 찾아주는 기능은 아니다. Cloudflare class exports 오류 레퍼런스

소유 Worker 자체도 정리해야 한다. tombstone을 두기 전에 코드에서 class를 제거하고, 같은 Worker의 durable_objects.bindings에서도 해당 binding을 빼야 한다. class가 코드에 남아 있으면 tombstone_delete_class_still_in_code로 차단되므로 외부 Worker 목록만 비웠다고 삭제 준비가 끝나는 것은 아니다.

삭제 전에 안전하게 밟아야 할 배포 순서

1. class와 소유 Worker, environment를 고정한다

일반 namespace 목록 API는 namespace의 id, class, name, 소유 script, use_sqlite를 확인하는 inventory로 쓸 수 있다. 그러나 공식 응답 필드에는 참조 Worker의 역목록이 없다. 먼저 삭제할 class와 소유 Worker를 고정하는 용도로 사용해야 한다. Durable Objects List Namespaces API

top-level과 named environment도 구분한다. Wrangler environment에 따라 Worker 이름이 달라질 수 있고, 각 environment는 별도의 provisioned namespace 상태를 유지한다. tombstone 역시 선언한 environment 범위에 적용되므로 env.* 설정과 script_name을 함께 확인해야 한다. Durable Objects environments

2. 데이터 보존 여부를 먼저 결정한다

deleted tombstone이 적용되면 namespace와 저장 데이터는 영구 삭제되며 Trash나 soft delete가 없다. 참조 binding 검사를 통과했다는 사실은 데이터 보존 승인을 뜻하지 않는다. 필요한 데이터를 복사했는지, 삭제 대상과 environment가 맞는지 확인한 뒤에만 다음 단계로 넘어가야 한다.

3. 소유 Worker에 tombstone을 선언해 배포한다

코드와 소유 Worker binding을 제거한 뒤 기존 class 이름을 다음처럼 deleted 상태로 둔다.

{
  "exports": {
    "OldDurableObject": {
      "type": "durable-object",
      "state": "deleted"
    }
  }
}

그다음 npx wrangler deploy를 실행한다. 외부 binding이 남아 있다면 배포가 차단되고 참조 Worker 이름이 반환된다. 공식 문서에는 이 관계만 미리 읽는 별도 명령이 제시돼 있지 않으며, wrangler deploy --dry-run이 원격 참조를 검사한다는 근거도 확인되지 않았다. 따라서 데이터 보존 확인 전에 “목록만 보겠다”는 목적으로 이 배포를 실행하면 안 된다.

4. 참조 Worker를 먼저 수정하고 재배포한다

referencing_scripts에 나온 각 Worker의 durable_objects.bindings에서 삭제 대상 class_name과 script_name 관계를 제거한 뒤 해당 Worker를 먼저 배포한다. rename이나 transfer가 목적이라면 binding을 새 대상으로 바꾸고 선행 배포한다.

로컬 wrangler.jsonc, wrangler.toml과 저장소 검색은 후보 탐색에는 유용하다. 하지만 다른 저장소, 과거 배포, environment override를 놓칠 수 있으므로 계정에 실제 배포된 상태의 최종 판단은 reconciliation이 반환한 script 목록을 기준으로 해야 한다.

5. 소유 Worker의 삭제 배포를 다시 실행한다

참조 Worker 배포가 모두 끝난 다음 소유 Worker의 tombstone 배포를 다시 실행한다. 조건을 통과하면 namespace와 데이터가 삭제된다. 이후 reconciliation의 removable_entries 또는 CLI의 Safe to remove from exports 목록에 tombstone이 나오면 다음 설정 편집에서 제거할 수 있다. Cloudflare reconciliation 출력 설명

CLI와 API에서는 보이지만 전용 Dashboard 목록은 확인되지 않았다

확인 표면	확인할 수 있는 내용	한계
wrangler deploy	structured error, Referencing scripts, Safe to remove from exports	실제 배포 흐름이며 읽기 전용 preview가 아니다
Workers API 응답 스키마	exports_reconciliation, referencing_scripts, removable_entries	실제 lifecycle 작업은 해당 API 작업의 인증과 endpoint 문서를 함께 따라야 한다
List Namespaces API	namespace와 소유 script 정보	참조 Worker 역목록 필드는 문서화되지 않았다
Cloudflare Dashboard	이번 조사에서 전용 참조 목록의 공식 설명을 확인하지 못했다	UI 부재를 영구적인 사실로 단정할 수 없다
로컬 설정·저장소 검색	class_name, script_name, binding 후보	실제 배포 metadata 전체를 증명하지 못한다

자동화에서는 Workers API 응답의 exports_reconciliation.info[].referencing_scripts와 removable_entries가 구조화된 판단 근거가 된다. 사람이 작업할 때는 Wrangler 출력이 주 표면이다. 어느 경우든 일반 namespace inventory를 참조 관계 조회 API로 오해하지 않는 것이 중요하다. Workers Scripts API

exports와 legacy migrations를 섞으면 안 된다

이 보호 장치는 선언형 exports lifecycle의 기능이다. legacy 흐름은 tag가 있는 누적 migrations 배열과 deleted_classes를 사용하며, 한 Worker에서 migrations와 exports를 동시에 사용할 수 없다. exports로 전환한 뒤 legacy migrations로 돌아갈 수도 없다는 제약이 있다. Legacy migration 문서

기존 legacy Worker라면 참조 목록 기능만 보고 곧바로 설정을 바꾸기보다 현재 storage backend와 live class 상태를 먼저 확인해야 한다. 공식 문서는 new_sqlite_classes로 생성한 class는 sqlite, new_classes로 생성한 class는 legacy-kv로 대응해 live exports map으로 옮기는 흐름을 설명한다. 이 전환은 데이터를 옮기는 storage migration과 같은 작업이 아니다.

또한 wrangler versions upload는 lifecycle 변경을 적용하지 않고 exports가 있으면 실패하므로 원격 preview로 쓸 수 없다. exports lifecycle 변경은 gradual deployment를 지원하지 않으며 control plane에서 atomic하게 적용되고, lifecycle 변경 이전 version으로 rollback할 수도 없다. 삭제 전에 되돌리기 계획 대신 데이터 보존과 대상 검증을 끝내야 하는 이유다. Cloudflare exports 제약

공개 날짜보다 현재 동작 조건을 기준으로 판단한다

편집 단계에서 제시된 2026년 7월 20일은 현재 공식 변경 기록과 일치하지 않는다. 2026년 8월 4일 확인 기준 Workers product changelog는 관련 exports 항목을 7월 4일로 표시하고, 개별 공지 URL에는 6월 30일이 들어 있다. 반면 Durable Objects changelog의 7월 20일 항목은 SQLite namespace의 총 저장량 차트다. 날짜 표기가 바뀌었을 가능성은 남아 있으므로 참조 Worker 열거 기능의 공개일을 7월 20일로 단정하지 않는 편이 정확하다. Workers changelog, Durable Objects changelog

운영 판단은 간단하다. exports를 쓰는 같은 계정의 cross-Worker binding이라면 삭제 배포의 차단 오류를 안전장치로 활용할 수 있다. 그러나 독립 inventory 조회, Dashboard 전용 화면, 다른 계정까지의 탐색, rollback을 기대하는 절차에는 맞지 않는다. 실제 배포 전에는 최신 공식 exports 문서를 다시 확인하고, 배포 전후 검증이 필요하다면 Cloudflare Workers 통합 테스트 구성 방법도 함께 점검하는 것이 좋다.

FAQ

참조 Worker 목록을 삭제 배포 전에 별도 API로 조회할 수 있나?

공식 문서에서는 목록 전용 read-only endpoint를 확인할 수 없다. referencing_scripts는 exports lifecycle 배포의 reconciliation 결과와 Workers API 응답 스키마에 문서화돼 있다. “배포 전”은 삭제가 적용되기 전 검증 단계에서 차단된다는 뜻이지, 안전한 독립 조회를 뜻하지 않는다.

같은 소유 Worker의 binding도 referencing_scripts에 표시되나?

공식 설명에서 referencing_scripts는 같은 계정의 다른 Worker가 가진 외부 binding을 가리킨다. 소유 Worker 자체는 코드에서 class를 제거하고 해당 Worker의 binding도 먼저 삭제해야 하며, class가 남으면 별도의 tombstone_delete_class_still_in_code 오류로 차단된다.

tombstone은 언제 exports에서 제거해도 되나?

삭제가 적용된 뒤 reconciliation의 removable_entries 또는 CLI의 Safe to remove from exports에 해당 항목이 표시될 때 다음 설정 편집에서 제거할 수 있다. 삭제 성공 전에 tombstone을 먼저 지우면 lifecycle 의도가 완성되지 않는다.

legacy migrations 사용자도 같은 보호 기능을 바로 쓸 수 있나?

같은 기능을 legacy deleted_classes의 보편 동작으로 설명할 수 없다. exports와 migrations는 함께 쓸 수 없고 exports 전환은 되돌릴 수 없으므로, 현재 storage backend와 live class map을 확인한 뒤 별도의 전환 절차로 판단해야 한다.

staging의 tombstone이 production namespace도 삭제하나?

공식 문서상 각 environment는 별도의 provisioned namespace 상태를 유지하며 tombstone은 선언된 environment 범위에 적용된다. 다만 script_name이 top-level Worker의 Objects를 가리키는 설정이 있을 수 있으므로 Worker 이름과 환경 블록을 함께 확인해야 한다.