Как запустить ИИ-агента на сервере: Docker, env и production-чеклист

Прототип ИИ-агента можно запускать с ноутбука, но для реальных пользователей нужен серверный контур: секреты в env, отдельный процесс, HTTPS, очередь для долгих задач, логи, healthcheck, резервное отключение tools и понятный rollback. Иначе агент будет зависеть от открытого терминала и ломаться в самый неудобный момент.

Короткая версия: упакуйте агента в Docker, вынесите ключи в .env, закройте публичный доступ к внутренним endpoints, добавьте healthcheck, логи, очередь, лимиты, мониторинг и простой план отката.

Что мы собираем

Соберем базовую production-схему для ИИ-агента. Она подходит для агента на FastAPI, Flask, Node.js, Laravel, LangGraph, LlamaIndex, Flowise-adapter или собственного backend API.

• Приложение агента работает как отдельный service.
• Секреты лежат в .env, а не в коде.
• Внешний мир ходит только через HTTPS и reverse proxy.
• Долгие задачи уходят в очередь.
• Логи и traces помогают понять, что сделал агент.
• Healthcheck показывает, жив ли сервис.
• Rollback позволяет быстро вернуться на предыдущую версию.

Шаг 1. Разделите dev и production

Не переносите на сервер папку “как есть” с локального ноутбука. Production должен иметь отдельные переменные окружения, отдельные ключи, отдельную базу и отдельные лимиты.

• Dev: тестовые ключи, тестовые webhooks, маленькие лимиты, отладочные логи.
• Production: боевые ключи, HTTPS, ограниченные права, rate limits, мониторинг.
• Staging: промежуточный контур, где можно прогнать сценарии перед релизом.

Если staging пока нет, хотя бы заведите отдельного тестового бота, тестовую CRM-воронку и отдельный индекс RAG.

Шаг 2. Соберите список секретов

ИИ-агент почти всегда работает с внешними сервисами. Все секреты должны быть описаны и храниться вне репозитория.

• LLM API key.
• Telegram bot token.
• CRM webhook или OAuth credentials.
• Database password.
• Vector database key.
• LangSmith или другой tracing key.
• Webhook secret для входящих событий.
• Admin token для внутренних endpoints.

Создайте .env.example без настоящих значений, чтобы было понятно, какие переменные нужны для запуска.

Шаг 3. Сделайте минимальный health endpoint

Healthcheck нужен, чтобы понять, живо ли приложение. Он не должен вызывать модель и тратить деньги. На первом уровне достаточно проверить, что web server отвечает и приложение может загрузить конфиг.

from fastapi import FastAPI

app = FastAPI()


@app.get("/health")
async def health():
    return {"status": "ok"}

Отдельно можно сделать deep healthcheck для внутренних проверок: база, очередь, vector database, CRM API. Но публичный health endpoint лучше держать легким и безопасным.

Шаг 4. Упакуйте агента в Docker

Docker помогает запускать приложение одинаково на локальной машине и сервере. Ниже пример для Python/FastAPI агента. Если у вас Node.js или PHP, смысл тот же: зависимости, рабочая папка, команда запуска.

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Не кладите .env внутрь image. Image должен быть одинаковым для окружений, а секреты должны подключаться при запуске.

Шаг 5. Опишите docker-compose.yml

Docker Compose удобен, когда агенту нужны несколько сервисов: web, worker, Redis, Postgres, Qdrant. Для старта можно поднять только web, а очередь добавить позже.

services:
  agent-api:
    build: .
    env_file:
      - .env
    ports:
      - "127.0.0.1:8000:8000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"]
      interval: 30s
      timeout: 5s
      retries: 3

Порт привязан к 127.0.0.1, чтобы сервис не торчал наружу напрямую. Снаружи его должен открывать Nginx или другой reverse proxy через HTTPS.

Шаг 6. Настройте reverse proxy и HTTPS

Публичный endpoint агента должен быть доступен по HTTPS. Обычно схема такая: Nginx принимает запросы на домене, проверяет TLS и проксирует на локальный порт контейнера.

server {
    server_name agent.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }
}

Для webhook Telegram, CRM и внешних интеграций HTTPS обязателен не только для безопасности, но и для нормальной совместимости с платформами.

Шаг 7. Добавьте очередь для долгих задач

Если агент отвечает мгновенно, можно начать без очереди. Но как только появляются RAG, CRM, файлы, несколько tools или длинная генерация, лучше разделить быстрый прием запроса и долгую обработку.

• Web endpoint принимает сообщение и быстро возвращает “задача принята”.
• Worker выполняет agent run.
• Результат отправляется в Telegram, чат-виджет, CRM или сохраняется в базе.
• Ошибки worker попадают в лог и retry-политику.

