LeafWiki, 마크다운 파일로 남기는 가벼운 셀프 호스팅 위키

LeafWiki, 마크다운 파일로 남기는 가벼운 셀프 호스팅 위키

LeafWiki 셀프 호스팅 위키 썸네일

팀 문서를 직접 운영하고 싶어도 데이터베이스와 여러 서비스를 함께 관리해야 하면 일이 커져요. LeafWiki는 페이지를 일반 마크다운 파일로 저장하고, 단일 Go 바이너리로 실행해 이런 운영 부담을 줄인 셀프 호스팅 위키예요. 런북, 홈랩 기록, 튜토리얼처럼 폴더 구조가 중요한 문서에 초점을 맞췄어요. 1

핵심 요약

구분	핵심	왜 볼 만한가요
저장 방식	본문을 디스크의 `.md` 파일로 저장해요	앱이 없어도 파일을 읽고 검색하거나 다른 도구로 옮길 수 있어요
운영 방식	외부 데이터베이스 서버 없이 단일 Go 바이너리로 실행해요	작은 팀과 홈랩에서 관리할 구성 요소가 줄어요
편집 경험	라이브 프리뷰, 자동 저장, 이미지 붙여넣기, 위키링크 자동완성을 지원해요	가벼운 구조를 유지하면서 일상적인 문서 편집 기능을 챙겼어요
활용 범위	사설 위키, 공개 문서 사이트, 로컬 노트패드 모드를 제공해요	같은 도구를 개인 기록과 소규모 팀 문서에 맞춰 쓸 수 있어요

1. 문서는 파일로, 위키 기능은 가볍게 관리해요

LeafWiki는 페이지 본문을 폴더 안의 `.md` 파일로 보관해요. 전용 내보내기 기능을 거치지 않아도 일반 편집기로 열 수 있고, `grep`으로 내용을 찾을 수도 있어요. 디렉터리를 복사하는 방식으로 백업할 수 있어 복구 절차도 단순해요. 링크, 태그, 검색 인덱스 같은 메타데이터는 파일 옆의 경량 SQLite에 따로 저장해요. 따라서 “데이터베이스가 전혀 없다”기보다 별도의 데이터베이스 서버를 운영하지 않아도 된다는 설명이 정확해요. 2

폴더 트리가 문서 구조가 돼요

페이지 목록을 평면 피드로 보여 주지 않고 디렉터리 트리로 유지해요. 서버 설정 아래에 네트워크, 배포, 장애 대응 문서를 두는 식으로 실제 운영 구조를 그대로 옮기기 쉬워요. 전체 텍스트 검색과 태그 필터를 함께 쓸 수 있고, 빠른 이동 단축키도 제공해요.

728x90

페이지 이름을 바꾸거나 위치를 옮길 때 기존 링크를 자동으로 고치는 기능도 있어요. 백링크를 추적해 깨진 링크를 페이지별로 표시하며, 저장할 때마다 리비전을 남겨 이전 버전으로 되돌릴 수 있어요. 링크 자동 수정과 리비전 기록은 각각 실행 옵션으로 켜는 방식이에요. 3

편집 화면은 마크다운 원문과 결과를 함께 보여 줘요

내장 편집기는 마크다운 원문과 렌더링 결과를 나란히 보여 줘요. 자동 저장을 지원하고, 클립보드의 이미지를 붙여 넣으면 파일 업로드와 링크 삽입을 처리해요. `[[wikilink]]` 문법과 자동완성을 지원해 Obsidian에서 쓰던 연결 방식을 이어가기 좋아요.

표, 작업 목록, 각주, 콜아웃뿐 아니라 Mermaid 다이어그램과 KaTeX 수식도 렌더링해요. 별도 플러그인을 조합하지 않아도 기술 문서에서 자주 쓰는 표현을 한곳에서 다룰 수 있어요.

설치는 가볍지만 권한과 보안 범위는 확인해야 해요

리눅스, macOS, 윈도우, 라즈베리 파이용 바이너리를 제공하며 Docker로도 실행할 수 있어요. 운영 모드는 로그인 기반 사설 위키, 읽기는 공개하고 편집만 제한하는 문서 사이트, 인증을 끈 로컬 노트패드로 나뉘어요. 관리자, 편집자, 열람자 역할을 구분하고 CSRF 보호와 인증 요청 제한도 기본으로 제공해요. Authentik, Authelia, Keycloak 같은 기존 인증 시스템과는 신뢰 HTTP 헤더로 연결할 수 있어요. 2

다만 실시간 공동 편집, 승인 절차, 복잡한 자동화가 필요한 조직을 겨냥한 제품은 아니에요. 여러 부서의 세밀한 권한 체계나 올인원 협업 공간이 필요하면 별도 도구가 더 잘 맞을 수 있어요. LeafWiki는 개인과 소규모 팀이 오래 보관할 문서를 적은 구성 요소로 운영하는 데 무게를 둬요.

왜 중요한가요

셀프 호스팅 문서 도구를 고를 때 화면 기능만큼 중요한 것이 데이터의 형태예요. 본문이 일반 파일로 남으면 서비스가 멈춰도 내용을 읽을 수 있고, Git이나 파일 백업 도구를 기존 방식대로 붙이기 쉬워요. 다른 문서 시스템으로 옮길 때도 전용 포맷을 해제하는 작업이 줄어요. 3

LeafWiki의 선택은 운영 범위도 분명해요. 외부 PostgreSQL, Redis, Node.js 런타임을 따로 두지 않고 바이너리와 데이터 폴더를 관리하면 돼요. 문서 수와 사용자가 많지 않은 홈랩이나 작은 개발팀이라면 업데이트, 백업, 장애 복구 때 확인할 지점이 줄어들어요.

도입 전에는 협업 요구를 먼저 확인하는 편이 좋아요. 여러 사람이 같은 페이지를 동시에 편집하거나 결재 단계와 기업용 권한 정책이 필요하면 기능이 부족할 수 있어요. 반대로 폴더 중심의 기술 문서, 이동 가능한 마크다운 원본, 간단한 복구 절차가 우선이라면 직접 시험해 볼 만해요.

참고 자료

1. LeafWiki, 서버와 DB 없이 단일 바이너리로 실행하는 셀프 호스팅 위키 — GeekNews
2. LeafWiki 공식 사이트 — LeafWiki
3. perber/leafwiki — GitHub