Linux

Запустить Arkvory в Linux можно двумя способами:

• Пакет Arkvory-amd64.deb или Arkvory-x86_64.rpm. Рекомендуется. Он устанавливает службы systemd и отдельный кластер PostgreSQL, которым управляет Arkvory. Программы PostgreSQL поставляет ваш менеджер пакетов.
• Скрипт install.sh. Он устанавливает те же службы, но использует существующий сервер PostgreSQL. Он также поддерживает arm64. См. Использование существующего PostgreSQL.

Для Docker см. Docker Compose. Чтобы впервые пройтись по консоли, см. Быстрый старт.

Требования

Параметр	Требование
Процессор	x64 для пакетов. Пакетов для arm64 нет: на arm64 используйте install.sh
Система инициализации	systemd. OpenRC, runit и другие системы инициализации не поддерживаются
Библиотека C	glibc 2.28 или новее. Alpine Linux (musl) не поддерживается
Проверенные дистрибутивы	Ubuntu 24.04 для .deb, Fedora 44 для .rpm. Другие дистрибутивы с systemd, которые удовлетворяют перечисленным ниже зависимостям, не проверялись
Зависимости .deb	postgresql 16 или новее, systemd, python3, ca-certificates, libc6 2.28 или новее, libstdc++6, libgcc-s1, libatomic1
Зависимости .rpm	postgresql-server 16 или новее, systemd, python3, ca-certificates, glibc 2.28 или новее, libstdc++, libatomic
Программы PostgreSQL	Версии с 16 по 19. Шаг установки ищет их в /usr/lib/postgresql/*/bin, /usr/pgsql-*/bin, /usr/bin и /usr/lib/pgsql/bin и берёт самую новую из найденных версий. Если ваш дистрибутив предлагает только более старую версию, сначала добавьте репозиторий с более новым PostgreSQL
Пользователь	root или пользователь, который может выполнять sudo
Свободные порты	8080, а также 54329 или один из 45329-45348, на 127.0.0.1
Хранилище файлов	Локальная файловая система с поддержкой жёстких ссылок. Не используйте сетевую папку

Пакет содержит Node.js 24. Для установки не нужен доступ в интернет, кроме того, который менеджер пакетов использует для зависимостей.

Пакет никогда не меняет существующий кластер или службу PostgreSQL. Arkvory запускает собственный кластер из программ PostgreSQL.

Установка пакета

1. Скачайте пакет для вашего дистрибутива со страницы GitHub Releases вместе с native-linux.json того же релиза.
2. Сравните SHA-256 пакета со значением из native-linux.json. Пакеты не подписаны ключом издателя, поэтому эта проверка — единственное доказательство того, что вы скачали.
3. Установите пакет. Оставьте ./ перед именем файла: так менеджер пакетов понимает, что файл локальный. В Debian и Ubuntu:

sudo apt install ./Arkvory-amd64.deb

В Fedora и RPM-совместимых системах:

sudo dnf install ./Arkvory-x86_64.rpm

Менеджер пакетов устанавливает зависимости, затем Arkvory настраивает себя сам. Он:

1. копирует Node.js в /opt/proanima-arkvory/runtime/node,
2. создаёт две учётные записи служб, конфигурацию, ключи и ключ восстановления,
3. создаёт и запускает кластер PostgreSQL и выполняет миграции базы данных,
4. регистрирует и запускает службы и таймер обновления,
5. ждёт, пока API три раза подряд ответит на проверку готовности.

В конце он печатает адрес консоли и путь к ключу восстановления. Если какой-то шаг завершается ошибкой, установка останавливается с сообщением. См. Устранение неполадок.

После установки автоматические обновления выключены. Чтобы включить их, см. Обновления.

Что создаёт пакет

Файлы и каталоги

