project-surf: 위키백과 서핑

이 프로젝트는 claude code와 openai codex를 이용하여 제작된 코드입니다. 보안 취약점이나 심각한 버그가 존재할 수 있으므로, 사용 시 주의하시기 바랍니다.

위키백과 문서 두 개를 입력하면, 링크만 타고 이동하는 최단 경로를 찾아 각 구간이 실제로 어느 문장에서 쓰였는지 보여주는 서비스.

빠른 시작 (Docker)

cp config/config.example.toml config/config.toml
# config/config.toml 을 열어 [contact] 섹션에 이메일을 채워주세요 (권장 사항)

docker compose build
docker compose --profile pipeline run --rm pipeline build   # 한국어 덤프 다운로드 + 스냅샷 빌드 (약 2.3GB, 20분 소요)
docker compose up server                                     # http://localhost:8081

빠른 기능 확인만 하려면 config/config.toml의 wiki.lang을 simple로 바꾼 뒤 파이프라인을 다시 실행하세요.

로컬 개발 (Docker 없이)

Go 1.24+, Node 20+ 필요.

cp config/config.example.toml config/config.toml
# config/config.toml 에 이메일 채우기

go run ./cmd/surf-pipeline build      # 덤프 다운로드 + 스냅샷 빌드
go run ./cmd/surf-pipeline info       # 빌드 결과 확인

go run ./cmd/surf-server              # :8081 — API + (빌드했다면) 프론트엔드

cd web && npm install && npm run dev  # :5173 — 개발 서버, /api 는 :8081 으로 프록시

아키텍처

cmd/surf-pipeline   덤프 다운로드 → 그래프/텍스트/색인 빌드 (build / info)
cmd/surf-server     API 서버 + 빌드된 프론트엔드 서빙 (go:embed)
internal/           파이프라인·그래프·API 각 단계 구현체
web/                Vite + React + TypeScript 프론트엔드

빌드 산출물(스냅샷)은 data/snapshots/<wiki>-<날짜>/ 아래 바이너리 파일들로 저장됩니다.

설정 (`config/config.toml`)

config/config.example.toml을 복사해서 씁니다.

모든 키는 SURF_<SECTION>_<KEY> 환경변수로 덮어쓸 수 있습니다. 예: SURF_WIKI_LANG=ko, SURF_CONTACT_EMAIL=me@example.com.

섹션	키	설명
`[wiki]`	`lang`	대상 위키 코드: `ko`(기본) \| `simple`(개발·테스트용) \| `en`
	`snapshot`	사용할 덤프 날짜(`YYYYMMDD`) 또는 `latest`
`[contact]`	`app_name`, `email`, `url`	덤프 다운로드 User-Agent용 연락처 (위키미디어 정책)
`[paths]`	`dump_dir`, `snapshot_dir`	덤프/스냅샷 저장 위치
`[pipeline]`	`workers`	파이프라인 워커 수, `0` = CPU 코어 수
	`links`	`prose`(본문 링크만, 기본) \| `all` \| `both` — `all`/`both`는 아직 미구현
	`keep_dumps`	빌드 후 원본 덤프 보관 여부
	`text_max_bytes`	일반 문서 저장 기준. 그래프에 남긴 링크의 문맥은 이 값 뒤라도 보존
	`zstd_level`	본문 압축 레벨 (1~19)
`[server]`	`addr`	리스닝 주소, 기본 `:8081`
	`cors_origins`	허용할 Origin 목록
	`max_paths`	`/api/v1/path` 응답에 담을 최대 경로 개수

API

엔드포인트	설명
`GET /api/v1/meta`	스냅샷 정보 (위키, 날짜, 노드/간선 수)
`GET /api/v1/suggest?q=&limit=`	제목 자동완성 (접두사 + 초성 검색, 차수순 정렬)
`GET /api/v1/path?from=&to=&limit=`	최단 경로(들) — `from`/`to`는 제목 또는 dense id
`GET /api/v1/snippet?from=<id>&to=<id>`	두 문서 사이 간선의 실제 문맥 스니펫
`GET /api/v1/random-pair`	도달 가능한 임의의 두 문서

기여와 라이선스

이슈와 개선 제안, 풀 리퀘스트를 환영합니다. 변경 전에는 go test ./...와 cd web && npm run build를 실행해 주세요.

소스 코드는 MIT License로 배포합니다. 위키백과 콘텐츠와 덤프에서 파생된 데이터에는 코드 라이선스가 적용되지 않으며, CC BY-SA 4.0 및 위키미디어의 이용 조건을 따릅니다. 공개 배포 시에는 해당 출처·저작자 표시 및 동일조건변경허락 의무를 반드시 지켜야 합니다.