Elasticsearch 실전 튜토리얼 — Docker 설치·한국어 검색·Node.js 연동까지

docker-compose.yml
version: '3.8'
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.13.4
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false   # 개발 환경 전용
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports:
      - "9200:9200"
    volumes:
      - es_data:/usr/share/elasticsearch/data

  kibana:
    image: docker.elastic.co/kibana/kibana:8.13.4
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

volumes:
  es_data:

docker exec -it $(docker compose ps -q elasticsearch) bash
./bin/elasticsearch-plugin install analysis-nori
exit
docker compose restart elasticsearch

인덱스 생성·문서 CRUD (curl)
# 인덱스 생성
curl -X PUT http://localhost:9200/products \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    }
  }'

# 문서 추가 (POST: 자동 ID 생성)
curl -X POST http://localhost:9200/products/_doc \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "맥북 프로 M4",
    "description": "애플 실리콘 M4 칩 탑재 개발자용 노트북",
    "price": 2490000,
    "category": "laptop"
  }'

# 특정 ID로 문서 추가 (PUT: 없으면 생성, 있으면 전체 교체)
curl -X PUT http://localhost:9200/products/_doc/1 \
  -H 'Content-Type: application/json' \
  -d '{"name": "맥 미니 M4", "price": 899000}'

# 문서 조회
curl http://localhost:9200/products/_doc/1

# 부분 수정 (_update)
curl -X POST http://localhost:9200/products/_update/1 \
  -H 'Content-Type: application/json' \
  -d '{"doc": {"price": 799000}}'

# 문서 삭제
curl -X DELETE http://localhost:9200/products/_doc/1

nori 분석기 적용 인덱스 매핑
curl -X PUT http://localhost:9200/posts \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "analysis": {
        "analyzer": {
          "korean": {
            "type": "custom",
            "tokenizer": "nori_tokenizer",
            "filter": ["lowercase", "nori_stop"]
          }
        },
        "filter": {
          "nori_stop": {
            "type": "nori_part_of_speech",
            "stoptags": [
              "E", "IC", "J", "MAG", "MAJ", "MM",
              "SP", "SSC", "SSO", "SC", "SE",
              "XPN", "XSA", "XSN", "XSV", "UNA", "NA"
            ]
          }
        }
      },
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "title": {
          "type": "text",
          "analyzer": "korean",
          "fields": {
            "keyword": { "type": "keyword" }
          }
        },
        "content": {
          "type": "text",
          "analyzer": "korean"
        },
        "category": { "type": "keyword" },
        "published_at": { "type": "date" },
        "tags": { "type": "keyword" },
        "slug": { "type": "keyword" }
      }
    }
  }'

curl -X POST "http://localhost:9200/posts/_analyze" \
  -H 'Content-Type: application/json' \
  -d '{"analyzer": "korean", "text": "검색 엔진 설치 방법 알아보기"}'

Elasticsearch 검색 쿼리 예시
// 1. 단순 match 검색
{
  "query": {
    "match": { "title": "Elasticsearch 설치 방법" }
  },
  "size": 10,
  "from": 0
}

// 2. multi_match — title(가중치 2배)과 content 동시 검색
{
  "query": {
    "multi_match": {
      "query": "검색 엔진 설치",
      "fields": ["title^2", "content"],
      "type": "best_fields"
    }
  }
}

// 3. bool 쿼리 — 카테고리 필터 + 키워드 검색 + 날짜 범위
{
  "query": {
    "bool": {
      "must": [
        { "multi_match": {
            "query": "Docker 설치",
            "fields": ["title^2", "content"]
        }}
      ],
      "filter": [
        { "term": { "category": "tutorial" } },
        { "range": { "published_at": { "gte": "2026-01-01" } } }
      ]
    }
  },
  "_source": ["title", "category", "published_at", "slug"],
  "highlight": {
    "fields": {
      "title": {},
      "content": { "fragment_size": 150, "number_of_fragments": 1 }
    }
  }
}

npm install @elastic/elasticsearch@8

lib/elasticsearch.js — 클라이언트 초기화
import { Client } from '@elastic/elasticsearch'

const esClient = new Client({
  node: process.env.ELASTICSEARCH_URL || 'http://localhost:9200',
  // 보안이 활성화된 프로덕션 환경:
  // auth: { username: 'elastic', password: process.env.ES_PASSWORD }
  // tls: { rejectUnauthorized: false }  // 자체 서명 인증서일 때만
})

export default esClient

lib/search.js — 검색·인덱싱 함수
import esClient from './elasticsearch'

export async function searchPosts(keyword, { from = 0, size = 10, category } = {}) {
  const must = [{
    multi_match: {
      query: keyword,
      fields: ['title^2', 'content'],
      type: 'best_fields',
    },
  }]

  const filter = []
  if (category) {
    filter.push({ term: { category } })
  }

  const response = await esClient.search({
    index: 'posts',
    query: { bool: { must, filter } },
    from,
    size,
    highlight: {
      fields: {
        title: {},
        content: { fragment_size: 150, number_of_fragments: 1 },
      },
    },
    _source: ['title', 'category', 'published_at', 'slug'],
  })

  return {
    total: response.hits.total.value,
    hits: response.hits.hits.map((hit) => ({
      id: hit._id,
      score: hit._score,
      ...hit._source,
      highlight: hit.highlight,
    })),
  }
}

export async function indexPost(post) {
  return esClient.index({
    index: 'posts',
    id: String(post.id),
    document: {
      title: post.title,
      content: post.content,
      category: post.category,
      published_at: post.date,
      slug: post.slug,
      tags: post.tags || [],
    },
  })
}

export async function bulkIndexPosts(posts) {
  const operations = posts.flatMap((post) => [
    { index: { _index: 'posts', _id: String(post.id) } },
    {
      title: post.title,
      content: post.content,
      category: post.category,
      published_at: post.date,
      slug: post.slug,
      tags: post.tags || [],
    },
  ])
  return esClient.bulk({ operations })
}

export async function deletePost(id) {
  return esClient.delete({ index: 'posts', id: String(id) })
}

app/api/search/route.js (Next.js App Router)
import { NextResponse } from 'next/server'
import { searchPosts } from '@/lib/search'

export async function GET(request) {
  const { searchParams } = new URL(request.url)
  const q = searchParams.get('q')?.trim()
  const page = Math.max(1, Number(searchParams.get('page') || '1'))
  const category = searchParams.get('category') || undefined
  const size = 10

  if (!q || q.length < 2) {
    return NextResponse.json(
      { error: '검색어는 2자 이상 입력해주세요.' },
      { status: 400 }
    )
  }

  try {
    const result = await searchPosts(q, {
      from: (page - 1) * size,
      size,
      category,
    })
    return NextResponse.json(result)
  } catch (error) {
    console.error('[ES search error]', error.message)
    return NextResponse.json(
      { error: '검색 서비스 일시 오류' },
      { status: 500 }
    )
  }
}