Upptime를 사용하여 무료로 자체 상태 페이지 구축하는 방법

2026. 6. 18.

AI 참여

이 페이지의 작성, 편집 또는 검토에는 AI가 참여했습니다.

중요한 내용은 신중하게 판단하고, 필요하면 1차 자료로 핵심 결정을 다시 확인하세요.

Upptime를 사용하여 무료로 자체 상태 페이지 구축하는 방법

모니터링 작업 전체를 GitHub 저장소로 옮겨보세요—Actions가 프로브 역할, 저장소가 데이터베이스, Pages가 CDN, Issues가 이벤트 로그. 서버 없이, 월 비용 없이, 볼 수 있고 조회할 수 있고 기록이 남는 상태 사이트를 만들어냅니다. 마법이라고 부르든, 가난한 사람의 지혜라고 부르든, 어쨌든 작동합니다.

배경

10개 이상의 대외 서비스로 구성된 소규모 제품 매트릭스를 운영할 때 “도대체 연결되는지 안 되는지”는 자주 입에 오르내리는 말이 됩니다. 고객이 접속할 수 없다고 피드백하고, ssh로 접속해서 curl을 돌려보니 정상입니다. 몇 분 뒤에 또 죽는데, 이번엔 못 봤습니다. 상업용 모니터링(Pingdom, UptimeRobot 고급 등급, Datadog)도 물론 해결할 수 있지만, 사이트당 요금이든 요청 횟수당 요금이든, 독립 개발자에게는 비용과 정신적 부담이 둘 다 그다지 타당하지 않습니다.

더 중요한 건, 상태 페이지 자체도 사용자가 조회할 수 있어야 한다는 점입니다. 이상적인 모습은 다음과 같습니다: 하나의 도메인(예: status.hagicode.com)이 각 서비스의 가용률, 응답 시간 곡선, 과거 이벤트를 실시간으로 보여주고, 장애 발생 시 자동으로 기록하고 자동으로 알림을 줍니다. 전통적인 방식은 네 가지 요소—cron을 실행하는 서버, 과거 데이터를 저장하는 데이터베이스, 프론트엔드 사이트, CD를 갖춰야 합니다. 이 네 가지가 늘어서면, 운영 비용은 즉시 모니터링 대상 서비스 자체를 넘어서게 됩니다. 닭 잡는 데 소 달린 칼을 쓰는 격이고, 닭조차 너무 비좁아합니다.

이러한 고통을 해결하기 위해, 우리는 결정을 내렸습니다: 모니터링 솔루션 전체를 GitHub로 옮기는 것입니다. 이 결정이 가져온 변화는, 당신이 생각하는 것보다 훨씬 클지도 모릅니다—나중에 천천히 말씀드리겠습니다.

HagiCode에 대하여

이 글에서 공유하는 솔루션은 HagiCode 프로젝트에서 뒹굴며 얻은 경험에서 나왔습니다. HagiCode는 AI 코드 어시스턴트 프로젝트로, 웹사이트, 문서 사이트, 다운로드 엔드포인트 등 10개 이상의 공공 서비스를 노출하고 있으며, 그 뒤에는 HagiCode-org/site라는 메인 저장소가 있습니다. 이러한 사이트는 반드시 안정적으로 사용 가능해야 하므로, 상태 모니터링은 우리에게 선택이 아닌 필수입니다. 아래这套 Upptime 솔루션은 HagiCode 실제 프로덕션 환경에서 사용 중인 것입니다—제가 지어낸 게 아닙니다.

분석: Upptime은 도대체 어떻게 실행되는가

Upptime의 본질은 GitHub 저장소 템플릿 하나와, 템플릿에서 생성된 여섯 개의 workflow입니다. 이해하는 열쇠는 “누가 언제, 누구를 호출하고, 무엇을 생산해서 어디에 떨어뜨리는가”를 명확히 보는 것입니다. 이것을 뜯어보면, 그렇게 신비하지 않습니다.

데이터 흐름: 하나의 설정 파일이 모든 것을 구동합니다

전체 시스템은 .upptimerc.yml이라는 하나의 선언적 설정 파일을 중심으로 돌아갑니다. HagiCode의 실제 설정 구조는 대략 이렇습니다:

