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

Подробное руководство для администратора: как развернуть платформу на своём сервере — в российском облаке, в собственном ЦОД или на ноутбуке для пилота. После установки у вас будет витрина маркетплейса, конструктор агентов, личный кабинет организаций и работающие контуры AI-агентов на порту 8080.

Оглавление:

1. Что устанавливается
2. Требования к системе
3. Быстрая установка (одна команда)
4. Установка вручную
5. Структура каталогов
6. Переменные окружения
7. Проверка установки
8. Продакшн: systemd и reverse proxy с TLS
9. Обновление
10. Резервное копирование и восстановление
11. Безопасность хоста
12. Мониторинг и журналы
13. Устранение неполадок
14. Итоговый чек-лист

1. Что устанавливается

Один процесс, один порт, без обязательной СУБД и без брокера сообщений: платформа укладывается в ванильный Linux с Python. Внешние API (1С, Битрикс24, Директ и др.) по умолчанию отвечают демо-транспортом; боевые токены подключаются из кабинета без переустановки.

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

Минимум для пилота (до ~10 организаций и 50 задач в день):

• Linux x86_64 (проверено на Ubuntu 22.04/24.04, Debian 12, Astra Linux);
• Python 3.10 или новее (проверено на 3.13), pip;
• 2 ядра CPU, 2 ГБ RAM, 5 ГБ диска;
• доступ в интернет при установке (загрузка fastapi, uvicorn,

cryptography из репозитория пакетов) — далее платформа работает без интернета.

Рекомендации для продакшна: 4 ядра, 8 ГБ RAM, SSD; отдельный диск или том под deployments/ (состояние контуров); доменное имя и сертификат TLS.

Не требуется: PostgreSQL (файловое хранилище), Docker (опционально), отдельный сервер Redis/очередей.

3. Быстрая установка (одна команда)

# 1. Положите проект в постоянный каталог (архив или git-клон)
cd /opt
# вариант А: архив
#   tar -xzf mindroot-ru.tar.gz && mv mindroot-ru-*/ mindroot-ru
# вариант Б: git
git clone https://github.com/runvnc/mindroot mindroot-ru   # ядро
# ... положите поверх файлы проекта mindroot.ru (server/, web/, scripts/, ...)

cd mindroot-ru

# 2. Запустите — скрипт сам достроит зависимости и соберёт реестр
bash start.sh

Что делает start.sh:

1. проверяет fastapi и uvicorn, при отсутствии ставит requirements.txt;
2. доставляет cryptography (AES-256-GCM для секретов организаций; без

него включается встроенный HMAC-фолбэк — но в продакшене ставьте AES);

1. собирает каталог агентов (scripts/build_agents.py) и реестр

(scripts/build_registry.py) из кода плагинов;

1. запускает uvicorn на 0.0.0.0:${PORT:-8080}.

После старта откройте:

• http://SERVER:8080/ — маркетплейс;
• http://SERVER:8080/builder.html — конструктор;
• http://SERVER:8080/login.html — вход и регистрация;
• http://SERVER:8080/docs/ — документация;
• http://SERVER:8080/api/swagger — Swagger REST API.

4. Установка вручную

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

cd mindroot-ru

# зависимости
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt          # fastapi, uvicorn, cryptography

# сборка реестра (обязательна: web и API читают data/registry.json)
python3 scripts/build_agents.py
python3 scripts/build_registry.py

# запуск (из корня проекта — так находит server/ и плагины)
python3 -m uvicorn server.app:app --host 0.0.0.0 --port 8080

Проверка контракта плагинов перед первым запуском в новой версии:

python3 scripts/check_plugins.py
# ожидаемо: «Всего плагинов: 10, команд: 76, сервисов: 14» и 0 замечаний

5. Структура каталогов

