사용자 소유 Cloudflare에 게시하고 운영하기

Glif의 현재 웹 게시 방향은 사용자가 소유한 Cloudflare 계정과 Pages project에 Binder의 정적 결과를 보내는 것이다. 계정, project, domain과 credential의 권위는 사용자에게 있으며 Glif server가 provider secret을 소유하거나 실패 시 Managed hosting으로 자동 전환하지 않는다.

이 장은 배포 버튼보다 더 긴 전체 운영 흐름을 다룬다. 성공은 upload 완료가 아니라 provider apply 뒤 공개 URL의 정확한 revision과 대표 asset을 검증한 상태다.

⚠️
첫 실제 웹 게시 전체 여정은 현재 requires-setup이다. 로컬 구현과 테스트는 닫혔지만 real OAuth·credential, provider propagation, public promotion과 packaged profile의 release evidence는 남아 있다. 이 가이드는 production 성공을 보장하지 않는다.

외부 activation evidence가 준비되기 전 실제 웹 게시 진입을 막는 현재 화면

기능과 공개 경계

기능 ID 사용자 기능 현재 가이드 처리
PB-29 사용자 소유 Cloudflare Pages direct deploy 절차와 preflight 설명
PB-30 deploy 진행 상태 실제 UI와 예시 상태 설명
PB-31 credential을 제거한 진행 log 공개 가능한 필드와 금지값 설명
PB-32 local·provider deploy history 결과 상태와 재검증 설명
PB-34 remote Pages project 삭제 typed confirmation과 local source 보존 설명
PB-41 Binder materialization requires-setup; fail-closed 경계 설명
PB-43 첫 verified public publish requires-setup; external activation evidence 대기

PB-33 Managed source sync와 PB-40 legacy Managed bucket·pull rollback은 현재 사용자 기능이 아니다. retired 구현의 containment evidence이므로 메뉴나 대안으로 안내하지 않는다.

실습 준비

deploy-operations-lab을 내려받아 Binder로 연다. 실제 provider 실증은 다음 조건을 만족하는 계정에서만 한다.

  • 개인 또는 조직이 직접 소유하고 관리하는 Cloudflare 계정
  • 삭제해도 되는 전용 Pages test project
  • 필요한 Pages 범위만 가진 OAuth 연결 또는 scoped API token
  • 실제 서비스 domain과 분리된 pages.dev 또는 test subdomain
  • screenshot·영상에 token과 raw account/project ID를 남기지 않는 캡처 환경

실제 credential이 없다면 이 장의 UI 탐색, 로컬 Preview, progress·log·history 해석과 삭제 확인 직전까지 진행하고 외부 성공을 기록하지 않는다.

1. Binder와 materialization preflight

게시 대상은 현재 Binder다. source Markdown과 resource identity는 계속 원본 권위이며, publish는 그 입력에서 파생된 정적 결과만 provider에 보낸다.

  1. Output Structure에서 공개할 문서와 순서를 확인한다.
  2. Preview 작업 공간에서 route, link와 asset을 확인한다.
  3. Site 설정의 title, base URL, menu, search·TOC와 접근 정책을 저장한다.
  4. preflight에 차단된 reference, read-only mount 또는 Binder 밖 resource가 없는지 확인한다.
  5. local static result에 index.html과 필요한 route·asset이 있는지 확인한다.

PB-41은 일부 환경에서 추가 설정과 검증이 필요하다. mounted·read-only Binder, Binder 밖 reference나 ambiguous include policy는 fail-closed한다. Glif는 staging 결과를 원본에 조용히 다시 쓰지 않고 app-owned marker 범위 밖 파일을 cleanup하지 않는다.

공개 가이드와 오류 화면에는 physical staging path, manifest hash나 app-data 위치를 노출하지 않는다.

2. 게시 대상 검토

첫 웹 게시 화면에서 다음 항목을 읽는다.

항목 확인 기준
게시할 폴더 현재 Binder 이름과 일치
게시 문서 의도한 문서 수와 일치
프로젝트 이름 내 Cloudflare 계정의 대상 project
예상 공개 주소 test 또는 production 의도와 일치
공개 범위 public, password, expiration 중 저장한 정책
운영 계정 내 Cloudflare
연결 방식 OAuth 권장, 제한 환경에서 scoped token
원본 문서 변경하지 않음·자동 GitHub sync 없음

로컬 Preview 완료와 인터넷 공개는 별개의 단계다. 게시 내용 검토 뒤에도 Glif 로그인, provider 연결, target resolution과 permission 검사가 남을 수 있다.

3. Cloudflare 연결

권장 경로는 OAuth다. OAuth를 사용할 수 없는 제한된 환경에서만 scoped API token 입력을 연다.

  1. Cloudflare 연결을 선택한다.
  2. 브라우저에서 계정과 요청 권한을 확인한다.
  3. Glif로 돌아와 같은 게시 작업이 이어지는지 확인한다.
  4. 계정이 여러 개면 사용할 계정을 명시적으로 선택한다.
  5. 같은 project 이름이 있으면 기존 project 사용 또는 새 이름을 선택한다.

Token은 password 입력처럼 session에서 다루고 Markdown, front matter, hugo.toml, screenshot, log 또는 evidence JSON에 기록하지 않는다. credential이 만료됐거나 Pages 권한이 부족하면 다시 연결하고 권한 범위를 고친다.

4. 게시 시작과 단계 읽기

게시 작업은 다음 단계를 구분한다.

단계 의미 아직 성공이 아닌 이유
배포 준비 중 target과 입력을 재검사 artifact가 없음
사이트 빌드 중 정적 결과 생성 provider가 받지 않음
업로드 중 파일 전송 production apply 전
Cloudflare 대기열 provider가 요청 수락 실행·전파 전
Cloudflare 배포 중 provider 적용 진행 공개 URL 검증 전
공개 주소 검증 중 URL·revision·asset 확인 모든 check가 끝나지 않음
웹 게시 완료 live verification 통과 이때만 완료로 기록

Progress percentage는 사용자 피드백이며 ordering authority가 아니다. 더 늦게 끝난 오래된 요청이 최신 accepted 요청을 이기지 못해야 하며, stale result는 production 성공으로 승격하지 않는다.

5. 진행률과 파일 통계

실시간 상태에는 전체 progress와 현재 단계가 표시된다. 업로드 단계에서는 다음 통계를 읽는다.

  • 처리한 chunk / 전체 chunk
  • 준비한 file / 전체 file
  • 새 파일, 변경 파일, 건너뛴 파일, 실패 파일
  • 크기 제한으로 제외된 파일

100%만 보고 끝내지 않는다. 최종 상태와 공개 URL 검증을 함께 확인한다. 실패 파일이나 size skip이 있으면 누락이 의도한 결과인지 확인한다.

업로드 progress, 파일 통계와 credential을 제외한 단계 로그 예시

이 화면의 progress와 log는 실제 Glif UI에 로컬 예시 상태를 투영한 것이다. 레이아웃과 상태 해석을 검증하지만 Cloudflare가 upload를 받았다는 production evidence는 아니다.

6. 안전한 진행 로그

로그는 시각, 단계, 사용자용 요약과 제한된 detail만 포함해야 한다.

기록해도 되는 예:

  • 사이트 빌드 완료
  • 42개 파일 업로드 준비
  • Provider apply 관측 대기
  • 대표 asset revision 불일치

기록하면 안 되는 값:

  • OAuth callback query와 API token
  • raw account/project identifier
  • provider raw response body
  • Binder의 physical local path
  • source 본문과 비밀번호

긴 detail은 펼쳐서 읽되 support에 전달하기 전 다시 redaction한다. 실패를 알 수 없음으로 뭉개지 말고 connection, permission, upload, propagation, verification 중 어느 단계인지 구분한다.

영상 속 provider 상태와 history는 설명용 local fixture다. 실제 token, provider request와 remote mutation은 발생하지 않았다.

7. 게시 이력 읽기

Publish History는 local operation record와 provider에서 관측한 실행을 구분한다. 한 기록에서 다음 항목을 확인한다.

  • preview 또는 production target
  • manual, scheduled 또는 rollback trigger
  • terminal state
  • artifact·revision의 제한된 식별자
  • provider deployment observation
  • duration과 file diff summary
  • domain, access, analytics, public marker, 대표 asset 검증 결과

주요 terminal state:

상태 해석 다음 행동
live_verified 공개 결과의 exact revision 검증 완료 URL을 새 브라우저에서 최종 확인
verification_failed apply됐어도 공개 결과 검증 실패 revision·domain·asset 검사 후 재시도 판단
observation_pending provider 결과가 아직 확정되지 않음 새 upload보다 상태 재관측 우선
cancelled 사용자가 중단 입력 변경 여부에 따라 새 실행
failed 실행 실패 diagnostic과 retryability 확인

