Оновлення, міграція та відкат

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

Операційне життєвий цикл валідатора Solana неможливий без регулярних оновлень клієнта. Кожен реліз виправляє вразливості, змінює поведінку консенсусу або додає нові типи транзакцій. Пропуск оновлення — це пряма загроза делегованому стейку та репутації оператора. Цей розділ дає повний операційний довідник: від перевірки нової версії Agave до повного відкату та міграції ledger між клієнтами.

Як оновити валідатор без зайвого простою

Чому регулярні оновлення критичні

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

Перевірка актуальної версії Agave

Перед будь-якими діями визначте поточний стан:

Виконайте agave-validator --version на сервері валідатора та зафіксуйте результат.
Перевірте актуальну стабільну версію в офіційному репозиторії Agave на GitHub — порівняйте з вашою.
Перевірте, чи не наближається scheduled upgrade кластера (зазвичай оголошується в офіційних каналах).

Завантаження та верифікація нового release

Середовище: Ubuntu 24.04 LTS (або ваша ОС), клієнт Agave, mainnet-beta. Перевірте актуальну версію та хеш-суму в реліз-нотатках перед завантаженням.

Завантажте бінарний файл або вихідний код виключно з офіційного репозиторію Agave.
Перевірте SHA256 хеш-суму завантаженого артефакту з тією, що вказана в релізі.
Якщо збираєте з вихідного коду — переконайтеся, що використовуєте тег відповідного релізу, а не гілку main.

Ризик: Завантаження з дзеркал або неперевірених джерел може призвести до встановлення скомпрометованого бінарного файлу.

Стратегія rolling update

Повністю безперервне оновлення валідатора Solana неможливе — процес потрібно перезапустити. Проте downtime можна мінімізувати:

Hot-swap бінарного файлу: заміна виконуваного файлу до зупинки процесу дозволяє скоротити час простою до одного перезапуску.
Резервний вузол: другий валідатор із тим самим identity продовжує обслуговувати запити під час оновлення основного.
Точкове вікно: оновлення виконується в момент низького навантаження на кластер, коли пропускна здатність слотів мінімальна.

Кроки оновлення з мінімальним downtime

Збережіть поточний бінарний файл як резервну копію: cp /usr/local/bin/agave-validator /usr/local/bin/agave-validator.bak
Встановіть нову версію через agave-install init або замініть бінарний файл вручну.
Перевірте, що новий бінарний файл доступний: agave-validator --version
Зупиніть сервіс: sudo systemctl stop agave-validator
Переконайтеся, що процес повністю зупинено: ps aux | grep agave-validator
Запустіть сервіс: sudo systemctl start agave-validator
Спостерігайте за журналами: journalctl -u agave-validator -f

Очікуваний результат: валідатор підключається до кластера, починає отримувати слоти та голосувати протягом 30–60 секунд після запуску.

Перевірка після оновлення

Перевірте, що версія в журналах відповідає очікуваній.
Перевірте статус голосування через solana vote-account — останній голос має бути не старішим за кілька слотів.
Перевірте відсутність помилок у журналах: "skip slot", "bank hash mismatch", "duplicate slot".
Перевірте метрики відстеження (root slot зростає, ping до сусідів у нормі).

Що робити, якщо щось пішло не так

Якщо валідатор не стартує або не голосує — негайно зупиніть сервіс і виконайте відкат до резервного бінарного файлу. Детальні кроки описані в розділі «Як виконати відкат валідатора до попередньої версії».

Як підготувати план відкату валідатора

Що таке rollback та коли він потрібен

Rollback — це повернення валідатора до попередньої стабільної версії клієнта після невдалого оновлення. Він потрібен, коли нова версія призводить до краху, втрати голосів, невідповідності хешів банків або інших критичних помилок, які неможливо швидко виправити на місці.

Компоненти плану відкату

Резервний бінарний файл: попередня версія клієнта, збережена до оновлення.
Резервна копія конфігурації: файл validator.yml та всі змінні середовища.
Точка відновлення ledger: snapshot або інкрементальна копія, сумісна з попередньою версією.
Процедура зупинки та запуску: чітка послідовність команд.
Критерії успіху: які показники свідчать, що відкат пройшов успішно.