owner: HagiCode-org
repo: upptime

sites:
  - name: HagiCode Website
    url: https://www.hagicode.com
  - name: HagiCode Docs
    url: https://docs.hagicode.com
  - name: Server Package Index
    url: https://index.hagicode.com/server/index.json
  # ... 총 14개 사이트

status-website:
  cname: status.hagicode.com
  logoUrl: https://raw.githubusercontent.com/HagiCode-org/upptime/master/assets/upptime-icon.svg
  name: HagiCode Status
  introTitle: "**HagiCode Status**"
  introMessage: Real-time availability tracking for public HagiCode websites and download endpoints.
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

여기서 두 가지를 꼽을만합니다. 첫째, sites는 웹페이지(HTML 반환)뿐만 아니라 순수 JSON 엔드포인트(예: index.json)도 모니터링할 수 있으며, Upptime은 HTTP 상태 코드와 응답 시간만 보고 내용 검증은 하지 않습니다. 둘째, cname은 status.hagicode.com을 가리키며, 이는 해당 도메인을 소유하고 있어야 하며 DNS를 GitHub Pages로 가리켜야 합니다—무료라고 해도 도메인은 내야 하니까요.

여섯 개 workflow의 분업

.github/workflows/ 아래 모든 파일의 상단에는 경고 Do not edit this file directly!가 있습니다—이들은 템플릿이 매주 자동으로 업데이트하므로, 당신은 .upptimerc.yml만 수정하면 됩니다. 각 workflow는 cron으로 트리거되며, 동일한 action upptime/uptime-monitor@v1.42.6의 다른 하위 명령을 호출하여 분명하게 분업하고 있어, 마음 편합니다:

Workflow	cron	명령	역할
uptime.yml	*/5 * * * *	update	5분마다 활성을 확인하고 history/*.yml에 씁니다
response-time.yml	—	response-time	응답 시간 통계를 계산합니다
graphs.yml	—	graphs	일/주/월/년 PNG 곡선을 생성합니다
summary.yml	—	summary	README의 상태 표를 업데이트합니다
site.yml	0 1 * * *	site	매일 정적 사이트를 빌드하고 Pages에 배포합니다
update-template.yml	0 0 * * *	—	매주 업스트림 템플릿을 동기화합니다

uptime.yml의 핵심 조각은 “프로브”가 어떻게 실행되는지 보여줍니다:

on:
  schedule:
    - cron: "*/5 * * * *"
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GH_PAT || github.token }}
      - name: Check endpoint status
        uses: upptime/uptime-monitor@v1.42.6
        with:
          command: "update"
        env:
          GH_PAT: ${{ secrets.GH_PAT || github.token }}
          SECRETS_CONTEXT: ${{ toJson(secrets) }}

site.yml에는 한 단계가 더 있어, peaceiris/actions-gh-pages@v4를 사용하여 빌드 산출물을 gh-pages 브랜치로 푸시합니다:

- uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GH_PAT || github.token }}
    publish_dir: "site/status-page/__sapper__/export/"
    user_name: "Upptime Bot"
    user_email: "73812536+upptime-bot@users.noreply.github.com"

데이터 저장: 파일이 데이터베이스입니다

모니터링 결과는 데이터베이스에 저장되지 않고, 파일 형식으로 저장소에 commit됩니다. 이것은 조금 야생처럼 들리지만, 사용해보면 꽤 든든합니다. 각 사이트에는 세 가지 유형의 산출물이 있습니다.

상태 스냅샷 history/{slug}.yml, 예: history/hagi-code-website.yml:

url: https://www.hagicode.com
status: up
code: 200
responseTime: 96
lastUpdated: 2026-06-17T00:22:34.485Z
startTime: 2026-03-24T10:07:32.531Z

shields.io의 endpoint 배지 데이터 소스 api/{slug}/response-time.json, uptime.json:

{"schemaVersion":1,"label":"response time","message":"739 ms","color":"yellow"}

그리고 응답 시간 곡선 그래프 graphs/{slug}/response-time-{day,week,month,year}.png.

