본 콘텐츠는 사용자의 편의를 고려해 자동 기계 번역 서비스를 사용하였습니다. 영어 원문과 다른 오류, 누락 또는 해석상의 미묘한 차이가 포함될 수 있습니다. 필요하시다면 영어 원문을 참조하시기를 바랍니다.
원격 바인딩은 로컬에서 시뮬레이션된 리소스 대신 Cloudflare 계정에 배포된 리소스에 연결하는 바인딩입니다.그리고 최근에는 원격 바인딩을 일반 사용자도 모두 사용할 수 있다고 발표했습니다.
이번 출시를 통해 이제 로컬 컴퓨터에서 Worker 코드를 실행하면서 R2 버킷 및 D1 데이터베이스 와 같은 배포된 리소스에 연결할 수 있습니다. 즉, 반복할 때마다 배포하는 오버헤드 없이 실제 데이터 및 서비스에 대해 로컬 코드 변경 사항을 테스트할 수 있습니다.
이 블로그 게시물에서는 Cloudflare가 이를 어떻게 구축하여 원활한 로컬 개발 경험을 만들었는지에 대한 기술적 세부 사항을 살펴봅니다.
Cloudflare Workers 플랫폼 의 핵심은 무언가를 테스트할 때마다 코드를 배포하지 않고도 로컬에서 코드를 개발할 수 있는 기능이었습니다. 지원 방식은 수년에 걸쳐 크게 바뀌었습니다.
먼저 wrangler dev를 원격 모드로 실행했습니다. 이는 코드를 변경할 때마다 Cloudflare의 네트워크에서 실행되는 Worker의 미리 보기 버전을 배포하고 연결하여 작동하므로 개발하면서 테스트할 수 있습니다. 그러나 원격 모드는 복잡하고 유지 관리하기 어려우므로 완벽하지는 않습니다. 또한 개발자 경험은 느린 반복 속도, 불안정한 디버깅 연결, 다중 작업자 시나리오에 대한 지원 부족 등 아쉬운 점이 많습니다.
이러한 문제 등은 2023년 중반에 출시되어 wrangler dev의 기본 경험이 된 Workers의 완전한 로컬 개발 환경에 상당한 투자를 하게 된 동기가 되었습니다. 그 이후로 저희는 Wrangler, Cloudflare Vite 플러그인(@cloudflare/vitest-풀-workers와 함께), Miniflare 등을 포함한 로컬 개발 경험에 많은 노력을 기울였습니다.
그래도 원래 원격 모드는 wrangler dev --remote 플래그를 통해 계속 액세스할 수 있었습니다. 원격 모드를 사용하면 완전한 로컬 경험의 모든 DX 이점과 지난 몇 년 동안 이룬 개선 사항이 무시됩니다. 그렇다면 사람들이 여전히 Cloudflare를 이용하는 이유는 무엇일까요? 이를 통해 로컬 개발 중에 원격 리소스에 바인딩하는 고유한 핵심 기능이 가능해집니다. 로컬 모드를 사용하여 로컬에서 Worker를 개발하면 모든 바인딩 이 로컬(초기에는 비어 있음) 데이터를 사용하여 로컬에서 시뮬레이션됩니다. 이는 테스트 데이터로 앱의 로직을 반복할 때 환상적입니다. 하지만 팀과 리소스를 공유하고자 하는 경우, 실제 데이터와 연계된 버그를 복제하려는 경우, 앱이 실제 리소스로 프로덕션 환경에서 작동한다는 확신을 갖고자 할 때 그것만으로는 충분하지 않을 때가 있습니다. .
이러한 점을 고려하면, 다음과 같은 기회를 포착했습니다. 원격 모드의 가장 좋은 부분(즉, 원격 리소스 액세스)을 Wrangler 개발자에게 제공하는 경우 Workers 개발에 단일 단일 흐름이 있으므로 많은 사용 사례를 가능하게 하면서도 로컬 개발에서 수행한 발전에서 사람들을 가로막지 못할 것입니다. 그렇게 했죠!
Wrangler v4.37.0부터는 단순히 remote 옵션을 지정하는 것만으로 바인딩별로 원격 또는 로컬 리소스를 사용할지 여부를 선택할 수 있습니다. 이 점을 다시 강조하는 것이 중요합니다.remote: true만 추가하면 됩니다! API 키와 자격 증명을 복잡하게 관리할 필요 없이 Wrangler와 Cloudflare API 사이의 기존 Oauth 연결을 사용하기만 하면 됩니다.
{
"name": "my-worker",
"compatibility_date": "2025-01-01",
"kv_namespaces": [{
"binding": "KV",
"id": "my-kv-id",
},{
"binding": "KV_2",
"id": "other-kv-id",
"remote": true
}],
"r2_buckets": [{
"bucket_name": "my-r2-name",
"binding": "R2"
}]
}
매의 눈을 가진 사람들은 일부 바인딩이 이미 이러한 방식으로 로컬 개발자의 원격 리소스에 액세스하는 방식으로 작동한다는 사실을 깨달았을 것입니다. 가장 두드러진 점은 AI 바인딩 이 일반 원격 바인딩 솔루션의 미래를 개척했다는 점입니다. Workers AI와 함께 사용할 수 있는 다양한 모델을 모두 지원하는 진정한 로컬 환경은 실용적이지 않고 AI 모델을 대량으로 미리 다운로드해야 하므로 도입부터 AI 바인딩은 항상 원격 리소스에 연결되었습니다.
Workers 내의 서로 다른 제품(예: Images 및 Hyperdrive)에는 원격 바인딩과 유사한 것이 필요하다는 것을 깨닫고 서로 다른 솔루션을 약간의 패치워크로 만들었습니다. Cloudflare는 모든 바인딩 유형에서 작동하는 단일 원격 바인딩 솔루션으로 통합했습니다.
저희는 개발자가 프로덕션 Workers 코드를 변경하지 않고도 원격 리소스에 정말 쉽게 액세스할 수 있도록 하기 위해 Worker의 사용 지점에서 원격 리소스에서 데이터를 가져와야 하는 솔루션을 찾았습니다.
const value = await env.KV.get("some-key")
위의 코드는 env.KV KV 네임스페이스의 "some-key" 값에 액세스하는 것을 보여줍니다. 이 값은 로컬에서 사용할 수 없으며 네트워크를 통해 가져와야 합니다.
이것이 우리의 요구 사항이라면 어떻게 달성할 수 있을까요? 예를 들어 사용자가 Worker에서 env.KV.put("key","value")를 호출했다면 실제로 이를 원격 KV 저장소에 저장하려면 어떻게 해야 할까요? 가장 확실한 해결책은 Cloudflare API를 사용하는 것이었습니다. 우리는 로컬에서 전체 env를 API 호출을 하는 스텁 객체로 대체하고 env.KV.put() 을 PUT http:///accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/{key_name}으로 변환할 수도 있었습니다.
이 방식은 KV, R2, D1 등 성숙한 HTTP APIs를 포함한 바인딩에 유용했을 것입니다. 하지만 구현하고 유지 관리하기가 상당히 복잡한 솔루션이었을 것입니다. 우리는 전체 바인딩 API 표면을 복제하고 바인딩에서 가능한 모든 작업을 동등한 API 호출로 변환해야 했습니다. 또한 일부 바인딩 작업에는 이에 해당하는 API 호출이 없으므로 이 전략을 사용하면 지원할 수 없습니다.
대신 우리는 이미 프로덕션에서 사용하는 API가 기성품으로 우리를 기다리고 있다는 것을 깨달았습니다!
Workers 플랫폼의 대부분의 바인딩은 본질적으로 서비스 바인딩으로 귀결됩니다. 서비스 바인딩은 두 Workers 사이의 링크를 통해 HTTP나 JSRPC (JSRPC에 대해서는 나중에 설명하겠습니다)를 통해 통신할 수 있도록 합니다.
예를 들어, KV 바인딩은 작성된 Worker와 HTTP Worker 간의 서비스 바인딩으로 구현됩니다. KV 바인딩용 JS API는 Workers 런타임에서 구현되며, env.KV.get() 과 같은 호출을 KV 서비스를 구현하는 Worker에 대한 HTTP 호출로 변환합니다.
프로덕션 환경에서 KV 바인딩이 작동하는 방식을 단순화한 모델을 보여주는 다이어그램
여기에는 env.KV.get() 호출을 변환하는 런타임과 KV 서비스를 구현하는 Worker 사이에 자연스러운 비동기 네트워크 경계가 있음을 알 수 있습니다. 그래서 자연스러운 네트워크 경계를 사용하여 원격 바인딩을 구현할 수 있다는 것을 깨달았습니다. 프로덕션 런타임이 env.KV.get() 을 HTTP 호출로 변환하는 대신,로컬 런타임(workerd)이 env.KV.get() 을 HTTP 호출로 변환한 다음, KV 서비스로 직접 보내도록 할 수 있습니다. 프로덕션 런타임을 우회하는 것입니다. 그렇게 했죠!
원격 프록시 서버와 통신하는 단일 원격 프록시 클라이언트, 차례로 원격 KV와 통신하는 단일 KV 바인딩을 사용하여 로컬로 실행되는 worker를 보여주는 다이어그램
위 다이어그램은 원격 KV 바인딩과 함께 실행되는 로컬 Worker를 보여줍니다. 이제 로컬 KV 시뮬레이션이 처리하는 대신 원격 프록시 클라이언트가 처리합니다. 그런 다음 이 Worker는 실제 원격 KV 리소스에 연결된 원격 프록시 서버와 통신하여 궁극적으로 로컬 Worker가 원격 KV 데이터와 원활하게 통신할 수 있도록 합니다.
각 바인딩은 원격 프록시 클라이언트(모두 동일한 원격 프록시 서버에 연결된) 또는 로컬 시뮬레이션에서 독립적으로 처리될 수 있으므로, 일부 바인딩은 로컬에서 시뮬레이션되고 다른 바인딩은 실제 원격 리소스에 연결되는 매우 동적인 워크플로우가 가능합니다. 아래 예시에서 설명하겠습니다.
위 다이어그램과 구성은 서로 다른 3개의 리소스에 바인딩된 Worker(컴퓨터에서 실행)를 보여줍니다. 2개는 로컬(KV 및 R2), 다른 1개는 원격(KV_2)
위 섹션에서는 HTTP 연결(예: KV 및 R2)로 지원되는 바인딩을 다루었지만, 최신 바인딩은 JSRPC를 사용합니다. 즉, 로컬에서 실행되는 workerd 가 JSRPC를 프로덕션 런타임 인스턴스와 대화할 수 있는 방법이 필요했습니다.
Cap'n Web 블로그에서 자세히 설명한 바와 같이, 다행히도 이를 가능하게 하는 병행 프로젝트가 진행되고 있었습니다. 로컬 workerd 인스턴스와 원격 런타임 인스턴스 간의 연결이 Cap'n Web을 사용하여 WebSocket을 통해 통신하도록 하고, JSRPC로 지원되는 바인딩이 작동하도록 했습니다. 여기에는 Images와 같은 최신 바인딩과 자체 Workers에 대한 JSRPC 서비스 바인딩이 포함됩니다.
Vite, Vitest, JavaScript 생태계와의 원격 바인딩
이 흥미로운 새 기능을 wrangler dev 전용으로 제한하고 싶지 않았습니다. 저희는 Cloudflare Vite 플러그인 및 바이테스트-풀-작업자 패키지에서 이를 지원하고, JavaScript 생태계의 다른 잠재적 도구와 사용 사례에서도 이점을 누릴 수 있도록 하고 싶었습니다.
이 목적을 달성하기 위해, wrangler 패키지는 이제 wrangler dev를 활용하지 않는 도구도 원격 바인딩을 지원할 수 있도록 해주는startRemoteProxySession 등의 유틸리티를 내보냅니다. 자세한 내용은 공식 원격 바인딩 문서에서 확인할 수 있습니다.
그냥 wrangler dev를 사용하세요! Wranglerv4.37.0(@cloudflare/vite-plugin v1.13.0, @cloudflare/vitest-pool-workers v0.9.0) 기준으로, 원격 바인딩은 모든 프로젝트에서 사용할 수 있으며, 다음을 추가하여 바인딩별로 설정할 수 있습니다 remote: Wrangler 구성 파일의 바인딩 정의와 일치해야 합니다.