bitcoind/README.ru-RU.md

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

English version: README.md

Bitcoin Core — эталонная реализация Bitcoin. bitcoind — её демон: хранит полную копию цепочки, ретранслирует транзакции и предоставляет интерфейс JSON-RPC.

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

Репозиторий описывает только развёртывание в docker. Двоичные файлы — официальная сборка релиза, проверяемая по SHA-256, зафиксированному в Dockerfile.

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

У контейнера два порта, и они не взаимозаменяемы. Порт RPC (8332 для main, 18332 для test, 18443 для regtest) управляет кошельком и не имеет TLS: держите его на loopback или во внутренней сети docker. Порт P2P (8333 / 18333 / 18444) — протокол цепочки: опубликуйте его, чтобы принимать входящие соединения, или не публикуйте, и тогда узел работает только на исходящих.

Сеть выбирается переменной BITCOIND_CHAIN, она же задаёт RPC-порт по умолчанию. Неизвестное значение останавливает контейнер, а не откатывается к mainnet.

docker-compose

services:
  bitcoind:
    build:
      context: https://git.bitdeals.org/private/bitcoind.git
      dockerfile: ./docker/Dockerfile
    image: registry.bitdeals.org/bitcoind
    environment:
      - BITCOIND_CHAIN=regtest
      - BITCOIND_USER=CHANGE_ME
      - BITCOIND_PASSWORD=CHANGE_ME
      - BITCOIND_FALLBACKFEE=0.00001
      - BITCOIND_TXINDEX=1            # оба нужны ElectrumX; уберите,
      - BITCOIND_TXOSPENDERINDEX=1    # если узел никто не индексирует
    ports:
      - 127.0.0.1:18443:18443   # RPC — только loopback
    volumes:
      - btcdata:/data/.bitcoin

volumes:
  btcdata:

docker cli

docker run -d \
  -e BITCOIND_CHAIN=regtest \
  -e BITCOIND_USER=CHANGE_ME \
  -e BITCOIND_PASSWORD=CHANGE_ME \
  -e BITCOIND_FALLBACKFEE=0.00001 \
  -p 127.0.0.1:18443:18443 \
  -v btcdata:/data/.bitcoin \
  registry.bitdeals.org/bitcoind

Всё, что указано после имени образа, добавляется к аргументам демона, поэтому разовая служебная операция не требует нового образа:

docker run --rm -v btcdata:/data/.bitcoin registry.bitdeals.org/bitcoind -reindex

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

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

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

Другая версия Core задаётся аргументом сборки, и вместе с ней меняется контрольная сумма — оба значения берутся из https://bitcoincore.org/bin/bitcoin-core-<версия>/SHA256SUMS:

docker build . --file docker/Dockerfile \
  --build-arg BITCOIN_VERSION=31.1 \
  --build-arg BITCOIN_SHA256_X86_64=b80d9c3e04da78fb6f0569685673418cf686fadba9042d926d13fb87ff503f9e \
  --tag registry.bitdeals.org/bitcoind:31.1

Параметры

Образы контейнера настраиваются параметрами, передаваемыми при запуске.