Документування кроків відкату

Кожен крок має бути записаний як конкретна команда з вказанням користувача, шляху та очікуваного результату. Не використовуйте формулювання на кшталт «відкотити версію» — пишіть «зупинити сервіс, замінити бінарний файл за шляхом X на резервну копію, запустити сервіс».

Тестування плану відкату

План відкату, який не тестувався — це не план, а гіпотеза. Перевірте його на testnet або devnet: виконайте оновлення до цільової версії, потім відкатіть назад. Зафіксуйте час виконання та будь-які несподіванки.

Критерії прийняття рішення про відкат

Валідатор не стартує після оновлення протягом 120 секунд.
Валідатор стартує, але не голосує протягом 30 слотів.
У журналах з'являються критичні помилки: "bank hash mismatch", "fatal error", "ledger verification failed".
Метрики показують аномальне споживання пам'яті або CPU, що загрожує OOM-вбивством.

Чеклист відкату

Резервний бінарний файл збережено та перевірено (agave-validator.bak --version).
Конфігурація збережена.
Snapshot, сумісний із попередньою версією, доступний.
Команди зупинки, заміни та запуску записані.
Критерії відкату зафіксовані.
План протестовано на testnet.
Час виконання відкату зафіксовано.

Як перевірити нову версію Agave перед оновленням

Звідки дізнатися про новий release

Офіційний репозиторій Agave на GitHub — розділ Releases.
Офіційні канали спільноти Solana (оголошення про scheduled upgrades).
Моніторинг кластера: якщо сусідні валідатори вже оновилися, а ваш голосує на старій версії — це сигнал.

Читання release notes та changelog

Зосередьтеся на таких розділах:

Breaking changes: зміни в форматах даних, конфігурації, прапорцях запуску.
Consensus changes: зміни в логіці голосування, обробці слотів, епох.
Performance: зміни в вимогах до пам'яті, диску, CPU.
Known issues: відомі проблеми, які не виправлені в цьому релізі.
Dependencies: оновлення системних бібліотек або Rust toolchain.

Запуск на testnet або devnet

Розгорніть валідатор на testnet або devnet із тією конфігурацією, яка максимально наближена до вашої production-налаштування. Не тестуйте на mainnet-beta — це пряма загроза стейку.

Перевірка сумісності з поточним конфігом

Перевірте, чи всі прапорці запуску в вашому validator.yml або systemd-юніті підтримуються новою версією.
Перевірте, чи не змінилися значення за замовчуванням для параметрів, які ви явно не вказуєте.
Перевірте сумісність з вашою версією ledger (формат snapshot може змінитися).

Моніторинг стабільності тестового запуску

Час роботи без краху: мінімум 24 години на testnet.
Стабільне голосування без пропусків слотів.
Відсутність зростання споживання пам'яті (ознака витоку).
Нормальний час обробки слотів (без аномальних сповільнень).

Критерії переходу на production

Перехід на production дозволено, якщо: тестовий валідатор працює стабільно не менше 24 годин, голосує без пропусків, журнали не містять критичних помилок, а release notes не містять невирішених breaking changes для вашої конфігурації.

Як виконати відкат валідатора до попередньої версії

Коли відкат є необхідним

Відкат виконується, коли нова версія клієнта несподівано нестабільна на вашому обладнанні, призводить до краху під час синхронізації, або кластер скасував scheduled upgrade і вимагає повернення до попередньої версії.

Зупинка поточного валідатора

Попередження: ця дія зупиняє процес валідатора та призводить до тимчасової втрати голосів.

sudo systemctl stop agave-validator
Дочекайтеся повної зупинки: ps aux | grep agave-validator — процес має бути відсутнім.
Зафіксуйте останні рядки журналу для діагностики: journalctl -u agave-validator -n 100 --no-pager

Переключення на резервний бінарний файл

