Cloudflare 연결 가이드

# 내 한의원 사이트를 세상에 공개하려면 한의원 홈페이지를 만들었으면, 환자들이 실제로 접속할 수 있게 **인터넷에 올려야** 합니다. ClinicOS는 이 과정을 Cloudflare라는 인프라 위에서 처리합니다. 이 가이드는 **"내 사이트를 세상에 공개하기 위한 기반"**을 마련하는 과정입니다. 계정을 만들고, 연결 키(API Token)를 발급한 뒤 ClinicOS의 숨김 입력 도구로 연결하면 됩니다. 이후 리소스 생성과 배포는 에이전트와 함께 진행합니다. --- ## Cloudflare가 해주는 일 | 역할 | 병원에서 쓰는 곳 | |------|-----------------| | **Pages(페이지)** | 홈페이지를 인터넷에 공개 | | **D1** | 환자, 예약, 콘텐츠 같은 운영 데이터 저장 | | **R2 객체 스토리지(R2)** | 사진과 첨부파일 저장 | > 무료 플랜으로 시작할 수 있습니다. 다만 사용량과 Cloudflare 정책에 따라 과금 조건이 달라질 수 있으니, 개설할 때 현재 플랜과 사용량 알림을 함께 확인하세요. --- ## 1단계: 계정 만들기 1. [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) 접속 2. 이메일과 비밀번호 입력 3. **이메일 인증 완료** (받은편지함에서 인증 메일 클릭) 4. 무료(Free) 플랜 선택 > **중요**: 이메일 인증을 반드시 완료하세요. 인증하지 않으면 API Token 발급 시 403 오류가 발생합니다. 가입 후 Cloudflare에서 보낸 인증 메일을 확인하고 링크를 클릭하세요. > 이미 Cloudflare 계정이 있다면 기존 계정을 그대로 사용할 수 있습니다. --- ## 2단계: API Token 발급 API Token은 에이전트가 Cloudflare에 접속할 수 있게 해주는 **열쇠**입니다. ### 토큰 만드는 법 1. [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) 접속 2. **토큰 생성(Create Token)** 클릭 3. **커스텀 토큰 생성(Create Custom Token)** 선택 4. 토큰 이름: `Clinic-OS` (자유) 5. 권한을 아래와 같이 설정합니다: **계정(Account) 권한 (4개)**: | 카테고리 | 권한 | 수준 | |----------|------|------| | 계정 설정(Account Settings) | 계정 설정(Account Settings) | **읽기(Read)** | | Cloudflare Pages | Pages(페이지) | **편집(Edit)** | | D1 | D1 | **편집(Edit)** | | R2 객체 스토리지(R2 Storage) | R2 객체 스토리지(R2 Storage) | **편집(Edit)** | 처음 `pages.dev` 주소에 배포할 때는 영역(Zone) 권한이 필요하지 않습니다. 나중에 커스텀 도메인을 연결할 때만 다음 두 권한을 추가한 별도 토큰을 사용합니다. **커스텀 도메인 연결 시에만 필요한 영역(Zone) 권한**: | 카테고리 | 권한 | 수준 | |----------|------|------| | 영역(Zone) | 영역(Zone) | **읽기(Read)** | | DNS | DNS | **편집(Edit)** | > **영역(Zone) 권한 설정 시**: 영역 리소스(Zone Resources)에서 "포함(Include) → 모든 영역(All zones)" 선택 6. **계정 리소스(Account Resources)**: 본인 계정 선택 7. **요약으로 이동(Continue to summary)** → **토큰 생성(Create Token)** 8. 화면에 표시된 토큰을 복사합니다 > **중요**: 토큰은 이 화면에서 한 번만 볼 수 있습니다. 안전한 곳에 메모해두세요. ### 토큰 적용 ClinicOS Starter 프로젝트 폴더의 터미널에서 아래 명령을 실행합니다. Windows PowerShell은 `npm` 대신 `npm.cmd`를 사용합니다. ```bash npm run cloudflare:setup ``` 명령이 연 숨김 입력란에 토큰을 직접 붙여 넣습니다. 입력한 문자는 화면이나 터미널 기록에 표시되지 않습니다. 토큰을 에이전트 채팅, 명령 인자, 메모 문서에 붙여 넣지 마세요. 도구는 토큰과 계정을 Cloudflare API로 먼저 확인한 뒤, 해당 프로젝트의 Git 제외 `.env`에 `CLOUDFLARE_API_TOKEN`과 `CLOUDFLARE_ACCOUNT_ID`만 저장합니다. Windows의 `setx`처럼 PC 사용자 전체에 적용되는 환경변수는 사용하지 않습니다. 같은 PC의 다른 병원 프로젝트와 자격이 섞이지 않도록 프로젝트마다 따로 연결합니다. > **Codespaces 사용자 주의**: Codespace를 삭제하면 그 안의 `.env`도 사라집니다. 새 > Codespace에서는 이 숨김 입력 절차를 다시 실행하거나, 해당 병원 저장소에만 제한한 > GitHub Codespaces Secret을 사용하세요. ### 연결 확인 ```bash npm run cloudflare:status -- --verify git check-ignore .env git ls-files .env ``` 원격 검증이 `정상`이어야 하며, `git check-ignore`는 `.env`를 출력하고 `git ls-files`는 아무것도 출력하지 않아야 합니다. --- ## 2.5단계: R2 스토리지 결제 수단 확인 R2 스토리지(이미지/파일 저장)를 활성화할 때 결제 수단 등록을 요청받을 수 있습니다. 무료 제공량과 과금 기준은 바뀔 수 있으므로, 화면에 표시되는 현재 조건을 확인한 뒤 진행하세요. 1. [dash.cloudflare.com](https://dash.cloudflare.com) 로그인 2. 왼쪽 메뉴에서 **R2 객체 스토리지(R2 Object Storage)** 클릭 3. "R2 시작하기(Get started with R2)" 또는 활성화 버튼 클릭 4. 화면에서 요청할 경우 현재 과금 조건을 확인하고 결제 수단 입력 > 결제 수단을 요청하는지는 계정과 현재 정책에 따라 다를 수 있습니다. R2 활성화 화면에 보이는 안내를 확인하고, 진행되지 않을 때만 결제 설정을 점검하세요. --- ## 3단계: 에이전트와 연결 상태 확인하기 계정과 토큰이 준비되면, 에이전트에게 이렇게 말하세요: ``` 셋업 진행해줘 ``` 에이전트가 아래 작업을 진행하면 생성 결과와 연결 상태를 확인합니다. - D1 데이터베이스 생성 - R2 스토리지 생성 - 설정 파일 연결 - 초기 데이터 투입 오류가 표시되면 완료로 넘기지 말고, 해당 단계와 오류 메시지를 함께 전달하세요. --- ## 인증 방식 선택 | 환경 | 인증 방식 | 비고 | |------|----------|------| | **GitHub Codespaces** (워크숍) | **API Token** (위 2단계) | 필수. 브라우저 OAuth 불가 | | **Windows 네이티브** (Claude Code/Codex) | **프로젝트별 API Token** | 3기 권장 경로 | | macOS 로컬 | API Token 또는 브라우저 로그인 | 둘 다 가능 | | Windows WSL / 서버 | **API Token** | 필수 | > **Codespaces 사용자**: `npx wrangler login` (브라우저 OAuth)은 Codespaces에서 팝업 차단으로 실패합니다. 반드시 위의 API Token 방식을 사용하세요. macOS 로컬에서 직접 개발하는 경우에만 브라우저 로그인도 가능합니다: ```bash npx wrangler login ``` 브라우저가 열리면 Cloudflare에 로그인하고 **Allow**를 클릭하면 됩니다. --- ## 처음 준비를 맡기는 경우 초기 구축을 맡기는 경우에는 위와 동일한 최소권한 토큰을 만들어 HQ의 보호된 초기 구축 안내 폼에만 입력합니다. 일반 채팅이나 이메일로 전달하지 않습니다. > 초기 구축이 끝나면 토큰을 삭제해도 됩니다. 삭제하면 더 이상 해당 토큰으로 접근할 수 없습니다. --- ## 자주 묻는 질문 ### 비용이 발생하나요? 처음에는 Free 플랜으로 시작할 수 있습니다. 저장량과 요청이 늘면 비용이 생길 수 있으니, 가입할 때 보이는 최신 한도와 실제 사용량을 함께 확인하세요. ### API Token이 유출되면? 즉시 [API Tokens 페이지](https://dash.cloudflare.com/profile/api-tokens)에서 해당 토큰을 삭제하세요. 삭제 즉시 접근이 차단됩니다. ### 기존 Cloudflare 계정을 사용할 수 있나요? 네. 기존 계정에 다른 사이트가 있어도 Clinic-OS를 추가로 사용할 수 있습니다. --- ## 관련 콘텐츠 - 📹 **관련 영상**: 커리큘럼 0-2. 준비물 확인 (계정 만들기) - 📋 **워크숍**: W1 M0에서 다룸 - 🎯 **직원 투어**: 관리자 패널에서 **설정** 투어를 시작하세요 - 직접 설치: `npm run setup:step -- --next` 실행 - 초기 구축 맡기기: HQ의 보호된 안내 폼에 API Token 입력

Cloudflare 연결 가이드

이 페이지에서 확인할 내용