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 리버스 프록시 + Namecheap 와일드카드 SSL