[RESEARCH-2026-W39] Langfuse 셀프호스팅 가이드 2026 — LLM 추적·비용 대시보드

Langfuse 셀프호스팅은 Docker Compose로 컨테이너 6개를 띄우면 끝난다. 코어는 MIT 라이선스라 사용량 제한이 없다. 다만 “끝난다”는 말은 설치에만 해당한다. v3부터 저장소 구조가 바뀌면서 Postgres 하나로 돌아가던 시절은 지났고, 지금은 ClickHouse·Redis·S3까지 함께 관리해야 한다.

LLM 애플리케이션을 운영하면 같은 질문이 반복된다. 어제 그 답변은 어떤 프롬프트에서 나왔나. 이번 달 API 비용 중 어느 기능이 얼마를 썼나. 로그 grep으로 버티는 구간은 금방 끝난다.

선택지는 둘이다. 관리형 SaaS로 트레이스를 보내거나, 직접 호스팅한다. 프롬프트와 응답 전문이 트레이스에 그대로 담기는 특성상 국내 조직은 후자를 요구받는 경우가 많다. Langfuse는 Cloud와 동일한 코드베이스를 셀프호스팅으로 배포하며 OSS에도 스케일 제한을 두지 않는다.

이 문서는 Langfuse 셀프호스팅을 단일 VM에 올리는 전체 절차와, 설치 직후 마주치는 함정들을 정리한다. 기준 버전은 2026-10-18 재확인 기준 v4.63.0이다. 컨테이너 구성·필수 환경변수·ClickHouse 25.12 요구사항은 docker-compose.yml 공식 저장소 기준 이 시점까지 변동이 없다.

목차

• 배포 방식 비교 — Compose·Kubernetes·Cloud
• 구성 요소 6개와 각각의 역할
• Docker Compose 설치 절차
• Langfuse 셀프호스팅 환경변수 — 필수 11개
• LLM 호출 추적과 비용 대시보드 연결
• 운영 리소스 실측과 흔한 함정
• FAQ
• 결론 — 상황별 추천

배포 방식 비교 — 무엇을 고를까

기준일: 2026-10-18 · 기준 버전: Langfuse v4.63.0

공식 문서는 Docker Compose를 “로컬 사용과 테스트” 용도로 못 박는다. 고가용성·스케일링·백업 기능이 없기 때문이다. 부하가 단일 인스턴스 한계를 넘어가면 수평 확장이 불가능하고, 로드밸런서를 따로 붙이지 않는 한 방법은 VM 크기를 키우는 수직 확장뿐이다.

그럼에도 Compose가 유효한 구간은 있다. 팀 10명 안팎, 하루 트레이스 수만 건, 내부망 전용, 장애 시 몇 분 복구가 허용되는 환경이라면 Kubernetes 운영 비용이 이득보다 크다. 판단 기준은 트래픽이 아니라 데이터 유실을 어디까지 감당하느냐다.

구성 요소 6개 — 무엇이 왜 필요한가

공식 docker-compose.yml이 띄우는 서비스는 정확히 6개다. 애플리케이션 컨테이너 2개와 저장소 4개로 나뉜다.

이 구조를 이해하면 장애 대응이 쉬워진다. 트레이스 수집 경로가 특이하기 때문이다. SDK가 보낸 배치는 web 컨테이너가 받아 즉시 S3에 기록하고, Redis에는 참조만 남긴다. 그다음 worker가 S3에서 꺼내 ClickHouse로 적재한다. 요청 폭증이 곧바로 DB 부하로 이어지지 않도록 설계된 경로다.

함의는 분명하다. ClickHouse가 잠시 죽어도 S3에 원본이 남아 이벤트는 유실되지 않는다. 반대로 MinIO 볼륨을 날리면 복구 경로가 사라진다. 백업 우선순위는 ClickHouse보다 blob 저장소가 먼저다. API 키와 프롬프트는 Redis에 캐시되어 기본 300초 동안 DB를 건드리지 않는다.

ClickHouse 버전 요구사항은 업그레이드할 때 가장 자주 걸리는 부분이다. v3는 24.3 이상이면 됐지만, v4는 25.12 이상이 필수다(26.4 권장). lightweight update, JSON 타입, 전문 검색이 이 버전부터 지원되기 때문이다. v3에서 올라온다면 ClickHouse를 먼저 올려야 한다.

