Установка — AiHummer Документация

[!NOTE] Результат: после выполнения этой инструкции на вашем сервере будет работать служба aihummer-gateway под systemd, /healthz и /readyz ответят 200, а стартовый пароль администратора будет ждать вас в /home/.aihummer/etc/initial-admin-password.txt (при rootless-установке — ~/.aihummer/etc/initial-admin-password.txt). Одна команда устанавливает AiHummer; после неё настройте внешний адрес, TLS, модель, резервное копирование и первый канал.

AiHummer устанавливается напрямую в Linux под systemd, без Docker. Установка начинается в личном кабинете my.aihummer.ru: вы регистрируетесь, получаете персональную ссылку установки и запускаете одну команду на своём сервере. Скрипт установки скачивает подписанный пакет под нужную архитектуру, раскладывает единый корень установки в ~/.aihummer (~ — домашний каталог пользователя, от имени которого выполнена установка), регистрирует systemd-юниты и при необходимости разворачивает дополнительные сервисы (sidecar). Контейнеров в этом процессе нет нигде.

[!NOTE] Это установка без контейнеров — релизный tarball под управлением systemd, а не Docker. Шлюз, дополнительные сервисы и плагины работают каждый как своя служба systemd.

[!NOTE] Что понадобится перед началом:

сервер с Linux (x86_64 или arm64) и доступ к нему по SSH;

права sudo (или готовность ставить в rootless-режиме — см. ниже);

PostgreSQL с расширением pgcrypto — или разрешите установщику развернуть пользовательский кластер (в rootless-режиме он делает это сам);

учётная запись на my.aihummer.ru, чтобы получить персональную ссылку установки.

Полный список требований — на странице Требования.

Шаг 1: получите персональную ссылку установки

Публичного скрипта установки больше нет — установочная ссылка персональная и выдаётся в личном кабинете:

Зарегистрируйтесь на my.aihummer.ru (номер телефона
- пароль; почта тоже понадобится).
Откройте экран «Установка» и нажмите «Получить персональную ссылку установки».
Кабинет покажет готовую команду с вашей персональной ссылкой.

Подробнее о самом кабинете (реквизиты, документы, тарифы) — на странице Личный кабинет.

Шаг 2: установка одной командой

Скопируйте команду с экрана «Установка» и запустите её на сервере (Linux x86_64/arm64):

curl -fsSL -o install.sh "<личная ссылка установки>" && sudo bash install.sh

Ожидаемый результат: установщик печатает журнал шагов и завершается сообщением об успешном запуске. После этого:

служба активна — systemctl status aihummer-gateway показывает active (running);
веб‑интерфейс администратора доступен на http://localhost:8781/;
одноразовый пароль администратора лежит в /home/.aihummer/etc/initial-admin-password.txt (при rootless-установке — ~/.aihummer/etc/initial-admin-password.txt);
состояние можно проверить командой aihummer status.

Персональная ссылка имеет вид https://my.aihummer.ru/dl/<токен>/install.sh и привязана к вашему аккаунту.

[!IMPORTANT] Ссылка одноразовая: она срабатывает ровно на одну установку. Как только установщик скачал по ней install.sh, ссылка считается использованной. Повторный запуск той же команды вернёт ошибку «ссылка уже использована» — это не сбой, а защита. Что делать: откройте экран «Установка» в личном кабинете и получите новую ссылку, это бесплатно и мгновенно.

Срок 30 дней относится не к повторной установке, а к скачиванию артефактов: уже установленный инстанс продолжает обновляться через свою ссылку и после того, как она израсходована на установку.

Скрипт определит архитектуру CPU, скачает подходящий пакет вместе с его контрольной суммой .sha256 и cosign-подписью .sig, проверит обе, распакует корень установки и зарегистрирует службу gateway. Актуальный релиз — в журнале изменений.

Персональная ссылка также привязывает инстанс к вашему личному кабинету: установщик сохраняет токен из ссылки, инстанс передаёт его при первой регистрации у вендора, и кабинет автоматически связывает инстанс с вашей учётной записью, а адрес вашей электронной почты сразу становится подтверждённым контактом инстанса — привязывать и подтверждать почту в веб‑интерфейсе отдельно не нужно, и лицензия доставляется без ручных шагов.

[!WARNING] Что произойдёт: любой, у кого есть ваша персональная ссылка, сможет скачивать сборки от вашего имени. При каком условии: если вы опубликуете ссылку или передадите её третьим лицам, пока не истёк срок действия токена. Как исправить: не публикуйте ссылку; если она утекла — получите новую на экране «Установка», старый токен перестанет действовать по истечении срока.

Раскладка корня установки

