지식 관리 시스템을 떠올릴 때 대부분의 사용자는 클라우드 기반 플랫폼인 유어나 노션 같은 서비스를 먼저 떠올린다. 이러한 서비스는 원격에서의 접근성과 협업 편의성 측면에서 매우 유용하지만, 개인적인 기록 목적과 높은 프라이버시 요구가 있는 경우, 로컬 기반 지식 저장소의 장점이 두드러진다.

결론적으로 말하자면:

• 보안성 확보: 서버 계정이나 비밀번호 관리 없이 완전히 로컬에서 운영되며, 외부 노출 위험이 없다.
• 지속 가능성: 서비스 종료나 유지 보수 중단 등의 리스크가 없으며, 특히 국내 인터넷 환경에서는 공공 클라우드의 안정성에 대한 우려가 크다.
• 자유로운 컨텐츠 생성: 제한 없는 자유로운 작성 권한으로, 특정 표현으로 인해 계정 정지되는 일도 발생하지 않는다.
• 확장성 및 커스터마이징 가능: 개발 역량이 있다면 필요한 기능을 직접 구현하거나 추가할 수 있으며, 유료 멤버십 등 추가 비용 없이 사용 가능.

반면 단점은 다음과 같다:

• 접근 범위 제한: 로컬 컴퓨터 또는 사설 서버에서만 접근 가능하며, 어디서든 열람하려면 별도 설정이 필요하다.
• 기술적 진입 장벽 존재: 초보자에게는 다소 부담스러울 수 있으나, 학습 곡선은 매우 낮다.

기존의 문서 저장 방식은 마크다운 파일(.md) 기반으로 시작되었으며, 이는 작업 로그, 일상 기록, 개인 블로그 등 다양한 용도로 활용되었다. 초기에는 VuePress 1.x를 기반으로 로컬 지식 저장소를 구축했고, 내용은 GitHub에 저장하여 버전 관리를 수행했다. 그러나 이후 Vue3 도입과 함께 생긴 호환성 문제, Node.js 업데이트로 인한 빌드 실패 등 여러 문제들이 누적되면서 점차 관리 부담이 커졌다. 특히 최근에는 Tailwind CSS와의 의존성 충돌로 인해 서비스 시작 자체가 불가능해지는 상황까지 발생했다.

이에 따라 기존 기술 스택을 완전히 전환하기로 결정하고, 최종적으로 Docusaurus를 선택하게 되었다. 이는 기존의 Vue 기반 솔루션보다 더 나은 성능, 모던한 아키텍처, 그리고 확장 가능한 플러그인 시스템을 제공하기 때문이다.

1. Docusaurus 프로젝트 생성

npx create-docusaurus@latest my-knowledge-base classic --typescript

npx 대신 yarn, pnpm, ni 등 다양한 패키지 매니저를 사용할 수 있으며, 결과는 동일하다. 설치 후 필수 플러그인을 추가한다:

pnpm add @docusaurus/plugin-ideal-image @easyops-cn/docusaurus-search-local docusaurus-plugin-image-zoom

각 플러그인의 기능은 공식 문서나 GitHub README에서 확인할 수 있다.

2. 사이드바 구성 및 자동화

기존에 VuePress에서는 폴더 트리 구조를 동적으로 생성하기 위해 별도의 Node.js 스크립트를 작성해야 했지만, Docusaurus는 내장된 자동 사이드바 생성 기능을 제공한다. sidebars.ts 파일에서 다음과 같이 설정하면, 해당 디렉토리 하위의 모든 문서가 자동으로 메뉴에 포함된다.

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  documentation: [
    { type: 'autogenerated', dirName: 'docs' },
  ],
  tutorials: [
    { type: 'autogenerated', dirName: 'tutorials' },
  ],
  reference: [
    { type: 'autogenerated', dirName: 'reference' },
  ],
};

export default sidebars;

여기서 docs, tutorials, reference는 실제 docs/ 폴더 내의 하위 폴더 이름과 일치해야 한다.

3. 실행 및 운영 최적화

지속적으로 명령어 창을 열어두는 것은 불편하므로, 다음 두 가지 방법으로 운영 효율성을 높일 수 있다.

• 백그라운드 실행: pm2를 사용해 서비스를 백그라운드로 관리한다.

{
  "name": "knowledge-wiki",
  "script": "pnpm run build && pnpm run serve",
  "cwd": "./my-knowledge-base"
}

주의: run serve는 빌드 후 서버를 시작하는 명령어이며, SSR(서버사이드 렌더링)를 수행한다. 하지만 변경 사항 반영이 즉시 적용되지 않으므로, 개발 중에는 pnpm run start를 사용하는 것이 적절하다.

• 역방향 프록시 설정: 로컬에서 nginx를 이용해 사용자 정의 도메인을 통해 접근 가능하게 할 수 있다. 예: http://wiki.local → localhost:3000

Git 연동 및 백업 전략

최소한의 데이터 손실을 막기 위해 반드시 개인용 프라이빗 리포지토리를 생성하고, 로컬 지식 저장소 전체를 관리해야 한다. 이를 통해 다음과 같은 이점을 얻을 수 있다:

• 데이터 손실 방지 (예: 하드웨어 고장)
• 커밋 기록을 통한 창작 히스토리 추적
• 팀 내 공유 및 협업 가능 (기업 내부에서도 활용 가능)

이러한 방식은 단순한 저장소를 넘어, 지식의 지속적 관리와 생산성 향상을 위한 실질적인 솔루션이다.