Шлюзы чтения

Шлюз чтения — это дополнительный процесс API, который обслуживает только скачивания. Он работает на том же сервере, что и основной API (пишущий процесс, writer), использует ту же базу данных PostgreSQL и тот же каталог хранилища файлов и делит один лимит скачивания с пишущим процессом и другими шлюзами.

Шлюзы нужны, чтобы распределить множество параллельных скачиваний между несколькими процессами, сохраняя общую скорость скачивания в пределах одного заданного вами лимита. Шлюз ничего не копирует. Он читает файлы, которые опубликовал пишущий процесс, поэтому никогда не отстаёт. Он также не защищает от потери сервера или диска. Для этого см. разделы Резервные копии и Зеркала.

Как это работает

• В установке один пишущий процесс и до 15 шлюзов чтения. Вместе это не более 16 слотов. Пишущий процесс всегда использует слот 0. Каждый шлюз использует собственный слот от 1 до числа слотов минус один.
• Все процессы используют одну базу данных PostgreSQL и один каталог хранилища файлов. Шлюз проверяет, что хранилище файлов существует и принадлежит этой базе данных. Он никогда его не создаёт.
• Вы задаёте одну общую скорость скачивания для всех процессов. Каждый процесс получает равную фиксированную долю: общую скорость, делённую на число слотов, с округлением вниз.
• Процесс удерживает свой слот арендой в базе данных. Если он теряет аренду, он перестаёт отдавать новые данные и его нужно перезапустить. Так сумма всех долей остаётся в пределах общей скорости.

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

От чего шлюз отказывается

Шлюз принимает только GET и HEAD. Каждый запрос, который что-то меняет, получает HTTP 405 с заголовком Allow: GET, HEAD и кодом read_only, даже если у ключа есть право записи. Это относится и ко входу, и к самостоятельной регистрации. Консоль входит только в пишущий процесс, поэтому на шлюзе она недоступна.

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

Требования

• Тот же сервер. Шлюз должен видеть ровно те файлы, которые опубликовал пишущий процесс, без задержки. Независимые диски с rsync или другим асинхронным копированием не подходят. Ни одна сетевая файловая система пока не сертифицирована, поэтому используйте шлюзы для нескольких процессов на одном сервере.
• Те же ключи сервисов. Дайте каждому процессу одинаковое содержимое ARKVORY_KEYS_FILE, чтобы файловые ключи и их ID совпадали. Управляемые ключи сервисов хранятся в базе данных, поэтому совпадают сами.
• Свой порт. Каждому процессу на одном узле нужен собственный ARKVORY_PORT.
• Представление файлов только для чтения. Где возможно, подключайте каталог хранилища файлов для шлюза только для чтения. Отказ на уровне HTTP не заменяет права операционной системы. Учтите, что шлюз всё равно пишет в базу данных: аренды, диагностику хранилища файлов, время последнего использования персональных токенов и блокировки, которые защищают читаемые файлы.
• Соединения с базой данных. Каждому шлюзу нужно на три соединения больше, чем ARKVORY_DATABASE_POOL_SIZE. Учитывайте их в max_connections PostgreSQL.

Запустите шлюз

Установщики регистрируют API, обработчик и агент резервного копирования. Шлюз они не регистрируют, и arkvory status им не управляет. Шлюз вы запускаете сами — как ещё один экземпляр программы API установленного выпуска, со своим окружением и под своим менеджером служб.

Настройки, общие для всех процессов, для двух процессов с общей скоростью 64 МиБ/с и 16 МиБ/с на одну учётную запись или ключ:

ARKVORY_GATEWAY_SLOTS=2
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND=67108864
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL=16777216

Пишущий процесс добавляет:

ARKVORY_ROLE=api
ARKVORY_GATEWAY_SLOT=0

Шлюз добавляет:

ARKVORY_ROLE=reader
ARKVORY_GATEWAY_SLOT=1
ARKVORY_PORT=8081

Шлюзу нужны и остальные настройки API: ARKVORY_DATABASE_URL той же базы данных, ARKVORY_DATA_DIR, который ведёт к тому же хранилищу файлов (путь может отличаться, идентичность хранилища должна совпадать), ARKVORY_KEYS_FILE и настройки HTTPS, если шлюз доступен с других компьютеров. См. Переменные окружения.

