2Ex-Hentai

Hitomi와 제한된 E-Hentai 공개 갤러리를 개인 환경에서 수집·저장·검색하고 읽기 기록을 관리하는 Docker 기반 모노레포다. 브라우저 요청은 Nginx의 단일 진입점을 거치며 PostgreSQL, Redis와 MinIO를 로컬 Docker 데이터로 사용한다.

주요 기능

• Hitomi Nozomi 기반 최신·증분·전체·명시 범위 수집, canonical ID·파일 지문 사전 중복 판정과 coverage 복구
• E-Hentai 공개 갤러리 보완 수집: Doujinshi·Manga·Artist CG·Image Set·Non-H·Misc의 관리자 수동 최신·증분·전체·명시 범위
• Hitomi AVIF·WebP와 E-Hentai 공개 원본 형식 보존
• PostgreSQL 제목·태그 검색, 이름별 통합 태그 자동완성, 포함·제외 필터와 갤러리 ID·페이지 수·무작위 정렬
• 공유 통계 snapshot과 한국시간 기준 최근 7일 차트
• 갤러리·작가·그룹 북마크, 읽기 진행률과 기간별 대시보드
• 블랙리스트 규칙, 실시간 로그 통합 검색과 체크포인트 재개
• 일반·관리자 passkey 계정, 사용자별 설정·썸네일 숨김과 개인 태그 차단
• invisible Turnstile 인증과 Redis grant·gallery lease 기반 원본 열람 보호
• desktop·mobile 반응형 UI와 공용 확인창, 한 페이지·두 페이지·웹툰 뷰어
• mobile browser-local PWA 설치 안내, browser cache 정리와 작가·그룹 북마크 Web Push 알림
• 최초 방문자의 만 19세 이상 확인과 확인 전 성인 콘텐츠 차단

실행 환경

• Windows Docker Desktop과 Docker Compose v2

Node.js를 직접 실행 환경으로 사용하지 않는다. 빌드, 실행과 테스트는 모두 Docker Compose에서 수행한다.

빠른 시작

1. 처음 설정할 때 환경변수 파일을 만든다. 기존 파일이 있으면 값을 보존한다.

if (-not (Test-Path -LiteralPath .env.develop)) {
  Copy-Item .env.example .env.develop
}

2. .env.develop의 CHANGE_ME_* 값을 모두 안전한 값으로 교체한다. 특히 다음 값은 반드시 설정한다.

• DATABASE_PASSWORD, REDIS_PASSWORD
• JWT_SECRET, COOKIE_SECRET
• ADMIN_SECURITY_KEY
• TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY(개발은 Cloudflare 공식 test key)
• MINIO_ROOT_USER, MINIO_ROOT_PASSWORD
• MINIO_ACCESS_KEY, MINIO_SECRET_KEY

로컬 passkey 사용 시 아래 값은 서로 일치해야 한다.

FRONTEND_URL=http://localhost:30000
CORS_ORIGIN=http://localhost:30000
WEBAUTHN_ORIGIN=http://localhost:30000
RPID=localhost

3. 설정을 검사하고 전체 서비스를 빌드한다.

docker compose --env-file .env.develop config --quiet
docker compose --env-file .env.develop up -d --build
docker compose --env-file .env.develop up -d --wait --wait-timeout 300
docker compose --env-file .env.develop ps

healthcheck가 있는 서비스가 healthy이고 byedpi가 Up이면 http://localhost:30000에서 접속한다.

서비스 구성

경로	역할
apps/backend	NestJS API, 인증, 검색과 통계
apps/web	Next.js UI, PWA manifest·mobile 설치 흐름과 Push service worker
apps/crawler	Hitomi 수집, E-Hentai 수집, 이미지 원본 검증과 저장
packages/shared	공용 타입, server-only 저장 helper, 블랙리스트 matcher와 태그 번역
sql/init-db.sql	fresh install 기준 PostgreSQL 최종 스키마
nginx	브라우저 진입점, API와 web reverse proxy
byedpi	허용된 source host의 TLS·연결 오류에 선택적으로 적용하는 crawler 전용 SOCKS sidecar
ops	Linux 운영 audit·backup·restore drill·soak·API latency 도구
docs	아키텍처, 운영 절차, 계획과 완료 이력