Всё лежит под одним каталогом. Где именно — зависит от того, как вы запустили установщик:

Как установлено	Корень установки	Конфигурация	От кого работает служба
Обычная установка (через `sudo`)	`/home/.aihummer`	`/etc/aihummer/gateway.env`	Отдельная служебная учётная запись `aihummer`
Без root (rootless)	`~/.aihummer`	`~/.aihummer/etc/gateway.env`	Ваш пользователь

Обычная установка не кладёт файлы в ваш домашний каталог и не запускает службу от вашего имени: для неё заводится выделенный непривилегированный пользователь aihummer. Это сделано намеренно — компрометация службы не даёт доступа к вашим личным файлам.

Раскладка внутри корня одинакова в обоих режимах (ниже показан обычный):

/home/.aihummer/
├── bin/        бинарный файл gateway и CLI aihummer
├── etc/        конфигурация (gateway.env)
├── share/      статические файлы административного интерфейса
├── sidecars/   опциональные сервисы STT/TTS/и т.д.
├── plugins/    установленные плагины маркетплейса
├── systemd/    юнит-файлы (симлинки в /etc/systemd/system)
├── state/      рабочее состояние
├── data/       хранилище медиафайлов
└── logs/       журналы служб

Юнит-файлы systemd, сгенерированные в systemd/, симлинкуются в /etc/systemd/system/, поэтому управляются обычными командами systemctl.

Установка без root (rootless)

Права sudo/root не обязательны. Если запустить установочную команду без sudo, установщик переключается в rootless-режим: юниты регистрируются в пользовательском scope systemd --user (файлы в ~/.config/systemd/user), CLI aihummer и cosign ложатся в ~/.aihummer/bin, а если не задан AIHUMMER_DATABASE_URL, установщик разворачивает пользовательский (user-mode) кластер PostgreSQL внутри корня установки. Службами управляют командами systemctl --user .... Чтобы службы стартовали при загрузке хоста (а не только при входе пользователя), включите lingering:

loginctl enable-linger $USER

Ожидаемый результат: loginctl show-user $USER | grep Linger выводит Linger=yes, и службы поднимаются после перезагрузки без входа пользователя.

Выбор дополнительных сервисов

Лёгкие медиа-сервисы — STT (faster-whisper), TTS (edge-tts) и video — ставятся из коробки, без вопросов и флагов: голос «туда-обратно» работает сразу. Учтите: faster-whisper распознаёт речь локально, а edge-tts обращается к онлайн‑сервису Microsoft Edge — текст для синтеза покидает ваш контур. Отключить любой из них можно переменными окружения AIHUMMER_SKIP_STT=1, AIHUMMER_SKIP_TTS=1, AIHUMMER_SKIP_VIDEO=1.

Веб-поиск (SearXNG) и браузер (CloakBrowser) вшиты в подписанный бандл и ставятся офлайн по умолчанию — установщик о них больше не спрашивает. Изменить это поведение можно флагами — это полный список:

Флаг	Эффект
`--no-search` / `--no-browser`	Пропустить этот сервис
`--external-search=URL` / `--external-browser=URL`	Использовать существующий сервис по этому URL вместо установки
`--browser-engine=cloak\|chrome`	Движок браузера (по умолчанию `cloak`)
`--with-search` / `--with-browser`	Избыточны с v1.0.14: это и есть поведение по умолчанию
`--with-embedder`	Установить семантический эмбеддер (opt-in: тянет PyTorch — сотни МБ)

Поиск и браузер ставятся и без tty: полезная нагрузка берётся из бандла, доступ в интернет для этого не нужен. Установка обоих не блокирующая — если полезной нагрузки нет или версия Python не поддерживается, сервис просто остаётся ненастроенным, а установка продолжается. Эмбеддер также включается переменной AIHUMMER_WITH_EMBEDDER=1; без него память работает на резервном лексическом поиске. Язык интерфейса задаёт AIHUMMER_LANG=ru|en (иначе установщик спросит на tty). Подключение PostgreSQL запрашивается на tty; для неинтерактивной установки заранее задайте AIHUMMER_DATABASE_URL. На tty установщик также предлагает восстановление из резервной копии.

# Установить gateway с эмбеддером, без браузера (поиск ставится по умолчанию)
curl -fsSL -o install.sh "<личная ссылка установки>" && sudo bash install.sh \
  --with-embedder --no-browser

Поскольку к дополнительным сервисам обращаются по URL, можно свободно смешивать нативные и внешние и направлять несколько шлюзов на один общий сервис.

Как проверяется подлинность сборки

