Langflow на сервере: частые ошибки и решения

MAATRIX

Langflow ставится одной командой, а ломается десятком способов: uv не собирает webrtcvad, свежий FastAPI уносит импорт, потоки «исчезают» вместе со сменой рабочего каталога, редактор виснет на «Building» за nginx. Ниже — ошибки, которые чаще всего доходят до поддержки: текст сообщения, причина, команда проверки. Версии и значения по умолчанию сверены с документацией на конец августа 2026 года.

Триаж за пять минут: версия, /health_check и код выхода

Сначала версия: половина советов в сети относится к веткам 1.0–1.4, где переменные окружения вели себя иначе. Актуальный стабильный релиз на PyPI — 1.11.5 от 25 августа 2026 года, требование пакета — Requires-Python: >=3.10,<3.15.

langflow --version
curl -s http://127.0.0.1:7860/api/v1/version
curl -s http://127.0.0.1:7860/health_check
{"status":"ok","chat":"ok","db":"ok"}

Если "db" не ok — проблема в базе, а не в интерфейсе. Тишина на loopback означает, что приложение не поднялось, и конфиги nginx трогать рано.

Дальше вопрос, который экономит час: тот ли порт вы проверяете. В документации у LANGFLOW_PORT прямо сказано, что сервер сам выбирает свободный порт, если указанный занят, — Langflow не падает с «address already in use», а молча переезжает на 7861. Вторая ловушка того же рода: LANGFLOW_HOST по умолчанию localhost, и запрос по внешнему адресу упирается в тишину. Проверка — ss -tlnp | grep -E ':78[0-9]{2}'.

Логов почти нет не потому, что всё хорошо: LANGFLOW_LOG_LEVEL по умолчанию error. Поднимите до info и задайте LANGFLOW_LOG_FILE; на debug в лог уезжают тела запросов с промптами и ключами.

Для контейнера: docker inspect langflow --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}}'.

Не ставится и не стартует: webrtcvad и FastAPI 0.140

Ставьте через uv, а не pip: на этом дереве зависимостей pip уходит в многоминутный перебор версий.

pip install uv && uv venv /opt/langflow/venv
source /opt/langflow/venv/bin/activate
uv pip install langflow

Сборка webrtcvad падает. Пакет тянется зависимостью голосового режима и собирается из исходников:

  × Failed to build `webrtcvad==2.0.10`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

На чистой Ubuntu нет компилятора и заголовков Python: ставьте build-essential python3-dev либо готовое колесо uv pip install webrtcvad-wheels и повторяйте установку.

Импорт падает на get_body_field. Установка прошла, а запуск заканчивается так:

ImportError: cannot import name 'get_body_field' from 'fastapi.dependencies.utils'

Причина не в Langflow: с FastAPI 0.140.5 функция удалена, а Langflow 1.11.0 разрешает диапазон >=0.139.0,<1.0.0 и затягивает несовместимый релиз. Обход — пин uv pip install langflow "fastapi<0.140"; в 1.11.1 и новее резолвер подбирает совместимую пару сам.

No module named 'langflow.__main__' означает, что запускается исполняемый файл от старой установки. По порядку: uv run langflow run, затем python -m langflow run, и только потом uv pip install langflow --pre -U --force-reinstall.

Держите сервис в systemd, а не в screen:

[Service]
User=langflow
WorkingDirectory=/opt/langflow
EnvironmentFile=/etc/langflow/langflow.env
ExecStart=/opt/langflow/venv/bin/langflow run --host 127.0.0.1 --port 7860
Restart=always
RestartSec=5

И помните приоритет настроек, вывернутый относительно привычного: аргумент CLI перебивает .env, а .env перебивает системную переменную окружения. Прописали Environment="LANGFLOW_PORT=8080" в юните, а рядом лежит старый .env с 7860 — победит файл.

База: относительный путь SQLite, PostgreSQL 15 и asyncpg

По умолчанию база — SQLite со строкой sqlite:///./langflow.db, и путь относительный: он разрешается от каталога запуска. Руками из /opt/langflow — одна база, systemd без WorkingDirectory стартовал из / — другая. Отсюда фирменное «после перезапуска пропали все потоки»: они на месте, вы смотрите в другой файл. Абсолютный путь пишется с четырьмя слэшами, а промежуточные каталоги SQLite не создаёт — несуществующая подпапка это падение на старте.

LANGFLOW_DATABASE_URL=sqlite:////var/lib/langflow/langflow.db

Как только пользователей больше одного, SQLite упирается в блокировки записи, и нужен PostgreSQL. Здесь две типовые ошибки.

