1. Назначение и комплект поставки

Инструкция предназначена администратору, который устанавливает ArhiPlanning и предоставляет пользователям доступ к платформе. Она описывает подготовку среды, локальный запуск, требования к серверному размещению, контроль установленного экземпляра и восстановление данных.

Для работы с уже установленным экземпляром пользователю достаточно браузера, адреса и выданной учётной записи. Установка на рабочем месте пользователя в этом случае не требуется.

Часть поставки	Назначение
api и engine	Веб-сервис, хранение данных, управление расчётами и расчётные компоненты.
web/dist и examples	Собранный интерфейс и три учебных набора данных.
Install.ps1 и Start.ps1	Установка зависимостей и запуск локального экземпляра на Windows.
scripts и README.md	Управление учётными записями, резервное копирование и параметры запуска.
requirements.lock.txt и MANIFEST.sha256	Зафиксированные версии Python-зависимостей и контрольные суммы файлов.
deploy/Platform.Dockerfile	Описание сборки контейнера для серверного размещения.

Программная среда

Локальный порядок установки проверен с Python 3.13 x64, Windows и WSL Ubuntu. Серверный контейнер использует Python 3.13 и Linux. Зависимости Python устанавливаются из requirements.lock.txt; для готового интерфейса отдельная установка Node.js не требуется.

Для балансового планирования и расчёта доступных объёмов необходим ArhiPlex с действующей лицензией. ArhiPlex является отдельно поставляемым расчётным ядром; это требование к среде ArhiPlanning. В контрольных расчётах использована версия ядра 2.6.1.242987. Бинарные файлы ядра и лицензионные реквизиты предоставляются администратору отдельно.

Требуются права записи в каталог данных, свободное место для входных файлов и результатов, а при установке зависимостей — доступ к настроенному репозиторию Python-пакетов. Объём памяти и вычислительные ресурсы выбираются по размеру задач; универсальный минимальный объём для всех моделей не устанавливается.

2. Установка и запуск на Windows

Подготовка каталога и зависимостей

Распакуйте ArhiPlanning_1.0.0_20260914.zip в отдельный каталог. Сверьте SHA-256 архива с сопровождающим файлом контрольной суммы. Все дальнейшие команды выполняйте в PowerShell из корня распакованной поставки. Не размещайте новую установку поверх рабочего каталога с данными.

python --version
./Install.ps1

Команда python должна запускать Python 3.13 x64. Install.ps1 создаёт каталог .venv и устанавливает зависимости из lock-файла. Продолжайте после сообщения об успешном завершении установки. Если корпоративная политика блокирует выполнение PowerShell-сценариев, администратор должен разрешить запуск утверждённых сценариев установленным в организации способом.

Подключение расчётного ядра

В WSL Ubuntu установите предоставленный дистрибутив ArhiPlex согласно его инструкции и подключите действующую лицензию. По умолчанию ArhiPlanning запускает /opt/arhiplex/bin/arhiplex. Библиотеки ядра должны быть доступны через LD_LIBRARY_PATH в окружении bash -lic. Лицензионный config.toml настраивается для этой установки ядра.

Если имена дистрибутива WSL или путь отличаются от стандартных, задайте параметры перед запуском платформы. Ниже показаны значения по умолчанию.

$env:AP_WSL_DISTRO='Ubuntu'
$env:AP_ARHIPLEX_BIN='/opt/arhiplex/bin/arhiplex'

Первый запуск и вход

./Start.ps1

Откройте http://127.0.0.1:8097. При первом запуске создаётся уникальная учётная запись admin; логин и пароль записываются в runtime/LOCAL_ACCESS.txt. Файл предназначен администратору экземпляра. Данные сохраняются в runtime/data. Пока выполняется Start.ps1, окно процесса должно оставаться открытым.

Для другого каталога данных используйте полный путь. Адрес 127.0.0.1 предоставляет доступ только с этой машины; серверный доступ настраивается отдельно.

./Start.ps1 -Port 8097 -BindAddress 127.0.0.1 -DataPath D:/ArhiPlanningData

Успешный запуск веб-страницы ещё не подтверждает готовность расчётного ядра. Выполните контрольные расчёты из раздела 4 этой инструкции.

3. Серверное размещение и контейнер

Сборка и состав образа

Для сборки используйте deploy/Platform.Dockerfile. Контекст должен содержать api/app, engine, examples, scripts, web/dist, requirements.lock.txt и каталог vendor/arhiplex с разрешёнными к поставке файлами установленного ядра. В vendor/arhiplex необходимы каталоги bin, lib64 и data. Лицензионный config.toml в образ не включается.

docker build -f deploy/Platform.Dockerfile -t arhiplanning:1.0.0 .

Используйте проверенный образ и фиксируйте его контрольный идентификатор. При публикации в корпоративном реестре сохраняйте правила доступа, принятые для этого реестра. Контейнер запускает API на порту 8082 и раздаёт собранный интерфейс.

