goatdash

goatdash는 [GoatCounter](https://www.goatcounter.com/) 분석을 위한 가볍고 개인정보 보호에 중점을 둔 대시보드입니다. 의존성, 빌드 도구, 자체 백엔드 서버 없이 순수 vanilla JavaScript로 클라이언트 측에서 완전히 실행됩니다. 배포는 단순히 몇 개의 정적 파일을 웹 호스트에 복사하는 것만으로 충분합니다. ## 주요 기능 이 대시보드는 HTTPS를 통해 공개 v0 API를 사용하여 하나 이상의 GoatCounter 인스턴스에 연결됩니다. 다음과 같은 분석 데이터를 표시합니다: - **5가지 KPI 카드**: 고유 방문자(추세 포함), 페이지뷰, 최상위 페이지, 추적된 경로, 총 이벤트 수. - **추천 경로 분석**: 채널별(직접, 검색 엔진, 캠페인, 기타 사이트) 트래픽 그룹화 및 개별 추천 경로와 유입 페이지에 대한 상세 분석(drill-down). - **단계 구분도(Choropleth) 세계 지도**: 제곱근 척도를 사용하여 방문 수에 따라 국가별 색상을 표시하며, 호버 툴팁, 확대/축소, 이동 및 초기화 기능을 제공합니다. - **전방위 상세 분석**: 어떤 페이지든 클릭하여 추천 경로를 확인하고, 추천 경로를 클릭하여 유입 페이지를 확인하며, 브라우저/시스템/기기를 클릭하여 버전을, 국가를 클릭하여 지역을, 캠페인을 클릭하여 소스 URL을 확인할 수 있습니다. - **유연한 날짜 범위**: 오늘, 7일, 30일, 90일 또는 사용자 지정 시작/종료 기간 설정이 가능합니다. ## 다중 사이트 지원 goatdash는 각 사이트가 고유한 도메인을 가지면서 단일 GoatCounter 계정을 공유하는 다중 사이트 설정에 최적화되어 있습니다. GoatCounter는 `Host` 헤더를 통해 올바른 사이트를 식별하므로, 대시보드는 각 사이트의 도메인으로 교차 출처(cross-origin) 쿼리를 수행합니다. 사이드바에는 API 키 권한 범위 내의 `/api/v0/sites`에 등록된 모든 사이트가 나열됩니다. 비활성 사이트의 백그라운드 사전 캐싱 덕분에 사이트 전환이 빠르게 이루어집니다. ## 아키텍처 및 스택 - **순수 JS 전용**: React, 번들러, CDN 호출이 없습니다. 총 7개의 정적 파일로 구성됩니다. - **백엔드 없음**: 브라우저가 GoatCounter API와 직접 통신합니다. 패치할 서버, 백업할 데이터베이스, 유지 관리할 서비스가 없습니다. - **서비스 워커(Service worker)**: 앱 셸과 버전 관리된 에셋을 캐싱하여 즉각적인 재로딩을 지원하며, API 응답은 stale-while-revalidate 방식으로 캐싱됩니다. - **테마**: 다크, 라이트 또는 자동 모드를 지원하며, 상단 바 버튼을 통해 전환됩니다. 엄격한 CSP(`default-src 'self'`)와 호환되는 외부 `theme.js` 스크립트가 렌더링 전에 테마를 적용합니다. - **언어**: 스페인어, 영어 또는 자동 감지를 지원하며 `localStorage`에 저장됩니다. - **데모 모드**: API 키 없이도 탐색할 수 있도록 실제와 유사한 샘플 데이터를 로드합니다. ## 설치 설치 스크립트나 컴파일 과정이 없습니다. 모든 HTTP 서버에서 정적 파일을 제공하면 됩니다: ```sh python3 -m http.server 8000 ``` 요구 사항: 정적 웹 서버와 브라우저에서 HTTPS를 통해 v0 API에 접근 가능한 GoatCounter 인스턴스가 필요합니다. Docker, Node 또는 빌드 도구는 필요하지 않습니다. 운영 환경의 다중 사이트 배포를 위해서는 웹 서버가 전용 도메인(예: `stats.example.com`)에서 파일을 제공하도록 설정하고, index HTML에 `Cache-Control: no-store`를 설정하십시오. 에셋 파일은 버전 쿼리 문자열(예: `app.js?v=3`)을 사용하며, 캐시 문제를 방지하기 위해 배포 시마다 버전을 업데이트해야 합니다. 선택 사항으로, 최신 GitHub 릴리스를 다운로드하고 SHA256 체크섬을 검증하며 현재 설치본을 백업한 후 새 버전으로 교체하는 systemd 기반의 주간 자동 업데이트 스크립트(`deploy/goatdash-update.sh`)가 제공됩니다. ## 설정 처음 로드 시 연결 화면에서 다음 정보를 요청합니다: - 사이트의 **GoatCounter URL** (예: `https://stats.cloudless.club`). - GoatCounter의 설정 > API에서 생성한 **API 키** (최소 Count 및 Read statistics 권한 필요). 두 값 모두 브라우저의 `localStorage`에 저장되며 HTTPS를 통해서만 GoatCounter 인스턴스로 전송됩니다. 테마, 언어, 선택된 사이트 및 날짜 범위 또한 로컬에 저장됩니다. 다중 사이트 설정의 경우, 각 사이트는 동일한 GoatCounter 설치본을 가리키는 고유 도메인을 가져야 합니다. GoatCounter는 `Access-Control-Allow-Origin: *`를 전송하여 프록시 없이도 교차 출처 요청을 가능하게 합니다. 인증된 모든 요청은 `OPTIONS` 프리플라이트(preflight)를 트리거하여 API 호출당 두 번의 왕복 통신이 발생함에 유의하십시오. ## 사용법 페이지를 열고 GoatCounter URL과 API 키를 입력하거나, **Try Demo**를 클릭하여 샘플 데이터로 탐색하십시오. 세그먼트 컨트롤을 사용하여 날짜 범위를 전환하고, 톱니바퀴 메뉴에서 테마/언어를 변경하거나 연결을 해제할 수 있으며, 메트릭 카드를 클릭하여 관련 데이터의 상세 내용을 확인할 수 있습니다. 새로고침 메뉴를 통해 캐시를 지우고 모든 데이터를 다시 가져올 수 있습니다. ## 개발 이 프로젝트는 `index.html`, `styles.css`, `theme.js`, `app.js`, `fixtures.js`, `sw.js`에 걸쳐 순수 HTML, CSS, JavaScript로 구성되어 있습니다. `package.json`, 번들러 또는 테스트 하네스가 없습니다. 로컬 개발 방법: ```sh python3 -m http.server 8000 ``` `fixtures.js`의 데모 고정 데이터는 실제 API 응답 형태를 반영합니다. ## 라이선스 AGPL-3.0. 세계 지도 에셋(`assets/world-map.js`)은 Abhishekh Singh의 MIT 라이선스 goatcounter-dashboard에서 그대로 가져왔으며 MIT 라이선스를 유지합니다.