AI 사냥개가 한국 커뮤니티 게시판에서 삭제 위협받는 익명 글(따뜻한 미담 또는 대기업 비위)을 길어 올리고, 소셜 로그인한 인간의 투표가 임계값에 도달하면 Arweave에 박제하는 Web2.5 타임캡슐 아카이브입니다.
Supabase 없이도 돌아갑니다 —
SUPABASE_*를 비워두면 내장 로컬 DB(기본 엔진: Rust 재작성 SQLite 인 Turso Database) + 게스트 인증으로 자동 폴백됩니다(5-1b 참고). 기존 Supabase 데이터는scripts/migrate_supabase_to_local.py로 통째로 이전할 수 있습니다.
AINSpace 주민형 archivist로의 전환을 위한 첫 vertical slice가 함께 제공됩니다. 현재
/.well-known/agent.json은 A2A v1 Agent Card를, /a2a는 TheWitness JSON-RPC endpoint를
제공합니다. Event/Memory 분리, deterministic significance, Recall, daily Chronicle과
5개 SQLite 테이블이 구현되어 있으며 기존 Heart & Critique API는 그대로 보존됩니다.
실행 및 메시지 예시는 docs/THEWITNESS.md를 참고하세요.
인터넷의 수많은 홍보(PR) 노이즈와 마케팅 찌라시 속에서 날것의 사실을 건져 올리는 **AI 사냥개(Scout/Critic)**와, 그 정보의 역사적 가치를 최종 판결하는 **인간 문지기(Gatekeeper)**가 결합한 온체인 타임캡슐 아카이브입니다.
- 목표(Goal): 돈(투기성 토큰) 때문에 오염되는 예측 시장이나 대기업의 자본력에 의해 삭제되는 Web2 커뮤니티의 사각지대를 해결합니다.
- 핵심 가치(Core Value): 인간 유저에게 지갑 연동, 가스비 결제 같은 Web3 진입 장벽을 강요하지 않으면서도, 소셜 로그인을 거친 인간의 '결단(투기 없는 순수한 가치 판단)'을 아위브(Arweave)에 영구 박제하여 데이터의 소유권과 영속성을 지킵니다.
유저의 UX는 완벽한 Web2 스타일을 따르고, 백엔드에서 AI 에이전트가 자율적으로 온체인 트랜잭션과 가스비를 처리합니다.
[User] OAuth Social Login (Google) — Supabase 미설정 시 게스트 신원(HMAC 토큰) ➔ Vote 'Approve' (공론화 찬성)
│
▼
[Backend/DB] Supabase(또는 내장 SQLite 로컬 백엔드) 테이블에 투표수 누적 & 중복 체크
│
▼
[Trigger] 특정 사건의 'Approve' 투표수가 임계값(Threshold)을 달성하는 순간
│
▼
[Crypto Agent Worker]
1. 해당 사건 데이터 + 인간 투표 로그를 JSON 데이터셋으로 묶음
2. 에이전트의 프라이빗 키로 데이터셋에 암호화 서명(Sign) 추가
3. Irys(구 Bundlr) SDK를 사용하여 Arweave에 영구 박제 (가스비 대납)
│
▼
[Frontend UI] 박제가 완료되면 아위브 트랜잭션 ID(Tx ID) 링크를 화면에 영구 노출
Docker
├── app (Python/FastAPI :8000)
│ ├── main.py # FastAPI 진입점 + JSON-RPC A2A 엔드포인트
│ ├── routers/
│ │ ├── stories.py # POST /api/story, GET /api/stories[/{id}]
│ │ ├── votes.py # POST /api/vote/{id}, GET /api/vote/{id}/status
│ │ ├── auth.py # POST /api/auth/guest — 로컬 모드 게스트 신원 발급(Supabase 모드에선 404)
│ │ ├── stats.py # GET /api/stats (대시보드 통계)
│ │ ├── feed.py # GET /feed/*.xml (Atom 피드: all/archived/extreme/deleted)
│ │ └── transparency.py # GET /api/transparency(정책 스냅샷), GET /api/verify/{id}(서명 검증)
│ └── services/
│ ├── llm.py # Groq/Gemini 스토리 생성 파이프라인
│ ├── hunter.py # 자동 사냥꾼 — 주기적 스토리 자동 생성 루프
│ ├── collector.py # 선제 수집기 — RSS로 화제글 미리 캡처(본문+해시+삭제확률) → 삭제 감시
│ ├── promoter.py # ★ 캡처→공개 승격 — hard 삭제된 캡처글을 익명 문학 스토리로 공개(PII 게이트)
│ ├── volatility.py # 삭제확률 예측기(결정적) — 캡처 우선순위·필터·UI 배지 랭킹 전용
│ ├── value.py # 아카이브 가치 스코어러(결정적) — 캡처/승격 우선순위·스팸 제외(docs/ARCHIVAL_CRITERIA.md)
│ ├── pii.py # 구조적 PII 스캐너 — 승격 공개 전 안전 게이트
│ ├── wayback.py # Wayback 위임 박제 — IA Save Page Now 큐(원본 삭제 대비 외부 스냅샷)
│ ├── proxyfetch.py # 추적 불가(봇차단) 출처의 프록시 2차 관측 — soft 신호 전용(옵트인)
│ ├── tracker.py # 출처/수집글 삭제 추적 + 적응형 재검사 스케줄(compute_next_check)
│ ├── nativetext.py # tracker 텍스트 파이프라인 Rust 가속 래퍼 — 미설치 시 동작 동일 파이썬 폴백
│ ├── transparency.py # 정책·가중치 실시간 스냅샷 + 박제물 서명 검증(docs/TRANSPARENCY.md)
│ ├── db.py # Supabase 클라이언트 싱글톤 — SUPABASE_* 미설정 시 localdb 로 자동 폴백
│ ├── localdb.py # 로컬 백엔드 (supabase-py 호환 서브셋, 스키마 자동 생성) — 기본 엔진
│ │ # pyturso(Rust 재작성 SQLite, 파일 포맷 호환), 미설치 시 sqlite3 폴백
│ ├── localauth.py # 게스트 인증 — HMAC 서명 토큰 발급·검증 (로컬 모드 전용)
│ ├── dberrors.py # APIError 단일 수입 지점 (postgrest 부재 환경 호환)
│ ├── crypto.py # EC 키 서명·검증 (secp256k1 ECDSA-SHA256)
│ └── archive.py # 스토리+투표 번들 → uploader 서비스 호출
├── uploader (Node.js/Irys :3000)
│ └── index.js # POST /upload → Irys → Arweave Tx ID 반환
├── native/ (Rust, PyO3) # hc_native — tracker 가시텍스트 추출+패턴 스캔 가속 (실측 8배, GIL 해제)
│ └── src/lib.rs # Dockerfile 멀티스테이지에서 abi3 휠로 빌드·설치
└── static/
└── index.html # 프론트엔드 (Supabase JS + 바닐라 JS UI) — 글 공유(/s/<id>)·🧾영수증 PNG/QR 내보내기 포함
- 사용자가
/api/story를 직접 호출하거나 백그라운드의hunter.py가 돌면서 스토리를 탐색합니다. - LLM 엔진(
services/llm.py)이 뉴스 및 커뮤니티 글을 모니터링하여 미담 혹은 비위 사건을 수집하고 한국어로 스토리를 생성 및 Supabase DB(stories)에 기록합니다. - 적합성 게이트(no_fit): 검색 결과에 진짜 해당 카테고리 글이 없으면 모델이
NO_FIT을 내고, 서로 다른 쿼리로 제한 재시도(RELEVANCE_MAX_ATTEMPTS)합니다. 모든 시도가 실패하면 빈 본문을 박제하지 않고503으로 알려 재시도를 유도합니다.- 휘발성(삭제확률) 점수는
critique에서만 채택 게이트로 씁니다.critique는 '자본 압박으로 곧 삭제될 폭로'가 핵심이라 저휘발 글을 거르지만,kindness(미담)는 삭제 위험과 무관하므로 저휘발이라고 버리지 않습니다(휘발성은 표시·랭킹 전용이라는 원칙과 일관). → 미담 생성이 저휘발 글을 과도하게 거부해no_fit → 503이 잦던 문제를 해소.
- 휘발성(삭제확률) 점수는
- 공급자 폴백(Groq → Gemini): 기본
groq(Tavily 검색 grounding)가 한도(분당TPM·일일TPD) 소진이나 일시 오류로 실패하면gemini(Google Search grounding)로 자동 폴백합니다. Gemini 호출은 일시적 5xx(고수요·UNAVAILABLE)·429·네트워크 오류에 지수 백오프로 재시도(GEMINI_MAX_ATTEMPTS)하여, 한 번의 일시 장애가 사용자503으로 번지지 않게 합니다. Gemini 응답의NO_FIT도 동일하게 감지해 본문 누수를 막습니다.
- 사용자가 구글 소셜 로그인 후 찬성(Approve) 투표를 누릅니다.
- 로컬(SQLite) 모드에선 로그인 대신 게스트 신원이 자동 발급됩니다: 프론트가
POST /api/auth/guest로 HMAC 서명 토큰을 받아 localStorage에 보관하고 같은 Bearer 경로로 투표합니다(중복 투표는 동일하게 DB UNIQUE로 차단, 401 시 1회 자동 재발급). 게스트 신원은 브라우저 단위라 OAuth만큼 강하지 않습니다 — 공개 운영엔 Supabase 모드 권장.
- 로컬(SQLite) 모드에선 로그인 대신 게스트 신원이 자동 발급됩니다: 프론트가
- 박제 임계값(Threshold):
- 기본값은
VOTE_THRESHOLD(기본값: 3). 단일 출처는 services/threshold.py의DEFAULT_THRESHOLD입니다. DYNAMIC_THRESHOLD=true로 활성화 시 활성 투표자 수에 비례하여 동적으로 조정됩니다.- 검열 신호(출처 글 삭제 감지, 언론 보도 격차 발생 등)가 감지되면 임계값이 최저 1표까지 낮아져, 본문이 완전히 사라지기 전에 박제되도록 유도합니다.
- 기본값은
- 투표수가 임계값에 도달하는 즉시 백그라운드에서
archive_story()가 트리거됩니다. - 에이전트의 개인키(
AGENT_PRIVATE_KEY)를 통해 ECDSA 서명(secp256k1 SHA-256)을 생성하여 데이터 신뢰성을 보장합니다. - Node.js 기반의
uploader컨테이너가 Irys SDK를 사용해 데이터를 Arweave에 업로드하고 트랜잭션 ID(Tx ID)를 받아 Supabase에 반영합니다.
- 왜 필요한가: 검색(Tavily/구글)은 이미 삭제된 글을 구조적으로 가져올 수 없습니다 — 삭제되면 인덱스에서 사라지고, 검색은 살아남은 인기글(개념글/베스트)만 돌려주기 때문입니다. 따라서
hunter의 검색 경로만으로는 사실상 '삭제되지 않을 글'만 박제하게 됩니다. 진짜로 사라지는 글을 잡으려면 살아있을 때 미리 잡아두고, 죽는 것을 감시해야 합니다. - Collector (
COLLECTOR_ENABLED=true): RSS·공개 목록의 링크를 영속 대기열에 기록하고 사이트별 예산으로 본문·이미지를 캡처합니다. 본문·해시·점수·보존물 참조는 비공개captured_posts에, HTML·이미지·manifest·오프라인 사본은data/captures에 저장합니다. 실패한 첫 캡처도 재시도하며 최초 성공 원본은 덮어쓰지 않습니다. - Tracker (
compute_next_check적응형 주기): 캡처/출처 URL을 재방문해 삭제를 감지합니다. **HTTP 404/410(hard 삭제)**가 확인되면hard_deleted_at을 기록합니다 — 이것이 '확정 삭제' 신호입니다. 본문 패턴·메인 리다이렉트 같은 soft 신호는 오탐(살아있는 글의 정상 UI에 매치) 가능성이 있어 자동 박제 트리거로 쓰지 않습니다.
수집 사이트 확인: 화면 상단의 수집 사이트에서 사이트명·게시판·도메인을 검색하고,
수집 대상 / 확인 필요 / 수집 제외로 필터링할 수 있습니다. 수집 방식, 마지막 확인 시각,
새 링크·캡처 건수와 오류 사유를 함께 표시합니다. 가벼운 공개 API는 GET /api/sources입니다.
카탈로그는 23개 사이트·26개 목록, 자동 수집 대상은 12개 사이트·15개 목록입니다.
인벤 오픈이슈갤러리·루리웹 유머 베스트·퀘이사존 자유게시판을 추가했습니다.
접근 제한 또는 허가가 필요한 11개 목록은 사유를 표시하고 자동 수집에서 제외합니다. 전체 게시판과 동작 설명은
수집 사이트 안내, 단일 설정 목록은
services/community_sources.py를 참고하세요.
보존물 검증과 Wayback/Common Crawl 과거 사본 복구 명령은 커뮤니티 아카이빙 운영 안내에 있습니다.
captured_posts는 그동안 '죽어도 아무도 못 보는' 비공개 보관함이었습니다. Promoter(PROMOTER_ENABLED=true)가 마지막 고리를 이어, 실제로 사라진 글을 공개 박제 파이프라인에 올립니다.
[검색의 한계] Tavily/구글은 이미 삭제된 글을 못 준다 (인덱스에 없음, 살아남은 글만 줌)
│ 그래서 ↓ 살아있을 때 미리 잡는다
[Collector] RSS/공개 목록 폴링 → 화제글 본문+해시+삭제확률(volatility)을 captured_posts(비공개)에 보관
│
[Tracker] 적응형 주기로 재방문 → HTTP 404/410 확인 시 hard_deleted_at 기록 (= 확정 삭제)
│
[Promoter] hard 삭제된 캡처글을 골라:
│ 1. PII 게이트(services/pii.py): 주민번호·전화·이메일·카드·계좌 검출 시 차단
│ 2. 익명 재작성(llm.generate_from_text): 검색 없이 보관 본문만 → '한 누리꾼' 전언체·헤지·면책문
│ 3. 삭제확률 필터(PROMOTER_MIN_VOLATILITY): 저가치 잡담 제외
│ 4. stories에 from_capture=true INSERT + 죽은 원본 URL을 citation 등록
▼
[공개·투표] 이제 사람이 볼 수 있고 투표 가능. 죽은 원본 citation 은 '사라진 출처'
배지로 표시된다(임계값 인하는 tracker 가 살아있는 걸 직접 목격한 뒤
삭제된 hard 신호만 반영 — 이미 죽은 채 등록된 링크는 표시 전용).
안전 원칙 (Arweave 박제는 되돌릴 수 없으므로):
- 자동 승격은 hard 삭제(404/410)만. soft 삭제(본문 패턴/리다이렉트/본문 급감)는 오탐 자가정정 가능성이 있어 자동 박제하지 않습니다(
tracker/threshold의 hard-only 원칙과 일관). - PII 게이트 2중(원본 본문 + LLM 출력) — 구조적 식별자 검출 시 차단(
blocked_pii)하고 수동 검토 큐로 보냅니다. 비공개 원본 본문은 절대 그대로 공개하지 않으며, 환각방지·헤지·면책 가드레일을 통과한 LLM 익명 재작성문만 공개합니다. critique(기업 비위): 명예훼손 노출이 커 기본은 수동 검토(pending_review).PROMOTER_AUTO_CRITIQUE=true로 자동 승격을 켤 수 있습니다.- **삭제확률 점수(
volatility.py)**는 캡처 우선순위·승격 필터·UI 배지 랭킹 전용입니다 — 스토리 생성 게이트나 박제 임계값에는 절대 주입하지 않습니다(임계값 인하는 오직 hard 삭제 신호로만). - 멱등:
stories.origin_captured_urlUNIQUE로 같은 원본의 중복 승격을 차단합니다. - 수동 승격(어드민):
ADMIN_TOKEN설정 시POST /api/admin/promote?url=...(X-Admin-Token헤더)로 검토 후 직접 공개할 수 있습니다.
한 줄 요약: 검색은 살아남은 글만 준다 → Collector가 살아있을 때 잡고 → Tracker가 죽는 걸 감시하고 → Promoter가 확정 삭제된 글을 PII·익명화 게이트를 거쳐 공개 박제한다. 이 경로만이 '정말 사라지는 글'을 박제한다.
WAYBACK_ENABLED=true설정 시 작동합니다.- 수집된 출처 URL을 Internet Archive(IA)의 Save Page Now API에 대기열(Queue) 형태로 위임 요청합니다.
- 이를 통해 크롤링 차단 우회 및 공인된 외부 스냅샷 링크(
archive_url)를 확보하고, 스토리 조회 시 제공합니다.
별도 백엔드 없이 클라이언트 사이드(static/index.html)에서만 동작하는 두 가지 내보내기 기능입니다.
- 🔗 공유: 각 글마다 OG 미리보기가 붙는 영속 링크
/s/<id>를 복사하거나 네이티브 공유 시트로 전달합니다. 주소창은 글을 열 때#story=<id>로 동기화되어 새로고침·뒤로가기·딥링크가 가능합니다. - 🧾 영수증: 글을 영수증 형태의 PNG 이미지로 저장합니다. 외부 렌더 라이브러리 없이 **순수
<canvas>**로 그립니다.- 상단 QR 코드 — 박제된 글이면 Arweave 영구 원본(
gateway.irys.xyz/devnet) 주소를, 아직 박제 전이면 글 영속링크(/s/<id>)를 가리킵니다. QR 아래에 해당 URL을 텍스트로도 인쇄합니다. - 하단 본문 — 글 내용을 영수증체 작은 글씨로(한글 글자 단위 자동 줄바꿈) 출력하고, 그 위에 메타 영수증 행(분류·발행일·글번호·출처/삭제 수·박제 Tx 또는 투표 현황·체인)과 가짜 바코드·위아래 절취선(톱니)을 그려 실제 영수증 질감을 냅니다.
- QR 인코더(
qrcode-generator)는 버튼 클릭 시점에 jsdelivr CDN에서 1회 지연 로드하며 SRI 해시로 고정(변조 시 실행 거부)합니다. 로드/생성에 실패하면 QR 대신 링크 박스로 우아하게 폴백합니다. - 저장 방식: 데스크톱은
<a download>로 바로 다운로드, 터치 기기(특히 iOS)는 파일 공유 시트(navigator.share({files}))로 사진·파일에 저장합니다. - 안전장치: 동시 호출 차단, 본문 줄 수 클램프(브라우저 캔버스 32767px 한계 회피), QR 입력 길이 가드,
toBlob→toDataURL폴백.
- 상단 QR 코드 — 박제된 글이면 Arweave 영구 원본(
- 목록 헤더의 🔍 검색창에 키워드를 입력하면 (로드된 목록이 아니라) 전체 아카이브를 서버에서 검색합니다(
GET /api/stories?q=). 본문(body)과 시적 사유(poetic_reason)를 대소문자 무시 부분일치로 매칭합니다. - 입력 문자열은 PostgREST 필터 구조 문자(
* % _ , ( ) \ ")를 제거(_sanitize_search)해 필터 인젝션·와일드카드 누수를 차단한 뒤or_(body.ilike.*kw*,poetic_reason.ilike.*kw*)로 질의합니다. - 프론트엔드는 300ms 디바운스(+Enter 즉시 실행)로 호출하며, 결과 수·빈 결과 안내·지우기(✕)를 표시합니다. 기존 카테고리 필터 칩은 검색 결과 위에 그대로 적용됩니다.
services/value.py가 "사라지면 아까운 정도"를 0~10 결정적 점수로 평가합니다(기준 연구:docs/ARCHIVAL_CRITERIA.md— 셸렌버그 증거/정보가치, 유일성, DocNow 윤리 하한). 1인칭 직접 경험·물증(녹취/영수증/CCTV)·공익 제보(실명+고발)·내부고발·소비자 안전·목격 미담은 가산, 질문글·기사 펌글·한 줄 글은 감산됩니다.- collector의 캡처 우선순위가 기존 삭제확률(volatility) 단독에서 삭제위험+가치 결합 점수로 바뀌고, 광고·거래 글(hard negative)은 본문 GET 예산 자체에서 제외됩니다(단 "허위 광고에 당했다" 류 피해 고발은 보호). promoter의 승격 순서는 가치 우선으로 정렬됩니다(
migrations/011_value_score.sql적용 시 — 미적용이어도 자동 폴백). - 원칙: volatility와 동일하게 점수는 우선순위·표시 전용 — 박제 결정·투표 임계값에는 절대 주입하지 않습니다. 가중치는
VALUE_W_*로 튜닝하며 현재 적용값은GET /api/transparency로 공개됩니다.
- fmkorea 등 봇차단으로 "🚫 삭제 추적 불가"였던 출처를
services/proxyfetch.py가 렌더링 프록시(기본 Jina Reader)로 2차 관측합니다. 직접 관측이 봇차단으로 실패했을 때만 발동합니다. - soft 신호 전용 설계: 절대 hard(404/410)를 만들지 않아 임계값 인하·자동 승격에 영향이 없고, 배지·표시만 정확해집니다. 프록시 관측에 성공하면 추적 불가 라벨이 해제됩니다.
- 기본 꺼짐(
PROXY_FETCH_ENABLED=false) — 출처 URL이 프록시 사업자에 전달되는 트레이드오프가 있어 옵트인이며, 이 한계는docs/TRANSPARENCY.md에 공개되어 있습니다.
GET /api/transparency: 서버가 지금 실제로 적용 중인 정책·가중치·게이트·활성 모듈·에이전트 공개키의 실시간 스냅샷. 문서(docs/TRANSPARENCY.md)의 '약속'과 대조하면 약속 위반이 드러나는 구조입니다.GET /api/verify/{story_id}: 박제된 글의 Arweave 번들을 허용 게이트웨이에서 직접 받아 ECDSA(secp256k1-SHA256) 서명을 검증하고, 박제 이후 DB 본문이 몰래 바뀌지 않았는지까지 대조합니다(body_matches_db). 서버 없이 재현하는 절차는docs/TRANSPARENCY.md참고.- 출처 citation에
content_fingerprint(첫 생존 확인 시점 본문의 sha256)가 노출되어, 원문 재공개 없이 "그 시각에 그 내용이 존재했음"을 제3자가 대조할 수 있습니다. - 프론트 하단의 접이식 투명성 패널이 같은 스냅샷을 사람이 읽는 9섹션 형태로 렌더하고, 박제된 글 상세의 "🔐 박제 무결성 검증" 카드는 브라우저에서 서명 검증 + 박제본↔화면 본문 대조를 독립 수행합니다.
- '목격한 삭제'만 임계값 인하: 살아있는 원본을 직접 확인(기준선 캡처)한 뒤의 hard 404/410/403 만 박제 임계값을 낮춥니다 — 첫 접촉부터 죽어 있던 링크(오탐 구분 불가)는 배지 전용. 승격 글의 죽은 원본은 collector 의 생전 목격 기록을 기준선으로 승계합니다.
SUPABASE_*미설정(또는DB_BACKEND=local) 시services/db.get_db()가services/localdb.py로 자동 폴백합니다. supabase-py 쿼리 인터페이스의 사용 서브셋(에러코드23505/23503,or_중첩 필터, PostgreSQL식 NULLS 정렬,count=exact, RPC 등)을 그대로 재현해 라우터·tracker·cleanup 코드 무수정으로 동작하며, 전체 마이그레이션이 적용된 스키마를 자동 생성합니다.- 저장 엔진은 기본이 pyturso(Turso Database — SQLite 를 Rust 로 재작성한 인프로세스 DB, SQLite 파일 포맷·핫 WAL 양방향 호환)이고, 미설치 환경은 stdlib
sqlite3(C)로 자동 폴백합니다(LOCAL_DB_ENGINE으로 강제 가능). 같은 DB 파일을 두 엔진이 그대로 공유하므로 엔진 전환에 변환이 필요 없습니다. - 인증은 게스트 토큰(
services/localauth.py)으로 대체되고,/api/config의auth_mode: "guest"를 보고 프론트가 자동 전환합니다. 기존 Supabase 배포는 무변경(env 있으면 기존 경로). 계약은tests/test_localdb.py가 두 엔진 파라미터라이즈로 고정합니다. 실행법은 5-1b 참고. - 기존 Supabase 데이터 이전:
docker compose build app && docker compose run --rm --no-deps app python scripts/migrate_supabase_to_local.py(읽기 전용 export → 자연키 upsert, 재실행 안전, 행 수 대조 리포트).
- 출처 삭제 감시의 CPU 핫패스(가시텍스트 추출 + 삭제/차단/봇 패턴 매칭)를 Rust(
hc_native, PyO3 + regex crate)로 가속: 실측 8배(80KB 페이지 14.8ms→1.9ms), GIL 해제 실행으로 async 이벤트 루프 스톨 제거. - 탐지 패턴의 단일 출처는 여전히
tracker.py의re.compile—.pattern문자열을 그대로 전달하므로 패턴 수정이 자동 반영됩니다.hc_native미설치·패턴 비호환·NATIVE_TEXT_ENABLED=false면 동작 동일한 파이썬 폴백으로 조용히 전환됩니다(패리티는tests/test_nativetext.py의 픽스처+퍼즈 200케이스가 고정).
- 🗳 내 투표(
GET /api/my/votes): 로그인 계정으로 투표한 글만 모아 보는 개인 아카이브 필터 — 내 결단이 박제로 남는 과정을 추적할 수 있습니다. - 중복 스토리 방지(
services/dedup.py): 이미 스토리로 만든 출처 URL 을 검색 후보에서 선제 제외해 같은 글의 근사 중복(투표 분산·이중 박제)을 막습니다(STORY_DEDUP_ENABLED, 기본 켜짐). 적용 상태는/api/transparency의generation_gates로 공개됩니다.
프로젝트를 실행하려면 루트 디렉토리에 .env 파일을 만들고 아래 변수들을 설정해야 합니다.
| 변수명 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
SUPABASE_URL |
선택 | - | Supabase 프로젝트 URL. 미설정 시 SQLite 로컬 백엔드 + 게스트 인증으로 자동 폴백 (아래 'Supabase 없이 실행' 참고) |
SUPABASE_ANON_KEY |
Supabase 사용 시 | - | 클라이언트(프론트엔드)용 Supabase Anon Key |
SUPABASE_SERVICE_ROLE_KEY |
Supabase 사용 시 | - | 서버 사이드 관리자 권한용 Service Role Key |
DB_BACKEND |
선택 | 자동 | local(로컬 강제) 또는 supabase(강제). 미설정 시 SUPABASE_* 유무로 자동 판별 |
LOCAL_DB_PATH |
선택 | data/heartcritique.db |
로컬 모드 DB 파일 경로 (Docker에선 ./data 볼륨에 영속) |
LOCAL_DB_ENGINE |
선택 | 자동(turso) |
로컬 모드 저장 엔진: turso(Rust, pyturso) 또는 sqlite(C stdlib). pyturso 미설치 시 자동 sqlite 폴백 — 파일 포맷이 같아 두 엔진이 한 파일을 공유 |
GUEST_TOKEN_SECRET |
선택 | 자동 생성 | 게스트 토큰 HMAC 비밀키. 미설정 시 데이터 디렉터리 guest_secret 파일에 자동 생성·영속 |
GUEST_RATELIMIT_PER_IP |
선택 | 10 |
게스트 신원 발급(로컬 모드) IP당 윈도우 내 상한 |
AGENT_PRIVATE_KEY |
필수 | - | 에이전트 Ethereum 개인키 (서명 및 Irys 가스비 대납용) |
LLM_PROVIDER |
선택 | groq |
LLM API 제공자 (groq 또는 gemini) |
GROQ_API_KEY |
Groq 사용 시 | - | Groq Cloud API Key |
TAVILY_API_KEY |
Groq 사용 시 | - | Tavily Search API Key |
GEMINI_API_KEY |
Gemini 사용 시 | - | Google Gemini API Key (Search Grounding 적용). 설정 시 Groq 실패의 폴백 경로로도 쓰임 |
GEMINI_MAX_ATTEMPTS |
선택 | 5 |
Gemini 호출의 일시 오류(5xx·429·네트워크) 재시도 횟수(지수 백오프). Groq 한도 소진 시 Gemini가 단독 경로가 되므로 고수요 스파이크를 견디게 함 |
GEMINI_RETRY_BASE |
선택 | 1.5 |
Gemini 재시도 백오프 기준 초 (1.5→3→6→12… ≈ 최대 ~22초) |
RELEVANCE_MAX_ATTEMPTS |
선택 | 2 |
적합성 게이트가 NO_FIT일 때 다른 쿼리로 재시도하는 최대 횟수 (Groq TPM 안전을 위해 기본 2) |
IRYS_NETWORK |
선택 | devnet |
devnet(약 60일 임시 저장) 또는 mainnet(영구 저장, 가스비 소모). devnet 모드 시 UI에 임시 배지가 표시됩니다. |
VOTE_THRESHOLD |
선택 | 3 |
박제 트리거에 필요한 기본 투표수 |
DYNAMIC_THRESHOLD |
선택 | true |
활성 투표자 수 및 검열 신호에 따라 임계값 동적 변동 여부 |
COLLECTOR_ENABLED |
선택 | false |
RSS·공개 목록 선제 수집기 활성화 여부 (migrations/006 및 013 필요) |
PROMOTER_ENABLED |
선택 | false |
★ 캡처→공개 승격기 활성화. hard 삭제된 캡처글을 익명 재작성·PII 게이트 후 공개 (migrations/009 + COLLECTOR_ENABLED=true 필요) |
PROMOTER_AUTO_CRITIQUE |
선택 | false |
critique(기업 비위) 캡처도 자동 승격할지. 기본은 수동 검토(pending_review, 명예훼손 노출 최소화) |
PROMOTER_MIN_VOLATILITY |
선택 | 0 |
승격 최소 삭제확률(0~10). 높일수록 저가치 잡담을 걸러내고 고위험 글만 공개 (hard 삭제가 이미 강한 게이트) |
ADMIN_TOKEN |
선택 | - | 설정 시 POST /api/admin/promote(수동 승격) 활성화. X-Admin-Token 헤더로 인증. 미설정이면 엔드포인트 비활성(404) |
STORY_DEDUP_ENABLED |
선택 | true |
이미 스토리로 만든 출처 URL 을 검색 후보에서 제외(중복 스토리 방지). DB 조회 실패 시 필터 없이 통과 |
STORY_CLEANUP_MAX_VOTES |
선택 | 임계값-1 | 이 표 수 이하의 오래된 미박제 글만 정리. 캡처 승격글(from_capture)은 항상 보존 (migrations/010 권장) |
WAYBACK_ENABLED |
선택 | false |
Internet Archive Wayback Machine 백업 위임 활성화 여부 (migrations/007 필요) |
IA_ACCESS_KEY |
Wayback 사용 시 | - | Internet Archive S3 Access Key |
IA_SECRET_KEY |
Wayback 사용 시 | - | Internet Archive S3 Secret Key |
PROXY_FETCH_ENABLED |
선택 | false |
봇차단 출처의 프록시 2차 관측. soft 신호 전용 — 임계값·자동 승격 영향 없음. 출처 URL이 프록시 사업자에 전달됨(옵트인) |
PROXY_FETCH_BASE / PROXY_FETCH_API_KEY |
선택 | Jina Reader / - | 렌더링 프록시 교체·인증(키 없이도 동작, 낮은 레이트리밋) |
VALUE_W_* |
선택 | value.py 참고 |
가치 스코어러 가중치(캡처/승격 우선순위 전용, 박제 결정 미주입). 적용값은 /api/transparency로 공개 |
VERIFY_CACHE_TTL |
선택 | 600 |
/api/verify 결과 캐시(초) — 게이트웨이 GET 남용 방지 |
NATIVE_TEXT_ENABLED |
선택 | true |
tracker 텍스트 파이프라인 Rust 가속(native/의 hc_native, Docker 빌드 포함). 실측 8배 + GIL 해제. 미설치·비호환 시 동작 동일한 파이썬 자동 폴백 |
가장 간단하게 시스템을 실행하는 방법입니다. FastAPI 백엔드, Node.js 업로더, DB(Supabase 또는 내장 로컬 DB — 기본 Rust 엔진)가 유기적으로 연결됩니다. Supabase 를 쓰지 않을 거라면 2번(스키마 실행) 단계를 건너뛰고 1-b를 따르세요.
# 1. 환경변수 파일 생성 및 작성
cp .env.example .env
# 2. Supabase SQL Editor 에서 아래 스키마 스크립트들을 순서대로 실행 (멱등성 보장)
# - supabase_schema.sql
# - supabase_migration_2026-06.sql (원자적 cleanup RPC 등 2026-06 갱신)
# - migrations/006_captured_posts_and_adaptive.sql (선제 수집/적응형 추적)
# - migrations/007_wayback_snapshots.sql (선택: Wayback 위임)
# - migrations/008_poetic_reason_and_volatility.sql (박제 사유/휘발성 점수)
# - migrations/009_capture_promotion_bridge.sql (★ 캡처→공개 승격: Promoter)
# - migrations/010_cleanup_preserve_captures.sql (미박제 글 정리 시 캡처 승격글 보존)
# - migrations/011_value_score.sql (아카이브 가치 점수 저장 — 승격 우선순위)
# - migrations/012_story_value_score.sql (선택: 승격 글에 아카이브 가치 점수 승계·표시)
# - migrations/013_discovery_queue.sql (영속 발견 큐·원문 보존물 참조)
# 3. Docker 컨테이너 빌드 및 실행
docker compose up -d
# 4. 로그 확인
docker compose logs -f appSupabase 프로젝트가 없어도 전체 기능이 동작합니다. .env 에서 SUPABASE_URL /
SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY 를 비워두면:
- DB:
services/localdb.py가 로컬 파일(./data/heartcritique.db,LOCAL_DB_PATH로 변경 가능)에 동일한 스키마(전체 마이그레이션 적용 상태)를 자동 생성합니다. Supabase SQL Editor 단계가 필요 없습니다. 저장 엔진은 기본이 pyturso(Turso Database) — SQLite 를 Rust 로 재작성한 인프로세스 DB 로, SQLite 파일 포맷과 완전 호환이라 기존 SQLite 파일도 변환 없이 그대로 씁니다 (미설치 시 stdlibsqlite3자동 폴백,LOCAL_DB_ENGINE으로 강제 선택 가능). 참고: turso 엔진은 DB 파일을 프로세스 단위로 독점 잠금하므로 앱 가동 중에는 다른 프로세스가 같은 파일을 열 수 없습니다 — 가동 중 점검은 파일 사본을 떠서 하세요(사본은 stdlib sqlite3 로도 열림). - 인증: Google OAuth 대신 게스트 인증이 켜집니다. 브라우저가
POST /api/auth/guest로 HMAC 서명 토큰을 받아 투표합니다(UI 우측 상단에 '게스트' 배지 표시). 게스트 신원은 브라우저 단위라 OAuth 만큼 중복투표에 강하지 않습니다. - 백그라운드 루프(tracker/hunter/cleanup 등)와 박제(Irys)·검증(/api/verify)은 그대로 동작합니다.
cp .env.example .env # SUPABASE_* 는 비워둔 채 LLM 키 등만 채우기
docker compose up -d # ./data 볼륨에 DB 파일 영속기존 Supabase 배포에서 갈아타기 — 데이터 전체(스토리·투표·수집글·Wayback 큐)를
로컬 DB 로 이전한 뒤 DB_BACKEND=local 로 전환합니다(원본 Supabase 는 읽기만 하므로 무변경):
docker compose build app # 마이그레이션 스크립트가 든 최신 이미지 먼저 빌드
docker compose stop app # 이전 중 델타 쓰기 방지
docker compose run --rm --no-deps app python scripts/migrate_supabase_to_local.py
echo 'DB_BACKEND=local' >> .env # SUPABASE_* 는 남겨둬도 됨(local 이 우선)
docker compose up -d app알아둘 것: ① 스크립트 재실행(델타 흡수)은 원본의 추가/수정만 반영하고 삭제는 미러링하지 않으므로(유령 행 잔존 가능) 앱을 멈춘 상태의 1회 실행이 정석입니다. ② 이전된 투표의 user_id 는 기존 Google OAuth 신원 그대로라, 게스트 인증 전환 후 같은 사람이 새 게스트 신원으로 다시 투표하는 것까지 막지는 못합니다.
이미 Supabase 를 쓰던 배포는 전환 전까지 아무 변화 없습니다(환경변수가 있으면 기존 경로 그대로).
백엔드 파이썬 서버나 Node uploader를 개별적으로 수정하며 개발할 때 유용합니다.
파이썬 백엔드 실행:
pip install -r requirements.txt
uvicorn main:app --reload --port 8000Irys 업로더 단독 실행:
cd uploader
npm install
node index.js- 단일 프로세스 실행 권장: 백그라운드 스케줄러(Hunter, Tracker, Archive Sweeper) 및 인메모리 캐시/레이트리밋 구조로 인해
--workers 1로 실행되어야 합니다. 수평 확장이 필요할 경우 백그라운드 루프를 독립된 컨테이너로 분리하십시오. - 디재스터 복구 및 DB 초기화:
supabase_schema.sql은 멱등하게 설계되어 재실행해도 기존 데이터를 덮어쓰지 않습니다. DB를 완전히 초기화하려면 supabase_reset.sql을 실행하십시오. (🚨 주의: 데이터 영구 삭제) 로컬(SQLite) 모드의 초기화는 컨테이너 중지 후./data/heartcritique.db(및 WAL 파일)를 삭제하면 됩니다 —data/guest_secret까지 지우면 기존 게스트 토큰도 무효화됩니다. - API 레이트리밋: 무인증 API 호출로 인한 LLM 비용 폭탄을 방지하기 위해
/api/story및 A2A/message/send엔드포인트에는 IP당/전역 레이트리밋(STORY_RATELIMIT_*)이 적용되어 있습니다.
로컬에서 단위 테스트를 수행하여 로직(서명 검증, 임계값 계산, Wayback 백오프, 로컬 DB 계약, Rust 패리티 등)의 안정성을 검증할 수 있습니다.
pip install -r requirements-dev.txt
pytestpytest.ini는 단위 테스트 경로를 tests/로 제한하여 운영 data/와 로컬 연구 파일을 탐색하지 않습니다.
tests/test_localdb.py— SQLite 로컬 백엔드의 supabase-py 호환 계약(에러코드·필터·정렬·RPC) 고정tests/test_nativetext.py— Rust 텍스트 파이프라인과 파이썬 폴백의 결과 완전 일치(픽스처+퍼즈 200케이스). 로컬에hc_native가 없으면 Rust 쪽 패리티는 자동 건너뛰므로, 완전 검증은 휠이 설치된 Docker 이미지 안에서 실행합니다:docker compose build app docker run --rm -v ./tests:/app/tests:ro heartcritiqueeas-app \ sh -c "pip install -q pytest && python -m pytest -q tests/test_nativetext.py"
- 스토리 생성 (레이트리밋 적용)
curl -X POST http://localhost:8000/api/story
- 스토리 목록 조회 (
q로 본문·시적 사유 부분일치 검색,limit으로 개수 조절)curl http://localhost:8000/api/stories curl "http://localhost:8000/api/stories?q=택시&limit=200" # 키워드 검색(전체 아카이브 대상)
- 대시보드 통계 집계
curl http://localhost:8000/api/stats
- 게스트 신원 발급 + 투표 (로컬 모드 전용 — Supabase 모드에선 404)
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/guest | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])") curl -X POST http://localhost:8000/api/vote/<story_id> -H "Authorization: Bearer $TOKEN"
- 투명성 스냅샷 / 박제 검증 / 글 공유 링크
curl http://localhost:8000/api/transparency # 지금 적용 중인 정책·가중치·게이트 curl http://localhost:8000/api/verify/<story_id> # 서명 검증 + DB 본문 대조 (/api/recheck 와 per-IP 레이트리밋 공유) curl -i http://localhost:8000/s/<story_id> # OG 미리보기 + SPA 리다이렉트 (5분 공용 캐시)
- 수동 승격 (어드민,
ADMIN_TOKEN설정 시) — 캡처글을 검토 후 직접 공개 박제curl -X POST "http://localhost:8000/api/admin/promote?url=<captured_url>" \ -H "X-Admin-Token: $ADMIN_TOKEN"
- A2A JSON-RPC 2.0 (하위 호환)
curl -X POST http://localhost:8000 \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"message/send","id":1,"params":{"message":{"parts":[{"text":"이야기 하나 들려줘"}]}}}'