179 lines
4.6 KiB
Markdown
179 lines
4.6 KiB
Markdown
# Cloudflare Durable Objects + WebSocket 실시간 카운터
|
|
|
|
이 프로젝트는 SvelteKit, Cloudflare Durable Objects, WebSocket을 사용하여 실시간 카운터 및 접속자 수를 표시하는 예제 애플리케이션입니다.
|
|
|
|
## 주요 기능
|
|
|
|
- ✅ **Cloudflare Durable Objects**로 상태 관리
|
|
- ✅ **WebSocket Hibernation API**로 실시간 양방향 통신
|
|
- ✅ 카운트 버튼 클릭으로 증가
|
|
- ✅ 실시간 접속자 수 표시
|
|
- ✅ 모든 클라이언트에 실시간 동기화
|
|
- ✅ Durable Objects 영구 저장소에 상태 저장
|
|
|
|
## 기술 스택
|
|
|
|
- **SvelteKit 5** - 풀스택 웹 프레임워크
|
|
- **Cloudflare Durable Objects** - 상태 저장 및 관리
|
|
- **WebSocket Hibernation API** - 저비용 실시간 통신
|
|
- **Tailwind CSS 4** - 스타일링
|
|
- **TypeScript** - 타입 안전성
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
├── src/
|
|
│ ├── durable-objects/
|
|
│ │ └── counter.ts # Durable Object 구현
|
|
│ ├── routes/
|
|
│ │ ├── api/counter/
|
|
│ │ │ └── +server.ts # WebSocket 엔드포인트
|
|
│ │ └── +page.svelte # 메인 UI 컴포넌트
|
|
│ ├── app.d.ts # TypeScript 타입 정의
|
|
│ └── hooks.server.ts # Durable Object export
|
|
├── wrangler.jsonc # Cloudflare Workers 설정
|
|
├── svelte.config.js # SvelteKit 설정
|
|
└── package.json
|
|
```
|
|
|
|
## 개발 환경 설정
|
|
|
|
### 1. 의존성 설치
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### 2. 로컬 개발 서버 실행
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
개발 서버가 시작되면 `http://localhost:5173`에서 애플리케이션을 확인할 수 있습니다.
|
|
|
|
**참고**: 로컬 개발 환경에서는 Durable Objects가 에뮬레이션되므로, 실제 동작과 약간 다를 수 있습니다.
|
|
|
|
## Cloudflare에 배포하기
|
|
|
|
### 1. 프로젝트 빌드
|
|
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
### 2. Wrangler로 배포
|
|
|
|
Cloudflare 계정이 필요합니다. 아직 로그인하지 않았다면:
|
|
|
|
```bash
|
|
npx wrangler login
|
|
```
|
|
|
|
그런 다음 배포:
|
|
|
|
```bash
|
|
npx wrangler deploy
|
|
```
|
|
|
|
### 3. Durable Objects 설정 확인
|
|
|
|
배포 시 Cloudflare Dashboard에서 다음을 확인하세요:
|
|
|
|
1. **Workers & Pages** 섹션으로 이동
|
|
2. 배포된 Worker 선택
|
|
3. **Settings** > **Durable Objects** 확인
|
|
4. `CounterDurableObject` 바인딩이 올바르게 설정되었는지 확인
|
|
|
|
## 작동 원리
|
|
|
|
### Durable Objects
|
|
|
|
`CounterDurableObject` 클래스는 다음을 담당합니다:
|
|
|
|
1. **상태 관리**: 카운트 값과 연결된 WebSocket 세션 관리
|
|
2. **영구 저장**: 카운트를 Durable Objects Storage에 저장
|
|
3. **브로드캐스팅**: 모든 연결된 클라이언트에 상태 변경 알림
|
|
|
|
### WebSocket Hibernation
|
|
|
|
Cloudflare의 WebSocket Hibernation API를 사용하여:
|
|
|
|
- 메시지가 없을 때 Durable Object를 메모리에서 제거
|
|
- 비용 절감 (GB-초 단위 청구 방지)
|
|
- 클라이언트 연결 유지
|
|
|
|
### 실시간 동기화
|
|
|
|
1. 클라이언트가 `/api/counter`로 WebSocket 연결
|
|
2. Durable Object가 모든 클라이언트 세션 추적
|
|
3. 카운트 변경 시 모든 연결된 클라이언트에 브로드캐스트
|
|
4. 각 클라이언트가 실시간으로 UI 업데이트
|
|
|
|
## 환경 변수 및 설정
|
|
|
|
### wrangler.jsonc
|
|
|
|
```jsonc
|
|
{
|
|
"name": "dd",
|
|
"main": ".svelte-kit/cloudflare/_worker.js",
|
|
"compatibility_date": "2025-01-15",
|
|
"assets": {
|
|
"binding": "ASSETS",
|
|
"directory": ".svelte-kit/cloudflare"
|
|
},
|
|
"durable_objects": {
|
|
"bindings": [
|
|
{
|
|
"name": "COUNTER",
|
|
"class_name": "CounterDurableObject",
|
|
"script_name": "dd"
|
|
}
|
|
]
|
|
},
|
|
"migrations": [
|
|
{
|
|
"tag": "v1",
|
|
"new_sqlite_classes": ["CounterDurableObject"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 추가 기능 아이디어
|
|
|
|
- 여러 개의 독립적인 카운터 (룸 기반)
|
|
- 사용자 인증 및 권한 관리
|
|
- 카운트 히스토리 및 통계
|
|
- 더 복잡한 실시간 협업 기능
|
|
|
|
## 문제 해결
|
|
|
|
### WebSocket 연결 실패
|
|
|
|
- 브라우저 콘솔에서 오류 확인
|
|
- Cloudflare Dashboard에서 Durable Objects 바인딩 확인
|
|
- Worker 로그 확인 (`wrangler tail`)
|
|
|
|
### 로컬 개발 시 WebSocket 작동하지 않음
|
|
|
|
로컬 개발 환경에서는 Wrangler의 `--local` 모드를 사용하거나 `wrangler dev`를 실행할 수 있습니다:
|
|
|
|
```bash
|
|
pnpm build
|
|
npx wrangler dev
|
|
```
|
|
|
|
## 참고 자료
|
|
|
|
- [SvelteKit 문서](https://kit.svelte.dev/)
|
|
- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
|
|
- [WebSocket Hibernation API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/)
|
|
- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
|
|
|
|
## 라이선스
|
|
|
|
MIT
|
|
|