프로젝트: Wiki.js Knowledge Base
원본 상대경로:README.md
형식:MD
분류:Readme Md
추출 방식:text
동기화:2026-06-29 09:50:49
README.md여러 에이전트와 여러 작업 환경에서 함께 쓰기 위한 Wiki.js 기반 지식 저장소입니다. 웹 UI는 Wiki.js가 담당하고, 장기 보존 및 에이전트 활용은 Markdown/Git 저장소를 기준으로 운영하는 구성을 권장합니다.
docker-compose.yml: Wiki.js 2 + PostgreSQL 15.env.example: 배포 환경 변수 예시.env.synology.example: Synology NAS 배포 환경 변수 예시deploy/: Synology Compose override와 배포 스크립트.github/workflows/: GitHub Actions 배포 템플릿docs/: 운영 및 배포 문서wiki-content/: Git 저장소로 올릴 초기 문서 구조와 템플릿scripts/: 백업 보조 스크립트환경 변수 파일을 만듭니다.
Copy-Item .env.example .env
Linux/macOS에서는:
cp .env.example .env
.env에서 POSTGRES_PASSWORD를 긴 랜덤 문자열로 바꿉니다.
컨테이너를 시작합니다.
docker compose up -d
기본 설정이면 http://localhost:8080으로 접속합니다.
첫 접속 화면에서 관리자 계정을 생성합니다.
기본값은 127.0.0.1:8080에만 바인딩합니다. 서버 외부에서 바로 접속하려면 .env에서 아래처럼 바꿉니다.
WIKI_BIND_ADDRESS=0.0.0.0
WIKI_HTTP_PORT=8080
운영 환경에서는 직접 공개보다 Caddy, Nginx Proxy Manager, Traefik 같은 리버스 프록시 뒤에 두고 HTTPS를 붙이는 방식을 권장합니다.
DS920+와 Container Manager, Nginx Proxy Manager를 쓰는 환경이라면 Synology용 override를 함께 사용합니다.
cp .env.synology.example .env
vi .env
docker compose -f docker-compose.yml -f deploy/compose.synology.yml up -d
자세한 절차는 Synology Deployment를 참고하세요.
기본 Synology 구성은 NPM에서 http://<NAS_LAN_IP>:8080으로 프록시하는 방식입니다. NPM과 같은 Docker network로 붙이고 싶다면 deploy/compose.npm-network.example.yml을 추가로 사용합니다.
GitHub Actions 템플릿은 .github/workflows/에 있습니다.
deploy-synology.yml은 self-hosted runner가 Synology의 /volume1/docker/wiki-js-knowledge-base/app 경로를 직접 볼 수 있을 때만 로컬 배포를 실행합니다.
publish-wikijs-api.yml은 Wiki.js GraphQL API로 단일 Markdown 페이지를 생성/수정하는 테스트용 workflow입니다.
publish-wikijs-tree.yml은 wiki-content/ 아래 Markdown 전체를 Wiki.js GraphQL API로 생성/수정하는 일괄 게시 workflow입니다. 기본값은 _template.md 같은 템플릿 파일까지 포함하고, 먼저 dry_run=true로 create/update 판정을 확인한 뒤 dry_run=false로 반영합니다.
API 테스트에 필요한 repository 설정:
WIKIJS_BASE_URL, 예: https://wiki.saintkite.comWIKIJS_API_TOKENGitHub CLI로 설정할 때는:
gh variable set WIKIJS_BASE_URL --body "https://wiki.saintkite.com"
gh secret [REDACTED] WIKIJS_API_TOKEN
로컬에서 먼저 테스트하려면 .env에 같은 값을 넣고 dry-run을 실행합니다.
py -3 scripts/publish_wikijs_page.py `
--file wiki-content/knowledge/glossaries/battery-ai.md `
--path knowledge/glossaries/battery-ai `
--locale ko `
--dry-run
실제 반영은 --dry-run을 빼고 실행합니다. API 방식은 Wiki.js DB에 직접 페이지를 만들거나 갱신하므로, Git의 wiki-content/가 원본이라는 운영 규칙을 유지하려면 항상 Git 변경을 먼저 커밋한 뒤 API publish를 실행합니다.
전체 트리 게시를 로컬에서 테스트하려면:
py -3 scripts/publish_wikijs_tree.py `
--root wiki-content `
--locale ko `
--include-templates `
--dry-run
Wiki.js 첫 설정이 끝나면 별도 private Git 저장소를 만들고 wiki-content/ 내용을 초기 커밋으로 올립니다.
cd wiki-content
git init
git add .
git commit -m "Initialize knowledge base"
git branch -M main
git remote add origin <your-private-repo-url>
git push -u origin main
그 다음 Wiki.js 관리 화면에서 Storage의 Git 연동을 설정합니다. 권장 운영 규칙은 다음과 같습니다.
agents/: 에이전트별 역할, 사용법, 한계, 좋은 프롬프트projects/: 프로젝트별 현재 상태, 구조, 배포, 운영 맥락decisions/: 중요한 설계 및 운영 결정 기록prompts/: 재사용 가능한 프롬프트와 작업 패턴troubleshooting/: 오류, 원인, 해결 절차runbooks/: 반복 운영 절차와 체크리스트PowerShell:
.\scripts\backup.ps1
Linux/macOS:
sh ./scripts/backup.sh
백업 파일은 backups/에 SQL dump로 생성됩니다. 복구 테스트는 별도 임시 인스턴스에서 먼저 검증한 뒤 운영 DB에 적용하세요.
PowerShell 복구:
.\scripts\restore.ps1 .\backups\wikijs-YYYYMMDD-HHMMSS.sql -Force
Linux/macOS 복구:
CONFIRM_RESTORE=YES sh ./scripts/restore.sh ./backups/wikijs-YYYYMMDD-HHMMSS.sql
업그레이드 전에는 반드시 DB 백업을 먼저 만듭니다.
docker compose pull
docker compose up -d
이 프로젝트는 Wiki.js 이미지를 ghcr.io/requarks/wiki:2로 고정합니다. latest는 예기치 않은 메이저 업그레이드를 일으킬 수 있으므로 운영에서는 피합니다.
.env의 DB 비밀번호 [REDACTED]