Міграція ledger (журналу транзакцій) та accounts (бази стану акаунтів) між клієнтами — стандартна інфраструктурна процедура при переході на іншу реалізацію клієнта, зміні архітектури вузла або відновленні після збою. Нижче — перевірена послідовність дій із вказанням ризиків, точок контролю та шляхів відкату.

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

Статус клієнтів для «Як мігрувати ledger та accounts між клієнтами» перевірено 2 серпня 2026 року. Frankendancer — гібрид Agave/Firedancer — працює на mainnet-beta щонайменше з 2025 року: офіційна програма делегування повідомляла майже про 200 валідаторів у вересні 2025 року. Повний Firedancer є окремою реалізацією мовою C; його поточне впровадження та частку валідаторів потрібно звіряти з офіційним звітом, а не з давніми твердженнями про «лише testnet».

Середовище перевірки: Ubuntu 24.04 LTS (x86_64), клієнт Agave, кластер mainnet-beta. Конкретні версії клієнтів та форматів ledger змінюються з кожним релізом — перед виконанням обов'язково перевірте актуальні release notes обох клієнтів (джерельного та цільового).

Передумови:

  • Джерельний валідатор зупинений або працює в режимі лише читання
  • Цільовий клієнт встановлений та скомпільований на тому самому або окремому сервері
  • Достатньо вільного місця на диску для розміру ledger та accounts (мінімум 2× від поточного об'єму)
  • Доступ до надійного джерела snapshot (якщо не використовується локальний)
  • Резервна копія всієї директорії даних джерельного вузла

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

Міграція ledger необхідна у таких випадках:

  • Перехід між різними реалізаціями клієнта — наприклад, з Agave на Firedancer або інший сумісний клієнт. Кожна реалізація може зберігати ledger у власному форматі.
  • Зміна формату ledger у межах одного клієнта — деякі оновлення вводять несумісні зміни формату зберігання. У таких випадках просте оновлення неможливе, потрібна міграція.
  • Перенесення вузла на нове обладнання з іншою файловою системою або конфігурацією дисків.
  • Відновлення після пошкодження ledger — коли локальний ledger пошкоджено, але є валідний snapshot або експорт accounts з іншого джерела.
  • Реструктуризація інфраструктури — об'єднання або розділення ролей (валідатор, RPC-вузол, архівний вузол) на різних серверах.

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

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

Формат ledger у Solana прив'язаний до так званого hard-fork slot — конкретного слоту, після якого вступає в силу новий формат. Це означає, що:

  • Два клієнти з однаковою підтримкою hard-fork slot можуть читати один і той самий ledger.
  • Якщо цільовий клієнт не підтримує hard-fork slot джерельного ledger, міграція через пряме копіювання файлів неможлива — потрібен конвертер або відновлення з snapshot.
  • Snapshot-формат також має версію. Snapshot, створений клієнтом однієї версії, може бути несумісним із клієнтом іншої версії, навіть якщо обидва підтримують однаковий hard-fork slot.

Як перевірити сумісність:

  1. У release notes обох клієнтів знайдіть розділ про зміни формату ledger або snapshot.
  2. Перевірте значення hard-forks у конфігураційному файлі обох клієнтів — вони мають збігатися для поточної епохи.
  3. Якщо клієнти належать до різних реалізацій, зверніться до документації цільового клієнта щодо підтримки імпорту чужого формату.

Ризик: спроба завантажити несумісний ledger призведе до паніки клієнта (panic) при старті з помилкою формату. Це не пошкодить дані, але вимагатиме відкату до попередньої конфігурації.

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

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

Експорт accounts з джерельного клієнта

Зупиніть валідатор, якщо він працює:

  1. Зупинка сервісу:
    sudo systemctl stop agave-validator
  2. Перевірте, що процес повністю зупинено:
    ps aux | grep agave-validator
  3. Виконайте експорт accounts за допомогою утиліти solana-accounts-db:
    solana-accounts-db export /mnt/solana/accounts-db /mnt/backup/accounts-export
    де /mnt/solana/accounts-db — шлях до бази accounts, а /mnt/backup/accounts-export — директорія призначення.
  4. Зафіксуйте хеш-суму експортованого архіву для подальшої перевірки:
    sha256sum /mnt/backup/accounts-export/*.tar.gz > /mnt/backup/accounts-export.sha256

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

Імпорт accounts на цільовий клієнт

  1. Підготуйте директорію accounts-db цільового клієнта:
    mkdir -p /mnt/solana-new/accounts-db
  2. Виконайте імпорт:
    solana-accounts-db import /mnt/backup/accounts-export /mnt/solana-new/accounts-db
  3. Перевірте хеш-суму після імпорту та порівняйте з еталонною.
  4. Переконайтеся, що права доступу до директорії відповідають користувачу, від імені якого запускається валідатор:
    chown -R solana:solana /mnt/solana-new/accounts-db

Очікуваний результат: цільовий клієнт має розпізнати імпортовану базу accounts і використовувати її при старті з snapshot або при синхронізації з початку.

Відкат: якщо імпорт завершився з помилкою, видаліть вміст /mnt/solana-new/accounts-db і повторіть процедуру. Оригінальна база на джерельному вузлі залишається недоторканою.

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

Найшвидший спосіб підняти новий клієнт — використати snapshot замість повної синхронізації з genesis. Snapshot містить стиснений стан ledger та accounts на певний слот.

Отримання snapshot

Є два варіанти:

  • Локальний snapshot від джерельного вузла — знаходиться в директорії ledger/snapshots/. Це найнадійніший варіант, оскільки ви точно знаєте його походження.
  • Зовнішній snapshot з довіреної джерельної точки (genesis archive або інший валідатор). Перевірте актуальну адресу джерела snapshot у документації клієнта — вона змінюється.

Розміщення snapshot

  1. Скопіюйте файл snapshot у директорію ledger цільового клієнта:
    cp /mnt/solana/ledger/snapshots/snapshot-*.tar.zst /mnt/solana-new/ledger/snapshots/
  2. Перевірте цілісність архіву:
    zstd -t /mnt/solana-new/ledger/snapshots/snapshot-*.tar.zst
  3. Переконайтеся, що права доступу коректні:
    chown solana:solana /mnt/solana-new/ledger/snapshots/*

Запуск з snapshot

Запустіть цільовий валідатор із вказанням шляхів:

agave-validator \
  --ledger /mnt/solana-new/ledger \
  --accounts /mnt/solana-new/accounts-db \
  --snapshot-interval-slots 100 \
  --no-genesis-fetch

Клієнт має розпакувати snapshot, відновити стан і почати синхронізацію з моменту створення snapshot.

Ризик: якщо snapshot несумісний із цільовим клієнтом (різниця у версіях формату), ви отримаєте помилку десеріалізації. У такому разі необхідно отримати snapshot, створений цільовим клієнтом, або виконати повну синхронізацію з genesis.

Відкат: видаліть вміст директорій ledger та accounts-db цільового клієнта і повторіть процедуру з коректним snapshot.

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

Після успішного старту цільового клієнта виконайте наступні перевірки:

Перевірка слоту та синхронізації

solana slot
solana catchup

Очікуваний результат: перша команда повертає поточний слот кластера, друга підтверджує, що вузол синхронізовано.

Перевірка root slot

solana slot --root

Root slot має бути близьким до поточного слота (різниця не більше кількох епох, залежить від конфігурації).

Перевірка стану accounts

solana account <YOUR_VALIDATOR_PUBKEY>

Перевірте, що баланс та стан акаунта валідатора відповідають очікуваним значенням до міграції.

Аналіз журналів

Перевірте журнали на відсутність помилок:

journalctl -u agave-validator --since "1 hour ago" | grep -iE "error|panic|corrupt|invalid" | tail -20

Очікуваний результат: порожній вивід або лише інформаційні повідомлення без критичних помилок.

Перевірка консенсусу

solana validators | grep <YOUR_VALIDATOR_IDENTITY>

Валідатор має бути у списку активних валідаторів із коректним root slot.

Критерій успіху: вузол синхронізовано, root slot оновлюється, журнали не містять помилок десеріалізації чи пошкодження даних, акаунт валідатора цілісний.

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

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

Паралельна підготовка

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

  1. Встановіть та скомпілюйте цільовий клієнт.
  2. Скопіюйте snapshot та accounts у фоновому режимі (без зупинки джерела).
  3. Запустіть цільовий клієнт і дайте йому синхронізуватися до поточного слота.
  4. Дочекайтеся, коли цільовий вузол наздожене джерельний (різниця в слотах — менше 100 слотів).

Швидке перемикання

Коли цільовий вузол готовий:

  1. Зупиніть джерельний валідатор:
    sudo systemctl stop agave-validator
  2. Оновіть конфігурацію сервісу (systemd unit) на використання цільового клієнта та нових шляхів.
  3. Запустіть валідатор:
    sudo systemctl start agave-validator

Очікуваний downtime: від кількох секунд до однієї хвилини, залежно від часу зупинки та запуску процесу.

Моніторинг у перші години

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

  • Різницю між локальним слотом та слотом кластера — вона не має зростати.
  • Наявність голосів (vote) від вашого валідатора в блок-оглядачі кластера.
  • Журнали на предмет помилок пам'яті або диску (OOM, I/O error).
  • Статус delinquent — якщо вузол не голосував достатньо епох, він може бути позначений як delinquent. Діагностика цієї ситуації розглядається в окремому матеріалі.

Резервний шлях

Якщо цільовий клієнт не стабілізується протягом перших 10–15 хвилин:

  1. Зупиніть цільовий клієнт.
  2. Відновіть конфігурацію systemd unit на джерельний клієнт.
  3. Запустіть джерельний валідатор — він продовжить з того місця, де був зупинений.
  4. Проаналізуйте журнали цільового клієнта для виявлення причини збою.

Цей підхід гарантує, що максимальний downtime обмежений часом одного циклу зупинка-запуск, а повний відкат можливий без додаткової міграції даних.

Джерела