SiYuan Docker 설치 가이드: 양방향 링크 노트 시스템 자체 호스팅 ⋆ Blog * JackerLab

SiYuan(思源)은 프라이버시 우선, 완전 오픈소스 개인 지식 관리 시스템입니다. TypeScript와 Go로 작성되어 빠르고 안정적이며, 블록 기반 편집과 양방향 링크를 지원하여 Obsidian, Notion, Roam Research의 강력한 대안이 됩니다. 로컬 우선 설계로 오프라인에서도 완벽히 작동하며, E2E 암호화 동기화를 지원합니다. GitHub Stars 42K+로 빠르게 성장하는 프로젝트입니다.

SiYuan 주요 특징

SiYuan은 현대적인 지식 관리에 필요한 모든 기능을 제공합니다.

블록 기반 편집

블록 레퍼런스: 블록 단위로 양방향 링크 생성
블록 임베드: 다른 문서의 블록을 실시간 임베드
백링크: 현재 문서를 참조하는 모든 블록 표시
그래프 뷰: 지식 네트워크 시각화

마크다운 & WYSIWYG

실시간 마크다운 렌더링
수식 (KaTeX/MathJax)
다이어그램 (Mermaid, PlantUML)
코드 하이라이팅
테이블, 할 일 목록

고급 기능

플래시카드: 간격 반복 학습 (Spaced Repetition)
PDF 주석: PDF 문서 내 주석 및 하이라이트
SQL 쿼리: SQL로 노트 검색 및 필터링
템플릿: 커스텀 템플릿 시스템
플러그인/테마: 확장 생태계

사전 요구 사항

Docker 및 Docker Compose 설치
최소 512MB RAM
2GB 이상 저장 공간

Docker Compose로 SiYuan 설치

기본 설치

# docker-compose.yml
services:
  siyuan:
    image: b3log/siyuan:latest
    container_name: siyuan
    restart: unless-stopped
    command:
      - '--workspace=/siyuan/workspace/'
      - '--accessAuthCode=${AUTH_CODE:-your_secure_password}'
    ports:
      - "6806:6806"
    volumes:
      - ./siyuan/workspace:/siyuan/workspace
    environment:
      - TZ=Asia/Seoul
      - PUID=1000
      - PGID=1000

volumes:
  siyuan-data:

환경 변수 파일

# .env
AUTH_CODE=your_secure_access_code

설치 및 실행

# 디렉토리 생성
mkdir -p siyuan-server/siyuan/workspace
cd siyuan-server

# 권한 설정 (중요!)
chown -R 1000:1000 siyuan/

# docker-compose.yml 및 .env 파일 생성

# 컨테이너 실행
docker compose up -d

# 로그 확인
docker compose logs -f siyuan

# 브라우저에서 접속
# http://localhost:6806
# 접근 코드 입력 (AUTH_CODE 값)

접근 코드 설정

SiYuan은 접근 코드로 인증합니다:

브라우저에서 http://localhost:6806 접속
접근 인증 코드 입력 (docker-compose.yml의 --accessAuthCode 값)
입력 후 SiYuan 워크스페이스 접근

고급 설정

프로덕션 환경 (Traefik 연동)

# docker-compose.prod.yml
services:
  siyuan:
    image: b3log/siyuan:latest
    container_name: siyuan
    restart: always
    command:
      - '--workspace=/siyuan/workspace/'
      - '--accessAuthCode=${AUTH_CODE}'
    expose:
      - "6806"
    volumes:
      - ./siyuan/workspace:/siyuan/workspace
    environment:
      - TZ=Asia/Seoul
      - PUID=1000
      - PGID=1000
    networks:
      - traefik-public
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.siyuan.rule=Host(`notes.yourdomain.com`)"
      - "traefik.http.routers.siyuan.entrypoints=websecure"
      - "traefik.http.routers.siyuan.tls.certresolver=letsencrypt"
      - "traefik.http.services.siyuan.loadbalancer.server.port=6806"

networks:
  traefik-public:
    external: true

Nginx 리버스 프록시 설정