cp /usr/local/bin/agave-validator /usr/local/bin/agave-validator.failed — збережіть невдалу версію для діагностики.
cp /usr/local/bin/agave-validator.bak /usr/local/bin/agave-validator — відновіть попередню версію.
agave-validator --version — переконайтеся, що версія відповідає очікуваній.

Перевірка ledger на сумісність

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

Перезапуск та синхронізація

sudo systemctl start agave-validator
Спостерігайте за журналами: journalctl -u agave-validator -f
Якщо ledger несумісний — замініть snapshot на сумісний і перезапустіть знову.
Очікуйте синхронізацію: валідатор може потребувати кілька хвилин для досягнення поточного слота.

Моніторинг після відкату

Перевірте, що валідатор голосує: solana vote-account <your_vote_address></your_vote_address>
Перевірте, що root slot зростає.
Перевірте відсутність помилок у журналах протягом першої години.

Повідомлення команди та стейкерів

Якщо ваш валідатор обслуговує зовнішніх делегаторів — повідомте їх про відкат, причину та очікуваний час відновлення. Це зменшує паніку та запобігає масовому undelegate.

Як мігрувати з Solana Labs на Agave клієнт

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

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

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

Назва пакету та бінарного файлу: можуть відрізнятися залежно від способу встановлення.
Конфігурація: деякі прапорці запуску можуть бути перейменовані або видалені.
Формат ledger: у більшості випадків зворотно сумісний, але це треба перевірити для кожного конкретного релізу.
Репозиторій: вихідний код розміщений в окремому репозиторії Agave.

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

Прочитайте release notes Agave, зокрема розділ про міграцію з Solana Labs Validator.
Зробіть повну резервну копію: бінарний файл, конфігурацію, ledger, accounts.
Протестуйте міграцію на testnet або devnet.
Підготуйте план відкату до Solana Labs Validator.

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

Зупиніть валідатор Solana Labs: sudo systemctl stop agave-validator
Збережіть поточний бінарний файл як резервну копію.
Встановіть Agave клієнт з офіційного репозиторію.
Перевірте, що конфігурація сумісна: запустіть agave-validator --help і порівняйте прапорці.
Внесіть необхідні зміни в конфігурацію (перейменовані прапорці, нові значення за замовчуванням).
Запустіть Agave валідатор: sudo systemctl start agave-validator
Спостерігайте за журналами на предмет помилок міграції.

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

Версія клієнта в журналах відповідає Agave.
Валідатор підключається до кластера та голосує.
Ledger читається без помилок.
Метрики стабільні протягом першої години.

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

Невідомий прапорець: прапорець, який існував у Solana Labs, видалено або перейменовано в Agave. Рішення: перевірте release notes та оновіть конфігурацію.
Несумісний snapshot: формат змінився. Рішення: завантажте snapshot, створений Agave, або дочекайтеся створення нового snapshot з нуля.
Зміна шляху до accounts: перевірте, що --accounts вказує на правильну директорію.

Як налаштувати автоматичне оновлення валідатора

Чи варто автоматизувати оновлення

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

Ризики автоматичних оновлень

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

Інструменти: update-managers, CI/CD

Якщо ви все ж вирішили автоматизувати, використовуйте інструменти, які дозволяють додати етап підтвердження:

agave-install із прапорцями, що завантажують, але не встановлюють реліз автоматично.
CI/CD пайплайни (GitLab CI, GitHub Actions), які виконують завантаження, верифікацію та розгортання після вашого ручного підтвердження.
Кастомні скрипти, які перевіряють наявність нового релізу та надсилають сповіщення, але не виконують оновлення.

Стратегія semi-automated: сповіщення + підтвердження

Оптимальний підхід для production: скрипт періодично перевіряє наявність нового релізу (через API GitHub) і надсилає сповіщення в ваш канал (Slack, Telegram, email). Оновлення виконується вручну за вашим підтвердженням, але з використанням автоматизованих команд, які мінімізують ризик помилки оператора.

Тестове оновлення перед production

Навіть у semi-automated схемі першим кроком має бути автоматичне оновлення тестового вузла на testnet. Тільки після підтвердження його стабільності сповіщення про production-оновлення надсилається оператору.

Моніторинг автоматичних оновлень