Docker Compose는 다음 서비스를 실행한다.

nginx -> web
      -> backend -> PostgreSQL / Redis / MinIO
                 -> crawler -> PostgreSQL / Redis / MinIO
                            -> Hitomi / E-Hentai (direct, 필요 시 ByeDPI)

브라우저는 backend나 crawler 컨테이너에 직접 접근하지 않고 http://localhost:30000/api/*를 사용한다.

데이터와 초기 스키마

로컬 데이터는 다음 경로에 영속화된다.

• data/postgres: PostgreSQL 데이터
• data/redis: Redis 데이터
• data/minio: 이미지 원본 객체
• data/nginx: Nginx cache

빈 PostgreSQL 데이터 디렉터리에서는 sql/init-db.sql이 최종 스키마와 기본 데이터를 한 번에 구성한다. hard reset 이전 migration은 지원하지 않으며 reset 이후 운영 데이터를 보존하는 변경만 새 TypeORM migration과 fresh schema에 함께 반영한다. 현재 migration과 데이터 소유권은 데이터베이스 스키마 정책을 단일 기준으로 사용한다.

data/ 삭제는 DB와 이미지 손실을 일으킨다. 초기화 전 ops/backup-production.sh로 PostgreSQL과 MinIO를 같은 복구 시점의 외부 filesystem에 보존하고 ops/restore-drill.sh로 시험 복구한다. 자세한 절차는 운영 가이드를 따른다.

관리자 인증

공개 갤러리 조회와 관리자 변경 API는 권한이 분리돼 있다. 최초 관리자 passkey 등록에는 .env.develop의 ADMIN_USERNAME, ADMIN_SECURITY_KEY, RPID, WEBAUTHN_ORIGIN을 사용하며 이후 로그인에는 등록한 passkey만 사용한다.

수집·실시간 로그·전역 블랙리스트는 크롤러 화면, 중복 후보 검토·가비지 컬렉션은 중복 관리에서 수행한다. source별 언어·카테고리 정책과 passkey 등록 문제는 운영 가이드를 기준으로 확인한다.

상태 확인

docker compose --env-file .env.develop ps
docker compose --env-file .env.develop logs backend --tail 100
docker compose --env-file .env.develop logs crawler --tail 100
docker compose --env-file .env.develop logs web --tail 100
docker compose --env-file .env.develop logs nginx --tail 50

Invoke-WebRequest -UseBasicParsing http://localhost:30000/api/health/live
Invoke-WebRequest -UseBasicParsing http://localhost:30000/api/health/ready

개발과 검증

변경된 앱과 관련 테스트를 선택하고 최종 수정 뒤 해당 서비스만 재빌드한다. 예를 들어 실시간 로그 동작을 수정했다면:

powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\run-unit.ps1 -Workspace web -TestPath src/components/crawler/LogViewer.test.tsx
docker compose --env-file .env.develop up -d --build web

DB·공용 흐름·passkey 등 변경 범위별 추가 검증과 runner 명령은 테스트 안내를 따른다. 문서만 변경한 경우에는 링크·경로·명령 존재 여부, Compose 구성과 git diff --check를 확인한다.

문서

기준 문서의 소유 범위와 현재 계획은 문서 색인, 제공 범위와 최신 검증 기준선은 완료 이력에서 관리한다. API 접근 계약은 API 계약, 검증 진입점은 테스트 안내, 작업 규칙은 루트 AGENTS.md와 영역별 작업 규칙을 따른다.

라이선스

Private Project. 개인 사용 목적의 저장소다.