Provider observation은 지연될 수 있다. history가 비어 있거나 오래됐다고 즉시 project를 다시 만들지 말고 새로 고침과 target binding을 먼저 확인한다.

live_verified와 revision_mismatch를 함께 보여 주는 local publish history 예시

provider apply 뒤에도 revision과 대표 asset 검증이 남은 경계

8. 실패와 재시도

오류 의미 복구
provider connection required 연결을 확인할 수 없음 같은 게시 작업에서 재연결
account ambiguous 여러 계정 중 target 미확정 계정 선택
project collision 이름 충돌 기존 project 또는 새 이름 선택
credential stale 인증 만료 재연결
permission insufficient Pages 권한 부족 scope 수정 후 재연결
network retryable 일시적 network 실패 상태 확인 뒤 동일 작업 재시도
verification timeout 전파 지연 provider state와 URL 재관측
revision mismatch live 결과가 현재 revision과 다름 최신 accepted 입력으로 새 게시

재시도 전에 source, build profile, target과 accepted revision이 바뀌었는지 확인한다. 입력이 바뀌면 동일 작업의 단순 retry가 아니라 새 generation이 필요하다.

9. Pages project 관리

Project 관리에서는 연결 새로 고침, local 연결 해제와 remote 삭제를 구분한다.

  • 연결 새로 고침: remote project를 관측하고 local binding을 갱신
  • 연결 해제: local Binder와 project 연결만 제거; remote project 유지
  • 사이트 삭제: Cloudflare의 remote Pages project 삭제

10. Remote project 삭제

삭제는 되돌리기 어려운 외부 작업이다.

  1. Project 관리에서 대상 이름과 Pages domain을 확인한다.
  2. 사이트 삭제를 선택한다.
  3. 표시된 project 이름을 정확히 입력한다.
  4. local Binder와 source는 삭제되지 않는다는 경계를 확인한다.
  5. 삭제를 실행한다.
  6. provider에서 project가 사라졌는지 다시 관측한다.
  7. Glif의 local binding과 상태가 정리됐는지 확인한다.

remote site 이름을 다시 입력해야 활성화되는 삭제 확인 UI

삭제 확인이 실패하거나 remote 결과가 불확실하면 성공으로 표시하지 않는다. 같은 이름의 project를 바로 다시 만들기 전에 provider 상태를 확인한다.

11. 공개 URL 검증

Provider apply 뒤 다음 항목이 모두 맞아야 한다.

  • HTTPS public URL이 의도한 host로 열린다.
  • revision marker가 이번 accepted revision과 같다.
  • root와 대표 하위 route가 응답한다.
  • 대표 image·CSS·script asset이 같은 결과에 속한다.
  • 공개 범위와 password·expiration 정책이 맞다.
  • analytics를 켰다면 consent와 적용 상태가 맞다.

pages.dev 주소와 custom domain의 전파 속도는 다를 수 있다. custom domain이 pending이면 provider apply와 domain verification을 분리해 기록한다.

12. 첫 게시 완료 기준

PB-43의 완전한 release evidence는 아직 남아 있다. 현재 가이드에서 확정할 수 있는 완료 기준은 다음 두 층이다.

  1. 로컬 층: Binder → Preview → browser handoff와 recovery 동작
  2. 외부 activation 층: real credential → provider apply → propagation → exact live verification

두 번째 층의 P6 evidence가 채워지기 전에는 “누구나 바로 첫 웹 게시 완료”로 표현하지 않는다. 실제 시도에서 얻은 URL, timestamp와 revision은 credential을 제거한 release evidence에 기록한다.

문제 해결 체크리스트

  • 현재 Binder와 project target이 맞다.
  • source·resource preflight가 통과했다.
  • credential이 source나 log에 남지 않았다.
  • 진행 상태와 sanitized log를 함께 확인했다.
  • provider apply와 live verification을 구분했다.
  • history의 revision과 공개 결과가 같다.
  • remote 삭제 전 project 이름을 정확히 입력했다.
  • 삭제가 local Binder 삭제가 아님을 확인했다.

다음 단계는 실제 provider credential이 준비된 release candidate에서 이 절차 전체를 실행해 PB-43의 external activation evidence를 닫는 것이다.