# Cloudflare 기초 용어 정리

> 결 프로젝트를 만들면서 자주 나오는 Cloudflare 용어를 개발 초보 기준으로 정리한 문서입니다.

---

## 1. Cloudflare Pages

Cloudflare Pages는 정적 웹사이트와 프론트엔드 앱을 배포하는 서비스입니다.

결에서 Pages의 역할:

```text
사용자가 보는 화면을 인터넷에 띄우는 곳
```

예:

```text
/
/app
/goal
/asset/000660
```

같은 화면들이 Cloudflare Pages를 통해 배포됩니다.

---

## 2. Pages Functions

Pages Functions는 Cloudflare Pages 안에서 서버 기능을 실행하는 기능입니다.

결에서 Pages Functions의 역할:

```text
프론트 화면과 D1/KV/R2/API를 연결하는 서버 코드
```

예:

```text
/api/health
/api/news/search
/api/decisions
```

이런 주소는 단순 HTML이 아니라 Pages Functions 코드가 실행되는 곳입니다.

---

## 3. D1

D1은 Cloudflare의 서버리스 SQL 데이터베이스입니다.

쉽게 말하면:

```text
Cloudflare 안에 있는 SQLite 기반 데이터베이스
```

결에서 D1의 역할:

```text
판단 로그
목표 계산
종목 재무 데이터
공시 데이터
복기 로그
로직 업데이트 기록
```

처럼 구조화된 데이터를 저장합니다.

D1에 저장하기 좋은 것:

```text
테이블 형태 데이터
검색/정렬/필터링이 필요한 데이터
관계가 있는 데이터
오래 보관할 중요한 기록
```

예:

```text
decision_logs
fundamentals_snapshots
goal_profiles
reflection_logs
```

결론:

```text
D1 = 결의 장부 / 원장 / 데이터베이스
```

---

## 4. SQL

SQL은 데이터베이스에 명령을 내리는 언어입니다.

쉽게 말하면:

```text
데이터베이스용 명령어
```

예:

```sql
CREATE TABLE decision_logs (...);
```

뜻:

```text
decision_logs라는 표를 만들어라.
```

예:

```sql
SELECT * FROM decision_logs;
```

뜻:

```text
decision_logs 표에 저장된 내용을 보여줘라.
```

---

## 5. KV

KV는 Key-Value의 약자입니다.

쉽게 말하면:

```text
이름표(key)를 붙여 값을 저장하는 초고속 메모장
```

예:

```text
key: latest:naver:SK하이닉스
value: 최근 뉴스 API 응답 요약
```

결에서 KV의 역할:

```text
자주 읽는 값
잠깐 저장할 값
API 응답 캐시
설정값
오늘의 레이더 임시 결과
```

KV에 저장하기 좋은 것:

```text
최근 뉴스 검색 결과
최근 API 응답
사용자 설정
빠르게 읽어야 하는 작은 JSON
```

KV에 저장하면 안 좋은 것:

```text
정확한 거래 장부
복잡한 관계형 데이터
강한 일관성이 필요한 데이터
```

결론:

```text
KV = 빠른 메모장 / 임시 캐시 / 설정 저장소
```

---

## 6. Cache

Cache는 자주 쓰는 데이터를 잠깐 저장해두고 빠르게 다시 쓰는 구조입니다.

쉽게 말하면:

```text
매번 새로 가져오지 않기 위한 임시 보관함
```

예:

```text
네이버 뉴스 API를 1분마다 계속 호출하지 않고,
한 번 가져온 결과를 5분 정도 저장했다가 다시 사용
```

결에서 캐시가 필요한 이유:

```text
API 호출 비용/한도 줄이기
화면 속도 높이기
같은 데이터를 반복 조회하지 않기
```

예:

```text
SK하이닉스 뉴스 검색 결과를 5분 캐시
```

결론:

```text
Cache = 반복 조회를 줄이는 임시 저장 전략
KV = 그 캐시를 저장할 수 있는 저장소 중 하나
```

---

## 7. R2

R2는 Cloudflare의 Object Storage입니다.

쉽게 말하면:

```text
Cloudflare 안에 있는 파일 창고
```

결에서 R2의 역할:

```text
긴 리포트
백업 파일
첨부 파일
PDF
CSV
JSON 로그 아카이브
차트 이미지
```

R2에 저장하기 좋은 것:

```text
파일 형태 데이터
용량 큰 데이터
나중에 다운로드할 자료
장기 보관 리포트
```

D1과 R2의 차이:

```text
D1 = 표 형태 장부
R2 = 파일 창고
```

예:

```text
D1: 판단 로그 제목, 종목코드, 날짜
R2: 주간 리포트 PDF 파일 원본
```

---

## 8. Bucket

Bucket은 R2 안에서 파일을 담는 큰 통입니다.

쉽게 말하면:

```text
파일 창고 안의 큰 보관함
```

결에서 만든 bucket:

```text
gyeol-storage
```

이 bucket 안에 나중에 이런 파일들이 들어갈 수 있습니다.

```text
weekly-reports/2026-07-07.pdf
backups/decision_logs_2026-07.json
charts/asset_000660_growth.png
```

결론:

```text
R2 = 파일 창고 서비스
Bucket = 그 창고 안의 파일 보관함
Object = bucket 안의 개별 파일
```

---

## 9. Binding

Binding은 Pages Functions 코드가 Cloudflare 자원에 접근하기 위한 연결 이름입니다.

쉽게 말하면:

```text
코드에서 Cloudflare 자원을 부르는 별명
```

결에서 만든 binding:

```text
DB      → D1 데이터베이스 gyeol-db
CACHE   → KV namespace gyeol-cache
STORAGE → R2 bucket gyeol-storage
```

코드에서는 이렇게 접근합니다.

```javascript
context.env.DB
context.env.CACHE
context.env.STORAGE
```

결론:

```text
Binding = 코드와 Cloudflare 저장소를 연결하는 손잡이
```

---

## 10. 결 기준 저장소 선택법

### D1에 넣을 것

```text
목표 계산
판단 로그
복기 로그
종목 재무 스냅샷
공시 데이터
기회 점수
포트폴리오 스냅샷
```

### KV에 넣을 것

```text
최근 API 응답
짧은 캐시
오늘의 레이더 임시 결과
빠른 설정값
```

### R2에 넣을 것

```text
PDF 리포트
백업 JSON
CSV 파일
차트 이미지
긴 분석 원문
```

---

## 11. 한 줄 비유

```text
Cloudflare Pages = 가게 간판과 매장
Pages Functions = 매장 안 직원
D1 = 회계 장부
KV = 카운터 옆 빠른 메모지
Cache = 방금 쓴 내용을 잠깐 복사해두는 습관
R2 = 창고
Bucket = 창고 안의 큰 박스
Binding = 직원이 장부/메모지/창고에 접근하는 열쇠 이름
```

---

## 12. 결 프로젝트에서 현재 만든 것

```text
Pages 프로젝트
- gyeol-8ux.pages.dev

D1
- gyeol-db

KV
- gyeol-cache

R2
- gyeol-storage

Bindings
- DB
- CACHE
- STORAGE
```

---

## 13. 앞으로 작업 순서

```text
1. D1에 최종 테이블 구조 생성
2. /goal 화면과 API 연결
3. /app Opportunity Radar 화면 연결
4. /theme, /asset, /portfolio, /decision, /reflection 확장
5. 실제 API 연결 확대
```