systemd и проверки работоспособности

curl -fsS http://127.0.0.1:8780/healthz   # 200 + версия
curl -fsS http://127.0.0.1:8780/readyz    # 200 готов, 503 если Postgres недоступен

deploy/host/smoke.sh

# 1. Служба: запущена ли?
systemctl status aihummer-gateway
# 2. Порт: слушает ли шлюз?
ss -ltn | grep 8780
# 3. Работоспособность: отвечает ли процесс?
curl -fsS http://127.0.0.1:8780/healthz
# 4. База: готов ли шлюз обслуживать запросы?
curl -fsS http://127.0.0.1:8780/readyz
# 5. Журнал: что говорит сама служба?
journalctl -u aihummer-gateway -n 100

aihummer up         # установить / поднять службы
aihummer restart    # перезапустить gateway
aihummer stop       # остановить службы
aihummer status     # показать статус служб
aihummer logs --no-follow   # последние строки журнала и выход (без флага — следить; опционально: aihummer logs <юнит>)
aihummer doctor     # запустить диагностику

AiHummer устанавливается напрямую в Linux под systemd, без Docker: разворачивается как релизный tarball под управлением **systemd**, а не в контейнерах. Эта страница описывает, где он лежит на диске, как проверять его состояние и что закрыть перед запуском в промышленную эксплуатацию. ## Корень установки и юниты systemd Всё лежит в едином корне установки — **`~/.aihummer`** (`~` — домашний каталог пользователя, от имени которого выполнена установка), разложенном по `bin/ etc/ share/ sidecars/ plugins/ systemd/ state/ data/ logs/`. Файл конфигурации gateway — `~/.aihummer/etc/gateway.env`. Файлы юнитов systemd хранятся в корне установки и **симлинкуются в `/etc/systemd/system/`**, поэтому шлюз и каждый дополнительный сервис — обычные службы, которые можно запускать, останавливать и осматривать через `systemctl` и `journalctl`. Каждый дополнительный сервис работает под своим юнитом — см. [Дополнительные сервисы](/v1.0/architecture/sidecars). ## Пробы работоспособности и готовности Шлюз предоставляет две разные пробы: | Проба | Endpoint | Что означает | |---|---|---| | Работоспособность (liveness) | `GET /healthz` | Процесс работает; возвращает версию | | Готовность (readiness) | `GET /readyz` | Проверяет PostgreSQL; возвращает **503**, если БД недоступна | Используйте `/healthz` для «процесс поднят», а `/readyz` — для «может ли он реально обслужить запрос». За обратным прокси или балансировщиком направляйте проверку готовности на `/readyz`, чтобы шлюз без базы выводился из ротации. ```bash curl -fsS http://127.0.0.1:8780/healthz # 200 + версия curl -fsS http://127.0.0.1:8780/readyz # 200 готов, 503 если Postgres недоступен ``` > [!NOTE] > PostgreSQL — единственная жёсткая зависимость. Без доступной базы шлюз > работает в деградированном режиме «только проверка работоспособности», а > `/readyz` отдаёт 503. ## Smoke-тест После установки или обновления запустите встроенный smoke-тест, чтобы убедиться, что развёртывание отвечает корректно от начала до конца: ```bash deploy/host/smoke.sh ``` **Ожидаемый результат:** скрипт завершается без ошибок и сообщает, что базовые поверхности отвечают. ## Порядок диагностики Если что-то не работает, проверяйте в этом порядке — от службы к журналу: ```bash # 1. Служба: запущена ли? systemctl status aihummer-gateway # 2. Порт: слушает ли шлюз? ss -ltn | grep 8780 # 3. Работоспособность: отвечает ли процесс? curl -fsS http://127.0.0.1:8780/healthz # 4. База: готов ли шлюз обслуживать запросы? curl -fsS http://127.0.0.1:8780/readyz # 5. Журнал: что говорит сама служба? journalctl -u aihummer-gateway -n 100 ``` ## Управление службами через CLI CLI `aihummer` — основной инструмент для повседневной эксплуатации: он управляет шлюзом и дополнительными сервисами, избавляя от ручного `systemctl`: ```bash aihummer up # установить / поднять службы aihummer restart # перезапустить gateway aihummer stop # остановить службы aihummer status # показать статус служб aihummer logs --no-follow # последние строки журнала и выход (без флага — следить; опционально: aihummer logs <юнит>) aihummer doctor # запустить диагностику ``` Полный набор команд, включая `backup`, `restore`, `update` и `uninstall`, см. в [справочнике CLI](/v1.0/reference/cli). ## Предстартовый чек-лист для промышленной эксплуатации Перед тем как открыть AiHummer для реального трафика, пройдите этот список: - **Задайте мастер-ключ.** Укажите `AIHUMMER_MASTER_KEY` (base64, 32 байта), чтобы хранилище секретов и BYOK были зашифрованы при хранении. - **Настройте корпоративную аутентификацию.** Подключите OIDC, LDAP и/или SAML, чтобы `/v1/admin/*` был защищён. Без эмитента аутентификации админ-поверхность доверяет dev-заголовкам. - **Задайте входящий секрет.** Укажите `AIHUMMER_INBOUND_SECRET`, чтобы коннекторы аутентифицировались на `/v1/inbound/*`. - **Закройте рискованные инструменты.** Ограничьте или отключите `code_exec`, ужесточите исходящие подключения и привяжите `db_query` к read-only DSN. - **Терминируйте TLS на обратном прокси.** Запускайте шлюз за прокси, обрабатывающим HTTPS; сам шлюз отдаёт обычный HTTP. > [!WARNING] > **Что произойдёт:** админ-API начнёт доверять dev-заголовкам, то есть любому, > кто до него дотянется. **При каком условии:** если эмитент OIDC/LDAP/SAML не > настроен, а инстанс открыт в недоверенную сеть. **Как исправить:** настройте > корпоративную аутентификацию до открытия доступа извне. ## Куда дальше - Транспортная модель для речи и инструментальных сервисов: [Дополнительные сервисы](/v1.0/architecture/sidecars). - Резервные копии, мастер-ключ и аварийное восстановление: [Резервные копии и аварийное восстановление](/v1.0/operations/backups-dr). - Метрики, трейсы и за чем следить: [Наблюдаемость](/v1.0/operations/observability).