Cloudflare Workers로 매뉴얼 배포하기: 문서 구조와 캐시 검증 OnTech Insight

TECH INSIGHT / EXPLAINED

매뉴얼의 첫 화면은 기능 목록보다 사용자가 멈추는 지점에 답해야 한다. ‘설정을 저장했는데 시작된 건가’, ‘중지하면 주문도 취소되나’, ‘알림이 안 오면 어디를 보나’ 같은 질문을 공개 문서로 정리하면 작은 팝업의 설명 부담을 줄일 수 있다.

개념을 설명하는 AI 제작 일러스트. 세 사람이 앱 도움말 링크, 문서 버전과 클라우드 문서 전달을 설명하는 모습

기존 사용 화면과 소개 이미지

기존 글에 담았던 사용 화면과 소개 이미지를 함께 보며 구조와 동작을 확인할 수 있습니다.

공개 프로젝트 화면 캡처

아래는 이 글에서 다루는 프로젝트의 공개 페이지를 직접 열어 촬영한 화면입니다. 각 그림에 출처와 촬영 날짜를 표시했습니다.

공개 운영 중인 OnStock Bot 사용자 매뉴얼의 상단 화면. 2026-09-30에 실제 페이지를 브라우저로 캡처했다. 문서 사이트의 브랜드·목차·첫 안내 영역을 보여준다. 출처 보기

공개 매뉴얼의 「설정 화면 열기」 설명 부분을 2026-09-30에 브라우저로 캡처했다. 화면 속 계좌번호·금액·마스킹된 키는 매뉴얼에 표시된 설명용 예시이며, 실제 로그인한 계좌 캡처가 아니다. 출처 보기

문서의 책임을 먼저 정한다

짧은 시작 절차, 입력값의 단위와 범위, 상태 표시의 의미, 오류에서 복구하는 방법, 데이터 저장·삭제 경로를 순서대로 배치한다. 예를 들어 주문 간격 입력란에는 ‘0.2%는 소수 비율 0.002’라고 적고 화면이 어느 표기를 받는지 명시한다. 문서에 적용되는 앱 버전과 확인 날짜도 표시한다.

정적 파일과 Worker 코드를 선택한다

Cloudflare Workers Static Assets로 HTML·CSS·이미지를 배포할 수 있다. 공개 매뉴얼만 제공한다면 모든 요청을 직접 처리하는 함수가 꼭 필요한 것은 아니다. 언어 라우팅이나 요청에 따른 동작이 필요하면 Worker를 함께 쓴다. 정적 자산 요청과 Worker 실행의 요금·한도는 구분하여 현재 공식 표를 확인한다.

다음은 응답 흐름을 설명하는 작은 Worker 예시다. 실제 매뉴얼 본문은 별도 HTML 파일로 관리하면 긴 문자열의 이스케이프와 편집 실수를 줄일 수 있다.

const MANUAL_HTML = '<!doctype html><html lang="en"><meta charset="utf-8"><title>Manual</title><h1>Bot manual</h1><p>Read the operating steps before enabling jobs.</p></html>';
export default {
  async fetch(request) {
    if (!['GET', 'HEAD'].includes(request.method)) {
      return new Response('Method Not Allowed', {
        status: 405, headers: {Allow: 'GET, HEAD'}
      });
    }
    const path = new URL(request.url).pathname;
    const found = path === '/' || path === '/Manual';
    return new Response(request.method === 'HEAD' ? null :
      (found ? MANUAL_HTML : 'Not Found'), {
      status: found ? 200 : 404,
      headers: {
        'Content-Type': found ? 'text/html; charset=utf-8' : 'text/plain; charset=utf-8',
        'Cache-Control': 'public, max-age=300'
      }
    });
  }
};

캐시 헤더가 뜻하는 범위를 확인한다

max-age=300은 캐시가 응답을 최대 5분 동안 신선한 것으로 취급할 수 있다는 의미다. 수정이 즉시 반영된다는 뜻은 아니다. Worker가 직접 만든 Response에 이 헤더를 붙였다고 자동으로 Cloudflare 엣지 캐시에 저장되는 것도 아니다. Static Assets의 제공 방식이나 Cache API 등 실제 캐시 경로를 따로 확인한다.

공개 문서만 공용 캐시에 넣는다. 로그인 사용자별 상태나 API 키가 섞인 페이지는 같은 방식으로 다루지 않는다. 중요 수정은 새 버전 식별자를 확인하고 브라우저 캐시와 엣지 캐시를 구분해 검사한다.

앱에서 문서로 바로 연결한다

설정 옆 도움말은 문서 첫 화면 대신 해당 항목의 고정 앵커로 연결한다. 일반 외부 링크를 열기 위해 확장 manifest에 windows 권한을 추가할 필요는 없다. 새 창 링크에는 noopener를 사용해 opener 참조를 분리하고, referrer 전달을 막을 목적이라면 noreferrer를 함께 사용한다.

도메인을 옮길 때는 기존 URL의 리디렉션을 유지하고 언어별 경로와 앵커도 점검한다. URL을 한 설정값에서 관리하면 수정 위치는 줄지만 이미 배포된 링크가 저절로 바뀌지는 않는다.

배포 검증은 다섯 가지면 구체적이다

실제 공개 URL에서 예상 제목·문서 버전·한글 인코딩을 확인한다.
모바일에서 메뉴, 코드 블록, 표가 가로로 넘치지 않는지 본다.
모르는 경로가 문서 복사본 대신 404를 반환하는지 확인한다.
샘플 화면에 실제 계좌·키·개인 식별 정보가 없는지 확인한다.
복구할 이전 문서 버전과 앱 버전의 대응을 기록한다.

서버를 직접 재부팅하지 않아도 도메인 갱신, 권한 관리, 배포 검증과 문서 갱신은 남는다. 운영 부담을 줄이는 선택의 효과는 이런 작업이 반복 가능해질 때 드러난다.

설정 저장소의 범위와 복구 기준을 문서화하기

참고 자료

내용·예제 검토: 2026-09-29

Cloudflare Workers로 매뉴얼 배포하기: 문서 구조와 캐시 검증