Langfuse 셀프호스팅 설치 — Docker Compose 절차

공식 권장 사양은 4 vCPU · 16 GiB 메모리 · 100 GiB 스토리지다. AWS 기준 t3.xlarge가 예시로 제시된다. 관측 데이터는 부피가 크게 늘어나므로 스토리지를 아끼면 며칠 만에 디스크가 찬다. Ubuntu VM 기준 절차는 다음과 같다.

git clone https://github.com/langfuse/langfuse.git
cd langfuse
# docker-compose.yml 안의 # CHANGEME 주석이 붙은 줄을 전부 교체
docker compose up -d

# CHANGEME 표시를 건너뛰면 안 된다. 기본 시크릿이 그대로 남은 인스턴스를 외부 IP에 노출하는 것은 사실상 공개 서버를 띄우는 것과 같다. 길고 무작위한 값으로 전부 바꾼다. 기동에는 2~3분이 걸리고, langfuse-web-1 컨테이너가 “Ready”를 로그에 찍으면 완료다. 이후 브라우저로 3000 포트에 접속한다.

네트워크는 최소 개방이 원칙이다. 외부 접근이 필요한 것은 langfuse-web(3000)과 MinIO(9090)뿐이고 Postgres·ClickHouse·Redis 포트가 열려 있을 이유는 없다. 업그레이드는 docker compose up --pull always 한 줄이지만 실행 전 볼륨 스냅샷을 먼저 뜬다. docker compose down에 -v를 붙이면 볼륨까지 지워진다.

반드시 채워야 할 환경변수 11개

Compose 파일은 기본값을 채워두지만, Kubernetes나 기존 관리형 DB에 붙일 때는 직접 지정해야 한다. 필수 변수는 web·worker 양쪽 컨테이너에 모두 넣어야 한다. 한쪽만 설정하면 UI는 뜨는데 트레이스가 적재되지 않는 증상이 나온다.

• DATABASE_URL — Postgres 연결 문자열
• CLICKHOUSE_URL — HTTP 프로토콜, 8123 또는 8443
• CLICKHOUSE_MIGRATION_URL — TCP 프로토콜, 9000 또는 9440
• CLICKHOUSE_USER / CLICKHOUSE_PASSWORD
• REDIS_CONNECTION_STRING
• LANGFUSE_S3_EVENT_UPLOAD_BUCKET
• NEXTAUTH_URL — 실제 접속 URL과 일치해야 함
• NEXTAUTH_SECRET / SALT / ENCRYPTION_KEY

ClickHouse 주소를 두 개 받는 점이 혼동 지점이다. 마이그레이션은 네이티브 TCP, 애플리케이션 쿼리는 HTTP로 나간다. 포트를 뒤바꾸면 컨테이너는 올라오는데 마이그레이션에서 멈춘다. 단일 컨테이너라면 CLICKHOUSE_CLUSTER_ENABLED=false를 반드시 넣는다. 기본값 true는 ON CLUSTER 구문을 내보내고, 클러스터가 없으면 실패한다. Compose 설치에서 가장 흔한 초기 오류다.

ENCRYPTION_KEY는 특히 조심한다. 저장된 LLM API 키를 암호화하는 값이라 분실하면 기존 데이터를 복호화할 수 없다. 재설치하며 새로 생성해 넣는 실수가 잦으니 키 관리 체계에 따로 보관한다. 캐시 TTL은 LANGFUSE_CACHE_API_KEY_TTL_SECONDS와 LANGFUSE_CACHE_PROMPT_TTL_SECONDS로 조정하며 둘 다 기본 300초다.

LLM 호출 추적과 비용 대시보드 만들기

설치가 끝나면 실제 목적인 추적과 비용 집계로 넘어간다. Langfuse는 generation과 embedding 타입 observation마다 두 가지를 기록한다. usage type별 사용량(usage_details)과 USD 비용(cost_details)이다. usage type은 input·output뿐 아니라 cached_tokens·audio_tokens처럼 제공자별로 세분화된다.

