Настройка

У Arkvory два вида настроек:

• Настройки сервера — переменные ARKVORY_* в файле config/runtime.json. Они задают адрес, ограничения, хранилище и подобные вещи. API, обработчик и агент резервного копирования читают их при запуске.
• Политика установки — политика обновлений, файлы HTTPS, хранилище копий и зеркала. Вы меняете её командой arkvory configure. Команда проверяет изменение, перезапускает всё, что нужно, и возвращает прежнее состояние, если службы не запускаются.

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

Где хранится конфигурация

Всё хранится в корне установки. Это C:\ProgramData\ProAnima\Arkvory в Windows и /opt/proanima-arkvory в Linux. Установка Compose использует тот же корень на хосте. Пути ниже указаны относительно корня.

Файл	Содержимое	Как менять
config/runtime.json	Настройки сервера. Ключи начинаются с ARKVORY_, а каждое значение — строка. Содержит пароль базы данных	Вручную или командой configure
config/keys.json	Хеши SHA-256 ключа восстановления и ключа готовности. Самих ключей в нём нет	Только чтобы заменить ключ восстановления
config/bootstrap-token.txt	Ключ восстановления	Только чтобы заменить его
config/health-token.txt	Ключ, которым средства установки проверяют готовность	Не меняйте
config/hub.json	Адрес хаба, канал обновлений и настройка статистики	Командой configure
config/install-id	Случайный ID установки, который отправляется в хаб только при включённой статистике	Не меняйте
config/mirrors/	Список зеркал и ключи, которые обработчик использует для источников	Командой configure --mirror
config/webhooks/	Список подписок, секреты подписи и удостоверяющие центры получателей, которые использует worker	Командой configure --webhook
installation.json	Режим, движок, настройка автоматических обновлений, закрепление версии и установленный релиз	Только командами
github-token.txt	Необязательный токен GitHub для скачивания релизов. См. Обновления	Вручную
config/compose.env, config/compose.vault.yml, config/compose.mirrors.yml	Только Compose: образ, подключение хранилища копий и подключение зеркал	Только командами

В нативной установке Linux runtime.json и keys.json принадлежат root:arkvory с режимом 0640, а файлы с учётными данными в config/ может читать только root. Установка Compose использует режим 0644 для файлов, которые читают контейнеры: см. Docker Compose. Сохраняйте владельцев и режимы, которые задал установщик.

Команды жизненного цикла

Все команды требуют прав администратора и параметра --root с корнем установки.

Установка	Как выполнить команду
Пакет для Linux	sudo arkvory <команда> --root /opt/proanima-arkvory
Windows, графический установщик	В PowerShell с повышенными правами: & 'C:\Program Files\ProAnima\Arkvory\arkvory.ps1' <команда> --root C:\ProgramData\ProAnima\Arkvory
Установка скриптом, Compose	sudo <корень>/runtime/node-v24.21.0-linux-x64/bin/node <корень>/manage.mjs <команда> --root <корень>. В Windows используйте runtime\node-v24.21.0-win-x64\node.exe

arkvory help перечисляет команды без особых прав. В примерах на этом сайте используется краткая форма arkvory <команда>.

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

Одновременно выполняется только одна команда. Вторая команда останавливается с сообщением Installation is locked. Никогда не помещайте ключ или пароль в параметр команды: используйте файлы.

Команда configure

Один вызов меняет один вид настроек. Шесть видов в одном вызове смешивать нельзя.

Вид	Параметры	Действие
HTTPS	--tls-cert FILE --tls-key FILE [--listen-host ADDRESS] или --tls-off [--listen-host ADDRESS]	Включает или выключает встроенный HTTPS. Перезапускает службы и проверяет готовность. См. HTTPS
Хранилище копий	--backup-vault DIRECTORY [--vault-key-file FILE | --init-vault --vault-no-encryption]или--backup-vault-off	Подключает или отключает хранилище копий. Перезапускает только агент резервного копирования. См. Резервные копии
Зеркала	--mirror REPOSITORY --mirror-upstream URL --mirror-token-file FILE [--mirror-source REPOSITORY] [--mirror-stages LIST] [--mirror-ca-file FILE], или --mirror REPOSITORY --mirror-token-file FILE для нового ключа, или --mirror-detach REPOSITORY[,REPOSITORY…] либо --mirror-detach all	Превращает репозиторий в зеркало или в цель импорта либо снова делает его обычным. См. Зеркала
Вебхуки	--webhook ID --webhook-repository REPOSITORY --webhook-url URL --webhook-secret-file FILE [--webhook-next-secret-file FILE] [--webhook-actions LIST] [--webhook-allow-private LIST] [--webhook-ca-file FILE], or --webhook-detach ID	Добавляет, заменяет или удаляет подписку на вебхук. Перезапускает службы и проверяет готовность. См. Вебхуки
Кластер	--cluster ha-2 или ha-3 [--cluster-resource NAME]	На основном сервере реплицируемого тома: включает режим кластера. См. Кластер высокой доступности
Обновления	--enable-updates, --disable-updates, --pin [--version X.Y.Z], --unpin, --update-channel stable или beta, --statistics on или off, --hub-url URL, --hub-off	Меняет политику обновлений. См. Обновления

