Edit this page on GitHub (opens in a new tab)
Zcash Stack — это набор инструментов с открытым исходным кодом для развёртывания от команды, создавшей zec.rocks. В него входят полный узел Zcash, сервер лёгкого кошелька и дополнительные компоненты (Zaino, обозреватель блоков, скрытый сервис Tor, DNS-сидер, zecd, прокси gRPC-web для браузерных кошельков) в виде Helm-чарта для Kubernetes и файлов Compose для Docker. Все серверы zec.rocks lightwalletd запускаются из этого чарта. Проект финансируют Zcash Community Grants.
На этой странице кратко описано, что развёртывает набор инструментов, что нужно подготовить перед установкой и какие настройки важнее всего. Здесь рассматривается версия чарта 0.4.9 (выпущена 13 ноября 2026 года). Сначала ознакомьтесь с README чарта и заметками к семинару проекта — это основные справочные материалы, которые нужно прочитать перед запуском в рабочей среде.
Каждый компонент включается или отключается в values.yaml чарта. По умолчанию включён только lightwalletd, которому нужен узел блокчейна, поэтому в примерах также включён Zebra.
| Компонент | Образ в чарте 0.4.9 | По умолчанию | Назначение |
|---|---|---|---|
| Zebra | zfnd/zebra:7.0.0 | выключен (включён в примерах) | Полный узел: проверяет блокчейн и предоставляет RPC остальным компонентам |
| Zakura | zakuracore/zakura:1.8.6 | выключен | Форк Zebra; прямая замена lightwalletd или Zaino вместо Zebra |
| lightwalletd | electriccoinco/lightwalletd:v0.6.1 | включён | Сервер лёгкого кошелька (gRPC) для мобильных и настольных кошельков |
| Zaino | zingodevops/zaino:0.8.0-no-tls |
Два замечания о версиях. Версия Zaino выше по течению — 0.10.1, тогда как в чарте по-прежнему используется образ версии 0.8.0. Перед тем как полагаться на более новое поведение Zaino, проверьте values.yaml. Кроме того, узлы Zakura в Mainnet останавливаются на заданной для каждого релиза высоте окончания поддержки: для версии 1.8.6 это блок 3 643 309, ориентировочно 5 декабря 2026 года. Сборки для x86-64 начиная с версии 1.8.0 не запускаются на процессорах без BMI2 и ADX. На странице описаны обе проблемы.
Чарт развёртывается с использованием трёх компонентов, которые нужно настроить один раз для каждого кластера.
Ingress и по умолчанию использует класс nginx. Рекомендуется ingress-nginx, поскольку он одинаково обрабатывает gRPC в k3s и GKE. В k3s установите k3s с --disable traefik или оставьте Traefik и задайте ingress.className: traefik вместе с ingress.backendProtocol: GRPC (тогда чарт создаст Traefik IngressRoute, поскольку обычный Ingress через Traefik возвращает HTTP 500 для gRPC). В GKE встроенный класс ingress gce не умеет направлять gRPC к lightwalletd или Zaino.examples/cluster-issuer.yaml; сначала проверьте всё с тестовым издателем сертификатов). В GKE Autopilot установите cert-manager с помощью --set global.leaderElection.namespace=cert-manager, иначе создание издателя завершится ошибкой x509 «unknown authority». Вместо cert-manager можно указать собственный сертификат в <service>.ingress.tls.secretName.local-path с NVMe. В GKE назначьте Zebra класс IOPS с предварительным выделением ресурсов (в репозитории есть пример для Hyperdisk) и заранее увеличьте региональную квоту на диски: в новых проектах GKE в каждом регионе разрешено только 500 ГБ SSD и 500 ГБ Hyperdisk, а узлу блокчейна требуется от 300 до 500 ГБ. Иначе том останется в состоянии с ошибкой . Изменить у существующего StatefulSet нельзя, не пересоздав том.Затем направьте DNS-записи для каждого имени хоста на внешний IP контроллера ingress. Если у вас ещё нет DNS, добавьте имя sslip.io, например 203-0-113-7.sslip.io, рядом с настоящим именем хоста: оно разрешается в указанный в нём IP-адрес, поэтому сертификат выпускается сразу. Для постоянных серверов указывайте собственное имя хоста как основное.
helm repo add zcash https://zecrocks.github.io/zcash-stack
helm repo update
# copy an example from the repo's examples/ folder, set your hostnames and RPC credentials, then:
helm install zcash zcash/zcash-stack -f examples/zebra-mainnet.yaml
Пример zebra-mainnet.yaml включает Zebra, подключает к нему lightwalletd, выделяет lightwalletd кэш объёмом 40 ГиБ и настраивает TLS ingress, оставляя RPC узла внутри кластера. Перед установкой замените примерные имя пользователя и пароль RPC. В других примерах описаны testnet, GKE, GKE Autopilot с высокой доступностью, скрытый сервис Tor и начальная настройка sslip.io.
Для обновления выполните helm repo update, просмотрите изменения с помощью плагина helm-diff (helm diff upgrade zcash zcash/zcash-stack -f values.yaml), затем выполните helm upgrade с теми же аргументами. Если вы переходите с чарта версии 0.0.x, сначала прочитайте MIGRATION.md: в версии 0.1.0 прежняя конфигурация Traefik была заменена на стандартный Ingress и cert-manager, а структура параметров изменилась.
| В обычном режиме | При первоначальной синхронизации | Диск | |
|---|---|---|---|
| Zebra | около 0,1 vCPU, 1,6 ГиБ | Требует много CPU, IOPS и памяти | Около 260 ГиБ (июнь 2026 года), объём растёт; значение по умолчанию в чарте — 500 ГиБ |
| lightwalletd | около 0,15 vCPU, 165 МиБ | Построение кэша по блокам | Около 17 ГиБ; значение по умолчанию в чарте — 40 ГиБ |
Для всего набора компонентов запрашивается около 1,5 vCPU и 4,5 ГиБ памяти. Для одной машины чарт рекомендует 8 vCPU, 32 ГиБ ОЗУ и около 1 ТБ NVMe (в GKE — n2-standard-8 с томом Hyperdisk или pd-ssd на 500 ГиБ). Значения запросов по умолчанию уже соответствуют минимальным требованиям GKE Autopilot. Ограничения CPU не заданы, чтобы во время синхронизации можно было использовать дополнительную мощность.
Восстановление из снимка. Задайте <chain>.initSnapshot.enabled: true (с initSnapshot.url, gs:// или https://), чтобы начать с опубликованного снимка вместо синхронизации с генезисного блока. Процесс восстановления отмечает прогресс, корректно перезапускает прерванную загрузку и не удаляет данные исправного тома, оставшиеся от предыдущей установки. Снимок позволяет сэкономить время и требует доверия к его источнику: блоки после снимка всё равно проверяются, а некорректный снимок приведёт к ошибкам проверки блоков. По оценке семинара, синхронизация с нуля занимает около 10 дней, а запуск со снимка — около 10 часов.
Масштабирование и работа без простоев. lightwalletd и Zaino — это небольшие кэши перед узлом. Используйте replicas: 2 для обновлений без простоев (PodDisruptionBudget добавляется автоматически, если число реплик больше 1). Узлы блокчейна не масштабируют ради нагрузки: каждая реплика — ещё один полный узел со своим томом и собственной синхронизацией. Запускайте один узел или два для резервирования.
Входящие пиры. По умолчанию Zebra устанавливает только исходящие соединения. zebra.p2pPublic.enabled: true принимает входящие подключения пиров на порт 8233 (18233 в testnet) и сообщает им ваш адрес. Для bare metal и k3s выберите externalAddrFrom: hostIP, в облаках, где собственный IP узла является частным, — nodeExternalIP, а в GKE Autopilot — loadBalancer с зарезервированным статическим IP.
TLS и gRPC. TLS завершается на ingress, а внутри кластера используется обычный HTTP/2, поэтому несколько имён хоста могут указывать на один lightwalletd. Оставьте path: / вместе с pathType: Prefix, поскольку путям методов gRPC это необходимо. Если первый выпуск сертификата завершился ошибкой из-за перенаправления на HTTPS, выпустите сертификат с тестовым издателем или временно задайте ingress.tls.sslRedirect: "false".
Скрытый сервис Tor. Подходит, если у кластера нет публичного IP или домена:
tor:
enabled: true
targetService: zaino # or lightwalletd
hiddenServicePort: 443
Узнайте адрес с помощью kubectl exec -it tor-0 -- cat /var/lib/tor/hidden_service/hostname и проверьте его локальным клиентом Tor с zecping: ./zecping -socks localhost:9150 -addr <address>.onion:443.
Во время обновления сети. Zebra может заблокировать пиры со старыми версиями и остановиться, записав в журнал сообщение о том, что обновления блокчейна остановились. Список блокировок хранится в памяти, поэтому kubectl delete pod zebra-0 очищает его. Под сохраняет прежние данные блокчейна и запускается без повторной синхронизации.
Чтобы запустить Compose на одной машине, клонируйте репозиторий и запустите файл по умолчанию из каталога docker/:
git clone https://github.com/zecrocks/zcash-stack.git
cd zcash-stack/docker
docker compose up --detach
docker compose logs --follow
Файл compose.yaml запускает Zebra, lightwalletd и Watchtower на x86; compose.arm.yaml делает то же самое на ARM-хостах. Watchtower автоматически загружает новые образы, а в файле по умолчанию указан тег zfnd/zebra:latest, поэтому узел автоматически переходит на новые релизы Zebra без ручного обновления. В файле compose.zaino.yaml вместо lightwalletd используется Zaino, однако в нём закреплён старый образ сообщества (emersonian/zcash-zaino:0.1.2-zr4), поэтому проверьте его перед использованием. В других файлах добавлены TLS-фронтенд Caddy, прокси VPS и туннель autossh для узлов, работающих дома.
Укажите LIGHTWALLETD_DONATION_ADDRESS в файле .env — собственный унифицированный адрес, который будет опубликован как адрес для пожертвований сервера. Если перед первым docker compose up запустить ./download-snapshot.sh из каталога docker/, вместо синхронизации с нуля будет загружен снимок блокчейна.
На втором занятии семинара рассматриваются способы сделать сервер доступным: использовать публичный статический IP, скрыть домашний IP за SSH-туннелем к VPS или Tailscale Funnel либо запустить сервер только в Tor. Проверьте результат, подключив к серверу кошелёк (в ZODL откройте «Расширенные настройки»; см. ) или вызвав GetLightdInfo с помощью клиента gRPC.
На третьем занятии перечислены команды Docker для ручного мониторинга. Также предлагается зарегистрировать публичный сервер в hosh — мониторе доступности zec.rocks. Для регистрации нужно отправить pull request, добавив имя хоста и порт в список серверов hosh. Помощь по всем этапам можно получить на форуме семинаров zec.rocks.
Установка lightwalletd без узла блокчейна. lightwalletd получает данные из Zebra (или Zakura). Включите один из этих компонентов или начните с примера, где он уже включён.
Использование примерных учётных данных RPC. В примерах указаны заглушки. RPC остаётся внутри кластера, но всё равно замените их.
Запуск узла блокчейна с квотой диска GKE по умолчанию. Том не будет подключён. Перед установкой увеличьте региональную квоту.
Масштабирование Zebra ради нагрузки. Каждая реплика Zebra требует ещё одной полной синхронизации. Вместо этого масштабируйте lightwalletd или Zaino.
Использование старой версии чарта при обновлении сети. Узел, выпущенный до обновления сети, после него перестанет следовать за Mainnet (для Zebra с версии NU7 требуется версия 7.0.0 или новее). Выполните helm repo update и обновите чарт до достижения высоты активации и высот окончания поддержки Zakura.
Последнее обновление: ноябрь 2026 года (чарт 0.4.9)
| выключен |
| Индексатор Rust, который также обслуживает лёгкие кошельки |
| Обозреватель блоков | emersonian/zcash-explorer:v0.0.6 | выключен | Веб-обозреватель, получающий данные через JSON-RPC узла (Zaino не подойдёт: он предоставляет только gRPC) |
| Tor | osminogin/tor-simple:0.4.9.16 | выключен | Публикует lightwalletd или Zaino как сервис .onion |
| DNS-сидер | zfnd/dnsseeder:v1.8.0 | выключен | Помогает новым узлам находить пиры |
| zecd | ghcr.io/zecrocks/zecd:0.6.3 | выключен | Сервер кошелька, ориентированный на экранированные транзакции (см. ) |
| Прокси gRPC-web | envoyproxy/envoy:v1.40.2 | выключен | Позволяет браузерным кошелькам подключаться к lightwalletd, недоступному браузерам через обычный gRPC |
| Кошелёк WebZjs | ghcr.io/zecrocks/webzjs-wallet | выключен | Браузерный кошелёк; для него нужен прокси gRPC-web на том же хосте |
PendingQUOTA_EXCEEDEDstorageClassName