ADR 0033 — Нативные установщики и знакомство с Arkvory

Статус: принято для реализации; допуск выпуска — по нативным гейтам.

Решение

Основной Windows-дистрибутив — EXE Inno Setup 6.7.3, RU/EN, системная светлая/тёмная тема, отдельная бренд-панель. В комплекте проверенные SHA-256 Node.js 24, PostgreSQL 18, WinSW и Microsoft VC++ runtime. На целевой машине не выполняются npm, сборка или скачивание исполняемого кода. UAC и создание пароля владельца остаются необходимыми действиями пользователя. Перезагрузка, запрошенная Microsoft runtime, не маскируется успешной установкой.

Linux получает DEB/RPM с готовыми Node.js/Arkvory. Зависимости PostgreSQL, systemd, Python и сертификаты разрешает пакетный менеджер. Первый профиль: x64/glibc, Ubuntu 24.04 / Debian с PostgreSQL >=16, RPM-дистрибутивы с PostgreSQL 16–19. Не обещаем GUI на headless, Alpine/musl, macOS или штатный пакет для старых дистрибутивов. Графический менеджер приложений может установить локальный пакет; автоматическое открытие браузера из root post-install запрещено. Ярлык ведёт в onboarding. Docker остаётся самостоятельным Compose-профилем с заранее установленным engine: установщик хранилища не включает гипервизор или WSL.

Командные launchers удалены. ZIP/tar комплекты сохраняются как наборы для операторской автоматизации и внешней БД, без обещания графической установки.

Жизненный цикл и данные

• Код установщика и payload Windows: Program Files; mutable state: ProgramData/ProAnima/Arkvory. Linux package payload: /usr/lib/proanima-arkvory, state: /opt/proanima-arkvory.
• Отдельный управляемый кластер слушает только 127.0.0.1 на порту, выбранном при установке, и записанном в database/settings.json (уточнение 2026-10-15): первый свободный из списка — на Windows 45329–45348, ниже динамического диапазона 49152–65535, блоки которого Hyper-V и WinNAT резервируют при каждой загрузке по-разному; на других системах сначала 54329. Установки, сделанные раньше, сохраняют 54329. Свободный при установке порт не защищён от следующих загрузок: Hyper-V/WinNAT резервируют блоки и ниже 49152, если динамический диапазон расширен. Поэтому на Windows установщик добавляет на выбранный порт постоянное административное исключение (netsh int ipv4 add excludedportrange ... store=persistent, уточнение 2026-10-15): система не включает его в резервируемые блоки, а явный bind PostgreSQL исключение не запрещает. Кандидат внутри системного блока или с отказом netsh пропускается. Исключение, добавленное Arkvory, отмечено файлом database/port-exclusion; удаление снимает только его, а восстановление, обновление и повторная установка поверх сохранённых данных добавляют отсутствующее исключение (отказ — предупреждение, не ошибка обновления). Перевыбор порта при запуске службы отвергнут: служба БД работает от NetworkService и не может переписать config/runtime.json API/worker, а неатомарная смена порта в двух файлах опаснее явного отказа. После установки порт не меняется сам: конфликт порта при запуске приводит к ошибке с понятной записью в журнале БД, не к автоматическому переключению на чужую БД. Существующие системные кластеры не изменяются.
• Windows БД работает как NetworkService, API/worker как LocalService. Linux: arkvory-db и arkvory. Кластер и пароль владельца БД недоступны идентичности API. Приложение использует отдельную роль без superuser/createdb/createrole.
• initdb включает checksums и SCRAM. Частичная инициализация и неоднозначное выполнение CREATE ROLE / CREATE DATABASE сохраняются для восстановления; их нельзя автоматически удалять или повторять без проверки.
• База имеет собственную службу и graceful fast shutdown. Перезапуск API не перезапускает БД. Установщик ждёт инициализации БД и готовности API/worker.
• Удаление программы останавливает службы и снимает собственное исключение порта БД, но не удаляет кластер, blobs, настройки или recovery key. Повторная установка и code update используют существующий journal/pointer. Смена major PostgreSQL не входит в автообновление Arkvory.
• Отдельная поставка Node/PostgreSQL означает отдельное обслуживание этих зависимостей; обновление кода Arkvory само по себе не заменяет установленный runtime.

Доступ и знакомство

Windows-мастер передаёт имя/пароль через закрытый JSON, создаёт первого администратора по loopback API и удаляет файл после успеха. Группа arkvory-owners получает write-доступ к начальному репозиторию releases, затем в неё включается владелец. Административный флаг сам по себе не заменяет repository grants. При частичном сбое после создания аккаунта интерфейс сообщает о восстановлении группы через раздел доступа. Пароль не передаётся argv, URL, журналом или localStorage. Bootstrap token остаётся закрытым recovery credential, не попадает в браузер автоматически. При неизвестном результате создания владельца оператор проверяет состояние через recovery key; повторная установка не сбрасывает пароли.

Браузер открывается от исходного пользователя на /console/#onboarding. Linux/headless onboarding использует существующую авторизацию по recovery key для создания владельца. Это не публичный unauthenticated setup endpoint. Интерфейс ведёт к входу, первой загрузке, интеграциям и эксплуатационной подготовке. Изменение темы/языка сохраняет несекретные поля текущей формы.

API-справочник использует существующий paginated /api/v1/operations с текущим токеном и repository. Смена контекста отменяет загрузку и очищает результаты. Он показывает метод, путь, видимость, права и политику повторов; не подменяет серверную авторизацию. CLI help отделяет обслуживание инсталляции от API интеграций.

Приёмка и выпуск

native-package компилирует настоящие EXE/DEB/RPM и проверяет manifest/version/commit/хеши. native-install работает только на одноразовом Actions runner: установка, readiness, вход владельца Windows, отсутствие superuser у app-role, удаление с сохранением данных. Эти гейты включены в verify/release и обязательную ветку CI. Нативные артефакты публикуются после приёмки без пересборки, права записи есть только у publish.

В Linux-гейт включена установка RPM в Fedora 44 с настоящим systemd, проверка readiness, повторная установка и удаление с сохранением данных. Контейнер с привилегиями запускается только на одноразовом CI runner; это испытательное окружение, не профиль эксплуатации Arkvory. Остальные RPM-дистрибутивы требуют отдельной приёмки перед заявлением поддержки. Подпись EXE сертификатом Ian Panaev и подпись DEB/RPM требуют отдельно предоставленных signing credentials. Пока их нет, нельзя называть сборку подписанной или обещать отсутствие SmartScreen. Подпись должна предшествовать нативной приёмке, не выполняться в publish после проверки.

Источники зависимостей

Inno Setup, лицензия компилятора, PostgreSQL Windows, EDB binaries, WinSW. Все URL и digest версий зафиксированы в scripts/native-dependencies.mjs; сторонние лицензии входят в Windows payload.