Изменения HTTPS, хранилища копий и зеркал перезапускают службы и возвращают прежнюю конфигурацию, если изменение не работает. Параметры обновлений только переписывают installation.json и hub.json; они ничего не перезапускают. Пути к файлам указывайте абсолютные.

Настройки по задачам

Адрес и порт

Переменная	По умолчанию	Значение
ARKVORY_HOST	127.0.0.1	Адрес, который слушает API
ARKVORY_PORT	8080	Порт TCP

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

• Встроенный HTTPS. arkvory configure --tls-cert … --tls-key … --listen-host 0.0.0.0. См. HTTPS.
• Обратный прокси-сервер на другом компьютере. Задайте в ARKVORY_HOST адрес сетевого интерфейса для прокси-сервера и укажите прокси-сервер в ARKVORY_TRUSTED_PROXIES. Отредактируйте runtime.json или выполните arkvory configure --tls-off --listen-host <адрес>. Ограничьте порт брандмауэром так, чтобы он был доступен только прокси-серверу.

Один параметр --listen-host отклоняется: используйте его вместе с файлами TLS или с --tls-off. После --tls-off добавьте --listen-host 127.0.0.1, чтобы вернуться на loopback, иначе API продолжит слушать заданный адрес.

Когда API слушает не loopback-адрес без TLS и без доверенного прокси-сервера, при запуске он записывает предупреждение http.plaintext_exposed. Никогда не передавайте ключи по обычному HTTP между компьютерами.

В Linux службы работают от непривилегированной учётной записи, которая обычно не может слушать порт ниже 1024. Ярлыки консоли (меню «Пуск», пункт меню) по-прежнему указывают на порт 8080. Команды жизненного цикла следуют адресу и порту из runtime.json. В установке Compose адрес и порт зафиксированы: см. Docker Compose.

Публичный адрес и пересылаемые заголовки

Параметра публичного URL нет. Сервер строит абсолютные ссылки, например ссылки в ответах Git LFS и npm, из запроса: схема — https, когда соединение защищено TLS или когда прокси-сервер отправляет X-Forwarded-Proto: https, а хост — это заголовок Host. Прокси-сервер из ARKVORY_TRUSTED_PROXIES может также задать хост через X-Forwarded-Host. Поэтому ваш прокси-сервер должен пересылать публичное имя. См. HTTPS.

ARKVORY_TRUSTED_PROXIES принимает до 32 адресов или диапазонов CIDR через запятую. Только эти узлы могут задавать адрес клиента через X-Forwarded-For и ID запроса через X-Request-Id. Без списка каждый клиент выглядит пришедшим с адреса прокси-сервера, и ограничение входа считает их одним клиентом.

Браузеры на другом адресе

ARKVORY_CORS_ORIGINS перечисляет через запятую до 16 источников консоли или другого веб-приложения, которое работает по другому адресу. Каждый источник состоит из схемы, хоста и необязательного порта, без пути. Нужен HTTPS; обычный HTTP принимается только для localhost, 127.0.0.1 и [::1]. См. HTTPS. ARKVORY_ALLOW_REGISTRATION=true позволяет людям самим создавать учётные записи на странице входа; по умолчанию эта возможность выключена.

База данных

Переменная	По умолчанию	Значение
ARKVORY_DATABASE_URL	задаёт установщик	URL подключения PostgreSQL. Управляемая база данных слушает 127.0.0.1 на порту, выбранном при установке
ARKVORY_DATABASE_POOL_SIZE	10	Размер пула соединений API, от 4 до 200

