Redd-Archiver

⭐ 이 프로젝트가 유용하다고 생각되신다면, 저장소에 스타(star)를 눌러주세요! 이는 다른 사람들이 도구를 발견하는 데 도움이 되며 지속적인 개발의 동기부여가 됩니다.

압축된 데이터 덤프(data dumps)를 유연한 배포 옵션을 갖춘 탐색 가능한 HTML 아카이브(archives)로 변환합니다. Redd-Archiver는 정렬된 인덱스 페이지를 통한 오프라인 브라우징(offline browsing) 또는 Docker 배포를 통한 전문 검색(full-text search)을 지원합니다. 모바일 우선 디자인(mobile-first design), 멀티 플랫폼 지원, 그리고 PostgreSQL 전문 검색 인덱싱(full-text indexing)을 통한 엔터프라이즈급 성능을 특징으로 합니다.

지원 플랫폼:

버전 1.0은 멀티 플랫폼 아카이빙, 30개 이상의 엔드포인트(endpoints)를 가진 REST API, AI 통합을 위한 MCP 서버, 그리고 대규모 처리를 위한 PostgreSQL 기반 아키텍처(architecture)를 특징으로 합니다.

🚀 빠른 시작

사라지기 전에 인터넷 역사를 기록하세요 - 도메인 없이 2분 만에 배포 가능합니다.

라이브 데모 체험하기: 예시 아카이브 둘러보기 →

→ QUICKSTART.md - 단계별 배포:

• 2분: Tor 은닉 서비스 (도메인 불필요, 포트 포워딩 불필요, CGNAT 환경에서도 작동)
• 5분: 로컬 테스트 (localhost 상의 HTTP)
• 15분: 프로덕션 HTTPS (Let's Encrypt 자동화)

왜 지금인가요? 커뮤니티는 차단되고, 플랫폼은 폐쇄되며, 토론은 사라집니다. 오늘부터 보존을 시작하세요.

문서

→ 처음 오셨나요? QUICKSTART.md - 2~15분 내에 배포 가능

→ 빠른 답변이 필요하신가요? FAQ - 일반적인 질문들에 대해 30초 내로 답변 제공

→ 도움이 필요하신가요? Troubleshooting - 일반적인 문제 해결

→ API를 사용하시나요? API Reference - 30개 이상의 REST 엔드포인트 (endpoints)

→ 작동 원리가 궁금하신가요? Architecture - 기술적 심층 분석

→ 배포 가이드 (Deployment guides):

• Tor Hidden Service - .onion 설정 (2분 소요, 도메인 불필요)
• HTTPS Production - Let's Encrypt SSL (15분 소요)
• Static Hosting - GitHub/Codeberg Pages (브라우징 전용)
• Docker Reference - 완전한 Docker 가이드

→ 고급 기능 (Advanced):

• MCP Server - AI 통합 (Claude Desktop/Code)
• Scanner Tools - 데이터 탐색 유틸리티
• Registry Setup - 인스턴스 리더보드

🎯 주요 기능 (Key Features)

🌐 멀티 플랫폼 지원 (Multi-Platform Support)

여러 링크 애그리게이터 (link aggregator) 플랫폼의 콘텐츠를 하나의 통합된 아카이브로 보관하세요:

• 자동 감지 (Automatic Detection): 파일 확장자를 통해 플랫폼 자동 감지
• 통합 검색 (Unified Search): PostgreSQL FTS (Full Text Search)를 통한 모든 플랫폼 통합 검색
• 혼합 아카이브 (Mixed Archives): Reddit, Voat, Ruqqus를 단일 아카이브로 결합

🤖 MCP 서버 (AI 통합)

AI 어시스턴트를 위해 OpenAPI로부터 자동 생성된 29개의 MCP 도구:

• 전체 아카이브 액세스 (Full Archive Access): Claude Desktop 또는 Claude Code를 통해 게시물, 댓글, 사용자 쿼리 및 검색 수행
• 토큰 오버플로 방지 (Token Overflow Prevention): 필드 선택 및 절단을 통한 LLM (Large Language Model) 가이드 내장
• 5개의 MCP 리소스 (5 MCP Resources): 통계, 인기 게시물, 서브레딧, 검색 도움말에 즉시 액세스
• Claude Code 준비 완료 (Claude Code Ready): 즉시 사용 가능한 복사-붙여넣기 설정 제공

{
  "mcpServers": {
    "reddarchiver": {
...

전체 설정 가이드는 MCP Server Documentation을 참조하세요.

핵심 기능

• 📱 모바일 우선 디자인 (Mobile-First Design): 모든 기기에 최적화된 반응형 레이아웃과 터치 친화적인 내비게이션 제공
• 🔍 고급 검색 시스템 (Advanced Search System, 서버 필요): Tor 네트워크에 최적화된 PostgreSQL 전문 검색 (Full-text search) 지원. 키워드, 서브레딧 (Subreddit), 작성자, 날짜, 점수(Score)로 검색 가능. Docker 배포가 필요하며, 오프라인 브라우징 시에는 정렬된 인덱스 페이지를 사용합니다.
• ⚡ JavaScript 프리 (JavaScript Free): JavaScript 없이도 완전한 기능을 제공하며, 순수 CSS 상호작용만으로 동작
• 🎨 테마 지원 (Theme Support): CSS만으로 구현된 내장 라이트/다크 테마 토글 기능
• ♿ 접근성 (Accessibility): 키보드 내비게이션 및 스크린 리더(Screen reader)를 지원하는 WCAG 준수
• 🚄 성능 (Performance): 최적화된 CSS (29KB)를 사용하여 저대역폭 네트워크에서도 원활하게 작동하도록 설계

기술적 우수성

• 🏗️ 모듈형 아키텍처 (Modular Architecture): 유지보수와 확장성을 위해 18개의 특화된 모듈로 구성
• 🗄️ PostgreSQL 백엔드 (PostgreSQL Backend): 데이터셋 크기에 관계없이 일정한 메모리 사용량을 유지하며 대규모 데이터 처리 가능
• ⚡ 초고속 검색 (Lightning-Fast Search): GIN 인덱싱을 활용한 PostgreSQL 전문 검색 (Full-text search)
• 🌐 REST API v1: 게시물, 댓글, 사용자, 통계, 검색, 집계(Aggregations) 및 내보내기(Exports)에 대한 프로그래밍 방식의 접근을 위해 MCP/AI에 최적화된 30개 이상의 엔드포인트 제공
• 🧅 Tor 최적화 (Tor-Optimized): JavaScript 미사용, 서버 측 검색, 외부 의존성 없음
• 📊 풍부한 통계 (Rich Statistics): 파일 크기 추적 기능이 포함된 종합 분석 대시보드
• 🔗 SEO 최적화 (SEO Optimized): 완전한 메타 태그 (Meta tags), XML 사이트맵 (Sitemaps), 구조화된 데이터 (Structured data) 제공
• 💾 스트리밍 처리 (Streaming Processing): 자동 재개(Resume) 기능이 포함된 메모리 효율적 방식
• 📈 진행 상황 추적 (Progress Tracking): 실시간 전송 속도, 예상 완료 시간 (ETA) 및 데이터베이스 메트릭 제공
• 🏆 인스턴스 레지스트리 (Instance Registry): 분산 아카이브를 위해 완성도 가중치 점수(Completeness-weighted scoring)를 적용한 리더보드 시스템

배포 옵션 (Deployment Options)

• 🏠 로컬/홈랩 (Local/Homelab): localhost 또는 LAN 상의 HTTP (명령어 2개)
• 🌐 프로덕션 HTTPS (Production HTTPS): 자동화된 Let's Encrypt 설정 (5분)
• 🧅 Tor 은닉 서비스 (Tor Hidden Service): .onion 접속, 네트워크 설정 불필요 (2분)
• 🔀 듀얼 모드 (Dual-Mode): HTTPS와 Tor 동시 사용
• 📄 정적 호스팅 (Static Hosting): 소규모 아카이브를 위한 GitHub/Codeberg Pages (조회 전용, 검색 불가)

📸 스크린샷 (Screenshots)

대시보드 (Dashboard)

Reddit, Voat, Ruqqus에 걸친 9,592개 게시물의 통계와 아카이브 개요를 보여주는 메인 랜딩 페이지입니다. 맞춤형 브랜딩(사이트 이름, 프로젝트 URL), 반응형 카드, 활동 지표 및 콘텐츠 통계를 제공합니다. (오프라인 작동)

서브레딧 인덱스 (Subreddit Index)

정렬 옵션(점수, 댓글, 날짜), 페이지네이션(Pagination), 배지 색상 지정이 포함된 게시물 목록입니다. 탐색 기능과 테마 전환 기능을 포함합니다. (오프라인 작동 - 점수/댓글/날짜순 정렬 가능)

댓글이 포함된 게시물 페이지 (Post Page with Comments)

접이식 UI(Collapsible UI), 사용자 플레어(User flair), 타임스탬프가 포함된 중첩된 댓글 스레드를 보여주는 개별 게시물 페이지입니다. 댓글에는 사용자 페이지에서 직접 이동할 수 있는 앵커 링크(Anchor links)가 포함되어 있습니다. (오프라인 작동)

모바일 반응형 디자인 (Mobile Responsive Design)

터치 친화적인 탐색과 반응형 레이아웃으로 모바일 기기에 완전히 최적화되었습니다.

검색 인터페이스 (Search Interface)

Google 스타일의 연산자를 사용하는 PostgreSQL 전문 검색(Full-text search)입니다. 서브레딧, 작성자, 날짜 범위 및 점수에 따른 필터링을 지원합니다. (Docker 배포 필요)

PostgreSQL의 ts_headline()을 사용하여 강조된 발췌문을 보여주는 검색 결과입니다. GIN 인덱싱을 통해 1초 미만의 응답 시간을 보장합니다. (서버 기반, Tor 호환)

샘플 아카이브 (Sample Archive): Reddit, Voat, Ruqqus의 프로그래밍 및 기술 커뮤니티를 특징으로 하는 멀티 플랫폼 아카이브 · 모든 스크린샷 보기 →

🛠️ 설치 (Installation)

사전 요구 사항 (Prerequisites): Python 3.7 이상, PostgreSQL 12 이상, 4GB 이상의 RAM

빠른 설치 (Quick Install) (Docker):

git clone https://github.com/19-84/redd-archiver.git
cd redd-archiver

...

상세 설치 절차 (Docker, Ubuntu/Debian, macOS, Windows WSL2):

• 설치 가이드 (Installation Guide) - 플랫폼별 설정 및 문제 해결

📊 사용법

빠른 워크플로우: 데이터 다운로드 → 아카이브 생성기 실행 → 배포

기본 예시

# 아카이브 생성 (data/ 디렉토리에 .zst 파일이 있다고 가정)
python reddarc.py data/ \
  --subreddit privacy \
...

멀티 플랫폼 지원

• Reddit: Pushshift의 .zst 파일 (3.28TB, 23.8억 개의 게시물)
• Voat: Archive.org의 SQL 덤프 (15GB, 380만 개의 게시물) - 1000배 빠른 속도를 위해 사전 분할 파일 (pre-split files) 사용
• Ruqqus: Archive.org의 .7z 파일 (752MB, 50만 개의 게시물)

상세 가이드

• QUICKSTART.md - 단계별 배포 (2~15분 소요)
• 스캐너 도구 (Scanner Tools) - 우선순위가 높은 커뮤니티 식별
• 설치 가이드 (Installation Guide) - 상세 설정 절차
• 배포 가이드 (Deployment Guides) - Docker, Tor, 정적 호스팅 (Static hosting)

CLI 옵션 및 고급 워크플로우: 전체 참조를 위해 QUICKSTART.md를 확인하세요.

환경 변수 (Environment Variables):

# 필수 항목
DATABASE_URL=postgresql://user:pass@host:5432/reddarchiver

...

🏗️ 아키텍처

18개의 특화된 HTML 모듈과 멀티 플랫폼 임포트 (Import) 지원을 갖춘 PostgreSQL 기반의 모듈형 설계:

핵심 구성 요소 (Core Components):

• reddarc.py - 플랫폼 자동 감지 기능이 포함된 메인 CLI 진입점 (Entry point)
• core/ - PostgreSQL 백엔드, 스트리밍 임포터 (Reddit/Voat/Ruqqus), HTML 생성
• api/ - 30개 이상의 엔드포인트(Endpoints)를 갖춘 REST API v1
• mcp_server/ - AI 통합을 위한 MCP 서버 (29개 도구)
• html_modules/ - 18개의 특화된 모듈 (Jinja2 렌더링, SEO, 통계, CSS 압축 (Minification))
• templates_jinja2/ - 상속 시스템을 갖춘 15개의 Jinja2 템플릿
• processing/ - 병렬 사용자 처리, 배치 (Batch) 최적화, 통계
• monitoring/ - 성능 추적, 자동 튜닝 (Auto-tuning), 시스템 최적화

주요 특징 (Key Features):

• 일정한 메모리 사용량을 유지하는 스트리밍 아키텍처 (데이터셋 크기에 관계없이 4GB 유지)
• 초당 15,000개 이상의 삽입 (Inserts)이 가능한 PostgreSQL COPY 프로토콜
• O(1) 쿼리를 위한 키셋 페이지네이션 (Keyset pagination)
• 데이터베이스 체크포인트를 통한 재개 (Resume) 기능
• FTS GIN 인덱싱을 통한 멀티 플랫폼 통합 검색

더 알아보기: ARCHITECTURE.md - 완전한 기술적 심층 분석

🌐 REST API 및 검색

MCP/AI 최적화를 통한 프로그래밍 방식의 접근을 지원하는 30개 이상의 REST API 엔드포인트 (Endpoints):

• System (5개): 상태 확인 (Health checks), 통계, 스키마 (Schema), OpenAPI 명세
• Posts (13개): 목록, 단일 항목, 댓글, 컨텍스트, 트리 (Tree), 관련 항목, 랜덤, 집계 (Aggregate), 배치 (Batch)
• Comments (7개): 목록, 단일 항목, 랜덤, 집계, 배치
• Users (8개): 프로필, 요약, 활동, 집계, 배치
• Subreddits (4개): 목록, 통계, 요약
• Search (3개): Google 스타일 연산자를 사용하는 전문 검색 (Full-text search), 쿼리 디버깅

AI 최적화 기능: 필드 선택, 절단 (Truncation) 제어, 내보내기 형식 (CSV/NDJSON), 배치 엔드포인트, 컨텍스트 엔드포인트. 분당 100회 요청으로 속도 제한 (Rate limited) 적용.

PostgreSQL 전문 검색 (Full-Text Search): 관련성 순위 지정 (Relevance ranking), 강조된 발췌문, 고급 필터 (Subreddit, 작성자, 날짜, 점수)를 갖춘 GIN 인덱스 기반의 초고속 검색. 대규모 데이터셋에서도 1초 미만의 결과 반환.

인스턴스 레지스트리 (Instance Registry): 아카이브 인스턴스를 추적하기 위한 분산형 리더보드 시스템. 메타데이터 구성, 점수 산정 자동화, 협력적 아카이빙을 위한 팀 그룹화 지원.

더 알아보기: API 문서 (API Documentation) · 검색 설정 (Search Setup) · 레지스트리 가이드 (Registry Guide)

🎯 활용 사례 (Use Cases)

연구 및 학술 (Research & Academia)

• 온라인 담론 및 커뮤니티 역학 연구
• 사회적 운동 및 트렌드 분석
• 인터넷 문화 보존

커뮤니티 아카이빙 (Community Archiving)

• 잠재적 삭제 전 서브레딧 (Subreddit) 백업
• 오프라인 접속 가능한 커뮤니티 리소스 생성
• 지식 저장소 배포

조사 및 분석 (Investigation & Analysis)

• 삭제/제거된 콘텐츠의 패턴 분석
• 사용자 행동 연구
• 콘텐츠 모더레이션 (Content moderation) 연구

🚨 참여하기: 인터넷 역사를 보존하는 데 도움을 주세요

인터넷 콘텐츠는 매일 사라집니다. 커뮤니티는 차단되고, 플랫폼은 폐쇄되며, 가치 있는 토론들은 자취를 감춥니다. 여러분이 이를 방지하는 데 도움을 줄 수 있습니다.

📥 지금 데이터 다운로드 및 미러링하기

콘텐츠가 사라질 때까지 기다리지 마세요. 지금 바로 이 데이터셋들을 다운로드하세요: