Самостоятельная установка одного API, completion worker и агента резервных копий: Linux/systemd, Windows desktop/Server и Docker Compose. Перед открытием доступа пройдите чек-лист эксплуатации. Поддерживаются стабильные опубликованные GitHub Releases, фиксация версии и отключаемые автоматические обновления. Готовые артефакты создаёт workflow Prepare stable release; до публикации первого релиза сетевой installer не сможет скачать Arkvory. Из исходников можно установить локальный артефакт.
Для установки на другую машину откройте Arkvory Remote Setup из клиентского пакета: адрес SSH → проверка ключа и платформы → одна кнопка установки → готовая консоль через автоматически созданный приватный туннель. Поддержаны нативные Windows/Linux, RU/EN и обе темы. Шаги, требования и ограничения сети.
Основной вариант Windows — Arkvory-Setup-x64.exe: настоящий мастер RU/EN со светлой/тёмной темой, готовыми Node.js/PostgreSQL/WinSW/VC++ runtime, созданием владельца и открытием onboarding. Интернет при установке не требуется. UAC и ввод пароля владельца выполняются пользователем.
Linux — Arkvory-amd64.deb / Arkvory-x86_64.rpm. Node.js и Arkvory включены, PostgreSQL и системные зависимости устанавливает пакетный менеджер. Откройте пакет в менеджере приложений или используйте apt/dnf. После установки откройте Arkvory из меню приложений. Не обещаем двойной щелчок на headless сервере или одинаковый GUI во всех дистрибутивах.
База Arkvory изолирована на loopback (порт выбирается при установке: 54329 или 45329–45348, на Windows только второй диапазон); существующие кластеры не изменяются. Данные сохраняются при удалении. Подробности, ограничения платформ, CLI и восстановление: native/README, ADR 0033.
ZIP/tar-комплекты остаются для операторской автоматизации и Compose. CMD-launchers удалены; эти архивы не являются графическими установщиками. Docker engine устанавливается отдельно.
Скачайте install.sh либо install.ps1 из проверенного релиза и просмотрите скрипт перед запуском. Он скачивает закреплённый Node.js 24 LTS с проверкой SHA-256, затем проверенный runtime Arkvory. npm и компилятор на целевом сервере не нужны. Без опубликованного релиза используйте распакованный комплект Arkvory-Linux.tar.gz / Arkvory-Windows.zip (локальный artifact, см. «Docker одной командой») либо установку из исходников.
| Вариант | Команда | Права | Supervisor |
|---|---|---|---|
| Linux, systemd | sudo bash ./install.sh --automatic |
root | systemd: arkvory-api, -worker, -backup |
| Windows, нативные службы | .\install.ps1 -AutomaticUpdates |
PowerShell от администратора | WinSW: Arkvoryapi, Arkvoryworker, Arkvorybackup |
| Docker, Linux | sudo bash ./install.sh --mode compose |
root либо пользователь группы docker | restart policy Docker |
| Docker, Windows | .\install.ps1 -Mode compose |
пользователь Docker Desktop, повышение не нужно | restart policy Docker Desktop |
Командным нативным вариантам нужна доступная PostgreSQL (URL запрашивается скрыто); графические EXE/DEB/RPM создают выделенный кластер. Docker-вариант поднимает API, worker, агента резервных копий и PostgreSQL 18.4 из deploy/compose.yml.
Linux, нативно:
sudo bash ./install.sh --automaticНужны systemd, glibc, Bash, curl, Python 3, tar/xz и доступная PostgreSQL. Архитектуры x64/arm64. Установщик скрыто запросит PostgreSQL URL; можно передать --config /secure/arkvory.json с {"ARKVORY_DATABASE_URL":"postgresql://..."}. Базу и права создаёт администратор PostgreSQL. Путь по умолчанию — /opt/proanima-arkvory; другой путь: sudo env ARKVORY_INSTALL_ROOT=/srv/arkvory bash ./install.sh. Не размещайте установку в домашнем каталоге: служба использует ProtectHome.
Windows x64, PowerShell от администратора (Windows desktop с поддержкой Node.js 24 либо Server 2022/2025):
.\install.ps1 -AutomaticUpdatesПуть — C:\ProgramData\ProAnima\Arkvory; доступны -Root, -Config, -Version и -Pin. Для другого Root используйте машинный каталог вне пользовательского профиля/AppData: LocalService должен проходить по родительским каталогам при разрешении пути Node.js. PostgreSQL URL запрашивается скрыто. Службы Arkvoryapi, Arkvoryworker и Arkvorybackup используют LocalService; WinSW 2.12.0 проверяется по закреплённому SHA-256. Пользовательский сеанс для нативных служб не нужен.
Docker, Linux:
sudo bash ./install.sh --mode compose --automaticБез root установщик работает от пользователя группы docker с доступным ему корнем: ARKVORY_INSTALL_ROOT="$HOME/arkvory" bash ./install.sh --mode compose. Корень получает 0700, а systemd-updater не регистрируется (см. «Планировщик updater без повышения прав»). Ограничение ProtectHome относится только к нативной службе.
Docker, Windows с работающим Docker Desktop в режиме Linux containers, обычная PowerShell от того же пользователя, под которым запущен Docker Desktop:
.\install.ps1 -Mode composeПовышение прав для Compose не требуется и не рекомендуется: Docker Desktop читает bind mounts с токеном своего пользователя, поэтому ACL корня — SYSTEM, Administrators и этот пользователь, без наследования (ADR 0050). Корень по умолчанию — C:\ProgramData\ProAnima\Arkvory; другой задаётся -Root. Если PowerShell запрещает запуск скриптов, используйте powershell -ExecutionPolicy Bypass -File .\install.ps1 -Mode compose (политика меняется только для этого процесса). При запуске от администратора дополнительно регистрируется SYSTEM-задача updater, которая рассчитана на системный движок, а не на Docker Desktop.
Движок и Compose должны быть установлены заранее; установщик не меняет гипервизор, WSL или Docker. Образ собирается локально из скомпилированного релиза. PostgreSQL 18.4 включён, пароль генерируется; named volumes сохраняют каталог БД и файлы. Для Podman: --engine podman / -Engine podman, нужен совместимый compose provider; приёмка конкретной версии проводится отдельно. Rootless Podman и Docker Desktop требуют планировщика в контексте пользователя движка; системный updater рассчитан на системный Docker/Podman. Windows containers не поставляются.
Стек API + worker + агент резервных копий + PostgreSQL из deploy/compose.yml ставится одной командой установщика. Из опубликованного релиза — команды из таблицы выше. Из распакованного комплекта без доступа к GitHub Releases (Node.js по-прежнему скачивается с проверкой SHA-256):
# Linux, в каталоге распакованного Arkvory-Linux.tar.gz
sudo env ARKVORY_ARTIFACT_DIR="$PWD" bash ./install.sh --mode compose# Windows, в каталоге распакованного Arkvory-Windows.zip
.\install.ps1 -Mode compose -Artifact $PWD.PathПередавайте -Root/-Artifact абсолютными путями: .NET разрешает относительный путь от рабочего каталога процесса, а не от текущего каталога PowerShell.
Из исходников (оценка до первого релиза; нужен Node.js 24 и npm ci --ignore-scripts) одна команда собирает проект, упаковывает тот же комплект, что проверяют гейты, и ставит его в режиме Compose текущим Node.js:
npm run deploy:compose -- --root "$HOME/arkvory-compose"npm run deploy:compose -- --root C:\Arkvory\composeПараметры: --version 0.1.0 (по умолчанию 0.0.1 — локальная сборка, которую плановое обновление заменит первым stable-релизом), --engine podman. Корень должен быть новым выделенным каталогом. Production-установку выполняйте из проверенного релиза, не из рабочего дерева.
После установки консоль открывается по http://127.0.0.1:8080/console/, ключ — в config/bootstrap-token.txt. Управление Compose-проектом (Linux; на Windows те же аргументы с путями $root\...):
root=/opt/proanima-arkvory
version=$(node -p "require('$root/installation.json').current.version")
compose=(docker compose --project-name proanima-arkvory --project-directory "$root" --env-file "$root/config/compose.env" -f "$root/releases/$version/deploy/compose.yml")
# Настроенный vault резервных копий: без этого файла `up` пересоздаст backup без vault.
[[ -f "$root/config/compose.vault.yml" ]] && compose+=(-f "$root/config/compose.vault.yml")
"${compose[@]}" ps
"${compose[@]}" logs --tail 100 api worker backup
"${compose[@]}" stop --timeout 120 backup worker api
"${compose[@]}" up -d --wait api worker
"${compose[@]}" up -d backup$root = 'C:\ProgramData\ProAnima\Arkvory'
$version = (Get-Content "$root\installation.json" -Raw | ConvertFrom-Json).current.version
docker compose --project-name proanima-arkvory --project-directory $root --env-file "$root\config\compose.env" -f "$root\releases\$version\deploy\compose.yml" psПолное удаление оценочной установки вместе с данными — та же команда с down --volumes, затем удаление каталога root. На рабочем хранилище down --volumes не выполняйте.
Установка Compose без root/Administrator не регистрирует системный updater и печатает указание запланировать updates-poll под владельцем движка. Без него консоль не применит запросы обновления. Linux (crontab пользователя группы docker):
* * * * * /path/to/root/runtime/node-v24.21.0-linux-x64/bin/node /path/to/root/manage.mjs updates-poll --root /path/to/rootWindows (обычная PowerShell от пользователя Docker Desktop; задача работает только в его сеансе, пока Docker Desktop запущен):
$root = 'C:\ProgramData\ProAnima\Arkvory'
$node = "$root\runtime\node-v24.21.0-win-x64\node.exe"
$action = New-ScheduledTaskAction -Execute $node -Argument "`"$root\manage.mjs`" updates-poll --root `"$root`"" -WorkingDirectory $root
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) -RepetitionInterval (New-TimeSpan -Minutes 1)
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -MultipleInstances IgnoreNew -ExecutionTimeLimit (New-TimeSpan -Minutes 30)
Register-ScheduledTask -TaskName ProAnimaArkvoryUpdate -Action $action -Trigger $trigger -Settings $settingsАргументы совпадают с системной задачей schedule-windows.ps1, поэтому повторная регистрация от администратора не считается чужой установкой. npm run deploy:compose не скачивает runtime: в обеих командах укажите путь к используемому Node.js 24.
HTTP по умолчанию доступен только через http://127.0.0.1:8080. Первичный ключ — в config/bootstrap-token.txt, в вывод установки он не попадает. После первого входа создайте учётные записи и сервисные ключи с ограниченными правами и работайте под ними. Bootstrap-ключ остаётся локальным ключом восстановления: его читают инструменты установки (создание владельца, configure --backup-vault, проверка агента после обновления), поэтому файл не удаляют и не передают клиентам. При подозрении на утечку замените токен и его SHA-256 в config/keys.json вместе и перезапустите API. Для удалённого доступа на нативной установке включите встроенный HTTPS: arkvory configure --root <root> --tls-cert <fullchain.pem> --tls-key <privkey.pem> --listen-host 0.0.0.0. Команда проверит файлы, перезапустит службы и при сбое вернёт прежнюю настройку; --tls-off выключает HTTPS. Обновлённые файлы сертификата подхватываются без перезапуска, проверки установщика сверяют сам настроенный сертификат, см. CORE_RUNBOOK. Для Compose используйте HTTPS reverse proxy (подходит и для нативной установки): nginx.conf.example не буферизует большие загрузки. Сертификаты, домен и firewall настраивает оператор.
Readiness проверяется отдельным config/health-token.txt: его запись deployment-health в keys.json не имеет repository grants и административных прав. Сохраняйте эту запись при замене bootstrap-ключа; при замене health credential синхронно меняйте токен и его SHA-256 и перезапускайте API. Healthcheck не использует административный ключ и не снимает авторизацию с /health/ready.
Агент резервных копий (arkvory-backup / Arkvorybackup / сервис Compose backup) устанавливается и запускается вместе с API и worker, но в readiness не входит. Без vault он работает и сообщает vault_not_configured. Vault — отдельный том или NAS, смонтированный заранее, вне корня установки. Подключение и отключение:
sudo arkvory configure --root /opt/proanima-arkvory --backup-vault /mnt/backup/arkvory --init-vault
sudo arkvory configure --root /opt/proanima-arkvory --backup-vault-offКоманда проверяет каталог до изменений и создаёт vault.json только в пустом каталоге (--init-vault). Затем она выдаёт доступ учётной записи службы (Linux — arkvory, 0700 и drop-in systemd; Windows — NT AUTHORITY\LOCAL SERVICE; Compose — bind mount config/compose.vault.yml с владельцем uid 1000) и перезапускает только агента. Изменение принимается, когда агент сам сообщил этот vault доступным; при сбое прежняя настройка возвращается. Расписание, retention и копии — в консоли, arkvoryctl backup и CORE_RUNBOOK. Решение: ADR 0057.
Установка 0.2.x, обновлённая своим же кодом (manage.mjs update/upgrade, планировщик), службу агента не получает: после обновления выполните arkvory updates-connect --root <root>. Пакеты deb, rpm и exe и обновления, выполненные новой версией, регистрируют её сами. Удаление и repair vault не трогают.
Установка может держать копию репозитория другой установки Arkvory рядом с потребителями. Копия доступна только для чтения и раздаёт файлы и при недоступном главном сервере. Подключение — arkvory configure --root <root> --mirror <repository> --mirror-upstream https://<главный> --mirror-token-file <ключ только для чтения>, отключение — --mirror-detach <repository>. С --mirror-stages release получается перенос dev → prod: обычный репозиторий забирает версии со стадией release, и очистка на dev их не удаляет. Команда проверяет главный этим ключом до изменений, перезапускает API и worker и при сбое возвращает прежнюю настройку. Подробности: CORE_RUNBOOK, решение — ADR 0058.
Сетевая установка и обновления берут версию, одобренную в хабе ProAnimaStudio, и проверяют подпись релиза встроенным ключом (хаб, подпись и статистика); GitHub-токен для этого не нужен. Только для обхода через GitHub, когда хаб недоступен, или для установки с --hub-off создайте в выделенном каталоге установки github-token.txt с токеном чтения Contents этого репозитория. Не передавайте его аргументом CLI. Linux: owner root (или пользователь Compose без root), mode 0600, каталог 0700; Windows: только Administrators/SYSTEM, для Compose без повышения — ещё установивший пользователь. Тот же файл использует updater. Служба Arkvory не должна читать его. Токен, скопированный после установки, нужно защитить теми же правами. Для публичных releases он не нужен.
| Путь | Назначение |
|---|---|
releases/<version> |
Код и production dependencies; приложение не пишет сюда |
installation.json |
Текущая версия, режим, automatic и pin; меняется CLI под lock |
config/runtime.json, config/keys.json |
Настройки и хеши ключей |
config/bootstrap-token.txt, github-token.txt |
Раздельные секреты приложения и обновления |
data, logs |
Данные нативной установки и логи Windows |
journal.json, operation.lock |
Состояние переключения/восстановления |
launcher.mjs, manage.mjs |
Загрузчики текущего релиза |
Каждый процесс Arkvory загружает код только из своего релиза и встроенных модулей Node.js: родительские node_modules, ~/.node_modules и NODE_PATH отклоняются, определения служб очищают NODE_PATH. На Windows установка и восстановление служб оставляют %ProgramData%\ProAnima над корнем по умолчанию на запись только администраторам; родителей корня в другом месте выбирает и защищает оператор. ADR 0031, дополнение 2026-10-18.
Контейнерные данные находятся в proanima-arkvory_storage и proanima-arkvory_catalog, а не в host data. Не запускайте down --volumes на установленном хранилище. Профиль имеет фиксированные Compose project и порт, одна установка на container host. Нельзя подключать второго writer к той же БД/root.
Примеры используют node; при отсутствии в PATH укажите поставленный runtime/node-v24.21.0-<platform>/bin/node (Linux) либо runtime/node-v24.21.0-win-x64/node.exe. Выполняйте команды с правами администратора (для Compose без повышения — от пользователя, установившего его):
node /opt/proanima-arkvory/manage.mjs status --root /opt/proanima-arkvory
node /opt/proanima-arkvory/manage.mjs update --root /opt/proanima-arkvory
node /opt/proanima-arkvory/manage.mjs configure --root /opt/proanima-arkvory --disable-updates
node /opt/proanima-arkvory/manage.mjs configure --root /opt/proanima-arkvory --pin
node /opt/proanima-arkvory/manage.mjs configure --root /opt/proanima-arkvory --unpin --enable-updatesНовые установки подключают уведомления и минутный обработчик команд. Проверка stable GitHub Releases выполняется каждые 6 часов, даже при выключенной автоустановке. --automatic / -AutomaticUpdates включает установку в окно 03:00–03:59 UTC на всех платформах; час меняется в консоли → Обновления. Не более одной попытки за сутки UTC, без догоняющего запуска вне окна. Pin запрещает плановую смену версии. Ручной выбор: update --version 1.2.3; downgrade запрещён. На хостах без системного планировщика его подключает оператор. Уведомления, подключение существующих установок, API и восстановление.
Linux: systemctl status arkvory-api arkvory-worker arkvory-backup, journalctl -u arkvory-api -u arkvory-worker -u arkvory-backup, updater — journalctl -u arkvory-update; лимиты journald задаются в ОС. Windows: Services и logs с ротацией по 20 MiB, пять архивов; вывод задачи ProAnimaArkvoryUpdate (запуск без консоли) пишется в logs/updater.log с той же ротацией. Строки deploy CLI имеют формат <ISO-8601> INFO|WARN|ERROR <текст>, секреты редактируются. Поля JSON-журнала API/worker и метрики: CORE_RUNBOOK. Docker: Compose logs, JSON logs ограничены 20 MiB × 5. Сбой процесса вызывает restart через 10 секунд у нативных служб, у Docker — по политике движка. Неуспешная readiness сама по себе не вызывает restart: мониторинг отдельно сообщает о недоступной БД, потере ownership и дисковых ошибках. Матрица автозапуска, восстановления и обязательных проверок отдельно описывает зависимость Docker от запуска движка и ограничения Linux без systemd.
Сначала проверяется полный релиз: SHA-256, безопасные пути ZIP и лимиты распаковки; для Compose заранее строится образ. Затем останавливаются агент резервных копий, worker и API с пределом 120 секунд, переключается версия, запускаются API, worker, затем агент, и проверяется readiness API/worker. Агент в readiness не входит: если он не сообщил о себе за ~90 секунд, печатается WARN, обновление не откатывается. При той же схеме миграции не запускаются, возможен автоматический rollback. Старый код, ключи, конфигурация, volumes и данные сохраняются. Это обновление с перерывом, не HA/rolling update; клиентам нужны resume/retry.
Релиз со сменой схемы ставится тем же update, консолью, автообновлением или пакетом. Перед остановкой встроенный агент снимает свежую точку в vault и проверяет её. Без подключённого vault, работающего агента и хотя бы одной завершённой копии установка отклоняется до любых изменений. Упавшая миграция откатывает свою транзакцию и возвращает прежнюю версию. Отказ запуска после успешной миграции оставляет журнал maintenance-required с ID точки. Подробности — UPDATES и ADR 0059.
Без встроенного vault (и при переходе с 0.2.0, где нет API резервных копий) нужны offline backup БД и полного storage root, проверка восстановления и migration notes. После этого:
node /opt/proanima-arkvory/manage.mjs upgrade --root /opt/proanima-arkvory --version 1.2.3 --backup-record /secure/backup-2026-09-25.txtbackup-record — существующая запись оператора, не автоматическое доказательство полноты копии. Журнал и откат такие же, как у update. Runtime URL пока используется и для миграций; если runtime роль лишена DDL, переключайте credential на обслуживание и возвращайте ограниченную роль после него. Автоматическое управление ролями PostgreSQL не реализовано.
После аварии updater:
- Остановите планировщик, убедитесь, что updater завершён, сохраните journal и логи.
- Только после этого удалите конкретный
operation.lock. Захват «старого» lock автоматически запрещён. - Запустите
node .../manage.mjs recover --root .... При той же схеме и при смене схемы до начала миграции (prepared,stopped) он возвращает прежнюю версию. Послеmigratingон повторяет миграцию и запускает новую. Если и это не помогает, восстановите точку изjournal.jsonпрежней версией. - Проверьте readiness, completion queue и контрольное скачивание; включите расписание.
Если первая установка остановилась после записи installation.json, устраните причину и используйте finish-install --root ... через manage.mjs. Не удаляйте config/data для повтора. При более ранней ошибке сохраните секреты и диагностируйте каталог: конфигурация не перезаписывается.
Старые releases, staging и download artifacts автоматически не удаляются. После проверки можно вручную убрать неиспользуемые каталоги, оставив текущую и предыдущую версию из журнала. Node.js, WinSW, PostgreSQL major, ОС и container engine обновляются отдельным обслуживанием.
npm ci --ignore-scripts
npm run gate -- quick deployment
npm run release:package -- 0.1.0
node artifacts/0.1.0/arkvory-setup.mjs install --root /opt/proanima-arkvory --mode compose --artifact artifacts/0.1.0Ту же последовательность для Compose выполняет npm run deploy:compose -- --root <dir>. Нативная локальная установка требует --config и административных прав. Артефакты рабочего дерева — для проверки; production выпускает workflow с tested commit. Prepare stable release работает только с main: read-only job выполняет полный release gate и собирает один candidate; приёмка Windows/Linux и контейнеров использует именно его. Отдельный publish job проверяет SHA-256 всех assets и совпадение commit/version, не пересобирает и не запускает артефакт, затем создаёт tag и draft. Только он имеет contents:write. Публикация draft владельцем делает версию доступной автообновлению. Неполный draft после ошибки upload нельзя публиковать. Повтор с существующим tag отказывает: разберите сбой, не заменяйте опубликованную версию.
release-checksums.json связывает runtime, bootstrap, командные установщики и два комплекта с одной версией/коммитом. Это контроль целостности, не независимая цифровая подпись. Передача candidate между jobs требует доступной квоты GitHub Actions artifacts. При нехватке места workflow блокирует выпуск; переключения на непроверенную пересборку или пропуска приёмки нет.
Гейты deployment, deployment-services, deployment-containers проверяют соответственно переносимый runtime, настоящий crash/restart трёх изолированных служб (API, worker, агент резервных копий с vault через drop-in/ACL) и Docker install/migrate/копию/update с сохранением volume. Service gate требует Windows Administrator либо Linux/systemd и passwordless sudo; container gate — Docker/Compose без уже установленного проекта proanima-arkvory. На Linux он запускает install.sh --mode compose, на Windows-хосте с Docker Desktop (Linux containers) — install.ps1 -Mode compose от пользователя Docker Desktop, без повышения прав: npm run gate -- deployment-containers. Они обязательны в CI и verify/release; отсутствие инфраструктуры не считается pass. Двухсерверный HA остаётся стендовой проверкой.