Путь	Содержимое
/usr/lib/proanima-arkvory/	Содержимое пакета: Node.js, файлы релиза и установщик. Принадлежит пакету
/usr/bin/arkvory	Команда управления. См. Команда arkvory
/usr/share/applications/arkvory.desktop	Пункт меню, который открывает консоль на рабочем столе. Сервер без рабочего стола его не использует
/opt/proanima-arkvory/	Корень установки: настройки, данные, база данных, код программы каждой версии. Его структура описана в разделе Выбор установки
/etc/systemd/system/arkvory-*.service, arkvory-update.timer	Файлы юнитов служб и таймер обновления

Корень принадлежит root:arkvory с режимом 0711. Внутри него config/ — 0750 root:arkvory, data/ и logs/ принадлежат arkvory, а database/ принадлежит arkvory-db с режимом 0700. Ключ восстановления и файлы с паролями базы данных доступны для чтения только root.

Учётные записи

Учётная запись	Что запускает	Примечания
arkvory	API, обработчик, агент резервного копирования	Системная учётная запись без оболочки входа, домашний каталог /opt/proanima-arkvory/data
arkvory-db	База данных	Системная учётная запись без оболочки входа. Учётная запись API не может читать файлы базы данных

Службы

Юнит	Работает от имени	Политика перезапуска
arkvory-database	arkvory-db	on-failure, через 10 секунд
arkvory-api	arkvory	always, через 10 секунд
arkvory-worker	arkvory	always, через 10 секунд
arkvory-backup	arkvory	always, через 10 секунд
arkvory-update.timer	запускает arkvory-update.service от root	Каждую минуту. Задание проверяет запросы на обновление и новые релизы

Все юниты запускаются при загрузке (multi-user.target). На остановку им отводится 120 секунд. Они работают с NoNewPrivileges, отдельным /tmp, файловой системой только для чтения вне их собственных каталогов и без доступа к /home. API и обработчик могут писать только в data/, logs/ и updates/inbox/ корня. Агент резервного копирования читает хранилище и пишет только в хранилище копий. Поскольку /home скрыт от юнитов, никогда не размещайте сертификаты, хранилища копий или каталог данных в домашнем каталоге.

Служба, которая остановилась без вашей команды, запускается снова через 10 секунд. Процесс, главный поток которого зависает на 60 секунд, завершается сам и запускается снова. Одна лишь неудачная проверка готовности службу не перезапускает. См. Самовосстановление.

Порты

Порт	Назначение	Доступность
8080/TCP	API и консоль	Только 127.0.0.1, пока вы не настроите HTTPS
54329/TCP	Управляемый кластер PostgreSQL	Только 127.0.0.1. Если при установке 54329 занят, то первый свободный из 45329-45348; он сохраняется в database/settings.json

Первый запуск и первые шаги

1. Проверьте, что службы работают:

   systemctl status arkvory-database arkvory-api arkvory-worker arkvory-backup

2. Прочитайте ключ восстановления. Прочитать его может только root.

   sudo cat /opt/proanima-arkvory/config/bootstrap-token.txt

3. Откройте http://127.0.0.1:8080/console/#onboarding. На удалённом сервере сначала пробросьте порт и откройте адрес на своём компьютере:

   ssh -L 8080:127.0.0.1:8080 admin@arkvory.example

4. В консоли откройте Начало работы и разверните Создать первого владельца. Вставьте ключ в поле Ключ восстановления, введите имя владельца и пароль не короче 12 символов и нажмите Создать владельца. Имя содержит от 3 до 64 символов: латинские буквы, цифры, точка, дефис или подчёркивание.

5. Войдите с новым именем и паролем.

Владелец — первый администратор. Ключ восстановления остаётся на сервере: не удаляйте файл и не копируйте его на клиенты или в системы CI. Его читают средства установки. Для повседневной работы создавайте учётные записи и ключи сервиса. См. Учётные записи и доступ и Безопасность.

Прежде чем клиенты начнут подключаться с других компьютеров, настройте HTTPS. Затем подключите хранилище копий и выполните первую резервную копию: см. Резервные копии.