Не переключайте установку на другую базу данных. Сохранённые файлы и каталог составляют одно целое. Переход на новую базу данных — это восстановление из резервной копии: см. Резервные копии. Для внешнего PostgreSQL задайте max_connections достаточно большим для пула API, по одному соединению на каждую одновременную загрузку для блокировок записи, 5 для обработчика и соединений агента резервного копирования.

Каталог данных и свободное место

Переменная	По умолчанию	Значение
ARKVORY_DATA_DIR	<корень>/data	Где хранится содержимое файлов. Задаётся установщиком. Используйте локальный диск
ARKVORY_CAPACITY_BYTES	10 ТиБ	Наибольший объём, который может занять всё зарезервированное содержимое. Это предел резервирования, а не измерение диска
ARKVORY_STORAGE_RESERVE_BYTES	1 ГиБ	Свободное место, которое загрузки никогда не используют. 0 выключает резерв
ARKVORY_MAX_OBJECT_BYTES	около 10 ТиБ	Наибольший отдельный объект. Задайте меньшее значение, чтобы ограничить размер файла

Оставьте ARKVORY_DATA_DIR там, куда его поместил установщик. Юниты Linux могут писать только в data/, logs/ и updates/inbox/ корня, поэтому другой путь для них доступен только для чтения. Чтобы использовать диск побольше, остановите службы, скопируйте содержимое на новый диск, смонтируйте диск в data/ с владельцем arkvory и запустите службы. В Windows и Linux можно также выбрать сам корень при установке скриптом (-Root, ARKVORY_INSTALL_ROOT). См. Хранение.

Ограничения передач

Ограничения относятся к одному процессу API. Скорость 0 означает отсутствие ограничения.

Переменная	По умолчанию	Значение
ARKVORY_MAX_UPLOADS	2	Одновременные загрузки, от 1 до 32
ARKVORY_MAX_DOWNLOADS	16	Одновременные скачивания, от 1 до 256
ARKVORY_MAX_UPLOADS_PER_PRINCIPAL	1	Одновременные загрузки одной учётной записи или одного ключа
ARKVORY_MAX_DOWNLOADS_PER_PRINCIPAL	4	Одновременные скачивания одной учётной записи или одного ключа
ARKVORY_DOWNLOAD_STRATEGY	ordered	Порядок очереди скачиваний: ordered (классы и очередь по кругу), smallest-first или shared (без очереди, как раньше)
ARKVORY_UPLOAD_BYTES_PER_SECOND	0	Общая скорость загрузки в байтах в секунду
ARKVORY_DOWNLOAD_BYTES_PER_SECOND	0	Общая скорость скачивания в байтах в секунду
ARKVORY_UPLOAD_DEADLINE_MS	1800000	Наибольшая длительность одного запроса загрузки, 30 минут
ARKVORY_UPLOAD_IDLE_TIMEOUT_MS	30000	Запрос загрузки, который столько времени не передаёт данные, прерывается

Прокси-сервер перед API должен допускать запрос не короче ARKVORY_UPLOAD_DEADLINE_MS. См. HTTPS. Все остальные ограничения, например очередь ожидания и скорости на учётную запись, перечислены на странице Переменные окружения.

Значения очереди скачиваний (стратегию, число одновременных скачиваний, запас, веса и остальные) можно менять и без перезапуска: Площадки → Настройки этой площадки или PUT /api/v1/system/downloads/settings. Сохранённые значения на процессе записи важнее этих переменных; см. Площадки.

Резервные копии и зеркала

Для обоих используйте configure. --backup-vault записывает ARKVORY_BACKUP_VAULT, даёт сервисной учётной записи доступ к каталогу, перезапускает только агент резервного копирования и сохраняет изменение, только когда агент сообщает, что хранилище копий доступно. Хранилище копий должно находиться вне корня установки и вне каталога данных. --mirror записывает ARKVORY_MIRRORS_FILE и файлы ключей, перезапускает API и обработчик и проверяет источник вашим ключом, прежде чем что-либо изменить.

Обновления и хаб

Политика обновлений хранится в installation.json и config/hub.json. Параметры описаны в разделе Команда configure, а их смысл — на странице Обновления. ARKVORY_HUB_URL в runtime.json — отдельная настройка: она задаёт, куда консоль отправляет обратную связь. configure --hub-url или --hub-off меняет оба значения, а адрес обратной связи меняется после следующего перезапуска служб.