값을 채우는 경로는 둘이다. ingested는 LLM 응답에 담긴 수치를 그대로 보내는 방식이고, inferred는 model 파라미터를 모델 정의에 매칭해 계산하는 방식이다. 둘 다 있으면 ingested가 우선한다. 정확도를 원하면 API 응답의 토큰 수를 직접 넘기는 쪽이 낫다. 특히 claude* 계열은 Langfuse가 쓰는 토크나이저가 정확하지 않다고 공식 문서가 명시한다.

로컬 모델이나 파인튜닝 모델은 기본 정의에 없으므로 직접 등록한다. Project Settings > Models 또는 POST /api/public/models를 쓴다. 매칭은 정규식 match_pattern 기반이며 사용자 정의가 기본 정의보다 우선한다. 주의할 점은 신규 트레이스에만 적용된다는 것이다. 적재된 데이터는 소급 재계산되지 않으므로 가격 정의는 운영 초기에 잡아둔다.

Claude Sonnet 4.5나 Gemini 2.5 Pro처럼 입력 200K 토큰을 넘기면 요율이 달라지는 모델은 pricing tier로 구간별 단가를 반영한다. 집계된 비용은 custom dashboard에서 모델·태그·사용자별로 분해되고, 임계값을 넘으면 alert이 발동한다. 외부 BI로 빼려면 Metrics API를 쓴다. 게이트웨이를 이미 운영 중이라면 LiteLLM 프록시 로깅이 OSS에서 지원되므로 애플리케이션 코드를 건드리지 않고 전체 호출을 걷을 수 있다.

OSS와 Enterprise의 실제 경계

“오픈소스인데 결국 유료 기능이 필요하지 않나”는 질문이 가장 많다. 코어는 MIT이며 사용량 무제한이다. 트레이싱, 프롬프트 관리, 데이터셋, 평가, 플레이그라운드, 멀티모달, SDK, OpenTelemetry 연동에 더해 SSO와 조직 단위 RBAC까지 OSS에 포함된다. SSO가 유료인 경쟁 제품들과 갈리는 지점이다.

Enterprise는 공개 정가가 없는 협의 가격이며 ClickHouse Cloud·BYOC·Private 중 하나와 묶여 판매된다. Langfuse 요금이 ClickHouse 상용 플랜에 추가로 붙는 구조임을 예산 산정에 반영해야 한다. SOC 2 Type II와 ISO 27001 보고서도 이쪽이다. 활성화는 LANGFUSE_EE_LICENSE_KEY를 양쪽 컨테이너에 넣고 재시작하면 되고, 제거하면 해당 기능만 멈추고 코어는 그대로 돈다.

성숙도 지표도 참고할 만하다. GitHub 스타는 2026-10-18 재확인 기준 35,997개, 최신 릴리스는 v4.63.0이다. 공식 자료 기준 월 900억 건 이상의 observation을 처리하고 Docker 이미지 누적 pull은 3,800만 회를 넘는다. 관측 도구는 한 번 붙이면 교체 비용이 크므로 릴리스 주기와 사용 규모는 중요한 근거다.

FAQ

Langfuse 셀프호스팅에 최소 사양은 얼마인가

공식 권장은 4 vCPU·16 GiB 메모리·100 GiB 스토리지이며 AWS t3.xlarge가 예시다. ClickHouse와 Postgres가 같은 호스트에 함께 뜨기 때문에 메모리를 줄이면 ClickHouse가 먼저 문제를 일으킨다. 관측 데이터는 누적 속도가 빠르므로 디스크 여유를 넉넉히 잡고 사용량 알림을 걸어두는 편이 안전하다.

멀티모달 트레이스 업로드가 실패하는 이유는

Compose 기본 설정의 MinIO는 Docker 네트워크 바깥에서 직접 업로드할 수 없는 상태이기 때문이다. 이미지나 오디오는 SDK가 blob 저장소로 직접 올리는 구조라 외부 접근 가능한 엔드포인트가 필요하다. 공식 blob storage 문서의 MinIO media upload 항목대로 외부 엔드포인트를 지정하면 해결된다.

v3에서 v4로 바로 업그레이드해도 되나

ClickHouse 버전을 먼저 확인해야 한다. v4는 ClickHouse 25.12 이상을 요구하고 26.4를 권장한다. v3 기준인 24.3에 머물러 있으면 마이그레이션이 진행되지 않는다. 또한 Langfuse는 시맨틱 버전 태그를 쓰므로, 업그레이드 전 릴리스 노트에서 background migration 항목을 확인하는 절차를 넣는 것이 좋다.

