시놀로지 Note Station 백업 및 마크다운 변환 스크립트 (3/5)

# 방법 1: cp + unzip (Linux/macOS)
cp backup.nsx backup.zip
unzip backup.zip -d nsx_extracted/

# 방법 2: Python으로 직접 추출 (OS 무관)
python3 -c "
import zipfile
with zipfile.ZipFile('backup.nsx', 'r') as z:
    z.extractall('nsx_extracted/')
print('추출 완료:', len(z.namelist()), '개 파일')
"

nsx_extracted/
├── config.json             # 노트북 목록 및 전체 메타데이터
├── [uuid1].json            # 노트 1 내용 (HTML 본문 포함)
├── [uuid2].json            # 노트 2 내용
├── ...
└── [image_uuid]/           # 첨부 이미지 폴더 (uuid명)
    ├── [img_hash].jpg
    ├── [img_hash].png
    └── width               # 이미지 표시 너비 정보

{
  "title": "홈랩 Docker 네트워크 설정 메모",
  "content": "<div style=\"font-family:Arial;\">
    <strong>핵심 체크:</strong> 브릿지 네트워크 우선 사용.<br>
    <ul><li>서브넷: 172.20.0.0/16</li></ul>
    <img src=\"[image_uuid]/abc123.png\" />
  </div>",
  "ctime": 1715642400,      # 생성 시각 (Unix timestamp)
  "mtime": 1715653200,      # 수정 시각
  "tag": ["홈랩", "Docker", "네트워크"],
  "parent_id": "[notebook_uuid]",  # 소속 노트북
  "attachment": {
    "[image_uuid]": {
      "md5": "abc123...",
      "mime": "image/png",
      "filename": "network_diagram.png"
    }
  }
}

pip install markdownify beautifulsoup4 lxml tqdm

#!/usr/bin/env python3
"""
시놀로지 Note Station .nsx → Markdown 완전 자동화 변환기
사용법: python3 nsx_to_markdown.py --nsx backup.nsx --out ./output
"""
import json, os, re, shutil, zipfile, argparse
from datetime import datetime
from pathlib import Path
from bs4 import BeautifulSoup
from markdownify import markdownify as md
from tqdm import tqdm


def clean_html_to_markdown(html_content: str) -> str:
    """HTML 태그 제거 및 깨끗한 마크다운으로 변환"""
    if not html_content:
        return ""
    # BeautifulSoup로 1차 파싱 (잘못된 HTML 교정)
    soup = BeautifulSoup(html_content, "lxml")

    # 불필요한 스타일/스크립트 태그 완전 제거
    for tag in soup.find_all(["style", "script", "meta"]):
        tag.decompose()

    # markdownify로 마크다운 변환
    result = md(str(soup), heading_style="ATX", bullets="-")

    # 연속 빈줄 정리 (3줄 이상 → 2줄)
    result = re.sub(r'\n{3,}', '\n\n', result)
    return result.strip()


def epoch_to_date(timestamp: int) -> str:
    """Unix timestamp → YYYY-MM-DD 변환"""
    return datetime.fromtimestamp(timestamp).strftime('%Y-%m-%d')


def build_frontmatter(note: dict, notebook_name: str) -> str:
    """YAML Frontmatter 생성"""
    title = note.get("title", "Untitled").replace('"', "'")
    created = epoch_to_date(note.get("ctime", 0))
    updated = epoch_to_date(note.get("mtime", note.get("ctime", 0)))
    tags = note.get("tag", [])
    tags_str = "[" + ", ".join(f'"{t}"' for t in tags) + "]"

    return f"""---
title: "{title}"
date: {created}
updated: {updated}
tags: {tags_str}
notebook: "{notebook_name}"
source: synology_note_station
---"""


