Web Inspector
웹 페이지 및 사이트 품질 검사 도구. HTML/CSS, 접근성, SEO, 성능/보안 4개 카테고리 기준으로 웹 페이지를 분석하고 점수와 개선 사항을 제공한다.
주요 기능
3가지 검사 모드
| 모드 | 설명 |
|---|---|
| 한 페이지 검사 | 단일 URL 입력 → AI 기반 품질 분석 → 점수/등급/이슈 리포트 |
| 사이트 크롤링 | 루트 URL 입력 → BFS 크롤링으로 페이지 자동 발견 → 전체 사이트 일괄 검사 |
| 목록 업로드 | .txt 파일로 URL 목록 업로드 → 일괄 검사 |
검사 카테고리 (4개)
- HTML/CSS — 마크업 품질, 시맨틱 태그, CSS 모범 사례
- 접근성 (Accessibility) — WCAG 가이드라인 준수, ARIA, 키보드 접근성
- SEO — 메타태그, 구조화 데이터, 크롤러 친화성
- 성능/보안 — 로딩 속도, HTTPS, CSP 헤더 등
실시간 진행 상태
- SSE (Server-Sent Events) + Redis Pub/Sub로 크롤링/검사 진행 상태 실시간 스트리밍
- 페이지별 검사 상태(대기→검사 중→완료) 실시간 업데이트
크롤러 특징
- BFS 기반 동일 도메인 링크 탐색
- URL 정규화: fragment 제거, trailing slash 제거, www. 제거, scheme/netloc 소문자화
- 리다이렉트 추적 → 최종 URL 기준 중복 제거
- 쿼리 파라미터가 다르면 유니크 URL로 판단
- max_pages는 유니크 URL 기준 카운트
Tech Stack
| 구분 | 기술 |
|---|---|
| Frontend | Next.js 15 (App Router), TypeScript, TailwindCSS, shadcn/ui |
| State | Zustand, TanStack React Query |
| Backend | FastAPI (Python 3.11), Pydantic v2 |
| Database | MongoDB 7.0 (Motor async driver) |
| Cache/PubSub | Redis 7 |
| AI | Claude API (검사 분석) |
| Infra | Docker Compose, Nginx (리버스 프록시 + SSL) |
Project Structure
web-inspector/
├── backend/
│ └── app/
│ ├── main.py # FastAPI 엔트리포인트
│ ├── core/
│ │ ├── config.py # 환경변수 설정
│ │ └── database.py # MongoDB + Redis 연결
│ ├── models/
│ │ ├── schemas.py # 단일 검사 스키마
│ │ ├── site_schemas.py # 사이트 크롤링 스키마
│ │ └── batch_schemas.py # 배치 검사 스키마
│ ├── routers/
│ │ ├── inspections.py # 단일 검사 API
│ │ ├── site_inspections.py # 사이트 크롤링 API
│ │ ├── batch_inspections.py # 배치 검사 API
│ │ ├── reports.py # 리포트 API
│ │ └── health.py # 헬스체크
│ └── services/
│ ├── inspection_service.py # 단일 검사 서비스
│ ├── site_inspection_service.py # 사이트 크롤링 + 검사
│ ├── batch_inspection_service.py # 배치 검사 서비스
│ ├── link_crawler.py # BFS 크롤러
│ └── report_service.py # 리포트 생성
├── frontend/
│ └── src/
│ ├── app/
│ │ ├── page.tsx # 홈 (탭 UI)
│ │ ├── history/page.tsx # 이력 (탭별)
│ │ ├── inspections/[id]/page.tsx # 단일 검사 결과
│ │ ├── inspections/[id]/progress/page.tsx # 단일 검사 진행
│ │ ├── site-inspections/[id]/page.tsx # 사이트 검사 결과
│ │ ├── site-inspections/[id]/progress/ # 사이트 검사 진행
│ │ └── batch-inspections/[id]/ # 배치 검사 결과/진행
│ ├── components/
│ │ ├── inspection/ # 탭 UI, 폼 컴포넌트
│ │ ├── site-inspection/ # 페이지 트리, 진행 상태
│ │ ├── batch-inspection/ # 배치 URL 목록, 진행
│ │ ├── dashboard/ # 점수 대시보드, 이슈 목록
│ │ └── history/ # 이력 테이블
│ ├── stores/ # Zustand 스토어
│ ├── hooks/ # SSE 훅, React Query 훅
│ ├── lib/ # API 클라이언트, 유틸리티
│ └── types/ # TypeScript 타입 정의
├── nginx/
│ └── nginx.conf # 리버스 프록시 + SSE 설정
├── docker-compose.yml
└── .env
Getting Started
# 환경변수 설정
cp .env.example .env
# ANTHROPIC_API_KEY 설정 필요
# 서비스 시작
docker compose up -d
# 서비스 로그
docker compose logs -f
# 빌드 후 시작
docker compose build --no-cache && docker compose up -d
API Endpoints
단일 검사
POST /api/inspections # 검사 시작
GET /api/inspections/{id} # 결과 조회
GET /api/inspections/{id}/stream # SSE 스트림
GET /api/inspections # 이력 (페이지네이션)
사이트 크롤링
POST /api/site-inspections # 크롤링 + 검사 시작
GET /api/site-inspections/{id} # 결과 조회
GET /api/site-inspections/{id}/stream # SSE 스트림
GET /api/site-inspections # 이력 (페이지네이션)
배치 검사
POST /api/batch-inspections # 파일 업로드 + 검사 시작
GET /api/batch-inspections/{id} # 결과 조회
GET /api/batch-inspections/{id}/stream # SSE 스트림
GET /api/batch-inspections # 이력 (페이지네이션)
Deployment
- URL: https://web-inspector.yakenator.io
- Gitea: https://gitea.yakenator.io/yakenator/web-inspector
- Server: Nginx 리버스 프록시 + Let's Encrypt 와일드카드 SSL