Инструкция по установке

Программный комплекс «RAGu MAX» — корпоративная платформа оркестрации ИИ-агентов

Правообладатель: ООО «Ресетлаб» Версия ПО: 1.0.0 Форма поставки: дистрибутивный комплект с готовым Docker-образом (сборка исходного кода на стороне пользователя не требуется)

Настоящая инструкция описывает развертывание ПО «RAGu MAX» на сервере заказчика из готового Docker-образа. Все программные зависимости приложения (интерпретатор Python, библиотеки, модели распознавания документов Docling, OCR-движок Tesseract с русским языковым пакетом) уже включены в образ; доступ к внешним сетям в процессе эксплуатации приложением не требуется.

1. Состав дистрибутивного комплекта

Файл / каталог	Назначение
`ragu-max-1.0.0.tar.gz`	Docker-образ приложения (бэкенд, API-шлюз, сервер инструментов)
`docker-compose.yml`	Манифест развертывания всех сервисов
`.env.example`	Шаблон файла конфигурации
`alembic.ini`, `alembic/`	Скрипты миграции базы данных
`keycloak/realms/ragu-realm.json`	Realm Keycloak для автоимпорта при первом запуске
`keycloak/themes/`, `keycloak/providers/`	Тема оформления с русской локалью, провайдеры VK ID / Яндекс ID
`frontend/dist/`	Статическая сборка веб-интерфейса
`nginx/ragu.conf`	Конфигурация фронтального веб-сервера (nginx)
`ИНСТРУКЦИЯ_ПО_УСТАНОВКЕ.md`	Настоящий документ

2. Требования к инфраструктуре

2.1. Аппаратные требования

Параметр	Минимум	Рекомендуется
CPU	4 ядра (x86_64)	8 ядер
ОЗУ	8 ГБ	16 ГБ
Диск	30 ГБ свободно	100 ГБ (с учетом документов и артефактов)

Важное уведомление

Архитектура образа должна соответствовать архитектуре сервера. Стандартная поставка — linux/amd64; сборка под linux/arm64 предоставляется по запросу.

2.2. Программные требования

ОС семейства Linux (Debian/Ubuntu, RHEL/производные, Astra Linux, РЕД ОС и др.) или macOS;
ядро Linux версии 4.15 и новее (рекомендуется 5.x/6.x; требуется поддержка overlay2 и cgroups v2);
Docker Engine версии 24 или новее;
Docker Compose v2 (плагин docker compose).

Проверка:

uname -r                  # версия ядра >= 4.15
docker --version          # Docker version 24.x или выше
docker compose version    # Docker Compose version v2.x

Если Docker не установлен (пример для Debian/Ubuntu):

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # перелогиниться после выполнения

2.3. Сетевые требования

Наружу публикуется только порт 80/TCP (фронтальный nginx; при настройке TLS — 443/TCP);
все остальные сервисы работают во внутренней сети Docker и снаружи недоступны;
серверу требуется имя (FQDN) или IP-адрес, по которому пользователи будут открывать портал. Далее в документе используется переменная RAGU_HOST — укажите в ней имя сервера, например ragu.company.local.

2.4. Развертывание в закрытом контуре

Инфраструктурные образы (postgres, valkey, minio, keycloak, nginx) по умолчанию загружаются из публичных реестров. Если сервер не имеет доступа в интернет, загрузите образы заранее на машине с доступом и перенесите их вместе с комплектом:

# На машине с доступом в интернет
docker pull postgres:16-alpine valkey/valkey:8-alpine pgsty/minio:latest \
            quay.io/keycloak/keycloak:26.0 nginx:1.27-alpine
docker save -o ragu-infra-images.tar postgres:16-alpine valkey/valkey:8-alpine \
            pgsty/minio:latest quay.io/keycloak/keycloak:26.0 nginx:1.27-alpine

# На целевом сервере
docker load -i ragu-infra-images.tar

3. Установка

3.1. Распаковка комплекта