def process_images(note: dict, src_dir: Path, out_dir: Path) -> dict:
    """첨부 이미지를 출력 폴더로 복사하고 경로 매핑 반환"""
    path_map = {}
    attachments = note.get("attachment", {})
    if not attachments:
        return path_map

    img_out = out_dir / "images"
    img_out.mkdir(exist_ok=True)

    for att_id, att_info in attachments.items():
        src_img = src_dir / att_id
        if src_img.is_dir():
            for img_file in src_img.iterdir():
                if img_file.name != "width":
                    dest = img_out / img_file.name
                    shutil.copy2(img_file, dest)
                    # HTML의 원본 경로 → 상대 경로 매핑
                    path_map[att_id] = f"images/{img_file.name}"
    return path_map


def convert_nsx(nsx_path: str, output_dir: str):
    nsx_path = Path(nsx_path)
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    # 1. .nsx 압축 해제
    tmp_dir = Path("/tmp/nsx_tmp")
    if tmp_dir.exists():
        shutil.rmtree(tmp_dir)
    with zipfile.ZipFile(nsx_path, 'r') as z:
        z.extractall(tmp_dir)
    print(f"✅ 압축 해제 완료: {len(list(tmp_dir.iterdir()))}개 파일")

    # 2. config.json에서 노트북 이름 매핑
    config_path = tmp_dir / "config.json"
    notebook_map = {}
    if config_path.exists():
        config = json.loads(config_path.read_text(encoding="utf-8"))
        for nb in config.get("notebook", []):
            notebook_map[nb.get("noteBookId", "")] = nb.get("title", "Unknown")

    # 3. 모든 노트 JSON 처리
    note_files = [f for f in tmp_dir.iterdir()
                  if f.suffix == ".json" and f.name != "config.json"]
    print(f"📝 처리할 노트 수: {len(note_files)}개")

    success, failed = 0, 0
    for note_file in tqdm(note_files, desc="변환 중"):
        try:
            note = json.loads(note_file.read_text(encoding="utf-8"))
            title = note.get("title", "Untitled")
            notebook_id = note.get("parent_id", "")
            notebook_name = notebook_map.get(notebook_id, "Unsorted")

            # 노트북별 서브폴더 생성
            safe_nb = re.sub(r'[^\w\s-]', '', notebook_name).strip()
            nb_dir = output_dir / safe_nb
            nb_dir.mkdir(exist_ok=True)

            # 이미지 복사 및 경로 매핑
            path_map = process_images(note, tmp_dir, nb_dir)

            # HTML → 마크다운 변환
            content = clean_html_to_markdown(note.get("content", ""))

            # 이미지 경로 치환
            for att_id, rel_path in path_map.items():
                content = content.replace(att_id, rel_path)

            # YAML Frontmatter 결합
            frontmatter = build_frontmatter(note, notebook_name)
            final_md = f"{frontmatter}\n\n# {title}\n\n{content}"

            # 파일명 안전 처리 후 저장
            safe_title = re.sub(r'[^\w\s-]', '', title)[:60].strip()
            created = epoch_to_date(note.get("ctime", 0))
            filename = f"{created}_{safe_title}.md"
            (nb_dir / filename).write_text(final_md, encoding="utf-8")
            success += 1

        except Exception as e:
            print(f"\n❌ 변환 실패: {note_file.name} — {e}")
            failed += 1

    print(f"\n✅ 변환 완료: {success}개 성공 / {failed}개 실패")
    shutil.rmtree(tmp_dir)


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--nsx", required=True, help=".nsx 파일 경로")
    parser.add_argument("--out", required=True, help="출력 폴더 경로")
    args = parser.parse_args()
    convert_nsx(args.nsx, args.out)

# 기본 실행
python3 nsx_to_markdown.py --nsx ~/Downloads/backup.nsx --out ~/AI_Knowledge_Base/

# 실행 결과 예시
# ✅ 압축 해제 완료: 847개 파일
# 📝 처리할 노트 수: 823개
# 변환 중: 100%|████████████| 823/823 [02:34<00:00,  5.3it/s]
# ✅ 변환 완료: 819개 성공 / 4개 실패

---
# ── 기본 식별 정보 ─────────────────────────
title: "KOSPI 2023 약세장 대응 원칙"
date: 2023-10-15          # 작성일 (필터링 핵심)
updated: 2024-02-20       # 최종 수정일

