Agave — це пряма спадкоємність валідаторного клієнта Solana Labs, який продовжує розвиток під новою організацією. Міграція зводиться до заміни бінарного файлу, оновлення конфігурації сервісу та перевірки синхронізації. Нижче — повний операційний runbook із вказаними ризиками, точками перевірки та шляхом відкату.

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

Чому відбувається перехід на Agave

Розробка валідаторного клієнта перейшла від організації Solana Labs до Anza. Agave — це той самий кодова база клієнта на Rust, але під новим репозиторієм, новим бінарним іменем та окремим циклом релізів. Усі подальші виправлення безпеки, оптимізації продуктивності та оновлення протоколу для цього клієнта виходитимуть саме в Agave. Solana Labs клієнт більше не отримує оновлень, тому продовжувати працювати на ньому — це прийняття невиправданого ризику пропуску критичних патчів.

Різниці між Solana Labs та Agave

Для операційної міграції мають значення такі фактичні відмінності:

  • Назва бінарного файлу. Замість solana використовується agave. Усі CLI-команди, які раніше починалися з solana-, тепер починаються з agave- (наприклад, agave-validator стає agave-validator).
  • Репозиторій. Джерелом істини став репозиторій anza-xyz/agave замість solana-labs/solana.
  • Шлях встановлення. За замовчуванням agave-install розміщував бінарні файли у ~/.local/share/solana/install/active_release/bin/. Agave використовує власний інсталятор із аналогічною структурою, але з іншим іменем каталогу.
  • Формат леджера та ключів. Леджер, identity keypair, vote-account keypair та авторизовані ключі повністю сумісні. Міграція леджера не потрібна.
  • Конфігураційні файли. Формат validator.yml (або аргументи командного рядка) зберігає зворотну сумісність. Проте деякі прапорці можуть бути позначені як застарілі або перейменовані — це треба перевіряти в changelog конкретного релізу.

Підготовка до міграції

Перед будь-якими діями переконайтеся, що виконані всі передумови.

Середовище перевірки

ОС: Ubuntu 24.04 LTS (amd64). Кластер: mainnet-beta. Клієнт джерела: Solana Labs validator. Клієнт призначення: Agave validator. Дата актуальності процедури: перевірте відповідність релізу Agave поточній рекомендованій версії в офіційному репозиторії anza-xyz/agave перед початком міграції.

Чек-лист передумов

  • Валідатор активний, не delinquent, голосує безперервно щонайменше 4 години до міграції.
  • Відомі поточна версія клієнта (solana --version) та цільова версія Agave (з офіційного релізу).
  • Наявність резервної копії identity keypair (validator-keypair.json).
  • Наявність резервної копії vote-account keypair (якщо зберігається локально).
  • Резервна копія файлу systemd-сервісу валідатора.
  • Вільне місце на диску: мінімум 20 ГБ для тимчасових файлів під час збірки або завантаження бінарного файлу.
  • Доступ до моніторингу (графіки CPU, RAM, мережі, слот-хайт) у реальному часі.
  • Зрозумілий план відкату (див. розділ із попередженнями нижче).

Резервне копіювання

Виконайте обов'язкове резервне копіювання перед зупинкою:

  • Identity keypair: cp ~/validator-keypair.json ~/validator-keypair.json.bak.$(date +%Y%m%d%H%M)
  • Vote-account keypair: аналогічно, якщо файл є на сервері.
  • Systemd сервіс: cp /etc/systemd/system/solana.service /etc/systemd/system/solana.service.bak.$(date +%Y%m%d%H%M)
  • Конфігурація: збережіть поточні аргументи запуску з файлу сервісу або з ps aux | grep agave-validator.

Кроки міграції

Крок 1. Фіксація поточного стану

Зафіксуйте поточний слот і версію для порівняння після міграції:

  • solana slot — запишіть значення.
  • solana --version — запишіть версію.
  • solana validators — переконайтеся, що валідатор не delinquent.

Крок 2. Коректна зупинка валідатора

Попередження: різка зупинка процесу (kill -9) може призвести до пошкодження останнього snapshot-файлу. Використовуйте лише graceful shutdown.

  • sudo systemctl stop solana
  • Дочекайтеся повної зупинки: sudo systemctl status solana має показати inactive (dead).
  • Перевірте, що процесу немає: ps aux | grep agave-validator — має повернути порожній результат.

Крок 3. Встановлення Agave

Перевірте актуальний метод встановлення в офіційному репозиторії anza-xyz/agave, оскільки процедура може змінюватися між релізами. Типовий шлях — завантаження попередньо зібраного бінарного файлу або збірка з вихідного коду.

