Типовые инциденты, DLQ retry, наблюдаемость, регламентные операции.

Ранбук — эксплуатация wallet-scoring

Операционная памятка для on-call.

Быстрая карта

Что	Где
Сервис приложения	`systemctl status wallet-scoring` (PocketBase, 127.0.0.1:8090)
Сервис БД	`systemctl status surrealdb` (127.0.0.1:27182, только loopback)
State	`data/pb` (SQLite tenancy), `data/surreal` (программы, кредиты, DLQ, аудит)
Очередь задач	`WF_JOBS_DIR=/srv/wallet-scoring/jobs` (файловая, переживает рестарт)
Env	`/srv/wallet-scoring/env` (chmod 600)
Секреты сценариев	`/srv/wallet-scoring/scenarios/*/.env` (TRONGRID_API_KEY)
Admin UI	`https://<host>/_/` (доступ по allowlist IP в Caddyfile)
Health	`GET /api/health` (app), `GET http://127.0.0.1:27182/health` (SurrealDB)

Логи и наблюдаемость

journalctl -u wallet-scoring -f                 # приложение
journalctl -u surrealdb -f                      # БД
journalctl -u wallet-scoring --since "1h ago" -p err
journalctl -u wallet-scoring -g 'dlq|score' -i  # grep по паттерну

Health: curl -fsS http://127.0.0.1:8090/api/health → {"code":200,...}; внешний uptime-check с алертом при != 200.
Метрики: GET /admin/api/metrics (superuser Bearer) — счётчики скоринга/очереди/DLQ.
Минимальные алерты: health app != 200 (5 мин), health surrealdb != 200, диск > 80%, рост DLQ > 0 в течение часа.

Типовые инциденты

Переполнение диска

Симптомы: health 500, SQLite database or disk is full, SurrealDB write errors.

df -h /srv/wallet-scoring; du -sh /srv/wallet-scoring/*
Быстро освободить: старые бэкапы, journalctl --vacuum-size=500M, старые бинари.
PocketBase backups — удалить старые из admin UI (/_/ → Settings → Backups).
Стратегически: увеличить диск; рассмотреть архивацию аудита в SurrealDB.
systemctl restart surrealdb wallet-scoring, проверить health обоих.

Рост DLQ (задачи, исчерпавшие ретраи)

Диагностика: journalctl -u wallet-scoring -g 'dlq' -i --since today — типичные причины: недоступен TronGrid (сеть/ключ), невалидный payload, деградация SurrealDB.
Если причина внешняя — сначала устранить её, потом retry.
Retry DLQ — через админку: admin UI /_/ / Admin API (superuser Bearer).
После retry проконтролировать метрику DLQ → 0 и credits_spent у задач.

У тенанта кончились кредиты

Симптом: POST /api/v1/score возвращает INSUFFICIENT_CREDITS с корректным ключом.

curl -X POST https://<host>/admin/api/credits/topup \
  -H "Authorization: Bearer <superuser-token>" \
  -H "Content-Type: application/json" \
  -d '{"tenant":"<ns>","amount":1000}'

Расход виден в credit ledger (SurrealDB) и в метриках.

Wallet-scoring не стартует

journalctl -u wallet-scoring -n 200 --no-pager — типичное: занят порт 8090, недоступен SurrealDB, битый env-файл.
Порядок запуска важен: сначала surrealdb, потом wallet-scoring (After= в unit-файле).
Данные повреждены — восстановление из бэкапа; очередь jobs/ переживает рестарт, после восстановления проверить DLQ.

Все скоринги падают / таймаутят, но сервис жив

Исходящий доступ к внешним API: curl -sS -o /dev/null -w '%{http_code}n' https://api.trongrid.io/
TRONGRID_API_KEY в scenarios/default/.env — после правки пересобрать и перезагрузить дистрибутив программы.
Активная программа тенанта существует: GET /api/admin/programs?ns=<ns>.

Регламентные операции

Операция	Периодичность	Как
Бэкап state (data + jobs)	nightly	cron → `backup/backup.sh`
Проверка восстановления	ежемесячно	staging
Ротация бэкапов	автоматически	`find -mtime +14 -delete`
Обновление бинаря	по релизам	symlink-flip + restart (Обновление)
Загрузка новой версии программы	по релизам сценариев	без даунтайма
Ревизия allowlist IP для `/_/`	ежеквартально	`deploy/Caddyfile`

Ретраи и рескоры идемпотентны: снапшот входных данных (хеши транзакций, диапазон блоков) + версия модели гарантируют воспроизводимость. Backfill исторических прогонов выполняется повторной постановкой задач через ту же очередь с теми же ключами идемпотентности — дублей списаний и результатов не возникает. Массовый backfill проводить в часы низкой нагрузки и контролировать глубину очереди и DLQ через /admin/api/metrics.

Ранбук (on-call)