Meilisearch 완전 정복 — Strapi v5 연동 로컬 AI 홈랩 초고속 검색 허브 구축 2026

# 설정 파일이 위치할 디렉토리
mkdir -p /mnt/data/01_ai/meilisearch

# 인덱스 데이터 영구 저장 디렉토리
mkdir -p /mnt/data/01_ai/meilisearch/data

cd /mnt/data/01_ai/meilisearch

services:
  meilisearch:
    image: getmeili/meilisearch:v1.13
    container_name: meilisearch
    restart: unless-stopped
    ports:
      - "7700:7700"
    environment:
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
      - MEILI_ENV=production
      - MEILI_DB_PATH=/meili_data
      - MEILI_NO_ANALYTICS=true
    volumes:
      # ./data 는 이 파일이 있는 디렉토리 기준 상대 경로
      # 실제 경로: /mnt/data/01_ai/meilisearch/data/
      - ./data:/meili_data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7700/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - ai-common-net

networks:
  ai-common-net:
    external: true

# 32자 이상 강한 키 필수 — 아래 명령어로 생성
# openssl rand -hex 32
MEILI_MASTER_KEY=여기에_강한_마스터키_입력_최소_32자_이상

cd /mnt/data/01_ai/meilisearch
docker compose up -d

# 정상 기동 확인 — {"status":"available"} 이 나오면 성공
curl http://localhost:7700/health

# 로그 실시간 확인
docker compose logs -f meilisearch

curl -X POST 'http://localhost:7700/indexes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY' \
  --data-binary '{
    "uid": "blog-posts",
    "primaryKey": "post_id"
  }'

curl -X PATCH 'http://localhost:7700/indexes/blog-posts/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY' \
  --data-binary '{
    "searchableAttributes": [
      "title",
      "excerpt",
      "content",
      "tags",
      "category"
    ],
    "filterableAttributes": [
      "category",
      "tags",
      "status",
      "author",
      "published_at"
    ],
    "sortableAttributes": [
      "published_at",
      "views",
      "updated_at"
    ],
    "displayedAttributes": [
      "post_id",
      "title",
      "excerpt",
      "category",
      "tags",
      "author",
      "published_at",
      "url",
      "thumbnail"
    ]
  }'

curl -X POST 'http://localhost:7700/indexes/blog-posts/documents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_ADMIN_KEY' \
  --data-binary '[
    {
      "post_id": 1,
      "title": "Plane 셀프호스팅 완전 가이드 2026",
      "excerpt": "Jira 대체 오픈소스 프로젝트 관리 툴 Plane을 홈서버에 설치하는 방법",
      "content": "...(본문 전체 또는 요약)...",
      "category": "홈랩",
      "tags": ["Plane", "Docker", "셀프호스팅", "프로젝트관리"],
      "author": "agibop",
      "status": "published",
      "published_at": 1751788800,
      "views": 1250,
      "url": "https://agibop.com/plane-selfhost-complete-guide-2026/",
      "thumbnail": "https://agibop.com/wp-content/uploads/plane-guide.jpg"
    }
  ]'

curl -X POST 'http://localhost:7700/indexes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY' \
  --data-binary '{
    "uid": "news-feed",
    "primaryKey": "article_id"
  }'

curl -X PATCH 'http://localhost:7700/indexes/news-feed/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY' \
  --data-binary '{
    "searchableAttributes": [
      "title",
      "summary",
      "content",
      "tags",
      "source_name"
    ],
    "filterableAttributes": [
      "source",
      "source_name",
      "category",
      "tags",
      "lang",
      "published_at"
    ],
    "sortableAttributes": [
      "published_at",
      "crawled_at"
    ],
    "displayedAttributes": [
      "article_id",
      "title",
      "summary",
      "source",
      "source_name",
      "category",
      "tags",
      "lang",
      "published_at",
      "url",
      "thumbnail"
    ]
  }'

curl -X POST 'http://localhost:7700/indexes/news-feed/documents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_ADMIN_KEY' \
  --data-binary '[
    {
      "article_id": "reuters-2026-07-06-001",
      "title": "Fed signals rate cut as inflation cools to 2.1%",
      "summary": "Federal Reserve officials signal potential rate cuts...",
      "content": "...(전문)...",
      "source": "reuters.com",
      "source_name": "Reuters",
      "category": "economy",
      "tags": ["Fed", "금리", "인플레이션", "미국경제"],
      "lang": "en",
      "published_at": 1751788800,
      "crawled_at": 1751789400,
      "url": "https://reuters.com/...",
      "thumbnail": "https://..."
    }
  ]'

curl -X POST 'http://localhost:7700/indexes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY' \
  --data-binary '{
    "uid": "products",
    "primaryKey": "sku"
  }'

curl -X PATCH 'http://localhost:7700/indexes/products/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY' \
  --data-binary '{
    "searchableAttributes": [
      "name",
      "description",
      "brand",
      "tags",
      "category"
    ],
    "filterableAttributes": [
      "category",
      "brand",
      "in_stock",
      "price",
      "rating"
    ],
    "sortableAttributes": [
      "price",
      "rating",
      "created_at"
    ],
    "displayedAttributes": [
      "sku",
      "name",
      "description",
      "brand",
      "category",
      "price",
      "in_stock",
      "rating",
      "thumbnail"
    ]
  }'