Лог кожного автоматичного оновлення (навіть невиконаного) з фіксацією версії, хеш-суми та часу.
Алерт, якщо тестовий вузол не оновився (ознака проблеми із скриптом або доступом до репозиторію).
Алерт, якщо production-валідатор працює на версії, яка відстає від кластера більше ніж на N слотів.

Як тестувати оновлення на testnet та devnet

Різниця між testnet та devnet

Testnet: наближається до mainnet за конфігурацією (розмір слота, час епохи, кількість валідаторів). Підходить для перевірки стабільності та сумісності конфігурації.
Devnet: менш стабільний, частіше перезапускається, використовується для розробки. Підходить для швидкої перевірки того, чи валідатор взагалі стартує на новій версії.

Розгортання валідатора на testnet

Використовуйте окремий сервер або віртуальну машину з тією ж ОС та архітектурою, що й ваш production-валідатор. Конфігурація має бути максимально схожою: ті самі прапорці запуску, та сама структура директорій. Не використовуйте production-сервер для тестування.

Симуляція оновлення

Встановіть поточну production-версію на testnet-валідатор.
Дочекайтеся повної синхронізації та стабільного голосування.
Виконайте оновлення до цільової версії тими самими командами, що плануєте для production.
Зафіксуйте час простою та поведінку після перезапуску.

Моніторинг метрик після оновлення

Час старту до першого голосу.
Кількість пропущених слотів під час та після оновлення.
Споживання пам'яті (RSS) протягом 24 годин — перевірте на відсутність витоку.
Час обробки слотів та розмір тпу.
Наявність помилок у журналах.

Фіксація результатів тестування

Запишіть: версію «звідки» і «куди», дату, час простою, виявлені проблеми, висновок (дозволено / не дозволено production-оновлення). Зберігайте історію тестувань для аналізу трендів.

Перехід від тесту до production

Тест вважається успішним, якщо жоден із критеріїв не показав аномалій. Перехід до production виконується за процедурою, описаною в розділі «Як оновити валідатор без зайвого простою».

Як працювати з резервним вузлом під час оновлення

Архітектура з резервним вузлом

Резервний вузол (hot standby) — це другий валідатор із тим самим identity-ключем, запущений на окремому сервері. Під час нормальної роботи лише один вузол активний — два вузли з одним identity не можуть одночасно голосувати в кластері.

Синхронізація резервного вузла

Резервний вузол підтримує актуальний ledger через periodic snapshot-завантаження або спільну файлову систему (NFS, тощо).
Альтернатива: резервний вузол працює як повноцінний валідатор, але з відключеним голосуванням (--no-voting), і синхронізується з кластером в реальному часі.

Оновлення основного вузла з активним резервом

Перевірте, що резервний вузол синхронізований і готовий до переключення.
Зупиніть основний вузол.
Оновіть основний вузол до нової версії.
Запустіть основний вузол і перевірте його стабільність.
Якщо все в порядку — основний вузол продовжує роботу. Резервний залишається в режимі очікування.

Переключення ролей при проблемах

Якщо оновлений основний вузол не стартує або нестабільний:

Зупиніть оновлений основний вузол.
Активуйте резервний вузол (увімкніть голосування, якщо воно було відключене).
Перевірте, що резервний вузол голосує і обслуговує запити.
Виконайте відкат основного вузла в фоновому режимі.

Зворотне переключення після успішного оновлення

Після підтвердження стабільності оновленого основного вузла оновіть резервний вузол тією ж процедурою. Під час оновлення резерву основний продовжує обслуговувати кластер.

Вартість та складність резервного вузла

Резервний вузол вимагає окремого сервера з аналогічними характеристиками (або дещо нижчими, якщо він не обробляє RPC-запити). Складність полягає в координації переключення та підтримці синхронізації ledger. Для операторів із значним делегованим стейком ця складність виправдана.

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

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

Процес не стартує — systemd повідомляє про помилку запуску.
Процес стартує, але негайно завершується (crash loop).
Процес працює, але не підключається до кластера (немає сусідів, немає слотів).
Процес підключається, але не голосує.
Процес голосує, але журнали містять критичні помилки.

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

