ИИ и автоматизация 15 мин чтения 2026-11-02

Центр мониторинга и отладки LLM-приложений: развертывание Langfuse на VDS в Docker Compose для трейсинга промптов, аудита расходов токенов и оценки качества ответов

Практическое руководство по развертыванию платформы LLM Observability Langfuse v4 на собственном VDS в Docker Compose. Разбираем архитектуру с ClickHouse, PostgreSQL 17, Redis и MinIO, настройку Nginx с SSL, сквозной трейсинг промптов, контроль расходов токенов в OpenAI/Ollama/DeepSeek и обеспечение приватности по 152-ФЗ.

Инженерная редакция SysKit Проверено инженерами SysKit.ru

1. Зачем нужен LLM Observability и как устроен Langfuse v4

Каждый разработчик или владелец онлайн-бизнеса, запускающий в работу искусственный интеллект — будь то бот клиентской поддержки в Telegram, агент автогенерации товарных карточек в интернет-магазине или RAG-пайплайн по корпоративным регламентам, — неизбежно сталкивается с феноменом «черного ящика». Обычное текстовое логирование в терминал или файлы app.log мгновенно захлебывается: многостраничные JSON-ответы, вложенные ветвления вызовов функций (Function Calling), скрытые ретраи сетевых шлюзов и хаотичный расход токенов превращают отладку в мучение.

В продакшене бизнес платит реальные деньги за каждый сгенерированный токен. Когда пользователи начинают жаловаться: «Бот зависает на 15 секунд», «Ассистент галлюцинирует и выдумывает несуществующие скидки» или счета за OpenAI API / облачные шлюзы неожиданно вырастают вчетверо, без специализированной платформы телеметрии локализовать причину невозможно. Именно эту задачу решает класс систем LLM Observability, безоговорочным open-source лидером среди которых является Langfuse (более 12 000 звёзд на GitHub).

Что даёт внедрение Langfuse в инфраструктуру:
  • Сквозной трейсинг цепочек (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.

Конфигурация
4 vCPU 3.3 ГГц • 8 ГБ RAM • 80 ГБ NVMe • Трафик без лимита
Премиум Tier III
🔷

Selectel — Корпоративная инфраструктура Tier III

Максимальная надежность с размещением в ЦОД уровня Tier III в РФ. Подходит для строгой изоляции персональных данных клиентов и соблюдения 152-ФЗ.

Конфигурация
4 vCPU • 8 ГБ RAM • 100 ГБ NVMe • Канал 100 Мбит/с
Быстрый старт
🟠

Beget — Простота и отказоустойчивость

Удобная панель управления, автоматические ежедневные бэкапы VDS и поминутная тарификация для тестирования пайплайнов и ИИ-агентов.

Конфигурация
4 vCPU • 8 ГБ RAM • 90 ГБ NVMe • Выделенный IPv4

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-ФЗ «О персональных данных», требующего локализации баз данных граждан РФ на территории России.

Рекомендации SysKit по соблюдению 152-ФЗ при развертывании Langfuse:
  • Локализация 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 будет самостоятельно вычищать устаревшие партиции без просадки производительности и блокировок запросов.

Инструменты SysKit по теме статьи

Бесплатные утилиты для проверки и диагностики вашего сервера

Вопросы и ответы (FAQ)

Популярные вопросы вебмастеров и сисадминов по данной теме

Замедляет ли Langfuse работу продакшен-приложений и ботов при отправке трейсов?
Практически нет. Официальный SDK Langfuse (как для Python, так и для TypeScript/Node.js) работает в полностью неблокирующем асинхронном режиме. Вызовы и спаны помещаются в локальную память процесса (background queue) и отправляются на сервер батчами (раз в 1–2 секунды или по достижении лимита записей) в отдельном фоновом потоке. Если VDS с Langfuse кратковременно недоступен, основное приложение не зависает и продолжает отвечать пользователям без задержек.
Можно ли использовать Langfuse для мониторинга локальных LLM (Ollama, vLLM) без выхода в интернет?
Да, именно в этом одно из ключевых преимуществ self-hosted Langfuse. Платформа работает полностью автономно внутри вашего VDS или защищенного контура локальной сети. Вы можете подключить трейсинг локальных моделей в Ollama, llama.cpp или vLLM, и ни один промпт, токен или ответ не покинут периметр вашего сервера. Для работы веб-интерфейса и приема трейсов внешний доступ в глобальный интернет не требуется.
Что делать при ошибке ClickHouse Code: 241 (MEMORY_LIMIT_EXCEEDED)?
Колоночная СУБД ClickHouse оптимизирована под предельную скорость аналитических агрегаций и при построении тяжелых дашбордов в веб-панели Langfuse может запрашивать пиковый объем оперативной памяти. Если на VDS с 8 ГБ RAM возникает эта ошибка, убедитесь, что на сервере активирован Swap-файл размером минимум 4–8 ГБ. Также в файле .env можно ограничить аппетит СУБД директивой CLICKHOUSE_MAX_MEMORY_USAGE=4000000000 (4 ГБ) или передавать параметр max_memory_usage в настройках ClickHouse.
Как обновлять Langfuse v4 на новые минорные релизы в Docker Compose?
Процесс обновления полностью автоматизирован благодаря встроенным механизмам миграций схем в PostgreSQL и ClickHouse. Для обновления достаточно перейти в каталог /opt/langfuse и выполнить: docker compose pull (скачает свежие образы тега :4), затем docker compose down и docker compose up -d. Контейнеры веб-сервера и воркера самостоятельно применят миграции при запуске. Перед любым обновлением обязательно сделайте резервную копию базы данных скриптом backup_langfuse.sh.

Читайте также в блоге SysKit

Смежные руководства и полезные технические статьи