bitcoind/README.ru-RU.md

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

> English version: [README.md](README.md)

[Bitcoin Core](https://bitcoincore.org/) — эталонная реализация 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

```yaml
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

```sh
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
```

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

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

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

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

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

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

```sh
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 трое суток
  начальной загрузки блоков» приводило бы к перезапускам узла всем, что следит
  за состоянием контейнеров.