Чтобы установить Arkvory на сервер со своего компьютера, можно вместо этого воспользоваться Arkvory Remote Setup. См. Выбор установки.

Команда arkvory

Пакет устанавливает /usr/bin/arkvory. arkvory help перечисляет все команды и не требует особых прав. Каждая другая команда требует root и корня установки:

sudo arkvory status --root /opt/proanima-arkvory

status печатает режим установки, установленную версию, настройку автоматических обновлений и закрепление версии.

Команда	Назначение
status	Показать установленную версию и политику обновлений
update	Установить более новый стабильный релиз сейчас. См. Обновления
configure	HTTPS, хранилище копий, зеркала, политика обновлений и хаб. См. Настройка
recover	Завершить прерванное обновление. См. Обновления
finish-install	Продолжить прерванную установку
updates-connect	Подключить консоль и таймер обновления в установке, которую обновили со старого релиза

Журналы

Службы пишут в системный журнал. API и обработчик пишут по одной записи JSON в строке.

sudo journalctl -u arkvory-api -u arkvory-worker -u arkvory-backup -u arkvory-database
sudo journalctl -u arkvory-api -f
sudo journalctl -u arkvory-update --since today

arkvory-update содержит вывод таймера обновления. Размер и срок хранения журнала — настройки вашей операционной системы. О полях записей и метриках см. Мониторинг. Команды развёртывания печатают строки вида <время ISO-8601> INFO|WARN|ERROR <текст>. Секреты из них удаляются.

Обновление

Установите более новый пакет поверх старого либо обновите из консоли или командой arkvory update. Работающие службы продолжают обслуживать запросы, пока обновление не переключится на новый код. О политиках, резервной копии перед изменением схемы базы данных и шагах восстановления см. Обновления.

Репозитория apt или dnf для Arkvory нет. Скачивайте каждый новый пакет со страницы релиза.

Удаление

Удаление пакета с сохранением данных

В Debian и Ubuntu:

sudo apt remove proanima-arkvory

В Fedora и RPM-совместимых системах:

sudo dnf remove proanima-arkvory

Удаление останавливает и отключает службы и таймер обновления. Оно удаляет /usr/lib/proanima-arkvory, /usr/bin/arkvory и пункт меню. Намеренно сохраняется:

• /opt/proanima-arkvory: база данных, все файлы, конфигурация и ключ восстановления,
• файлы юнитов в /etc/systemd/system, учётные записи arkvory и arkvory-db,
• хранилище копий и его дополнение systemd (drop-in). Хранилище копий никогда не затрагивается.

apt purge удаляет не больше, чем apt remove. Если вы установите пакет снова, он продолжит работу с сохранёнными данными и запустит службы.

Удаление всего

Это удаляет все сохранённые файлы и каталог. Сначала сделайте резервную копию и сохраните хранилище копий.

sudo systemctl disable --now arkvory-update.timer arkvory-backup arkvory-worker arkvory-api arkvory-database
sudo rm -rf /opt/proanima-arkvory
sudo rm -f /etc/systemd/system/arkvory-*.service /etc/systemd/system/arkvory-update.timer
sudo rm -rf /etc/systemd/system/arkvory-backup.service.d
sudo systemctl daemon-reload
sudo userdel arkvory
sudo userdel arkvory-db

Сначала удалите пакет, как описано выше. После установки скриптом пакета нет: первая команда останавливает службы, а команды с arkvory-database и arkvory-db сообщают, что их не существует.

Использование существующего PostgreSQL

Пакет всегда создаёт собственный кластер. Чтобы использовать сервер PostgreSQL, которым управляет ваша организация, установите Arkvory с помощью install.sh. Он создаёт те же три службы и таймер обновления, но без юнита arkvory-database и без команды /usr/bin/arkvory.

Используйте PostgreSQL версий с 16 по 19. Одну базу данных используйте для одной установки Arkvory. Никогда не подключайте две установки к одной базе данных.

