electrumx/README.ru-RU.md

Общие сведения

English version: README.md

ElectrumX — сервер протокола Electrum. Он индексирует цепочку по данным полного узла и отвечает на запросы, которые лёгкий клиент не может обработать сам: история и UTXO произвольного адреса, а также публикация транзакций.

ElectrumX, работающий в docker-контейнере, настраивается переменными окружения.

Репозиторий описывает только развёртывание в docker. Сам ElectrumX устанавливается из зафиксированного тега upstream-репозитория.

Использование

ElectrumX нужен bitcoind, доступный по RPC, в той же сети и без обрезки цепочки. DAEMON_URL — единственная обязательная переменная; NET должен называть ту же сеть, в которой работает демон.

Контейнер отдаёт протокол Electrum на порту 50001 (открытый TCP) и, если этого требует SERVICES, на порту 50002 (TLS). Никакой аутентификации нет, поэтому держите оба порта во внутренней сети docker или на loopback. Служебный RPC на localhost:8000 наружу не выходит — им пользуется проверка состояния контейнера.

docker-compose

services:
  electrumx:
    build:
      context: https://git.bitdeals.org/private/electrumx.git
      dockerfile: ./docker/Dockerfile
    image: registry.bitdeals.org/electrumx
    environment:
      - COIN=Bitcoin
      - NET=regtest
      - DAEMON_URL=http://CHANGE_ME:CHANGE_ME@bitcoind:18443
      - CACHE_MB=400
    ports:
      - 127.0.0.1:50001:50001   # без аутентификации — только loopback
    volumes:
      - electrumxdata:/data

volumes:
  electrumxdata:

docker cli

docker run -d \
  -e COIN=Bitcoin \
  -e NET=regtest \
  -e DAEMON_URL=http://CHANGE_ME:CHANGE_ME@bitcoind:18443 \
  -e CACHE_MB=400 \
  -p 127.0.0.1:50001:50001 \
  -v electrumxdata:/data \
  registry.bitdeals.org/electrumx

Всё, что указано после имени образа, передаётся electrumx_server.

сборка и публикация

Пуш в main собирает и публикует образ (.gitea/workflows/build.yaml) с тремя тегами: <версия>.<sha7> — для развёртывания, <версия> — для чтения глазами, latest — для compose и Watchtower. Вручную, если под рукой есть учётные данные registry:

docker build . --file docker/Dockerfile --tag registry.bitdeals.org/electrumx
docker push registry.bitdeals.org/electrumx

Другая версия ElectrumX задаётся аргументом сборки — берите тег из upstream-репозитория:

docker build . --file docker/Dockerfile \
  --build-arg ELECTRUMX_VERSION=2.0.0 \
  --tag registry.bitdeals.org/electrumx:2.0.0

Параметры

Образы контейнера настраиваются параметрами, передаваемыми при запуске. Все переменные — собственные переменные ElectrumX, поэтому справочник upstream применим без изменений; в таблице перечислены те, которым этот образ задаёт значения по умолчанию.

Параметр	Назначение
-p 127.0.0.1:50001	Протокол Electrum поверх открытого TCP. Аутентификации нет — см. «Замечания»
-p 127.0.0.1:50002	Протокол Electrum поверх TLS. Отдаётся, только если SERVICES содержит ssl://
-v /data	Каталог данных: индекс и самоподписанный сертификат, если он был создан. Его потеря означает повторную индексацию цепочки
-e DAEMON_URL	Обязательный. RPC демона, например http://user:password@bitcoind:8332. Можно указать несколько через запятую
-e COIN	Класс монеты. По умолчанию: Bitcoin
-e NET	Сеть: mainnet, testnet, testnet4, signet, regtest или mutinynet. Должна совпадать с сетью демона. По умолчанию: mainnet
-e DB_ENGINE	Хранилище индекса. По умолчанию: rocksdb — единственный движок, библиотеки которого есть в образе
-e DB_DIRECTORY	Где лежит индекс. По умолчанию: /data
-e SERVICES	Что обслуживать, через запятую. По умолчанию: tcp://:50001,rpc://localhost:8000. Оставьте запись rpc:// — она нужна проверке состояния
-e SSL_CERTFILE, -e SSL_KEYFILE	Сертификат и ключ TLS. По умолчанию: самоподписанная пара создаётся в каталоге данных, если SERVICES содержит ssl://
-e PEER_DISCOVERY	Искать ли другие публичные серверы. По умолчанию: off — образ рассчитан на приватный индексатор
-e PEER_ANNOUNCE	Объявлять ли себя в сети серверов. По умолчанию: false
-e CACHE_MB	Кэш индексации. По умолчанию: 1200 (значение ElectrumX). Снижайте для небольшой цепочки, повышайте для ускорения первой индексации mainnet

Замечания

• Аутентификации нет никакой. Любой, кто дотянулся до 50001 или 50002, может запросить произвольный адрес и опубликовать транзакцию. Публикуйте на loopback, а если клиенты — контейнеры той же сети, не публикуйте вовсе.
• Индекс от другого образа не читается. Здесь rocksdb, а lukechilds/electrumx, который этот образ заменяет в BitDeals, писал leveldb. Подключите пустой том и дайте проиндексировать заново: для regtest и testnet это быстро, для mainnet — несколько суток.
• Демону нужны txindex=1 и txospenderindex=1. ElectrumX 2.x перед началом работы запрашивает getindexinfo и завершается с RuntimeError, называя недостающий индекс — по одному за раз, так что после включения txindex вы получите то же сообщение про txospenderindex. В соседнем образе bitcoind это BITCOIND_TXINDEX=1 и BITCOIND_TXOSPENDERINDEX=1; на существующем каталоге данных их включение означает переиндексацию демона.
• Демон не должен быть обрезанным. Индексация читает каждый блок; узел с -prune приводит к отказу на середине с сообщением об отсутствующем блоке, а не о неверной настройке.
• NET пишется по-электрумовски, а не по-биткойновски. Демон называет сети main, test и regtest, ElectrumX — mainnet, testnet и regtest. Точка входа отвергает неизвестное значение, потому что пара обычно настраивается из одного .env, и NET=test иначе упал бы глубоко внутри поиска класса монеты.
• Контейнер становится healthy только когда начинает обслуживать клиентов — то есть после того, как догнал демона. Первая индексация mainnet занимает несколько суток, и всё это время контейнер будет unhealthy; смотрите логи. На regtest это секунды.
• Самоподписанный сертификат создаётся, только если SERVICES требует TLS, а файлы не заданы. Клиентам придётся доверять ему явно. Это плата за то, что ElectrumX отказывается стартовать при запросе ssl:// без сертификата — не лучший способ узнать, что вы добавили порт.