beast docs

Быстрый старт

Linux с systemd, nginx и домен с TLS. Один бинарник, один файл настроек, один юнит.

1. Сборка

Нужен Go 1.25 или новее. CGO не нужен, бинарник статический.

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o beast-kluk .
scp beast-kluk user@host:/tmp/

На сервере:

sudo install -m 755 /tmp/beast-kluk /usr/local/bin/beast-kluk
sudo useradd --system --no-create-home --shell /usr/sbin/nologin beast-kluk

Сервис откажется работать от root. Каталог состояния /var/lib/beast-kluk создаст systemd.

2. Секреты

beast-kluk secret     # DEPOSIT_KEY_SECRET: 64 hex
beast-kluk token      # токен API для вашего бэкенда
beast-kluk token      # токен админки

token печатает две строки:

token  3c9f…   ← отдаёте клиенту или вводите в браузере
sha256 a41e…   ← пишете в файл настроек

На сервере хранится только SHA-256 токена. Сам токен сохраните в своём менеджере паролей.

DEPOSIT_KEY_SECRET закрывает все ключи кошельков. Сразу сделайте офлайн-копию: менеджер паролей или бумага. Не рядом с бэкапами базы. Подробно в разделе Безопасность.

3. Файл настроек

sudo install -m 600 /dev/null /etc/beast-kluk.env
sudo nano /etc/beast-kluk.env

Шаблон лежит в deploy/beast-kluk.env.example. Владелец root, права 0600.

ПеременнаяЧто это
DEPOSIT_KEY_SECRETОбязательна. 64 hex из beast-kluk secret. Шифрует каждый ключ. Менять на живой базе нельзя: сервис не стартует.
API_TOKEN_SHA256Обязательна. SHA-256 hex токена API.
ADMIN_TOKEN_SHA256Обязательна. SHA-256 hex токена админки.
PUBLIC_URLОбязательна, только https. База для checkout_url: PUBLIC_URL/pay/<id>. Слеш в конце срезается.
WEBHOOK_URLНеобязательна, только https. Куда слать invoice.paid.
WEBHOOK_SECRETНужна, если задан WEBHOOK_URL. Не короче 32 символов. Ключ HMAC.
MAIN_TRON_WALLETПубличный адрес холодного кошелька TRON (T…). Пусто: слив TRC20 выключен. Кривой адрес: сервис не стартует.
MAIN_BSC_WALLETПубличный адрес холодного кошелька BSC (0x…, проверяется контрольная сумма EIP-55). Пусто: слив BEP20 выключен.
TRONGRID_URLПо умолчанию https://api.trongrid.io.
TRONGRID_API_KEYОчень желателен. Без ключа лимит TronGrid низкий, а сервис делает до 20 запросов за 15 секунд. На полной нагрузке это около 115 тысяч в сутки.
BSC_RPC_URLОбязательна. HTTPS JSON-RPC, который отдаёт eth_getLogs на 1000 блоков. Публичные узлы bsc-dataseed этого не умеют.
TRON_VERIFY_URLНеобязательна, но очень желательна. Второй, независимый провайдер TRON: база HTTP API java-tron с /wallet/triggerconstantcontract. Подтверждает баланс до paid. Зачем.
BSC_VERIFY_RPC_URLНеобязательна, но очень желательна. Второй, независимый JSON-RPC BSC, та же роль.
BSC_MAX_GAS_GWEIСлив BSC откажется при цене газа выше этой. По умолчанию 5.
MAX_OPEN_INVOICESОткрытых неистёкших счетов на сеть. По умолчанию 200. Сверх лимита 429.
MAX_TTLСамый долгий ttl в секундах. По умолчанию 86400, не больше 604800.

Все адреса API только https. Адрес http:// остановит запуск. Как и кривое число в лимитах.

DEPOSIT_KEY_SECRET=<64 hex>
API_TOKEN_SHA256=<sha256 токена API>
ADMIN_TOKEN_SHA256=<sha256 токена админки>
PUBLIC_URL=https://pay.example.com
WEBHOOK_URL=https://shop.example.com/hooks/beast
WEBHOOK_SECRET=<32+ случайных символов>
MAIN_TRON_WALLET=T...
MAIN_BSC_WALLET=0x...
TRONGRID_URL=https://api.trongrid.io
TRONGRID_API_KEY=<ключ TronGrid>
BSC_RPC_URL=https://<ваш BSC RPC>
TRON_VERIFY_URL=https://<второй провайдер TRON>
BSC_VERIFY_RPC_URL=https://<второй провайдер BSC>
BSC_MAX_GAS_GWEI=5
MAX_OPEN_INVOICES=200
MAX_TTL=86400