# Master Key로 API 키 목록 조회
curl 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY'

# 응답에서 확인:
# "Default Admin API Key"  → 문서 추가/삭제 등 백엔드·n8n에서 사용
# "Default Search API Key" → 검색 전용, 프론트엔드에 노출 가능

curl -X POST 'http://localhost:7700/indexes/blog-posts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_SEARCH_KEY' \
  --data-binary '{
    "q": "Docker",
    "limit": 10,
    "offset": 0
  }'

# news-feed: 영문 economy 카테고리, 최신순 정렬
curl -X POST 'http://localhost:7700/indexes/news-feed/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_SEARCH_KEY' \
  --data-binary '{
    "q": "Fed rate cut",
    "filter": "lang = en AND category = economy",
    "sort": ["published_at:desc"],
    "limit": 5
  }'

# blog-posts: 홈랩 카테고리 + 조회수 높은 순
curl -X POST 'http://localhost:7700/indexes/blog-posts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_SEARCH_KEY' \
  --data-binary '{
    "q": "Prometheus",
    "filter": "category = 홈랩 AND status = published",
    "sort": ["views:desc"],
    "limit": 5
  }'

curl -X POST 'http://localhost:7700/indexes/blog-posts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 여기에_SEARCH_KEY' \
  --data-binary '{
    "q": "Meilisearch",
    "attributesToHighlight": ["title", "excerpt"],
    "highlightPreTag": "<mark>",
    "highlightPostTag": "</mark>",
    "attributesToCrop": ["content"],
    "cropLength": 150,
    "limit": 5
  }'

Method:  POST
URL:     http://meilisearch:7700/indexes/blog-posts/documents
         (ai-common-net 내부 통신, 컨테이너명으로 접근)

Headers:
  Authorization: Bearer [ADMIN_KEY]
  Content-Type:  application/json

Body (JSON):
[
  {
    "post_id":      {{ $json.id }},
    "title":        "{{ $json.title.rendered }}",
    "excerpt":      "{{ $json.excerpt.rendered | stripHtml | truncate(200) }}",
    "content":      "{{ $json.content.rendered | stripHtml | truncate(2000) }}",
    "category":     "{{ $json.categories[0].name }}",
    "tags":         {{ $json.tags | map('name') | json }},
    "author":       "agibop",
    "status":       "published",
    "published_at": {{ $json.date | toTimestamp }},
    "url":          "{{ $json.link }}",
    "thumbnail":    "{{ $json.featured_media_src_url }}"
  }
]

워크플로우: Cron(30분) → RSS Feed Read → Set → HTTP Request
Method:  POST
URL:     http://meilisearch:7700/indexes/news-feed/documents

Body (JSON):
[
  {
    "article_id":   "{{ $json.guid }}",
    "title":        "{{ $json.title }}",
    "summary":      "{{ $json.contentSnippet | truncate(300) }}",
    "source":       "{{ $json.link | extractDomain }}",
    "source_name":  "{{ $node['RSS Feed'].json.feedTitle }}",
    "category":     "{{ $json.categories[0] ?? 'general' }}",
    "tags":         {{ $json.categories | json }},
    "lang":         "{{ $json.lang ?? 'ko' }}",
    "published_at": {{ $json.pubDate | toTimestamp }},
    "crawled_at":   {{ $now | toTimestamp }},
    "url":          "{{ $json.link }}"
  }
]

cd /mnt/data/01_ai/meilisearch

# 1. docker-compose.yaml에서 이미지 태그 수정
#    image: getmeili/meilisearch:v1.12  →  v1.13

# 2. 새 이미지 Pull 및 재시작
docker compose pull
docker compose up -d

# 3. 정상 기동 확인
curl http://localhost:7700/health

### Step 1: 현재 버전에서 Dump 생성
curl -X POST 'http://localhost:7700/dumps' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY'

# 반환된 taskUid로 완료 여부 확인 (status: "succeeded" 대기)
curl 'http://localhost:7700/tasks/여기에_TASK_UID' \
  -H 'Authorization: Bearer 여기에_MASTER_KEY'

# Dump 파일 위치 확인
# 호스트 경로: /mnt/data/01_ai/meilisearch/data/dumps/
ls /mnt/data/01_ai/meilisearch/data/dumps/

### Step 2: docker-compose.yaml 이미지 버전 변경
#   image: getmeili/meilisearch:v1.x → v2.x

### Step 3: One-off 컨테이너로 Dump 임포트
docker compose run --rm \
  -e MEILI_IMPORT_DUMP="/meili_data/dumps/20260706-120000.dump" \
  meilisearch

### Step 4: 임포트 완료 후 정상 기동
docker compose up -d

# meilisearch 컨테이너의 네트워크 확인
docker inspect meilisearch | grep -A 10 "Networks"

# ai-common-net에 없다면 수동 연결
docker network connect ai-common-net meilisearch

# 연결 후 n8n에서 재시도