✳빛의 지도DEPLOYMENT GUIDE

Cloudflare 배포 안내

이 ZIP은 HTML과 Cloudflare Pages용 뉴스 수집 서버가 포함된 완성 패키지입니다. 별도 빌드는 필요하지 않습니다. 실제 수집한 기사 저장본이 포함되어 업로드 즉시 자료가 표시됩니다. 새 뉴스 수집에는 DB·관리자 암호 연결이 필요하며 AI는 선택 사항입니다.

1. ZIP 업로드

  1. Cloudflare 대시보드에서 Workers & Pages로 이동합니다.
  2. Create application → Pages → Upload assets 또는 ‘Drag and drop your files’ 경로를 선택합니다. Workers의 일반 정적 자산 업로드가 아니라 Pages Direct Upload를 선택하세요. 화면 명칭은 변경될 수 있습니다.
  3. 프로젝트 이름을 정하고 제공된 ZIP을 업로드합니다. ZIP 최상위에 index.html, _worker.js, app.js가 있어야 합니다.
  4. 배포된 *.pages.dev 주소를 열면 화면과 배포 안내를 볼 수 있습니다. 첫 화면부터 실제 수집 자료가 표시됩니다. DB를 연결하면 이 저장본을 자동으로 불러옵니다.

2. 저장소 연결

  1. Storage & databases → D1에서 데이터베이스를 생성합니다. 이름 예: media-art-atlas.
  2. 방금 만든 Pages 프로젝트의 Settings → Bindings에서 D1 database 바인딩을 추가합니다.
  3. 변수 이름은 정확히 DB로 입력하고 생성한 데이터베이스를 선택합니다.

테이블은 앱의 첫 요청에서 자동 생성됩니다. 별도 SQL 실행은 필요하지 않습니다. 프로젝트를 갱신할 때 같은 DB를 유지하면 기존 자료도 유지됩니다.

3. 선택 사항: 뉴스 분류 AI 연결

기본 분류는 별도 AI 없이 확인된 장소명 및 기사 제목의 지역·시설명·행사 표현을 추출하여 작동하며 모든 결과를 검토 필요 후보로 표시합니다. 더 넓은 범위의 자동 추출을 원하면 같은 Bindings 화면에서 Workers AI를 추가하고 변수 이름을 AI로 입력합니다. Cloudflare 계정에서 Workers AI 이용이 활성화되어 있어야 합니다.

기본 모델은 @cf/meta/llama-3.3-70b-instruct-fp8-fast입니다. 향후 모델 지원이 변경되면 JSON mode를 지원하는 모델 이름을 환경변수 AI_MODEL로 지정할 수 있습니다. 모델 출력은 검증 후 저장합니다.

4. 관리자 암호 설정

Pages 프로젝트 Settings → Variables and Secrets에서 이름 ADMIN_TOKEN, 유형 Secret으로 16자 이상의 충분히 긴 임의 암호를 추가하세요. 뉴스 수집과 데이터 수정에 필요합니다. 검색 API 키를 이 암호로 사용하지 마세요.

암호를 HTML이나 JavaScript에 직접 적지 않습니다. 배포된 사이트의 ‘연결 설정’에 같은 암호를 입력합니다. 입력값은 현재 탭의 메모리에만 보관됩니다.

5. 다시 배포하고 수집 시작

  1. 바인딩·Secret을 설정한 뒤 동일 ZIP으로 새 배포를 만듭니다. 설정 변경만으로 기존 배포에 적용되지 않을 수 있습니다.
  2. 사이트 → 연결 설정에서 저장소·관리자 암호가 연결된 것을 확인합니다. AI는 연결하지 않아도 기본 분류가 작동합니다.
  3. 관리자 암호, 검색어, 기간을 저장하고 뉴스 새로 수집을 누릅니다.

선택: Google 뉴스 검색 API 연결

기본은 Google 뉴스 검색 RSS입니다. API 키가 필요 없지만 비공식 피드여서 응답 제한·형식 변경·검색 누락이 생길 수 있습니다. 안정적인 대체 경로가 필요하면 SerpApi에서 발급한 키를 Cloudflare Secret SERPAPI_KEY로 저장하고 재배포하세요. 설정되면 RSS 대신 SerpApi의 Google News 검색을 사용합니다. SerpApi는 별도 외부 서비스이며 이용 요금·한도가 적용될 수 있습니다.

