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

Инструкция для администратора Linux, который ставит платформу на сервер своей компании и видит её впервые. Образы платформы и языковые модели приходят в пакете поставщика — на сервере без доступа в интернет установку ведут из этого пакета. После страницы вы сможете:

• проверить целостность поставки и распаковать её;
• убедиться до установки, что сервер подходит;
• загрузить образы и модели из пакета поставщика без интернета;
• установить платформу с именем и открыть чат, панель и конструктор с рабочего места;
• снять предупреждение браузера о сертификате: добавить сертификат установки в доверенные рабочих мест;
• войти первым администратором, проверить блокировку и разблокировку учётной записи;
• понять, что делать, если загрузчик или установщик сообщили об ошибке.

Что нужно заранее

• Сервер, отвечающий требованиям из раздела Требования к площадке, со средствами контейнеризации (Docker и Docker Compose v2) из штатного репозитория операционной системы.
• Права администратора на сервере: установку запускает обычный пользователь с правами sudo. Если на вашем сервере для sudo нужен пароль, установщик сам его спросит (шаг 2 раздела 6).
• Поставка от поставщика — три файла: архив платформы mnemax-distro-1.1.4.tar.gz, файл контрольной суммы mnemax-distro-1.1.4.tar.gz.sha256 рядом с ним и, если на сервере нет интернета, пакет образов и моделей mnemax-bundle.tar.gz со своим файлом mnemax-bundle.tar.gz.sha256.
• Лицензионный файл, полученный от поставщика (шаг 4).
• Терминал на сервере. Веб-интерфейс на этапе установки не нужен.

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

1. Проверьте целостность поставки и распакуйте её

1. Скопируйте все переданные файлы на сервер, например в домашний каталог.

2. Из каталога, где лежит архив, проверьте целостность:

sha256sum -c mnemax-distro-1.1.4.tar.gz.sha256

Ответ mnemax-distro-1.1.4.tar.gz: OK — архив цел. На системе с русской локалью то же сообщение печатается словом ЦЕЛ. Любой другой ответ — архив повреждён при переносе: перекопируйте файлы и повторите проверку. Ставить платформу из повреждённого архива нельзя.

1. Создайте каталог установки и распакуйте архив в него:

mkdir -p ~/mnemax
tar -xzf mnemax-distro-1.1.4.tar.gz -C ~/mnemax

В каталоге ~/mnemax появятся файлы платформы: install.sh, каталоги tools, config и другие. Архив не создаёт вложенного каталога — всё распаковывается прямо в указанный.

1. Перейдите в каталог установки — все дальнейшие команды выполняются из него:

cd ~/mnemax

2. Проверьте сервер до установки

1. Сверьте сервер с разделом Требования к площадке и проверьте процессор — платформа работает только на уровне инструкций x86-64-v3 (AVX2):

grep -c avx2 /proc/cpuinfo

Число больше нуля — процессор подходит. Ноль — не подходит: в настройках виртуальной машины поставьте гостю процессор host либо уровня x86-64-v3 и повторите проверку.

1. Запустите проверку готовности — она ничего не меняет на сервере и не запускает установку:

bash install.sh --check-only

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

== Проверка готовности поставки пройдена ==
Версия: 1.1.4
Ресурсы: <N> ядер / <N> ГБ ОЗУ / <N> ГБ диска
Оверлеи безопасности на месте; исходники служб найдены (пути названы в журнале <имя файла>).
Установка не запускалась (--check-only).

Если ресурса не хватает, установка печатает строку ОСТАНОВ с именем ресурса и минимальным значением — вернитесь к Требованиям к площадке. Если средств контейнеризации на сервере ещё нет, проверка предупредит об этом, но пройдёт: ВНИМАНИЕ: docker не найден… — установите Docker из штатного репозитория операционной системы до шага 5.

Про РЕД ОС

Установка проверена на Astra Linux SE 1.8. На РЕД ОС 8 требования те же, проверка установки на живой машине выполняется отдельно — при заказе согласуйте её с поставщиком.

3. Задайте имя установки

Имя — это адрес, по которому сотрудники откроют платформу с рабочих мест:

• чат — https://<имя>;
• панель администрирования — https://admin.<имя>;

• конструктор процессов — https://admin.<имя>/flows.