이 “파일이 데이터베이스”라는 절충안은 사실 꽤 명확하게 생각했습니다: 쓰기 많고 읽기 적음, 규모 통제 가능(각 사이트 하루 약 288개 샘플, 전량이 아닌 증분 저장), 자연스럽게 버전 내역 포함, 인프라 제로. 대가는, 저장소가 지속적으로 커지고, 가끔 돌아보아야 한다는 점입니다.

이벤트와 알림: Issues가 이벤트 로그입니다

장애 기록은 GitHub Issues에 의존하며, 저장소에 내장된 두 개의 템플릿과 함께합니다: .github/ISSUE_TEMPLATE/bug_report.md(사용자 장애 보고)와 maintainance-event.md(계획된 유지보수). 유지보수 템플릿은 frontmatter로 시간 창을 표현합니다:

<!--
start: 2021-08-24T13:00:00.220Z
end: 2021-08-24T14:00:00.220Z
expectedDown: google, hacker-news
-->

Upptime은 이러한 Issue를 파싱하여 “유지보수 중”과 “발생한 이벤트”를 상태 페이지와 README에 렌더링합니다. 알림은 Issue 자체의 watch 메커니즘에 의존하며, 구성 가능한 webhook, Slack, Telegram( .upptimerc.yml 상단에 notifications 선언, HagiCode 예제 저장소는 현재 활성화하지 않음—하나라도 줄일 수 있으면 줄이니까요)을 추가할 수 있습니다.

해결: 5단계로 상태 사이트 복제하기

HagiCode와 동일한 상태 사이트를 복제하려면, 처음부터 라이브까지 총 5단계입니다. 5단계라고 하지만, 실제로 각 단계는 그리 길지 않으니 천천히 하시면 됩니다.

1단계: 템플릿에서 저장소 생성하기

git clone 후 수정하지 말고, GitHub의 “Use this template”로 저장소를 직접 생성하세요(예: your-org/upptime). 템플릿에는 이미 모든 workflow, Issue 템플릿, 정적 사이트 골격이 내장되어 있습니다. 로컬로 clone한 후, 수동으로 수정해야 할 것은 .upptimerc.yml뿐입니다—나머지는 그대로 두세요.

2단계: .upptimerc.yml 편집하기

owner/repo를 당신의 것으로 변경하고, sites에 모니터링할 주소를 나열하고, status-website로 사이트를 구성합니다. 최소 사용 가능 버전은 대략 다음과 같습니다:

owner: your-org
repo: upptime

sites:
  - name: Main Site
    url: https://example.com
  - name: API Health
    url: https://api.example.com/health
    expectedStatusCodes:
      - 200

status-website:
  cname: status.example.com   # 도메인이 없으면 삭제하고 기본값 your-org.github.io/upptime 사용
  name: Example Status
  introTitle: "**Example Status**"
  introMessage: 서비스 가용성 실시간 모니터링
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

고급 옵션: expectedStatusCodes는 허용 가능한 상태 코드를 제한(기본값 200-399); headers는 요청 헤더를 사용자 정의(인증이 필요한 엔드포인트용); maxResponseTime은 느린 응답을 표시합니다. 이것들은 당신의 필요에 따라 필요한 것만 사용하면 됩니다.

3단계: Secret 및 권한 구성하기

workflow는 기본적으로 ${{ secrets.GH_PAT || github.token }}을 사용합니다. github.token은 기본 흐름을 실행할 수 있지만, 두 가지 제한이 걸릴 수 있습니다:

1. 기본 token으로 트리거된 workflow는 하류 workflow를 다시 트리거하지 않습니다(순환 방지), 따라서 “활성 확인 → Issue 생성 → 알림” 체인이 중간에서 끊깁니다.
2. 저장소 간 작업(예: 다중 조직)에 대한 권한이 부족합니다.

PAT( repo + workflow 권한 필요)을 새로 생성하고, 저장소 Secret GH_PAT로 저장하는 것을 추천합니다. update-template.yml에 전용 확인 단계가 있습니다: GH_PAT가 없으면 템플릿 자동 업데이트를 건너뛰고 warning을 출력하므로, 이 secret은 선택이 아니라 마음 편함의 열쇠입니다.

4단계: GitHub Pages 활성화하기

