Быстрый старт
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/. |
-addr | 127.0.0.1:8829 | API клиента и страница оплаты. Наружу только через nginx. |
-admin-addr | 127.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, придёт вебхук.
Перед боевым запуском
- Холодные кошельки свежие, ключи офлайн. В файл настроек только публичные адреса.
- Ключ TronGrid и BSC RPC, который отдаёт
eth_getLogsна 1000 блоков. - Вторые провайдеры:
TRON_VERIFY_URLиBSC_VERIFY_RPC_URL, другой компании, чем основные. В журнале при старте нетWARNING. - Пробный платёж 1 USDT в каждой сети: счёт, оплата,
paid, вебхук, оценка, слив. - Офлайн-копия
DEPOSIT_KEY_SECRET.backup.shпо cron каждый час с другой машины, от пользователяbeast-kluk-backup, первая копия уже у вас. - Юридическая сторона. Приём криптовалюты в оплату ограничен в ряде стран. Например, резидентам РФ это запрещает ст. 14 закона 259-ФЗ. Спросите местного юриста.
Пересборка транзакций TRON сверялась только с собственным кодировщиком. Если TronGrid закодирует поле иначе, слив откажется подписывать. Это безопасно, но потребует правки. Поэтому пробный слив на малой сумме обязателен.