Параметр	Настройка
Процессы и реплики	Один процесс Uvicorn, одна реплика приложения. Для обновлений с общей SQLite-базой используется последовательная замена экземпляра.
AP_DATA_DIR	Постоянный каталог /var/lib/arhiplanning с правом чтения и записи для UID/GID контейнера.
AP_ARHIPLEX_BIN	/opt/arhiplex/bin/arhiplex; исполняемые файлы должны иметь право запуска.
LD_LIBRARY_PATH	/opt/arhiplex/lib64 для библиотек расчётного ядра.
Учётные записи и подпись	users.json и signing.key в каталоге данных либо отдельные подключения из защищённого хранилища секретов.
Лицензия	Отдельное подключение действующего /opt/arhiplex/config.toml согласно поставке расчётного ядра.

Постоянное хранилище и публикация

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

Настройте HTTPS-прокси на порт приложения. Прокси должен пропускать заголовок Authorization: Bearer *** API. Если используется дополнительный внешний механизм входа, он не должен перехватывать этот заголовок и блокировать авторизацию платформы. Передайте пользователям адрес только после контрольной проверки входа, расчётов и выгрузки отчётов.

4. Учётные записи и проверка установки

Учётная запись планировщика

Для обычной работы и проверки функций создайте отдельную учётную запись с ролью planner. В локальной установке выполните следующую команду; пароль будет запрошен интерактивно. Если выбран другой каталог данных, укажите его вместо runtime/data.

./.venv/Scripts/python.exe scripts/users.py expert --role planner --data-dir runtime/data

В серверной установке утилита scripts/users.py выполняется администратором в подготовленном Python-окружении; файл users.json размещается в постоянном каталоге или подключается как секрет. Если файл подключён из секретов, изменения вносятся в источник секрета и применяются при обновлении контейнера. Не передавайте проверяющим административную учётную запись.

Контроль установленного экземпляра

Проверьте /api/health относительно адреса экземпляра: ответ должен содержать product ArhiPlanning, version 1.0.0, build 20260914 и три направления supply, calendar, availability. Затем войдите через веб-интерфейс и последовательно запустите три установленных учебных набора.

Учебный расчёт	Ожидаемый контрольный результат
Балансовое планирование	Завершённый расчёт, подтверждённая оптимальность; значение целевой функции около 13 115 526 689,486279.
Календарное планирование	38 транспортных единиц, 760 единиц объёма поставок; дефициты основного и вторичного каналов равны нулю.
Доступные объёмы	Спрос 280, обеспечено 270, дефицит 10. Дефицит предусмотрен условиями учебного примера.

Для каждого расчёта откройте результат, проверьте сообщение о проверке решения и выгрузите Excel. Убедитесь, что отчёт открывается и содержит таблицы выбранного направления. Для календарного JSON проверьте передачу плана в доступные объёмы и отдельный запуск полученного набора.

Сохранность и доступ

Загрузите отдельный учебный входной файл, выполните расчёт и сохраните идентификаторы набора и результата. После штатного перезапуска, а для контейнера — после его пересоздания, проверьте наличие этих объектов, скачивание исходного файла, чтение результата и выгрузку Excel. Рабочие данные должны сохраняться на постоянном томе.

Перед передачей проверочной учётной записи убедитесь, что она входит по внешнему адресу и выполняет необходимые операции. Реквизиты передаются отдельно от общедоступных документов. Использование учётной записи проверяющего не требует установки платформы на его компьютере.

5. Обновление и восстановление

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

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

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

./.venv/Scripts/python.exe scripts/backup.py backup `
    --data-dir runtime/data --output ../private-backup.zip

В архив входят база, входные файлы, результаты, учётные записи и ключ подписи. Храните его в закрытом каталоге с доступом администратора. Если секреты подключены отдельно, сохраните их также средствами соответствующей среды размещения.

Восстановление и запуск

Восстановление выполняется при остановленном приложении в пустой каталог. Утилита проверяет состав и контрольные суммы архива, восстанавливает файлы и переносит пути в базе на новый каталог.

./.venv/Scripts/python.exe scripts/backup.py restore `
    --archive ../private-backup.zip --data-dir D:/ArhiPlanningRestored
./Start.ps1 -DataPath D:/ArhiPlanningRestored

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

Типовые причины неудачного запуска

Признак	Действие администратора
Permission denied для каталога данных	Проверить фактически подключённый каталог, UID/GID, права записи и политики доступа; затем повторить попытку записи от имени контейнера.
Не запускается расчётное ядро	Проверить путь, право исполнения, доступность библиотек и действующую лицензию ArhiPlex.
HTTP 401 при входе или вызове API	Проверить учётную запись и настройки внешнего прокси; повторно выполнить вход и проверить передачу Bearer-токена.
После перезапуска пропали наборы	Проверить AP_DATA_DIR и подключение постоянного тома. Восстанавливать базу только вместе с соответствующими файлами.

Для отката используйте предыдущую версию приложения и совместимую с ней резервную копию. Порядок работы с данными и расчётами описан в документации по эксплуатации ArhiPlanning.