Приклад завантаження попередньо зібраного релізу (перевірте актуальну URL-адресу релізу в репозиторії):

  • Завантажте архів із реліз-сторінки anza-xyz/agave.
  • Розпакуйте та встановіть: ./agave-install init (ім'я інсталятора може відрізнятися — перевірте в інструкції релізу).
  • Перевірте: agave --version — має показати версію Agave.

Крок 4. Оновлення systemd-сервісу

Відкрийте файл сервісу та замініть усі посилання на бінарний файл:

  • Замініть шлях до бінарного файлу з agave-validator на agave-validator.
  • Якщо використовувалися інші утиліти (наприклад, solana-ledger-tool у пре- або пост-командах), замініть їх на agave-ledger-tool.
  • Збережіть файл та перезавантажте конфігурацію: sudo systemctl daemon-reload.

Крок 5. Запуск валідатора на Agave

  • sudo systemctl start solana (ім'я сервісу лишається незмінним, змінюється лише вміст файлу).
  • Негайно перевірте статус: sudo systemctl status solana.
  • Почніть моніторинг журналів: sudo journalctl -u solana -f.

Шлях відкату

Якщо валідатор не стартує або показує критичні помилки:

  1. Зупиніть сервіс: sudo systemctl stop solana.
  2. Відновіть оригінальний файл сервісу: sudo cp /etc/systemd/system/solana.service.bak.{timestamp} /etc/systemd/system/solana.service.
  3. Виконайте sudo systemctl daemon-reload.
  4. Переконайтеся, що старий бінарний файл agave-validator досі присутній у системі (якщо видалили — відновіть із резервної копії або перевстановіть).
  5. Запустіть: sudo systemctl start solana.
  6. Перевірте журнали та слот-хайт.

Леджер та ключі не змінювалися під час міграції, тому відкат повертає валідатор у попередній робочий стан без втрати даних.

Перевірка працездатності після міграції

Після запуску виконайте послідовну перевірку:

Негайна перевірка (перші 2 хвилини)

  • Журнали без помилок: sudo journalctl -u solana --since "2 minutes ago" | grep -i error — має бути порожнім.
  • Процес живий: ps aux | grep agave-validator — процес присутній, споживає CPU та RAM.
  • Версія клієнта: agave --version — підтверджує Agave.

Перевірка синхронізації (перші 10 хвилин)

  • Слот-хайт зростає: виконуйте agave slot кілька разів з інтервалом 10–15 секунд. Значення має збільшуватися.
  • Відстань до кореня: agave block-height — порівняйте з останнім слотом з експлорера. Відставання не має перевищувати типове для вашого вузла.

Перевірка голосування (перші 30 хвилин)

  • Голосування підтверджено: agave vote-account ~/vote-account-keypair.json — перевірте, що last_vote зростає.
  • Статус валідатора: agave validators — ваш валідатор має бути в списку активних, без позначки delinquent.

Повна перевірка (через 1–2 години)

  • Перевірте моніторинг: графіки CPU, RAM, мережевого I/O мають відповідати типовому профілю вашого вузла.
  • Перевірте, що кредити голосування накопичуються: порівняйте значення credits до і після міграції.
  • Перевірте, що RPC-endpoint (якщо працює на тому ж вузлі) відповідає на запити: curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' http://127.0.0.1:8899 — має повернути "ok".

Типові проблеми при міграції

Бінарний файл не знайдено після оновлення сервісу

Симптом: systemd повідомляє про помилку запуску, journalctl показує Exec format error або No such file or directory.

Причина: шлях до agave-validator у файлі сервісу вказує некоректно, або бінарний файл встановлений у каталог, який не входить у PATH systemd-сервісу.

Рішення: виконайте which agave-validator, скопіюйте повний шлях і вставте його у файл сервісу як абсолютний шлях до ExecStart. Після цього sudo systemctl daemon-reload та перезапуск.

Застарілі прапорці командного рядка

Симптом: валідатор стартує, але в журналах з'являються попередження про deprecated flags, або деякі параметри ігноруються.

Причина: між останньою версією Solana Labs і поточною версією Agave деякі CLI-прапорці були перейменовані або вилучені.

Рішення: перевірте changelog релізу Agave на предмет змін у CLI. Замініть застарілі прапорці на актуальні. Не ігноруйте ці попередження — параметр, що ігнорується, може змінити поведінку вузла (наприклад, налаштування gossip-порту або ліміти пам'яті).

Валідатор delinquent після перезапуску

Симптом: agave validators показує delinquent статус.

Причина: валідатор був зупинений надто довго і пропустив занадто багато епох без голосування, або після запуску не зміг швидко наздогнати кластер.

Рішення: переконайтеся, що слот-хайт зростає. Якщо зростає — статус delinquent зникне автоматично після накопичення достатньої кількості голосів у наступних епохах. Якщо слот не зростає — діагностуйте причину (мережа, диск, RAM) за журналами.

Проблеми з snapshot-файлами

Симптом: валідатор стартує, але показує помилки десеріалізації snapshot або повільну синхронізацію з нуля.

Причина: у рідкісних випадках зміна формату внутрішніх структур між версіями може зробити останній snapshot несумісним.

Рішення: Agave автоматично створює новий snapshot під час синхронізації. Якщо старий snapshot викликає помилку, валідатор відступить до більш раннього snapshot або розпочне синхронізацію з genesis/frozen-точки. Це нормально, але займе час. Переконайтеся, що на диску достатньо місця для створення нового snapshot.

Конфлікт портів із залишковим процесом

Симптом: помилка Address already in use при спробі запустити agave-validator.

Причина: попередній процес agave-validator не був повністю зупинений, або інший процес зайняв ті самі порти (gossip 8001, RPC 8899 тощо).

Рішення: sudo lsof -i :8001 -i :8899 — знайдіть процес, що займає порти. Якщо це залишковий процес старого клієнта — завершіть його. Якщо це інший сервіс — змініть порти у конфігурації.

Джерела