Цей матеріал описує операційну конфігурацію snapshot-джерела та генератора для валідатора Solana. Ви дізнаєтесь, як підключитися до зовнішнього snapshot-джерела, налаштувати власну генерацію, керувати кількістю та частотою snapshots, а також організувати моніторинг процесу.

Операційні вимоги для «Як налаштувати snapshot-джерело та генератор» перевірено 2 серпня 2026 року. Для production використовуйте тільки реліз Agave, рекомендований для конкретного кластера, і звіряйте параметри з agave-validator --help . Офіційні вимоги Anza на цю дату орієнтують операторів на Ubuntu 24.04, щонайменше 12 ядер/24 потоки, 256 ГБ RAM, окремі швидкі NVMe та симетричний канал від 2 Гбіт/с; це рекомендації, а не гарантія достатньої продуктивності.

Середовище перевірки: клієнт Agave (githash та точну версію перевірте у своєму середовищі командою agave-validator --version), кластер mainnet-beta, ОС Ubuntu 24.04 LTS. Конфігураційні прапорці та значення за замовчуванням можуть відрізнятися між версіями — обовʼязково перевіряйте актуальну документацію до вашого релізу.

Що таке snapshot-джерело (snapshot source)

Snapshot у Solana — це серіалізований стан бази даних акаунтів (accounts database) на конкретному слоті. Він містить повну картину всіх акаунтів, їхніх балансів та даних без необхідності відтворювати кожну транзакцію від genesis. Snapshot-джерело — це HTTP-ендпоінт, з якого валідатор завантажує готовий snapshot під час bootstrap-процесу.

Без snapshot-джерела новий вузол змушений відтворювати весь леджер від початку, що на mainnet-beta займає тижні. Зі snapshot-джерелом час знижується до годин, залежно від швидкості диска та мережі.

Типи snapshot-джерел:

  • Вбудоване (default) — клієнт Agave містить hardcoded список відомих snapshot-серверів, що підтримуються інфраструктурною командою Solana.
  • Зовнішнє (custom) — будь-який HTTP-сервер, який роздає валідні snapshot-файли у правильній структурі каталогів.

Кожен snapshot складається з повного snapshot (full snapshot) та одного або кількох інкрементних snapshots (incremental snapshots), які містять лише зміни від попереднього повного. Клієнт завантажує останній повний snapshot і всі необхідні інкрементні після нього.

Як вказати зовнішній snapshot у конфігурації

Для підключення до зовнішнього snapshot-джерела використовується прапорець --snapshot-url. Його можна передати безпосередньо при запуску або прописати у файлі конфігурації сервісу.

Приклад командного рядка:

agave-validator --snapshot-url https://snapshot.example.com/snapshots ...

У файлі конфігурації systemd (Override або безпосередньо у unit-файлі):

ExecStart=/usr/bin/agave-validator --snapshot-url https://snapshot.example.com/snapshots --ledger /mnt/ledger ...

Можна вказати кілька джерел — клієнт спробує їх послідовно:

--snapshot-url https://primary.example.com/snapshots --snapshot-url https://backup.example.com/snapshots

Що потрібно перевірити:

  • URL має бути доступний з вашого сервера (перевірте curl -I <URL> — має повернути HTTP 200 або коректний listing).
  • Сервер має підтримувати range-запити (HTTP 206 Partial Content) — клієнт завантажує snapshot частинами з паралельними зʼєднаннями.
  • SSL-сертифікат має бути валідним, якщо використовується HTTPS.
  • Шлях у URL має відповідати структурі каталогів, яку очікує клієнт. Перевірте актуальний формат у документації вашої версії Agave — у деяких релізах клієнт автоматично додає суфікс шляху до базового URL.

Вимкнення завантаження snapshots:

Якщо ви навмисно бажаєте відтворювати леджер без snapshot (наприклад, для аудиту), використовуйте --no-snapshot-fetch. Це значно подовжить час синхронізації.

Налаштування генерації власних snapshots