• Возьмите имя из домена вашей организации, например mnemax.company.ru. В имени допустимы латинские буквы, цифры, точка и дефис, и в нём должна быть хотя бы одна точка. Не берите имя, заканчивающееся на .local: оно зарезервировано для служебного протокола mDNS и по нему рабочие места платформу не найдут. Имя не может быть адресом вида 10.0.0.5.

• Имя задаётся один раз, при первой установке, и потом не меняется: без имени доступен только чат, панель и конструктор не откроются, и для них потребуется установка заново на чистом каталоге.

• Добавьте записи в DNS вашей организации либо в файл hosts на сервере и на рабочих местах:

<адрес сервера> <имя> admin.<имя>

Например: 192.0.2.10 mnemax.company.ru admin.mnemax.company.ru — это адрес из служебного диапазона для примеров; возьмите адрес сервера в вашей сети. Файл hosts лежит в /etc/hosts в Linux и macOS и в C:\Windows\System32\drivers\etc\hosts в Windows; править его нужно с правами администратора. Если вы создали DNS-записи, hosts править не нужно.

4. Положите лицензионный файл

Комплектация — Базовая, Расширенная или Корпоративная (см. Комплектации) — определяется лицензионным файлом. Положите полученный от поставщика файл в каталог установки:

mkdir -p config/license
cp <путь к файлу лицензии> config/license/license.json

Установка проверит подпись файла и сама включит оплаченный состав. Без лицензионного файла на шаге «Граница комплектаций» установка спросит Продолжить с базовой комплектацией? [y/N] — продолжение ставит Базовую комплектацию: затем разберитесь с лицензией и запустите установку заново.

5. Загрузите образы и модели из пакета поставщика

На сервере без интернета образы и модели ставятся из пакета mnemax-bundle.tar.gz — одного архива, в котором образы платформы и языковые модели.

1. Создайте в каталоге установки подкаталог dist и скопируйте туда пакет и его файл контрольной суммы:

mkdir -p dist
cp <путь к пакету>/mnemax-bundle.tar.gz dist/
cp <путь к пакету>/mnemax-bundle.tar.gz.sha256 dist/

1. Запустите загрузчик:

bash tools/load-offline.sh

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

Набор найден:
  каталог набора: <путь>
  образы стека, есть; языковые модели, есть; модели поиска, есть

и в конце:

== Итог загрузки ==
  Журнал загрузки (сырой вывод загрузки образов, сверка с описью и отпечатки):
    <путь к файлу журнала>
  Работа завершена: образы и модели на месте.

  Что сделать дальше, запустить установку (имя машины задайте на первом запуске:
  по нему открывается и чат, и панель; без имени, только чат):
    MNEMAX_HOST=<имя> bash install.sh --offline

1. Если на сервере есть интернет, этот шаг пропускается: установщик сам заберёт образы и модель, а после проверки моделей (раздел 9) контур закрывается.

6. Установите платформу

1. Запустите установку с вашим именем:

MNEMAX_HOST=<имя> bash install.sh --offline

например MNEMAX_HOST=mnemax.company.ru bash install.sh --offline. Установка идёт этапами, каждый печатается в терминал отдельной строкой: проверки окружения, подготовка файла настроек, генерация конфигураций, старт служб, «Граница комплектаций», смоук-тесты, гейт моделей.

1. На этапе «Внешний исполнитель применения изменений панели» установщик ставит служебный юнит средствами системы. Если для sudo на вашем сервере нужен пароль, установщик в этот момент спросит его — это единственное, что установка спрашивает сама. Если sudo настроен без пароля, вопрос не появится: установка печатает, что юнит установлен, включён и запущен, и переходит к следующему этапу.

2. В конце установка печатает итог:

== Готово ==
Чат:            https://<имя>
Панель:         https://admin.<имя>
Сборка сценариев:    https://admin.<имя>/flows
Строка для DNS или файла hosts рабочего места и сервера:
  <адрес сервера> <имя> admin.<имя>
Первый администратор: demo, пароль: в .env (DEMO_USER_PASSWORD).
При первом входе система потребует сменить пароль.

Сравните напечатанную строку для hosts с той, что вы раздали на шаге 3, — адреса должны совпадать. Каждая строка OK в смоук-тестах — проверенное обещание; если мелькнула строка ПРОВЕРИТЬ — задержитесь и загляните в раздел «Типовые ошибки».

1. Если у сервера на этапе установки есть интернет, установку запускают без флага:

MNEMAX_HOST=<имя> bash install.sh