Флаги

ФлагПо умолчаниюЧто это
-state/var/lib/beast-klukБаза beast-kluk.db и папка backups/.
-addr127.0.0.1:8829API клиента и страница оплаты. Наружу только через nginx.
-admin-addr127.0.0.1:8830Админка. Никогда не проксируйте.

Подкоманды: beast-kluk token и beast-kluk secret. Без подкоманды сервис запускается.

4. systemd

sudo cp deploy/beast-kluk.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now beast-kluk
journalctl -u beast-kluk -f

Юнит закрыт со всех сторон: свой пользователь, ProtectSystem=strict, фильтр системных вызовов, MemoryMax=64M, CPUQuota=25%. При первом старте в журнале появятся адреса газовых кошельков:

trc20 gas wallet T..., sweep true
bep20 gas wallet 0x..., sweep true
api 127.0.0.1:8829, admin 127.0.0.1:8830

sweep false значит, что холодный кошелёк этой сети не задан. Строка WARNING: TRON_VERIFY_URL is not set или BSC_VERIFY_RPC_URL is not set значит, что второго провайдера нет и оплату решает один основной.

5. nginx

Наружу смотрят только /v1/ и /pay/. На /pay/ ставим лимит по IP: это публичные страницы. Страница оплаты опрашивает статус раз в 5 секунд, лимит ниже с запасом это выдерживает.

limit_req_zone $binary_remote_addr zone=beast_pay:10m rate=2r/s;

server {
    listen 443 ssl http2;
    server_name pay.example.com;
    ssl_certificate     /etc/letsencrypt/live/pay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pay.example.com/privkey.pem;

    client_max_body_size 16k;

    location /pay/ {
        limit_req zone=beast_pay burst=20 nodelay;
        limit_req_status 429;
        proxy_pass http://127.0.0.1:8829;
    }
    location /v1/ {
        proxy_pass http://127.0.0.1:8829;
    }
    location / {
        return 404;
    }
}

server {
    listen 80;
    server_name pay.example.com;
    return 301 https://$host$request_uri;
}

Порт 8830 в nginx не попадает никогда. Хотите закрыть API по IP своего бэкенда? Добавьте allow и deny all в location /v1/.

6. Вход в админку

ssh -N -L 8830:127.0.0.1:8830 user@host

Откройте http://127.0.0.1:8830/. Браузер спросит логин и пароль: логин любой, пароль это токен админки. Дальше в разделе Админка и слив.

7. Первый счёт

curl -s https://pay.example.com/v1/invoices \
  -H "Authorization: Bearer $BEAST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"network":"trc20","amount":"1","external_id":"smoke-1"}'

Откройте checkout_url из ответа и заплатите 1 USDT. Через минуту статус станет paid, придёт вебхук.

Перед боевым запуском

  1. Холодные кошельки свежие, ключи офлайн. В файл настроек только публичные адреса.
  2. Ключ TronGrid и BSC RPC, который отдаёт eth_getLogs на 1000 блоков.
  3. Вторые провайдеры: TRON_VERIFY_URL и BSC_VERIFY_RPC_URL, другой компании, чем основные. В журнале при старте нет WARNING.
  4. Пробный платёж 1 USDT в каждой сети: счёт, оплата, paid, вебхук, оценка, слив.
  5. Офлайн-копия DEPOSIT_KEY_SECRET. backup.sh по cron каждый час с другой машины, от пользователя beast-kluk-backup, первая копия уже у вас.
  6. Юридическая сторона. Приём криптовалюты в оплату ограничен в ряде стран. Например, резидентам РФ это запрещает ст. 14 закона 259-ФЗ. Спросите местного юриста.

Пересборка транзакций TRON сверялась только с собственным кодировщиком. Если TronGrid закодирует поле иначе, слив откажется подписывать. Это безопасно, но потребует правки. Поэтому пробный слив на малой сумме обязателен.