Очередь особенно важна для webhooks: внешний сервис не должен ждать, пока LLM думает 40 секунд.

Шаг 8. Настройте логи и traces

Логи должны помогать отлаживать агента, но не превращаться в склад персональных данных. Разделите технические логи, traces и бизнес-события.

• Request id или run id для каждого запуска.
• Время ответа и стоимость.
• Названия вызванных tools.
• Ошибки API и retry.
• ID найденных документов RAG, но не обязательно полный текст.
• Решение о handoff или отказе.
• Маскирование токенов, телефонов и других чувствительных данных.

Для агентных систем особенно полезен tracing: он показывает цепочку prompt -> retrieval -> tool -> answer.

Шаг 9. Ограничьте публичные endpoints

Production-агент почти всегда имеет публичные точки входа: чат-виджет, Telegram webhook, CRM webhook, API для сайта. У каждой точки должны быть ограничения.

• Rate limit по IP, user_id, session_id или chat_id.
• Проверка webhook secret.
• Максимальный размер тела запроса.
• Allowed origins для browser-запросов.
• Отдельные permissions для admin endpoints.
• Запрет прямого доступа к внутренним tool endpoints.

Не делайте endpoint вроде /run-tool, куда можно передать любое имя инструмента и аргументы. Это слишком опасно.

Шаг 10. Добавьте feature flags

Feature flags помогают отключить рискованную часть агента без деплоя. Например, если CRM-интеграция начала ошибаться, можно временно запретить create_deal, но оставить ответы по базе знаний.

• ENABLE_CRM_TOOLS=false
• ENABLE_LONG_TERM_MEMORY=false
• ENABLE_TELEGRAM_WEBHOOK=true
• ENABLE_RAG=true
• MAX_DAILY_LLM_COST=3000

Даже простые env-флаги уже дают больше контроля, чем “остановить весь сервис”.

Шаг 11. Подготовьте deploy и rollback

Перед первым запуском напишите короткую процедуру релиза. Она нужна не для бюрократии, а чтобы в момент ошибки не вспоминать команды наугад.

git pull
docker compose build
docker compose up -d
docker compose ps
docker compose logs -f --tail=100 agent-api

Rollback может быть простым: вернуться на предыдущий git tag, пересобрать контейнер и перезапустить сервис. Главное - заранее знать, какая версия была рабочей.

Шаг 12. Проверьте production-чеклист

Перед тем как отдавать агента пользователям, прогоните короткую приемку на живом контуре.

• /health отвечает.
• HTTPS работает.
• Секреты не лежат в репозитории и не видны во frontend.
• Webhook secret проверяется.
• Rate limit включен.
• Очередь обрабатывает долгие задачи.
• Логи пишутся и не содержат токены.
• RAG индекс доступен.
• CRM и Telegram tools работают на тестовых данных.
• Есть команда быстрого отключения опасных tools.
• Есть rollback-план.

Если Docker пока не подходит

Для маленького прототипа можно запустить агента как systemd service. Это проще, но требует аккуратно настроить рабочую папку, env и restart policy.

[Unit]
Description=AI Agent API
After=network.target

[Service]
WorkingDirectory=/opt/ai-agent
EnvironmentFile=/opt/ai-agent/.env
ExecStart=/opt/ai-agent/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Docker обычно удобнее для повторяемости, но systemd нормален, если проект маленький и вы хорошо контролируете сервер.

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

Можно ли запускать ИИ-агента на обычном VPS?

Да, если агент использует облачную LLM и не запускает большие локальные модели. Для локальных LLM уже важны CPU, RAM, GPU и скорость диска. Начинайте с небольшого VPS, но следите за latency, очередью и лимитами.

Нужно ли сразу делать Kubernetes?

Обычно нет. Для первого production-запуска достаточно Docker Compose, reverse proxy, env, logs, healthcheck и backup. Kubernetes имеет смысл, когда есть несколько сервисов, команда эксплуатации, автоскейлинг и понятная нагрузка.

Где хранить API-ключи?

Минимально - в .env на сервере с правильными правами доступа. Лучше - в секретах CI/CD или secret manager. Никогда не храните ключи в frontend, репозитории, публичных логах и примерах кода.

Что лучше мониторить в первую очередь?

Доступность /health, количество ошибок, latency, стоимость LLM, длину очереди, частоту tool failures, RAG retrieval failures и safety incidents. Для бизнеса также важны handoff rate и успешность целевых сценариев.

Как понять, что агент готов к production?

Он должен проходить контрольные evals, иметь логи и traces, корректно падать без потери данных, не раскрывать секреты, не выполнять опасные tools без правил и иметь понятный способ отката на предыдущую версию.