Запуск и обслуживание

Инструкции для того, кто держит службу brokapi постоянно: как запустить ее вместе с системой, что она делает при сбоях, как остановить гейтвей и снять заявки, какие файлы где лежат и что делать, когда что-то не запускается. Первый запуск по шагам: Быстрый старт.

Постоянный запуск (systemd)

brokapi up без -d работает на переднем плане и печатает, что запустилась: это ровно то, что нужно менеджеру служб. Когда systemd посылает SIGTERM, служба останавливает гейтвеи (каждому дается stop_timeout, по умолчанию 10 секунд) и выходит. Образец юнита /etc/systemd/system/brokapi.service:

[Unit]
Description=brokapi service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=brokapi
ExecStart=/usr/local/bin/brokapi -c /etc/brokapi/brokapi.toml up
EnvironmentFile=/etc/brokapi/tokens.env
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Три замечания к образцу:

• Токены лежат в /etc/brokapi/tokens.env строками TBANK_TOKEN=... с правами 600 и владельцем из User=. В конфиге на них ссылается token_env. Либо token_file на файл с теми же правами.
• -c с полным путем. У юнита нет рабочего каталога с brokapi.toml, а относительный state_dir считается от каталога конфига, так что -c достаточно.
• Пользователь без прав входа. Служба хранит в каталоге состояния ключи доступа ботов. Этот каталог должен принадлежать тому же пользователю и никому больше.

Это образец, а не команда установки: подстройте пути и пользователя под себя. Установки службы одной командой пока нет, ни для systemd, ни для launchd на macOS и службы Windows. На macOS и Windows службу можно запустить в фоне командой brokapi up -d, после перезагрузки машины ее придется запустить заново.

Несколько служб на одной машине

Каждый конфиг - своя служба: свой каталог состояния, свой сокет, свои гейтвеи. brokapi -c prod.toml up -d и brokapi -c test.toml up -d не мешают друг другу, а brokapi services показывает обе:

$ brokapi services
PID   GATEWAYS      UPTIME  CONFIG                      STATE DIRECTORY
4121  2/2 running   3h02m   /home/me/bots/prod.toml     /home/me/bots/prod.state
4377  1/1 running   12m07s  /home/me/bots/test.toml     /home/me/bots/test.state

Две службы на один каталог состояния не пустит ни одна: вторая откажется запускаться и назовет pid и конфиг первой. Так сделано, чтобы два процесса не делили журнал заявок и сокеты. Если конфиги лежат рядом, у них разные имена файлов и значит разные каталоги по умолчанию (prod.state, test.state).

Что происходит при сбоях

Остановить гейтвей и снять заявки

Заявка на бирже живет дольше, чем процесс, который ее поставил. Поэтому остановка гейтвея заявок не снимает: ни stop, ни down, ни перезагрузка. Снять их можно двумя способами.

Остановка без снятия: brokapi stop <гейтвей> останавливает один гейтвей и держит его остановленным до brokapi start. brokapi down останавливает службу и все гейтвеи, brokapi down --leave-gateways - только службу, гейтвеи остаются работать (следующий up подхватит их).

На Linux и macOS гейтвею посылается SIGTERM, и если он не вышел за stop_timeout, его завершают принудительно. На Windows у процесса без окна нет просьбы остановиться, поэтому он завершается сразу, и в его журнале не будет строки stopped. Журнал и сверка при старте рассчитаны на внезапный конец, заявки это не теряет.

Менять конфиг, не останавливая службу

Правьте brokapi.toml и применяйте:

• brokapi reload - привести работающие гейтвеи в соответствие с файлом: новые запустить, убранные остановить, измененные перезапустить, остальные не трогать.
• brokapi add <гейтвей> - запустить один гейтвей из файла. brokapi remove <гейтвей> - остановить и забыть его в памяти службы.

remove не правит файл. Пока гейтвей остается в файле, reload вернет его. Чтобы убрать насовсем, удалите раздел из brokapi.toml. Изменения state_dir, раздела [service] и listen без перезапуска службы не применяются.

Какие файлы где лежат

brokapi.state/                  каталог состояния службы (state_dir)
  service.key                   ключ доступа к службе, права 600
  service.addr                  где служба слушает
  service.sock                  сокет службы (Linux, macOS)
  service.pid                   pid службы
  logs/service.log              журнал службы
  logs/<гейтвей>.log            журнал гейтвея
  gateways/<гейтвей>/           один гейтвей
    journal.jsonl               журнал заявок
    access.key                  ключ доступа ботов, права 600
    gateway.addr                где слушает гейтвей
    gateway.sock                сокет гейтвея (Linux, macOS)
    gateway.pid                 pid гейтвея

Путь до сокета Unix не может быть длиннее 107 байт на Linux и 103 на macOS. Каталог состояния в ~/Library/Application Support/... с длинным именем гейтвея легко получает путь длиннее. Тогда программа не отказывается стартовать: сокет кладется в личный каталог $XDG_RUNTIME_DIR/brokapi-<uid> или /tmp/brokapi-<uid> (права 700, только ваш пользователь, чужой или подмененный каталог не берется), а настоящий адрес записывается в service.addr и gateway.addr. Команды и боты читают адрес из этих файлов, так что ничего настраивать не нужно. Сокет убирается, когда гейтвей или служба останавливаются. Если даже так не получилось, ошибка называет причину и предлагает короче state_dir или свой короткий путь в listen. Если вы сами задали в listen слишком длинный путь, это тоже ошибка с пояснением: за вас его не меняют.

Журналы ротируются по размеру ([service.logs]): max_size_mb и keep. Каталог состояния не кладите в репозиторий и в общую копию: в нем ключи доступа к службе и гейтвеям. Токены брокеров там не лежат, они только в переменной окружения или в token_file.

Реестр служб машины (его читает brokapi services) хранится отдельно: в ~/.local/state/brokapi/services на Linux, на macOS и Windows в каталоге локальных данных пользователя.

Если что-то пошло не так