Генерація snapshots увімкнена за замовчуванням для кожного валідатора. Валідатор періодично створює повний та інкрементні snapshots у підкаталозі snapshots/ всередині директорії леджера.

Ключові прапорці:

  • --snapshots (за замовчуванням увімкнено) — загальне увімкнення/вимкнення механізму snapshot.
  • --no-snapshot-generation — вимикає лише генерацію, але залишає можливість завантажувати сторонні snapshots.

Ручне створення snapshot за допомогою solana-ledger-tool:

solana-ledger-tool create-snapshot --ledger /mnt/ledger <slot> /mnt/ledger/snapshots

Де <slot> — це слот, для якого ви маєте повний стан. Інструмент створить повний snapshot у вказаній директорії. Перевірте, що вказаний слот є коректним слотом епохи (epoch boundary) або що ваша версія клієнта підтримує створення snapshot на довільному слоті — це залежить від релізу.

Вимоги до інфраструктури для генерації:

  • Достатній вільний простір на диску з леджером — повний snapshot mainnet-beta займає значний обсяг (перевірте актуальний розмір у вашому середовищі командою du -sh /mnt/ledger/snapshots/).
  • Диск має забезпечувати прийнятну швидкість послідовного запису — під час генерації snapshot створюється тимчасовий файл, який потім стискається.
  • Під час створення snapshot навантаження на I/O зростає. На вузлах з обмеженим диском це може вплинути на затримку голосування.

Частота генерації та зберігання

Інтервал генерації:

Прапорець --snapshot-interval-slots визначає, як часто створюються інкрементні snapshots. Значення за замовчуванням перевірте у вашій версії командою agave-validator --help або в документації релізу. Повний snapshot створюється на початку кожної епохи.

Кількість збережених snapshots:

Прапорець --maximum-snapshots-to-retain контролює, скільки повних snapshots зберігається на диску. Коли ліміт перевищується, найстаріший повний snapshot та повʼязані з ним інкрементні видаляються автоматично. Перевірте значення за замовчуванням для вашої версії — типово це невелика кількість (2–4), що достатньо для відкату в межах кількох епох.

Практичні рекомендації:

  • Не зменшуйте --maximum-snapshots-to-retain нижче за замовчуванням, якщо не маєте вагомої причини — це обмежить ваші можливості відновлення.
  • Збільшення цього значення лінійно збільшує споживання дискового простору. Розраховуйте: розмір одного повного snapshot помножити на бажану кількість.
  • Інкрементні snapshots значно менші за повні, але їхня кількість залежить від інтервалу та довжини епохи.

Ризик при ручному видаленні snapshots:

Попередження: Ніколи не видаляйте snapshot-файли вручну з файлової системи, поки валідатор працює. Це може призвести до пошкодження стану або паніки клієнта. Якщо потрібно звільнити місце, змініть --maximum-snapshots-to-retain і перезапустіть валідатор — клієнт сам видалить зайві файли коректно.

Резервний шлях: Якщо ви вже вручну видалили файли і валідатор не стартує, зупиніть сервіс, завантажте свіжий snapshot із зовнішнього джерела (переконайтеся, що --snapshot-url вказано) і запустіть валідатор з прапорцем --no-snapshot-generation для початкового відновлення, після чого приберіть цей прапорець.

Як інші валідатори завантажують ваші snapshots

Якщо ви хочете надавати свої snapshots іншим операторам, вам потрібно розгорнути HTTP-сервер, який роздає вміст директорії snapshots/ вашого леджера.

Мінімальна конфігурація nginx:

Налаштуйте location, що вказує на /mnt/ledger/snapshots/, з увімкненим autoindex для листингу файлів та підтримкою range-запитів (за замовчуванням nginx їх підтримує).