2023년 이후 누적 조사

이 버전은 2023년 1월 1일부터 현재까지 월별 미디어아트·미디어파사드·몰입형 전시 검색과 17개 시도별 연간 검색을 실행합니다. 검색 결과가 95건 이상이면 구간을 이등분하여 다시 검색하며, 7일 이하까지 분할해도 상한에 도달한 구간은 화면에 표시합니다. 이후 새로 발견한 전시관 이름으로 보완 검색합니다.

화면 상단에서 연도별 기사 수, 완료·대기·실패 검색 구간, 상한 도달 구간을 확인할 수 있습니다. ‘2023년 이후 전체 기간 수집’은 저장된 진행 상태부터 이어서 실행하고 실패한 구간은 재시도합니다. Google 검색의 미색인·누락·응답 제한이 있으므로 구간 처리가 끝났다는 뜻이 전국 전수 확인을 의미하지 않습니다.

로컬 미리보기는 브라우저를 닫아도 서버 실행 중 누적 조사를 계속합니다. Cloudflare Pages 배포에서는 해당 버튼으로 실행하며 브라우저가 열려 있는 동안 진행합니다. 창을 닫으면 저장된 작업부터 다음 실행에 이어집니다. 새 뉴스는 별도의 ‘뉴스 새로 수집’으로 갱신할 수 있습니다.

2023년 이전에 개관한 시설도 2023년 이후 기사가 있으면 포함합니다. 시설 수는 장소별로 통합하며 행사는 연도·시즌·회차를 구분합니다. 상설관에서 콘텐츠를 교체한 기사는 시설의 출처로 연결합니다. 상설전시·행사 모두 자동 분류 후보와 검토 완료 자료를 필터로 구분할 수 있습니다.

수집·분류 방식

검색 범위와 운영

일반 새 수집은 검색어 최대 8개를 사용합니다. 전체 기간 수집은 월별·지역별 작업을 자동 생성하고 검색 응답 상한에 가까우면 기간을 분할합니다. 날짜 필터는 Google 검색식 after:, before:로 전달하며 종료일은 미포함입니다. 검색 서비스의 색인·응답 한계가 있어 전수 수집이 아닙니다. 오래된 자료가 많으면 월별·지역별·시설명별로 나누어 검색하세요. 날짜가 확인되지 않은 기사는 ‘기사일 미확인’으로 보존하고 연도 필터에서 제외합니다.

DB에 기록한 자료는 방문자에게 공개됩니다. 관리자 암호는 수정·수집을 보호하며 열람을 제한하지 않습니다. 비공개 운영이 필요하면 Cloudflare Access를 별도로 적용하세요. Cloudflare D1·Workers AI·Pages의 계정별 사용량과 비용을 확인하세요.

지도는 ZIP에 동봉한 Leaflet 1.9.4와 OpenStreetMap 온라인 타일을 사용합니다. 인터넷 연결이 필요하며 타일 제공자의 이용 정책을 따릅니다. 대규모 운영은 적절한 지도 타일 제공자로 변경하세요.

문제 해결

포함 파일

index.html 화면 · style.css 스타일 · app.js 지도·관리 기능 · _worker.js 서버 · _routes.json API 경로 · _headers 보안 헤더 · vendor/ 지도 라이브러리와 라이선스 · guide.html 이 안내.

검증 범위

동봉 구현은 로컬에서 중복 통합, 서로 다른 행사 회차 구분, 인증, 자료 수정·합치기·분리, 오류 보존과 화면 동작을 검증했습니다. 사용자의 Cloudflare 계정·바인딩과 실제 Workers AI 실행은 배포 후 연결 확인이 필요합니다. 예시 화면은 실제 뉴스 데이터와 분리되어 있으며 데이터베이스에 저장되지 않습니다.

공식 참고 문서

Pages ZIP 업로드와 _worker.js 지원
Pages D1·Workers AI 바인딩
Workers AI JSON mode
SerpApi Google News API
OpenStreetMap 타일 정책

← 빛의 지도로 돌아가기