Переменная	Правило
ARKVORY_GATEWAY_SLOTS	Число процессов, включая пишущий, 2–16
ARKVORY_GATEWAY_SLOT	Слот этого процесса, от 0 до числа слотов минус один. У пишущего процесса 0, у шлюза не 0
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND	Обязательна. Общая скорость всех процессов, не менее 65 536, умноженных на число слотов, и не более 1 ТиБ в секунду
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL	Общая скорость для одной учётной записи или ключа по всем процессам. 0 означает «без ограничения». Иначе тот же диапазон, что выше

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

1. Решите, сколько будет слотов, и выберите скорости.
2. Добавьте пишущему процессу три общие переменные и две его собственные и перезапустите пишущий процесс. Он сохранит политику в базе данных.
3. Запустите шлюз с его собственными переменными. Если его числа отличаются от сохранённой политики, он не запустится.
4. Проверьте готовность каждого процесса и проверьте скачивание диапазона на каждом. См. Мониторинг шлюзов.
5. Только после этого добавьте шлюз в балансировщик нагрузки.

Несколько правил защищают эту схему:

• Шлюз можно запустить, только когда пишущий процесс сохранил политику.
• Когда политика уже есть в базе данных, пишущий процесс без этих переменных не запускается. Он останавливается с сообщением, что база данных требует общей конфигурации скачивания.
• Скорости и число слотов нельзя менять в работающей установке. См. Измените конфигурацию.

Лимит скачивания

Каждый процесс получает общая скорость / слоты с округлением вниз. То же относится к скорости для одной учётной записи или ключа. Например, при 64 МиБ/с и 2 слотах каждый процесс отдаёт до 32 МиБ/с, а одна учётная запись получает до 8 МиБ/с в каждом процессе.

• Процесс не может использовать долю другого. Если один из двух процессов остановлен, вы получаете половину общей скорости. Так лимит остаётся простым и проверяемым.
• Локальные настройки ARKVORY_DOWNLOAD_BYTES_PER_SECOND и ARKVORY_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL могут уменьшить долю, но не увеличить.
• Лимиты загрузки остаются на пишущем процессе, потому что шлюзы не принимают загрузки.
• Очередь ожидающих передач и предел активных передач остаются локальными для каждого процесса, поэтому возможности всех процессов складываются.

Лимит применяется к полезной нагрузке приложения с небольшим всплеском. Это не ограничение сетевого интерфейса. См. Переменные окружения.

Аренды и сбои

База данных резервирует слот на 10 секунд. Процесс продлевает аренду каждые 2 секунды и доверяет ей локально не более 8 секунд. Аренда, срок которой истёк, никогда не возобновляется, даже если пришёл запоздавший ответ.

• Аренда потеряна. Процесс перестаёт отдавать новые данные, на новые авторизованные запросы отвечает 503 и требует перезапуска. Оборванное скачивание можно продолжить повтором или запросом диапазона. Это относится и к пишущему процессу.
• Перезапуск того же слота. Новый процесс ждёт, пока истечёт старое резервирование, — до 10 секунд после его последнего продления и до 15 секунд всего. Если работающий шлюз всё ещё держит слот, новый процесс останавливается с busy.
• Часы. Аренды опираются на монотонные часы. Скачок часов сервера базы данных или остановленная виртуальная машина могут оставить процесс работающим дольше его аренды. В таком случае остановите старые процессы, прежде чем запускать замену.
• Сбой базы данных. База данных — слабое место. Если она станет недоступна, аренды истекут, и все процессы перестанут отдавать данные.

Сервер может заметить мёртвый процесс, потерявший сеть, только по TCP keepalive. Задайте в PostgreSQL tcp_keepalives_idle, tcp_keepalives_interval и tcp_keepalives_count, например 10, 5 и 3 секунды, или задайте tcp_user_timeout. Без них новый пишущий процесс или обработчик может ждать долгого тайм-аута операционной системы по умолчанию.

Мониторинг шлюзов