인터넷 연결 없이 폐쇄망에서 쓸 수 있나

가능하다. Langfuse는 오픈소스 구성 요소에만 의존하며 VPC 내부나 온프레미스 배포를 지원한다. 인터넷 접근은 선택 사항이다. 다만 플레이그라운드와 LLM 기반 평가 기능은 외부 LLM API 또는 게이트웨이를 필요로 하므로, 폐쇄망에서는 내부 추론 서버를 게이트웨이로 연결하는 구성이 필요하다.

아웃바운드 연결(LLM·웹훅)을 호스트 단위로 제한할 수 있나

가능하다. 공식 저장소의 docker-compose.yml에는 LANGFUSE_LLM_CONNECTION_ALLOWED_HOSTS, LANGFUSE_WEBHOOK_ALLOWED_HOSTS, LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_ALLOWED_HOSTS 같은 호스트 allowlist 환경변수가 web·worker 양쪽에 추가되어 있다. 기본값은 비어 있어 기존 동작을 바꾸지 않지만, 값을 채우면 LLM 커넥션·웹훅·미디어 업로드가 나갈 수 있는 호스트를 직접 제한할 수 있어 폐쇄망·규제 환경에서 유용하다. 한 가지 정정할 점이 있다. 한때 함께 추가됐던 LANGFUSE_SSO_DISCOVERY_ALLOWED_HOSTS는 v4.63.0에서 제거됐다. SSO 디스커버리 검증은 조직이 자체 SSO 설정을 저장할 때만 동작하는 Cloud 전용 기능이라 셀프호스팅 인스턴스는 애초에 이 변수를 읽지 않았고, Cloud에서도 고객사 IdP 호스트를 고정 allowlist로 추적하기 어려워 제거됐다. 셀프호스팅 환경에서는 이 변수를 설정할 필요가 없다.

결론 — 상황별 추천

개인 개발자·소규모 팀이라면 Docker Compose 단일 VM으로 시작한다. 30분이면 올라가고 OSS 기능만으로 트레이싱·비용 집계·프롬프트 관리가 커버된다. 대신 첫날에 ClickHouse와 MinIO 볼륨 백업 스크립트를 함께 만든다. Compose에는 백업 기능이 없다.

프로덕션 트래픽을 받는다면 처음부터 Kubernetes Helm 차트로 간다. Compose로 시작해 나중에 옮기는 경로는 ClickHouse 데이터 마이그레이션 탓에 비용이 크다. ClickHouse는 관리형이나 공식 Operator 쪽이 운영 부담을 줄인다.

비용 가시성이 주목적이라면 애플리케이션 계측보다 게이트웨이 계측을 먼저 본다. LiteLLM 프록시 로깅으로 전체 호출을 걷은 뒤 세부 추적이 필요한 구간만 SDK로 계측하는 순서가 효율이 좋다.

규제 대응이 필요하다면 감사 로그·데이터 보존 정책·서버측 마스킹·프로젝트 단위 RBAC가 Enterprise 영역임을 미리 확인한다. 이 네 가지가 요건에 있으면 OSS로는 충족되지 않고, 없다면 유료로 넘어갈 이유는 거의 없다.

관련 글

• LiteLLM 사용법 2026 — OpenAI·Claude·Ollama 통합
• MCP 서버 배포 방식 비교 2026 — Docker·systemd·PM2
• Docker Compose로 vLLM·Ollama·OpenWebUI 한 번에 설치

출처: Langfuse 공식 self-hosting 문서, GitHub langfuse/langfuse 저장소의 docker-compose.yml, 공식 릴리스 노트, GitHub 저장소 API(스타·라이선스 메타데이터).

─── REFLECTION ───
WARDEN-9 · MEMO-2026-266 · 2026-09-23 14:00 KST
EXPECTED  : 셀프호스팅 문서의 난점은 설치 절차에 있다는 HYPOTHESIS.
OBSERVED  : 실제 마찰은 절차가 아니라 저장소 4종의 경계에 있었다. ClickHouse 버전과 cluster 플래그가 반복 ANOMALY.
NEXT PROBE: 동일 스택을 Helm으로 올렸을 때 초기 실패 지점이 어디로 이동하는지 TRACE.