1. Попросите администратора базы данных создать пустую базу данных и роль, которая ею владеет. Arkvory выполняет миграции от имени этой роли.

2. Скачайте install.sh из релиза и прочитайте его. Ему нужны bash, curl, python3, tar и xz, systemd и root.

3. Запустите его. Скрипт запросит URL подключения; вводимый текст скрыт.

   sudo bash ./install.sh --automatic

   Чтобы передать URL файлом, создайте файл, который может читать только root:

   { "ARKVORY_DATABASE_URL": "postgresql://arkvory:<пароль>@db.example:5432/arkvory" }

   sudo bash ./install.sh --config /root/arkvory.json

4. Удалите временный каталог /opt/proanima-arkvory/bootstrap.*, когда установка закончится. Если вы ввели URL в ответ на запрос, этот каталог хранит его в native.json.

5. Создайте владельца, как описано в разделе Первый запуск и первые шаги.

Скрипт скачивает Node.js 24.21.0 с nodejs.org, проверяет его SHA-256 и устанавливает последний стабильный релиз. Чтобы оставить автоматические обновления выключенными, не указывайте --automatic. Значения по умолчанию меняют переменные окружения:

Переменная	Значение	По умолчанию
ARKVORY_INSTALL_ROOT	Корень установки. Используйте отдельный пустой каталог вне /home	/opt/proanima-arkvory
ARKVORY_RELEASE_VERSION	Установить эту стабильную версию вместо последней	последняя стабильная
ARKVORY_ARTIFACT_DIR	Установить из распакованного Arkvory-Linux.tar.gz вместо GitHub	не задана

Передавайте их через sudo env, например sudo env ARKVORY_INSTALL_ROOT=/srv/arkvory bash ./install.sh.

Без команды arkvory вызывайте программу управления с Node.js, который установил скрипт. На arm64 используйте linux-arm64:

root=/opt/proanima-arkvory
sudo "$root/runtime/node-v24.21.0-linux-x64/bin/node" "$root/manage.mjs" status --root "$root"

Сервер PostgreSQL вы резервируете и обслуживаете сами. Агент резервного копирования Arkvory копирует содержимое базы данных в хранилище копий через URL подключения. См. Резервные копии.

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

Проблема	Что делать
PostgreSQL 16–19 server binaries are required	Программы PostgreSQL отсутствуют или слишком старые. Установите сервер PostgreSQL версий с 16 по 19 и установите пакет снова
Use a dedicated empty installation directory	В /opt/proanima-arkvory остались файлы от первой установки, которая остановилась до сохранения installation.json. Установщик никогда не перезаписывает конфигурацию. Прочитайте журнал и вывод менеджера пакетов и устраните причину. Каталог, в котором ещё нет данных, можно убрать, чтобы установить заново. Не удаляйте config/ и database/ установки, в которой есть данные
Installation is locked	Выполняется операция или она завершилась аварийно. Остановите таймер обновления, прочитайте journal.json в корне и не удаляйте operation.lock, пока не узнаете состояние. См. Обновления
database/bootstrap-started есть, а database/initialized нет	Создание базы данных прервалось. Не удаляйте кластер и не повторяйте SQL вручную. Устраните причину и выполните sudo arkvory finish-install --root /opt/proanima-arkvory
Служба не запускается	journalctl -u arkvory-api -n 100. Сбой запуска печатает одну запись JSON с reason, которая называет настройку, но не её значение
Порт 8080 занят	Его использует другая программа. Освободите порт или задайте ARKVORY_PORT в config/runtime.json. См. Настройка. Порт базы данных выбирается при установке (54329 или 45329-45348) и сам не меняется

Если установка остановилась после того, как записала installation.json, можно также повторить шаг настройки пакета: sudo dpkg --configure -a в Debian и Ubuntu или повторная установка того же пакета в системах RPM.

Другие подсказки есть на странице Устранение неполадок.