mkdir -p /opt/ragu
tar -xzf ragu-max-1.0.0-distrib.tar.gz -C /opt/ragu
cd /opt/ragu/ragu-max-1.0.0

3.2. Загрузка образа приложения

docker load -i ragu-max-1.0.0.tar.gz
docker images | grep ragu-max     # должен появиться образ ragu-max:1.0.0

3.3. Конфигурация

Создайте файл .env из шаблона:

cp .env.example .env

Заполните .env. Обязательные параметры:

Переменная	Описание
`RAGU_HOST`	FQDN или IP сервера, видимый пользователям (например, `ragu.company.local`). Используется в OIDC-redirect и адресе портала
`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`	Учетные данные и имя БД PostgreSQL
`MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`	Учетные данные MinIO (S3-хранилище)
`KEYCLOAK_ADMIN`, `KEYCLOAK_ADMIN_PASSWORD`	Администратор Keycloak (master realm)
`RAGU_CREDENTIAL_ENCRYPTION_KEY`	Ключ шифрования учетных данных пользователей в БД (Fernet, 32 байта base64)
`RAGU_SERVICE_TOKEN`	Токен межсервисной аутентификации (произвольная стойкая строка)
`RAGU_KEYCLOAK_CLIENT_SECRET`	Секрет OIDC-клиента `ragu`. При использовании поставляемого realm — `ragu-client-secret` (рекомендуется заменить, см. п. 5.3)

Сгенерировать ключи можно так (команды выполняются в контейнере — отдельный Python на сервере не нужен):

# Ключ шифрования (Fernet)
docker compose run --rm --no-deps web python -c \
  "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Сервисный токен
openssl rand -hex 32

Опциональные параметры:

Переменная	Описание
`VK_CLIENT_ID`, `VK_CLIENT_SECRET`	Вход через VK ID (регистрация на id.vk.com)
`YANDEX_CLIENT_ID`, `YANDEX_CLIENT_SECRET`	Вход через Яндекс ID (регистрация на oauth.yandex.ru)
`RAGU_DEFAULT_LLM_CONFIGS`	JSON-массив OpenAI-совместимых LLM-эндпоинтов; первый элемент — основная модель, остальные — резервные. Пустое значение отключает функции, требующие LLM
`RAGU_MCP_SSRF_ALLOWED_HOSTS`	Список разрешенных внутренних хостов для инструмента `fetch_url` (через запятую)

Уведомление

Подключение к платформе RAGFlow/RAGu BASE настраивается не через переменные окружения, а в интерфейсе администратора: авторы приложений вводят API-токены через Credential Broker, токены хранятся в БД в зашифрованном виде (см. раздел 6).

Пример RAGU_DEFAULT_LLM_CONFIGS:

[{"label":"Corporate LLM","base_url":"https://llm.company.local/v1","api_key":"sk-...","model":"qwen2.5-72b-instruct","max_tokens":4096,"max_retries":2}]

3.4. Файл docker-compose.yml

Поставляемый docker-compose.yml уже подготовлен для развертывания из образа. Для справки — его логическая структура:

Сервис	Образ	Назначение
`nginx`	`nginx:1.27-alpine`	Единственная точка входа: отдает веб-интерфейс, проксирует `/api/v1/` → `web:8000`, `/realms/`, `/admin/`, `/resources/` → `keycloak:80`
`web`	`ragu-max:1.0.0`	API-шлюз, аутентификация, репозиторий, чат
`mcp-server`	`ragu-max:1.0.0` (команда `python -m ragu.mcp_server.server`)	Сервер инструментов (файловые операции, навыки)
`postgres`	`postgres:16-alpine`	Реляционная БД (метаданные, пользователи, исполнения)
`redis`	`valkey/valkey:8-alpine`	Сессии, очереди, шина событий (Redis-совместимый Valkey, BSD-лицензия)
`minio` + `minio-init`	`pgsty/minio`	Объектное S3-хранилище; `minio-init` создает бакеты при первом запуске
`keycloak`	`quay.io/keycloak/keycloak:26.0`	OIDC-провайдер идентификации; импортирует realm `ragu`

