bsz

## 프로젝트 개요 `bsz`(Busuanzi)는 불잣자(Busuanzi) 통계 인터페이스와 호환되는 자호스팅 방문자 통계 시스템입니다. 백엔드는 Rust로 작성되어 컴파일 시 단 하나의 바이너리 파일만 생성되며, 외부 라이브러리 의존성이 전혀 없어 운영 비용이 크게 절감됩니다. 프론트엔드는 bun workspaces를 사용하며, 독립적인 소개 페이지(Landing)와 선택적 관리 대실(Admin)을 제공하여 필요에 따라 따로 배포할 수 있습니다. ## 주요 기능 - **단일 바이너리, 제로 의존성**: 백엔드는 단일 실행 파일만으로 VPS, Docker, 시스템 서비스에서 배포 가능합니다. - **불잣자 API 호환**: 기존 불잣자 스크립트를 사용하는 사이트는 통계 인터페이스 주소만 변경하면 마이그레이션할 수 있습니다. - **완전한 프론트엔드·백엔드 분리**: 백엔드는 JSON API를 제공하고, Landing은 순수 정적 페이지, Admin은 SPA로 세 가지 모두 독립 또는 조합 배포가 가능합니다. - **선택적 관리 대실**: `ADMIN_TOKEN` 설정으로 Admin API를 활성화할 수 있으며, 미설정 시 백엔드 라우트가 존재하지 않아 보안성이 높습니다. - **경량 프론트엔드**: Landing은 순수 정적 자원으로 GitHub Pages, Cloudflare Pages 등 정적 사이트에 호스팅 가능합니다. Admin은 Vite + React 기반으로 구축된 단일 페이지 애플리케이션입니다. - **로컬 디버깅 용이**: `cargo run` 및 `bun run dev:*` 빠른 시작 스크립트를 제공하여 개발과 데모에 적합합니다. ## 아키텍처 설명 ``` . ├── backend/ # Rust 백엔드, /api/* 통계 인터페이스 및 선택적 /api/admin/* 관리 인터페이스 제공 └── frontend/ # bun workspaces └── packages/ ├── shared/ # UI 컴포넌트, 테마, Tailwind 프리셋 ├── landing/ # 소개 페이지(apex), 순수 정적 └── admin/ # 관리 대실 SPA(dash), 선택적 배포 ``` - **backend**: `actix-web` 기반으로 구현되며, 기본적으로 통계 라우트만 마운트합니다. 환경변수 `ADMIN_TOKEN`이 비어있지 않으면 관리 라우트도 추가 마운트합니다. - **landing**: 정적 HTML, CSS, JS만 포함하여 방문자 카운트, 문서 링크, 관리 대실 진입口를 표시합니다. - **admin**: 로그인 후 실시간 방문자 데이터, 역사 통계, IP 블랙리스트 기능 등을 확인할 수 있으며, 모든 요청은 백엔드의 Admin API로 인증됩니다. ## 빠른 시작 (5분 내 실행) ```bash # 1. 백엔드 실행 (Terminal 1) cd backend && ADMIN_TOKEN=test-token cargo run # 2. Landing 실행 (Terminal 2) cd frontend && bun install bun run dev:landing # http://localhost:12702 방문 # 3. Admin 실행 (Terminal 3) bun run dev:admin # http://localhost:12705 방문 ``` ## 배포 가이드 ### 백엔드 배포 - **바이너리**: `cargo build --release`로 `target/release/bsz`를 생성하여 서버에 복사한 후, `ADMIN_TOKEN`(선택사항) 및 `PORT` 등 환경변수를 설정합니다. - **systemd**: 예시 unit 파일을 제공하여 자동 시작 및 로그 관리를 구현할 수 있습니다. - **nginx 리버스 프록시**: `/api/` 경로를 백엔드로 전환하고, 정적 자원은 CDN에 호스팅할 수 있습니다. ### Landing 배포 ```bash bun run build:landing # 산출물은 frontend/packages/landing/dist/에 위치 # dist/ 디렉터리를 GitHub Pages, Cloudflare Pages 또는 임의의 정적 호스팅 서비스에 업로드 ``` ### Admin 배포 ```bash VITE_API_BASE_URL=https://api.example.com \ bun run build:admin # 산출물은 frontend/packages/admin/dist/에 위치 # 동일하게 정적 호스팅 플랫폼에 배포 가능하며, 접속 시 백엔드 URL과 ADMIN_TOKEN을 입력하여 연동 완료 ``` ## 설정 설명 - `ADMIN_TOKEN`: 비어있지 않으면 백엔드가 `/api/admin/*`를 마운트하며, 프론트엔드 Admin은 동일한 토큰으로 인증합니다. - `VITE_API_BASE_URL`: Admin 프론트엔드 빌드 시 주입되는 백엔드 API 기본 주소입니다. - 기타 환경변수(`PORT`, `RATE_LIMIT` 등)는 `backend/.env`에서 기본값을 확인할 수 있습니다. ## 라이선스 본 프로젝트는 MIT 라이선스를 따르며, 자유로운 사용, 수정, 재배포가 허용됩니다. --- 더 상세한 문서는 저장소 내 `backend/README.md`, `frontend/packages/landing/README.md`, `frontend/packages/admin/README.md`를 참조하십시오.