Параметр	Назначение
-p 127.0.0.1:8332	Порт RPC. Внутри контейнера демон слушает то, что задано BITCOIND_RPCBIND, поэтому доступность определяет то, что опубликовано. RPC полностью управляет кошельком — см. «Замечания»
-p 8333	P2P-порт. Необязательный: без него узел всё равно подключается к пирам сам, просто к нему подключиться нельзя. Зависит от сети: 8333 для main, 18333 для test, 18444 для regtest
-v /data/.bitcoin	Каталог данных: цепочка, индекс блоков и кошельки. Без него обновление контейнера означает повторную загрузку цепочки
-e BITCOIND_CHAIN	Сеть: main, test, signet или regtest. Любое другое значение останавливает контейнер. По умолчанию: main
-e BITCOIND_USER	Пользователь RPC. По умолчанию: user — измените
-e BITCOIND_PASSWORD	Пароль RPC. По умолчанию: pass — измените
-e BITCOIND_PORT	Порт RPC. По умолчанию: стандартный порт выбранной сети (8332/18332/38332/18443). Задайте явно, чтобы URL RPC не менялся при смене сети
-e BITCOIND_RPCBIND	Интерфейс, на котором RPC слушает внутри контейнера. По умолчанию: 0.0.0.0, чтобы другие контейнеры обращались по имени сервиса
-e BITCOIND_RPCALLOWIP	Кому разрешены вызовы RPC. По умолчанию: 0.0.0.0/0 — закрытость контейнера обеспечивается тем, что опубликовано, а не этим параметром
-e BITCOIND_FALLBACKFEE	Комиссия (BTC/kvB) на случай, когда в цепочке нет истории для оценки. По умолчанию: 0 (выключено). Свежей regtest-цепочке параметр необходим, например 0.00001
-e BITCOIND_TXINDEX	Строить полный индекс транзакций. По умолчанию: 0. Требуется для ElectrumX. Изменение на существующем каталоге данных вызывает переиндексацию
-e BITCOIND_TXOSPENDERINDEX	Строить индекс «какая транзакция потратила этот выход». По умолчанию: 0. Требуется для ElectrumX 2.x. Изменение на существующем каталоге данных вызывает переиндексацию
-e BITCOIND_EXTRA_ARGS	Дополнительные аргументы bitcoind, разделяемые пробелами и добавляемые последними — то есть они перекрывают всё вышеперечисленное

Замечания

• RPC полностью управляет кошельком и не имеет TLS. Публикуйте его только на 127.0.0.1 или не публикуйте вовсе — внутри compose-проекта другие сервисы обращаются к нему по имени сервиса во внутренней сети. Значение BITCOIND_RPCALLOWIP по умолчанию 0.0.0.0/0, потому что только оно работает для обращений между контейнерами; закрытость даёт публикация портов.
• Учётные данные RPC видны в списке процессов контейнера. Это аргументы демона, и иначе нельзя: сетевые параметры Core в конфигурационном файле действуют только внутри секции [chain]. Внутри контейнера bitcoin-cli берёт их из cli.conf, поэтому проверка состояния второй копии не создаёт.
• Каталог данных из другого образа требует однократного chown. Демон работает под uid 1000, точка входа исправляет владельца самого каталога, но намеренно не обходит его содержимое: синхронизированный mainnet — сотни гигабайт, и рекурсивный chown добавлялся бы к каждому перезапуску.
• ElectrumX перед этим узлом требует двух индексов. Задайте одновременно BITCOIND_TXINDEX=1 и BITCOIND_TXOSPENDERINDEX=1: ElectrumX 2.x при старте запрашивает getindexinfo и завершается, назвав недостающий — сначала txindex, а после его включения txospenderindex. По умолчанию оба выключены, потому что занимают место, а большинству других применений не нужны.
• Обрезка цепочки (pruning) несовместима с ElectrumX. Индексатору нужна вся цепочка; -prune через BITCOIND_EXTRA_ARGS приведёт к отказу позже и в куда менее очевидном месте.
• В Core 29 и новее нет legacy-кошельков. createwallet создаёт дескрипторный кошелёк, приватный ключ импортируется через importdescriptors, а не importprivkey. Код, жёстко задающий descriptors=false, падает уже при создании кошелька.
• Смена версии — это и смена контрольной суммы. Сборка скачивает архив релиза и проверяет его в том же слое; изменение одной лишь версии приводит к ошибке sha256sum -c, а не к выпуску непроверенного образа.
• Контейнер становится healthy, как только отвечает RPC, — задолго до синхронизации цепочки. Это сделано намеренно: состояние «unhealthy трое суток начальной загрузки блоков» приводило бы к перезапускам узла всем, что следит за состоянием контейнеров.