Переменные приложения подставляются в манифест из .env (${...}), поэтому редактировать сам docker-compose.yml, как правило, не требуется.

3.5. Запуск инфраструктурных сервисов

docker compose up -d postgres redis minio minio-init keycloak
docker compose ps    # дождитесь статуса healthy у postgres, redis, minio, keycloak

Первый запуск Keycloak занимает до 1–2 минут (сборка + импорт realm). Готовность определяется по статусу healthy в docker compose ps — сервис проверяет доступность realms/ragu изнутри автоматически.

3.6. Инициализация базы данных

Примените миграции (скрипты из комплекта монтируются в контейнер на время выполнения):

docker compose run --rm \
  --volume ./alembic.ini:/app/alembic.ini:ro \
  --volume ./alembic:/app/alembic:ro \
  web alembic upgrade head

Успешное завершение выводит строки вида Running upgrade -> <revision>, .... Команду следует выполнять при первом запуске и при каждом обновлении версии ПО.

3.7. Запуск приложения

docker compose up -d
docker compose ps

Все сервисы должны перейти в состояние running/healthy. Портал доступен по адресу http://<RAGU_HOST>/.

4. Проверка установки

Состояние контейнеров: docker compose ps — у всех сервисов статус healthy или running.
Бэкенд: docker compose exec web python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8000/docs').status)" → 200. Для mcp-server доступна проверка http://localhost:8081/health аналогичной командой.
OIDC: curl -fsS http://<RAGU_HOST>/realms/ragu/.well-known/openid-configuration → JSON с полем issuer.
Вход: откройте http://<RAGU_HOST>/ в браузере — произойдет перенаправление на страницу входа Keycloak (русская локаль). Войдите под тестовой учетной записью (см. п. 5.4) — после входа должен открыться интерфейс портала.

5. Настройка после установки

5.1. Административная консоль Keycloak

Консоль доступна по адресу http://<RAGU_HOST>/admin (учетные данные — KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD из .env).

5.2. Redirect URI для боевого адреса

Поставляемый realm содержит redirect URI для локальной разработки. Добавьте адрес сервера:

Консоль → realm ragu → Clients → ragu.
В Valid redirect URIs добавьте http://<RAGU_HOST>/api/v1/auth/callback.
В Web origins добавьте http://<RAGU_HOST>.
Save.

5.3. Смена секретов и паролей по умолчанию

Перед вводом в эксплуатацию:

смените пароль администратора Keycloak (Users в realm master, либо переменная KEYCLOAK_ADMIN_PASSWORD + пересоздание сервиса);
перегенерируйте секрет клиента ragu (Clients → ragu → Credentials → Regenerate) и обновите RAGU_KEYCLOAK_CLIENT_SECRET в .env, затем docker compose up -d web;
задайте стойкие POSTGRES_PASSWORD и MINIO_ROOT_PASSWORD до первого запуска (смена после инициализации требует отдельных процедур).

5.4. Учетные записи и группы

Поставляемый realm содержит демонстрационных пользователей и группы:

Пользователь	Пароль	Группа
`testuser`	`testpass123`	—
`contribuser`	`contribpass123`	`/engineering`
`adminuser`	`adminpass123`	`/finance`

Группы: finance, engineering, legal. Членство в группах используется Платформой для разграничения доступа к приложениям и LLM-эндпоинтам.

Предупреждение

В боевой среде удалите демонстрационных пользователей либо смените им пароли, создайте собственные группы (Groups → Create group) и назначьте пользователям членство (Groups → <группа> → Members → Add member).

5.5. Доступ к приложениям по группам

В веб-интерфейсе: Настройки → Приложения → Доступ по группам — выдача/отзыв доступа групп Keycloak к отдельным приложениям.

6. Внешние зависимости