Журналы и остановка

Переменная	По умолчанию	Значение
ARKVORY_LOG_LEVEL	info	debug, info, warning или error. Уровни warning и error также скрывают журнал доступа
ARKVORY_ACCESS_LOG	true	Одна запись JSON на каждый HTTP-запрос. Строка запроса никогда не записывается
ARKVORY_DRAIN_TIMEOUT_MS	30000	После запроса на остановку — время, за которое должны завершиться выполняющиеся запросы

Диспетчеры служб дают службе 120 секунд на остановку. Если вы задаёте время завершения запросов больше примерно 90 секунд, увеличьте и тайм-аут остановки в менеджере служб: TimeoutStopSec в юнитах systemd, тайм-аут остановки служб Windows и stop_grace_period в Compose. См. Мониторинг.

Применение изменения

configure применяет собственное изменение. Для всего, что вы правите в config/runtime.json:

1. Сделайте копию файла, например sudo cp -p /opt/proanima-arkvory/config/runtime.json /root/runtime.json.bak. В нём лежит пароль базы данных: храните копию в закрытом месте.

2. Отредактируйте файл на месте. Сохраняйте корректный JSON, где каждое значение — строка.

3. Проверьте владельца и режим. В Linux они должны остаться root:arkvory и 0640. Восстановите их командами sudo chown root:arkvory runtime.json и sudo chmod 0640 runtime.json.

4. Перезапустите службы. Настройки читаются только при запуске.

   sudo systemctl restart arkvory-api arkvory-worker arkvory-backup

   Restart-Service Arkvoryapi, Arkvoryworker, Arkvorybackup

   В установке Compose остановите и запустите контейнеры командой compose из раздела Docker Compose:

   "${compose[@]}" stop --timeout 120 backup worker api
   "${compose[@]}" up -d --wait api worker
   "${compose[@]}" up -d backup

5. Проверьте результат. Значение вне допустимого диапазона останавливает процесс при запуске с сообщением, которое называет переменную, но не её значение. В Linux прочитайте его командой journalctl -u arkvory-api -n 50. В этом случае Arkvory не подставляет значение по умолчанию.

Перезапуск прерывает выполняющиеся передачи. Клиенты их возобновляют.

Замена ключа восстановления

Замените ключ восстановления, если подозреваете, что кто-то прочитал config/bootstrap-token.txt. Ключ хранится в двух местах, которые должны меняться вместе: в файле bootstrap-token.txt лежит сам ключ, а запись bootstrap-owner в keys.json содержит его SHA-256. Запись deployment-health оставьте как есть.

1. Сделайте копию config/keys.json.

2. Сохраните этот скрипт как replace-recovery-key.mjs:

   import { createHash, randomBytes } from 'node:crypto';
   import { readFileSync, writeFileSync } from 'node:fs';
   
   const directory = process.argv[2];
   const token = randomBytes(32).toString('hex');
   const keys = JSON.parse(readFileSync(`${directory}/keys.json`, 'utf8'));
   const owner = keys.find((key) => key.id === 'bootstrap-owner');
   if (!owner) throw new Error('No bootstrap-owner entry');
   owner.sha256 = createHash('sha256').update(token).digest('hex');
   writeFileSync(`${directory}/keys.json`, JSON.stringify(keys, null, 2));
   writeFileSync(`${directory}/bootstrap-token.txt`, token);

3. Запустите его от имени root или администратора с Node.js установки. Скрипт записывает данные в существующие файлы, поэтому владельцы и правила доступа остаются прежними.

   sudo /opt/proanima-arkvory/runtime/node ./replace-recovery-key.mjs /opt/proanima-arkvory/config

   & 'C:\ProgramData\ProAnima\Arkvory\runtime\node.exe' .\replace-recovery-key.mjs 'C:\ProgramData\ProAnima\Arkvory\config'

   После установки скриптом используйте Node.js из runtime\node-v24.21.0-….

4. Перезапустите службы, как показано в разделе Применение изменения.

5. Прочитайте новый ключ из config/bootstrap-token.txt, а скрипт и копию keys.json удалите.

Учётные записи, персональные токены и ключи сервиса это не затрагивает. Они хранятся в базе данных.