# ── 분류 체계 ──────────────────────────────
notebook: "투자"           # 원본 노트북 이름
category: "investment"     # 영문 카테고리 (필터 쿼리용)
tags: ["KOSPI", "리스크관리", "원칙", "2023"]

# ── RAG 필터링용 커스텀 필드 ───────────────
domain: "finance"          # 지식 도메인
importance: "high"         # high / medium / low
market_condition: "bear"   # 작성 당시 시장 상황
review_status: "reviewed"  # draft / reviewed / archived
language: "ko"

# ── 원본 추적 정보 ─────────────────────────
source: "synology_note_station"
original_ctime: 1715642400  # 원본 타임스탬프 보존
---

import base64, httpx

def generate_alt_text(image_path: str, ollama_url: str = "http://localhost:11434") -> str:
    """Ollama Vision 모델로 이미지 Alt 텍스트 자동 생성"""
    with open(image_path, "rb") as f:
        img_b64 = base64.b64encode(f.read()).decode()

    response = httpx.post(f"{ollama_url}/api/generate", json={
        "model": "llava:13b",  # 또는 gemma3:12b
        "prompt": "이 이미지를 한국어로 50자 이내로 간결하게 설명해줘. "
                  "다이어그램이면 구조를, 스크린샷이면 화면 내용을 중심으로.",
        "images": [img_b64],
        "stream": False
    })
    return response.json().get("response", "").strip()

# 마크다운의 이미지 태그에 Alt 텍스트 삽입
# 변환 전: ![](images/abc123.png)
# 변환 후: ![Docker 네트워크 브릿지 구성 다이어그램](images/abc123.png)

import os, re
from pathlib import Path

def validate_markdown_quality(output_dir: str):
    """변환된 마크다운 파일 품질 일괄 검증"""
    issues = []
    md_files = list(Path(output_dir).rglob("*.md"))
    print(f"검증 대상: {len(md_files)}개 파일")

    for md_file in md_files:
        content = md_file.read_text(encoding="utf-8")

        # 1. HTML 태그 잔존 여부 확인
        html_tags = re.findall(r'<\w+[^>]*>', content)
        if html_tags:
            issues.append(f"⚠️ HTML 잔존: {md_file.name} ({len(html_tags)}개 태그)")

        # 2. YAML Frontmatter 존재 여부
        if not content.startswith("---"):
            issues.append(f"❌ Frontmatter 없음: {md_file.name}")

        # 3. 내용이 너무 짧은 파일 (HTML만 있었던 경우)
        body = content.split("---", 2)[-1] if "---" in content else content
        if len(body.strip()) < 50:
            issues.append(f"⚠️ 내용 부족 (50자 미만): {md_file.name}")

        # 4. 깨진 이미지 링크 확인
        img_links = re.findall(r'!\[.*?\]\((.*?)\)', content)
        for link in img_links:
            if not (md_file.parent / link).exists():
                issues.append(f"🖼️ 이미지 경로 깨짐: {md_file.name} → {link}")

    if issues:
        print(f"\n⚠️ 발견된 문제: {len(issues)}건")
        for issue in issues[:20]:  # 최대 20건 출력
            print(f"  {issue}")
    else:
        print("✅ 모든 파일 품질 검증 통과!")

validate_markdown_quality("./AI_Knowledge_Base")

/volume1/AI_Knowledge_Base/
├── 투자/
│   ├── images/
│   │   └── 2023-10-15_chart.png
│   ├── 2023-10-15_KOSPI_2023_약세장_대응_원칙.md
│   └── 2024-01-20_포트폴리오_리밸런싱_기록.md
├── 홈랩/
│   ├── images/
│   ├── 2024-03-01_Docker_네트워크_설정.md
│   └── 2024-05-10_시놀로지_NAS_설정_메모.md
├── 일기/
│   └── 2024/
│       ├── 2024-01-01_신년_다짐.md
│       └── ...
└── _backup/
    └── backup_original.nsx  # 원본 보존