mindroot-ru/
├── start.sh              # штатный вход: зависимости + сборка + сервер
├── requirements.txt      # fastapi, uvicorn, cryptography
├── server/               # FastAPI-приложение, рантайм, аккаунты, провижининг
├── web/                  # витрина, конструктор, кабинет, документация (HTML/CSS/JS)
├── plugins/              # 10 плагинов-коннекторов (mod.py + plugin_info.json)
├── agents/               # готовые агенты (agent.json)
├── scripts/              # сборка, автотесты, демо-сценарий
├── docs/                 # INSTALL.md, USER_GUIDE.md, STRATEGY.md, DEMO.md
├── data/                 # ← состояние (создаётся автоматически)
│   ├── registry.json     #   собранный реестр плагинов и агентов
│   └── accounts/         #   организации, пользователи, сессии, API-ключи,
│                         #   keys/*.key (ключи шифрования, 0600),
│                         #   org-audit.jsonl (журнал действий)
└── deployments/          # ← состояние контуров (создаётся автоматически)
    ├── index.json        #   витрина контуров
    └── dep-<...>/        #   файлы контура, agent.json, state/ (аудит,
                          #   счётчики, pending, secrets.enc)

data/ и deployments/ — единственные каталоги, которые нельзя терять и которые нужно брать в резервную копию (см. §10). Всё остальное восстанавливается из поставки.

6. Переменные окружения

Пример:

PORT=8080 MARKETPLACE_ADMIN_KEY="$(openssl rand -hex 24)" bash start.sh

Файлы админки создаются в data/admin/ (права 0600): settings.json — глобальные настройки, payments.json — журнал платежей.

Больше настроек не требуется: тарифы, роли и политики — данные организаций, а не конфигурация сервера.

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

Выполните по порядку, всё должно отвечать без ошибок:

BASE=http://localhost:8080

# страницы витрины и документации
for p in / /builder.html /login.html /org.html /docs/ /api/swagger; do
  printf '%-18s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' $BASE$p)"
done

# публичный API без токена
curl -s $BASE/api/registry | head -c 200          # реестр плагинов
curl -s $BASE/api/pricing | head -c 200           # тарифы
curl -s $BASE/api/auth/demo-accounts | head -c 200 # демо-аккаунты

# закрытые маршруты обязаны отвечать 401
curl -s -o /dev/null -w '%{http_code}\n' $BASE/api/contours   # ожидаемо 401

Автоматические проверки (сервер должен быть запущен):

# 1. Контракты плагинов — работает и без сервера
python3 scripts/check_plugins.py
# ожидаемо: 10 плагинов, 76 команд, 14 сервисов, 0 замечаний

# 2. Мультиарендность: изоляция, роли, квоты, ключи, журнал, админка — 79 проверок
python3 scripts/check_multitenancy.py
# ожидаемо: «Итог: 79 из 79 проверок пройдено»
# (созданную для теста организацию скрипт удаляет за собой)

# 3. Сквозной сценарий «четыре организации» → журнал в docs/DEMO.md
python3 scripts/demo_scenario.py > docs/DEMO.md
# ожидаемо: код возврата 0; в журнале — Ромашка, Сфера, ТехноПарк, Северный Ветер

Если все три команды зелёные — установка завершена.

8. Продакшн: systemd и reverse proxy с TLS

8.1. Пользователь и каталог

sudo useradd -r -s /usr/sbin/nologin mindroot
sudo mkdir -p /opt/mindroot-ru && sudo chown -R mindroot: /opt/mindroot-ru
# файлы проекта уже лежат в /opt/mindroot-ru

8.2. systemd

/etc/systemd/system/mindroot.service:

[Unit]
Description=MindRoot.ru — платформа AI-агентов
After=network.target

[Service]
Type=simple
User=mindroot
WorkingDirectory=/opt/mindroot-ru
ExecStart=/usr/bin/bash start.sh
Restart=on-failure
RestartSec=5
# порт и ключ администратора маркетплейса
Environment=PORT=8080
Environment=MARKETPLACE_ADMIN_KEY=ЗАМЕНИТЕ_НА_СЛУЧАЙНУЮ_СТРОКУ
# жёсткие лимиты — защита от раскочегаривания одного контура
MemoryMax=4G
TasksMax=256
NoNewPrivileges=true
ProtectSystem=full
ReadWritePaths=/opt/mindroot-ru/data /opt/mindroot-ru/deployments

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mindroot
systemctl status mindroot      # должен быть active (running)
journalctl -u mindroot -f      # логи

8.3. nginx + TLS

Витрина отдаёт HTML, JSON и файлы пакетов; особых требований нет, кроме размера тела для выгрузок и корректного /c/ (панели контуров).

/etc/nginx/sites-available/mindroot:

server {
    listen 443 ssl http2;
    server_name mindroot.example.ru;

    ssl_certificate     /etc/letsencrypt/live/mindroot.example.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mindroot.example.ru/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 32m;          # выгрузки пакетов и агенты

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 120s;
    }
}
server {                                # только redirect на HTTPS
    listen 80;
    server_name mindroot.example.ru;
    return 301 https://$host$request_uri;
}

sudo ln -s /etc/nginx/sites-available/mindroot /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Важно: не публикуйте витрину в открытый интернет без TLS — сессии и API-ключи иначе передаются открытым текстом. Если публичного домена нет, закройте порт файрволом и откройте его только по IP своей сети/VPN:

sudo ufw allow from 10.0.0.0/8 to any port 8080 proto tcp   # пример

При работе за reverse proxy внешний адрес указывайте в ссылках клиентам (https://mindroot.example.ru/), внутренний 127.0.0.1:8080 наружу не выходит.

9. Обновление

Переустановка не нужна. Обновление — это «накат» новых файлов поверх установленной копии и перезапуск. В поставке нет каталогов data/ и deployments/ (они создаются при первом запуске), поэтому при копировании состояние — организации, ключи шифрования, контуры, аудит — не затрагивается. Миграции схемы тоже не требуется: форматы файлов совместимы в пределах этапа.

9.1. Порядок действий

# 1. Остановить сервер
sudo systemctl stop mindroot
# (если запускали вручную: Ctrl+C в терминале, где работает start.sh)

# 2. Бэкап состояния — 1 минута, спасает всё (см. также §10)
cd /opt/mindroot-ru
sudo -u mindroot tar -czf /var/backups/mindroot-state-$(date +%F-%H%M).tar.gz \
  data deployments

# 3. Положить новые файлы ПОВЕРХ установки
#    Вариант А — архив обновления:
tar -xzf mindroot-ru-<новая-версия>.tar.gz
cp -a mindroot-ru-*/. /opt/mindroot-ru/        # data/ и deployments/ в архиве нет — их не задеть
#    Вариант Б — git:
# git -C /opt/mindroot-ru pull   (или распаковка поверх, если репозиторий не использовался)

# 4. Перезапустить — стартовый скрипт сам достроит зависимости
sudo systemctl start mindroot
# (вручную: bash start.sh)

9.2. Что происходит при перезапуске (start.sh)

1. проверяет fastapi/uvicorn/cryptography и докладывает недостающее;
2. пересобирает каталог агентов и реестр из кода плагинов

(build_agents.py → build_registry.py) — правки в plugins/ и agents/ подхватываются сами;

1. поднимает сервер; фоновые данные (data/admin/settings.json и

payments.json, если их ещё не было) создаются при первом обращении.

Правило: правки web/ и docs/ подхватываются без перезапуска (отдаются с диска), но если в версии есть изменения в server/ или scripts/ — перезапуск обязателен. Удобнее просто перезапускать всегда: дешевле ищет, чем гадает.

9.3. Проверка после обновления

BASE=http://localhost:8080
curl -s -o /dev/null -w '%{http_code}\n' $BASE/            # 200
curl -s -o /dev/null -w '%{http_code}\n' $BASE/admin.html  # 200
python3 scripts/check_plugins.py                           # 0 замечаний
python3 scripts/check_multitenancy.py                      # 79 из 79
python3 scripts/demo_scenario.py > docs/DEMO.md            # exit 0 (по желанию)

9.4. Откат

Если новая версия не устраивает: остановить, вернуть файлы проекта из прежней копии (server/, web/, scripts/, docs/ — состояние не трогать), перезапустить. Бэкап состояния из шага 2 нужен только при катастрофе с данными: распаковать его вместо data/ и deployments/ (порядок — §10), заодно проверить права 0600/0700.

9.5. Когда всё же нужна чистая установка

Только если хотите стенд с нуля (потерять все организации и контуры):

sudo systemctl stop mindroot
cd /opt/mindroot-ru
sudo mv data data.old && sudo mv deployments deployments.old   # не удалять сразу — страховка
bash start.sh    # свежие каталоги создадутся сами, демо-организации стендa поднимутся заново

10. Резервное копирование и восстановление

Что копировать: data/ (организации, пользователи, сессии, API-ключи, ключи шифрования, журнал) и deployments/ (контуры, их аудит и секреты). Всё остальное — восстановимая поставка.

# инкрементальная копия (ключей шифрования — тоже, они необходимы для чтения backups)
sudo -u mindroot tar --ignore-failed-read -czf \
  /var/backups/mindroot-$(date +%F-%H%M).tar.gz data deployments

Рекомендации:

• копируйте сразу копию data/accounts/keys/ в отдельное зашифрованное

хранилище: без ключа организации файлы state/secrets.enc нечитаемы;

• храните копии минимум за 30 дней (срок жизни сессий — 7 дней, но аудит

контуров дольше);

• делайте копию перед каждым обновлением (§9).

Восстановление:

sudo systemctl stop mindroot
cd /opt/mindroot-ru
sudo -u mindroot rm -rf data deployments
sudo -u mindroot tar -xzf /var/backups/mindroot-2026-10-08-1200.tar.gz
sudo systemctl start mindroot

После восстановления проверьте права: каталог ключей 0700, файлы *.key, sessions.json — 0600 (их так и создаёт платформа; при распаковке от root — chown -R mindroot: data deployments).

10а. Админка платформы

После установки доступна страница администрирования — обзор всего, что происходит на платформе, и глобальные настройки:

• Адрес: https://ваш-домен/admin.html; вход — ключом

MARKETPLACE_ADMIN_KEY (см. §6). Сессия администратора живёт 12 часов.

• Что видно: сводка (организации, пользователи, контуры, задачи,

API-ключи, оплаченные суммы); организации с тарифами, сотрудниками, контурами и последним входом; пользователи с ролями и историей входов; активность контуров (задачи, команды, записи за сутки, последнее событие); журнал событий всех организаций; очередь оплат и история платежей.

• Что можно: сменить тариф любой организации, отметить оплату

(заготовка биллинга до подключения эквайринга), изменить глобальные настройки — стартовый тариф регистраций, открытие/закрытие регистрации, режим обслуживания (витрина и админка живы, прикладные API отвечают 503).

• Чего админка не делует: внутри организаций ничего не меняет —

контуры, сотрудники и секреты принадлежат владельцам организаций.

Автотест проверяет админку целиком (раздел 8, команды входа и настроек).

11. Безопасность хоста

• Ключи организаций лежат в data/accounts/keys/*.key (права 0600) —

приравняйте их к своим приватным ключам; попадание копии в бэкап вне защищённого хранилища недопустимо.

• Файрвол: наружу только 80/443 (или VPN), 8080 — localhost/внутренняя сеть.
• Обновления ОС — штатно, платформа от системных патчей не зависит.
• MARKETPLACE_ADMIN_KEY — длинная случайная строка, хранится только в

unit-файле, не в репозитории.

• Резервные копии шифруйте на стороне хранилища (ВКС, gpg, корп.

хранилище).

• Включение двухфакторного входа и SSO — этап roadmap; на текущей версии

держите платформу за корпоративным VPN либо ограничивайте доступ по IP.

• Отказ в обработке данных за пределами РФ на стороне платформы не

требуется: контуры и файлы живут на вашем хосте; внешние API не вызываются, пока в настройках контура не указан боевой токен.

12. Мониторинг и журналы

Простой health-check для мониторинга:

curl -sf http://127.0.0.1:8080/api/pricing > /dev/null || echo DOWN

13. Устранение неполадок

14. Итоговый чек-лист

• ☐ Файлы лежат в постоянном каталоге (/opt/mindroot-ru), владелец —

пользователь сервиса.

• ☐ bash start.sh поднимает сервер, curl на / даёт 200.
• ☐ python3 scripts/check_plugins.py — 0 замечаний.
• ☐ python3 scripts/check_multitenancy.py — 79/79.
• ☐ python3 scripts/demo_scenario.py > docs/DEMO.md — код 0.
• ☐ systemd-юнит включён, рестарты автоматические.
• ☐ nginx перед сервисом, TLS 1.2/1.3, 8080 не светится наружу.
• ☐ MARKETPLACE_ADMIN_KEY задан (иначе админка работает на ключе

по умолчанию mindroot-admin).

• ☐ Бэкап data/ + deployments/ со шифрованием, ключи — отдельно.
• ☐ Права: data/accounts/keys/ — 0700, файлы ключей и сессий — 0600.

Смежные документы: docs/USER_GUIDE.md — руководство для клиентов; docs/STRATEGY.md — архитектура и roadmap; docs/DEMO.md — журнал приёмочного прогона; web/docs/ — документация в витрине.