저장소 Settings → Pages → Source에서 Deploy from a branch를 선택하고, 브랜치는 gh-pages, 디렉토리는 /root를 선택합니다. site.yml은 매일 새벽 1시에 자동으로 빌드 산출물을 이 브랜치로 푸시합니다. cname을 구성했다면, DNS 공급자에서 CNAME 레코드를 하나 추가하여 your-org.github.io를 가리키세요.

첫 번째 수동 트리거도 좋습니다: Actions 페이지에서 “Static Site CI”를 찾아 → Run workflow, 예약된 작업을 기다리지 마세요—결과를 일초라도 빨리 보면 마음이 일초라도 빨리 편해집니다.

5단계: 검증 및 유지보수

설정을 push한 후, Actions로 가서 “Uptime CI”가 5분마다 실행되는지, history/에 *.yml 파일이 나타나기 시작하는지 확인하세요. 상태 페이지 주소는 https://<your-org>.github.io/upptime/ 또는 사용자 정의 도메인입니다. 이후 사이트 추가, 도메인 변경은 .upptimerc.yml 파일 하나만 수정하면 되며, workflow는 전 자동입니다. HagiCode는 지난 1년 넘게 이这套 메커니즘으로 14개 엔드포인트의 가용성을 유지했으며, 별로 신경 쓰지 않았습니다.

실천: 밟은 함정은 모두 대신 밟았습니다

아래 몇 가지는 HagiCode 실제 운영에서 축적된 경험으로, 적어두면 당신도 굽이 적은 길을 갈 수 있습니다.

실천 1: 모니터링 세분성 선택

