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

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

Середовище перевірки: клієнт — Agave (форк solana-labs/solana), ОС — Ubuntu 24.04 LTS, кластер — mainnet-beta. Конкретні версії бінарних файлів та хеші комітів перевірте у своєму оточенні перед виконанням команд.

Ознаки невдалого оновлення

Оновлення вважається невдалим, якщо після перезапуску сервісу валідатор не відновив синхронізацію з кластером протягом розумного часу (зазвичай 2–5 хвилин для звичайного рестарту). Ключові індикатори:

  • Статус systemd — сервіс перебуває у стані failed або постійно перезапускається (цикл crash-loop).
  • Логи старту — відсутність рядка про успішне підключення до gossip-мережі або наявність panic у Rust-вихлопі.
  • Метрики — значення slot_height зупинилося, vote_latency відсутнє, моніторинг фіксує втрату heartbeat.
  • CLI-перевірка — команда solana slot повертає помилку або значення, що не зростає.
  • Поведінка RPC — endpoint повертає 503 або таймаути на getHealth.

Окремий випадок — валідатор стартує, але починає відставати за слотами без видимих помилок. Це також ознака проблеми, пов’язаної з оновленням (наприклад, несумісність форматів snapshot).

Збір діагностичної інформації

Перш ніж втручатися в систему, зафіксуйте поточний стан. Це потрібно для аналізу причини та можливого зворотного зв’язку з розробниками клієнта.

Логи systemd

Отримайте повний журнал останнього запуску:

Команда: journalctl -u agave-validator --no-pager -b -0

Якщо сервіс перезапускався кілька разів, додайте прапорець -n 500 для обмеження виводу або використайте --since для вузького вікна часу. Збережіть лог у файл перед подальшими діями:

Команда: journalctl -u agave-validator --no-pager -b -0 > /root/failed-update-journal.log

Шукайте в логах: panic, Error (з великої літери — це Rust-макрос), snapshot, ledger, accounts_db, incompatible, version mismatch.

Стан ledger

Перевірте цілісність та версію snapshot, з якого завантажується валідатор:

Команда: ls -lah /mnt/ledger/snapshots/

Зверніть увагу на дату створення останнього snapshot та його розмір. Аномально малий розмір або відсутність файлів snapshot — пряма ознака пошкодження. Перевірте також наявність та розмір файлу status_cache.dat у робочому каталогу.

Для перевірки версії формату snapshot виконайте:

Команда: solana-ledger-tool verify --ledger /mnt/ledger 2>&1 | head -50

Ця команда може виявити несумісність між версією бінарного файлу та форматом існуючого ledger.

Мережеві помилки

Виключіть мережеві проблеми як первинну причину:

Команда: solana gossip --entrypoint entrypoint.mainnet-beta.solana.com:8001

Якщо gossip не отримує відповідей від достатньої кількості peer-вузлів, проблема може бути не в оновленні, а в мережевому доступі, фаєрволі або DNS. Перевірте також, чи не змінився порт gossip або RPC у новій версії конфігурації.

Типові причини невдач

  • Несумісність формату snapshot. Нова версія клієнта очікує іншу структуру snapshot, ніж та, що збережена на диску. Найчастіша причина при стрибках між мінорними версіями.
  • Зміна структури accounts-db. Міграція схеми бази рахунків не завершилася через нестачу пам’яті або дискового простору під час першого запуску.
  • Видалення або перезапис конфігураційного файлу. Скрипт оновлення перезаписав validator.yml або аргументи запуску в systemd-юніті, і валідатор стартує з неправильними параметрами.
  • Несумісність бінарних залежностей. Нова версія вимагає іншу версію системної бібліотеки (наприклад, glibc, openssl), яка відсутня в поточній ОС.
  • Недостатньо RAM для міграції. Під час першого запуску після оновлення клієнт може потребувати більше пам’яті для перебудови індексів accounts-db.
  • Залишок старих бінарних файлів. Конфлікт між старою та новою версією в PATH, коли systemd продовжує викликати попередній бінарний файл.

План виправлення: крок за кроком

Передумови: у вас є доступ до сервера під root або через sudo; ви знаєте, яку версію клієнта встановлювали та з якої відкатуєтесь; ledger не пошкоджений на рівні файлової системи.

