Переменные окружения
Arkvory настраивается переменными окружения, имена которых начинаются с ARKVORY_. На этой странице перечислены все переменные, которые читают серверные процессы, клиент командной строки и скрипты установки.
Откуда берутся значения
Установщики записывают настройки сервера в один файл, config/runtime.json, в корне установки. Программа запуска каждой службы читает этот файл и передаёт его значения API, обработчику и агенту резервного копирования. Каждый ключ должен начинаться с ARKVORY_, а каждое значение должно быть строкой.
json
{
"ARKVORY_HOST": "127.0.0.1",
"ARKVORY_PORT": "8080",
"ARKVORY_CAPACITY_BYTES": "10995116277760",
"ARKVORY_DATABASE_URL": "postgresql://arkvory:PASSWORD@127.0.0.1:54329/arkvory",
"ARKVORY_DATA_DIR": "/opt/proanima-arkvory/data",
"ARKVORY_KEYS_FILE": "/opt/proanima-arkvory/config/keys.json",
"ARKVORY_MAX_DOWNLOADS": "32"
}Файл содержит пароль базы данных. Оставьте его права доступа такими, какими их задал установщик.
Чтобы изменить настройку, отредактируйте config/runtime.json и перезапустите службы. Там, где настройку покрывает команда arkvory configure (HTTPS, хранилище копий, зеркала, обновления), используйте её. Команда проверяет изменение и возвращает прежний файл, если службы не запустились. См. Настройка.
bash
sudo systemctl restart arkvory-api arkvory-worker arkvory-backuppowershell
Restart-Service Arkvoryapi, Arkvoryworker, ArkvorybackupЗначение вне допустимого диапазона останавливает процесс при запуске с сообщением, в котором названа переменная. В этом случае Arkvory не возвращается к значению по умолчанию.
В столбце «Читает» используются такие названия: API — HTTP-сервер (в том числе шлюз чтения), worker — фоновый обработчик, agent — агент резервного копирования, CLI — arkvoryctl.
Основные настройки
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_DATABASE_URL | API, worker, agent, миграция | обязательна | URL подключения к PostgreSQL (postgres:// или postgresql://). Используйте отдельную базу данных для каждой установки. |
ARKVORY_DATA_DIR | API, worker, agent | обязательна | Локальный каталог хранилища: промежуточная область (staging), содержимое и файл storage-id. Не используйте сетевую папку. |
ARKVORY_HOST | API | 127.0.0.1 | Адрес, который нужно слушать. Установщики записывают 127.0.0.1; в Docker Compose внутри контейнера это 0.0.0.0, а порт публикуется только на loopback хоста. |
ARKVORY_PORT | API | 8080 | TCP-порт, 1–65535. |
ARKVORY_WEB_DIR | API | apps/web/public | Каталог с файлами веб-консоли. Программа запуска при каждом старте устанавливает его на текущий релиз. |
ARKVORY_DATABASE_POOL_SIZE | API | 20 | Размер пула запросов API, 4–200. Долгоживущие сессии используют отдельный пул из 3 соединений. |
Хранилище и ограничения
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_CAPACITY_BYTES | API, worker | 10 ТиБ | Верхний предел в байтах для всего зарезервированного содержимого: опубликованного, незавершённых загрузок и содержимого, ожидающего очистки. Это не проверка диска. Обработчик читает её только для копий зеркал. |
ARKVORY_STORAGE_RESERVE_BYTES | API, worker, agent | 1073741824 | Свободное место в байтах, которое загрузки никогда не занимают. Оно сохраняется для базы данных, журналов и системы. 0 отключает резерв. |
ARKVORY_MAX_OBJECT_BYTES | API | около 10 ТиБ | Наибольший объект в байтах. Наибольшее допустимое значение — 10 000 частей по 1 ГиБ. Задайте меньшее значение, чтобы ограничить размер файла. |
Передачи и пропускная способность
Эти ограничения относятся к одному процессу API. Скорости задаются в байтах в секунду: 0 означает «без ограничения», любое другое значение должно быть от 65 536 до 1 ТиБ.
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_MAX_UPLOADS | API | 8 | Одновременно выполняемые загрузки, 1–32. |
ARKVORY_MAX_DOWNLOADS | API | 16 | Одновременно выполняемые скачивания, 1–256. |
ARKVORY_MAX_UPLOADS_PER_PRINCIPAL | API | 4 | Одновременные загрузки одной учётной записи или ключа, не больше общего предела загрузок. |
ARKVORY_MAX_DOWNLOADS_PER_PRINCIPAL | API | 4 | Одновременные скачивания одной учётной записи или ключа, не больше общего предела скачиваний. |
ARKVORY_DOWNLOAD_STRATEGY | API | ordered | Как очередь упорядочивает целые скачивания объектов больше ARKVORY_DOWNLOAD_SESSION_MIN_BYTES: ordered (классы приоритета, учётные записи и ключи по кругу), smallest-first (сначала маленькие объекты) или shared (без очереди: каждый запрос допускается отдельно). Со шлюзами чтения (переменные ARKVORY_SHARED_DOWNLOADS_*) по умолчанию shared на каждом процессе, включая процесс записи. |
ARKVORY_MAX_DOWNLOAD_SESSIONS | API | ARKVORY_MAX_DOWNLOADS | Скачивания, одновременно занимающие место в очереди, 1–1024. |
ARKVORY_DOWNLOAD_RESERVE | API | 1 | Места для людей (сессии консоли и личные токены) во время массового обновления. При меньше чем четырёх местах по умолчанию 0. |
ARKVORY_DOWNLOAD_WEIGHTS | API | interactive=8,release=4,bulk=2,background=1 | Доля свободных мест по классам. Укажите только те классы, которые меняете. |
ARKVORY_DOWNLOAD_SESSION_MIN_BYTES | API | 16777216 | Объекты до этого размера идут без очереди, допуском на запрос. |
ARKVORY_DOWNLOAD_IDLE_SECONDS | API | 30 | Пауза между диапазонами дольше этой освобождает место. Скачивание сохраняет очередь ещё десять минут. |
ARKVORY_DOWNLOAD_AGING_MINUTES | API | 15 | Каждое такое ожидание поднимает скачивание на класс, не выше release. 0 отключает старение. |
ARKVORY_DOWNLOAD_PREEMPT | API | true | Клиенты протокола очереди (SDK, arkvoryctl) уступают место на границе диапазонов более высокому классу или ключу ниже его доли, если держат место не меньше минуты. |
ARKVORY_DOWNLOAD_RANGES_PER_SESSION | API | 4 | Одновременные запросы одного скачивания: параллельные диапазоны, клиенты за одним адресом. |
ARKVORY_DOWNLOAD_QUEUE_LIMIT | API | 65536 | Всего скачиваний в очереди, активных и ждущих. Сверх этого клиент получает просьбу прийти через минуту. |
ARKVORY_DOWNLOAD_QUEUE_PER_PRINCIPAL | API | 4096 | Всего скачиваний одной учётной записи, одного ключа или одной ссылки. |
ARKVORY_DOWNLOAD_HOLD_SECONDS | API | 20 | Сколько сервер держит запрос клиента вне протокола очереди (docker, npm, curl, браузер) до его очереди, прежде чем ответить 503. По умолчанию — ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS. 0 — отвечать сразу. |
ARKVORY_SITE_NAME | API | — | Как эта установка называется на странице «Площадки» других установок, 1–63 символа. |
ARKVORY_FLEET_KEY_FILE | API | fleet.key | Ключ, которым запечатаны ключи площадок, которыми управляет эта установка. Процесс записи создаёт его при первом запуске; берегите его как каталог данных. Его нет ни в базе данных, ни в резервных копиях. |
ARKVORY_SITE_URL | API | не задана | Адрес https://host[:port], по которому другие площадки обращаются к этой установке. Если задан, зеркала других площадок, источник которых — эта установка, ведут к ней на карте страницы «Площадки», а не показывают внешний адрес. Неверное значение останавливает запуск. |
ARKVORY_FLEET_LAG_ALERT | API | 1000 | На сколько изменений зеркало управляемой площадки может отстать от источника, прежде чем страница «Площадки» управляющей площадки покажет оповещение. Целое число, 1 или больше. |
ARKVORY_TRANSFER_QUEUE_LIMIT | API | 64 | Передачи, которые могут ждать свободного места (слота), 1–1024. |
ARKVORY_TRANSFER_QUEUE_PER_PRINCIPAL | API | 8 | Ожидающие передачи одной учётной записи или ключа, не больше предела очереди. |
ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS | API | 20000 | Сколько передача может ждать в очереди, 1–120 000 мс. |
ARKVORY_MAX_REQUESTS | API | 128 | Одновременные запросы с аутентификацией, 1–4096. Значение должно быть больше суммы загрузок и скачиваний. Если переменная не задана, а пределы передач высоки, по умолчанию берётся сумма загрузок и скачиваний плюс 64. |
ARKVORY_UPLOAD_BYTES_PER_SECOND | API | 0 | Общая скорость загрузки процесса. |
ARKVORY_DOWNLOAD_BYTES_PER_SECOND | API | 0 | Общая скорость скачивания процесса. |
ARKVORY_UPLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | Скорость загрузки одной учётной записи или ключа по всем их соединениям. |
ARKVORY_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | Скорость скачивания одной учётной записи или ключа по всем их соединениям. |
ARKVORY_UPLOAD_IDLE_TIMEOUT_MS | API | 30000 | Запрос загрузки, не передающий данные в течение этого времени, прекращается, 1–1 800 000 мс. |
ARKVORY_UPLOAD_DEADLINE_MS | API | 1800000 | Наибольшая длительность одного запроса загрузки, 1–1 800 000 мс. Она не может быть короче тайм-аута простоя. |
Сеть, HTTPS и браузеры
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_TLS_CERT_FILE | API | не задана | Сертификат PEM (вместе с цепочкой) для встроенного HTTPS. Задавайте вместе с файлом ключа. |
ARKVORY_TLS_KEY_FILE | API | не задана | Закрытый ключ PEM без пароля. |
ARKVORY_TLS_MIN_VERSION | API | TLSv1.2 | TLSv1.2 или TLSv1.3. |
ARKVORY_TLS_RELOAD_SECONDS | API | 300 | Как часто читаются обновлённые файлы сертификата: 30–86 400 секунд или 0, чтобы читать их только при запуске. |
ARKVORY_CORS_ORIGINS | API | пусто | Список из не более 16 origin браузера через запятую, для консоли на другом адресе. Только HTTPS или HTTP на loopback. |
ARKVORY_TRUSTED_PROXIES | API | пусто | До 32 адресов обратных прокси-серверов (IP или CIDR). Только они могут задавать адрес клиента через X-Forwarded-For, ID запроса через X-Request-Id, а также хост и протокол абсолютных ссылок (Git LFS, npm) через X-Forwarded-Host и X-Forwarded-Proto. |
Встроенный HTTPS предназначен для нативных установок. С Docker Compose используйте обратный прокси-сервер. См. HTTPS.
Идентификация и ключи
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_KEYS_FILE | API, worker | обязательна | Файл JSON с файловыми ключами, например ключом восстановления и ключом проверки работоспособности. В нём хранятся хеши SHA-256, но не сами ключи. |
ARKVORY_ALLOW_REGISTRATION | API | выкл. | true позволяет людям самим создавать учётные записи на странице входа. Любое другое значение оставляет регистрацию выключенной. |
Резервные копии
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_BACKUP_VAULT | agent | не задана | Каталог инициализированного хранилища копий. Без неё агент работает и сообщает, что хранилище не настроено. Записывает её arkvory configure --backup-vault. |
ARKVORY_BACKUP_VAULT_KEY_FILE | agent | не задана | Файл с ключом агента для зашифрованного vault (AK1-…) или набор восстановления. Команды принимают его и как --key-file. Его пишет arkvory configure --vault-key-file. |
ARKVORY_BACKUP_BYTES_PER_SECOND | agent | без ограничения | Ограничение скорости копирования резервной копии, не менее 65 536. |
ARKVORY_BACKUP_POLL_SECONDS | agent | 15 | Как часто агент проверяет наличие новых заданий резервного копирования, 1–3600 секунд. |
ARKVORY_BACKUP_LEASE_SECONDS | agent | 60 | Время аренды (lease), которое не позволяет второму агенту работать одновременно, 2–3600 секунд. |
ARKVORY_BACKUP_SNAPSHOT_SECONDS | agent | 1800 | Предел времени для части резервной копии со снимком базы данных, 60–86 400 секунд. |
ARKVORY_BACKUP_BARRIER_SECONDS | agent | 30 | Сколько резервная копия ждёт выполняющегося шага очистки, 1–600 секунд. |
ARKVORY_RESTORE_DATABASE_URL | команда restore | не задана | Целевая база данных при восстановлении. Это безопаснее, чем --database-url, потому что другие пользователи не видят её в списке процессов. |
См. Резервные копии.
Зеркала
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_MIRRORS_FILE | API, worker | не задана | Файл JSON со списком репозиториев-зеркал (до 64). Записывает его arkvory configure --mirror. |
ARKVORY_MIRRORS_CA_FILE | worker | не задана | Абсолютный путь к файлу PEM с дополнительными центрами сертификации для серверов-источников. TLS всегда проверяется. |
См. Зеркала.
Вебхуки
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_WEBHOOKS_FILE | worker | не задана | JSON-файл со списком подписок на вебхуки (до 16). Без него вебхуки не отправляются. |
ARKVORY_WEBHOOKS_ALLOW_PRIVATE | worker | не задана | Сети в формате CIDR через запятую (до 32), которым разрешено получать вебхуки помимо публичных адресов, например 10.20.0.0/16. |
ARKVORY_WEBHOOKS_CA_FILE | worker | не задана | Абсолютный путь к PEM-файлу с дополнительными удостоверяющими центрами получателей. TLS проверяется всегда. |
См. Вебхуки.
Кластер высокой доступности
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_REPLICA_SOCKET | API | не задана | Сокет службы arkvory-replica. Задаёт arkvory configure --cluster. С ней запись получает 2xx, только когда требуемые копии полные. Не задана — отдельный сервер. |
См. Кластер высокой доступности.
Обновления и хаб
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_HUB_URL | API | https://hub.proanima.net | Адрес хаба ProAnimaStudio, который использует только обратная связь из консоли (хаб обновлений хранится в config/hub.json и меняется командой arkvory configure). Пустое значение отключает обратную связь. Только HTTPS или HTTP на loopback. |
ARKVORY_HUB_PROJECT | API | arkvory | Название проекта в хабе. |
ARKVORY_UPDATE_CONTROL_DIR | API | не задана | Каталог, общий для API и средства обновления на хосте. Его задают установщики. Без него консоль не может запрашивать обновления. |
См. Обновления.
Журналирование и остановка
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_LOG_LEVEL | API, worker, agent | info | debug, info, warning или error. |
ARKVORY_ACCESS_LOG | API | true | true записывает одну строку JSON на каждый HTTP-запрос; false отключает запись. |
ARKVORY_DRAIN_TIMEOUT_MS | API | 30000 | После сигнала остановки — время, за которое должны завершиться выполняющиеся запросы, 0–3 600 000 мс. |
Шлюзы чтения
Если задана любая из этих переменных, обязательны слот, число слотов и общая скорость. Пишущий процесс использует роль api и слот 0. Каждый шлюз чтения использует роль reader и собственный слот. См. Шлюзы чтения.
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_ROLE | API | api | api (пишущий процесс) или reader (шлюз чтения). |
ARKVORY_GATEWAY_SLOTS | API | не задана | Число процессов, которые делят общий лимит скачивания, 2–16. |
ARKVORY_GATEWAY_SLOT | API | не задана | Слот этого процесса, от 0 до числа слотов минус один. |
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND | API | не задана | Общая скорость скачивания всех процессов. Каждый слот получает равную долю, не менее 65 536 байт в секунду. |
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | Общая скорость скачивания одной учётной записи или ключа по всем процессам; 0 означает «без ограничения». |
Сторожевой таймер
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_WATCHDOG_SECONDS | API, worker, agent | 60 | Процесс, который остаётся заблокированным в течение этого времени, завершается сам, а менеджер служб запускает его снова. 0 отключает сторожевой таймер (для отладчика); иначе 10–3600 секунд. |
См. Самовосстановление.
Клиент командной строки
| Переменная | Читает | По умолчанию | Значение |
|---|---|---|---|
ARKVORY_BASE_URL | CLI | профиль, затем http://127.0.0.1:8080 | Адрес сервера. Если переменная задана, ключ тоже должен браться из окружения. |
ARKVORY_TOKEN | CLI | не задана | Сам ключ. Приоритетнее файла ключа. |
ARKVORY_TOKEN_FILE | CLI | файл ключа из профиля | Путь к файлу, содержащему ключ. |
ARKVORY_CLI_HOME | CLI | ~/.config/arkvory | Каталог файла profiles.json. |
ARKVORY_CLI_VERSION | CLI | development | Версия, которую выводит --version. Её задают релизные пакеты. |
Скрипты установки
Эти переменные читает install.sh в Linux. В Windows install.ps1 вместо них использует параметры, например -Root и -Artifact.
| Переменная | По умолчанию | Значение |
|---|---|---|
ARKVORY_INSTALL_ROOT | /opt/proanima-arkvory | Корень установки. Не размещайте нативную установку в домашнем каталоге. |
ARKVORY_ARTIFACT_DIR | не задана | Каталог распакованного релиза. Скрипт устанавливает его вместо скачивания релиза. |
ARKVORY_RELEASE_VERSION | последний стабильный | Точная стабильная версия для установки, например 1.2.3. |
Задаются установщиком
Установщик задаёт эти переменные для своих вспомогательных процессов. Не задавайте их сами.
| Переменная | Значение |
|---|---|
ARKVORY_IMAGE | Образ контейнера текущего релиза в config/compose.env. |
ARKVORY_SERVICE_WRAPPER | Путь к обёртке службы резервного копирования Windows; используется, когда служба остановлена. |
ARKVORY_PROTECT_ROOT | Корень установки, для которого в Windows задаются правила доступа. |
ARKVORY_ENGINE_USER | В Windows с Docker Desktop даёт текущему пользователю доступ к корню. |