HagiCode는 웹페이지( https://www.hagicode.com)와 순수 데이터 엔드포인트( https://index.hagicode.com/server/index.json)를 동일한 sites 목록에 넣었습니다. JSON 엔드포인트의 경우, Upptime은 요청하고 HTTP 상태 코드를 파싱하지만, 내용 구조는 검증하지 않습니다. “200을 반환하지만 내용이 잘못됨”과 같은 심층 검사가 필요하다면, expectedStatusCodes에 외부 프로브를 추가해서 보완해야 합니다. Upptime 자체는 블랙박스 HTTP 검사만 합니다—얼굴만 보고 마음은 읽지 않습니다.

실천 2: 응답 시간 배지의 효과적인 사용

api/{slug}/response-time.json은 shields.io의 endpoint 배지 데이터 소스입니다. HagiCode의 README에는 이러한 URL이 대량으로 인용되어 있습니다:

https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FHagiCode-org%2Fupptime%2FHEAD%2Fapi%2Fhagi-code-website%2Fresponse-time.json

이렇게 하면 모든 Markdown(프로젝트 README, 블로그, 서드파티 페이지)에 실시간 응답 시간 배지를 임베드할 수 있으며, 색상은 message의 값과 color 필드로 구동됩니다. master/main이 아닌 HEAD로 raw 파일을 참조하면, 브랜치 이름 변경 후 대규모 실패를 방지할 수 있습니다—디테일 속에 안정이 숨어 있습니다.

실천 3: 저장소 크기 제어

5분마다 한 번 샘플링하면, 1년 동안 history/에 상당한 크기가 누적됩니다. Upptime은 전체 로그가 아닌 증분 YAML을 사용하므로 상대적으로 절제하지만, 여전히 정기적으로 저장소 크기를 한 번씩 보는 것을 추천합니다. 특정 사이트의 모니터링 가치가 떨어졌다면, sites에서 제거하면 되며, 해당 과거 파일도 수동으로 정리할 수 있습니다. 아까워서 지우지 않으면, 저장소는 결국 부풀어 올라 보여줄 것입니다.

실천 4: 유지보수 이벤트의 실제 사용법

maintainance-event.md는 장식이 아닙니다. 배포 계획 전, 템플릿에 따라 Issue를 열고 start/end/expectedDown을 채우면, Upptime은 이 시간 내의 해당 사이트를 “계획된 유지보수”로 표시하고 가용률 통계에 포함하지 않아, 정상적인 배포가 연간 SLA를 낮추는 것을 방지합니다. HagiCode의 expectedDown은 쉼표로 구분된 사이트 이름 목록을 지원하며, sites[].name과 일대일 대응합니다.

실천 5: 템플릿 업데이트와 사용자 정의의 경계

모든 .github/workflows/*.yml 상단의 Do not edit this file directly!는 당신을 겁주는 것이 아닙니다. update-template.yml은 매주 업스트림 템플릿으로 이러한 파일을 덮어씁니다. 사용자 정의 동작이 필요할 때, 올바른 방법은 .upptimerc.yml에서 공식적으로 지원되는 구성 항목(예: skipTopics, customStatusWebsite, runnerSettings)을 사용하는 것이지, workflow를 수정하는 것이 아닙니다. 정말로 workflow를 수정해야 한다면, update-template.yml을 끄거나, 템플릿을 fork해서 직접 유지하세요—후자는 무통 업그레이드를 잃게 되며, 득실 사이에서 직접 저울질하세요.

실천 6: 무료 한도의 현실적 제약

GitHub Actions는 공개 저장소에 무료이며 시간 제한이 없으므로, Upptime은 이 점을 활용하도록 설계되었습니다. 비공개 저장소는 매월 2000분 무료 한도가 있으며, uptime.yml이 5분마다 한 번 실행되고 매번 약 1분이면, 이 항목만으로 한 달에 약 8640분이 되어 초과합니다. 따라서 Upptime 저장소는 public이어야 하며, 이것은 “무료”라는 두 단어의 전제입니다—보안을 위해 private로 열었다가 청구서를 받으면 곤란합니다.

요약

처음 질문으로 돌아가서: 여러 대외 서비스를 모니터링할 때, 과연 저렴한 해결책이 있을까요? HagiCode의 대답은—있습니다, 그리고 저렴해서 진짜인지 의심될 정도입니다. Upptime은 모니터링을 네 가지 GitHub 네이티브 구성 요소로 분해했습니다:

• 프로브 = GitHub Actions의 cron
• 데이터베이스 = 저장소의 YAML/JSON 파일
• CDN = GitHub Pages
• 이벤트 로그 = GitHub Issues

당신은 다음을 얻습니다: 실시간 가용률, 응답 시간 곡선, 과거 이벤트, 가용률 배지, 사용자 정의 도메인, 자동 알림, 전부 서버 제로, 월 비용 제로. 대가는 저장소를 공개로 유지하고, 가끔 저장소 크기에 신경을 쓰는 것입니다. 사실 이 대가는, 직접 모니터링을 만드는 것에 비하면 이미 훨씬 가볍습니다.

이这套 솔루션이 작동할 수 있는 이유는, GitHub 생태계가 오픈소스 프로젝트에 대해 진심으로 보조를 제공하기 때문입니다. 당신도 다중 사이트 소규모 제품 매트릭스를 유지하고 있다면, 강력하게 오후 하나를 투자해서 구축해 보세요—직접 모니터링을 만드는 것보다 훨씬 마음 편합니다.

참고 자료

• Upptime 공식 저장소
• shields.io endpoint 배지 문서
• GitHub Actions 예약 작업 문서
• HagiCode 상태 사이트 예시

요약

“Upptime를 사용하여 무료로 자체 상태 페이지 구축하는 방법”을 둘러싸고, 더욱 안정적인 추진 방식은 핵심 구성, 종속성 경계, 랜딩 경로를 단계별로 통과한 후, 최적화 디테일을 보완하는 것입니다.

목표, 단계, 수락 기준이 명확해지면, 이러한 솔루션은 보통 더 원활하게 실제 인도 단계로 들어갈 수 있습니다.

AI 번역

이 페이지는 중국어 간체 원문을 바탕으로 AI 도움을 받아 번역되었습니다.

표현, 기술적 뉘앙스, 최신 업데이트를 확인해야 한다면 중국어 간체 원문도 함께 확인하세요.

중국어 간체 원문 보기

Tags:

• Upptime
• GitHub Actions
• 상태 모니터링
• 상태 페이지
• GitHub Pages
• HagiCode
• DevOps

Electron 앱을 Microsoft Store에 출시하는 방법: MSIX 패키징부터 스토어 제출까지

Electron에서 Windows 네이티브 API 호출 방법