1. Зачем нужен LLM Observability и как устроен Langfuse v4
Каждый разработчик или владелец онлайн-бизнеса, запускающий в работу искусственный интеллект — будь то бот клиентской поддержки в Telegram, агент автогенерации товарных карточек в интернет-магазине или RAG-пайплайн по корпоративным регламентам, — неизбежно сталкивается с феноменом «черного ящика». Обычное текстовое логирование в терминал или файлы app.log мгновенно захлебывается: многостраничные JSON-ответы, вложенные ветвления вызовов функций (Function Calling), скрытые ретраи сетевых шлюзов и хаотичный расход токенов превращают отладку в мучение.
В продакшене бизнес платит реальные деньги за каждый сгенерированный токен. Когда пользователи начинают жаловаться: «Бот зависает на 15 секунд», «Ассистент галлюцинирует и выдумывает несуществующие скидки» или счета за OpenAI API / облачные шлюзы неожиданно вырастают вчетверо, без специализированной платформы телеметрии локализовать причину невозможно. Именно эту задачу решает класс систем LLM Observability, безоговорочным open-source лидером среди которых является Langfuse (более 12 000 звёзд на GitHub).
- Сквозной трейсинг цепочек (Traces & Spans): вы видите все дерево выполнения запроса от нажатия кнопки пользователем до вызова векторной базы данных, реранкера и финальной генерации модели с точным замером времени каждого шага.
- Финансовый аудит и биллинг: детальный учет расходов до десятых долей цента в разрезе пользователей, API-ключей, моделей и релизов промптов.
- Версионирование промптов (Prompt Management): централизованное хранение и правка системных инструкций без необходимости пересобирать код и перезапускать микросервисы.
- Оценка качества (LLM-as-a-Judge): автоматическое тестирование ответов на галлюцинации, токсичность и соответствие фактам.
- 100% приватность данных по 152-ФЗ: конфиденциальные запросы клиентов и логи переписок не уходят в зарубежные Saas-системы вроде LangSmith или Datadog, а остаются исключительно на вашем защищенном VDS в РФ.
Архитектура Langfuse v4: микросервисы и роль ClickHouse
В четвертом мажорном поколении архитекторы Langfuse кардинально переработали ядро системы для работы под экстремальными нагрузками. Если ранние версии сохраняли все события в реляционную PostgreSQL, что приводило к деградации дисковой подсистемы при интенсивном потоке логов, то в архитектуре Langfuse v4 обязанности строго разделены:
langfuse-web(образdocker.langfuse.com/langfuse/langfuse:4): графический интерфейс на Next.js и высокоскоростной API-шлюз для приема входящей телеметрии.langfuse-worker(образdocker.langfuse.com/langfuse/langfuse-worker:4): изолированный фоновый воркер, который разгружает веб-ядро, асинхронно обрабатывает очереди BullMQ, агрегирует статистику и выполняет фоновые вычисления оценок.clickhouse(образclickhouse/clickhouse-server:24.8-alpine): высокопроизводительная колоночная СУБД. Именно ClickHouse принимает миллионы событий трейсинга, сжимает их по колонкам и обеспечивает мгновенные аналитические выборки за доли секунды.postgres(образpostgres:17-alpine): надежное реляционное хранилище для метаданных: учетных записей пользователей, проектов, прав доступа (RBAC), API-ключей и версий промптов.redis(образredis:7-alpine): оперативная память для очередей задач BullMQ и кэширования горячих сессий.minio(образminio/minio:RELEASE.2024-11-07T00-52-20Z): локальное S3-совместимое объектное хранилище для крупных полезных нагрузок (сырые JSON-дампы, мультимодальные изображения, аудиозаписи голосовых ботов и пакетные экспорты).
2. Системные требования и подготовка VDS-сервера
Поскольку стек Langfuse v4 объединяет 6 взаимодействующих контейнеров (включая прожорливый к памяти ClickHouse и СУБД PostgreSQL 17), выбор параметров VDS напрямую влияет на стабильность работы ядра.
| Параметр | Минимальная конфигурация (Dev / Тесты) | Рекомендуемая конфигурация (Production) |
|---|---|---|
| Процессор (vCPU) | 2 ядра (от 2.8 ГГц) | 4 ядра (от 3.3 ГГц NVMe) |
| Оперативная память (RAM) | 4 ГБ (+ 4 ГБ Swap обязательно) | 8 ГБ (+ 4 ГБ Swap) |
| Дисковый накопитель | 40 ГБ NVMe | 80–120 ГБ NVMe |
| Операционная система | Ubuntu 24.04 LTS / Debian 12 | Ubuntu 24.04 LTS / Debian 12 |
| Расчетный трафик событий | До 5 000 трейсов в сутки | От 50 000 до 500 000+ трейсов в сутки |
Если развернуть ClickHouse на сервере с 2–4 ГБ памяти без файла подкачки, системный механизм Linux OOM Killer неизбежно завершит процесс базы данных в момент построения тяжелого аналитического отчета. Поэтому первым шагом на сервере настраиваем обязательный Swap-раздел размером 4 ГБ.
Создание файла подкачки (Swap) и тюнинг ядра Linux
# Проверяем наличие активного swap
sudo swapon --show
# Если подкачки нет — создаем файл на 4 ГБ
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Фиксируем монтирование swap при перезагрузке сервера
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# Оптимизируем vm.swappiness (не сбрасывать память в swap без нужды)
sudo sysctl vm.swappiness=20
echo 'vm.swappiness=20' | sudo tee -a /etc/sysctl.d/99-sysctl.conf
# Увеличиваем лимиты виртуальной памяти для ClickHouse
sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.d/99-sysctl.conf
Установка официального Docker Engine и плагина Compose
Категорически не рекомендуется использовать устаревшие пакеты docker.io из стандартных репозиториев Ubuntu. Устанавливаем официальный современный стек Docker:
# Удаляем старые пакеты при их наличии
sudo apt-get remove -y docker docker-engine docker.io containerd runc
# Обновляем индекс пакетов и ставим утилиты загрузки
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release
# Добавляем официальный GPG-ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Подключаем репозиторий Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Устанавливаем Docker Engine, CLI и плагин Compose
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Проверяем корректность версий
docker --version
docker compose version
3. Полный манифест Docker Compose для Langfuse v4
Разворачивать стек Langfuse v4 мы будем в каталоге /opt/langfuse. Для соблюдения стандартов безопасности production-систем все внутренние порты баз данных (PostgreSQL, ClickHouse, Redis) и хранилища MinIO привязаны строго к интерфейсу локальной петли 127.0.0.1. Это гарантирует, что даже при включенном Docker-демоне сервисы не окажутся выставленными в открытый интернет в обход системного фаервола UFW. Проверить закрытие портов после запуска вы всегда можете через онлайн-сканер портов SysKit.
Генерация ключей шифрования и подготовка файла .env
Создаем рабочую директорию и генерируем криптографические ключи для шифрования данных и сессий NextAuth. Сгенерировать надежные пароли для баз данных поможет генератор паролей SysKit.
# Создаем изолированную директорию
sudo mkdir -p /opt/langfuse
cd /opt/langfuse
# Генерируем 64-символьный (256-битный) ключ шифрования AES для ENCRYPTION_KEY
openssl rand -hex 32
# Генерируем секрет сессий NextAuth
openssl rand -hex 32
# Генерируем случайную соль для хеширования
openssl rand -hex 16
Создаем конфигурационный файл /opt/langfuse/.env и указываем сгенерированные значения (замените плейсхолдеры на реальные пароли и ваш домен):
# /opt/langfuse/.env
# Основной публичный URL сервиса (обязательно с HTTPS)
NEXTAUTH_URL=https://langfuse.yourdomain.ru
NEXTAUTH_SECRET=9a4f8b2c1e7d3a5f6e8b0c2d4e6f8a1b3c5e7d9a1b3c5e7f9a1b3c5e7d9a1b3c
# Ключи безопасности ядра Langfuse
SALT=8f1c3d2e5a7b9c0e4d6f8a1b3c5e7d9a
ENCRYPTION_KEY=e4d2a1b9c8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1
TELEMETRY_ENABLED=false
# PostgreSQL 17 (метаданные, пользователи, проекты)
POSTGRES_USER=langfuse
POSTGRES_PASSWORD=SuperSecretPgPassword2026!
POSTGRES_DB=langfuse
DATABASE_URL=postgresql://langfuse:SuperSecretPgPassword2026!@postgres:5432/langfuse
# ClickHouse 24.8 (высокопроизводительный трейсинг)
CLICKHOUSE_USER=clickhouse
CLICKHOUSE_PASSWORD=SuperSecretClickhousePassword2026!
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000
# Redis 7 (очереди фонового воркера BullMQ)
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_AUTH=SuperSecretRedisPassword2026!
# MinIO S3 (хранилище полезных нагрузок и медиафайлов)
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=SuperSecretMinioPassword2026!
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=minioadmin
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=SuperSecretMinioPassword2026!
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://minio:9000
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID=minioadmin
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY=SuperSecretMinioPassword2026!
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT=http://minio:9000
LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT=http://minio:9000
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX=media/
Защищаем файл переменных от несанкционированного чтения другими пользователями VDS:
sudo chmod 600 /opt/langfuse/.env
Манифест docker-compose.yml с лимитами ресурсов
Ниже представлен полностью готовый к продакшену манифест /opt/langfuse/docker-compose.yml. В манифесте строго зафиксированы официальные стабильные теги образов и выставлены лимиты mem_limit и cpus для каждого сервиса, защищающие сервер от исчерпания системных ресурсов:
# /opt/langfuse/docker-compose.yml
services:
# Фоновый процессор очередей и аналитических агрегаций
langfuse-worker:
image: docker.langfuse.com/langfuse/langfuse-worker:4
container_name: langfuse_worker
restart: always
env_file:
- .env
depends_on:
postgres:
condition: service_healthy
clickhouse:
condition: service_healthy
redis:
condition: service_healthy
minio:
condition: service_healthy
ports:
- "127.0.0.1:3030:3030"
mem_limit: 1536m
cpus: 1.5
networks:
- langfuse_net
# Основной веб-интерфейс и API-шлюз приема трейсов
langfuse-web:
image: docker.langfuse.com/langfuse/langfuse:4
container_name: langfuse_web
restart: always
env_file:
- .env
depends_on:
postgres:
condition: service_healthy
clickhouse:
condition: service_healthy
redis:
condition: service_healthy
minio:
condition: service_healthy
ports:
- "127.0.0.1:3000:3000"
mem_limit: 1536m
cpus: 1.5
networks:
- langfuse_net
# Колоночная СУБД для телеметрии, спанов и метрик
clickhouse:
image: clickhouse/clickhouse-server:24.8-alpine
container_name: langfuse_clickhouse
restart: always
user: "101:101"
environment:
CLICKHOUSE_DB: default
CLICKHOUSE_USER: ${CLICKHOUSE_USER}
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
volumes:
- langfuse_clickhouse_data:/var/lib/clickhouse
- langfuse_clickhouse_logs:/var/log/clickhouse-server
ports:
- "127.0.0.1:8123:8123"
- "127.0.0.1:9000:9000"
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:8123/ping || exit 1"]
interval: 5s
timeout: 5s
retries: 10
start_period: 5s
mem_limit: 2048m
cpus: 2.0
networks:
- langfuse_net
# Реляционная база данных для пользователей, проектов и настроек
postgres:
image: postgres:17-alpine
container_name: langfuse_postgres
restart: always
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
TZ: UTC
PGTZ: UTC
volumes:
- langfuse_postgres_data:/var/lib/postgresql/data
ports:
- "127.0.0.1:5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 3s
timeout: 3s
retries: 10
mem_limit: 1024m
cpus: 1.0
networks:
- langfuse_net
# Очереди задач и оперативный кэш
redis:
image: redis:7-alpine
container_name: langfuse_redis
restart: always
command: >
--requirepass ${REDIS_AUTH}
--maxmemory 384mb
--maxmemory-policy noeviction
volumes:
- langfuse_redis_data:/data
ports:
- "127.0.0.1:6379:6379"
healthcheck:
test: ["CMD-SHELL", "redis-cli -a ${REDIS_AUTH} ping | grep PONG || exit 1"]
interval: 3s
timeout: 5s
retries: 10
mem_limit: 512m
cpus: 0.5
networks:
- langfuse_net
# Локальное S3-хранилище полезных нагрузок
minio:
image: minio/minio:RELEASE.2024-11-07T00-52-20Z
container_name: langfuse_minio
restart: always
entrypoint: sh
command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
environment:
MINIO_ROOT_USER: ${MINIO_ROOT_USER}
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
volumes:
- langfuse_minio_data:/data
ports:
- "127.0.0.1:9090:9000"
- "127.0.0.1:9091:9001"
healthcheck:
test: ["CMD-SHELL", "curl -f http://127.0.0.1:9000/minio/health/live || exit 1"]
interval: 5s
timeout: 5s
retries: 10
start_period: 3s
mem_limit: 512m
cpus: 0.5
networks:
- langfuse_net
volumes:
langfuse_postgres_data:
driver: local
langfuse_clickhouse_data:
driver: local
langfuse_clickhouse_logs:
driver: local
langfuse_redis_data:
driver: local
langfuse_minio_data:
driver: local
networks:
langfuse_net:
driver: bridge
Запускаем стек и проверяем успешное прохождение статус-чеков:
# Загружаем образы и запускаем контейнеры в фоновом режиме
cd /opt/langfuse
docker compose up -d
# Проверяем статусы контейнеров (все должны быть Up (healthy))
docker compose ps
4. Настройка Nginx, Let's Encrypt SSL и проксирование
Веб-интерфейс Langfuse принимает соединения на локальном порту 127.0.0.1:3000. Чтобы опубликовать платформу в интернете с защищенным протоколом HTTPS и поддержкой WebSocket для интерактивных дашбордов, настроим хостовый Nginx (версии nginx:1.26-alpine). Если вы используете другой веб-сервер, воспользуйтесь интерактивным генератором конфигураций Nginx от SysKit.
Установка Nginx и Certbot
sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx
Создание виртуального хоста Nginx
Создаем файл /etc/nginx/sites-available/langfuse.conf (замените langfuse.yourdomain.ru на ваше реальное доменное имя):
server {
listen 80;
server_name langfuse.yourdomain.ru;
# Увеличенный лимит тела запроса для мультимодальных трейсов и вложений
client_max_body_size 50M;
# Скрытие версии веб-сервера
server_tokens off;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
# Проброс заголовков для WebSockets и Server-Sent Events (SSE)
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# Передача реальных IP-адресов клиентов
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;
# Увеличенные таймауты для тяжелых аналитических выборок
proxy_connect_timeout 60s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
}
}
Активируем конфигурацию и выпускаем бесплатный SSL-сертификат:
# Создаем символическую ссылку
sudo ln -sf /etc/nginx/sites-available/langfuse.conf /etc/nginx/sites-enabled/
# Проверяем синтаксис Nginx
sudo nginx -t
# Перезагружаем Nginx
sudo systemctl reload nginx
# Выпускаем SSL-сертификат Let's Encrypt с автоматическим редиректом на HTTPS
sudo certbot --nginx -d langfuse.yourdomain.ru --redirect --non-interactive --agree-tos -m admin@yourdomain.ru
После установки сертификата проверьте корректность SSL-цепочки и дату истечения ключа с помощью инструмента проверки SSL от SysKit.
5. Практическая интеграция: Python SDK, LiteLLM и Telegram-боты
Открыв в браузере адрес https://langfuse.yourdomain.ru, создайте первого администратора и перейдите в Settings → API Keys. Скопируйте Public Key (начинается на pk-lf-...), Secret Key (начинается на sk-lf-...) и Host (ваш URL https://langfuse.yourdomain.ru).
Способ 1: Прямой перехват вызовов OpenAI (Drop-in Replacement)
Для проектов на Python официальная библиотека langfuse>=2.50.0 предоставляет готовую обертку, которая подменяет клиент OpenAI. Вы не меняете ни строчки бизнес-логики:
pip install "langfuse>=2.50.0" openai
import os
from langfuse.openai import openai
# Настраиваем переменные подключения к собственному инстансу Langfuse
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-1a2b3c4d5e6f..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-9z8y7x6w5v4u..."
os.environ["LANGFUSE_HOST"] = "https://langfuse.yourdomain.ru"
# Стандартный клиент OpenAI автоматически отправляет трейс в Langfuse!
response = openai.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Ты эксперт клиентской поддержки интернет-магазина."},
{"role": "user", "content": "Подскажи, где забрать заказ #4812 в Санкт-Петербурге?"}
],
name="customer-support-chat",
metadata={"channel": "telegram", "user_id": "tg_712398451"},
tags=["support", "delivery"]
)
print("Ответ модели:", response.choices[0].message.content)
Способ 2: Трейсинг многошаговых цепочек через декоратор @observe
Если ваш бот выполняет несколько шагов (например: 1) семантический поиск в векторной базе Qdrant, 2) форматирование контекста, 3) генерация ответа через LLM), объединить их в единое древовидное дерево трейса позволяет декоратор @observe:
from langfuse.decorators import observe, langfuse_context
from langfuse.openai import openai
@observe(name="retrieve_kb_context")
def retrieve_kb_context(query: str) -> str:
# Здесь происходит поиск по документам в Qdrant / pgvector
return "Самовывоз доступен ежедневно с 10:00 до 21:00 по адресу: Лиговский проспект, 50."
@observe(name="process_support_request")
def handle_support_ticket(user_id: str, question: str):
# Привязываем ID пользователя и теги к текущему трейсу
langfuse_context.update_current_trace(
user_id=user_id,
tags=["e-commerce", "pickup-points"],
session_id=f"session_{user_id}"
)
context = retrieve_kb_context(question)
completion = openai.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": f"Используй контекст базы знаний:\n{context}"},
{"role": "user", "content": question}
]
)
return completion.choices[0].message.content
# Вызов функции
reply = handle_support_ticket("user_9921", "Где забрать заказ?")
print("Результат:", reply)
Способ 3: Интеграция с универсальным шлюзом LiteLLM Proxy
Если в вашей инфраструктуре развернут шлюз моделирования (подробнее в нашем руководстве Универсальный AI-шлюз LiteLLM Proxy в Docker Compose), подключить Langfuse можно одной строчкой в конфигурации config.yaml LiteLLM:
# /opt/litellm/config.yaml
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]
environment_variables:
LANGFUSE_PUBLIC_KEY: "pk-lf-..."
LANGFUSE_SECRET_KEY: "sk-lf-..."
LANGFUSE_HOST: "https://langfuse.yourdomain.ru"
В этом сценарии все запросы ко всем моделям (Ollama, DeepSeek, Anthropic, OpenAI, YandexGPT), проходящие через LiteLLM Proxy, будут мгновенно и без накладных расходов логироваться в Langfuse с точным подсчетом затрат в рублях или долларах.
Способ 4: Подключение в визуальном конструкторе Dify
Для конструктора ИИ-агентов Dify (см. наше руководство Dify на VDS в Docker Compose) интеграция нативна: перейдите в Настройки приложения → Мониторинг → Langfuse, включите тумблер и вставьте Public Key, Secret Key и Host вашего инстанса.
Рекомендуемые VDS-провайдеры
Отказоустойчивые сервера с быстрыми NVMe и каналом до 1 Гбит/с
Timeweb Cloud — Скоростные NVMe VDS
Идеально для микросервисного стека Langfuse: высокочастотные ядра до 3.3 ГГц и быстрый NVMe-диск для мгновенной записи трейсов в ClickHouse.
Selectel — Корпоративная инфраструктура Tier III
Максимальная надежность с размещением в ЦОД уровня Tier III в РФ. Подходит для строгой изоляции персональных данных клиентов и соблюдения 152-ФЗ.
Beget — Простота и отказоустойчивость
Удобная панель управления, автоматические ежедневные бэкапы VDS и поминутная тарификация для тестирования пайплайнов и ИИ-агентов.
6. Резервное копирование PostgreSQL и ClickHouse с алертами в Telegram
База данных Langfuse состоит из двух критически важных слоев: реляционной СУБД PostgreSQL 17 (где хранятся учетные записи, API-ключи, промпты и права проектов) и колоночной ClickHouse 24.8 (где накапливаются исторические трейсы и агрегации). Потеря базы метаданных PostgreSQL сделает невозможным вход в платформу, поэтому ежедневный бэкап обязателен.
Скрипт автоматического бэкапа с отправкой статуса в Telegram
Создаем скрипт /opt/langfuse/backup_langfuse.sh. Скрипт использует безопасный вызов curl --data-urlencode для отправки логов в Telegram-бота без риска сбоя из-за спецсимволов:
#!/usr/bin/env bash
# /opt/langfuse/backup_langfuse.sh
set -euo pipefail
# Конфигурация путей и дат
BACKUP_DIR="/opt/langfuse/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
RETENTION_DAYS=7
# Настройки Telegram-оповещений (замените на свои значения)
TG_BOT_TOKEN="123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"
TG_CHAT_ID="987654321"
# Считываем переменные из .env
if [ -f /opt/langfuse/.env ]; then
# Экспортируем только нужные переменные без выполнения потенциально опасных команд
export POSTGRES_USER=$(grep -E '^POSTGRES_USER=' /opt/langfuse/.env | cut -d '=' -f2-)
export POSTGRES_DB=$(grep -E '^POSTGRES_DB=' /opt/langfuse/.env | cut -d '=' -f2-)
fi
mkdir -p "${BACKUP_DIR}"
send_telegram() {
local msg="$1"
curl -s -X POST "https://api.telegram.org/bot${TG_BOT_TOKEN}/sendMessage" \
--data-urlencode "chat_id=${TG_CHAT_ID}" \
--data-urlencode "text=${msg}" \
--data-urlencode "parse_mode=HTML" > /dev/null || true
}
echo "=== Запуск резервного копирования Langfuse: ${TIMESTAMP} ==="
PG_DUMP_FILE="${BACKUP_DIR}/langfuse_pg_${TIMESTAMP}.sql.gz"
CH_DUMP_FILE="${BACKUP_DIR}/langfuse_clickhouse_schema_${TIMESTAMP}.sql.gz"
# 1. Дамп реляционной базы PostgreSQL 17
if docker exec langfuse_postgres pg_dump -U "${POSTGRES_USER:-langfuse}" "${POSTGRES_DB:-langfuse}" | gzip -9 > "${PG_DUMP_FILE}"; then
PG_SIZE=$(du -h "${PG_DUMP_FILE}" | cut -f1)
echo "PostgreSQL дамп успешно создан: ${PG_SIZE}"
else
send_telegram "🚨 Langfuse Backup FAILED! Ошибка при создании дампа PostgreSQL."
exit 1
fi
# 2. Экспорт структуры таблиц ClickHouse 24.8
if docker exec langfuse_clickhouse clickhouse-client --query "SHOW CREATE DATABASE default" | gzip -9 > "${CH_DUMP_FILE}"; then
echo "ClickHouse схема сохранена."
fi
# 3. Удаление старых бэкапов старше RETENTION_DAYS дней
DELETED_COUNT=$(find "${BACKUP_DIR}" -type f -name "*.gz" -mtime +${RETENTION_DAYS} -delete -print | wc -l)
SUCCESS_MSG="✅ Бэкап Langfuse v4 успешно создан!
📅 Дата: ${TIMESTAMP}
📦 Размер PostgreSQL: ${PG_SIZE}
🧹 Удалено старых копий: ${DELETED_COUNT}"
send_telegram "${SUCCESS_MSG}"
echo "=== Резервное копирование завершено успешно ==="
Выставляем строгие права доступа (только для root) и добавляем задачу в планировщик cron:
# Запрещаем чтение скрипта посторонним пользователям
sudo chmod 700 /opt/langfuse/backup_langfuse.sh
# Добавляем запуск каждую ночь в 03:30
(crontab -l 2>/dev/null; echo "30 3 * * * /opt/langfuse/backup_langfuse.sh >> /var/log/langfuse_backup.log 2>&1") | crontab -
7. Безопасность, лимиты памяти и соответствие 152-ФЗ
При работе с клиентскими приложениями мониторинг запросов неизбежно собирает персональные данные (ФИО, телефоны, адреса доставки, тексты договоров). Использование зарубежных SaaS-сервисов вроде LangSmith или Helicone несет прямые юридические риски нарушения Федерального закона № 152-ФЗ «О персональных данных», требующего локализации баз данных граждан РФ на территории России.
- Локализация VDS: арендуйте серверы с физическим размещением в российских дата-центрах (например, в ЦОД Москвы или Санкт-Петербурга у провайдеров Selectel, Timeweb Cloud или Beget).
- Маскирование данных на клиенте (PII Masking): перед отправкой трейса в Langfuse очищайте текст от номеров банковских карт, СНИЛС и паспортных данных через регулярные выражения в middleware вашего бота.
- Шифрование ключей: переменная
ENCRYPTION_KEYшифрует учетные данные интеграций по стандарту AES-GCM-256 непосредственно в базе данных.
Автоматическая очистка старых трейсов (TTL в ClickHouse)
Через 6–12 месяцев непрерывной работы объем накопленных спанов и трейсов в ClickHouse может превысить десятки гигабайт. Чтобы диск NVMe не переполнился, настройте срок жизни (TTL) для записей в ClickHouse. Например, чтобы автоматически удалять трейсы старше 90 дней, выполните команду в консоли ClickHouse:
# Входим в контейнер ClickHouse
docker exec -it langfuse_clickhouse clickhouse-client --query "
ALTER TABLE default.traces MODIFY TTL timestamp + INTERVAL 90 DAY;
ALTER TABLE default.observations MODIFY TTL start_time + INTERVAL 90 DAY;
"
После применения TTL фоновый процесс слияния ClickHouse будет самостоятельно вычищать устаревшие партиции без просадки производительности и блокировок запросов.