Операційні вимоги для «Конфігураційний файл валідатора: ключові параметри» перевірено 2 серпня 2026 року. Для production використовуйте тільки реліз Agave, рекомендований для конкретного кластера, і звіряйте параметри з agave-validator --help . Офіційні вимоги Anza на цю дату орієнтують операторів на Ubuntu 24.04, щонайменше 12 ядер/24 потоки, 256 ГБ RAM, окремі швидкі NVMe та симетричний канал від 2 Гбіт/с; це рекомендації, а не гарантія достатньої продуктивності.
Конфігураційний файл config.yml — це єдина точка, де валідатор Solana отримує всі необхідні параметри для запуску: шляхи до ключів, розташування ledger, мережеві налаштування та обмеження ресурсів. Помилка в одному рядку цього файлу здатна зупинити ноду або призвести до втрати слотів. Нижче — детальний розбір кожного значущого параметра з прикладами, обмеженнями та діагностичними підказками.
Клієнт: Agave (колишній solana-labs/solana)
Кластер: mainnet-beta, testnet, devnet
ОС: Ubuntu 24.04 LTS
Дата перевірки: червень 2025
Розташування та формат config.yml
За замовчуванням Agave шукає конфігураційний файл у робочій директорії процесу під іменем config.yml. Типовий шлях для стандартного розгортання:
~/solana/config.yml
Формат — YAML. Важливо дотримуватися правил цього формату: відступи виключно пробілами (два пробіли на рівень), без табуляцій. Коментарі починаються з символу #.
Якщо файл відсутній, валідатор використовує вбудовані значення за замовчуванням, що майже ніколи не підходить для продакшен-ноди. Тому створення коректного config.yml — обовʼязковий крок до першого запуску.
Перевірити, який саме файл використовує запущений процес, можна через аргументи командного рядка у /proc/<pid>/cmdline</pid> або у конфігурації systemd-сервісу (детальніше — у розділі Як налаштувати systemd service для валідатора).
Identity та vote account у конфігурації
Ці два параметри визначають, хто саме валідує блоки та куди направляються голоси.
identity-path — абсолютний шлях до ключового файлу identity (keypair). Цей ключ є унікальним ідентифікатором ноди в мережі. Він не підлягає заміні без повторної реєстрації валідатора.
identity-path: /home/solana/validator-keypair.json
vote-account-path — абсолютний шлях до ключового файлу vote account. Цей акаунт створюється окремо і реєструється в мережі через solana create-vote-account.
vote-account-path: /home/solana/vote-account-keypair.json
Перевірка відповідності
Перед запуском варто переконатися, що pubkey з identity-файлу збігається з тим, що зареєстрований у vote-акаунті:
solana address -k /home/solana/validator-keypair.json
solana vote-account /home/solana/vote-account-keypair.json
У виводі vote-account має бути вказано identity pubkey вашої ноди в полі authorized voter або node. Якщо pubkey не збігається — голоси не будуть зараховані.
Застереження: ніколи не копіюйте identity-keypair на інші сервери. Втрата контролю над цим файлом означає втрату контролю над валідатором.
Ledger path та snapshot path
ledger-path — директорія, де Agave зберігає леджер: файли слотів, блоків, підписів та індексів. Для mainnet-beta це найбільш ємний каталог на диску.
ledger-path: /mnt/ledger
Рекомендована файлова система — XFS або ext4 з увімкненим journaling. Для NVMe-дисків XFS зазвичай показує кращу продуктивність при великих послідовних записах.
snapshot-path — директорія для зберігання повних та інкрементальних снапшотів. Якщо цей параметр не вказано, снапшоти зберігаються всередині ledger-path.
snapshot-path: /mnt/snapshots
Чому розділяти ledger і snapshots
- Снапшоти завантажуються та розпаковуються при старті ноди. Якщо вони на тому ж диску, що й активний леджер, I/O конкурує.
- Роздільне розташування дозволяє монтувати snapshots на меншому диску (снапшоти займають значно менше місця, ніж повний леджер).
- При аварійному відновленні окремий snapshot-path дозволяє швидко замінити снапшот без торкання леджера.
Перевірити фактичне використання дискового простору:
du -sh /mnt/ledger /mnt/snapshots
Вказівка entrypoint та відомих валідаторів
entrypoint — початкова точка підключення до кластера. Це адреса у форматі IP:порт, через яку нода вперше встановлює звʼязок із мережею.
entrypoint: 127.0.0.1:8001 (для локального devnet)
entrypoint: mainnet.solana.com:8001 (приклад для mainnet-beta)
Після першого підключення нода отримує список активних пірів через gossip-протокол, тому entrypoint використовується лише на етапі ініціалізації.
known-validatores — список pubkey валідаторів, яким нода довіряє при формуванні початкового набору пірів. Формат — масив рядків.
known-validatores:
- 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
- 9ZNTfG4NyQgxy2SWjSiQoUyBPEvXT2xo7fKc5hPYYJ7b
Якщо цей параметр порожній або відсутній, нода покладається виключно на entrypoint. Для mainnet-beta рекомендується вказати 3–5 стабільних валідаторів із високим uptime — це прискорює початкову синхронізацію та захищає від підміни пірів.
Актуальний список pubkey провідних валідаторів варто брати з незалежних джерел (моніторинги кластера) і періодично оновлювати.
Параметри мережі: порт, gossip
gossip-port — TCP-порт для gossip-протоколу, через який нода обмінюється інформацією про стан кластера, слоти, піри та snapshot-доступність. За замовчуванням 8001.
gossip-port: 8001
rpc-port — порт для JSON-RPC інтерфейсу. За замовчуванням 8899. Якщо ви не плануєте надавати публічний RPC, цей порт можна залишити без змін, але обмежити доступ через firewall.
rpc-port: 8899
bind-address — IP-адреса, на якій нода слухає вхідні зʼєднання. Якщо вказано 0.0.0.0, нода слухає на всіх інтерфейсах. Для продакшен-середовищ зазвичай вказують конкретну IP-адресу сервера.
bind-address: 10.0.1.50
dynamic-port-range — діапазон UDP-портів для transmit-трафіку (блоки, голоси, blob-дані). За замовчуванням 8000-8020.
dynamic-port-range: "8000-8020"
Цей діапазон має бути відкритий у firewall для UDP. Якщо порти закриті, нода не зможе отримувати блоки та передавати свої голоси, що призведе до пропуску слотів.
Перевірка мережевої доступності
З іншого сервера перевірте досяжність gossip-порту:
nc -zv <ip_валідатора> 8001</ip_валідатора>
У журналах валідатора (agave-validator.log) при успішному gossip-зʼєднанні зʼявляються записи типу:
[2025-06-10T12:00:00.000000000Z INFO] gossip: new peer 7xKXtg... score=100.0
Обмеження ресурсів: RAM, слоти
Agave споживає значний обсяг оперативної памʼяті. Без явних обмежень процес може викликати OOM-killer, що призведе до жорсткої зупинки ноди.
accounts-index-memory-limit — максимальний обсяг RAM для індексу акаунтів. Значення в байтах або з суфіксом GB/MB.
accounts-index-memory-limit: 64GB
Для mainnet-beta нині рекомендується не менше 48–64 ГБ під цей індекс. Занадто низьке значення призведе до постійного витіснення (eviction) акаунтів з памʼяті та деградації продуктивності.
limit-ledger-size — максимальний розмір леджера на диску у гігабайтах. Після досягнення цього ліміту Agave починає видаляти найстаріші слоти.
limit-ledger-size: 500000 (приблизно 500 ТБ — фактично без обмеження)
Для валідаторів, що не зберігають повний історичний леджер, це значення можна знизити до розумного обсягу (наприклад, 200000), щоб запобігти переповненню диска. Але варто розуміти: якщо диск заповниться до того, як спрацює цей ліміт, нода зупиниться з помилкою запису.
slots-to-keep — кількість слотів, що зберігаються в леджері після компактифікації. За замовчуванням зберігається повний леджер. Для нод без архівного призначення це значення можна зменшити.
slots-to-keep: 5000
Застереження: зміна slots-to-keep на вже працюючій ноді є необоротною операцією. Старі слоти будуть видалені під час наступної компактифікації. Якщо вам знадобиться відновити історію — доведеться завантажувати повний снапшот заново.
Типові помилки в конфігурації
Хибні шляхи до ключових файлів
Найчастіша причина неможливості запустити ноду — вказівка відносного шляху замість абсолютного, або помилка в імені файлу. Agave не створює ключові файли автоматично: якщо файл відсутній, процес завершується з помилкою.
Перевірка:
test -f /home/solana/validator-keypair.json && echo "OK" || echo "MISSING"
Відсутність прав на запис до ledger-path
Якщо користувач, від імені якого запущено валідатор, не має прав на запис у вказану директорію, процес завершується на етапі ініціалізації леджера. Перевірте:
sudo -u solana test -w /mnt/ledger && echo "WRITABLE" || echo "NOT WRITABLE"
Конфлікт портів
Якщо на сервері вже запущено інший процес (наприклад, попередній екземпляр валідатора), порти 8001, 8899 або діапазон 8000–8020 будуть зайняті. У журналі зʼявиться помилка типу Address already in use.
Діагностика:
ss -tulpn | grep -E '8001|8899|800[0-9]'
Невідповідність кластера та entrypoint
Якщо ви налаштовуєте ноду для mainnet-beta, але entrypoint вказує на testnet-адресу (або навпаки), нода підключиться до неправильного кластера. Це може призвести до непередбачуваної поведінки, включно з спробою голосувати в чужому кластері.
Завжди перевіряйте entrypoint проти офіційних даних кластера перед першим запуском. Детальніше про специфіку запуску на різних кластерах — у розділі Як запустити валідатор на mainnet-beta.
YAML-синтаксичні помилки
Табуляції замість пробілів, пропущені двокрапки після ключа, некоректні лапки — усе це робить файл невалідним. Agave повідомить про помилку парсингу, але повідомлення може бути неочевидним.
Валідація перед запуском:
python3 -c "import yaml; yaml.safe_load(open('/home/solana/config.yml'))" && echo "VALID" || echo "INVALID"
Ця команда не перевіряє семантику параметрів, але гарантує, що файл є коректним YAML і буде прочитаний клієнтом.