Дальнейшие шаги одинаковы.

7. Сертификат установки и рабочие места

Чат, панель и конструктор работают по защищённому соединению. Сертификат для них установка выпускает собственным удостоверяющим центром платформы: сертификат центра лежит на сервере в файле ~/mnemax/secrets/ca.crt. Пока рабочее место не знает этот центр, браузер при первом открытии предупреждает, что подключение не защищено, — центру нет причины доверять по умолчанию.

Это ожидаемое поведение закрытой установки, а не поломка: платформа работает внутри вашей сети, и публичный центр подтверждения к ней не обращается. Предупреждение снимается один раз на каждом рабочем месте:

1. Скопируйте файл ~/mnemax/secrets/ca.crt с сервера на рабочее место, например:

scp <пользователь>@<адрес сервера>:/home/<пользователь>/mnemax/secrets/ca.crt .

1. Добавьте сертификат в доверенные:
2. Windows: дважды щёлкните по файлу — «Установить сертификат» — «Локальный компьютер» — хранилище «Доверенные корневые центры сертификации». Закройте и заново откройте браузер: предупреждение пропадёт.
3. Linux, Firefox: «Настройки» — «Приватность и защита» — «Просмотр сертификатов» — в диспетчере на вкладке «Центры сертификации» «Импортировать», выберите ca.crt и отметьте доверие при идентификации веб-сайтов.
4. Linux и macOS, Chrome: импортируйте ca.crt в системное хранилище сертификатов: в Linux — командой sudo cp ca.crt /usr/local/share/ca-certificates/mnemax.crt && sudo update-ca-certificates, в macOS — приложением «Связка ключей», пункт «Импорт элементов».
5. Откройте чат по адресу https://<имя> — страница входа открывается без предупреждения.

Режим сертификата задаётся при установке значением TLS_MODE в файле .env. Их три:

• TLS_MODE=selfsigned — режим по умолчанию: центр установки, всё описанное выше. Повторный запуск установки центр не перевыпускает — доверие рабочих мест сохраняется.
• TLS_MODE=letsencrypt — сертификат публичного удостоверяющего центра. Подходит, когда имя установки — домен с записью, указывающей на сервер, и серверу на время установки доступен интернет. Рабочим местам ничего добавлять не нужно.
• Сертификат вашего удостоверяющего центра: при любом другом значении TLS_MODE установщик ничего не генерирует и ждёт готовые файлы secrets/ca.crt, secrets/server.crt и secrets/server.key в каталоге установки — положите их туда до запуска.

8. Войдите и смените пароль

1. Откройте чат по адресу https://<имя> с рабочего места. Появится страница «Добро пожаловать»: кнопка «Войти через Мнемакс SSO» и форма с полями почты и пароля. Форма нужна только для служебного входа, сотрудникам пользоваться ею не нужно. Регистрации в чате нет: впервые войдите демонстрационной учётной записью — так, как в шаге 2.

2. Войдите демонстрационной учётной записью: имя demo, пароль — значение DEMO_USER_PASSWORD из файла .env в каталоге установки. Скопируйте его в буфер обмена своего рабочего места одной командой — пароль нигде не печатается:

ssh <пользователь>@<адрес сервера> "grep -m1 '^DEMO_USER_PASSWORD=' ~/mnemax/.env | cut -d= -f2- | tr -d '\n'" | pbcopy

На Linux вместо pbcopy в конце той же команды поставьте xclip -selection clipboard, на Windows — clip. Вставьте пароль в поле пароля. При первом входе система потребует сменить пароль — задайте собственный и запомните его. Демонстрационная учётная запись нужна только для первого входа: работайте под своей учётной записью из шагов 4–5.

1. Убедитесь, что с рабочего места открываются панель — https://admin.<имя> — и конструктор — https://admin.<имя>/flows. Если браузер не находит имя, вернитесь к шагу 3: запись для admin.<имя> не дошла до этого рабочего места.

2. Создайте постоянного администратора. Войдите в панель и в меню слева откройте «Пользователи и права»: заполните форму «Добавить пользователя» и нажмите «Создать пользователя». Панель покажет уведомление «Пользователь «<логин>» создан» и временный пароль — панель показывает пароль один раз и нигде не хранит, запишите его и передайте этому пользователю.