Вимоги до публічного snapshot-сервера:

  • Доступність: сервер має бути доступний з мережі інтернет на порту 80 або 443.
  • Range-запити: обовʼязкова умова — без них клієнт не зможе завантажувати snapshot частинами і процес значно сповільниться.
  • Швидкість віддачі: bottleneck для завантаження — це не процесор, а мережевий канал. Розраховуйте на те, що один повний snapshot mainnet-beta — це гігабайти стиснених даних.
  • Актуальність: клієнт, що підключається до вашого джерела, очікує знаходити там snapshot поточної або попередньої епохи. Якщо ваш валідатор відстав, ваші snapshots будуть непридатні для bootstrap.
  • Цілісність: клієнт перевіряє SHA256-хеш завантаженого файлу. Переконайтеся, що файли .sha256 генеруються разом із snapshot і доступні за тим самим URL.

Як інший оператор підключається до вашого сервера:

Він вказує ваш URL через --snapshot-url https://your-server.example.com/snapshots. Клієнт звертається до вашого сервера, отримує список доступних snapshots, обирає найсвіжіший повний snapshot із відповідними інкрементними та завантажує їх.

Обмеження: публікація snapshots створює навантаження на ваш мережевий канал і може вплинути на роботу самого валідатора. Розгляньте використання окремого сервера або CDN для роздачі, копіюючи snapshot-файли туди асинхронно.

Моніторинг snapshot-процесу

Операційний моніторинг snapshot-процесу охоплює три аспекти: створення, завантаження та споживання дискового простору.

Журнали створення snapshot:

У stdout валідатора шукайте повідомлення, що містять ключове слово snapshot. Типові повідомлення:

  • Повідомлення про початок створення повного snapshot на початку епохи.
  • Повідомлення про завершення стиснення та запису.
  • Повідомлення про видалення старих snapshots при обмеженні --maximum-snapshots-to-retain.

Перевірка наявності та розміру snapshots:

ls -lh /mnt/ledger/snapshots/

du -sh /mnt/ledger/snapshots/

Регулярно перевіряйте, що нові snapshots зʼявляються з очікуваною періодичністю. Якщо повний snapshot не створюється на межі епохи — це сигнал проблеми з I/O або місцем на диску.

Моніторинг дискового простору:

  • Налаштуйте алерт на відсоток заповнення файлової системи з леджером. Критичний поріг залежить від розміру вашого диска, але загальне правило — тримати щонайменше обсяг, рівний двом повним snapshots, вільним.
  • Відстежуйте динаміку зростання директорії snapshots/ — різкий стрибок може вказувати на проблему з видаленням старих файлів.

Моніторинг завантаження snapshot (при bootstrap):

Якщо ваш вузол завантажує snapshot із зовнішнього джерела, у журналах відображається прогрес завантаження з вказанням розміру та швидкості. Якщо завантаження зависає або дуже повільне — перевірте мережеве зʼєднання та доступність snapshot-джерела.

Перевірка цілісності snapshot:

Клієнт автоматично верифікує хеш після завантаження. Якщо хеш не збігається, файл відкидається і завантажується повторно або з наступного джерела. У журналах це супроводжується відповідним повідомленням про невідповідність хешу.

Типові проблеми та діагностика:

  • Snapshot не створюється: перевірте вільне місце (df -h /mnt/ledger), перевірте, що прапорець --no-snapshot-generation не встановлено, перегляньте журнали на наявність помилок I/O.
  • Старі snapshots не видаляються: перевірте значення --maximum-snapshots-to-retain, переконайтеся, що процес валідатора має права на видалення файлів у директорії snapshots.
  • Зовнішнє джерело недоступне: перевірте DNS, мережеву доступність, SSL-сертифікат, наявність range-підтримки на сервері.
  • Завантажений snapshot відхиляється: перевірте, що джерело віддає актуальні snapshots для вашого кластера, перевірте хеш-файли на сервері джерела.

Наступний крок: після налаштування snapshot-джерела та генератора рекомендуємо ознайомитися з матеріалом про перенесення валідатора на новий сервер без втрати даних, де snapshots відіграють ключову роль у процесі міграції.

Джерела