왕밤빵 위키

GitHub Pages(정적 사이트) + Supabase(DB)로 동작하는 나무위키 스타일 위키입니다. 회원가입 없이 누구나 문서를 읽고 사이트 안에서 바로 편집할 수 있습니다.

기능

• 문서 보기 / 편집 / 새 문서 만들기

• 글쓰기 화면 같은 편집기: 마크다운 기호 없이 적용된 모습 그대로 보면서 편집(WYSIWYG)

  • 툴바: 문단 모양(본문/제목 1~3), 굵게·기울임·취소선·코드, 목록, 인용, 링크, 각주, 이미지, 표·구분선·코드 블록(삽입 메뉴)
  • 링크 창에서 위키 문서를 검색해 연결하거나 웹 주소를 넣을 수 있고, 없는 문서는 빨간 링크로 표시
  • 각주는 번호가 붙은 표시를 눌러 내용을 고치고, 표는 편집 중 행·열을 추가/삭제
  • 분류는 태그(칩)로 따로 입력하고, 넘겨주기는 "고급 설정"에서 지정 (문서 머리말 --- 은 화면에 보이지 않음)
  • 필요하면 마크다운 버튼으로 문법을 직접 편집하는 모드로 전환
  • 저장 형식은 그대로 마크다운이라 [[문서 링크]], [* 각주] 도 그대로 유지됨

  단축키	동작	단축키	동작
  Ctrl+B	굵게	Ctrl+K	링크
  Ctrl+I	기울임	Ctrl+Shift+F	각주
  Ctrl+Shift+X	취소선	Ctrl+Alt+2/3/4	제목 1/2/3 (0 은 본문)
  Tab / Shift+Tab	목록 들여쓰기·내어쓰기, 표에서는 다음·이전 칸

  Mac에서는 Ctrl 대신 Cmd.

• 이미지 올리기 (Supabase Storage): 툴바 이미지 버튼에서 사진을 고르거나, 편집창에 끌어다 놓기·붙여넣기(캡처 포함). PNG/JPG/GIF/WEBP 5MB 이하, 긴 변이 1600px 을 넘으면 자동으로 줄여서 올림. 프로필 상자에도 사진 올리기 버튼이 있음

• 친구 전용(초대 링크 + 기기 등록): 켜면 초대받아 등록된 기기만 문서를 읽고 쓰고 사진을 올릴 수 있음. 1회용 초대 링크를 처음 연 기기가 서버에 등록되어 이후 계속 입장하고, 사람별로 막을 수 있음. 서버(DB)가 확인하므로 사이트 주소만 알아서는 읽을 수 없음. 켜기 전에는 누구나 쓸 수 있음

• 사진 접기·크게 보기: 문서 속 사진은 높이 480px까지만 보이고, 누르면 전체 화면으로 크게 봄(원본 열기 링크 포함). 사진 하나하나를 접어서 보기로 설정하면 🖼 설명 ▸ 펼치기 한 줄로 줄어 문서가 길어지지 않음. 편집기에서 사진을 누르면 설명 수정·접기 설정·삭제를 할 수 있고, 이미지 창에도 "접어서 보여주기" 체크가 있음. 저장 형식은 ![설명](주소 "fold")

• 앱으로 설치(PWA): 홈 화면에 추가해 주소창 없이 앱처럼 실행. 한 번 열어 본 문서는 인터넷이 없어도 읽을 수 있음 (편집·검색·사진 올리기는 연결 필요)

• 프로필 상자(인포박스): 인물·작품·단체 문서 오른쪽 위에 사진과 정보 표를 보여 줌. 편집기의 삽입 → 프로필 상자에서 양식(인물/작품/단체)을 골라 만들고, 만든 상자를 눌러 고칠 수 있음. 본문에는 :::infobox ... ::: 블록으로 저장되어 검색·역링크·편집 기록이 그대로 동작

• 편집 기록(역사), 판 보기, 두 판 비교(diff), 이전 판으로 되돌리기

• 편집 충돌 감지 (내가 편집하는 사이 다른 사람이 저장하면 알려 줌)