journalctl -u agave-validator -n 500 --no-pager > /tmp/failed_update.log
agave-validator --version — зафіксуйте фактичну версію.
df -h — перевірте вільне місце на диску.
free -h — перевірте доступну пам'ять.
Збережіть конфігураційний файл та список прапорців запуску.
Зафіксуйте хеш-суму бінарного файлу: sha256sum /usr/local/bin/agave-validator

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

Несумісний прапорець: прапорець, який існував у попередній версії, видалено або змінено. Журнал містить повідомлення про невідомий аргумент.
Несумісний ledger: нова версія очікує інший формат snapshot. Журнал містить помилки десеріалізації.
Недостатньо пам'яті: нова версія вимагає більше RAM. Процес завершується через OOM killer.
Збійна збірка: бінарний файл скомпільовано з помилками або для іншої архітектури.
Завантажений неправильний реліз: випадково встановлено release-candidate замість стабільного релізу.

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

Прочитайте журнали та визначте тип помилки.
Якщо проблема в прапорцях — виправте конфігурацію та перезапустіть.
Якщо проблема в пам'яті — збільште swap або RAM, або перевірте, чи не витікає пам'ять.
Якщо проблема в ledger — завантажте сумісний snapshot.
Якщо причина незрозуміла — виконайте повний відкат.

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

Повний відкат потрібен, якщо: причину неможливо швидко діагностувати, проблема системна (несумісність формату даних), або ви витратили більше 10 хвилин на спроби виправлення без результату. Кожна хвилина без голосування — це пряма втрата винагороди.

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

Зафіксуйте причину невдачі та додайте перевірку в майбутній план оновлення.
Якщо проблема в конфігурації — оновіть шаблон конфігурації.
Якщо проблема в ledger — додайте перевірку формату snapshot до чеклиста.
Повторіть тестування на testnet із відтворенням умов, що призвели до невдачі.

Як мігрувати ledger та accounts між клієнтами

Коли потрібна міграція ledger

Перехід з Solana Labs Validator на Agave.
Перехід між різними версіями Agave, де змінився формат snapshot.
Перенесення ledger на новий сервер.
Перехід на альтернативний клієнт (якщо такий підтримується кластером).

Сумісність форматів ledger між версіями

Формат ledger та snapshot не завжди зворотно сумісний. Перевірте release notes для обох версій (звідки і куди мігруєте) на предмет змін у форматі. Якщо формат змінився — пряма копія ledger не спрацює, потрібен snapshot у новому форматі.

Експорт та імпорт accounts

Директорія accounts містить стан ваших локальних акаунтів (у тому числі identity та vote акаунти валідатора). Для міграції:

Зупиніть валідатор-джерело.
Скопіюйте всю директорію accounts на цільовий сервер: rsync -avz --progress /mnt/ledger/accounts/ target:/mnt/ledger/accounts/
Переконайтеся, що права доступу та власник збережені.

Попередження: ніколи не копіюйте accounts під час роботи валідатора — це може призвести до пошкодження даних.

Завантаження snapshot на новий клієнт

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

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

Валідатор стартує без помилок читання ledger.
Identity-акаунт валідатора відповідає очікуваному: solana address з вашим keypair-файлом.
Vote-акаунт доступний і показує правильний стан.
Root slot відповідає моменту створення snapshot або пізніше.
Журнали не містять помилок "slot hash mismatch" або "invalid snapshot".

Мінімізація downtime при міграції

Найкращий спосіб мінімізувати downtime — використовувати архітектуру з резервним вузлом. Підготуйте новий клієнт на резервному сервері, завантажте snapshot та accounts, переконайтеся, що він синхронізується. Потім переключте трафік та голосування на новий вузол, а старий зупиніть. У такій схемі downtime обмежується часом переключення.

Для операторів, які не мають резервного вузла, downtime дорівнює часу копіювання accounts та завантаження snapshot. На швидких NVMe-дисках з локальною копією snapshot це зазвичай займає 2–5 хвилин плюс час синхронізації з кластером після запуску.