# /etc/nginx/conf.d/siyuan.conf
server {
    listen 80;
    server_name notes.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name notes.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/notes.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/notes.yourdomain.com/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:6806;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 지원 (필수!)
        proxy_read_timeout 86400;
    }
}

중요: SiYuan은 WebSocket을 사용하므로 리버스 프록시에서 WebSocket을 활성화해야 합니다.

읽기 전용 공유 포트

노트를 읽기 전용으로 공개 공유:

# docker-compose.yml
services:
  siyuan:
    ports:
      - "6806:6806"  # 편집 가능
      - "6808:6808"  # 읽기 전용 공유

데스크톱/모바일 앱 연결

주의사항

Docker로 호스팅된 SiYuan 서버는 브라우저 접근만 지원합니다:

❌ 데스크톱 앱 직접 연결 불가
❌ 모바일 앱 직접 연결 불가
✅ 웹 브라우저로 접근
✅ PWA로 설치 가능

데스크톱/모바일 앱을 사용하려면:

각 기기에 SiYuan 앱 설치
클라우드 동기화 (S3, WebDAV) 또는 SiYuan 공식 클라우드 사용

동기화 옵션

SiYuan Cloud: 공식 유료 동기화 서비스
S3 호환: MinIO, AWS S3 등
WebDAV: Nextcloud, ownCloud 등

관리 명령어

# 로그 확인
docker compose logs -f siyuan

# 워크스페이스 백업
tar -czvf siyuan_backup_$(date +%Y%m%d).tar.gz ./siyuan/workspace

# 컨테이너 재시작
docker compose restart siyuan

# 업데이트
docker compose pull
docker compose up -d

# 권한 문제 해결
sudo chown -R 1000:1000 ./siyuan/workspace

환경 변수 및 파라미터

커맨드 파라미터

파라미터	설명
`--workspace`	워크스페이스 경로
`--accessAuthCode`	접근 인증 코드
`--ssl`	SSL 활성화
`--lang`	언어 설정 (zh_CN, en_US 등)

환경 변수

변수	설명	기본값
TZ	타임존	UTC
PUID	사용자 ID	1000
PGID	그룹 ID	1000

권한 문제 해결

SiYuan에서 가장 흔한 문제는 권한 오류입니다:

# 오류 메시지 예시
# permission denied: mkdir /siyuan/workspace/temp

# 해결 방법 1: 호스트 폴더 권한 변경
sudo chown -R 1000:1000 ./siyuan

# 해결 방법 2: docker-compose.yml에서 PUID/PGID 확인
# 현재 사용자 UID 확인
id -u  # 예: 1001

# docker-compose.yml 수정
environment:
  - PUID=1001
  - PGID=1001

데이터 구조

siyuan/workspace/
├── conf/           # 설정 파일
├── data/           # 노트북 데이터
│   └── 노트북이름/
│       └── 문서.sy
├── temp/           # 임시 파일
├── templates/      # 템플릿
├── widgets/        # 위젯
└── plugins/        # 플러그인

기능 제한 사항 (Docker 버전)

Docker로 호스팅 시 일부 기능이 제한됩니다:

❌ 데스크톱/모바일 앱 직접 연결
❌ PDF, HTML, Word 내보내기
✅ 웹 브라우저 접근
✅ 마크다운 내보내기
✅ 전체 편집 기능
✅ 플러그인/테마

마무리

SiYuan은 Notion, Obsidian, Roam Research의 장점을 결합한 강력한 지식 관리 시스템입니다. 블록 기반 편집과 양방향 링크로 아이디어를 연결하고, 플래시카드와 간격 반복으로 학습 효과를 높일 수 있습니다. Docker로 셀프호스팅하면 브라우저를 통해 어디서든 접근 가능한 개인 위키를 구축할 수 있습니다. 완전 오픈소스이며, 중국 개발팀이 활발하게 개발 중입니다.

참고 링크

공식 사이트: https://b3log.org/siyuan
GitHub: https://github.com/siyuan-note/siyuan
Docker Hub: https://hub.docker.com/r/b3log/siyuan
커뮤니티: https://liuyun.io