• GET /health/status публичен и возвращает только ready, unavailable или draining, а 503 — когда процесс не может обслуживать запросы (потерян слот или аренда, идёт плавная остановка). Используйте его для балансировщика нагрузки.
• GET /health/ready требует ключ. Он возвращает role, writable (на шлюзе всегда false), sharedDownloads с slot, slots, active и leaseSeconds, а также числа локальных очередей передач. При потере слота он отвечает 503. В автономной установке sharedDownloads равно null.
• GET /health/live показывает лишь, что процесс HTTP работает. Он не сообщает, может ли шлюз обслуживать запросы.
• GET /health/metrics каждого процесса показывает только этот процесс. Опрашивайте каждый шлюз и используйте метрики HTTP и передач на уровне процесса.

Проверяйте каждый процесс отдельно. Шлюз с writable равным false — это нормально. См. Мониторинг.

Маршрутизация запросов

Балансировщик нагрузки ваш. Arkvory не поставляет балансировщик.

• Отправляйте на пишущий процесс каждый запрос, который меняет данные, и /console/.
• Чтение байтов можно распределять между пишущим процессом и шлюзами: GET и HEAD для /api/v1/repositories/NAME/artifacts/ID/content, для .../packages/content и для .../asset/content. Остальные запросы оставляйте на пишущем процессе.
• Передавайте заголовки Authorization, Range, If-Range и ETag. Передавайте тело потоком, не буферизуя весь файл. Не перенаправляйте клиента на URL, который несёт ключ.
• Добавляйте сервер в балансировщик только тогда, когда его проверка готовности с аутентификацией в порядке.

SDK для TypeScript может продолжить прерванное скачивание через другой исправный сервер за тем же адресом. Работающее соединение TCP между серверами не переносится.

Измените конфигурацию

Нельзя менять скорости и число слотов, пока установка работает, и нельзя вернуться к одному процессу, пока политика существует. Даже если все шлюзы остановлены, сохранённая политика не даёт запуститься без лимитов.

1. Остановите входящий трафик. Остановите пишущий процесс, каждый шлюз и обработчик и убедитесь, что они действительно остановлены.
2. Подождите, пока истекут аренды в базе данных.
3. Сделайте резервную копию. См. Резервные копии.
4. Администратор базы данных Arkvory удаляет все строки таблиц arkvory_gateway_leases и arkvory_download_policy в одной транзакции. Это сбрасывает только состояние координации, но не каталог.
5. Запустите пишущий процесс с новыми настройками, затем шлюзы.

Никогда не делайте этого, пока может работать какой-либо процесс.

Обновление требует такой же осторожности. Остановите каждый шлюз до обновления установки и запустите их из нового выпуска после него. Шлюз, который продолжает работать со старым кодом на более новой схеме базы данных, сообщает, что не готов. Автономным инструментам восстановления для очистки тоже нужно, чтобы все шлюзы были остановлены. Онлайн-очистке пишущего процесса — нет.

Шлюзы или зеркала

	Шлюзы чтения	Зеркала
Что это	Больше процессов API на том же сервере и хранилище файлов	Вторая независимая установка с копией данных
Данные	Одна копия, читается напрямую	Вторая копия, которая забирается с задержкой
Учётные записи и ключи	Те же, что у пишущего процесса	Собственные
Дополнительный диск	Не нужен	Нужен, столько, сколько требуют репозитории
Что нужно	Та же база данных и та же файловая система	Канал HTTPS до источника и ключ только для чтения
Защищает от потери сервера или диска	Нет	Частично: обслуживает, пока источник недоступен, и на него можно переключиться
Для чего использовать	Больше параллельных скачиваний с одним общим лимитом скорости	Вторая площадка, офис ближе к пользователям, резервный сервер

И то и другое дополняет резервные копии, но не заменяет их.

Ограничения

• Все процессы должны делить один сервер и один каталог хранилища файлов. Для разных машин нужна файловая система, проверенная для такого случая, а ни одна пока не проверена.
• Нет поддержки в установщике, автоматического переключения и встроенного балансировщика.
• Одна база данных и один пишущий процесс остаются единой точкой отказа.
• Лимит фиксирован для слота и не перераспределяется, приоритетного планирования нет.
• Политику нельзя менять в работающей установке.

Связанные страницы

• Зеркала
• Мониторинг
• Самовосстановление
• Переменные окружения
• Обновления