Ризики: втрата останніх слотів з моменту останнього snapshot при відкаті; тривалий даунтайм під час повторного завантаження ledger.

  1. Зупиніть сервіс.
    systemctl stop agave-validator
    Переконайтеся, що процеси повністю зупинені: pgrep -f agave-validator має повернути порожній результат.
  2. Зафіксуйте версію, що викликала збій.
    agave-validator --version > /root/failed-version.txt
    Це потрібно для точного відкату та звіту.
  3. Визначте причину за логами.
    Використайте збережений журнал. Якщо причина — несумісність snapshot, перейдіть до кроку 4. Якщо — конфігурація, перейдіть до кроку 5. Якщо — залежності, до кроку 6.
  4. Видалення snapshot та повторна синхронізація (якщо snapshot несумісний).
    ⚠️ Попередження: ця дія видаляє локальний snapshot. Валідатор буде змушений завантажити свіжий snapshot з кластера або відновитися з genesis + replay, що значно подовжує час запуску.
    Резервний шлях: перед видаленням скопіюйте каталог snapshot: cp -r /mnt/ledger/snapshots /mnt/ledger/snapshots.bak.$(date +%s)
    rm -rf /mnt/ledger/snapshots/*
  5. Перевірка та відновлення конфігурації.
    Порівняйте поточний конфіг з резервною копією (якщо вона є): diff /etc/solana/validator.yml /etc/solana/validator.yml.bak
    Перевірте systemd-юніт: systemctl cat agave-validator
    Виправте розбіжності та перезавантажте конфігурацію systemd: systemctl daemon-reload
  6. Встановлення попередньої стабільної версії.
    Використайте той самий метод встановлення, що й раніше (binary release, source build, agave-install), але вкажіть відому робочу версію. Переконайтеся, що в PATH немає залишків нової версії: which agave-validator та agave-validator --version.
  7. Запуск із попередньою версією.
    systemctl start agave-validator
    Одразу перевірте логи: journalctl -u agave-validator -f
    Очікуваний результат: валідатор підключається до gossip, завантажує snapshot (або починає replay), починає голосувати.
  8. Верифікація синхронізації.
    solana slot — значення має зростати.
    solana validators — ваш валідатор має бути у списку з актуальним слотом.
    Перевірте відставання: порівняйте ваш слот із кореневим слотом кластера через будь-який публічний RPC.

Коли потрібен повний відкат

Повний відкат до попередньої версії бінарного файлу є єдиним правильним рішенням у таких випадках:

  • Panic у Rust-вихлопі під час старту з чітким вказанням на несумісність даних (accounts-db, snapshot, status-cache).
  • Цикл crash-loop без можливості стабільного запуску навіть із очищеним snapshot.
  • Відсутність офіційного патчу для виявленої проблеми у новій версії.
  • Ризик пропуску слотів перевищує допустимий поріг вашої інфраструктури, а час на діагностику обмежений.

⚠️ Попередження: відкат на версію, яка вже відстала від кластера більш ніж на кілька епох, може призвести до неможливості синхронізації через обмеження gossip. Перевірте актуальність версії, на яку відкатуєтесь, у офіційному репозиторії клієнта.

Якщо повний відкат неможливий (наприклад, кластер вже перейшов на нову версію протоколу, і старий клієнт не приймається), зверніться до документації клієнта та каналу інцидентного реагування вашої команди. Міграція ledger між клієнтами розглядається в окремому матеріалі.

Запобігання повторній невдачі

  • Тестове середовище. Застосовуйте будь-яке оновлення спочатку на testnet- або devnet-вузлі з копією конфігурації. Це виявляє проблеми несумісності snapshot та конфігурації до впливу на mainnet.
  • Резервне копіювання конфігурації. Перед кожним оновленням створюйте копії validator.yml, systemd-юніта та змінних середовища з позначкою дати та версії.
  • Фіксація версій. Використовуйте явне вказання версії при встановленні (наприклад, через тег релізу), а не latest. Це робить відкат детермінованим.
  • Перевірка release notes. Перед оновленням читайте нотатки до релізу в репозиторії клієнта. Шукайте розділи Breaking Changes, Migration, Snapshot compatibility.
  • Моніторинг першого запуску. Після оновлення не залишайте процес без нагляду. Спостерігайте за логами перших 5–10 хвилин — саме тоді проявляються проблеми міграції даних.
  • Резервний вузол. Наявність другого валідатора з відкладеним оновленням дозволяє уникнути простою під час діагностики. Процес роботи з резервним вузлом під час оновлення описано в окремій інструкції.

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

Джерела