• 편집자 닉네임 + IP 일부(예: 1.2.*.*) 기록

• [[문서 링크]], [[문서#섹션|표시 글자]], 빨간 링크(없는 문서), [* 각주], 자동 번호 목차

• 분류(categories:), 넘겨주기(redirect:), 역링크, 최근 변경, 전체 문서, 랜덤

• 제목 자동완성 + 본문 검색, 다크 모드, 모바일 대응

구조

• index.html, assets/ — 정적 프론트엔드 (빌드 불필요). 편집기는 assets/editor.js
• assets/config.js — 사이트 이름, Supabase URL, 공개용(publishable) 키
• supabase/migrations/ — DB 스키마 (적용 완료)
• supabase/seed.sql — 초기 예시 문서

보안 모델

공개용 키는 브라우저에 노출됩니다. 그래서 DB 쪽에서 권한을 제한했습니다.

• 테이블은 읽기 전용(RLS). 쓰기는 edit_page() 함수로만 가능합니다.
• edit_page() 가 제목·길이 검증, 충돌 검사, IP당 분당 15회 제한, 차단 목록 확인을 합니다.
• IP는 서버가 직접 읽고(클라이언트가 속일 수 없음), 원본은 저장하지 않습니다. 가린 값(1.2.*.*)과 솔트 해시만 저장하며 해시는 API로 읽을 수 없습니다.
• 본문은 DOMPurify로 정화해서 렌더링합니다.

앱 설치 (PWA)

• 안드로이드(크롬): 메뉴 → 홈 화면에 추가 / 앱 설치. 사이트 하단의 "앱으로 설치" 링크가 보이면 그것을 눌러도 됩니다.
• 아이폰(사파리): 공유 버튼 → 홈 화면에 추가.
• PC(크롬·엣지): 주소창 오른쪽의 설치 아이콘.

동작 방식 (sw.js):

• 앱 껍데기(index.html, assets/*, 아이콘): 기기에 저장해 빠르게 엶. index.html 은 인터넷 우선이라 배포하면 바로 새 버전이 열림. assets/* 는 저장본을 먼저 보여 주고 뒤에서 갱신.
• 문서 데이터(Supabase GET): 인터넷 우선, 안 될 때만 저장본(최근 80건)을 읽기 전용으로 보여 주며 "오프라인" 안내 띠를 띄움.
• 저장·검색·사진 올리기·이미지 파일은 서비스 워커가 건드리지 않음.
• 새 버전이 배포되면 "새 버전이 있어요 — 새로고침" 알림이 뜸.

관리할 때:

• index.html 의 ?v=숫자 는 assets/* 를 바꿀 때마다 올려 주세요 (바로 새 파일을 받게 하는 용도).
• sw.js 의 동작을 바꾸면 VERSION 도 올려 주세요.
• 아이콘은 assets/icons/ 의 PNG(192, 512, maskable 512, 애플 180)를 같은 이름으로 바꾸면 됩니다. 이름·색은 manifest.webmanifest.

친구 전용 (공유 코드 + 선택적 기기 초대)

기본 사용법(공유 코드): 친구들이 같이 쓰는 코드 하나를 정해 단톡방에 올립니다. 친구는 입장 화면에 코드를 넣거나 https://<사용자>.github.io/<저장소>/#/join/<코드> 링크를 열면 되고, 한 번 들어온 기기는 계속 들어옵니다 (기기마다 한 번).

select private.set_access_code('kq7m-x3vn-p9tb');   -- 코드 정하기 / 바꾸기 (켜기도 함께, 8자 이상 · 12자 이상 무작위 권장)
select private.clear_access_code();                 -- 공유 코드 끄기 (등록된 기기는 그대로)
select private.gate_off();                          -- 친구 전용 끄기 (다시 누구나 사용)

코드는 대소문자·공백·하이픈을 무시하고 해시로만 저장됩니다. 코드를 바꾸면 모두 새 코드를 다시 입력해야 합니다. 특정 사람만 막고 싶을 때는 아래 기기 초대를 함께 쓰세요.

선택: 1회용 초대 링크 + 기기 등록

웹 사이트는 기기의 MAC 주소를 읽을 수 없습니다(브라우저가 알려 주지 않고, 폰은 MAC 을 무작위로 바꿉니다). 대신 같은 효과를 이렇게 냅니다.

1. 관리자가 친구마다 1회용 초대 링크를 만든다 (기본 7일 안에 사용).
2. 친구가 링크를 처음 연 기기에 서버가 고유한 기기 토큰을 발급하고, 기기에 저장된다. 초대 링크는 그 순간 사용 처리된다.
3. 그 기기는 이후 링크·코드 없이 계속 들어온다. 서버에는 토큰의 해시만 저장된다.
4. 사람(기기)별로 막을 수 있다. 폰·PC 가 둘 다 필요하면 초대 링크를 각각 만든다.

동작 방식: 브라우저가 모든 요청에 x-wiki-code 헤더로 기기 토큰(또는 공유 코드)을 실어 보내고, DB가 확인합니다 (private.has_access()). 허가가 없으면 문서·역사는 빈 목록으로 보이고, 저장과 사진 올리기는 거절됩니다.

Supabase SQL Editor에서 실행:

select private.gate_on();                       -- 친구 전용 켜기 (등록된 기기만 입장)
select private.create_invite('명성아');           -- 1회용 초대 토큰 만들기 (이때 한 번만 보임, 7일)
select private.create_invite('홍우택', 14);       -- 유효기간 14일
-- 초대 링크: https://windowhyun.github.io/WangbamBBangwiki/#/join/<위에서 나온 토큰>

select id, name, created_at, last_seen, revoked_at, user_agent, ip_label from private.devices order by id;  -- 등록된 기기
select name, created_at, expires_at, used_at from private.invites order by id;                            -- 초대 현황
select private.revoke_device(3);                -- 기기 막기 (devices.id)
select private.gate_off();                      -- 모두에게 다시 열기 (공유 코드도 함께 지움)

• 공유 코드(선택): select private.set_access_code('kq7m-x3vn-p9tb'); 로 모두가 같이 쓰는 코드를 둘 수도 있습니다 (입장 화면에 직접 입력, 8자 이상·12자 이상 무작위 권장). 등록된 기기는 공유 코드와 상관없이 들어옵니다. select private.clear_access_code(); 로 공유 코드만 끄면 등록된 기기만 남습니다.
• 푸터 이 기기 로그아웃: 그 기기의 등록(저장된 토큰)과 오프라인용 문서 저장본을 지웁니다. 다시 들어오려면 새 초대 링크가 필요합니다. 공용 기기에서 쓰고 나면 눌러 주세요.
• 한계: iOS 사파리는 앱처럼 설치하지 않고 한동안(약 7일) 안 열면 저장된 토큰을 지울 수 있습니다. 친구들에게 홈 화면에 추가(PWA)를 권하세요. 브라우저 데이터를 지우거나 다른 브라우저로 열면 새 초대 링크가 필요합니다.
• 한계: 토큰은 비밀번호처럼 취급해야 합니다. 기기 토큰을 복사해 간 사람은 그 기기처럼 들어올 수 있으므로, 의심되면 revoke_device 로 막으세요.
• 한계: 사진 파일은 공개 버킷이라 사진 주소(추측하기 어려운 무작위 이름)를 아는 사람은 볼 수 있습니다. 켜기 전에 공개되어 있던 문서와 키는 이미 읽혔을 수 있습니다.
• 켜기 전(기본)에는 지금처럼 누구나 읽고 쓸 수 있습니다.

운영 (Supabase SQL Editor에서 실행)

이미지 올리기 제한: IP당 분당 8장 / 하루 100장, 전체 하루 1000장 (private.allow_image_upload() 의 숫자를 고치면 조정). 올린 사람은 서버 기록(private.upload_log)에 IP 해시와 파일 이름으로 남음.

문제 이미지를 올린 사람 차단 (파일 이름으로 IP 해시를 찾아 차단 — 문서 편집과 이미지 업로드가 함께 막힘):

insert into private.blocked_ips (ip_hash, reason)
select ip_hash, '이미지 장난' from private.upload_log where object_name = '2026/10/파일이름.png'
on conflict do nothing;

이미지 파일 삭제는 Supabase 대시보드 Storage → wiki-images 에서 합니다. (문서에서 쓰이지 않는 이미지도 자동으로 지워지지는 않음)

문서 보호 / 보호 해제:

update public.pages set protected = true where title = '대문';

장난 편집 되돌린 뒤 작성자 차단 (revisions 의 id 로 IP 해시를 찾아 차단):

insert into private.blocked_ips (ip_hash, reason)
select ip_hash, '장난 편집' from public.revisions where id = 123
on conflict do nothing;

문서 삭제 (역사도 함께 삭제됨):

delete from public.pages where title = '지울 문서';

Supabase 일시정지 방지 (GitHub Actions)

Supabase 무료 플랜은 일정 기간 요청이 없으면 프로젝트를 자동으로 일시정지하고, 그동안 사이트는 "오프라인"으로 보입니다. .github/workflows/keep-supabase-alive.yml 이 매일 한 번 DB 함수(check_access)를 호출해 정지를 막습니다.

• 주소와 공개용 키는 assets/config.js 에서 읽으므로 Secrets 등 따로 설정할 것이 없습니다. Supabase 프로젝트를 옮기면 config.js 만 바꾸면 됩니다.
• 저장소 Actions 탭에서 Keep Supabase alive → Run workflow 로 바로 실행해 볼 수 있습니다. 응답이 없으면 실패(빨간색)로 표시됩니다.
• GitHub 는 저장소에 60일 동안 활동이 없으면 예약 실행을 멈춥니다. 멈추면 Actions 탭에서 다시 켜 주세요.
• 이미 일시정지된 프로젝트는 이 방법으로 깨워지지 않습니다. 대시보드에서 Restore project 를 눌러야 합니다.

새 Supabase 프로젝트로 옮길 때

1. 프로젝트를 만들고 supabase/migrations/ 를 파일 이름 순서대로 적용합니다 (SQL Editor 또는 supabase db push).
2. (선택) supabase/seed.sql 로 예시 문서를 넣습니다.
3. assets/config.js 의 supabaseUrl, supabaseKey 를 새 프로젝트 값으로 바꾸고, index.html 의 ?v=숫자 를 올립니다.
4. 접속 코드·초대 링크·등록된 기기는 DB 안에 있어서 옮겨지지 않습니다. 새로 만들어야 합니다.

배포

GitHub Pages

1. 이 브랜치를 main 에 병합합니다.
2. 저장소 Settings → Pages: Source Deploy from a branch, Branch main / / (root).
3. https://<사용자>.github.io/<저장소>/ 에서 확인합니다.

Vercel

빌드가 없는 정적 사이트라 그대로 올라갑니다 (모든 경로가 상대 경로라 주소가 / 든 /저장소/ 든 동작).

1. vercel.com → Add New → Project → 이 GitHub 저장소를 가져옵니다.
2. Framework Preset: Other, Build Command·Output Directory 는 비워 둡니다 (루트 그대로 배포). vercel.json / .vercelignore 가 헤더와 제외 파일(supabase/)을 정해 줍니다.
3. Deploy → https://<프로젝트>.vercel.app 에서 확인합니다. 이후 main 에 푸시하면 자동 배포됩니다.

Supabase 쪽은 따로 설정할 것이 없습니다 (로그인을 쓰지 않아 허용 주소 설정이 필요 없고, API 는 어느 주소에서든 호출됩니다). 주소가 바뀌어도 친구 전용 접속 정보(코드·등록 기기)는 브라우저 저장소에 있어서 주소(도메인)마다 따로입니다. 새 주소에서는 다시 한 번 코드를 입력해야 합니다. GitHub Pages 와 Vercel 을 동시에 켜 두어도 같은 DB 를 보므로 문서는 똑같이 보입니다. 하나만 쓰려면 다른 쪽을 끄세요.

로컬 확인: python3 -m http.server 8000 후 http://localhost:8000