Версия ниже 15. Langflow пишет понятное сообщение и завершается, а в трассировке видна настоящая причина:

Langflow requires PostgreSQL 15 or higher when using PostgreSQL as the database.

(psycopg.errors.SyntaxError) syntax error at or near "NULLS"
LINE 13:  CONSTRAINT file_name_user_id_key UNIQUE NULLS DISTINCT (nam...

Синтаксис UNIQUE NULLS DISTINCT появился в PostgreSQL 15. На Debian 11 из репозитория приезжает 13 — этого достаточно, чтобы Langflow не стартовал; в Ubuntu 24.04 штатный пакет 16.

Драйвер asyncpg. Инициализация валится так:

sqlalchemy.exc.DBAPIError: (sqlalchemy.dialects.postgresql.asyncpg.Error)
<class 'asyncpg.exceptions.DataError'>: invalid input for query argument $7:
datetime.datetime(2025, 10, 31, 14, 8, 5... (can't subtract offset-naive and offset-aware datetimes)

asyncpg строже относится к часовым поясам и со схемой Langflow несовместим — нужен psycopg2-binary либо psycopg[binary]. В Compose указывайте имя сервиса (postgres), а не localhost: внутри контейнера это сам контейнер Langflow. Установка базы — в разборе PostgreSQL на VPS.

После обновления There's a mismatch between the models and the database. Лечится через uv run langflow migration --fix, но операция разрушительная: режим починки многократно откатывает и заново применяет ревизии схемы, может удалить данные и вообще не сойтись, если в той же базе лежат посторонние таблицы вроде langchain_pg_* от pgvector. Отсюда правило — отдельная база под Langflow и pg_dump перед миграцией.

Секреты и вход: SECRET_KEY, автологин и запертая дверь

LANGFLOW_SECRET_KEY — ключ Fernet: им шифруются глобальные переменные типа Credential (ключи OpenAI и прочих провайдеров) и подписываются JWT. Если переменная не задана, Langflow генерирует ключ сам. Отсюда самая дорогая ошибка эксплуатации: контейнер без постоянного тома получает новый ключ при каждом пересоздании, и старые креденшелы перестают расшифровываться — «после обновления образа Langflow забыл все ключи, хотя я ничего не менял».

python3 -c "from secrets import token_urlsafe; print(f'LANGFLOW_SECRET_KEY={token_urlsafe(32)}')" >> /etc/langflow/langflow.env

Ротация не сводится к правке строки: для неё есть скрипт перешифровки, описанный в разделе Secret Key Rotation файла SECURITY.md проекта.

PermissionError в Docker. Контейнер работает от пользователя с uid=1000, и если том langflow-data создавала старая сборка образа, он инициализировался как root:root:

PermissionError: [Errno 13] Permission denied: '/app/langflow/secret_key'

Пересоздаётся ровно этот том. Не заменяйте это на docker compose down -v — флаг снесёт и том с PostgreSQL:

docker compose down
docker volume ls | grep langflow-data
docker volume rm ИМЯ_ТОМА && docker compose pull && docker compose up -d

Авторизация. LANGFLOW_AUTO_LOGIN=true — однопользовательский режим: интерфейс логинит любого, кто дотянулся до порта, суперпользователем. Официальные образы ставят false, но тогда вы обязаны задать LANGFLOW_SUPERUSER_PASSWORD до первого старта. Имя по умолчанию — langflow (adminuser в примерах документации это именно пример), а легаси-пароль langflow система не примет: старт завершится ошибкой, а не молчаливым созданием слабой учётки. Отсюда ситуация «заперт снаружи», когда на странице входа вместо формы приходит:

An API key must be passed as query or header

Создавать и активировать обычные учётки может только суперпользователь, а LANGFLOW_NEW_USER_IS_ACTIVE по умолчанию False — заведённый аккаунт неактивен, пока его явно не включат. Выход: зайти суперпользователем либо временно перезапустить с LANGFLOW_AUTO_LOGIN=true. Перед публикацией сервиса проверьте ещё два переключателя: LANGFLOW_ENABLE_SIGNUP по умолчанию True, то есть публичная саморегистрация через POST /api/v1/users/ включена, а LANGFLOW_SKIP_AUTH_AUTO_LOGIN=true вовсе отключает проверку API-ключа.

За реверс-прокси: 413, оборванный стриминг, CORS и cookie

Базовая конфигурация, от которой стоит отталкиваться:

location / {
    proxy_pass http://127.0.0.1:7860/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    client_max_body_size 100M;
    proxy_read_timeout 600s;
    proxy_buffering off;
    proxy_request_buffering off;
}

413 при загрузке. Лимит самого Langflow щедрый — LANGFLOW_MAX_FILE_SIZE_UPLOAD по умолчанию 1024 МБ, а client_max_body_size в nginx по умолчанию 1 МБ, и стена почти всегда там. В логе nginx это видно дословно: client intended to send too large body: 5242880 bytes.

Редактор виснет на «Building». События сборки уходят отдельным запросом GET /api/v1/build/<job_id>/events, режим доставки задаёт LANGFLOW_EVENT_DELIVERY (по умолчанию streaming, есть также polling и direct). При включённой буферизации прокси копит поток и вываливает разом в конце — визуально «зависло, а потом внезапно построилось». Если наверху чужой балансировщик, который не переубедить, честный обход — LANGFLOW_EVENT_DELIVERY=polling. И поднимайте proxy_read_timeout вместе с LANGFLOW_WORKER_TIMEOUT (по умолчанию 300 секунд), иначе на длинном агентном прогоне Gunicorn убьёт воркер раньше, чем nginx дождётся ответа.

CORS. По умолчанию LANGFLOW_CORS_ORIGINS=* при LANGFLOW_CORS_ALLOW_CREDENTIALS=True; документация помечает это как опасное, и не зря — комбинация уже дала CVE-2025-34291, захват аккаунта с выходом на выполнение кода, закрытый в 1.7.0. Перечисляйте домены явно.

Cookie. LANGFLOW_ACCESS_SECURE и LANGFLOW_REFRESH_SECURE по умолчанию False ради разработки по HTTP; за HTTPS выставляйте обе в True, для кросс-сайтового размещения ещё и LANGFLOW_REFRESH_SAME_SITE=none. Ограничение, которое настройкой не лечится: LANGFLOW_ACCESS_HTTPONLY по умолчанию False, потому что штатный фронтенд читает access-токен из JavaScript.

429 у всей команды сразу. /login ограничен пятью попытками в минуту с одного IP, ответ — 429 с заголовком Retry-After: 60. За прокси Langflow видит IP прокси у всех, и лимит становится общим на офис. Помогает LANGFLOW_RATE_LIMIT_TRUST_PROXY=true, но включать его можно только если до Langflow нельзя дотянуться в обход прокси: иначе X-Forwarded-For подделывается тривиально. И последнее: Langflow живёт в корне домена, схема location /langflow/ даёт белую страницу и 404 на ассетах — берите поддомен. Общие рецепты — в статье nginx как реверс-прокси.

Память, воркеры и то, что нельзя выставлять наружу

oom=true exit=137 в docker inspect означает, что процесс убило ядро; на хосте то же видно через dmesg -T | grep -i 'killed process'. Требования разработчиков скромные: руководство по развёртыванию за nginx называет минимумом два ядра и 2 ГБ RAM, для Kubernetes — 1 ГБ на бэкенд и 512 МБ на фронтенд. Но это пустой Langflow: Docling и локальные эмбеддинги живут в том же процессе. Если Docling в контейнере падает на документах, в образе не хватает библиотек — apt-get install -y libgl1 libglib2.0-0.

LANGFLOW_WORKERS по умолчанию 1, и попытка поставить больше упирается в осознанный отказ: Langflow не стартует с RuntimeError, если воркеров больше одного, а LANGFLOW_JOB_QUEUE_TYPE остался asyncio. Очередь сборок в памяти своя у каждого процесса, и запрос за событиями может прилететь на чужой воркер; симптом полунастроенной конфигурации — JobQueueNotFoundError в логах.

LANGFLOW_WORKERS=5
LANGFLOW_JOB_QUEUE_TYPE=redis
LANGFLOW_REDIS_QUEUE_URL=redis://127.0.0.1:6379/1
LANGFLOW_GUNICORN_PRELOAD=true
GUNICORN_CMD_ARGS="--max-requests 100 --max-requests-jitter 20"

Три подводных камня разом. Кэш Langflow использует базу Redis 0, очередь заданий — 1; общий индекс даёт смешение ключей. Пароль и TLS поддерживаются только через LANGFLOW_REDIS_QUEUE_URL — раздельные LANGFLOW_REDIS_QUEUE_HOST и LANGFLOW_REDIS_QUEUE_PORT собирают открытое соединение без аутентификации. И LANGFLOW_GUNICORN_PRELOAD работает только на Linux. Блок выше — стартовые значения разработчиков для хоста на 4–8 ГБ; на 12 ГБ они рекомендуют 15 воркеров, на 24 и больше — 30.

Безопасность — не абзац для галочки. Документация формулирует прямо: Langflow это платформа выполнения кода, изоляции между пользователями внутри одного процесса она не обеспечивает, доступ к диску и сети не ограничивает. Отсюда правило — порт 7860 наружу не выставляется никогда: ufw allow 22/tcp && ufw allow 443/tcp && ufw deny 7860/tcp. История уязвимостей это подтверждает: CVE-2025-3248 — неаутентифицированное выполнение кода через /api/v1/validate/code с оценкой 9.8, закрыто в 1.3.0 и попало в каталог активно эксплуатируемых уязвимостей CISA; CVE-2026-33309 — произвольная запись файла с выходом на RCE через API загрузки версии v2, ветки с 1.2.0, исправлено в 1.9.0; CVE-2026-0770 — снова выполнение кода через validate_code(), последняя уязвимая версия 1.7.3. Если сервисом пользуются люди, которым вы не доверяете полностью, включайте ограничители: LANGFLOW_ALLOW_CUSTOM_COMPONENTS=false, LANGFLOW_BLOCK_CODE_INTERPRETER_COMPONENTS=true, LANGFLOW_RESTRICT_LOCAL_FILE_ACCESS=true, LANGFLOW_SSRF_PROTECTION_ENABLED=true.

Какой сервер под Langflow брать в MAATRIX

Langflow — не инференс, а оркестратор: собирает граф, вызывает API провайдеров и ждёт ответа. Нагрузка сетевая и по памяти, частота процессора вторична — если только в тот же процесс вы не затаскиваете локальные эмбеддинги, Docling или разбор больших файлов.

Честный минимум: 2 vCPU, 4 ГБ RAM, 40 ГБ NVMe. Формальный порог документации ниже — два ядра и 2 ГБ, — но на двух гигабайтах вы живёте на SQLite, с одним воркером и без запаса: первый же компонент обработки документов заканчивается exit=137. Четыре гигабайта это Langflow плюс локальный PostgreSQL 16 и место под растущую базу сборок.

Комфортный вариант: 4 vCPU, 8 ГБ RAM, 80 ГБ NVMe. Помещается всё сразу: Langflow с пятью воркерами и прелоадом, PostgreSQL, Redis под очередь заданий, nginx с сертификатом. Команда из нескольких человек работает в редакторе, пока API обслуживает боевые потоки. Под тяжёлые многоагентные сценарии берите 8 vCPU и 16 ГБ — агентные циклы едят память на каждый запрос.

Отдельно про соблазн поставить рядом локальную модель. Модель 7B в квантовании Q4 занимает около 5 ГБ только весами. На нашем стенде (AMD EPYC 9554, 16 vCPU, Ollama 0.33.1) qwen2.5:7b в Q4_K_M выдаёт 7,6 токена в секунду при четырёх потоках — и ровно столько же при восьми: генерация упирается в память, а не в ядра. qwen2.5:3b даёт 34 токена в секунду при 2,2 ГБ занятой памяти. Вывод: Langflow и локальный LLM на одной маленькой машине не уживаются.

Локация — Великобритания, Лондон. Сам Langflow тонкий, значение имеет то, откуда уходят его исходящие запросы. С лондонского адреса OpenAI, Anthropic и Google отвечают штатно, RTT до европейских API — десятки миллисекунд, а соседство с GDPR-периметром удобно для европейских клиентов. США логичнее, когда провайдеры и команда американские. Российская локация как точка входа для пользователей из РФ работает, но зарубежные LLM-API с неё откажут — типовой ответ 403 unsupported_country_region_territory, и перегенерацией ключа это не чинится.

Про установку без прикрас: Langflow в каталоге apps.maatrix.io пока нет. Сервер приезжает чистым, с Ubuntu 24.04 или Debian 12, и вы ставите его по разделам выше — полчаса вместе с nginx и сертификатом. Зато в каталоге есть готовые сборки родственных сервисов — n8n, Dify, LiteLLM, Ollama, Qdrant: они разворачиваются автоматически при заказе, доступы появляются в кабинете. Смежные разборы: Dify на сервере, Flowise на сервере и почему LiteLLM не видит API-ключи.

Оплата — картами российских банков, по СБП, криптовалютой или токеном MAAT; иностранная карта не нужна, хотя сервер стоит в Лондоне. Первым делом после выдачи: закрыть 7860 фаерволом и сгенерировать LANGFLOW_SECRET_KEY.

Частые вопросы