Персональная ссылка из личного кабинета всегда устанавливает текущий выпуск — это штатный и единственный путь. Выбирать «версию посвежее» не нужно: вы получаете ту сборку, которую вендор выпустил для эксплуатации.

Каждый артефакт — и при первой установке, и при каждом обновлении — приезжает tarball’ом под вашу архитектуру, а рядом с ним лежат контрольная сумма .sha256 и подпись .sig (cosign). Установщик проверяет обе до того, как что-либо распакует. Вручную проверять ничего не нужно.

Ожидаемый результат: проверки проходят молча и установка продолжается. Если хотя бы одна не сошлась, установщик останавливается с ошибкой и не трогает уже работающую версию — повреждённый или подменённый файл на сервер не попадёт.

Если вендор пригласил вас в программу раннего тестирования, на экране «Установка» в личном кабинете появится переключатель, и для выбранного варианта выпускается отдельная ссылка — см. Инстанс.

Проверка установки

После завершения установщика проверьте службу и endpoint готовности:

systemctl status aihummer-gateway
curl -fsS http://localhost:8780/healthz
curl -fsS http://localhost:8780/readyz

Ожидаемый результат: служба aihummer-gateway в статусе active (running), ответ 200 на /healthz и /readyz, а в /home/.aihummer/etc/initial-admin-password.txt (при rootless-установке — ~/.aihummer/etc/initial-admin-password.txt) — стартовый пароль администратора для первого входа.

/healthz сообщает о работоспособности и версии; /readyz проверяет PostgreSQL и возвращает 503, пока база недоступна. Встроенный CLI aihummer также предоставляет aihummer status и aihummer doctor для быстрой проверки работоспособности.

Чек‑лист перед промышленной эксплуатацией

Одна команда установки поднимает шлюз, но он ещё не готов к промышленной эксплуатации. Прежде чем открывать его наружу, выполните:

TLS — терминируйте HTTPS перед шлюзом (обратный прокси / собственный сертификат); не выставляйте обычный порт в недоверенную сеть.
🔴 Включите поддержку веб‑сокетов на обратном прокси. Мобильное и настольное приложение соединяется со шлюзом по wss://, поэтому прокси обязан пропускать заголовки Upgrade и Connection. Прокси без этой настройки отвечает обычной страницей со статусом 200 вместо 101 Switching Protocols — приложение читает это как «сервис не отвечает», хотя шлюз исправен и в его журнале нет ни одной ошибки. В Nginx Proxy Manager это переключатель Websockets Support у соответствующего Proxy Host, в обычном nginx — proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; плюс proxy_http_version 1.1 в блоке location.

Проверить одной командой (ожидается 101, а не 200):
```
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  https://ваш-домен/
```
Смените пароль администратора и удалите initial-admin-password.txt; задайте issuer аутентификации (AIHUMMER_OIDC_ISSUER / LDAP / SAML), прежде чем открывать /admin/*.
Сохраните мастер‑ключ и БД — запишите AIHUMMER_MASTER_KEY (без него секреты невосстановимы) и настройте регулярные резервные копии PostgreSQL.
Подключите реальную модель — задайте AIHUMMER_LLM_* (или BYOK); без неё ответы приходят из детерминированного мока.
Подключите хотя бы один канал (для начала Telegram) и привяжите к нему агента.

Подробности — в Первом входе, Конфигурации и Резервном копировании и DR.

Если не получилось

«ссылка уже использована» / установка не запускается повторно — ссылка одноразовая и уже потрачена на предыдущую попытку. Получите новую на экране «Установка» в кабинете и запустите команду снова.
curl: (22) … 404 или «ссылка недействительна» — ссылка скопирована не полностью либо её срок истёк. Лечится там же — новой ссылкой.
«unsupported architecture» — установка поддерживает Linux x86_64 и arm64; на других платформах пакета нет.
/readyz возвращает 503 — шлюз не видит PostgreSQL. Проверьте AIHUMMER_DATABASE_URL, доступность базы и что в ней создано расширение pgcrypto (CREATE EXTENSION IF NOT EXISTS pgcrypto;).
Служба не стартовала — посмотрите systemctl status aihummer-gateway и журнал journalctl -u aihummer-gateway; для быстрой диагностики запустите aihummer doctor.
Ставил без sudo, службы гаснут после выхода — включите lingering: loginctl enable-linger $USER (см. rootless).
Проверка подписи не прошла — не запускайте установку; повторите позже или получите свежую ссылку. Артефакт всегда проверяется по .sha256 и cosign-.sig.

Куда дальше

Первый вход — получите стартовый пароль администратора и сразу защитите вход.
Конфигурация — настройте внешний адрес, модель и рабочие параметры развёртывания.