3. Назначьте этому пользователю права администратора: в его строке списка выберите роль «Администратор — Полный доступ: пользователи и права, состав системы, модели и наблюдение» и нажмите «Назначить роль». Панель откроет страницу «Подтвердите личность» — назначение прав требует повторного входа. Нажмите «Войти и подтвердить», войдите снова — панель завершит действие и покажет «Роль назначена».

4. Проверьте блокировку на учётной записи из шага 4: в её строке нажмите «Заблокировать». Панель покажет «Вход для «<логин>» заблокирован». Новый вход отклоняется сразу, а открытые окна перестают пускать после того, как истечёт срок их сессии. Попробуйте войти под этой учётной записью в другом окне браузера — вход отклоняется, панель не открывается. Вернитесь в своё окно, нажмите «Разблокировать» и пройдите подтверждение личности — статус станет «активен». Свою учётную запись заблокировать нельзя: кнопка блокировки есть только в чужих строках.

При включённом входе по корпоративному каталогу учётные записи не создаются вручную: сотрудник входит своей доменной учётной записью, и она появляется при первом входе. Права назначаются так же, на экране «Пользователи и права».

9. Проверьте работоспособность

1. На сервере, из каталога установки:

bash tools/smoke.sh

Проверка опрашивает чат, шлюз моделей и службу входа и печатает по строке на каждую:

Чат:       OK
Шлюз:      OK (живость изнутри)
Вход:      OK

Все три строки должны показать OK. Первая может ждать до трёх минут, пока поднимается маршрут, — об этом проверка говорит сама.

1. Прогоните гейт моделей — контрольную проверку того, что каждая модель отвечает:

bash tools/verify-models.sh --smoke

Ожидаемый результат:

ГЕЙТ ПРОЙДЕН (ЗЕЛЁНЫЙ)
Все проверки завершены успешно.
Можно отключать интернет и переводить машину в закрытый контур.

1. Откройте чат с рабочего места, войдите и задайте простой вопрос, например: «Составь одно предложение о том, что ты работаешь внутри нашей компании». Убедитесь, что пришёл ответ. Модель работает на вашем сервере.

Первый ответ чата после установки.

После зелёного гейта из шага 2 контур можно закрывать: платформа работает автономно. Выход в интернет закрывайте на межсетевом экране: если вместо этого удалить на сервере шлюз по умолчанию, вместе с ним пропадёт маршрут к сети рабочих мест — службы будут работать, а сервер перестанет отвечать с рабочего места из другой сети. Маршрут к сети рабочих мест не удаляйте.

Обслуживание

• Резервная копия. В этой версии экрана копий в панели нет. Копии создаёт Инженер внедрения по согласованной с вами процедуре: обговорите расписание и место хранения копий при передаче поставки.

• Восстановление из копии — не поддерживается в этой версии. Штатной процедуры восстановления поставка пока не содержит: восстановление выполняет Инженер внедрения по отдельному запросу.

• Обновление до новой версии — не поддерживается в этой версии. Обновление передаётся поставщиком вместе с версией поставки, у которой появится своя процедура.

• Удаление — не поддерживается в этой версии. Останов платформы на усмотрение администратора, штатной команды удаления поставка не содержит.

Установка на усиленное ядро Astra Linux

На усиленном ядре Astra Linux SE 1.8 штатный режим контейнеризации без прав суперпользователя не поддерживается, поэтому установка идёт в привилегированном режиме — это рекомендация вендора операционной системы, а не отступление от требований безопасности. Проверка образов на уязвимости выполняется штатным средством самой операционной системы. Все шаги инструкции те же.

Типовые ошибки

Каждая остановка печатает сообщение с причиной. Частые случаи:

Сообщение на экране	Причина	Что делать
ОСТАНОВ: Процессор не поддерживает уровень x86-64-v3, не хватает флагов: <список флагов>.	процессор или гостевая система виртуальной машины не поддерживает набор инструкций x86-64-v3 (AVX2) — образы платформы на нём не стартуют	в настройках виртуальной машины поставьте гостю процессор host либо уровня x86-64-v3 — Proxmox по умолчанию предлагает x86-64-v2-AES, он не подходит; после этого запустите установку снова. На физическом сервере нужен процессор Intel начиная с 2014 года либо AMD EPYC
ОСТАНОВ: Процессор недостаточен, N логических ядер (минимум 4).	серверу не хватает ядер	увеличьте число ядер виртуальной машины или выберите хост с четырьмя и более ядрами, затем запустите установку снова
ОСТАНОВ: ОЗУ недостаточно, N ГБ (минимум 24 ГБ для поставки).	памяти меньше минимума	увеличьте объём памяти виртуальной машины или выберите другой хост и запустите установку снова; при объёме меньше 30 ГБ установка печатает предупреждение, что под одновременной работой генерации и поиска по документам машина может уходить в своп
ОСТАНОВ: Диск недостаточен, N ГБ свободно (минимум 50 ГБ).	некуда класть образы и модели	освободите или расширьте диск и запустите снова
ОСТАНОВ: имя установки '<имя>' не годится.	в имени есть недопустимые знаки, нет точки либо имя похоже на адрес вида 10.0.0.5	возьмите имя из домена вашей организации (латинские буквы, цифры, точка, дефис) и запустите установку снова
docker не найден, ставьте из штатного репозитория ОС	на сервере нет средств контейнеризации	установите их из репозитория операционной системы и повторите запуск
ОСТАНОВ: рядом с пакетом нет файла контрольной суммы mnemax-bundle.tar.gz.sha256.	в dist скопирован пакет без файла суммы	скопируйте mnemax-bundle.tar.gz.sha256 рядом с пакетом и запустите bash tools/load-offline.sh снова
ОСТАНОВ: контрольная сумма пакета не совпала.	пакет повреждён или подменён при переносе	не продолжайте: получите пакет у поставщика заново, скопируйте оба файла в dist и повторите загрузку
ОСТАНОВ: в офлайн-наборе не найдено ни одного ожидаемого артефакта.	пакет лежит не в dist внутри каталога установки	скопируйте пакет и файл суммы в dist каталога установки и повторите bash tools/load-offline.sh
ОСТАНОВ: образ N из M не совпал с описью набора.	пакет неполон или подменён: образ не загрузился либо его содержимое не то, что в описи	имена образов и расхождений установщик пишет в журнал загрузки рядом с набором; получите пакет у поставщика заново и повторите загрузку; повторная установка не нужна — запустите bash tools/load-offline.sh, затем bash install.sh --offline
ОСТАНОВ: файлы весов языковых моделей не прошли сверку по контрольным суммам:	архив моделей повреждён или подменён	не продолжайте: получите пакет моделей заново и повторите загрузку
ГЕЙТ НЕ ПРОЙДЕН (КРАСНЫЙ) — модель не прошла проверку	модель не отвечает	не отключайте интернет; перезапустите bash tools/verify-models.sh --smoke, при повторе обратитесь к поставщику
Внимание: служба лицензий не ответила (код выхода: N). … Продолжить с базовой комплектацией? [y/N]	служба лицензий не отвечает	проверьте, что лицензионный файл лежит в config/license/license.json и не повреждён; продолжение по y ставит Базовую комплектацию — затем разберитесь с лицензией и запустите установку снова
ПРОВЕРИТЬ в строке смоук-теста	маршрут экрана не успел подняться	дайте до трёх минут и повторите bash tools/smoke.sh; при повторе сохраните вывод установки и обратитесь к поставщику
Чат по имени не открывается, хотя установка завершилась	имя не раздалось до рабочего места или сервера	проверьте DNS-записи и строки в файлах hosts по шагу 3; на сервере сверьте их с итоговой печатью установки
Сервер не отвечает с рабочего места ни по 443, ни на ping, хотя установка завершилась	рабочее место в другой сети, у сервера нет маршрута к сети рабочих мест	добавьте маршрут к сети рабочих мест на межсетевом экране либо разместите рабочее место в сети сервера; выход в интернет закрывайте на межсетевом экране — маршрут к сети рабочих мест при этом не трогайте
Браузер предупреждает, что подключение не защищено	рабочее место ещё не доверяет удостоверяющему центру установки	добавьте файл ~/mnemax/secrets/ca.crt в доверенные рабочих мест — раздел 7
Чат открывается, а панель — нет	установка прошла без имени: доступен только чат	панель требует имени. Для установки с именем нужен чистый каталог: перенесите настройки и запустите MNEMAX_HOST=<имя> bash install.sh на новом каталоге

После установки

• Как внедряется платформа — установка, пилот, штатная работа.
• Руководство администратора — повседневное управление платформой.
• Требования к площадке — параметры сервера.
• Вопросы и ответы — типовые вопросы при знакомстве с платформой.