Зависимость	Обязательность	Примечание
OpenAI-совместимый LLM-эндпоинт	Для функций планирования и диалога	Задается через `RAGU_DEFAULT_LLM_CONFIGS`; далее управляется из БД через интерфейс администратора
RAGFlow/RAGu BASE	Для выполнения агентов/чатов/баз знаний	Внешняя платформа; достаточно доступного по сети экземпляра — API-токены авторов приложений вводятся через Credential Broker в интерфейсе администратора. Без него портал работает, но выполнение ИИ-агентов недоступно
VK ID / Яндекс ID	Опционально	Дополнительные способы входа; провайдеры уже включены в образ Keycloak, нужны только client_id/secret

7. Обновление версии

# 1. Загрузить новый образ
docker load -i ragu-max-<новая_версия>.tar.gz

# 2. Обновить тег образа в docker-compose.yml (или файл поставки уже содержит новый тег)

# 3. Применить миграции БД
docker compose run --rm \
  --volume ./alembic.ini:/app/alembic.ini:ro \
  --volume ./alembic:/app/alembic:ro \
  web alembic upgrade head

# 4. Перезапустить
docker compose up -d

8. Остановка, удаление, резервное копирование

docker compose down          # остановка; данные в томах сохраняются
docker compose down -v       # остановка + УДАЛЕНИЕ всех данных (безвозвратно)

Осторожность

Команда docker compose down -v безвозвратно удаляет все данные в томах (база данных, файлы в MinIO, настройки Keycloak). Перед выполнением убедитесь, что резервная копия снята.

Резервное копирование:

# База данных
docker compose exec postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup.sql

# Объектное хранилище и данные Keycloak — тома Docker:
docker run --rm -v ragu_minio_data:/data -v $PWD:/backup alpine \
  tar -czf /backup/minio_data.tar.gz -C /data .

9. Диагностика неполадок

Симптом	Возможная причина и действие
`web` в статусе `unhealthy`	`docker compose logs web`. Чаще всего: не применены миграции (п. 3.6) или неверный `RAGU_DATABASE_URL`
Бесконечный редирект при входе / «Invalid redirect uri»	Не добавлен боевой redirect URI в клиент `ragu` (п. 5.2); `RAGU_HOST` в `.env` не совпадает с адресом в браузере
Ошибка «Invalid or expired OIDC state»	Адрес `http://<RAGU_HOST>/realms/ragu` недоступен из браузера пользователя; истекло время состояния OIDC (10 мин) — повторите вход
После входа перебрасывает на `localhost`	Не задан `RAGU_HOST` / `RAGU_POST_LOGIN_REDIRECT_URL`; исправьте `.env`, `docker compose up -d web`
502 Bad Gateway от nginx	`web` еще не поднялся (`docker compose ps`); проверьте `docker compose logs web`
Не работает вход через VK/Яндекс	Не заполнены `VK_CLIENT_ID`/`YANDEX_CLIENT_ID` в `.env`; пересоздайте сервис `keycloak`
Ошибки загрузки файлов	Проверьте `MINIO_*` в `.env` и `docker compose logs minio`; бакеты создаются автоматически сервисом `minio-init`
Не распознаются изображения в документах	OCR встроен в образ (`RAGU_OCR_ENGINE=tesseract_cli`, языки `rus,eng`); проверьте `RAGU_OCR_ENABLED=true`
Логи сервиса	`docker compose logs -f <сервис>` (`web`, `mcp-server`, `postgres`, `keycloak`, `minio`, `nginx`)

10. Технические замечания

TLS. В производственной среде включите HTTPS на фронтальном nginx (сертификат + listen 443 ssl), обновите RAGU_HOST, KC_HOSTNAME и redirect URI на https://.
SSE. Потоковая передача событий исполнения (Server-Sent Events) требует отключенной буферизации на прокси — уже учтено в поставляемом nginx/ragu.conf (proxy_buffering off для /api/v1/).
Масштабирование. Сервис web не хранит состояние и может масштабироваться горизонтально за балансировщиком; сессии хранятся в Redis.
Изолированный контур. Приложение не выполняет внешних вызовов в runtime: модели Docling встроены в образ (HF_HUB_OFFLINE=1), автообновления и телеметрия отсутствуют.